@zerotal/inertia 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -8,6 +8,50 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.9.0] — 2026-08-29
+
+### Fixed
+
+- **A rebuilt bundle no longer 404s on a chunk the browser asks for.** `resources/js/app.tsx`
+  builds to `/assets/app.js` under that name every time, while `splitting: true` names each chunk
+  after its content. A rebuild therefore rewrites `app.js` to import `chunk-NEW.js` and prunes
+  `chunk-OLD.js` — and a browser holding a cached `app.js` asks for the pruned one and gets
+
+      GET /assets/chunk-hrnspqda.js  status=404
+
+  from a page that renders and a server that is healthy. Nothing in that line leads back to the
+  template.
+
+  The template hardcodes `/assets/app.js` rather than calling `asset()`, so the version token the
+  rest of the framework appends never reached it, and cache-busting had only ever been
+  implemented for `--dev-worker`. It now applies everywhere: the file's mtime in dev, where a
+  rebuild happens without a restart, and the boot-derived asset version otherwise, memoised
+  because a deploy restarts the process. An unchanged asset keeps a stable URL and stays cached,
+  which is why the token is derived rather than random.
+
+### Documented
+
+- **Every promised export is documented.** The `docs-coverage` gate reads `maturity: stable` as a
+  promise about a package's exports, and measures how much of that promise is written down. It
+  was 798 gaps across the suite; it is now zero. This package's share is covered on its own
+  pages — types named, options shapes described, and the decisions behind them recorded where
+  somebody looking for them will find them.
+
+### Added
+
+- **A warning when a model crosses into page props having declared no boundary.** Page props
+  are page source: everything handed to `inertia()` is serialised into the document, and
+  `return inertia("Trips/Show", { trip })` is what a newcomer writes on their first afternoon
+  and ships the whole row — the internal cost, the margin, the note about the customer, on
+  the customer's own screen. Nothing fails and the page looks right, which makes it the one
+  mistake here that never announces itself.
+
+  The ORM's `hidden` / `visible` lists were already honoured, since they are applied by
+  `toJSON()` and that is what serialises a prop — nothing said so. In development, passing a
+  model that declares neither list now names the model and the number of fields it is about
+  to publish. It fires once per model class and goes quiet as soon as either list exists, so
+  the normal case of passing models stays quiet.
+
 ## [1.8.0] — 2026-08-24
 
 ### Fixed

package/api-surface.md

@@ -256,12 +256,6 @@ interface InertiaDevtoolsConfig = {
 
 interface InertiaPageRegistry = {}
 
-interface InertiaProviderOptions = {
-  assetsUrl?: string
-  htmlTemplate?: string
-  version?: string
-}
-
 interface MergeConfig = {
   appendPaths: string[]
   deep: boolean
@@ -303,18 +297,6 @@ interface PaginatorLike = {
   total?: number
 }
 
-interface ResolvedPage = {
-  deepMergeProps?: string[]
-  deferredProps?: Record<string, string[]>
-  matchPropsOn?: string[]
-  mergeProps?: string[]
-  onceProps?: Record<string, {    prop: string;    expiresAt: number | null;}>
-  prependProps?: string[]
-  props: Record<string, unknown>
-  rescuedProps?: string[]
-  scrollProps?: Record<string, ScrollConfig>
-}
-
 interface ScrollConfig = {
   currentPage: number | null
   nextPage: number | null
@@ -328,8 +310,6 @@ type PageName = never
 
 type PageTarget = string
 
-type PropFactory = () => T | Promise<T>
-
 type PropInput = T | (() => T | Promise<T>) | AlwaysProp<T> | MergeProp<T> | (T extends PaginatorLike ? InfiniteScrollProp : never) | (undefined extends T ? OptionalProp<T> | DeferProp<T> : never)
 
 type PropsOf = PageComponent<N> extends (props: infer Props, ...rest: any[]) => any ? Props : PageComponent<N> extends abstract new (props: infer Props, ...rest: any[]) => any ? Props : Record<string, unknown>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/inertia",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -33,7 +33,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.8.0"
+    "@zerotal/core": "1.9.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/inertia.ts

@@ -1,10 +1,12 @@
 import { config, RequestContext } from "@zerotal/core";
+import { assetVersion as coreAssetVersion } from "@zerotal/core/assets";
 import { statSync } from "node:fs";
 import { InertiaTemplateNotLoadedError, InvalidComponentError } from "./errors.ts";
 import { DEFAULT_PAGES_DIR } from "./config.ts";
 import { sharedProps } from "./SharedProps.ts";
 import { assetVersion } from "./version.ts";
 import { resolveProps } from "./props/resolveProps.ts";
+import { checkPropBoundary } from "./props/propBoundary.ts";
 import { readHistoryFlags } from "./historyState.ts";
 import { allSharedKeys } from "./share.ts";
 import { recordPage } from "./devtools/recorder.ts";
@@ -81,6 +83,12 @@ export async function buildPageObject(
   // a no-op unless the DevTools recorder opened a recording for this request.
   recordPage(component, merged, resolved.props, resolved.rescuedProps);
 
+  // Everything below this line is page source. Last chance to say so — and the
+  // only place that sees the props as they will actually be serialised, after
+  // partial reloads and lazy wrappers have decided what is really going out.
+  // Development only; a no-op on a served request.
+  checkPropBoundary(resolved.props);
+
   const history = readHistoryFlags();
   if (history.encryptHistory) page.encryptHistory = true;
   if (history.clearHistory) page.clearHistory = true;
@@ -103,6 +111,9 @@ let _pagesDir = "";
  */
 export function _setHtmlTemplate(html: string): void {
   _htmlTemplate = html;
+  // The busted copy was derived from the previous template. Keeping it would
+  // serve the old markup for as long as the asset token happened to match.
+  _resetBustedTemplate();
 }
 
 /**
@@ -136,31 +147,70 @@ export function _getPagesDir(): string {
   return _pagesDir || `${process.cwd()}/${config.safe("inertia.pagesDir", DEFAULT_PAGES_DIR)}`;
 }
 
+/** Local `href="/…"` / `src="/…"` JS and CSS URLs that carry no query already. */
+const _LOCAL_ASSET_URL = /((?:href|src)=")(\/[^"?]+\.(?:js|css))(")/g;
+
 /**
- * In dev (`--dev-worker`) append a cache-busting `?v=<mtime>` to local JS/CSS
- * asset URLs in the served HTML, so the browser fetches a freshly-rebuilt
- * bundle instead of a stale cached copy.
+ * Append a cache-busting `?v=…` to the template's local JS/CSS URLs.
+ *
+ * **The entry point is not content-hashed and the chunks are**, which is the
+ * whole reason this exists. `app.tsx` builds to `/assets/app.js` under that name
+ * every time, while `splitting: true` names each chunk after its content — so a
+ * rebuild rewrites `app.js` to import `chunk-NEW.js` and prunes `chunk-OLD.js`.
+ * A browser holding a cached `app.js` then asks for a chunk that is no longer on
+ * disk and gets a 404, from a page that renders fine and a server that is
+ * perfectly healthy. The stack says `GET /assets/chunk-….js 404` and names
+ * nothing that would lead you here.
+ *
+ * The template hardcodes `/assets/app.js` rather than calling `asset()`, so the
+ * version token the rest of the framework appends never reached it. Two token
+ * sources, because the two runtimes invalidate at different moments:
  *
- * The token is the asset file's modification time: unchanged assets keep a
- * stable URL (and stay cached), while a rebuild changes the URL and forces a
- * re-fetch. No-op in production, where assets are served as-is.
+ * - **Dev (`--dev-worker`)**: the file's mtime, read per request. A rebuild
+ *   happens without a restart, so a token fixed at boot would be stale exactly
+ *   when it matters.
+ * - **Everywhere else**: the boot-derived asset version, memoised. A deploy
+ *   restarts the process — the pipeline says so in as many words — so the token
+ *   is computed once and reused, rather than stat-ing files on every render.
+ *
+ * Unchanged assets keep a stable URL and stay cached; that is the point of a
+ * derived token rather than a random one.
  *
  * @internal
  */
-function _devBustAssets(html: string): string {
-  if (!process.argv.includes("--dev-worker")) return html;
-  const root = `${process.cwd()}/public`;
-  return html.replace(
-    /((?:href|src)=")(\/[^"?]+\.(?:js|css))(")/g,
-    (match, pre: string, url: string, post: string) => {
+export function _bustAssets(html: string): string {
+  if (process.argv.includes("--dev-worker")) {
+    const root = `${process.cwd()}/public`;
+    return html.replace(_LOCAL_ASSET_URL, (match, pre: string, url: string, post: string) => {
       try {
         const mtime = Math.floor(statSync(`${root}${url}`).mtimeMs);
         return `${pre}${url}?v=${mtime}${post}`;
       } catch {
         return match; // asset not found under public/ — leave the URL untouched
       }
-    },
-  );
+    });
+  }
+
+  const token = coreAssetVersion();
+  // No token means nothing derived one — an app serving no built assets, or a
+  // boot order that has not reached the conventions phase. Leave the URLs alone
+  // rather than stamping `?v=` and inventing a second URL for the same file.
+  if (!token) return html;
+  if (_bustedFor === token) return _bustedHtml;
+
+  _bustedHtml = html.replace(_LOCAL_ASSET_URL, `$1$2?v=${token}$3`);
+  _bustedFor = token;
+  return _bustedHtml;
+}
+
+/** Memoised output of {@link _bustAssets}, keyed on the token it was built with. */
+let _bustedHtml = "";
+let _bustedFor = "";
+
+/** Drop the memoised template. Tests, and any caller that replaces the template. @internal */
+export function _resetBustedTemplate(): void {
+  _bustedHtml = "";
+  _bustedFor = "";
 }
 
 /**
@@ -215,7 +265,7 @@ async function _inertiaStream(component: string, props: Record<string, unknown>)
 
   const pageObject = await buildPageObject(component, props);
 
-  const [prefix = "", suffix = ""] = _devBustAssets(_htmlTemplate).split("<!-- @inertia -->");
+  const [prefix = "", suffix = ""] = _bustAssets(_htmlTemplate).split("<!-- @inertia -->");
 
   const { modPath, framework } = await resolvePageModule(_getPagesDir(), component);
   const encoder = new TextEncoder();
@@ -394,7 +444,7 @@ async function _inertia(component: string, props: Record<string, unknown>): Prom
     .replace(/&/g, "\\u0026")
     .replace(/\//g, "\\/");
 
-  const html = _devBustAssets(_htmlTemplate).replace(
+  const html = _bustAssets(_htmlTemplate).replace(
     "<!-- @inertia -->",
     `<div id="app"></div>\n    ` +
       `<script type="application/json" data-page="app">${safeJson}</script>`,

package/src/props/PropTypes.ts

@@ -14,6 +14,8 @@
  * Generic so a wrapper can carry what it will resolve to — that is what lets
  * `Inertia.render` check `defer(() => stats())` against the `stats` prop the
  * page component declares, instead of checking that *something* was passed.
+ *
+ * @internal
  */
 export type PropFactory<T = unknown> = () => T | Promise<T>;
 

package/src/props/propBoundary.ts

@@ -0,0 +1,161 @@
+/**
+ * The boundary between a model and a page prop.
+ *
+ * Inertia page props are page source. Everything handed to `inertia()` is
+ * serialised into the HTML document — or returned as JSON on an XHR visit — and
+ * anybody who views source reads all of it. That is not a leak in itself; it is
+ * how the protocol works. It becomes a leak because of what the obvious code does:
+ *
+ * ```ts
+ * return inertia("Trips/Show", { trip });   // the first thing anyone writes
+ * ```
+ *
+ * `trip` is a model, and a model serialises the row. Every column. The internal
+ * cost, the margin, the note somebody left about the customer — all of it, in the
+ * page, on the customer's own screen. Nothing fails, nothing logs, and the page
+ * looks right.
+ *
+ * The ORM already has the answer: `static hidden` and `static visible` are honoured
+ * by `toJSON()`, which is what serialises a prop. Declaring the dangerous columns
+ * once at the model is strictly better than remembering a projection at every call
+ * site. What was missing is anything that says so at the moment it matters.
+ *
+ * So this warns — in development only, once per model class — when a model reaches
+ * page props having declared neither list. Not "you passed a model", which is
+ * normal and fine, but "you passed a model that has never said which of its columns
+ * are safe to publish". A model with either list declared is silent forever after.
+ *
+ * @module
+ */
+import { deployEnv, isDevSurfaceAllowed } from "@zerotal/core";
+
+/** A value that serialises like an ORM model. */
+interface ModelLike {
+  toJSON(): unknown;
+  constructor: { name: string; hidden?: unknown; visible?: unknown };
+}
+
+/**
+ * Model classes already reported. Keyed by the class itself, so two models with the
+ * same name are two findings and a hot path never re-formats a warning nobody
+ * needs to read twice.
+ */
+const _warned = new WeakSet<object>();
+
+/** How deep to look for models inside props. */
+const MAX_DEPTH = 4;
+
+/** How many values to look at per level, so a large collection cannot cost the request. */
+const MAX_BREADTH = 50;
+
+/**
+ * How many fields a value publishes when serialised, or `null` when it is not the
+ * kind of thing this check is about.
+ *
+ * Structural, not `instanceof BaseModel`: `@zerotal/inertia` must not depend on
+ * `@zerotal/orm`, and an app can serve Inertia pages with no ORM installed at all.
+ * Three conditions together are specific enough — a class instance (not a plain
+ * object, which is already a projection), carrying its own `toJSON`, whose
+ * `toJSON` returns an object with fields in it.
+ *
+ * That last one is doing real work. `Date` is a class instance with a `toJSON`,
+ * and so are `URL` and the Temporal types; every one of them serialises to a
+ * string, and a string has no columns to leak. Requiring an object result is what
+ * separates "a row went into the page" from "a timestamp did".
+ */
+function serialisedFieldCount(value: unknown): number | null {
+  if (value === null || typeof value !== "object") return null;
+  if (Array.isArray(value)) return null;
+  const prototype = Object.getPrototypeOf(value) as object | null;
+  if (prototype === null || prototype === Object.prototype) return null;
+  if (typeof (value as { toJSON?: unknown }).toJSON !== "function") return null;
+  let json: unknown;
+  try {
+    json = (value as ModelLike).toJSON();
+  } catch {
+    // A model whose serialisation throws — an unloaded relation, most likely —
+    // has a problem this check is not the right place to report.
+    return null;
+  }
+  if (json === null || typeof json !== "object" || Array.isArray(json)) return null;
+  const fields = Object.keys(json).length;
+  return fields > 0 ? fields : null;
+}
+
+/** Whether a model's class has said anything at all about what is safe to publish. */
+function declaresBoundary(model: ModelLike): boolean {
+  const { hidden, visible } = model.constructor;
+  return (
+    (Array.isArray(hidden) && hidden.length > 0) || (Array.isArray(visible) && visible.length > 0)
+  );
+}
+
+/**
+ * The warning text. Names the model, says how much of it is about to be published,
+ * and gives the one-line fix rather than a principle.
+ */
+export function propBoundaryWarning(name: string, columns: number, propKey: string): string {
+  return (
+    `[inertia] \`${name}\` was passed as the \`${propKey}\` prop and declares neither ` +
+    `\`hidden\` nor \`visible\`, so all ${columns} of its serialised fields are written into ` +
+    `page source — readable by anyone who views source on this page.\n` +
+    `  If that is intended, say so once and this goes quiet:\n` +
+    `      static hidden: Columns<${name}>[] = ["cost_cents", "internal_notes"];\n` +
+    `      static visible: Columns<${name}>[] = ["id", "title"];   // or an allow-list\n` +
+    `  Both are honoured by toJSON(), which is what serialises this prop.`
+  );
+}
+
+/**
+ * Warn about models in page props that have never declared a boundary.
+ *
+ * Development only, and a no-op everywhere else — it walks the resolved prop tree,
+ * which is not work a served request should be doing.
+ *
+ * @param props - The resolved props, as they will be serialised.
+ * @param report - Where to write findings. Injectable for tests.
+ */
+export function checkPropBoundary(
+  props: Record<string, unknown>,
+  report: (message: string) => void = (m) => console.warn(m),
+): void {
+  if (!isDevSurfaceAllowed(deployEnv())) return;
+
+  const visit = (value: unknown, propKey: string, depth: number, seen: WeakSet<object>): void => {
+    if (depth > MAX_DEPTH || value === null || typeof value !== "object") return;
+    // Props can hold the same model twice, and a loaded relation can point back at
+    // its parent. Either would otherwise be walked forever.
+    if (seen.has(value)) return;
+    seen.add(value);
+
+    if (Array.isArray(value)) {
+      for (const item of value.slice(0, MAX_BREADTH)) visit(item, propKey, depth + 1, seen);
+      return;
+    }
+
+    const fields = serialisedFieldCount(value);
+    if (fields !== null) {
+      const model = value as ModelLike;
+      if (!declaresBoundary(model) && !_warned.has(model.constructor)) {
+        _warned.add(model.constructor);
+        report(propBoundaryWarning(model.constructor.name, fields, propKey));
+      }
+      return;
+    }
+
+    // A plain object — a paginator, a `{ data: [...] }` envelope, a hand-built
+    // projection that happens to carry a model on one key.
+    for (const nested of Object.values(value).slice(0, MAX_BREADTH)) {
+      visit(nested, propKey, depth + 1, seen);
+    }
+  };
+
+  for (const [key, value] of Object.entries(props)) {
+    visit(value, key, 0, new WeakSet<object>());
+  }
+}
+
+/** Forget every class already reported. @internal For tests. */
+export function _resetPropBoundaryWarnings(classes: object[]): void {
+  for (const cls of classes) _warned.delete(cls);
+}

package/src/props/resolveProps.ts

@@ -7,7 +7,11 @@ import {
   type ScrollConfig,
 } from "./PropTypes.ts";
 
-/** The resolved props plus the page-object metadata the client needs to merge/defer correctly. */
+/**
+ * The resolved props plus the page-object metadata the client needs to merge/defer correctly.
+ *
+ * @internal
+ */
 export interface ResolvedPage {
   props: Record<string, unknown>;
   deferredProps?: Record<string, string[]>;

package/src/types.ts

@@ -42,7 +42,11 @@ export interface PageObject {
   sharedProps?: string[];
 }
 
-/** Options passed to `InertiaProvider` to configure the adapter at boot. */
+/**
+ * Options passed to `InertiaProvider` to configure the adapter at boot.
+ *
+ * @internal
+ */
 export interface InertiaProviderOptions {
   /** Path to the HTML template. Default: 'resources/app.html' */
   htmlTemplate?: string;