@zerotal/core 1.14.3 → 1.15.1

package/CHANGELOG.md

@@ -8,6 +8,131 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.15.1] — 2026-09-13
+
+### Added
+
+- **`registerViewFileRouteResolver` is public.** It is what turns on server-rendered
+  file-route pages — a route file's default export rendered to HTML and wrapped in the
+  nearest `_layout` — and it carried an internal marker, so nothing outside the framework
+  could call it. Both features were implemented, tested, and described in `docs/view.md` as
+  automatic, while being unreachable through the public API.
+
+  Promoted rather than removed: the marker was wrong, not the design. It stays opt-in, and
+  the docblock now says why — it claims every `.tsx` route file's default export, which an
+  app using file routes for plain handlers has not asked for, and it turns on a directory
+  walk per scanned route. `docs/view.md` documents the call and the `_layout` convention,
+  including that `_layout` is read by its **default** export where `_middleware` is read by
+  a named one.
+
+### Fixed
+
+- **Four test suites left their fixture trees on disk after every run.** Each builds a
+  temporary package or asset tree and removes it in `afterAll`, and the removal reported
+  success without removing anything: on Bun 1.4.0 under Windows, a recursive `rm()` from
+  `node:fs/promises` resolves and deletes nothing when the path carries a `"./"` prefix,
+  which all four used. Written bare, the same call works.
+
+  Test-only, but it was not harmless. The abandoned trees contain deliberately
+  non-conformant fixture packages, `lint:ci` lints anything under `packages/**`, and the
+  gate is a ratchet against a committed count — so a full test run left the next lint run
+  one or two warnings over baseline, and the regression pointed at whatever change happened
+  to be in the tree. Previously read as fallout from interrupted runs, because an
+  interrupted run skips the hook and produces the same evidence.
+
+- **A `_layout` file that could not apply rendered its pages without one.** The same
+  fail-open the `_middleware` loader had, one function up in the same file, and found by
+  looking for the shape rather than by hitting it: an import error was swallowed together
+  with the not-found case under "component resolution is best-effort". Best-effort is
+  right for _absence_ and wrong for a file that exists and threw — a `_layout.tsx` with a
+  typo rendered every page beneath it without its chrome, with no error and no log, and on
+  a hot-reload without chrome it had a moment earlier.
+
+  Absence stays silent and the walk continues outward, as before. An import error stops
+  the boot with the path and the original error, and a `_layout` that default-exports no
+  component now says so rather than silently handing those pages an outer directory's
+  layout instead.
+
+  Worth noting alongside the `_middleware` fix in 1.15.0: these two sibling conventions
+  disagreed about export shape — `_layout` reads `default` and ignored a named export,
+  `_middleware` read the named export and ignored `default` — and each failed open on the
+  other's spelling. That disagreement is why `export default` was the natural guess in a
+  `_middleware.ts` to begin with.
+
+- **`zt doctor` says when its outside-in probes did not run.** The response-header and
+  WebSocket-transport probes only run with `--url`, and they are the two checks that can
+  see what no in-process check can. Being silent about skipping them meant the people who
+  most needed them were the ones with no way to learn they existed — a team running
+  `doctor` after every deploy for months never saw the duplicate-header check.
+
+  A line, not a new default: auto-probing `app.url` would print "✓ No duplicated security
+  headers" for a site that was merely unreachable, which is the same false confidence the
+  secure-headers check was fixed for in 1.15.0.
+
+## [1.15.0] — 2026-09-04
+
+### Changed — **BREAKING**
+
+- **BREAKING: a `_middleware.ts` that cannot apply now stops the boot.** Two ways one could
+  fail were silent, and both left the routes it was written to guard live and unguarded.
+  An app where either was happening will now refuse to boot until the file is fixed —
+  which is the point: it was not guarding anything before, and nothing said so. A directory
+  with no `_middleware` file is unchanged and stays silent. See the
+  [Upgrade Guide](/docs/upgrade#114-to-115).
+
+### Fixed
+
+- **A `_middleware.ts` that default-exported its list left the subtree unguarded.** The
+  loader read only `export const middleware`, so `export default [EmployerMiddleware]` was
+  ignored — no warning, no boot error, nothing in `route:list`. The app started, the routes
+  answered, and the directory the file was written to protect served to anyone. `export
+default` is the natural guess: every route file in the same directory default-exports its
+  handler.
+
+  The file now has to export a `middleware` array, and boot fails naming the file and the
+  fix when it does not. Nothing rejected here has ever applied, so no working app changes.
+
+- **An import error in a `_middleware.ts` was swallowed with the missing-file case.** Both
+  shared one `catch`, so a typo, a bad import path, a circular import or a `SyntaxError` all
+  read as "this directory has no middleware" and the routes beneath went on serving — on a
+  hot-reload, a guard that had been there a second earlier.
+
+  Absence and failure are now separate: no file is silent, as the convention intends, and a
+  file that threw stops the boot with the original error and its path. Under `zt dev` the
+  reload aborts and the previously compiled routes keep serving, so the guard never drops.
+
+- **`zt doctor`'s secure-headers check failed on any app behind a reverse proxy.** It read
+  `app.secureHeaders.secure` and inferred the response from it, so a deployment where Caddy
+  or nginx terminates TLS and sets HSTS — the most common production topology for a Bun app
+  — was reported as downgradeable while `curl -I` showed the header present. A check that is
+  wrong on the ordinary case is one people learn to skip.
+
+  It now makes one request to `app.url` on a deployment and reports what came back. When it
+  cannot reach the site, it warns with what it actually knows — the app does not send HSTS,
+  confirm the proxy does — instead of asserting a header is missing. Unreachable is no
+  longer reported as absent.
+
+### Added
+
+- **`zt route:types` regenerates every type file the app generates from its file tree**, not
+  only `types/routes.generated.ts`. `@zerotal/inertia` registers its page registry through
+  the new `registerTypeGenerator`, so adding a page and running the command whose name says
+  it generates types now does. Previously it regenerated the routes half, `Inertia.render`
+  still failed with `TS2345: … not assignable to 'PageName'`, and the error reads as a typo
+  in the page name rather than a registry that has not been rebuilt. `--check` gates on all
+  of them.
+
+- **`zt test` no longer inherits `.env`'s mail, queue, session and cache drivers.** Bun loads
+  `.env` into every process, so a developer with `MAIL_DRIVER=smtp` pointed at a local
+  Postfix got a suite where every path that sends mail opened a real SMTP connection — one
+  test going from milliseconds to a five-second timeout, failing only when run with its
+  siblings, and invisible to anyone without a mail server configured.
+
+  These four now get their in-process defaults (`log`, `sync`, `cookie`, `memory`), which is
+  what the app's own config already defaults to. A value set in the shell still wins, so
+  `MAIL_DRIVER=smtp bun zt test` works; `.env.test` is read and merged last; `--keep-env`
+  turns the whole thing off. The command prints what it changed.
+
 ## [1.14.3] — 2026-09-01
 
 ### Fixed

package/api-surface.md

@@ -3,6 +3,9 @@
 <!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
      Run `bun run api:surface` to regenerate after an intentional API change. -->
 
+> Not a guide — this is a flat, alphabetical snapshot used to detect unintended
+> API changes. For how to use these, read the [documentation](https://zerotal.dev/docs).
+
 ## .  `(./src/index.ts)`
 
 class AppBooted = {
@@ -3780,6 +3783,8 @@ function Fragment = ({ children }: {    children?: unknown;}) => SafeHtml
 
 function Raw = ({ html }: {    html: string;}) => SafeHtml
 
+function registerViewFileRouteResolver = () => void
+
 function safe = (html: string) => SafeHtml
 
 type Children = unknown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.14.3",
+  "version": "1.15.1",
   "license": "MIT",
   "maturity": "stable",
   "private": false,

package/src/command/TypeGenerators.ts

@@ -0,0 +1,87 @@
+/**
+ * The registry of generated-type files that `bun zt route:types` refreshes.
+ *
+ * Route names are not the only thing a Zerotal app generates from its own
+ * filesystem — `@zerotal/inertia` emits a page registry that gives
+ * `Inertia.render(name, props)` its typed page names. Both answer the same
+ * question ("what does the tree contain, as types?"), both go stale the moment
+ * a file is added, and `route:types` is the command whose name says it fixes
+ * that. It used to fix only half of it: adding a page and running `route:types`
+ * left the page registry stale, and the resulting error —
+ *
+ *   TS2345: Argument of type '"ops/orders"' is not assignable to 'PageName'
+ *
+ * — reads as "you typed the name wrong" rather than "nothing has regenerated
+ * the registry since you added the file", which sends you looking at the name.
+ *
+ * A view package registers its routine here from provider boot, so
+ * `@zerotal/core` never imports `@zerotal/inertia` (which would be circular).
+ * This mirrors `registerDevBuildHook` in `../dev/DevBuildHook.ts`, for the same
+ * reason and with the same shape.
+ */
+
+/**
+ * What one generator wrote, for the command's summary output.
+ *
+ * @internal Part of the {@link registerTypeGenerator} contract, like
+ * {@link TypeGeneratorFn} — framework-package plumbing, not app-facing API.
+ */
+export interface TypeGeneratorResult {
+  /** The file written, relative to the project root. */
+  file: string;
+  /** What it contains, phrased for a summary line (e.g. `12 pages`). */
+  summary: string;
+  /**
+   * Whether the file on disk differed from what the routine produced. Drives
+   * `route:types --check`, and lets the command say "Unchanged" rather than
+   * claiming a write it did not need to make.
+   */
+  changed: boolean;
+}
+
+/**
+ * A generated-types routine. `check` asks it to compare against disk and report,
+ * without writing — the CI gate that keeps a committed generated file honest.
+ *
+ * @internal
+ */
+export type TypeGeneratorFn = (options: { check: boolean }) => Promise<TypeGeneratorResult>;
+
+const _generators = new Map<string, TypeGeneratorFn>();
+
+/**
+ * @internal Exported for view packages to wire their codegen into `route:types`.
+ *
+ * Register a generated-types routine under a package name. Registering the same
+ * name twice replaces the earlier routine, so a provider may safely register on
+ * every boot.
+ */
+export function registerTypeGenerator(name: string, fn: TypeGeneratorFn): void {
+  _generators.set(name, fn);
+}
+
+/** @internal Forget every registered routine (tests only). */
+export function _resetTypeGenerators(): void {
+  _generators.clear();
+}
+
+/**
+ * @internal Run every registered routine, in registration order.
+ *
+ * One routine throwing does not stop the others — a broken page registry should
+ * not cost you your route types — but the error is returned rather than
+ * swallowed, so the command can report it and exit non-zero.
+ */
+export async function _runTypeGenerators(options: {
+  check: boolean;
+}): Promise<{ name: string; result?: TypeGeneratorResult; error?: unknown }[]> {
+  const outcomes: { name: string; result?: TypeGeneratorResult; error?: unknown }[] = [];
+  for (const [name, fn] of _generators) {
+    try {
+      outcomes.push({ name, result: await fn(options) });
+    } catch (error) {
+      outcomes.push({ name, error });
+    }
+  }
+  return outcomes;
+}

package/src/command/builtin/DoctorCommand.ts

@@ -39,6 +39,7 @@ export class DoctorCommand extends Command {
 
     const probeFailures = await this._probeTransport(app);
     const headerFindings = await this._probeHeaders();
+    this._noteSkippedProbes();
 
     const warns = report.filter((e) => e.result.status === "warn").length + headerFindings.warnings;
     const fails =
@@ -104,6 +105,30 @@ export class DoctorCommand extends Command {
    * are a warning, because they are a conflict waiting for someone to edit one
    * side.
    */
+  /**
+   * Say that the outside-in probes did not run, when they did not.
+   *
+   * They are the two checks that can see what no in-process check can — a header the
+   * proxy also sets, a WebSocket the proxy drops — and they are behind a flag, so the
+   * people who most need them are the ones who do not know the flag exists. A team
+   * running `doctor` after every deploy for months never saw the duplicate-header
+   * check and had no way to find out it was there.
+   *
+   * A line, not a default. Auto-probing `app.url` would print "✓ No duplicated
+   * security headers" for a site that was simply unreachable, which is a worse
+   * failure than the silence: it is the same false confidence the secure-headers
+   * check was fixed for.
+   */
+  private _noteSkippedProbes(): void {
+    if (this.flags["url"]) return;
+    this.newLine();
+    this.dim(
+      "Not checked: response headers and WebSocket transport, which are only visible " +
+        "from outside.\n    Add --url https://your-site to read the deployed app through " +
+        "its proxy.",
+    );
+  }
+
   private async _probeHeaders(): Promise<{ failures: number; warnings: number }> {
     const url = this.flags["url"] as string | undefined;
     if (!url) return { failures: 0, warnings: 0 };

package/src/command/builtin/RouteTypesCommand.ts

@@ -2,25 +2,34 @@ import { Command } from "../Command.ts";
 import type { FlagDef } from "../Command.ts";
 import { Router } from "../../router/Router.ts";
 import { writeRouteTypes, ROUTE_TYPES_FILE } from "../../router/routeTypes.ts";
+import { _runTypeGenerators } from "../TypeGenerators.ts";
 
 /**
- * `bun zt route:types` — write `types/routes.generated.ts`, the name → pattern
- * map that makes `route()` type-checked.
+ * `bun zt route:types` — refresh every type file the app generates from its own
+ * filesystem: `types/routes.generated.ts`, the name → pattern map that makes
+ * `route()` type-checked, plus whatever the installed view packages register
+ * (`@zerotal/inertia` adds its page registry, which types `Inertia.render`).
+ *
+ * It generates more than routes because a developer who adds a page and gets a
+ * type error about its name reaches for the command whose name says it
+ * generates types — and used to get the same error back, having regenerated the
+ * wrong half. Both files answer "what does the tree contain, as types?", and
+ * both go stale on the same edits.
  *
  * Boots the application (`needsApp`) and reads `Router.namedRoutes`, so routes
  * a provider registers programmatically and names set via a route file's
  * `export const meta` are included — not just what the file-router's naming
  * convention would produce.
  *
- * Commit the generated file: editors and CI need it without booting the app.
- * `zt dev` refreshes it on every restart, and `--check` fails when the file on
- * disk no longer matches the routes, which is the CI gate that keeps it honest.
+ * Commit the generated files: editors and CI need them without booting the app.
+ * `zt dev` refreshes them on every restart, and `--check` fails when a file on
+ * disk no longer matches, which is the CI gate that keeps them honest.
  *
  * @category Diagnostics
  */
 export class RouteTypesCommand extends Command {
   static commandName = "route:types";
-  static description = "Generate types/routes.generated.ts for typed route() names";
+  static description = "Generate the app's type files (routes, and any view package's registry)";
   static needsApp = true;
   static args = [];
   static flags: FlagDef[] = [
@@ -35,23 +44,51 @@ export class RouteTypesCommand extends Command {
   async run(): Promise<void> {
     const check = this.flags["check"] as boolean;
 
-    const result = await writeRouteTypes(Router.namedRoutes, { check });
+    const routes = await writeRouteTypes(Router.namedRoutes, { check });
+
+    // The routes file, then whatever the installed view packages register — the
+    // Inertia page registry, today. Collected into one list so the command reports
+    // every generated file the same way, and so a failure in one does not cost
+    // you the other: half-regenerated types are how this got confusing to begin with.
+    const files: { file: string; summary: string; changed: boolean }[] = [
+      {
+        file: ROUTE_TYPES_FILE,
+        summary: `${routes.count} named routes`,
+        changed: routes.changed,
+      },
+    ];
+    let failed = false;
+
+    for (const { name, result, error } of await _runTypeGenerators({ check })) {
+      if (error) {
+        failed = true;
+        this.error(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+        continue;
+      }
+      if (result) files.push(result);
+    }
 
     if (check) {
-      if (result.changed) {
-        this.error(`${result.path} is out of date. Run: bun zt route:types`);
-        throw new Error("Route types are out of date.");
+      const stale = files.filter((f) => f.changed);
+      for (const f of files) {
+        if (f.changed) this.error(`${f.file} is out of date. Run: bun zt route:types`);
+        else this.info(`${f.file} is up to date (${f.summary}).`);
+      }
+      if (stale.length > 0) {
+        throw new Error(`Generated types are out of date: ${stale.map((f) => f.file).join(", ")}`);
       }
-      this.info(`${result.path} is up to date (${result.count} named routes).`);
+      if (failed) throw new Error("A type generator failed.");
       return;
     }
 
-    if (result.count === 0) {
+    if (routes.count === 0) {
       this.warn("No named routes found — the generated map is empty.");
     }
 
-    this.info(
-      `${result.changed ? "Wrote" : "Unchanged"}: ${ROUTE_TYPES_FILE} (${result.count} named routes)`,
-    );
+    for (const f of files) {
+      this.info(`${f.changed ? "Wrote" : "Unchanged"}: ${f.file} (${f.summary})`);
+    }
+
+    if (failed) throw new Error("A type generator failed.");
   }
 }

package/src/command/builtin/TestCommand.ts

@@ -1,5 +1,6 @@
 import { Command } from "../Command.ts";
 import { bunBinary } from "../../support/runtime.ts";
+import { testEnvOverrides } from "../testEnv.ts";
 
 /**
  * `bun zt test [pattern] [flags]` — runs the test suite in the test environment.
@@ -11,6 +12,9 @@ import { bunBinary } from "../../support/runtime.ts";
  *    withDatabase() and DB.table() work without manual beforeAll boilerplate.
  *  - If @zerotal/testing is not installed the preload is silently skipped —
  *    tests that use createTestApp() still work without it.
+ *  - Resets the driver keys `.env` would otherwise lend the suite (mail, queue,
+ *    session, cache) to their in-process defaults, and loads `.env.test` when
+ *    the app has one. See `../testEnv.ts` for why, and `--keep-env` to opt out.
  *
  * All positional args and recognised flags are forwarded to bun test.
  *
@@ -72,6 +76,12 @@ export class TestCommand extends Command {
       description: "Run database/migrations against the test database before the suite",
       default: false,
     },
+    {
+      name: "keep-env",
+      type: "boolean" as const,
+      description: "Inherit .env's mail/queue/session/cache drivers instead of resetting them",
+      default: false,
+    },
   ];
 
   async run(): Promise<void> {
@@ -122,7 +132,18 @@ export class TestCommand extends Command {
     const timeout = (this.flags["timeout"] as number | undefined) || TestCommand.DEFAULT_TIMEOUT_MS;
     bunArguments.push(`--timeout=${timeout}`);
 
+    // `.env` is written for `zt dev`; a test run should decide for itself which
+    // outbound services it reaches. Reported rather than applied silently — a
+    // suite that behaves differently from the same code under `zt dev` has to
+    // say so, or the next person debugs the difference instead of reading it.
+    const { overrides, neutralised } = this.flags["keep-env"]
+      ? { overrides: {}, neutralised: [] as string[] }
+      : await testEnvOverrides(process.cwd(), Bun.env as Record<string, string | undefined>);
+
     this.dim(`APP_ENV=test  ZT_DB_URL=${dbUrl}  bun ${Bun.version}`);
+    if (neutralised.length > 0) {
+      this.dim(`Reset for tests: ${neutralised.join("  ")}  (keep .env's with --keep-env)`);
+    }
     this.dim(`bun ${bunArguments.join(" ")}\n`);
 
     // `bunBinary()`, not `"bun"`. The child of a command whose entire job is to run
@@ -136,6 +157,7 @@ export class TestCommand extends Command {
       stderr: "inherit",
       env: {
         ...Bun.env,
+        ...overrides,
         APP_ENV: "test",
         ZT_DB_URL: dbUrl,
       } as Record<string, string | undefined>,

package/src/command/builtin/index.ts

@@ -60,3 +60,10 @@ export { AssetsBuildCommand } from "./AssetsBuildCommand.ts";
 export { AssetsPruneCommand } from "./AssetsPruneCommand.ts";
 export { LintPackagesCommand } from "./LintPackagesCommand.ts";
 export { MakePackageCommand } from "./MakePackageCommand.ts";
+
+// Extension point rather than a command: lets a view package add its own
+// generated-types file to `zt route:types`, so one command refreshes every type
+// file an app generates from its file tree. `@zerotal/inertia` registers its page
+// registry here. See ../TypeGenerators.ts.
+export { registerTypeGenerator } from "../TypeGenerators.ts";
+export type { TypeGeneratorFn, TypeGeneratorResult } from "../TypeGenerators.ts";

package/src/command/testEnv.ts

@@ -0,0 +1,140 @@
+/**
+ * The environment `bun zt test` hands its child, and the one thing it takes away.
+ *
+ * Bun loads `.env` into every process it starts, so a test run inherits the
+ * developer's whole local setup — including the driver keys that decide whether
+ * a code path talks to something real. A developer with `MAIL_DRIVER=smtp`
+ * pointed at a local Postfix gets a suite where every path that sends mail opens
+ * an SMTP connection: one confirmed payment that issues an invitation goes from
+ * milliseconds to a five-second timeout, and fails only when run with its
+ * siblings. A developer with no mail server configured never sees it, which
+ * makes it precisely the kind of failure that lands on one person and looks
+ * like flakiness to everyone else.
+ *
+ * So the drivers below are reset for the test child. Not because `.env` is
+ * wrong — it is right for `zt dev`, which is what it was written for — but
+ * because "which outbound service does this reach" is a question a test run
+ * should answer for itself. The app's own config already defaults to the same
+ * safe values; it is only `.env` that overrides them.
+ *
+ * Two things still win over this:
+ *  - a value set in the shell (`MAIL_DRIVER=smtp bun zt test`), which is
+ *    someone deliberately testing that path;
+ *  - a value in `.env.test`, which is the same intent written down. Bun only
+ *    loads that file when `NODE_ENV=test`, so it is read here explicitly rather
+ *    than left as a file the docs mention and nothing loads.
+ */
+
+/**
+ * Driver keys reset for a test run, and what they are reset to. Each default is
+ * the in-process option: no socket, no external service, no shared state between
+ * runs — and each is already the app config's own default.
+ */
+export const TEST_SAFE_DRIVERS: Readonly<Record<string, string>> = {
+  /** Writes the message to the log instead of opening an SMTP connection. */
+  MAIL_DRIVER: "log",
+  /** Runs a dispatched job inline, so a test sees its effects without a worker. */
+  QUEUE_DRIVER: "sync",
+  /** Keeps the session in the cookie rather than reaching for Redis. */
+  SESSION_DRIVER: "cookie",
+  /** In-process cache, so one test file cannot see another's entries. */
+  CACHE_DRIVER: "memory",
+};
+
+/**
+ * Parse a dotenv file into a map. Deliberately small: this is used to find out
+ * *which keys a file mentions*, not to load anything — Bun has already loaded
+ * `.env` by the time this runs, and re-implementing its full semantics here
+ * would only produce a second, disagreeing answer.
+ *
+ * @param text - Raw file contents.
+ * @returns Key → value, with surrounding quotes stripped.
+ */
+export function parseDotenv(text: string): Map<string, string> {
+  const entries = new Map<string, string>();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+
+    const key = line
+      .slice(0, eq)
+      .trim()
+      .replace(/^export\s+/, "");
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+
+    let value = line.slice(eq + 1).trim();
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.endsWith(quote) && value.length > 1) {
+      value = value.slice(1, -1);
+    } else {
+      // Unquoted values run to a trailing comment, matching dotenv.
+      value = value.replace(/\s+#.*$/, "");
+    }
+    entries.set(key, value);
+  }
+  return entries;
+}
+
+/** Read and parse a dotenv file, or an empty map when it does not exist. */
+async function _read(path: string): Promise<Map<string, string>> {
+  const text = await Bun.file(path)
+    .text()
+    .catch(() => null);
+  return text === null ? new Map() : parseDotenv(text);
+}
+
+/**
+ * Work out what to change about the child process's environment.
+ *
+ * @param cwd - Project root holding the dotenv files.
+ * @param env - The parent's environment, as the child would otherwise inherit it.
+ * @returns Keys to override, and the subset of those that were neutralised drivers (for reporting).
+ */
+export async function testEnvOverrides(
+  cwd: string,
+  env: Record<string, string | undefined>,
+): Promise<{ overrides: Record<string, string>; neutralised: string[] }> {
+  const [dotenv, dotenvLocal, dotenvTest] = await Promise.all([
+    _read(`${cwd}/.env`),
+    _read(`${cwd}/.env.local`),
+    _read(`${cwd}/.env.test`),
+  ]);
+
+  const overrides: Record<string, string> = {};
+  const neutralised: string[] = [];
+
+  for (const [key, safe] of Object.entries(TEST_SAFE_DRIVERS)) {
+    const current = env[key];
+
+    // Unset means the app config's default applies, which is already the safe
+    // one — setting it anyway would only paper over a config the app changed
+    // on purpose.
+    if (current === undefined) continue;
+
+    // Already safe: nothing to say, and nothing to report.
+    if (current === safe) continue;
+
+    // Set in the shell rather than in a file — someone testing this path on
+    // purpose. Inferred by comparing against what the files declare, which is
+    // the only handle available: Bun merges dotenv into the environment before
+    // any of this runs, and does not record where a value came from.
+    const fromFile = dotenv.get(key) === current || dotenvLocal.get(key) === current;
+    if (!fromFile) continue;
+
+    overrides[key] = safe;
+    neutralised.push(`${key}=${safe}`);
+  }
+
+  // `.env.test` last: it is the app saying what a test run should use, which
+  // outranks both the inherited value and the default chosen here.
+  for (const [key, value] of dotenvTest) {
+    overrides[key] = value;
+    const index = neutralised.findIndex((entry) => entry.startsWith(`${key}=`));
+    if (index !== -1) neutralised.splice(index, 1);
+  }
+
+  return { overrides, neutralised };
+}

package/src/doctor/AppDoctor.ts

@@ -351,22 +351,88 @@ const corsWildcardCheck: DoctorCheck = {
  * false and has never had production auto-detection. A deployment that never set it
  * serves no `Strict-Transport-Security` at all, so a visitor's first request each
  * time stays downgradeable to plain HTTP.
+ *
+ * The header is the only thing that settles this, and the header is not always the
+ * app's to send. Reading `app.secureHeaders.secure` and inferring the response from
+ * it failed on the most ordinary production topology there is: a reverse proxy
+ * terminating TLS and setting HSTS itself. The app's config is then correctly
+ * false, the header is correctly present, and the check said the site could be
+ * downgraded — a wrong answer on a check that is otherwise reliable enough to be
+ * read, which is how a check becomes the line people learn to skip.
+ *
+ * So it probes when it can (`--url`, or `app.url` on a deployment: the response is
+ * the only thing that answers the question) and, when it cannot, says what it
+ * actually knows — the app does not send HSTS — rather than what it was guessing.
  */
 const secureHeadersCheck: DoctorCheck = {
   id: "secure-headers",
   label: "Secure headers",
-  run(app) {
+  async run(app) {
     const secure = _config(app, "app.secureHeaders.secure") === true;
     if (secure) return ok("HSTS enabled.");
     if (!_isProductionEnv(app)) return ok("HSTS off — expected outside a deployment.");
-    return fail(
-      "app.secureHeaders.secure is not true, so no Strict-Transport-Security header is " +
-        "sent and the first request of each visit can be downgraded to HTTP.",
-      "Set app.secureHeaders.secure: true in config/app.ts once the site is served over HTTPS.",
+
+    // One request to the public URL, which is the only view that includes the
+    // proxy. A loopback `app.url` on a deployment is its own finding, already
+    // reported by the transport-origins check.
+    const url = _config(app, "app.url");
+    if (typeof url === "string" && url !== "" && !_isLoopback(url)) {
+      const observed = await _observedHsts(url);
+      if (observed === true) {
+        return ok(`HSTS served by the proxy (${url}) — the app does not set it.`);
+      }
+      if (observed === false) {
+        return fail(
+          `No Strict-Transport-Security on ${url}: neither the app nor anything in ` +
+            `front of it sends it, so the first request of each visit can be downgraded ` +
+            `to HTTP.`,
+          "Set app.secureHeaders.secure: true in config/app.ts, or add the header at the proxy.",
+        );
+      }
+      // Unreachable: the deployment may not be up yet, or `doctor` may be running
+      // somewhere that cannot see the public URL. That is not evidence either way.
+    }
+
+    return warn(
+      "app.secureHeaders.secure is not true, so the app does not send " +
+        "Strict-Transport-Security. If a reverse proxy terminates TLS it may be sending " +
+        "it — confirm there; if nothing does, the first request of each visit can be " +
+        "downgraded to HTTP.",
+      `Check with: curl -sI ${typeof url === "string" && url !== "" ? url : "https://your-site"} | grep -i strict-transport-security\n` +
+        "    Then either set app.secureHeaders.secure: true in config/app.ts, or leave it " +
+        "to the proxy — but not both, which sends the header twice.",
     );
   },
 };
 
+/**
+ * Whether the deployed site answers with `Strict-Transport-Security`.
+ *
+ * `null` when the request could not be made at all, which is different from "no
+ * header" and must not be reported as one.
+ */
+async function _observedHsts(url: string): Promise<boolean | null> {
+  try {
+    const response = await fetch(url, {
+      method: "HEAD",
+      // `redirect: "manual"`: the redirect's own response is the one the proxy wrote,
+      // and following it would report the destination's headers instead.
+      redirect: "manual",
+      // `doctor` is what people run immediately after a deploy, so it may not hang on
+      // an unreachable host — a diagnostic that stops responding is worse than one
+      // that says it could not tell. A timeout lands in the `catch` as `null`, which
+      // is already "no evidence either way" rather than "no header".
+      signal: AbortSignal.timeout(_PROBE_TIMEOUT_MS),
+    });
+    return response.headers.get("strict-transport-security") !== null;
+  } catch {
+    return null;
+  }
+}
+
+/** How long the HSTS probe waits before reporting that it could not tell. */
+const _PROBE_TIMEOUT_MS = 5_000;
+
 /**
  * A rate limiter behind a proxy that was never told about the proxy keys every
  * visitor to the same bucket, because the socket address is the proxy's. It then

package/src/index.ts

@@ -245,6 +245,9 @@ export type {
 } from "./router/Route.ts";
 export { scanFileRoutes, registerFileRouteResolver } from "./router/FileRouter.ts";
 export type { FileRouteResolver, FileRouteContext } from "./router/FileRouter.ts";
+// `registerTypeGenerator` — the hook that lets a view package add its own
+// generated-types file to `zt route:types` — lives on `@zerotal/core/commands`,
+// not here: it is command plumbing, and this barrel is the frozen lean kernel.
 export type {
   FileHandler,
   RouteModule,

package/src/router/FileRouter.ts

@@ -312,25 +312,73 @@ async function _collectMiddleware(
     // sibling routes stayed live and unguarded, with no error and no log. A convention
     // that fails open is worse than one that does not exist.
     const middlewarePath = await _findMiddlewareFile(baseDir, dir);
+    // No file is the convention working — most directories have none. Everything past
+    // this point is a file somebody wrote in order to guard a subtree, so every way it
+    // can fail to apply is loud. These two cases used to share one `catch`, which made
+    // "there is no middleware here" and "the middleware is broken" indistinguishable.
+    if (!middlewarePath) continue;
+
+    // Convert to a file:// URL so dynamic import works on Windows (raw
+    // absolute paths with backslashes are not valid import specifiers).
+    // Append ?t=<reloadId> to bust the module cache on hot-reload.
+    const href = pathToFileURL(middlewarePath).href;
+    const importUrl = reloadId ? `${href}?t=${reloadId}` : href;
+
+    let loadedModule: MiddlewareModule & { default?: unknown };
     try {
-      if (middlewarePath) {
-        // Convert to a file:// URL so dynamic import works on Windows (raw
-        // absolute paths with backslashes are not valid import specifiers).
-        // Append ?t=<reloadId> to bust the module cache on hot-reload.
-        const href = pathToFileURL(middlewarePath).href;
-        const importUrl = reloadId ? `${href}?t=${reloadId}` : href;
-        const loadedModule = (await import(importUrl)) as MiddlewareModule;
-        if (Array.isArray(loadedModule.middleware)) {
-          result.push(...loadedModule.middleware);
-        }
-      }
-    } catch {
-      // The file is missing or failed to import — skip it.
+      loadedModule = (await import(importUrl)) as MiddlewareModule & { default?: unknown };
+    } catch (error) {
+      // A typo, a bad import path, a circular import, a SyntaxError — swallowing any of
+      // these left the subtree beneath serving normally with its guard silently gone,
+      // and on a hot-reload, gone a second after it was there. Boot stops instead.
+      throw new Error(
+        `[Zerotal] Failed to import ${middlewarePath}: ` +
+          `${error instanceof Error ? error.message : String(error)}\n` +
+          `Routes under this directory would serve unguarded, so boot stops here. ` +
+          `Fix the file, or delete it if the subtree needs no middleware.`,
+        { cause: error },
+      );
     }
+
+    if (Array.isArray(loadedModule.middleware)) {
+      result.push(...loadedModule.middleware);
+      continue;
+    }
+
+    // The file loaded and exports nothing the loader can apply — the same fail-open in
+    // a different disguise. `export default` is the common one: every route file in the
+    // same directory default-exports its handler, so it is the natural guess, and it
+    // used to leave the subtree open while looking exactly like a guarded one. Throwing
+    // cannot break a working app, because no shape rejected here has ever applied.
+    throw new Error(_middlewareExportError(middlewarePath, loadedModule));
   }
   return result;
 }
 
+/**
+ * The boot error for a `_middleware` file that exports nothing the loader can apply,
+ * naming the specific mistake so the message carries its own fix.
+ */
+function _middlewareExportError(
+  path: string,
+  loadedModule: MiddlewareModule & { default?: unknown },
+): string {
+  const fix = "  export const middleware = [YourMiddleware];";
+  const head = `[Zerotal] ${path} does not export a \`middleware\` array, so it guards nothing.`;
+
+  if (loadedModule.default !== undefined) {
+    return (
+      `${head}\n` +
+      `It has a \`default\` export, which this file does not use — route files ` +
+      `default-export their handler, but a _middleware file is read by name:\n${fix}`
+    );
+  }
+  if (loadedModule.middleware !== undefined) {
+    return `${head}\n\`middleware\` must be an array, even for a single entry:\n${fix}`;
+  }
+  return `${head}\nAdd the export, or delete the file if the subtree needs no middleware:\n${fix}`;
+}
+
 /**
  * Combine the stacked `_middleware.ts` chain (`base`) with a route file's own
  * `export const middleware` for a specific verb. Array form applies to every method;
@@ -366,18 +414,44 @@ async function _collectLayout(
       const layoutPath = dir
         ? join(baseDir, dir, `_layout${extension}`)
         : join(baseDir, `_layout${extension}`);
+      // No file at this spelling is the ordinary case — most directories have no
+      // layout, and the walk continues outward to find the nearest one that does.
+      if (!(await Bun.file(layoutPath).exists())) continue;
+
+      const href = pathToFileURL(layoutPath).href;
+      const importUrl = reloadId ? `${href}?t=${reloadId}` : href;
+
+      let loadedModule: { default?: unknown };
       try {
-        if (await Bun.file(layoutPath).exists()) {
-          const href = pathToFileURL(layoutPath).href;
-          const importUrl = reloadId ? `${href}?t=${reloadId}` : href;
-          const loadedModule = (await import(importUrl)) as { default?: unknown };
-          if (typeof loadedModule.default === "function") {
-            return loadedModule.default as ViewComponent;
-          }
-        }
-      } catch {
-        // A page module that fails to import is skipped — component resolution is best-effort.
+        loadedModule = (await import(importUrl)) as { default?: unknown };
+      } catch (error) {
+        // This was swallowed with the not-found case, under "component resolution is
+        // best-effort". Best-effort is right for *absence*; it is not right for a file
+        // that exists and threw. A `_layout.tsx` with a typo in it rendered every page
+        // beneath without its chrome — no error, no log, and on a hot-reload a layout
+        // that was there a moment ago. Same failure the `_middleware` loader had, one
+        // function up, minus the part where the missing thing was a guard.
+        throw new Error(
+          `[Zerotal] Failed to import ${layoutPath}: ` +
+            `${error instanceof Error ? error.message : String(error)}\n` +
+            `Pages under this directory would render without their layout, so boot ` +
+            `stops here. Fix the file, or delete it if the directory needs no layout.`,
+          { cause: error },
+        );
+      }
+
+      if (typeof loadedModule.default === "function") {
+        return loadedModule.default as ViewComponent;
       }
+
+      // The file exists and exports no component. Continuing the walk would silently
+      // hand these pages an outer directory's layout instead — plausible-looking output
+      // that is not what the file says should happen.
+      throw new Error(
+        `[Zerotal] ${layoutPath} does not default-export a component, so it lays out ` +
+          `nothing.\nA layout file is read by its default export:\n` +
+          `  export default (ctx, { children }) => \`<main>\${children}</main>\`;`,
+      );
     }
   }
   return undefined;

package/src/view/FileRouteResolver.ts

@@ -19,12 +19,36 @@ function isClass(fn: Function): boolean {
 }
 
 /**
- * Opt into rendering `.tsx`/`.jsx` file-route pages: a route file's default
- * export that is a view component (or any function tagged via the view marker)
- * is rendered to HTML, wrapped in the nearest `_layout`, and registered as a GET
- * route. Call from a provider's `onRegister()` before file routes are scanned.
+ * Opt into server-rendered file-route pages.
  *
- * @internal
+ * With this registered, a route file whose default export is a view component
+ * (or any function tagged by {@link definePage}) is rendered to HTML, wrapped in
+ * the nearest `_layout`, and registered as a `GET` route. Without it, neither
+ * happens: the default export is registered as an ordinary file handler and the
+ * `_layout` convention is switched off entirely.
+ *
+ * Call it before file routes are scanned — a provider's `onRegister()`, or
+ * `bootstrap/app.ts` before `fileBasedRouting()`:
+ *
+ * ```ts
+ * // bootstrap/app.ts
+ * import { registerViewFileRouteResolver } from "@zerotal/core/view";
+ *
+ * registerViewFileRouteResolver();
+ *
+ * export default Application.create({ providers }).fileBasedRouting({
+ *   web: basePath("app/views"),
+ * });
+ * ```
+ *
+ * **Why it is opt-in rather than on by default.** It claims every `.tsx` route
+ * file's default export, which an app using file routes for plain handlers has
+ * not asked for — and it turns on `_layout` discovery, which walks the directory
+ * tree on every scanned route. An app that wants JSX pages says so.
+ *
+ * It carried an internal marker until 1.15, which made both features unreachable
+ * through the public API while the documentation described them as automatic.
+ * The marker was wrong, not the design.
  */
 export function registerViewFileRouteResolver(): void {
   enableFileRouteLayouts();