@zerotal/core 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -8,6 +8,96 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.6.0] — 2026-08-15
+
+### Added
+
+- **`route()` in the browser — `@zerotal/core/routes`.** The typed `route()` helper now has a
+  browser twin. Hand it the table `bun zt route:types` already generates, once, at your
+  entry point:
+
+  ```ts
+  import { defineRoutes } from "zerotal/routes";
+  import { ROUTES } from "../../types/routes.generated";
+
+  defineRoutes(ROUTES);
+  ```
+
+  and `route("posts.show", { slug })` works in a component exactly as it does in a
+  controller. The table is a build-time constant, so it costs one static import, ships
+  nothing per response, and needs no fetch before the first link renders. `hasRoute(name)`
+  answers the conditional-link question without a try/catch, and `resetRoutes()` clears the
+  table for tests.
+
+  The two helpers are one implementation, not two that agree today. Everything a caller can
+  observe — param encoding, catch-all handling, which mistakes throw and what they say —
+  moved into a shared builder; only the table lookup differs (the live router on the server,
+  the generated map in the browser). Both are typed as the same `RouteBuilder` interface, and
+  both read the same `RouteRegistry`, so a name that type-checks in a controller type-checks
+  in a component and a missing `:param` fails the build on either side. A parity test asserts
+  the two produce byte-identical URLs and identical error messages.
+
+  The entry point is browser-safe by construction: it imports nothing that touches `Bun`,
+  the container, or request state.
+
+### Fixed
+
+- **Ten more places asked `APP_ENV` a question it cannot answer.** 1.5.0 and 1.5.1 each
+  fixed the instances that had been noticed; this is the audit of every remaining reader,
+  and it found more than either. `APP_ENV` holds the runtime mode once `setAppEnv()` has
+  run, so any check comparing it against a deployment name was asking whether `"web"` is
+  production. In core and its packages that meant:
+
+  - **auto-`synchronize` was never hard-off in production**, so the only thing between a
+    production database and boot-time schema sync was the config default. The comment above
+    the guard claimed `APP_ENV` still held the deployment name, which is precisely the
+    mistake;
+  - **the Flow client bundle was never minified in production**, shipping ~183 KB
+    unminified to every visitor;
+  - **`forceState()`** did not refuse to run on live data despite the throw written for it;
+  - **environment-scoped scheduled tasks never matched**, so `.environments(["production"])`
+    silently never ran;
+  - the N+1 detector's own gate, the monitor's reported environment, the admin environment
+    badge, the large-snapshot warning, and four config-first reads whose fallback was the
+    runtime mode.
+
+  All of them read `deployEnv()` now. Everything still fails closed: production, staging and
+  an unset environment behave exactly as before.
+
+- **`useOnce()` demanded a cast from every caller.** `PipeClass` used `unknown[]` for its
+  constructor arguments, which fails parameter contravariance for any middleware class with
+  a typed constructor — so all eight packages that register middleware wrote
+  `useOnce(Middleware as never)`, twelve times over. It uses the codebase's standard
+  `any[]` constructor shape now, the same reasoning `container/types.ts` already documented
+  for container tokens, and all twelve casts are gone.
+
+### Changed
+
+- **Reading `Bun.env["APP_ENV"]` directly is now a lint error.** Fourteen instances of one
+  mistake across seven packages were each found separately; the rule is so the fifteenth is
+  found by CI. Tests are exempt — pinning the variable is how a test reproduces what a
+  server sees — and the handful of genuine runtime-mode reads carry an inline disable saying
+  which of the two meanings they want.
+
+## [1.5.1] — 2026-08-15
+
+### Fixed
+
+- **Every development-only surface switched itself off under `zt serve`.**
+  `devSurfacesEnabled()` asked `Bun.env["APP_ENV"]` whether this was a development
+  environment — but `setAppEnv()` replaces that with the runtime mode before the app is
+  created, so it was asking whether `"web"` is development. The answer is no. An app with
+  `APP_ENV=development` in its `.env` therefore got **production error pages** from a plain
+  `bun zt serve`: no stack trace, no dev overlay.
+
+  It reads `deployEnv()` now, which is where the deployment name survives. Production and
+  staging are unaffected — both still fail closed, and an unset value still fails closed.
+
+  This is the third instance of one mistake. The weak-`APP_KEY` refusal and the ORM's N+1
+  detector had exactly the same bug, both fixed in 1.5.0. Reading `APP_ENV` to decide
+  anything about the _deployment_ is wrong once the app has booted; `deployEnv()` is the
+  answer.
+
 ## [1.5.0] — 2026-08-15
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -9,6 +9,7 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./routes": "./src/router/routes.ts",
     "./contracts": "./src/contracts/index.ts",
     "./lock": "./src/lock/index.ts",
     "./logger": "./src/logger/index.ts",

package/src/application/Application.ts

@@ -157,7 +157,14 @@ type DeferrableProviderClass = ProviderClass & {
   provides: readonly (keyof ContainerBindings)[];
 };
 type Environment = "web" | "console" | "worker" | "test" | "repl";
-type PipeClass = new (...args: unknown[]) => Pipe<HttpContext>;
+// `args: any[]`, the codebase's standard constructor shape — the same reasoning
+// `container/types.ts` already writes down for `ClassToken`: `unknown[]` fails
+// constructor-parameter contravariance at the call site, so any middleware class
+// with a typed constructor is rejected. Every provider that registers one worked
+// around it the same way, `useOnce(Middleware)`, eleven times across eight
+// packages — a cast the framework was asking for rather than one anybody wanted.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- middleware classes carry their own constructor shapes
+type PipeClass = new (...args: any[]) => Pipe<HttpContext>;
 
 /** Options form for `Application.create({ ... })`. */
 export interface CreateOptions {
@@ -452,6 +459,7 @@ export class Application {
       );
     }
 
+    // eslint-disable-next-line no-restricted-syntax -- runtime mode is exactly what Application.create() wants; _normaliseEnv maps deployment names onto it
     const rawEnv = options.env ?? Bun.env["APP_ENV"] ?? "web";
     const resolvedEnv: Environment = _normaliseEnv(rawEnv);
 
@@ -861,7 +869,7 @@ export class Application {
     // Inject the live-reload client (and any registered dev snippets) into HTML
     // responses, so auto-reload works for every view layer, not just Inertia.
     setDevReloadClientActive(true);
-    this.useOnce(DevReloadMiddleware as never);
+    this.useOnce(DevReloadMiddleware);
     return this;
   }
 
@@ -1055,7 +1063,7 @@ export class Application {
     // elsewhere it warns. Skipped in the test harness to keep output clean.
     if (this._env !== "test" && this._configValidators.length > 0) {
       const configManager = this.container.makeSync("config") as ConfigManager;
-      const appEnv = configManager.get<string>("app.env", Bun.env["APP_ENV"] ?? "development");
+      const appEnv = configManager.get<string>("app.env", deployEnv() || "development");
       runConfigValidators(this._configValidators, configManager, isProdLike(appEnv));
     }
 

package/src/command/builtin/ServeCommand.ts

@@ -7,6 +7,7 @@ import type { FlagDef } from "../Command.ts";
 import { hasDevBuildHooks, runDevBuildHooks } from "../../dev/DevBuildHook.ts";
 import { buildConfiguredAssets, type AssetBuildConfig } from "../../dev/CssPlugins.ts";
 import { bootBuildDecision } from "../../dev/bootBuild.ts";
+import { deployEnv } from "../../support/env.ts";
 import { collectDevProcesses, type ResolvedDevProcess } from "../../dev/DevProcess.ts";
 import { startDevMode, SERVER_PROCESS_NAME } from "../../dev/startDevMode.ts";
 import type { ConfigManager } from "../../config/ConfigManager.ts";
@@ -456,7 +457,7 @@ export class ServeCommand extends Command {
     // down is doing the right thing; rebuilding at boot would only fail. See bootBuild.ts.
     const decision = await bootBuildDecision(
       [`${process.cwd()}/${assets.outDir}`],
-      (this._appEnv() ?? Bun.env["APP_ENV"]) as string | undefined,
+      (this._appEnv() ?? deployEnv()) as string | undefined,
     );
     if (!decision.build) {
       this.info(decision.reason ?? "Skipping the boot-time asset build.");

package/src/config/AppConfig.ts

@@ -346,6 +346,7 @@ export function AppConfig(options: {
   // overrides (e.g. `conventions.paths.models`) keep every other default in place.
   const defaults: AppConfigShape = {
     name: "Zerotal App",
+    // eslint-disable-next-line no-restricted-syntax -- config is loaded before setAppEnv() runs, so APP_ENV still holds the deployment name here
     env: Bun.env["APP_ENV"] ?? "development",
     key: Bun.env["APP_KEY"] ?? "",
     debug: Bun.env["APP_DEBUG"] !== "false",

package/src/helpers/index.ts

@@ -22,7 +22,7 @@
  */
 import { join } from "node:path";
 import { ConfigError } from "../errors/ConfigError.ts";
-import { DEPLOY_ENV_VAR } from "../support/env.ts";
+import { DEPLOY_ENV_VAR, RUNTIME_MODES as _RUNTIME_MODES } from "../support/env.ts";
 
 // ── basePath() ────────────────────────────────────────────────────────────────
 
@@ -65,11 +65,9 @@ export function basePath(...segments: string[]): string {
  * setAppEnv(process.argv[2]);
  * const { default: app } = await import('./bootstrap/app.ts');
  */
-/** Runtime-mode values that Application understands natively — never remapped. */
-const _RUNTIME_MODES = new Set(["web", "worker", "console", "test", "testing", "repl"]);
-
 export function setAppEnv(command?: string): void {
   const normalizedCommand = (command ?? "").toLowerCase();
+  // eslint-disable-next-line no-restricted-syntax -- this IS setAppEnv — reading the pre-overwrite value is the whole job
   const current = Bun.env["APP_ENV"];
   const environment = Bun.env as Record<string, string>;
 
@@ -79,10 +77,11 @@ export function setAppEnv(command?: string): void {
   // quietly answering no — including the weak-`APP_KEY` refusal and the ORM's
   // N+1 detector. `deployEnv()` reads this back; see {@link DEPLOY_ENV_VAR}.
   //
-  // `??=` so the first caller wins: a re-entrant `setAppEnv` (dev mode boots the
-  // app twice) must not stamp the runtime mode over the real deployment name.
+  // The guard is what protects a re-entrant call: `current` is only ever written
+  // when it is a genuine deployment name, so a second `setAppEnv` — which sees the
+  // runtime mode this one just wrote — cannot stamp `"web"` over `"production"`.
   if (current && !_RUNTIME_MODES.has(current.toLowerCase())) {
-    environment[DEPLOY_ENV_VAR] ??= current;
+    environment[DEPLOY_ENV_VAR] = current;
   }
 
   if (["serve", "start", "s", "dev", "d"].includes(normalizedCommand)) {

package/src/logger/config.ts

@@ -21,6 +21,7 @@ export const DEFAULT_LOG_RETENTION_DAYS = 14;
  * A test that wants the trail asks for it explicitly.
  */
 function _fileDefault(): FileSinkConfig {
+  // eslint-disable-next-line no-restricted-syntax -- asks about the test/testing runtime modes, not the deployment
   const env = (Bun.env["APP_ENV"] ?? "").trim().toLowerCase();
   if (env === "test" || env === "testing") return false;
   return { path: DEFAULT_LOG_PATH, days: DEFAULT_LOG_RETENTION_DAYS };

package/src/provider/LogProvider.ts

@@ -1,6 +1,7 @@
 import { ServiceProvider } from "./ServiceProvider.ts";
 import type { AppEnvironment } from "./ServiceProvider.ts";
 import { FrameworkEvents } from "../events/FrameworkEvents.ts";
+import { deployEnv } from "../support/env.ts";
 import type {
   // Application lifecycle
   AppBooted,
@@ -60,7 +61,7 @@ export class LogProvider extends ServiceProvider {
       const cfg = (await c.make("config")) as { get<T>(path: string): T | undefined };
       const logging = cfg.get<LoggingConfigShape>("logging") ?? _defaultConfig();
       const appName = cfg.get<string>("app.name");
-      const appEnv = cfg.get<string>("app.env") ?? Bun.env["APP_ENV"];
+      const appEnv = cfg.get<string>("app.env") ?? deployEnv();
 
       return new LogManager(logging, { app: appName, env: appEnv });
     });
@@ -75,7 +76,7 @@ export class LogProvider extends ServiceProvider {
       get<T>(path: string): T | undefined;
     };
     const requests = cfg.get<LoggingConfigShape>("logging")?.requests ?? true;
-    if (requests) this.app.useOnce(LoggerMiddleware as never);
+    if (requests) this.app.useOnce(LoggerMiddleware);
   }
 
   override async onBooted(): Promise<void> {

package/src/router/Router.ts

@@ -17,11 +17,12 @@ import type {
 } from "./Route.ts";
 import type {
   RouteArgs,
-  RouteParamValue,
+  RouteBuilder,
   RouteParamValues,
   RouteQuery,
   RouteTarget,
 } from "./registry.ts";
+import { buildRouteUrl, unknownRouteError } from "./buildRoute.ts";
 import type { HttpContext } from "../pipeline/HttpContext.ts";
 import type { ExceptionHandler } from "../application/ExceptionHandler.ts";
 import { createRouteHandler } from "./RouteHandler.ts";
@@ -279,58 +280,12 @@ export interface ViewRegistration {
   withLayout(layout: ViewLayout): ViewRegistration;
 }
 
-/** Encode one catch-all value: `'guides/intro'` and `['guides','intro']` both give `guides/intro`. */
-function _encodeWildcard(value: RouteParamValue | readonly RouteParamValue[]): string {
-  const segments = Array.isArray(value) ? value : String(value).split("/");
-  return (segments as readonly RouteParamValue[])
-    .map((segment) => encodeURIComponent(String(segment)))
-    .filter((segment) => segment.length > 0)
-    .join("/");
-}
-
-/** Serialise the query bag: `null`/`undefined` drop out, arrays repeat the key. */
-function _encodeQuery(query: RouteQuery): string {
-  const pairs: string[] = [];
-  for (const [key, value] of Object.entries(query)) {
-    if (value === null || value === undefined) continue;
-    const values = Array.isArray(value) ? value : [value];
-    for (const entry of values as readonly (string | number | boolean)[]) {
-      pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(entry))}`);
-    }
-  }
-  return pairs.join("&");
-}
-
-/** The {@link route} helper: a checked call signature plus its `dynamic` escape hatch. */
-export interface RouteBuilder {
-  /**
-   * Generate a URL for a named route, substituting `:param` segments.
-   *
-   * @param name - The registered route name, e.g. `'posts.show'`.
-   * @param args - `params` (one value per `:param`; a catch-all takes the `"*"` key and accepts an array of segments) then optional `query` values.
-   * @throws {Error} when the route name is unknown, a required `:param` is missing, or a param key matches no segment.
-   */
-  <N extends RouteTarget>(name: N, ...args: RouteArgs<N>): string;
-
-  /**
-   * Build a URL for a route name that isn't known at compile time — a name from
-   * config, a database row, or a package that registers routes conditionally.
-   *
-   * The escape hatch is a separate function rather than an overload on purpose:
-   * an overload taking `string` is matched by every string, which would let
-   * every typo through the front door. This one is greppable, and reads as the
-   * exception it is.
-   *
-   * @param name - The route name, resolved at runtime.
-   * @param params - One value per `:param` in the pattern.
-   * @param query - Optional query-string values.
-   * @throws {Error} on the same conditions as {@link route} — an unknown name still throws.
-   *
-   * @example
-   * route.dynamic(config('app.home_route'), { id })
-   */
-  dynamic(name: string, params?: RouteParamValues, query?: RouteQuery): string;
-}
+/**
+ * The {@link route} helper's call signature. Declared in `registry.ts` and
+ * shared with the browser's `route()` (`@zerotal/core/routes`) so the two are
+ * the same signature, not two that happen to look alike.
+ */
+export type { RouteBuilder } from "./registry.ts";
 
 /**
  * Generate a URL for a named route, substituting `:param` segments.
@@ -364,45 +319,17 @@ export const route: RouteBuilder = Object.assign(
   },
 );
 
+/**
+ * Look the name up in the live router, then hand off to the shared builder.
+ *
+ * The lookup is the *only* server-specific part of `route()`: it reads
+ * `_s().namedRoutes`, which is per-application and resets between tests. The
+ * URL semantics live in `buildRoute.ts`, shared with the browser build.
+ */
 function _buildRoute(name: string, params: RouteParamValues, query: RouteQuery): string {
   const pattern = _s().namedRoutes.get(name);
-  if (pattern === undefined) {
-    throw new Error(`[Zerotal] Named route not found: "${name}"`);
-  }
-
-  const usedKeys = new Set<string>();
-  let url = pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, key: string) => {
-    const value = params[key];
-    if (value === undefined) {
-      throw new Error(`[Zerotal] Missing parameter "${key}" for route "${name}"`);
-    }
-    usedKeys.add(key);
-    // Encode path params so values containing `/ ? #` cannot mangle the URL.
-    return encodeURIComponent(String(value));
-  });
-
-  // A catch-all segment reaches the router as `*` — the `[...slug]` name is gone
-  // by then — so the wildcard is its own param key.
-  if (url.includes("*")) {
-    const value = params["*"];
-    if (value === undefined) {
-      throw new Error(`[Zerotal] Missing catch-all parameter "*" for route "${name}"`);
-    }
-    usedKeys.add("*");
-    url = url.replace("*", _encodeWildcard(value));
-  }
-
-  const unknown = Object.keys(params).filter((key) => !usedKeys.has(key));
-  if (unknown.length > 0) {
-    throw new Error(
-      `[Zerotal] Unknown parameter${unknown.length > 1 ? "s" : ""} ` +
-        `${unknown.map((key) => `"${key}"`).join(", ")} for route "${name}" (${pattern}). ` +
-        `Query-string values go in the third argument: route(name, params, query).`,
-    );
-  }
-
-  const search = _encodeQuery(query);
-  return search ? `${url}?${search}` : url;
+  if (pattern === undefined) throw unknownRouteError(name);
+  return buildRouteUrl(name, pattern, params, query);
 }
 
 /**

package/src/router/buildRoute.ts

@@ -0,0 +1,110 @@
+/**
+ * The URL-building half of `route()`: pattern in, URL out. No table, no router,
+ * no request — which is the point.
+ *
+ * `route()` exists twice, once against the server's live `Router.namedRoutes`
+ * and once against the generated `ROUTES` table in the browser bundle. Only the
+ * *lookup* differs; everything a caller can actually observe — how a `:param` is
+ * encoded, what a catch-all accepts, which mistakes throw and what they say —
+ * lives here so the two cannot drift. A client `route()` that encoded params
+ * differently from the server's would be worse than no client `route()` at all:
+ * the links would be wrong only for the values nobody tests with.
+ *
+ * Nothing in this file may import anything that touches `Bun`, `process`, the
+ * container, or request state. It is bundled into browsers.
+ */
+import type { RouteParamValue, RouteParamValues, RouteQuery } from "./registry.ts";
+
+/** Encode one catch-all value: `'guides/intro'` and `['guides','intro']` both give `guides/intro`. */
+function encodeWildcard(value: RouteParamValue | readonly RouteParamValue[]): string {
+  const segments = Array.isArray(value) ? value : String(value).split("/");
+  return (segments as readonly RouteParamValue[])
+    .map((segment) => encodeURIComponent(String(segment)))
+    .filter((segment) => segment.length > 0)
+    .join("/");
+}
+
+/** Serialise the query bag: `null`/`undefined` drop out, arrays repeat the key. */
+export function encodeRouteQuery(query: RouteQuery): string {
+  const pairs: string[] = [];
+  for (const [key, value] of Object.entries(query)) {
+    if (value === null || value === undefined) continue;
+    const values = Array.isArray(value) ? value : [value];
+    for (const entry of values as readonly (string | number | boolean)[]) {
+      pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(entry))}`);
+    }
+  }
+  return pairs.join("&");
+}
+
+/**
+ * The error both `route()` implementations throw for a name that isn't registered.
+ *
+ * Shared so the server and the browser report an unknown name identically — a
+ * name that resolves in one and throws in the other is the exact confusion this
+ * module exists to prevent.
+ *
+ * @param name - The name that was looked up.
+ * @returns The error to throw; the caller throws it so the stack starts at the call site.
+ */
+export function unknownRouteError(name: string): Error {
+  return new Error(`[Zerotal] Named route not found: "${name}"`);
+}
+
+/**
+ * Substitute `params` into a URL pattern and append `query`.
+ *
+ * Params are **exact**: a key the pattern has no segment for throws rather than
+ * quietly becoming a query-string entry. That rule is the reason the typed
+ * signature is worth having — a typo'd param name that silently became
+ * `?slugg=hello` is the bug the whole feature exists to catch — so it is
+ * enforced at runtime too, for callers on the untyped path (`route.dynamic`, or
+ * an app that has never run `zt route:types`).
+ *
+ * @param name - The route name, used only in error messages.
+ * @param pattern - The URL pattern the name resolved to, e.g. `/posts/:slug`.
+ * @param params - One value per `:param`; a catch-all takes the `"*"` key.
+ * @param query - Query-string values, appended after the path.
+ * @returns The built URL path (with query string when there is one).
+ * @throws {Error} when a required `:param` is missing or a param key matches no segment.
+ */
+export function buildRouteUrl(
+  name: string,
+  pattern: string,
+  params: RouteParamValues,
+  query: RouteQuery,
+): string {
+  const usedKeys = new Set<string>();
+  let url = pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, key: string) => {
+    const value = params[key];
+    if (value === undefined) {
+      throw new Error(`[Zerotal] Missing parameter "${key}" for route "${name}"`);
+    }
+    usedKeys.add(key);
+    // Encode path params so values containing `/ ? #` cannot mangle the URL.
+    return encodeURIComponent(String(value));
+  });
+
+  // A catch-all segment reaches the router as `*` — the `[...slug]` name is gone
+  // by then — so the wildcard is its own param key.
+  if (url.includes("*")) {
+    const value = params["*"];
+    if (value === undefined) {
+      throw new Error(`[Zerotal] Missing catch-all parameter "*" for route "${name}"`);
+    }
+    usedKeys.add("*");
+    url = url.replace("*", encodeWildcard(value));
+  }
+
+  const unknown = Object.keys(params).filter((key) => !usedKeys.has(key));
+  if (unknown.length > 0) {
+    throw new Error(
+      `[Zerotal] Unknown parameter${unknown.length > 1 ? "s" : ""} ` +
+        `${unknown.map((key) => `"${key}"`).join(", ")} for route "${name}" (${pattern}). ` +
+        `Query-string values go in the third argument: route(name, params, query).`,
+    );
+  }
+
+  const search = encodeRouteQuery(query);
+  return search ? `${url}?${search}` : url;
+}

package/src/router/registry.ts

@@ -121,3 +121,45 @@ export type RouteArgs<N extends string> = [RouteName] extends [never]
       // any literal, so a static route would quietly swallow `{ page: 2 }`.
       [params?: Record<string, never>, query?: RouteQuery]
     : [params: RouteParams<N>, query?: RouteQuery];
+
+/**
+ * The `route()` helper: a checked call signature plus its `dynamic` escape hatch.
+ *
+ * Declared here, next to the types it is built from, because `route()` is
+ * implemented twice — once on the server against `Router.namedRoutes`, once in
+ * the browser against the generated `ROUTES` table. Both are typed as this
+ * interface, so the two call sites cannot drift apart in what they accept: a
+ * component that renders on the server and hydrates in the browser sees one
+ * signature either way.
+ *
+ * @category Naming & URLs
+ */
+export interface RouteBuilder {
+  /**
+   * Generate a URL for a named route, substituting `:param` segments.
+   *
+   * @param name - The registered route name, e.g. `'posts.show'`.
+   * @param args - `params` (one value per `:param`; a catch-all takes the `"*"` key and accepts an array of segments) then optional `query` values.
+   * @throws {Error} when the route name is unknown, a required `:param` is missing, or a param key matches no segment.
+   */
+  <N extends RouteTarget>(name: N, ...args: RouteArgs<N>): string;
+
+  /**
+   * Build a URL for a route name that isn't known at compile time — a name from
+   * config, a database row, or a package that registers routes conditionally.
+   *
+   * The escape hatch is a separate function rather than an overload on purpose:
+   * an overload taking `string` is matched by every string, which would let
+   * every typo through the front door. This one is greppable, and reads as the
+   * exception it is.
+   *
+   * @param name - The route name, resolved at runtime.
+   * @param params - One value per `:param` in the pattern.
+   * @param query - Optional query-string values.
+   * @throws {Error} on the same conditions as `route()` — an unknown name still throws.
+   *
+   * @example
+   * route.dynamic(config('app.home_route'), { id })
+   */
+  dynamic(name: string, params?: RouteParamValues, query?: RouteQuery): string;
+}

package/src/router/routes.ts

@@ -0,0 +1,149 @@
+/**
+ * `route()` for the browser — the `@zerotal/core/routes` entry point.
+ *
+ * The server's `route()` (from `@zerotal/core`) reads the live router, which
+ * only exists in the server process. This one reads a table you hand it at
+ * boot: the `ROUTES` object that `bun zt route:types` already generates and
+ * commits.
+ *
+ * ```ts
+ * // resources/js/app.js — once, before anything renders
+ * import { defineRoutes } from "@zerotal/core/routes";
+ * import { ROUTES } from "../../types/routes.generated";
+ *
+ * defineRoutes(ROUTES);
+ * ```
+ *
+ * ```ts
+ * // anywhere in a page or component
+ * import { route } from "@zerotal/core/routes";
+ *
+ * route("posts.show", { slug });           // "/posts/hello"
+ * route("posts.index", {}, { page: 2 });   // "/posts?page=2"
+ * ```
+ *
+ * The table is a build-time constant, so it costs one static import and
+ * tree-shakes to the routes you keep — nothing is shipped per response and
+ * nothing has to be fetched before the first link renders.
+ *
+ * **Types come from the same place as the server's.** The generated file
+ * augments `RouteRegistry` in `@zerotal/core`, and both `route()`s are typed as
+ * the one `RouteBuilder` interface, so a name that type-checks in a controller
+ * type-checks in a component and a missing `:param` fails the build on either
+ * side.
+ *
+ * **This module is isomorphic.** Inertia renders pages twice — once in the SSR
+ * process, once in the browser — so a component importing `route` from here
+ * runs in both. Call {@link defineRoutes} in each entry (`app.js` and `ssr.js`);
+ * it is the same static import, and the same table.
+ *
+ * @module
+ */
+import type {
+  RouteArgs,
+  RouteBuilder,
+  RouteParamValues,
+  RouteQuery,
+  RouteTarget,
+} from "./registry.ts";
+import { buildRouteUrl, unknownRouteError } from "./buildRoute.ts";
+
+/**
+ * The name → pattern map `route()` resolves against. A plain object is what
+ * `types/routes.generated.ts` exports; a `Map` is accepted so a server-side
+ * caller can pass `Router.namedRoutes` straight through.
+ */
+export type RouteTable = Readonly<Record<string, string>> | ReadonlyMap<string, string>;
+
+/** `null` until `defineRoutes()` runs — distinct from "defined but empty", which is a valid state. */
+let _table: ReadonlyMap<string, string> | null = null;
+
+/**
+ * Install the route table `route()` resolves against.
+ *
+ * Call it once per entry point, before the first render. Calling it again
+ * replaces the table, which is what makes the dev server's hot reload work —
+ * the entry re-runs and the new table wins.
+ *
+ * @param table - The generated `ROUTES` object, or any name → pattern map.
+ *
+ * @example
+ * import { ROUTES } from "../../types/routes.generated";
+ * defineRoutes(ROUTES);
+ */
+export function defineRoutes(table: RouteTable): void {
+  _table = table instanceof Map ? table : new Map(Object.entries(table));
+}
+
+/**
+ * Forget the installed table, putting `route()` back into its "not configured"
+ * state. For tests that assert on the unconfigured error — application code
+ * wants {@link defineRoutes} instead.
+ */
+export function resetRoutes(): void {
+  _table = null;
+}
+
+/**
+ * Whether `name` is in the installed table.
+ *
+ * Useful for the conditional links a client bundle cannot resolve by other
+ * means: a nav item for a route that only exists when a package is installed,
+ * or an admin link a public build never registers. Returns `false` — rather
+ * than throwing — when no table has been installed.
+ *
+ * @param name - The route name to look for.
+ *
+ * @example
+ * {hasRoute("admin.index") && <a href={route("admin.index")}>Admin</a>}
+ */
+export function hasRoute(name: string): boolean {
+  return _table?.has(name) ?? false;
+}
+
+/** Resolve a pattern or throw the message that tells the caller what to fix. */
+function _pattern(name: string): string {
+  if (_table === null) {
+    throw new Error(
+      `[Zerotal] route("${name}") was called before the route table was installed. ` +
+        `Add this to your client entry (and your SSR entry, if you have one):\n` +
+        `  import { defineRoutes } from "@zerotal/core/routes";\n` +
+        `  import { ROUTES } from "./types/routes.generated";\n` +
+        `  defineRoutes(ROUTES);\n` +
+        `Generate the table with: bun zt route:types`,
+    );
+  }
+  const pattern = _table.get(name);
+  if (pattern === undefined) throw unknownRouteError(name);
+  return pattern;
+}
+
+/**
+ * Generate a URL for a named route, substituting `:param` segments.
+ *
+ * The browser twin of the server's `route()` — same signature, same encoding,
+ * same errors, resolved against the table {@link defineRoutes} installed
+ * instead of against the live router.
+ *
+ * @example
+ * route("posts.show", { slug: "hello" })       // "/posts/hello"
+ * route("search", {}, { q: "reno", page: 2 })  // "/search?q=reno&page=2"
+ * route("docs.show", { "*": "guides/intro" })  // "/docs/guides/intro"
+ *
+ * @category Naming & URLs
+ */
+export const route: RouteBuilder = Object.assign(
+  <N extends RouteTarget>(name: N, ...args: RouteArgs<N>): string => {
+    const [params = {}, query = {}] = args as [RouteParamValues?, RouteQuery?];
+    return buildRouteUrl(name, _pattern(name), params, query);
+  },
+  {
+    dynamic: (name: string, params: RouteParamValues = {}, query: RouteQuery = {}): string =>
+      buildRouteUrl(name, _pattern(name), params, query),
+  },
+);
+
+// The route *types* are deliberately not re-exported here. They erase at
+// compile time, so `import type { RouteName } from "@zerotal/core"` costs a
+// browser bundle nothing — and a second export path for the same names is a
+// second entry in every surface report, forever, for no runtime benefit.

package/src/support/env.ts

@@ -53,6 +53,22 @@ export const DEV_WORKER_ENV_VAR = "ZT_DEV";
  */
 export const DEPLOY_ENV_VAR = "ZT_APP_ENV";
 
+/**
+ * The values of `APP_ENV` that name a runtime *mode* rather than a deployment.
+ * `setAppEnv()` writes these; {@link deployEnv} recognises them to know whether
+ * `APP_ENV` still holds the deployment name.
+ *
+ * @internal
+ */
+export const RUNTIME_MODES: ReadonlySet<string> = new Set([
+  "web",
+  "worker",
+  "console",
+  "test",
+  "testing",
+  "repl",
+]);
+
 /**
  * The deployment name this process was started with — `production`, `staging`,
  * `local`, whatever the operator set — as opposed to the runtime *mode*.
@@ -72,7 +88,17 @@ export const DEPLOY_ENV_VAR = "ZT_APP_ENV";
  * @internal
  */
 export function deployEnv(): string {
-  return Bun.env[DEPLOY_ENV_VAR] ?? Bun.env["APP_ENV"] ?? "";
+  // eslint-disable-next-line no-restricted-syntax -- this IS deployEnv — it decides whether APP_ENV still holds the deployment name
+  const current = Bun.env["APP_ENV"] ?? "";
+  // If `APP_ENV` still holds a deployment name, it has not been overwritten yet —
+  // or something set it deliberately since — so it is the freshest answer. Only
+  // once it holds a runtime mode is the preserved copy the better one.
+  //
+  // Preferring the preserved copy unconditionally made it sticky for the life of
+  // the process: anything that set `APP_ENV` afterwards was ignored, which is
+  // wrong in itself and which leaked between test files sharing one process.
+  if (current && !RUNTIME_MODES.has(current.toLowerCase())) return current;
+  return Bun.env[DEPLOY_ENV_VAR] ?? current;
 }
 
 /**
@@ -101,7 +127,11 @@ export function deployEnv(): string {
  */
 export function devSurfacesEnabled(): boolean {
   if (Bun.env[DEV_WORKER_ENV_VAR] === "1") return true;
-  return isDevSurfaceAllowed(Bun.env["APP_ENV"] ?? "");
+  // `deployEnv()`, not `Bun.env["APP_ENV"]` — by the time anything asks, `setAppEnv()`
+  // has replaced that with the runtime mode, and `isDevSurfaceAllowed("web")` is false.
+  // An app with `APP_ENV=development` in its `.env` was therefore getting production
+  // error pages from a plain `zt serve`.
+  return isDevSurfaceAllowed(deployEnv());
 }
 
 /**