@zerotal/core 1.15.0 → 1.15.1

package/CHANGELOG.md

@@ -8,6 +8,67 @@ 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**

package/api-surface.md

@@ -3783,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.15.0",
+  "version": "1.15.1",
   "license": "MIT",
   "maturity": "stable",
   "private": false,

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/router/FileRouter.ts

@@ -414,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();