@zerotal/core 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -6,6 +6,109 @@ follows the Zerotal monorepo's unified versioning.
 
 **Maturity: `stable`**
 
+## [Unreleased]
+
+### Added
+
+- **`@zerotal/core/errors`** — a subpath for the error classes, so a module that can run in a
+  browser can import `ZerotalError` without reaching the root entry. The root re-exports
+  `CommandRunner`, which reaches the built-in CLI commands and `await import("bun")`, so a single
+  root import is enough to make a browser bundle fail at resolution. `@zerotal/core/helpers`
+  already covered `deepMerge` the same way.
+
+  The rule this makes workable: **core's root entry is server-only.** Anything that might be
+  bundled for a browser imports from a narrow subpath.
+
+
+## [1.7.1] — 2026-08-16
+
+### Changed
+
+- **`APP_ENV` is the deployment name; the runtime mode moved to `APP_TYPE`.** They shared one
+  variable and the mode won: `setAppEnv()` overwrote `APP_ENV` with `web` / `worker` /
+  `console` at boot, so an app whose `.env` said `APP_ENV=development` read `"console"` back
+  from `env("APP_ENV")` inside every CLI command.
+
+  The dangerous direction is the one nobody hits in development. A guard written the obvious
+  way —
+
+  ```ts
+  if (env("APP_ENV") === "production") refuseToWipe();
+  ```
+
+  — was **inert in every console command**, which is exactly where destructive commands live.
+  1.7.0 patched the framework's own gates by parking a copy that `deployEnv()` read back, but
+  application code reading the documented variable the documented way still got the mode.
+
+  Two questions, two variables. `setAppEnv()` no longer touches `APP_ENV` at all and writes
+  the mode to `APP_TYPE`; `runtimeMode()` reads it, and falls back to the legacy location so a
+  process started by an older launcher still boots the right providers. An explicit
+  `APP_TYPE` wins over the command, which is how `serve --dev` boots its supervised server as
+  `web`. `deployEnv()` and `config("app.env")` are unchanged and still correct.
+
+  No action needed in an app unless it sets `APP_ENV=web` by hand to force web mode — that
+  still works, and `APP_TYPE=web` is the spelling to move to.
+
+  Found seeding the first cookbook app, where a guard fired that should not have.
+
+### Fixed
+
+- **`Router.raw()` did not answer `HEAD`.** The pipeline derives a `HEAD` handler from every
+  `GET` — its own docblock notes that not doing so gives "every uptime monitor,
+  load-balancer probe, CDN origin check and `curl -I`" a 404 — and the raw path was left out
+  of it. So `curl -I` against a raw route answered 404 while the `GET` beside it answered 200. This framework's own site serves `/docs/*` and `/blog` from raw routes, so every link
+  checker and uptime probe aimed at the documentation was told the page did not exist.
+
+  Derived from the wrapped handler rather than the bare one, so the security headers below
+  ride along and a `HEAD` cannot answer with fewer than the `GET` it mirrors. A `HEAD` the
+  app registered itself still wins. Third gap in the same family, after the headers and
+  static files: any path that answers a request without running the pipeline needs whatever
+  the pipeline was doing for it.
+
+- **The dev deck would not scroll.** On the alternate screen a terminal has no scrollback of
+  its own, so the wheel and the scrollbar had nothing to move and the deck read as frozen —
+  from the moment tabs mode starts, every way of looking at an older line has to come from
+  the deck itself, and only Page Up/Down did.
+
+  It now asks the terminal to send the wheel as cursor keys (`?1007h`, released again on
+  exit) and handles `↑`/`↓` and Home/End. Deliberately not mouse tracking, which would give
+  real wheel events at the price of the terminal's own text selection.
+
+  Two things had to change underneath. A read from stdin is not one key: a wheel tick arrives
+  as the same arrow repeated once per line, all in one chunk, and two fast keystrokes arrive
+  together — so a chunk is split into keys and the frame painted once at the end. And a card
+  that has been scrolled up now holds its place: `scroll` counts up from the newest line, so a
+  busy process used to drag the window down by a line for every line it printed, sliding the
+  text somebody had stopped to read off the top while they read it. A card pinned to the
+  bottom still follows its output, which is the one that should.
+
+Both of the next two were found by wiring DevTools into this repo's own `apps/docs` and
+driving it in a browser.
+
+- **`Router.raw()` responses carried no security headers.** A raw route opts out of the
+  _request_ pipeline — CSRF on a transport endpoint, session resolution on a relay — and was
+  silently opting its response out of `SecureHeadersMiddleware` too. This framework's own
+  documentation site serves every `/docs/*` page from a raw route, so every page of it went
+  out with no `X-Content-Type-Options: nosniff`, no `X-Frame-Options`, no
+  `Referrer-Policy` and no `Permissions-Policy`. In production the reverse proxy happened
+  to add two of them, which is why nothing had noticed.
+
+  The header set is now applied to raw responses at compile time, **add-if-absent** rather
+  than overwrite: a raw route is the one place a handler owns its whole response, and an
+  endpoint that deliberately allows framing has a reason the framework cannot see. The
+  response is only reconstructed when something is missing, so the hot path — Flow's action
+  endpoint is a raw route — pays nothing when it already has them.
+
+  This is the third surface in the same family, after the pipeline and static files. Any
+  path that answers a request without running middleware needs the same treatment.
+
+- **`redactGraph` masked booleans.** Sensitivity is judged by key name, by substring, so
+  `cors.credentials` matched "credential" and the DevTools Config tab reported
+  `‹redacted›` where the answer was `false`. A boolean has two possible values: masking one
+  conceals nothing a reader could not guess, and hides the security setting they opened the
+  tab to check. Booleans now pass through; numbers still mask, since a number can be a PIN
+  or an account. The helper also gained the test file it shipped without.
+
 ## [1.7.0] — 2026-08-16
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -11,6 +11,7 @@
     ".": "./src/index.ts",
     "./routes": "./src/router/routes.ts",
     "./contracts": "./src/contracts/index.ts",
+    "./errors": "./src/errors/index.ts",
     "./lock": "./src/lock/index.ts",
     "./logger": "./src/logger/index.ts",
     "./commands": "./src/command/builtin/index.ts",

package/src/application/Application.ts

@@ -14,6 +14,7 @@ import type { HttpContext } from "../pipeline/HttpContext.ts";
 import { Pipeline } from "../pipeline/Pipeline.ts";
 import { ExceptionHandler } from "./ExceptionHandler.ts";
 import { Router, RouterState } from "../router/Router.ts";
+import { defineRouteMethods, defineRoutes } from "../router/routes.ts";
 import type { StaticOptions } from "../router/Router.ts";
 import { Health, resolveHealthConfig, checkHealthAccess } from "../health/Health.ts";
 import type { HealthConfigShape } from "../health/Health.ts";
@@ -42,7 +43,7 @@ import { NotFoundError } from "../errors/HttpError.ts";
 import type { ContainerBindings } from "../container/types.ts";
 import { dispatchRequest } from "../router/RouteHandler.ts";
 import type { ProviderHooks } from "../router/RouteHandler.ts";
-import { isProdLike, deployEnv } from "../support/env.ts";
+import { isProdLike, deployEnv, runtimeMode } from "../support/env.ts";
 import { appKeyStrengthWarning } from "../support/appKey.ts";
 import { runBootDoctor } from "./BootDoctor.ts";
 import { runConfigValidators } from "../config/validation.ts";
@@ -254,6 +255,8 @@ export async function _lazyStaticResponse(
 
 /** Minimal WebSocket handler shape accepted by Bun.serve(). */
 export interface WebSocketHandlers {
+  /** Seconds a connection may go quiet before Bun closes it. Bun's default is 10. */
+  idleTimeout?: number;
   open?(ws: unknown): void;
   message(ws: unknown, message: string | Uint8Array): void;
   close?(ws: unknown, code: number, reason: string): void;
@@ -501,8 +504,12 @@ 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";
+    // The runtime mode, which is what provider filtering is keyed on. Reading
+    // `APP_ENV` here used to be right only because `setAppEnv()` had overwritten
+    // it with the mode; now the mode has its own variable and this asks for it
+    // directly. `_normaliseEnv` still maps a deployment name onto a mode, for an
+    // explicit `options.env`.
+    const rawEnv = options.env ?? runtimeMode("web");
     const resolvedEnv: Environment = _normaliseEnv(rawEnv);
 
     const app = new Application();
@@ -1068,6 +1075,17 @@ export class Application {
     };
 
     return {
+      // Bun closes an idle WebSocket after 10 seconds by default, and the client
+      // pings every 30 — so a connection that is merely *quiet* was being cut
+      // before it ever had reason to speak, taking its channel subscriptions
+      // with it. Nothing surfaced: the page stayed rendered, the client kept its
+      // channel objects, and broadcasts simply stopped arriving for anyone who
+      // had been reading for more than ten seconds.
+      //
+      // 120s leaves room for four missed pings before a genuinely dead socket is
+      // reaped, which is the direction to err: a stale connection costs memory,
+      // a reaped live one costs the feature.
+      idleTimeout: 120,
       open: (ws: unknown) => {
         if ((ws as AnyWS).data._dev) {
           DevWsServer.open(ws as AnyWS);
@@ -1213,6 +1231,21 @@ export class Application {
       await this._loadFileRoutes();
     }
 
+    // Install the route table for `zerotal/routes`, now that every route is
+    // registered.
+    //
+    // That module is the standalone URL builder a browser bundle imports, so it
+    // cannot reach for `Router` itself — importing the router would drag the
+    // server into every client bundle. The dependency therefore points this way:
+    // the server, which already has both, pushes the table in.
+    //
+    // Without this, `route()` threw on the server for any app that renders its
+    // own markup — a `view` build produces every href and form action there —
+    // and the fix was a `defineRoutes()` call each app had to know to write.
+    // A browser entry still calls it; that is a different process with no router
+    // to read. See T24.
+    this._installRouteTable();
+
     // A routes/ directory nobody routed is a silent 404 for every path in it — the file
     // imports cleanly and registers nothing, which looks identical to a typo'd URL.
     this._warnUnroutedRoutesDir(process.cwd());
@@ -1266,6 +1299,23 @@ export class Application {
     if (warning) frameworkLog("app").warn(warning);
   }
 
+  /**
+   * Hand the registered routes to the standalone `route()` builder.
+   *
+   * Name → pattern for the URLs, and name → verb for `action()`. `RouteDefinition`
+   * carries its own `name` beside `method`, so the pair comes from one record —
+   * a path join would be wrong, since `GET /login` and `POST /login` share a path.
+   */
+  private _installRouteTable(): void {
+    const methods = new Map<string, string>();
+    for (const definition of Router.routes.values()) {
+      if (definition.name) methods.set(definition.name, definition.method);
+    }
+
+    defineRoutes(Router.namedRoutes);
+    defineRouteMethods(Object.fromEntries(methods));
+  }
+
   private async _loadFileRoutes(): Promise<void> {
     for (const { dir, prefix, middleware } of this._fileRouteGroups) {
       await Router.groupAsync({ prefix, middleware }, () => scanFileRoutes(dir).then(() => {}));

package/src/command/builtin/RouteTypesCommand.ts

@@ -34,6 +34,7 @@ export class RouteTypesCommand extends Command {
 
   async run(): Promise<void> {
     const check = this.flags["check"] as boolean;
+
     const result = await writeRouteTypes(Router.namedRoutes, { check });
 
     if (check) {

package/src/dev/DevDeck.ts

@@ -19,10 +19,19 @@
  * ## The terminal must survive us
  *
  * Raw mode plus the alternate screen left on is the classic TUI bug: the shell
- * comes back with no echo, no line editing, and no scrollback. The restore is
+ * comes back with no echo, no line editing, and no shell scrollback. The restore is
  * therefore registered *before* raw mode is entered, and it runs on every exit
  * path there is — `q`, a signal, and an uncaught throw. It is also idempotent,
  * because several of those can happen at once.
+ *
+ * ## Scrolling is ours to do
+ *
+ * The alternate screen has no scrollback of its own, so the terminal's scrollbar
+ * and wheel have nothing to move: from the moment tabs mode starts, every way of
+ * looking at an older line has to come from here. Each card keeps its own buffer
+ * and its own position in it, the wheel arrives as cursor keys, and a card that
+ * has been scrolled up holds its place while the process behind it keeps
+ * printing.
  */
 import type { OutputWriter } from "../command/OutputWriter.ts";
 import type { DevProcessColor } from "./DevProcess.ts";
@@ -184,7 +193,7 @@ export class TabsDeck implements Deck {
   private _restored = false;
   private _stream: StreamDeck | undefined;
 
-  private readonly _onData = (chunk: Buffer | string): void => this._key(chunk.toString());
+  private readonly _onData = (chunk: Buffer | string): void => this._input(chunk.toString());
   private readonly _onResize = (): void => this._paint();
   private readonly _onExit = (): void => this.stop();
 
@@ -207,7 +216,7 @@ export class TabsDeck implements Deck {
     process.on("uncaughtException", this._onExit);
     process.on("unhandledRejection", this._onExit);
 
-    this._write(ALT_SCREEN_ON + CURSOR_HIDE);
+    this._write(ALT_SCREEN_ON + CURSOR_HIDE + ALT_SCROLL_ON);
     this._stdin.setRawMode?.(true);
     this._stdin.resume?.();
     this._stdin.on?.("data", this._onData);
@@ -224,6 +233,7 @@ export class TabsDeck implements Deck {
     const body = stream === "stderr" ? _paint(text, "red") : text;
     card.lines.push(`${stamp}${body}`);
     if (card.lines.length > SCROLLBACK) card.lines.shift();
+    this._anchor(card, body);
 
     // A tab the user is not looking at still buffers; only the visible one costs
     // a repaint. In stream mode every line prints regardless of focus.
@@ -271,26 +281,38 @@ export class TabsDeck implements Deck {
     }
     this._stdin.pause?.();
     if (this._repaintTimer) clearTimeout(this._repaintTimer);
-    this._write(CURSOR_SHOW + ALT_SCREEN_OFF);
+    this._write(ALT_SCROLL_OFF + CURSOR_SHOW + ALT_SCREEN_OFF);
   }
 
   // ── Input ──────────────────────────────────────────────────────────────────
 
-  private _key(sequence: string): void {
-    if (this._searching) {
-      this._searchKey(sequence);
-      return;
-    }
+  /**
+   * One read from stdin, which is not the same thing as one key.
+   *
+   * A wheel tick arrives as the same arrow sequence repeated as many times as
+   * there are lines to scroll, all in a single read, and two fast keystrokes
+   * arrive together — so a chunk is split into keys first and the frame is
+   * painted once at the end rather than once per key.
+   */
+  private _input(chunk: string): void {
+    let dirty = false;
+    for (const key of _keys(chunk)) dirty = this._key(key) || dirty;
+    if (dirty) this._paint();
+  }
+
+  /** Handle one key. Returns whether the frame needs repainting. */
+  private _key(sequence: string): boolean {
+    if (this._searching) return this._searchKey(sequence);
 
     switch (sequence) {
       case "q":
       case "\x03": // Ctrl-C — the deck owns the terminal, so it owns the quit.
         this._options.onQuit();
-        return;
+        return false;
       case "r": {
         const card = this._cards[this._focused];
         if (card) this._options.onRestart(card.status.name);
-        return;
+        return false;
       }
       case "c": {
         const card = this._cards[this._focused];
@@ -306,7 +328,7 @@ export class TabsDeck implements Deck {
         break;
       case "s":
         this._toggleStream();
-        return;
+        return false;
       case "t":
         this._timestamps = !this._timestamps;
         break;
@@ -317,22 +339,39 @@ export class TabsDeck implements Deck {
       case ARROW_LEFT:
         this._focus(this._focused - 1);
         break;
+      // The wheel is these two: in the alternate screen a terminal has no
+      // scrollback to move, so it sends the cursor keys instead (which is what
+      // `ALT_SCROLL_ON` asks for). Ignoring them is what makes the deck look
+      // like a terminal that will not scroll.
+      case ARROW_UP:
+        this._scroll(1);
+        break;
+      case ARROW_DOWN:
+        this._scroll(-1);
+        break;
       case PAGE_UP:
         this._scroll(this._bodyHeight());
         break;
       case PAGE_DOWN:
         this._scroll(-this._bodyHeight());
         break;
+      case HOME:
+        this._scroll(Number.MAX_SAFE_INTEGER);
+        break;
+      case END:
+        this._scroll(-Number.MAX_SAFE_INTEGER);
+        break;
       default: {
         if (sequence >= "1" && sequence <= "9") this._focus(Number(sequence) - 1);
-        else return;
+        else return false;
       }
     }
 
-    this._paint();
+    return true;
   }
 
-  private _searchKey(sequence: string): void {
+  /** Handle one key while the search box has the keyboard. Always repaints. */
+  private _searchKey(sequence: string): boolean {
     if (sequence === "\r" || sequence === "\n" || sequence === "\x1b") {
       // Enter keeps the filter and hands the keyboard back; Escape drops it.
       this._searching = false;
@@ -348,7 +387,7 @@ export class TabsDeck implements Deck {
 
     const card = this._cards[this._focused];
     if (card) card.scroll = 0;
-    this._paint();
+    return true;
   }
 
   private _focus(index: number): void {
@@ -361,11 +400,36 @@ export class TabsDeck implements Deck {
   private _scroll(by: number): void {
     const card = this._cards[this._focused];
     if (!card) return;
-    const total = this._visibleLines(card).length;
-    const max = Math.max(0, total - this._bodyHeight());
+    const max = Math.max(0, this._visibleLines(card).length - this._bodyHeight());
     card.scroll = Math.min(max, Math.max(0, card.scroll + by));
   }
 
+  /**
+   * Hold a scrolled-up view on the lines it was left on.
+   *
+   * `scroll` counts lines up from the newest, so a busy process would otherwise
+   * drag the window down by one line for every line it printed and the text
+   * somebody stopped to read would slide off the top while they read it. A card
+   * pinned to the bottom (`scroll === 0`) is left alone — that one *should*
+   * follow the output.
+   */
+  private _anchor(card: Card, appended: string): void {
+    if (card.scroll === 0) return;
+    // Only the focused card is ever filtered — `_focus()` clears the search —
+    // so only there can an arriving line be invisible and move nothing.
+    const needle = this._cards[this._focused] === card ? this._search.toLowerCase() : "";
+    const visible = !needle || appended.toLowerCase().includes(needle);
+    // Unfiltered, the count is the buffer's own — worth the branch, because this
+    // runs once per line of output and the buffer holds thousands.
+    const total = needle ? this._visibleLines(card).length : card.lines.length;
+    // Clamped even when nothing was added: at the scrollback cap every new line
+    // evicts an old one, and without this the view would walk off the top.
+    card.scroll = Math.min(
+      card.scroll + (visible ? 1 : 0),
+      Math.max(0, total - this._bodyHeight()),
+    );
+  }
+
   /**
    * Hand the terminal back and print plainly from here on.
    *
@@ -384,7 +448,7 @@ export class TabsDeck implements Deck {
       return;
     }
     this._stream = undefined as StreamDeck | undefined;
-    this._write(ALT_SCREEN_ON + CURSOR_HIDE);
+    this._write(ALT_SCREEN_ON + CURSOR_HIDE + ALT_SCROLL_ON);
     this._stdin.setRawMode?.(true);
     this._paint();
   }
@@ -453,7 +517,7 @@ export class TabsDeck implements Deck {
     const scrolled = card && card.scroll > 0 ? `  ↑${card.scroll}` : "";
     const filtered = this._search ? `  /${this._search}` : "";
     const keys =
-      "1-9 tab · ←/→ cycle · r restart · c clear · / search · t time · s stream · q quit";
+      "1-9 tab · ←/→ cycle · ↑/↓ scroll · r restart · c clear · / search · t time · s stream · q quit";
     return _fit(_paint(keys + filtered + scrolled, "dim"), width);
   }
 
@@ -486,10 +550,70 @@ const CURSOR_HOME = "\x1b[H";
 const CLEAR_LINE = "\x1b[K";
 const CLEAR_BELOW = "\x1b[J";
 
+/**
+ * Alternate scroll: ask the terminal to send cursor keys when the wheel turns.
+ *
+ * On the alternate screen there is no scrollback for the wheel to move, so
+ * without this the wheel does nothing at all and the deck reads as frozen.
+ * Most terminals do it by default, some do not, and asking costs one sequence.
+ * Deliberately *not* mouse tracking (`?1000h` and friends), which would hand us
+ * real wheel events at the price of the terminal's own text selection.
+ */
+const ALT_SCROLL_ON = "\x1b[?1007h";
+const ALT_SCROLL_OFF = "\x1b[?1007l";
+
+const ARROW_UP = "\x1b[A";
+const ARROW_DOWN = "\x1b[B";
 const ARROW_LEFT = "\x1b[D";
 const ARROW_RIGHT = "\x1b[C";
 const PAGE_UP = "\x1b[5~";
 const PAGE_DOWN = "\x1b[6~";
+const HOME = "\x1b[H";
+const END = "\x1b[F";
+
+/** A CSI sequence ends at the first byte in this range; everything before is parameters. */
+const _CSI_END = /[@-~]/;
+
+/**
+ * Split one read from stdin into individual key presses.
+ *
+ * SS3 arrows (`ESC O A`, what a terminal in application cursor mode sends) are
+ * rewritten to their CSI spelling so the switch upstairs only has to know one
+ * form of each key, and text is walked by code point so that an emoji typed
+ * into the search box stays one key rather than two broken halves.
+ */
+function _keys(chunk: string): string[] {
+  const out: string[] = [];
+  let at = 0;
+
+  while (at < chunk.length) {
+    if (chunk[at] !== "\x1b") {
+      const point = String.fromCodePoint(chunk.codePointAt(at)!);
+      out.push(point);
+      at += point.length;
+      continue;
+    }
+
+    const next = chunk[at + 1];
+    if (next === "[") {
+      let end = at + 2;
+      while (end < chunk.length && !_CSI_END.test(chunk[end]!)) end++;
+      // A sequence cut off by the end of the read is passed through whole
+      // rather than split into an Escape and some letters, which is what would
+      // type `[` and `A` into the search box.
+      out.push(chunk.slice(at, end + 1));
+      at = end + 1;
+    } else if (next === "O" && at + 2 < chunk.length) {
+      out.push(`\x1b[${chunk[at + 2]}`);
+      at += 3;
+    } else {
+      out.push("\x1b"); // A bare Escape — the key, not the start of anything.
+      at += 1;
+    }
+  }
+
+  return out;
+}
 
 const STATE_GLYPH: Record<DevProcessStatus["state"], string> = {
   starting: "◌",

package/src/dev/DevOrchestrator.ts

@@ -166,7 +166,7 @@ export class DevOrchestrator {
         cwd: this._cwd,
         env: {
           ...Bun.env,
-          APP_ENV: "web",
+          APP_TYPE: "web",
           // Mark the worker as developer-supervised. APP_ENV above is the
           // runtime mode, not a deployment name, so it cannot carry this —
           // without the flag the worker looks production-like to every

package/src/helpers/index.ts

@@ -22,7 +22,11 @@
  */
 import { join } from "node:path";
 import { ConfigError } from "../errors/ConfigError.ts";
-import { DEPLOY_ENV_VAR, RUNTIME_MODES as _RUNTIME_MODES } from "../support/env.ts";
+import {
+  DEPLOY_ENV_VAR,
+  RUNTIME_MODES as _RUNTIME_MODES,
+  RUNTIME_MODE_VAR as _RUNTIME_MODE_VAR,
+} from "../support/env.ts";
 
 // ── basePath() ────────────────────────────────────────────────────────────────
 
@@ -46,13 +50,19 @@ export function basePath(...segments: string[]): string {
 // ── setAppEnv() ───────────────────────────────────────────────────────────────
 
 /**
- * Set `APP_ENV` from the CLI command name — call this in `zerotal.ts` BEFORE
- * the dynamic import of `bootstrap/app.ts` so `Application.create()` sees
- * the correct environment.
+ * Set `APP_TYPE` — the runtime mode — from the CLI command name. Call it in
+ * `zerotal.ts` BEFORE the dynamic import of `bootstrap/app.ts`, so
+ * `Application.create()` sees the mode it should boot providers for.
  *
- * If `APP_ENV` is already set (e.g. from `.env` or the shell), this is a no-op.
+ * **`APP_ENV` is not touched.** That variable holds the deployment name the
+ * operator set, and it is what answers "is this production?". The two used to
+ * share one variable and the mode won, so `APP_ENV=production` read back as
+ * `"console"` in every CLI command — see {@link RUNTIME_MODE_VAR}.
  *
- * | Command              | APP_ENV   |
+ * An `APP_TYPE` already in the environment wins over the command, which is how
+ * the dev orchestrator boots a supervised server as `web`.
+ *
+ * | Command              | APP_TYPE  |
  * |----------------------|-----------|
  * | serve / start / s    | web       |
  * | dev / d              | web       |
@@ -71,41 +81,46 @@ export function setAppEnv(command?: string): void {
   const current = Bun.env["APP_ENV"];
   const environment = Bun.env as Record<string, string>;
 
-  // Preserve the deployment name before it is overwritten. Every branch below
-  // replaces `APP_ENV` with a runtime mode, which is why six different gates that
-  // asked "is this production?" of `Bun.env["APP_ENV"]` were reading `"web"` and
-  // 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}.
+  // `APP_ENV` is left alone. It holds the deployment name the operator set —
+  // `production`, `staging`, `local` — and it is the only place that answers
+  // "is this production?". This function used to overwrite it with the runtime
+  // mode, which is why six gates asking that question of `Bun.env["APP_ENV"]`
+  // read `"web"` and quietly answered no, including the weak-`APP_KEY` refusal
+  // and the ORM's N+1 detector; a preserved copy patched those, and then
+  // `env("APP_ENV")` still returned `"console"` inside a seeder, because the
+  // copy was only ever read through `deployEnv()`.
   //
-  // 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"`.
+  // Two questions, two variables. The mode goes to `APP_TYPE`.
   if (current && !_RUNTIME_MODES.has(current.toLowerCase())) {
+    // Still mirrored, for anything already reading the preserved copy.
     environment[DEPLOY_ENV_VAR] = current;
   }
 
+  // Deliberately no attempt to "migrate" a legacy `APP_ENV=web` into `APP_TYPE`
+  // and put a deployment name back. `RUNTIME_MODES` contains `test` — which
+  // `zt test` sets as a *deployment* name — so the two sets overlap and any
+  // rewrite here would eventually clobber the one thing this change exists to
+  // protect. `runtimeMode()` reads the legacy location instead, where a wrong
+  // guess costs a mode rather than an environment.
+
+  // An explicit `APP_TYPE` wins: it is how the dev orchestrator tells the server
+  // it supervises to boot as `web` regardless of the command that started it.
+  const explicit = environment[_RUNTIME_MODE_VAR];
+  if (explicit && _RUNTIME_MODES.has(explicit.toLowerCase())) return;
+
   if (["serve", "start", "s", "dev", "d"].includes(normalizedCommand)) {
-    // Always force web mode for the HTTP server — deployment-env names like
-    // "local" or "production" must not leave the app in console mode.
-    //
     // `dev` belongs here with `serve`, and the reason is not cosmetic. Dev mode's
     // process 1 boots the app purely to ask its providers what to run, and a
-    // provider is only asked if `static environments` includes the env it booted
+    // provider is only asked if `static environments` includes the mode it booted
     // under. Falling through to "console" below would silently drop every
     // web-only provider — no error, no empty tab, just a process that never
     // appears — and would make `zt dev` and `serve --dev` disagree about what
     // dev mode consists of.
-    if (!current || !_RUNTIME_MODES.has(current.toLowerCase())) {
-      environment["APP_ENV"] = "web";
-    }
+    environment[_RUNTIME_MODE_VAR] = "web";
   } else if (["worker", "queue:work"].includes(normalizedCommand)) {
-    if (!current || !_RUNTIME_MODES.has(current.toLowerCase())) {
-      environment["APP_ENV"] = "worker";
-    }
-  } else if (!current || !_RUNTIME_MODES.has(current.toLowerCase())) {
-    // Mirror the serve/worker branches: a deployment-env name like "local" or
-    // "production" must not leave the app in web mode for a CLI command.
-    environment["APP_ENV"] = "console";
+    environment[_RUNTIME_MODE_VAR] = "worker";
+  } else {
+    environment[_RUNTIME_MODE_VAR] = "console";
   }
 }
 

package/src/router/Router.ts

@@ -81,6 +81,40 @@ function _wrapFileHandler(fn: FileHandler, debugName: string): ControllerClass {
 type AnyRouteHandler = RouteHandler<any>;
 
 type RouteHandlerFn = (req: Request, server?: unknown) => Response | Promise<Response>;
+
+/**
+ * Wrap a raw handler so its response carries the security headers, without
+ * touching any the handler set for itself.
+ *
+ * Add-if-absent rather than `withHeaders`, which overwrites: a raw route is the
+ * one place a handler is fully in charge of its own response, and a transport
+ * endpoint that deliberately sets `X-Frame-Options` for its own reasons must
+ * keep it. The response is only reconstructed when something is actually
+ * missing, so a handler that already set everything pays nothing — and
+ * reconstruction is required rather than optional when it happens, because a
+ * `Response.redirect()` has an immutable headers guard that throws on `set`.
+ */
+function _withSecurityDefaults(
+  handler: RouteHandlerFn,
+  defaults: Record<string, string>,
+): RouteHandlerFn {
+  const names = Object.keys(defaults);
+  if (names.length === 0) return handler;
+
+  return async (req, server) => {
+    const response = await handler(req, server);
+    const missing = names.filter((name) => !response.headers.has(name));
+    if (missing.length === 0) return response;
+
+    const merged = new Headers(response.headers);
+    for (const name of missing) merged.set(name, defaults[name]!);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: merged,
+    });
+  };
+}
 /**
  * A path entry is either a method-keyed map of handlers, or a bare static
  * `Response` (Bun.serve serves the latter at zero JS cost per request).
@@ -1077,12 +1111,31 @@ export class Router {
 
     // Raw routes bypass the middleware pipeline entirely — added last so they
     // take precedence over any same-path pipeline routes.
+    //
+    // Bypassing the pipeline also bypasses `SecureHeadersMiddleware`, and that is
+    // not what anyone opts out for: `Router.raw()` exists to skip *request*
+    // handling — CSRF on a transport endpoint, session resolution on a relay —
+    // not to opt a response out of the headers the framework advertises as
+    // automatic. This framework's own documentation site serves every `/docs/*`
+    // page from a raw route, and every one of them went out with no
+    // `X-Content-Type-Options: nosniff`.
+    //
+    // Computed once here rather than per request: raw routes include Flow's
+    // action endpoint, which is as hot as anything in the app.
+    const rawDefaults = staticSecurityHeaders();
     for (const [key, handler] of _s().rawRoutes) {
       const spaceIndex = key.indexOf(" ");
       const method = key.slice(0, spaceIndex) as HttpMethod;
       const path = key.slice(spaceIndex + 1);
       const rawMap = (compiled[path] ??= {}) as Record<string, RouteHandlerFn>;
-      rawMap[method] = handler;
+      rawMap[method] = _withSecurityDefaults(handler, rawDefaults);
+      // And `HEAD`, for the same reason the pipeline derives it — a raw route is
+      // still a route, and `curl -I` against one answered 404 while the `GET`
+      // beside it answered 200. This site's own `/docs/*` and `/blog` are raw,
+      // so every link checker and uptime probe pointed at them was told the page
+      // did not exist. Derived from the wrapped handler, so the headers above
+      // ride along.
+      if (method === "GET") rawMap["HEAD"] ??= _headFrom(rawMap[method]!);
     }
 
     return compiled;

package/src/router/routeTypes.ts

@@ -24,6 +24,7 @@
  * the browser bundle.
  */
 import { relative } from "node:path";
+import { Router } from "./Router.ts";
 
 /** Where the generated map is written, relative to the project root. */
 export const ROUTE_TYPES_FILE = "types/routes.generated.ts";
@@ -32,9 +33,11 @@ const HEADER = [
   "// Auto-generated by @zerotal/core — do not edit manually.",
   "// Regenerate with: bun zt route:types",
   "//",
-  "// Every named route and the URL pattern it compiles to. `route()` reads this",
-  "// through declaration merging, so an unknown name or a missing :param is a",
-  "// compile error. Commit this file: editors and CI need it without booting the app.",
+  "// Every named route, the URL pattern it compiles to, and the HTTP method it",
+  "// answers on. `route()` reads ROUTES through declaration merging, so an unknown",
+  "// name or a missing :param is a compile error; `action()` also reads METHODS, so",
+  "// a form cannot submit a route with the wrong verb.",
+  "// Commit this file: editors and CI need it without booting the app.",
   "",
 ];
 
@@ -52,17 +55,28 @@ const HEADER = [
 export function generateRouteTypes(
   namedRoutes: ReadonlyMap<string, string>,
   importSpecifier = "@zerotal/core",
+  methods: ReadonlyMap<string, string> = new Map(),
 ): string {
   const entries = Array.from(namedRoutes.entries()).sort(([a], [b]) => a.localeCompare(b));
+  const key = (name: string) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
 
   // Quote the key only when it isn't a bare identifier — `home` stays bare and
   // `posts.show` stays quoted, which is what a formatter would do to this file
   // anyway. Matching it here keeps `format:check` off a file nobody edits.
-  const lines = entries.map(
-    ([name, pattern]) =>
-      `  ${/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name)}: ` +
-      `${JSON.stringify(pattern)},`,
-  );
+  const lines = entries.map(([name, pattern]) => `  ${key(name)}: ${JSON.stringify(pattern)},`);
+
+  // A second table rather than one of `{ url, method }` objects: `ROUTES` is what
+  // `route()` and `RouteRegistry` already read, and widening its value type would
+  // break every app that has generated this file. Two flat maps also stay
+  // tree-shakeable — a bundle that only builds links never pulls the verbs in.
+  const methodLines = entries
+    .filter(([name]) => methods.has(name))
+    .map(([name]) => `  ${key(name)}: ${JSON.stringify(methods.get(name))},`);
+
+  const methodTable =
+    methodLines.length > 0
+      ? ["export const METHODS = {", ...methodLines, "} as const;"]
+      : ["export const METHODS = {} as const;"];
 
   // Empty on one line: an app with no named routes still gets a file a formatter
   // leaves alone (and a registry that types nothing, so `route()` stays on its
@@ -76,11 +90,17 @@ export function generateRouteTypes(
     ...HEADER,
     ...table,
     "",
+    ...methodTable,
+    "",
     "/** The generated route table, as a type. */",
     "export type Routes = typeof ROUTES;",
     "",
+    "/** The HTTP method each named route answers on. */",
+    "export type RouteMethods = typeof METHODS;",
+    "",
     `declare module ${JSON.stringify(importSpecifier)} {`,
     "  interface RouteRegistry extends Routes {}",
+    "  interface RouteMethodRegistry extends RouteMethods {}",
     "}",
     // The file is rewritten on every dev boot; without a trailing newline a
     // formatter in the app would put one back, forever.
@@ -104,15 +124,21 @@ export interface RouteTypesResult {
  * Write (or, with `check`, verify) `types/routes.generated.ts` for a booted app.
  *
  * @param namedRoutes - The router's `namedRoutes` map.
- * @param options - `cwd` (project root, default `process.cwd()`) and `check` (compare only, never write).
+ * @param options - `cwd` (project root, default `process.cwd()`), `check` (compare only, never write), and `methods` (name → HTTP verb).
  * @returns Whether the on-disk file was stale, plus the contents it should have.
  */
 export async function writeRouteTypes(
   namedRoutes: ReadonlyMap<string, string>,
-  options: { cwd?: string; check?: boolean } = {},
+  options: { cwd?: string; check?: boolean; methods?: ReadonlyMap<string, string> } = {},
 ): Promise<RouteTypesResult> {
   const cwd = options.cwd ?? process.cwd();
-  const content = generateRouteTypes(namedRoutes);
+  // Derived here rather than asked of the caller. `zt dev` regenerates this file
+  // on every boot through its own call site, and when only `route:types` passed
+  // the verbs, a dev restart silently rewrote the table empty — which turned a
+  // form POST into a GET and 404'd. A default a caller must remember is a
+  // default that eventually gets forgotten.
+  const methods = options.methods ?? routeMethods();
+  const content = generateRouteTypes(namedRoutes, "@zerotal/core", methods);
   const target = `${cwd}/${ROUTE_TYPES_FILE}`;
 
   const file = Bun.file(target);
@@ -130,3 +156,18 @@ export async function writeRouteTypes(
     count: namedRoutes.size,
   };
 }
+
+/**
+ * Name → HTTP verb for every named route the router knows.
+ *
+ * `RouteDefinition` carries its own `name` beside `method`, so the pair comes
+ * from one record. A path join would be wrong: `GET /login` and `POST /login`
+ * share a path and differ only by name.
+ */
+export function routeMethods(): Map<string, string> {
+  const methods = new Map<string, string>();
+  for (const definition of Router.routes.values()) {
+    if (definition.name) methods.set(definition.name, definition.method);
+  }
+  return methods;
+}

package/src/router/routes.ts

@@ -48,6 +48,31 @@ import type {
 } from "./registry.ts";
 import { buildRouteUrl, unknownRouteError } from "./buildRoute.ts";
 
+/**
+ * Re-exported so a browser bundle can write its own typed wrappers.
+ *
+ * These live in `registry.ts`, which is reachable from the `@zerotal/core` root
+ * — and that root drags the CLI command modules into any bundle that imports it.
+ * A component building a helper around `route()` needs the types without the
+ * server, so they surface here, on the entry that is already browser-safe.
+ */
+export type { RouteArgs, RouteParamValues, RouteQuery, RouteTarget } from "./registry.ts";
+
+/**
+ * `route()` without an import.
+ *
+ * {@link defineRoutes} puts the builder on `globalThis`, and this is the
+ * declaration that lets a call site use it: a page writes `route("posts.show")`
+ * with no import line, typed exactly as the named export is — the same
+ * `RouteBuilder`, so an unknown name or a missing `:param` still fails the build.
+ *
+ * `var` rather than `const`, because only `var` in a `declare global` block
+ * creates a matching property on `globalThis` for the assignment to satisfy.
+ */
+declare global {
+  var route: RouteBuilder;
+}
+
 /**
  * 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
@@ -73,6 +98,25 @@ let _table: ReadonlyMap<string, string> | null = null;
  */
 export function defineRoutes(table: RouteTable): void {
   _table = table instanceof Map ? table : new Map(Object.entries(table));
+  _installGlobal();
+}
+
+/**
+ * Put `route()` on `globalThis`, so nothing has to import it.
+ *
+ * This is the one function both processes already call — the server from
+ * `Application._installRouteTable()` at boot, a browser entry beside its
+ * generated `ROUTES` — which makes it the only place that can install the global
+ * for both without an app remembering to do it in two files.
+ *
+ * The table is installed first, deliberately: a global that exists but throws
+ * "no route table" is worse than one that appears at the same moment it works.
+ *
+ * `route` stays a named export. Removing it would break every existing import
+ * for no gain, and a test that wants a clean global can still reach for it.
+ */
+function _installGlobal(): void {
+  (globalThis as { route?: typeof route }).route = route;
 }
 
 /**
@@ -147,3 +191,74 @@ export const route: RouteBuilder = Object.assign(
 // 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.
+
+// ── Verb-aware routes ─────────────────────────────────────────────────────────
+
+/**
+ * Augmented by `types/routes.generated.ts` with the HTTP method of every named
+ * route, exactly as {@link RouteRegistry} is augmented with their patterns.
+ */
+export interface RouteMethodRegistry {}
+
+/** A name the generated table knows a verb for. */
+export type MethodedRouteName = Extract<keyof RouteMethodRegistry, string>;
+
+const methodTable = new Map<string, string>();
+
+/**
+ * Register the generated `METHODS` table.
+ *
+ * Called once at boot beside {@link defineRoutes}. Kept separate because the two
+ * tables have different audiences: a page that only builds links needs the
+ * patterns and never the verbs, and a bundler can then drop the verbs entirely.
+ */
+export function defineRouteMethods(table: Readonly<Record<string, string>>): void {
+  methodTable.clear();
+  for (const [name, method] of Object.entries(table)) methodTable.set(name, method);
+}
+
+/** The verb a named route answers on, or undefined when it was never registered. */
+export function routeMethod(name: string): string | undefined {
+  return methodTable.get(name);
+}
+
+/** A resolved endpoint: where to send a request, and how. */
+export interface RouteAction {
+  url: string;
+  method: string;
+}
+
+/**
+ * Resolve a named route to both its URL and its HTTP method.
+ *
+ * The pair is the point. A form that hardcodes a URL can still send the wrong
+ * verb, and the failure — a 404 or a 405 on submit — looks nothing like its
+ * cause. Taking both from one generated record means a route that changes verb
+ * changes it everywhere at once.
+ *
+ * Throws when the name has no registered verb. An earlier version defaulted to
+ * `GET`, and that default cost a real bug: a regenerated table came back empty,
+ * every `action()` reported `GET`, and a file upload submitted as a GET to its
+ * own store route and 404'd. The point of resolving a verb from a table is that
+ * a wrong verb becomes impossible — a silent fallback gives that away for a
+ * failure mode nobody reads, so this is loud instead.
+ *
+ * Use {@link route} for links, which need no verb.
+ *
+ * @example
+ * const submit = action("projects.issues.comments.store", { project: "apollo", issue: 4 });
+ * // → { url: "/projects/apollo/issues/4/comments", method: "POST" }
+ */
+export function action<N extends RouteTarget>(name: N, ...args: RouteArgs<N>): RouteAction {
+  const method = methodTable.get(name as string);
+  if (method === undefined) {
+    throw new Error(
+      `action("${String(name)}"): no HTTP method registered for this route. ` +
+        `On the server this is installed at boot, so an empty table means the route ` +
+        `is not registered. In a browser bundle, call defineRouteMethods(METHODS) ` +
+        `from types/routes.generated.ts at your entry point. ` +
+        `Use route() instead for links, which need no verb.`,
+    );
+  }
+  return { url: route(name, ...args), method };
+}

package/src/security/redactGraph.ts

@@ -89,7 +89,16 @@ function _walk(
     }
     const out: Record<string, unknown> = {};
     for (const [key, item] of Object.entries(object as Record<string, unknown>)) {
-      out[key] = options.sensitive(key) ? options.mask : _walk(item, options, depth + 1, seen);
+      // A boolean is never a secret. It has two possible values, so masking one
+      // conceals nothing a reader could not guess — while destroying the answer
+      // they came for. Names are matched by substring, so this is not
+      // hypothetical: `cors.credentials` contains "credential" and came back as
+      // `‹redacted›` on the DevTools Config tab, hiding whether credentialed
+      // CORS was on. That is a security setting a reader is checking *because*
+      // it matters.
+      const maskable = typeof item !== "boolean";
+      out[key] =
+        maskable && options.sensitive(key) ? options.mask : _walk(item, options, depth + 1, seen);
     }
     return out;
   } finally {

package/src/support/env.ts

@@ -53,6 +53,21 @@ export const DEV_WORKER_ENV_VAR = "ZT_DEV";
  */
 export const DEPLOY_ENV_VAR = "ZT_APP_ENV";
 
+/**
+ * Environment variable holding the *runtime mode* — `web`, `worker`, `console`.
+ *
+ * Separate from `APP_ENV`, which holds the deployment name, because they answer
+ * different questions and one variable cannot hold both. It used to try: every
+ * boot overwrote `APP_ENV` with the mode, so `APP_ENV=production` read back as
+ * `"console"` inside a CLI command and a guard written `if (env("APP_ENV") ===
+ * "production") refuse()` was inert exactly where destructive commands live.
+ *
+ * Written by `setAppEnv()`; read through {@link runtimeMode}. Settable by hand to
+ * force a mode — `APP_TYPE=web bun zt.ts something` — which is what the dev
+ * orchestrator does for the server it supervises.
+ */
+export const RUNTIME_MODE_VAR = "APP_TYPE";
+
 /**
  * The values of `APP_ENV` that name a runtime *mode* rather than a deployment.
  * `setAppEnv()` writes these; {@link deployEnv} recognises them to know whether
@@ -73,17 +88,18 @@ export const RUNTIME_MODES: ReadonlySet<string> = new Set([
  * The deployment name this process was started with — `production`, `staging`,
  * `local`, whatever the operator set — as opposed to the runtime *mode*.
  *
- * `APP_ENV` carries both meanings, and the second one destroys the first:
- * `setAppEnv()` overwrites it with `web` / `console` / `worker` before the app
- * boots, so a gate that asks `isProdLike(Bun.env["APP_ENV"])` after startup is
+ * `APP_ENV` used to carry both meanings, and the second destroyed the first:
+ * `setAppEnv()` overwrote it with `web` / `console` / `worker` before the app
+ * booted, so a gate asking `isProdLike(Bun.env["APP_ENV"])` after startup was
  * asking whether `"web"` is production and always getting no. That was not
  * theoretical — it silently disabled the weak-`APP_KEY` refusal and left the
- * ORM's N+1 detector wrapping every query in production.
+ * ORM's N+1 detector wrapping every query in production, and it later made
+ * `env("APP_ENV")` return `"console"` inside a seeder.
  *
- * `setAppEnv()` now preserves the original value, and this reads it back. Prefer
- * it to `Bun.env["APP_ENV"]` for **any** production decision. Config is an
- * equally correct source where it is available (`config("app.env")`), but this
- * works before config is loaded and in processes that have none.
+ * The mode now lives in its own variable ({@link RUNTIME_MODE_VAR}) and `APP_ENV`
+ * is left alone, so this is usually just a read of it. The runtime-mode branch
+ * below stays for a process started by an older launcher, or one where somebody
+ * still exports `APP_ENV=web` by hand.
  *
  * @internal
  */
@@ -101,6 +117,30 @@ export function deployEnv(): string {
   return Bun.env[DEPLOY_ENV_VAR] ?? current;
 }
 
+/**
+ * How this process is running — `web`, `worker`, or `console`.
+ *
+ * The other half of what `APP_ENV` used to mean. Providers are filtered on it
+ * (`static environments = ["console"]`), which is why getting it wrong is not a
+ * cosmetic problem: a provider is simply never asked to register, with no error
+ * and nothing missing from the logs.
+ *
+ * `fallback` is what an unset environment means, and it differs by caller:
+ * `setAppEnv()` treats a process that never declared itself as a script
+ * (`console`), while `Application.create()` has always treated one as a server
+ * (`web`) — an app constructed directly, in a test or a script, expects its
+ * web providers to register.
+ */
+export function runtimeMode(fallback = "console"): string {
+  const mode = (Bun.env[RUNTIME_MODE_VAR] ?? "").toLowerCase();
+  if (RUNTIME_MODES.has(mode)) return mode;
+
+  // A process started by an older launcher, which put the mode in `APP_ENV`.
+  // eslint-disable-next-line no-restricted-syntax -- reading the legacy location is the fallback's entire job
+  const legacy = (Bun.env["APP_ENV"] ?? "").toLowerCase();
+  return RUNTIME_MODES.has(legacy) ? legacy : fallback;
+}
+
 /**
  * Whether *this process* may expose dev-only surfaces — the stack-trace error
  * page, the trace inspector, an open monitor panel.