@farm.js/core 0.1.61 → 0.1.63

package/dist/chunk-ZQ5BDNKW.mjs

@@ -0,0 +1,954 @@
+import {
+  getFarmSourceRoots
+} from "./chunk-52Y3C3HG.mjs";
+import {
+  PROGRAMMATIC_ROUTE_FILE_NAMES,
+  getProgrammaticRouteDefinitionSource,
+  parseProgrammaticRouteModuleId
+} from "./chunk-6YFC3ZFX.mjs";
+
+// src/environment-vite.ts
+import { realpathSync } from "fs";
+import path from "path";
+
+// src/programmatic-routes-client.ts
+import { builtinModules } from "module";
+
+// src/browser-builtins.ts
+import { isBuiltin } from "module";
+var FARM_BROWSER_BUILTIN_PREFIX = "\0farm:browser-builtin:";
+var BROWSER_IMPLEMENTATIONS = {
+  crypto: {
+    webcrypto: "globalThis.crypto",
+    subtle: "globalThis.crypto?.subtle",
+    getRandomValues: "(array) => globalThis.crypto.getRandomValues(array)",
+    randomUUID: "() => globalThis.crypto.randomUUID()"
+  }
+};
+var BROWSER_EXTERNAL_RE = /^(?:__vite-)?browser-external(?::|$)/;
+var IDENTIFIER_RE = /^[A-Za-z_$][\w$]*$/;
+async function resolveFarmBrowserBuiltin(context, source, importer, options) {
+  const resolved = await context.resolve(source, importer, { ...options, skipSelf: true });
+  if (!resolved || !BROWSER_EXTERNAL_RE.test(resolved.id)) return resolved;
+  return FARM_BROWSER_BUILTIN_PREFIX + source.replace(/^node:/, "");
+}
+function loadFarmBrowserBuiltin(id) {
+  if (!id.startsWith(FARM_BROWSER_BUILTIN_PREFIX)) return void 0;
+  const name = id.slice(FARM_BROWSER_BUILTIN_PREFIX.length);
+  const implementations = BROWSER_IMPLEMENTATIONS[name] ?? {};
+  const exports = Object.keys(process.getBuiltinModule(`node:${name}`) ?? {}).filter(
+    (key) => key !== "default" && IDENTIFIER_RE.test(key)
+  );
+  const implemented = exports.filter((key) => key in implementations);
+  return [
+    ...exports.map((key) => `export const ${key} = ${implementations[key] ?? "undefined"};`),
+    `export default { ${implemented.join(", ")} };`
+  ].join("\n");
+}
+function farmBrowserBuiltinsOptimizerPlugin() {
+  return {
+    name: "farm:browser-builtins-optimizer",
+    resolveId(source, importer, options) {
+      return isBuiltin(source) ? resolveFarmBrowserBuiltin(this, source, importer, options) : null;
+    },
+    load(id) {
+      return loadFarmBrowserBuiltin(id) ?? null;
+    }
+  };
+}
+
+// src/programmatic-routes-client.ts
+import { fileURLToPath } from "url";
+var SERVER_PROPS_KEYS = ["params", "search", "guard", "data"];
+function programmaticClientRouteKey(routesFile, kind, routePath) {
+  return `${toPosixPath(routesFile)}\0${kind}\0${routePath}`;
+}
+function resolveProgrammaticClientRoutes(options) {
+  const routesFile = toPosixPath(options.routesFile);
+  const modules = collectGraph(options.graph, routesFile);
+  const routeSourceFiles = /* @__PURE__ */ new Set([routesFile]);
+  const exportsByValue = /* @__PURE__ */ new Map();
+  const modulesByFile = /* @__PURE__ */ new Map();
+  const definitions = options.routes.filter(isProgrammaticRouteDefinition);
+  for (const module of modules.values()) {
+    if (module.file) {
+      modulesByFile.set(module.file, [...modulesByFile.get(module.file) ?? [], module]);
+    }
+    for (const [exportName, value] of module.exports) {
+      if (!isReferenceValue(value)) continue;
+      if (!module.routeSource && holdsRouteDefinition(value, definitions)) {
+        module.routeSource = true;
+      }
+      const owners = exportsByValue.get(value) ?? [];
+      owners.push({ module, exportName });
+      exportsByValue.set(value, owners);
+    }
+  }
+  let untraced = false;
+  const definedIn = /* @__PURE__ */ new Map();
+  for (const route of definitions) {
+    const source = getProgrammaticRouteDefinitionSource(route);
+    const callers = (source?.stacks ?? []).map((stack) => findRouteCallers(stack, modulesByFile));
+    for (const caller of callers.flat()) caller.routeSource = true;
+    definedIn.set(route, callers.flat());
+    if (!source || source.raw || (callers[0] ?? []).length === 0) untraced = true;
+  }
+  for (const module of modules.values()) {
+    if (module.routeSource && module.file) routeSourceFiles.add(module.file);
+  }
+  const reaches = createReachability(modules);
+  const closure = createClosure(modules);
+  const routeCode = /* @__PURE__ */ new Map();
+  const definesRoutes = (module) => {
+    if (!routeCode.has(module)) routeCode.set(module, mayDefineRoutes(module.code));
+    return routeCode.get(module);
+  };
+  const refusal = /* @__PURE__ */ new Map();
+  const refuse = (module) => {
+    if (refusal.has(module)) return refusal.get(module);
+    let reason = null;
+    for (const reached of closure(module)) {
+      if (reached.routeSource) {
+        reason = reached === module ? `${module.file}, which defines routes` : `${module.file}, which imports ${reached.file ?? reached.id}, which defines routes`;
+        break;
+      }
+      if (untraced && !reached.external && definesRoutes(reached)) {
+        reason = `${module.file}, and a route defined as an object literal outside every export can't be traced to its module, so Farm can't tell that ${reached === module ? "it" : reached.file ?? reached.id} defines no routes (build such routes with page(), layout(), or api(), or export them)`;
+        break;
+      }
+    }
+    refusal.set(module, reason);
+    return reason;
+  };
+  const locate = (route, value, label) => {
+    if (!isReferenceValue(value)) return `its ${label} is not a component`;
+    const owners = exportsByValue.get(value) ?? [];
+    const local = owners.filter(({ module }) => module.file && !module.external);
+    const eligible = local.filter(({ module }) => !refuse(module));
+    if (eligible.length === 0) {
+      const refused = local.find(({ module }) => refuse(module));
+      if (refused) return `its ${label} is exported by ${refuse(refused.module)}`;
+      if (owners.some(({ module }) => module.external)) {
+        return `its ${label} comes from a package; re-export it from a module in your app`;
+      }
+      return `its ${label} is not exported by any module the routes file imports`;
+    }
+    let defining = eligible.filter(
+      (candidate) => !eligible.some(
+        (other) => other.module !== candidate.module && reaches(candidate.module, other.module)
+      )
+    );
+    if (defining.length === 0) defining = eligible;
+    if (new Set(defining.map(({ module }) => module)).size > 1) {
+      const importers = [...modulesByFile.get(routesFile) ?? [], ...definedIn.get(route) ?? []];
+      const imported = defining.filter(
+        (candidate) => importers.some((importer) => importsBinding(importer, candidate))
+      );
+      if (imported.length > 0) defining = imported;
+      const depth = Math.min(...defining.map(({ module }) => module.depth));
+      defining = defining.filter(({ module }) => module.depth === depth);
+      const files = [...new Set(defining.map(({ module }) => module.file))];
+      if (files.length > 1) {
+        return `its ${label} is exported by several modules (${files.join(", ")}) and Farm can't tell which one the routes file uses`;
+      }
+    }
+    const chosen = defining.sort(compareOwners)[0];
+    return { file: chosen.module.file, exportName: chosen.exportName };
+  };
+  const routes = /* @__PURE__ */ new Map();
+  for (const route of definitions) {
+    if (route.kind !== "page" && route.kind !== "layout" || typeof route.path !== "string") {
+      continue;
+    }
+    const routePath = options.normalizeRoutePath(route.path);
+    const clientRoute = {
+      kind: route.kind,
+      path: routePath,
+      routesFile
+    };
+    const problems = [];
+    const component = locate(route, route.component, "component");
+    if (typeof component === "string") problems.push(component);
+    else clientRoute.component = component;
+    if (route.kind === "page") {
+      if (route.pending) {
+        const pending = locate(route, route.pending, "pending component");
+        if (typeof pending === "string") problems.push(pending);
+        else clientRoute.pending = pending;
+      }
+      const serverProps = SERVER_PROPS_KEYS.filter((key) => Boolean(route[key]));
+      if (serverProps.length > 0) clientRoute.serverProps = serverProps;
+    }
+    if (problems.length > 0) clientRoute.problem = problems.join("; ");
+    routes.set(programmaticClientRouteKey(routesFile, route.kind, routePath), clientRoute);
+  }
+  return { routes, routeSourceFiles };
+}
+function createEvaluatedRouteGraph(server) {
+  const evaluated = server.environments?.ssr?.runner?.evaluatedModules;
+  if (!evaluated) return void 0;
+  const toGraphModule = (node) => ({
+    id: node.id,
+    file: node.file || void 0,
+    url: node.url,
+    imports: node.imports,
+    exports: node.exports,
+    external: Boolean(node.meta && "externalize" in node.meta),
+    code: node.meta && typeof node.meta.code === "string" ? node.meta.code : void 0
+  });
+  return {
+    getModuleById: (id) => {
+      const node = evaluated.getModuleById(id);
+      return node ? toGraphModule(node) : void 0;
+    },
+    getModulesByFile: (file) => [...evaluated.fileToModulesMap.get(file) ?? []].map(toGraphModule)
+  };
+}
+function mergeProgrammaticClientRoutes(entries) {
+  const routes = /* @__PURE__ */ new Map();
+  const routeSourceFiles = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    for (const [key, route] of entry.routes) routes.set(key, route);
+    for (const file of entry.routeSourceFiles) routeSourceFiles.add(file);
+  }
+  return { routes, routeSourceFiles };
+}
+function generateProgrammaticClientRouteModule(options) {
+  const label = `Programmatic ${options.kind} route "${options.routePath}" in ${options.routesFile}`;
+  if (options.kind === "api") {
+    throw new Error(
+      `[Farm.js] ${label} is server-only, but the browser bundle imports it. API routes never reach the browser; call them over HTTP instead.`
+    );
+  }
+  const route = options.route;
+  if (!route) {
+    throw new Error(
+      `[Farm.js] ${label} renders in the browser, but Farm did not find it when it evaluated the routes file on the server, so it can't tell which module holds its component.`
+    );
+  }
+  if (route.problem || !route.component) {
+    throw new Error(
+      `[Farm.js] ${label} renders in the browser, but ${route.problem ?? "its component has no module"}. The browser never loads the routes file, so move the component to its own module and import it into the routes file (for example \`import { AdminPage } from "./features/admin/page"\`).`
+    );
+  }
+  const component = importExport(route.component, "__farmComponent", options.toImportSpecifier);
+  if (route.kind === "layout") {
+    return `${component}
+export default __farmComponent;
+`;
+  }
+  const pending = route.pending ? importExport(route.pending, "__farmPending", options.toImportSpecifier) : "";
+  if (!route.pending && !route.serverProps) {
+    return `${component}
+export default __farmComponent;
+`;
+  }
+  const definition = [
+    `kind: "page"`,
+    `path: ${JSON.stringify(route.path)}`,
+    "component: __farmComponent",
+    ...route.pending ? ["pending: __farmPending"] : [],
+    // Read by createRouteModuleFromProgrammaticPage: the page renders only from props the
+    // server resolved for this document.
+    ...route.serverProps ? [`__farmServerHooks: ${JSON.stringify(route.serverProps)}`] : []
+  ];
+  return `
+import * as __farmRendererRuntime from ${JSON.stringify(options.rendererServer)};
+import { createRouteModuleFromProgrammaticPage as __farmCreatePageRouteModule } from "@farm.js/core/routes";
+${component}
+${pending}
+
+const __farmRouteModule = __farmCreatePageRouteModule(
+  { ${definition.join(", ")} },
+  {
+    createElement: __farmRendererRuntime.createElement,
+    Suspense: __farmRendererRuntime.Suspense,
+    // Optional hook: only renderers that need it export markFunctionComponent.
+    markFunctionComponent: Reflect.get(__farmRendererRuntime, "markFunctionComponent"),
+  },
+);
+
+export const __farmRouteSchemas = __farmRouteModule.__farmRouteSchemas;
+export const __farmRouteParsesProps = __farmRouteModule.__farmRouteParsesProps;
+export const __farmResolveRouteProps = __farmRouteModule.__farmResolveRouteProps;
+export default __farmRouteModule.default;
+`.trimStart();
+}
+function findClientNodeBuiltinChain(entry, getImportedIds) {
+  const parents = /* @__PURE__ */ new Map([[entry, null]]);
+  const queue = [entry];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    for (const imported of getImportedIds(id) ?? []) {
+      if (isNodeBuiltinId(imported)) {
+        const chain = [imported];
+        for (let cursor = id; cursor; cursor = parents.get(cursor) ?? null) {
+          chain.unshift(cursor);
+        }
+        return chain;
+      }
+      if (parents.has(imported) || !isApplicationModuleId(imported)) continue;
+      parents.set(imported, id);
+      queue.push(imported);
+    }
+  }
+  return null;
+}
+var NODE_BUILTINS = new Set(builtinModules);
+var MODULE_EXTENSION_RE = /\.[cm]?[jt]sx?$/;
+function isApplicationModuleId(id) {
+  if (id.startsWith("\0") || id.includes("/node_modules/") || id.includes("\\node_modules\\")) {
+    return false;
+  }
+  return MODULE_EXTENSION_RE.test(id.split("?", 1)[0]);
+}
+function isNodeBuiltinId(id) {
+  if (id.startsWith(FARM_BROWSER_BUILTIN_PREFIX)) return true;
+  const external = id.indexOf("__vite-browser-external:");
+  const bare = external === 0 || external === 1 ? id.slice(external + 24) : id;
+  return bare.startsWith("node:") || NODE_BUILTINS.has(bare);
+}
+function isProgrammaticRouteActionProxy(code) {
+  return Boolean(code?.includes("__farmRouteActionTarget: true"));
+}
+function collectGraph(graph, routesFile) {
+  const modules = /* @__PURE__ */ new Map();
+  const queue = [...graph.getModulesByFile(routesFile)].map((node) => ({ node, depth: 0 }));
+  while (queue.length > 0) {
+    const { node, depth } = queue.shift();
+    if (modules.has(node.id)) continue;
+    const file = node.file ? toModuleFile(node.file) : void 0;
+    const entry = {
+      id: node.id,
+      file,
+      url: node.url,
+      code: node.code,
+      external: node.external === true,
+      imports: [...node.imports],
+      exports: readExports(node.exports),
+      routeSource: file === routesFile,
+      order: modules.size,
+      depth
+    };
+    modules.set(node.id, entry);
+    if (entry.external) continue;
+    for (const id of entry.imports) {
+      const imported = graph.getModuleById(id);
+      if (imported && !modules.has(imported.id)) queue.push({ node: imported, depth: depth + 1 });
+    }
+  }
+  return modules;
+}
+function createReachability(modules) {
+  const cache = /* @__PURE__ */ new Map();
+  const reachable = (start) => {
+    const cached = cache.get(start.id);
+    if (cached) return cached;
+    const seen = /* @__PURE__ */ new Set();
+    const stack = [...start.imports];
+    while (stack.length > 0) {
+      const id = stack.pop();
+      if (seen.has(id)) continue;
+      seen.add(id);
+      const module = modules.get(id);
+      if (module && !module.external) stack.push(...module.imports);
+    }
+    cache.set(start.id, seen);
+    return seen;
+  };
+  return (from, to) => reachable(from).has(to.id);
+}
+function createClosure(modules) {
+  return function* closure(start) {
+    const seen = /* @__PURE__ */ new Set([start.id]);
+    const queue = [start];
+    while (queue.length > 0) {
+      const module = queue.shift();
+      yield module;
+      if (module.external) continue;
+      for (const id of module.imports) {
+        const imported = modules.get(id);
+        if (!imported || seen.has(id)) continue;
+        seen.add(id);
+        queue.push(imported);
+      }
+    }
+  };
+}
+var WALK_DEPTH = 10;
+var WALK_BUDGET = 2e4;
+function holdsRouteDefinition(value, definitions) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [{ value, depth: 0 }];
+  while (queue.length > 0 && seen.size < WALK_BUDGET) {
+    const { value: current, depth } = queue.shift();
+    if (!isReferenceValue(current) || seen.has(current)) continue;
+    seen.add(current);
+    if (isRouteManifest(current) || isDefinitionObject(current, definitions)) return true;
+    if (depth >= WALK_DEPTH || ArrayBuffer.isView(current) || current instanceof Promise) continue;
+    const next = (child) => {
+      if (isReferenceValue(child)) queue.push({ value: child, depth: depth + 1 });
+    };
+    try {
+      if (Array.isArray(current)) current.forEach(next);
+      else if (current instanceof Map) {
+        for (const [key, child] of current) {
+          next(key);
+          next(child);
+        }
+      } else if (current instanceof Set) current.forEach(next);
+      else {
+        for (const key of Object.keys(current)) {
+          const descriptor = Object.getOwnPropertyDescriptor(current, key);
+          if (descriptor && "value" in descriptor) next(descriptor.value);
+        }
+      }
+    } catch {
+    }
+  }
+  return false;
+}
+function isRouteManifest(value) {
+  return value.__farmRoutes === true && Array.isArray(value.routes);
+}
+function isDefinitionObject(value, definitions) {
+  if (!isProgrammaticRouteDefinition(value)) return false;
+  const route = value;
+  const where = route.kind === "redirect" ? route.source : route.path;
+  if (typeof where !== "string") return false;
+  const values = Object.values(route);
+  const own = (child) => typeof child === "function" || isReferenceValue(child) && Object.values(child).some((nested) => typeof nested === "function");
+  if (values.some(own)) return true;
+  return definitions.some(
+    (definition) => definition.kind === route.kind && Object.entries(definition).every(
+      ([key, child]) => !isReferenceValue(child) || route[key] === child
+    ) && definition[route.kind === "redirect" ? "source" : "path"] === where
+  );
+}
+function findRouteCallers(stack, modulesByFile) {
+  const files = stack.split("\n").slice(1).map(stackFrameFile).filter((file) => Boolean(file));
+  const own = files[0];
+  const callers = [];
+  for (const file of files) {
+    if (file === own) continue;
+    const modules = modulesByFile.get(file);
+    if (!modules) continue;
+    callers.push(...modules);
+    if (modules.some((module) => !module.external)) break;
+  }
+  return callers;
+}
+function stackFrameFile(frame) {
+  const line = frame.trim();
+  if (!line.startsWith("at ")) return void 0;
+  const location = line.endsWith(")") ? line.slice(line.lastIndexOf("(") + 1, -1) : line.slice(3).replace(/^async /, "");
+  const file = location.replace(/:\d+(?::\d+)?$/, "");
+  if (!file || file === location || file.startsWith("node:") || file.includes("<anonymous>")) {
+    return void 0;
+  }
+  return toModuleFile(file);
+}
+function importsBinding(importer, candidate) {
+  if (!importer.code || !importer.imports.includes(candidate.module.id)) return false;
+  const specifiers = new Set([candidate.module.url, candidate.module.id].filter(Boolean));
+  for (const match of importer.code.matchAll(SSR_IMPORT_RE)) {
+    if (!specifiers.has(readJsonString(match[1]))) continue;
+    if (match[2] === void 0) return true;
+    const names = readJsonArray(`[${match[2]}]`);
+    if (!names || names.includes(candidate.exportName)) return true;
+  }
+  return false;
+}
+var SSR_IMPORT_RE = /__vite_ssr_import__\(("(?:[^"\\]|\\.)*")(?:\s*,\s*\{\s*"importedNames"\s*:\s*\[([^\]]*)\])?/g;
+var ROUTE_KINDS = /* @__PURE__ */ new Set(["page", "layout", "api", "redirect"]);
+var ROUTE_FACTORIES = /* @__PURE__ */ new Set([
+  "page",
+  "layout",
+  "api",
+  "redirect",
+  "createRoute",
+  "routesBuilder",
+  "defineRoutes"
+]);
+function mayDefineRoutes(code) {
+  if (code === void 0) return true;
+  for (const match of code.matchAll(KIND_KEY_RE)) {
+    const value = code.slice(match.index + match[0].length);
+    const quote = value[0];
+    if (quote !== '"' && quote !== "'" && quote !== "`") return true;
+    const end = value.indexOf(quote, 1);
+    if (end < 0 || ROUTE_KINDS.has(value.slice(1, end))) return true;
+  }
+  if (KIND_SHORTHAND_RE.test(code) || KIND_ASSIGNMENT_RE.test(code)) return true;
+  for (const match of code.matchAll(SSR_IMPORT_RE)) {
+    if (!FARM_CORE_RE.test(readJsonString(match[1]) ?? "")) continue;
+    if (match[2] === void 0) return true;
+    const names = readJsonArray(`[${match[2]}]`);
+    if (!names || names.some((name) => ROUTE_FACTORIES.has(String(name)))) return true;
+  }
+  return false;
+}
+var KIND_KEY_RE = /(?<![\w$.])["']?kind["']?\s*:\s*/g;
+var KIND_SHORTHAND_RE = /[{,]\s*kind\s*[,}]/;
+var KIND_ASSIGNMENT_RE = /(?:\.kind|\[\s*["'`]kind["'`]\s*\])\s*=(?!=)/;
+var FARM_CORE_RE = /^@farm\.js\/core(?:\/routes)?$/;
+function readJsonString(text) {
+  try {
+    const value = JSON.parse(text);
+    return typeof value === "string" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readJsonArray(text) {
+  try {
+    const value = JSON.parse(text);
+    return Array.isArray(value) ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readExports(namespace) {
+  if (!namespace || typeof namespace !== "object" && typeof namespace !== "function") return [];
+  const entries = [];
+  let keys;
+  try {
+    keys = Object.keys(namespace);
+  } catch {
+    return [];
+  }
+  for (const key of keys) {
+    try {
+      entries.push([key, namespace[key]]);
+    } catch {
+    }
+  }
+  return entries;
+}
+function isReferenceValue(value) {
+  return typeof value === "function" || typeof value === "object" && value !== null;
+}
+function isProgrammaticRouteDefinition(value) {
+  if (!value || typeof value !== "object") return false;
+  const kind = value.kind;
+  return kind === "page" || kind === "layout" || kind === "api" || kind === "redirect";
+}
+function compareOwners(left, right) {
+  if (left.module !== right.module) return right.module.order - left.module.order;
+  if (left.exportName === "default") return -1;
+  if (right.exportName === "default") return 1;
+  return left.exportName < right.exportName ? -1 : left.exportName > right.exportName ? 1 : 0;
+}
+var IDENTIFIER_RE2 = /^[A-Za-z_$][\w$]*$/;
+function importExport(value, local, toImportSpecifier) {
+  const source = JSON.stringify(toImportSpecifier(value.file));
+  if (value.exportName === "default") return `import ${local} from ${source};`;
+  const imported = IDENTIFIER_RE2.test(value.exportName) ? value.exportName : JSON.stringify(value.exportName);
+  return `import { ${imported} as ${local} } from ${source};`;
+}
+function toPosixPath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+function toModuleFile(file) {
+  if (file.startsWith("file://")) {
+    try {
+      return toPosixPath(fileURLToPath(file));
+    } catch {
+      return toPosixPath(file);
+    }
+  }
+  return toPosixPath(file.split("?", 1)[0]);
+}
+
+// src/environment-vite.ts
+var ENVIRONMENT_IMPORTS = /* @__PURE__ */ new Set([
+  "@farm.js/core",
+  "@farm.js/core/environment",
+  "@farm.js/core/server"
+]);
+var ENVIRONMENT_FUNCTIONS = /* @__PURE__ */ new Set([
+  "createServerOnlyFn",
+  "createClientOnlyFn",
+  "createIsomorphicFn"
+]);
+var MODULE_EXTENSION_RE2 = /\.[cm]?[jt]sx?$/;
+function transformEnvironmentFunctions(options) {
+  if (!isTransformableModule(options.id) || !containsEnvironmentFunction(options.code)) {
+    return null;
+  }
+  let output = options.code;
+  let transformed = false;
+  for (let pass = 0; pass < 20; pass++) {
+    const ast = options.parse(output);
+    const bindings = findEnvironmentFunctionBindings(ast);
+    if (bindings.named.size === 0 && bindings.namespaces.size === 0) break;
+    const calls = findEnvironmentCalls(ast, bindings);
+    if (calls.length === 0) break;
+    const innermostCalls = calls.filter(
+      (call) => !calls.some(
+        (candidate) => candidate !== call && candidate.node.start > call.node.start && candidate.node.end < call.node.end
+      )
+    );
+    const replacements = innermostCalls.map(
+      (call) => createReplacement(output, options.id, options.environment, call)
+    );
+    output = applyReplacements(output, replacements);
+    transformed = true;
+  }
+  if (!transformed) return null;
+  const remainingAst = options.parse(output);
+  const remainingBindings = findEnvironmentFunctionBindings(remainingAst);
+  if (findEnvironmentCalls(remainingAst, remainingBindings).length > 0) {
+    throw transformError(options.id, "environment functions are nested too deeply");
+  }
+  return { code: output };
+}
+function farmEnvironmentFunctionsPlugin(options = {}) {
+  let routesFiles = /* @__PURE__ */ new Set();
+  let farmApi;
+  let isBuild = false;
+  let sources;
+  const routeSourceFiles = () => {
+    const clientRoutes = farmApi?.getProgrammaticClientRoutes();
+    if (sources?.for !== clientRoutes || !sources) {
+      sources = {
+        for: clientRoutes,
+        files: /* @__PURE__ */ new Set([
+          ...routesFiles,
+          ...[...clientRoutes?.routeSourceFiles ?? []].map(resolvedFile)
+        ])
+      };
+    }
+    return sources.files;
+  };
+  const routeSourceError = (file, importers = []) => `[Farm.js] ${file} defines programmatic routes, but the browser bundle imports it` + (importers.length > 0 ? ` (from ${importers.join(", ")})` : "") + ". Routes files and the modules that define routes carry server-only guards, data hooks, and API handlers, so they never reach the browser. Import the component, server function, or helper from its own module instead.";
+  return {
+    name: "farm:environment-functions",
+    enforce: "post",
+    configResolved(config) {
+      isBuild = config.command === "build";
+      farmApi = config.plugins.find((plugin) => plugin.name === "farm")?.api;
+      sources = void 0;
+      routesFiles = new Set(
+        getFarmSourceRoots({ ...options, root: options.root ?? config.root }).flatMap(
+          (source) => PROGRAMMATIC_ROUTE_FILE_NAMES.map(
+            (name) => resolvedFile(path.resolve(source.root, source.srcDir, name))
+          )
+        )
+      );
+    },
+    transform(code, id, transformOptions) {
+      const environment = resolveBuildEnvironment(
+        this,
+        transformOptions?.ssr
+      );
+      const parse = (source) => this.parse(source);
+      const result = transformEnvironmentFunctions({ code, id, environment, parse });
+      if (environment === "client" && !isBuild && !parseProgrammaticRouteModuleId(id) && routeSourceFiles().has(moduleFile(id)) && !isProgrammaticRouteActionProxy(code)) {
+        this.error(routeSourceError(moduleFile(id)));
+      }
+      return result ? { code: result.code, map: null } : null;
+    },
+    generateBundle() {
+      const context = this;
+      if (resolveBuildEnvironment(context, false) !== "client") return;
+      const forbidden = routeSourceFiles();
+      for (const id of this.getModuleIds()) {
+        if (parseProgrammaticRouteModuleId(id)) {
+          const chain = findClientNodeBuiltinChain(id, (moduleId) => {
+            return this.getModuleInfo(moduleId)?.importedIds;
+          });
+          if (chain) {
+            this.error(
+              `[Farm.js] The browser bundle reaches the server-only module "${chain.at(-1)}" through the programmatic route module ${moduleFile(id)}: ${chain.map(moduleFile).join(" -> ")}. Keep server-only imports in the routes file or in modules only its guard, data, and API handlers use.`
+            );
+          }
+          continue;
+        }
+        if (!forbidden.has(moduleFile(id))) continue;
+        const info = this.getModuleInfo(id);
+        if (isProgrammaticRouteActionProxy(info?.code)) continue;
+        this.error(routeSourceError(moduleFile(id), info?.importers.map(moduleFile)));
+      }
+    }
+  };
+}
+function moduleFile(id) {
+  return id.split("?", 1)[0].replace(/\\/g, "/");
+}
+function resolvedFile(filePath) {
+  try {
+    return moduleFile(realpathSync(filePath));
+  } catch {
+    return moduleFile(filePath);
+  }
+}
+function resolveBuildEnvironment(context, ssr) {
+  if (context.environment?.name === "client") return "client";
+  if (context.environment?.name === "rsc" || context.environment?.name === "ssr") {
+    return "server";
+  }
+  return ssr ? "server" : "client";
+}
+function findEnvironmentFunctionBindings(ast) {
+  const named = /* @__PURE__ */ new Map();
+  const namespaces = /* @__PURE__ */ new Set();
+  const body = Array.isArray(ast.body) ? ast.body : [];
+  for (const statement of body) {
+    if (!isAstNode(statement) || statement.type !== "ImportDeclaration") continue;
+    const source = isAstNode(statement.source) ? statement.source.value : void 0;
+    if (typeof source !== "string" || !ENVIRONMENT_IMPORTS.has(source)) continue;
+    const specifiers = Array.isArray(statement.specifiers) ? statement.specifiers : [];
+    for (const specifier of specifiers) {
+      if (!isAstNode(specifier) || !isAstNode(specifier.local)) continue;
+      const localName = specifier.local.name;
+      if (typeof localName !== "string") continue;
+      if (specifier.type === "ImportNamespaceSpecifier") {
+        namespaces.add(localName);
+        continue;
+      }
+      if (specifier.type !== "ImportSpecifier" || !isAstNode(specifier.imported)) continue;
+      const importedName = specifier.imported.name ?? specifier.imported.value;
+      if (isEnvironmentFunctionKind(importedName)) {
+        named.set(localName, importedName);
+      }
+    }
+  }
+  return { named, namespaces };
+}
+function findEnvironmentCalls(ast, bindings) {
+  const calls = [];
+  walkAst(ast, (node, ancestors) => {
+    if (node.type !== "CallExpression" || !isAstNode(node.callee)) return;
+    if (node.callee.type === "Identifier" && typeof node.callee.name === "string") {
+      const kind = bindings.named.get(node.callee.name);
+      if (kind && !isNameShadowed(node.callee.name, ancestors)) calls.push({ node, kind });
+      return;
+    }
+    if (node.callee.type !== "MemberExpression" || node.callee.computed === true || !isAstNode(node.callee.object) || !isAstNode(node.callee.property) || node.callee.object.type !== "Identifier" || node.callee.property.type !== "Identifier" || typeof node.callee.object.name !== "string" || typeof node.callee.property.name !== "string" || !bindings.namespaces.has(node.callee.object.name) || isNameShadowed(node.callee.object.name, ancestors) || !isEnvironmentFunctionKind(node.callee.property.name)) {
+      return;
+    }
+    calls.push({ node, kind: node.callee.property.name });
+  });
+  return calls;
+}
+function createReplacement(code, id, environment, call) {
+  const args = Array.isArray(call.node.arguments) ? call.node.arguments : [];
+  if (args.length !== 1 || !isAstNode(args[0]) || args[0].type === "SpreadElement") {
+    throw transformError(id, `${call.kind}() requires exactly one static argument`);
+  }
+  let replacement;
+  if (call.kind === "createIsomorphicFn") {
+    replacement = selectIsomorphicImplementation(code, id, environment, args[0]);
+  } else {
+    const expected = call.kind === "createServerOnlyFn" ? "server" : "client";
+    replacement = environment === expected ? readNode(code, args[0]) : `(0, ${readNode(code, call.node.callee)})(undefined, ${JSON.stringify(environment)})`;
+  }
+  return {
+    start: call.node.start,
+    end: call.node.end,
+    code: `(${replacement})`
+  };
+}
+function selectIsomorphicImplementation(code, id, environment, optionsNode) {
+  if (optionsNode.type !== "ObjectExpression") {
+    throw transformError(id, "createIsomorphicFn() requires an inline options object");
+  }
+  const properties = Array.isArray(optionsNode.properties) ? optionsNode.properties : [];
+  if (properties.some((property) => isAstNode(property) && property.type === "SpreadElement")) {
+    throw transformError(id, "createIsomorphicFn() does not support spread properties");
+  }
+  let selectedProperty;
+  for (const property of properties) {
+    if (!isAstNode(property) || property.type !== "Property" || property.computed === true) {
+      continue;
+    }
+    const key = readPropertyName(property.key);
+    if (key === environment) selectedProperty = property;
+  }
+  if (!selectedProperty || !isAstNode(selectedProperty.value)) {
+    throw transformError(id, `createIsomorphicFn() requires a ${environment} implementation`);
+  }
+  if (selectedProperty.kind !== void 0 && selectedProperty.kind !== "init") {
+    throw transformError(id, "createIsomorphicFn() does not support getters or setters");
+  }
+  return selectedProperty.method === true ? renderObjectMethod(code, id, selectedProperty.value) : readNode(code, selectedProperty.value);
+}
+function renderObjectMethod(code, id, functionNode) {
+  if (!isAstNode(functionNode.body) || !Array.isArray(functionNode.params)) {
+    throw transformError(id, "createIsomorphicFn() received an unsupported method");
+  }
+  const params = functionNode.params.map((param) => {
+    if (!isAstNode(param)) {
+      throw transformError(id, "createIsomorphicFn() received an unsupported parameter");
+    }
+    return readNode(code, param);
+  });
+  const asyncPrefix = functionNode.async === true ? "async " : "";
+  const generatorMarker = functionNode.generator === true ? "*" : "";
+  return `${asyncPrefix}function${generatorMarker}(${params.join(", ")}) ${readNode(code, functionNode.body)}`;
+}
+function applyReplacements(code, replacements) {
+  let output = code;
+  for (const replacement of replacements.sort((left, right) => right.start - left.start)) {
+    output = output.slice(0, replacement.start) + replacement.code + output.slice(replacement.end);
+  }
+  return output;
+}
+function walkAst(node, visit, ancestors = []) {
+  visit(node, ancestors);
+  const childAncestors = [...ancestors, node];
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "start" || key === "end" || key === "loc" || key === "range") continue;
+    if (isAstNode(value)) {
+      walkAst(value, visit, childAncestors);
+    } else if (Array.isArray(value)) {
+      for (const item of value) {
+        if (isAstNode(item)) walkAst(item, visit, childAncestors);
+      }
+    }
+  }
+}
+function isNameShadowed(name, ancestors) {
+  for (const [index, ancestor] of ancestors.entries()) {
+    if (isFunctionNode(ancestor)) {
+      const params = Array.isArray(ancestor.params) ? ancestor.params : [];
+      if (params.some((param) => patternContainsName(param, name))) return true;
+      if (patternContainsName(ancestor.id, name)) return true;
+      if (isAstNode(ancestor.body) && ancestors.slice(index + 1).includes(ancestor.body) && functionBodyDeclaresVarName(ancestor.body, name)) {
+        return true;
+      }
+    }
+    if (ancestor.type === "CatchClause" && patternContainsName(ancestor.param, name)) {
+      return true;
+    }
+    if ((ancestor.type === "BlockStatement" || ancestor.type === "StaticBlock") && blockDeclaresName(ancestor, name)) {
+      return true;
+    }
+    if (loopDeclaresName(ancestor, name)) return true;
+    if (ancestor.type === "SwitchStatement" && ancestors.slice(index + 1).some((candidate) => candidate.type === "SwitchCase") && switchDeclaresName(ancestor, name)) {
+      return true;
+    }
+    if (ancestor.type === "ClassExpression" && patternContainsName(ancestor.id, name) && ancestors.slice(index + 1).some((candidate) => candidate.type === "ClassBody")) {
+      return true;
+    }
+  }
+  return false;
+}
+function functionBodyDeclaresVarName(body, name) {
+  if (body.type === "VariableDeclaration" && body.kind === "var") {
+    const declarations = Array.isArray(body.declarations) ? body.declarations : [];
+    if (declarations.some(
+      (declaration) => isAstNode(declaration) && patternContainsName(declaration.id, name)
+    )) {
+      return true;
+    }
+  }
+  for (const [key, value] of Object.entries(body)) {
+    if (key === "start" || key === "end" || key === "loc" || key === "range") continue;
+    if (isAstNode(value)) {
+      if (isNestedVarScope(value)) continue;
+      if (functionBodyDeclaresVarName(value, name)) return true;
+    } else if (Array.isArray(value)) {
+      for (const item of value) {
+        if (!isAstNode(item) || isNestedVarScope(item)) continue;
+        if (functionBodyDeclaresVarName(item, name)) return true;
+      }
+    }
+  }
+  return false;
+}
+function isNestedVarScope(node) {
+  return isFunctionNode(node) || node.type === "ClassDeclaration" || node.type === "ClassExpression";
+}
+function loopDeclaresName(node, name) {
+  const declaration = node.type === "ForStatement" ? node.init : node.type === "ForInStatement" || node.type === "ForOfStatement" ? node.left : void 0;
+  if (!isAstNode(declaration) || declaration.type !== "VariableDeclaration") return false;
+  const declarations = Array.isArray(declaration.declarations) ? declaration.declarations : [];
+  return declarations.some((item) => isAstNode(item) && patternContainsName(item.id, name));
+}
+function switchDeclaresName(node, name) {
+  const cases = Array.isArray(node.cases) ? node.cases : [];
+  return cases.some((switchCase) => {
+    if (!isAstNode(switchCase) || !Array.isArray(switchCase.consequent)) return false;
+    return switchCase.consequent.some((statement) => {
+      if (!isAstNode(statement)) return false;
+      if ((statement.type === "FunctionDeclaration" || statement.type === "ClassDeclaration") && patternContainsName(statement.id, name)) {
+        return true;
+      }
+      if (statement.type !== "VariableDeclaration" || statement.kind === "var") return false;
+      const declarations = Array.isArray(statement.declarations) ? statement.declarations : [];
+      return declarations.some(
+        (declaration) => isAstNode(declaration) && patternContainsName(declaration.id, name)
+      );
+    });
+  });
+}
+function blockDeclaresName(block, name) {
+  const statements = Array.isArray(block.body) ? block.body : [];
+  for (const statement of statements) {
+    if (!isAstNode(statement)) continue;
+    if ((statement.type === "FunctionDeclaration" || statement.type === "ClassDeclaration") && patternContainsName(statement.id, name)) {
+      return true;
+    }
+    if (statement.type !== "VariableDeclaration" || !Array.isArray(statement.declarations)) {
+      continue;
+    }
+    if (statement.declarations.some(
+      (declaration) => isAstNode(declaration) && patternContainsName(declaration.id, name)
+    )) {
+      return true;
+    }
+  }
+  return false;
+}
+function patternContainsName(value, name) {
+  if (!isAstNode(value)) return false;
+  if (value.type === "Identifier") return value.name === name;
+  if (value.type === "RestElement") return patternContainsName(value.argument, name);
+  if (value.type === "AssignmentPattern") return patternContainsName(value.left, name);
+  if (value.type === "Property") return patternContainsName(value.value, name);
+  const elements = Array.isArray(value.elements) ? value.elements : Array.isArray(value.properties) ? value.properties : [];
+  return elements.some((element) => patternContainsName(element, name));
+}
+function isFunctionNode(node) {
+  return node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression";
+}
+function readPropertyName(value) {
+  if (!isAstNode(value)) return void 0;
+  if (value.type === "Identifier" && typeof value.name === "string") return value.name;
+  if (value.type === "Literal" && typeof value.value === "string") return value.value;
+  return void 0;
+}
+function readNode(code, node) {
+  return code.slice(node.start, node.end);
+}
+function isAstNode(value) {
+  return !!value && typeof value === "object" && typeof value.type === "string" && typeof value.start === "number" && typeof value.end === "number";
+}
+function isEnvironmentFunctionKind(value) {
+  return typeof value === "string" && ENVIRONMENT_FUNCTIONS.has(value);
+}
+function containsEnvironmentFunction(code) {
+  return Array.from(ENVIRONMENT_FUNCTIONS).some((name) => code.includes(name));
+}
+function isTransformableModule(id) {
+  const cleanId = id.split("?", 1)[0];
+  return MODULE_EXTENSION_RE2.test(cleanId) && !/\.d\.[cm]?ts$/.test(cleanId);
+}
+function transformError(id, message) {
+  return new Error(`[Farm environment functions] ${message} in ${id.split("?", 1)[0]}`);
+}
+
+export {
+  resolveFarmBrowserBuiltin,
+  loadFarmBrowserBuiltin,
+  farmBrowserBuiltinsOptimizerPlugin,
+  programmaticClientRouteKey,
+  resolveProgrammaticClientRoutes,
+  createEvaluatedRouteGraph,
+  mergeProgrammaticClientRoutes,
+  generateProgrammaticClientRouteModule,
+  transformEnvironmentFunctions,
+  farmEnvironmentFunctionsPlugin
+};