@zerotal/core 1.7.0 → 1.7.3

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;
+}