npm - @zerotal/inertia - Versions diffs - 1.8.1 → 1.10.0 - Mend

@zerotal/inertia 1.8.1 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/CHANGELOG.md +87 -0
package/api-surface.md +0 -20
package/package.json +3 -2
package/src/global.d.ts +2 -0
package/src/inertia.ts +103 -63
package/src/pageScript.ts +65 -0
package/src/props/PropTypes.ts +2 -0
package/src/props/propBoundary.ts +161 -0
package/src/props/resolveProps.ts +5 -1
package/src/ssr/head.ts +107 -0
package/src/ssr/renderPage.ts +133 -15
package/src/types.ts +8 -4

package/CHANGELOG.md CHANGED Viewed

@@ -8,6 +8,93 @@ follows the Zerotal monorepo's unified versioning.
 ## [Unreleased]
+## [1.10.0] — 2026-08-30
+### Fixed
+- **React SSR emits the page's `<Head>` tags.** The React branch rendered the page
+  component directly — `createElement(Page, props)` — which produces correct body
+  markup and drops every `<Head>` on the page. `<Head>` renders nothing; it reports
+  its children to a head manager it reads from context, and rendering the component
+  alone puts none there. So a page that set a title, a description and an og: card
+  contributed all three to nothing, and the server sent the template's `<head>`
+  verbatim. Nothing failed and nothing logged — the page was perfect in a browser,
+  where React had run — and a link pasted into a chat was a grey rectangle with a
+  domain in it.
+  Both server-rendered paths (`inertiaStream()` and `POST /__ssr`) now render through
+  `@inertiajs/react`'s `<App>`, which installs the head manager, and splice what comes
+  back into the template's `<head>`. **React apps using SSR must have
+  `@inertiajs/react` installed** — the same adapter the browser entry point already
+  uses; a missing one is now a named error rather than a silent omission.
+- **An injected head tag replaces the template's, rather than being appended after
+  it.** This applies to Vue as well, where head injection did work: the templates all
+  ship a `<title>`, and a document with two titles is a document with the _first_
+  one. The page's tag was present, correct and ignored. A rendered `<title>` now
+  replaces the template's, and a `<meta>` replaces the one with the same `name` or
+  `property`; anything with no counterpart is appended before `</head>`.
+- **The React SSR root is marked `data-server-rendered`, and the page script comes
+  first.** The streaming branch emitted an unmarked `<div id="app">`, so the client
+  discarded the server's markup and rendered the page a second time — paying for SSR
+  and then throwing it away. `POST /__ssr` also returns the same body shape as the Vue
+  branch now (the whole Inertia root, ready to drop into a template) instead of the
+  bare component HTML.
+### Documented
+- **["What a crawler sees"](/docs/inertia/ssr#what-a-crawler-sees)** — `inertia()` does
+  not server-render the component at all, which is the normal Inertia arrangement and
+  worth saying out loud: the served document is a `<title>` and a JSON blob. The page
+  names which readers run JavaScript (browsers, search engines on a second pass) and
+  which do not (every link-preview scraper, `curl`, most reader tools), and the three
+  ways to give the second group something to read.
+## [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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/inertia",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -33,7 +33,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.8.1"
+    "@zerotal/core": "1.10.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",
@@ -60,6 +60,7 @@
     }
   },
   "devDependencies": {
+    "@inertiajs/react": "^3.7.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "typescript": "^5.8.0"

package/src/global.d.ts CHANGED Viewed

@@ -25,6 +25,8 @@ declare module 'react' {
 declare module 'react-dom/client' {
   export function createRoot(container: Element | null): { render(el: unknown): void };
+  /** Attach React to markup the server already rendered, rather than replacing it. */
+  export function hydrateRoot(container: Element, el: unknown): { render(el: unknown): void };
 }
 declare module 'react-dom/server' {

package/src/inertia.ts CHANGED Viewed

@@ -1,14 +1,18 @@
 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";
-import { resolvePageModule, renderInertiaPage } from "./ssr/renderPage.ts";
+import { resolvePageModule, renderInertiaPage, _prepareReactRender } from "./ssr/renderPage.ts";
+import { injectHead } from "./ssr/head.ts";
+import { pageScript, rootOpen, ROOT_CLOSE } from "./pageScript.ts";
 import type { PageObject } from "./types.ts";
 import type { PageTarget, RenderArgs } from "./pages.ts";
@@ -81,6 +85,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 +113,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 +149,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 +267,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();
@@ -224,38 +276,32 @@ async function _inertiaStream(component: string, props: Record<string, unknown>)
   };
   if (framework === "react") {
-    // React's stream is just the component's inner HTML, so Zerotal wraps it in
-    // the app root and serialises the pageObject into the data-page script.
-    const safeJson = JSON.stringify(pageObject)
-      .replace(/</g, "\\u003c")
-      .replace(/>/g, "\\u003e")
-      .replace(/&/g, "\\u0026")
-      .replace(/\//g, "\\/");
-    const openTag = `<div id="app">`;
-    const closeBlock = `</div>\n    <script type="application/json" data-page="app">${safeJson}</script>`;
-    // Specifiers via variables, not literals. React is an *optional* peer — a Vue
-    // app never installs it — but a literal `import("react")` is still resolved by
-    // TypeScript, so type-checking a Vue project failed on modules it will never
-    // have. Both results are cast below, so nothing is lost by hiding the
-    // specifier from the resolver; this branch only runs when the app is React.
-    const reactSpecifier = "react";
+    // React's stream is just the component's inner HTML, so Zerotal writes the SSR
+    // root around it — the `<script data-page>` first, so the client's boot payload
+    // is in the browser's hands before the component finishes arriving.
+    //
+    // The head tags cost nothing to wait for. `renderToReadableStream` already
+    // resolves only once the shell is ready, which this branch already awaited, and
+    // `<Head>` reports to the head manager synchronously during that render. So by
+    // the time there is a first byte to send, the page's title and meta are known
+    // and can go into the `<head>` that is about to be flushed.
+    const { element, head } = await _prepareReactRender(pageObject, modPath);
+    // Specifier via a variable, not a literal. `react-dom/server` is an *optional*
+    // peer — a Vue app never installs it — but a literal `import()` is still
+    // resolved by TypeScript, so type-checking a Vue project failed on a module it
+    // will never have. The result is cast below; this branch only runs on React.
     const reactServerSpecifier = "react-dom/server";
+    const serverMod = (await import(reactServerSpecifier)) as {
+      renderToReadableStream(el: unknown): Promise<ReadableStream<Uint8Array>>;
+    };
-    const [reactMod, serverMod, pageMod] = await Promise.all([
-      import(reactSpecifier) as Promise<{ createElement(type: unknown, props: unknown): unknown }>,
-      import(reactServerSpecifier) as Promise<{
-        renderToReadableStream(el: unknown): Promise<ReadableStream<Uint8Array>>;
-      }>,
-      import(modPath) as Promise<{ default: unknown }>,
-    ]);
-    const element = reactMod.createElement(pageMod.default, pageObject.props);
     const reactStream = await serverMod.renderToReadableStream(element);
+    const openBlock = injectHead(prefix, head()) + pageScript(pageObject) + rootOpen(true);
     const readable = new ReadableStream<Uint8Array>({
       async start(controller) {
-        controller.enqueue(encoder.encode(prefix + openTag));
+        controller.enqueue(encoder.encode(openBlock));
         const reader = reactStream.getReader();
         try {
           while (true) {
@@ -266,7 +312,7 @@ async function _inertiaStream(component: string, props: Record<string, unknown>)
         } finally {
           reader.releaseLock();
         }
-        controller.enqueue(encoder.encode(closeBlock + suffix));
+        controller.enqueue(encoder.encode(ROOT_CLOSE + suffix));
         controller.close();
       },
     });
@@ -275,18 +321,16 @@ async function _inertiaStream(component: string, props: Record<string, unknown>)
     return;
   }
-  // Vue: @inertiajs/vue3's SSR mode already emits the full
-  // `<div id="app" data-page="…">…</div>` root (the complete pageObject is
-  // serialised into data-page), so inject it directly in place of the
-  // placeholder — no extra app-div wrapper or data-page script. Any <Head>
-  // tags are injected into <head>.
+  // Vue: @inertiajs/vue3's SSR mode already emits the full Inertia root — the
+  // `<script data-page>` and the `<div id="app">` around the rendered component —
+  // so inject it directly in place of the placeholder. Any <Head> tags are spliced
+  // into <head>, replacing the template's own title and meta rather than being
+  // appended after them (a second <title> is a <title> the browser ignores).
   const { body, head } = await renderInertiaPage(pageObject, modPath, framework);
-  const prefixWithHead =
-    head.length > 0 ? prefix.replace("</head>", `${head.join("")}</head>`) : prefix;
   const readable = new ReadableStream<Uint8Array>({
     start(controller) {
-      controller.enqueue(encoder.encode(prefixWithHead + body + suffix));
+      controller.enqueue(encoder.encode(injectHead(prefix, head) + body + suffix));
       controller.close();
     },
   });
@@ -385,19 +429,15 @@ async function _inertia(component: string, props: Record<string, unknown>): Prom
     throw new InertiaTemplateNotLoadedError();
   }
-  // Inject pageObject into the HTML template.
-  // Escape characters that would break HTML parsing inside a script tag.
-  // </script> → <\/script>, < → <, > → >
-  const safeJson = JSON.stringify(pageObject)
-    .replace(/</g, "\\u003c")
-    .replace(/>/g, "\\u003e")
-    .replace(/&/g, "\\u0026")
-    .replace(/\//g, "\\/");
-  const html = _devBustAssets(_htmlTemplate).replace(
+  // Inject pageObject into the HTML template. The root is empty — this path does
+  // not server-render the component, so it is deliberately *not* marked
+  // `data-server-rendered`: that flag tells the client to hydrate, and hydrating an
+  // empty div is a mismatch on every page. See `inertiaStream()` for the rendered
+  // form, and the "What a crawler sees" section of the Inertia docs for what this
+  // response contains.
+  const html = _bustAssets(_htmlTemplate).replace(
     "<!-- @inertia -->",
-    `<div id="app"></div>\n    ` +
-      `<script type="application/json" data-page="app">${safeJson}</script>`,
+    `${rootOpen(false)}${ROOT_CLOSE}\n    ${pageScript(pageObject)}`,
   );
   ctx.response = new Response(html, {

package/src/pageScript.ts ADDED Viewed

@@ -0,0 +1,65 @@
+/**
+ * The `<script data-page>` tag the Inertia client boots from, and the root it
+ * mounts into.
+ *
+ * Inertia v3 reads the initial page from
+ * `script[data-page="app"][type="application/json"]` — a script tag rather than an
+ * attribute on the root div, so a large page object does not have to survive
+ * attribute escaping. This module owns that markup so the three places that emit
+ * it (`inertia()`, `inertiaStream()`, and the `/__ssr` endpoint) cannot drift
+ * apart, which is how one of them ends up with a shape the client cannot read.
+ *
+ * @module
+ */
+/** The element id the Inertia client mounts into, and the `data-page` key it looks up. */
+export const APP_ID = "app";
+/**
+ * Serialise a page object for embedding in a `<script>` block.
+ *
+ * `JSON.stringify` alone is not safe here: the payload is arbitrary application
+ * data, and a string containing `</script>` ends the block early — everything
+ * after it is parsed as HTML. Escaping `<`, `>`, `&` and `/` to their `\uXXXX`
+ * forms keeps the JSON valid (JSON.parse decodes them) while leaving nothing in
+ * the output a parser can treat as markup.
+ *
+ * @param page - The Inertia page object.
+ * @returns JSON with every character that could break out of a script block escaped.
+ */
+export function serialisePage(page: unknown): string {
+  return JSON.stringify(page)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\//g, "\\/");
+}
+/**
+ * The `<script data-page>` tag carrying the page object.
+ *
+ * @param page - The Inertia page object.
+ */
+export function pageScript(page: unknown): string {
+  return `<script type="application/json" data-page="${APP_ID}">${serialisePage(page)}</script>`;
+}
+/**
+ * The opening tag of the mount root.
+ *
+ * `data-server-rendered` is the flag Inertia's client checks to decide between
+ * hydrating the markup already on the page and throwing it away to render from
+ * scratch. It is set only when the server actually rendered the component — on an
+ * empty root it would tell the client to hydrate nothing, which React reports as a
+ * mismatch on every page.
+ *
+ * @param serverRendered - Whether the root contains server-rendered markup.
+ */
+export function rootOpen(serverRendered: boolean): string {
+  return serverRendered
+    ? `<div data-server-rendered="true" id="${APP_ID}">`
+    : `<div id="${APP_ID}">`;
+}
+/** The closing tag of the mount root. */
+export const ROOT_CLOSE = "</div>";

package/src/props/PropTypes.ts CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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/ssr/head.ts ADDED Viewed

@@ -0,0 +1,107 @@
+/**
+ * Splicing server-rendered `<Head>` tags into the template's `<head>`.
+ *
+ * Inertia's head managers hand back an array of finished HTML strings — a
+ * `<title>`, some `<meta>`, whatever the page's `<Head>` declared. Getting them
+ * into the document looks like string concatenation and is not, because the
+ * template already has a `<head>` with opinions in it.
+ *
+ * Appending is the obvious move and it is wrong. Every Zerotal template ships a
+ * `<title>`, and a document with two titles is a document with the **first** one:
+ * the app name, on every page. The tag the page rendered would be present in the
+ * markup, correct, and ignored — which is a worse failure than not injecting at
+ * all, because it looks like it worked. The same holds for
+ * `<meta name="description">` and for the `og:` pair a link preview reads.
+ *
+ * So a rendered tag *replaces* the template's tag of the same identity, and only
+ * tags with no counterpart are appended before `</head>`.
+ *
+ * @module
+ */
+/** The template's `<title>`, whatever it says. */
+const TITLE_TAG = /<title\b[^>]*>[\s\S]*?<\/title>/i;
+/**
+ * Where injected tags go. The *first* occurrence closes the head — a later one is
+ * page content (a template that documents its own markup has the literal string in
+ * a code block), and splicing there puts the title in the body.
+ */
+const HEAD_CLOSE = "</head>";
+/**
+ * The identity of a `<meta>` tag: its `name` or `property`, lowercased.
+ *
+ * These are the two attributes that make one meta tag a replacement for another —
+ * `name="description"`, `property="og:title"`. A meta with neither (`charset`,
+ * `http-equiv`) has no identity to match on and is treated as unkeyed.
+ *
+ * @param tag - A rendered `<meta …>` tag.
+ * @returns `{ attr, value }`, or `null` when the tag is not a keyed meta.
+ */
+function metaIdentity(tag: string): { attr: string; value: string } | null {
+  const match = /^<meta\b[^>]*?\s(name|property)\s*=\s*["']([^"']*)["']/i.exec(tag);
+  if (!match) return null;
+  return { attr: match[1]!.toLowerCase(), value: match[2]! };
+}
+/** Escape a string for literal use inside a RegExp. */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Inject rendered head tags into an HTML prefix, replacing what they supersede.
+ *
+ * @param prefix - The HTML up to the injection point — everything containing `<head>`.
+ * @param head - Rendered head tags, as Inertia's head manager produces them.
+ * @returns The prefix with the tags spliced in. Returned unchanged when `head` is empty.
+ *
+ * @example
+ * ```ts
+ * injectHead('<head><title>App</title></head>', ['<title>Trip to Kruger</title>']);
+ * // → '<head><title>Trip to Kruger</title></head>'
+ * ```
+ */
+export function injectHead(prefix: string, head: string[]): string {
+  if (head.length === 0) return prefix;
+  let html = prefix;
+  const appended: string[] = [];
+  for (const tag of head) {
+    if (/^<title\b/i.test(tag)) {
+      // A title always wins over the template's, and there is only ever one.
+      if (TITLE_TAG.test(html)) {
+        html = html.replace(TITLE_TAG, tag);
+      } else {
+        appended.push(tag);
+      }
+      continue;
+    }
+    const identity = metaIdentity(tag);
+    if (identity) {
+      const existing = new RegExp(
+        `<meta\\b[^>]*\\b${identity.attr}\\s*=\\s*["']${escapeRegExp(identity.value)}["'][^>]*>`,
+        "i",
+      );
+      if (existing.test(html)) {
+        html = html.replace(existing, tag);
+        continue;
+      }
+    }
+    appended.push(tag);
+  }
+  if (appended.length === 0) return html;
+  const close = html.indexOf(HEAD_CLOSE);
+  // No `</head>` is a template we cannot reason about — a fragment, or one that
+  // relies on the parser to close the head for it. Appending is still better than
+  // dropping the tags, and it lands in the same place the parser would put them.
+  if (close === -1) return html + appended.join("");
+  return html.slice(0, close) + appended.join("") + html.slice(close);
+}

package/src/ssr/renderPage.ts CHANGED Viewed

@@ -4,14 +4,33 @@
  * Inertia's SSR contract is `{ component, props, url } → { head, body }`. Pages
  * may be authored as React `.tsx` or Vue `.vue` components, so this module
  * detects the framework from the page file on disk and renders with the matching
- * runtime — React via `react-dom/server`, Vue via `@inertiajs/vue3`'s SSR mode +
- * `vue/server-renderer`.
+ * runtime — React via `@inertiajs/react` + `react-dom/server`, Vue via
+ * `@inertiajs/vue3` + `vue/server-renderer`.
  *
  * Every framework runtime is resolved from the *app's* node_modules (not
  * @zerotal/inertia's), so an app only needs the libraries for the framework it
  * actually uses. Vue `.vue` files additionally require the `.vue` runtime loader
  * registered by InertiaProvider (see `registerVueRuntimeLoader`).
+ *
+ * ## Why React goes through `<App>` rather than the page component
+ *
+ * The obvious React render is `createElement(PageComponent, props)`, and it was
+ * what this module did. It produces correct-looking body HTML and silently drops
+ * every `<Head>` tag on the page, because `<Head>` renders nothing — it reports
+ * its children to a head manager it reads from context, and nothing had put one
+ * there. A page that set a title, a description and an og: card contributed all
+ * three to a manager that did not exist, and the server sent the template's
+ * `<head>` exactly as written. Nothing failed and nothing logged; the page was
+ * perfect in a browser, where React had run, and a link pasted into a chat was a
+ * grey rectangle with a domain in it.
+ *
+ * `@inertiajs/react`'s `<App>` is what installs the head manager, and
+ * `onHeadUpdate` is the public prop it reports through. So React renders the same
+ * component tree the browser will, and the tags come back.
+ *
+ * @module
  */
+import { pageScript, rootOpen, ROOT_CLOSE } from "../pageScript.ts";
 export type Framework = "vue" | "react";
@@ -26,6 +45,22 @@ export interface SsrResult {
   body: string;
 }
+/**
+ * A React page rendered far enough to hand to a renderer, but not yet rendered.
+ *
+ * The head tags are only known *after* the element has been through
+ * `react-dom/server`, because `<Head>` reports them during render. Callers render
+ * `element`, then read `head()`. Reading it earlier is not an error, it is just
+ * empty — which is exactly the failure this shape exists to make impossible to
+ * write by accident.
+ */
+export interface PreparedReactRender {
+  /** The `<App>` element, ready for any `react-dom/server` entry point. */
+  element: unknown;
+  /** The head tags collected during the render. Empty until `element` has been rendered. */
+  head: () => string[];
+}
 /**
  * Resolve a page component's module path and which frontend framework it targets,
  * preferring a `.vue` SFC when present and falling back to `.tsx`.
@@ -51,6 +86,12 @@ export async function resolvePageModule(
  * `modPath` is an absolute path to the page module; `framework` selects the
  * rendering runtime (use {@link resolvePageModule} to derive both).
  *
+ * The `body` is the complete Inertia SSR root — the `<script data-page>` tag and
+ * the `<div id="app">` around the rendered component — for both frameworks. That
+ * is the shape the Inertia SSR contract specifies and the shape a template drops
+ * in whole; React used to return the bare component HTML instead, which is why
+ * the two branches had to be spliced differently by every caller.
+ *
  * @param page - The `{ component, props, url }` page to render.
  * @param modPath - Absolute path to the page component module.
  * @param framework - Which runtime to render with (`"vue"` or `"react"`).
@@ -98,25 +139,102 @@ async function _renderVue(page: SsrPage, modPath: string): Promise<SsrResult> {
   return { head: result.head ?? [], body: result.body };
 }
-async function _renderReact(page: SsrPage, modPath: string): Promise<SsrResult> {
+/** Minimal shape of the `@inertiajs/react` exports this module uses. */
+interface InertiaReactModule {
+  App: unknown;
+}
+/** Minimal shape of the `react` exports this module uses. */
+interface ReactModule {
+  createElement: (type: unknown, props: unknown) => unknown;
+}
+/**
+ * Build the `<App>` element for a React page and wire a head collector to it.
+ *
+ * Exported because streaming SSR needs the element rather than a string: it hands
+ * it to `renderToReadableStream` and reads the head back once the shell resolves.
+ *
+ * @param page - The `{ component, props, url }` page to render.
+ * @param modPath - Absolute path to the page component module.
+ * @returns The element and a `head()` accessor, valid after the element is rendered.
+ * @throws {@link Error} When the page module has no default export, or the app does
+ *   not install `@inertiajs/react`.
+ * @internal
+ */
+export async function _prepareReactRender(
+  page: SsrPage,
+  modPath: string,
+): Promise<PreparedReactRender> {
   const pageMod = (await import(modPath)) as { default: unknown };
-  if (typeof pageMod.default !== "function") {
+  if (pageMod.default === undefined || pageMod.default === null) {
     throw new Error(`SSR component "${page.component}" has no default export`);
   }
-  // Specifiers via variables so TypeScript does not resolve them: React is an
-  // optional peer, and a Vue app type-checking this package must not be asked
-  // for modules it will never install. Both results are cast on the next lines.
+  // Specifiers via variables so TypeScript does not resolve them: React and its
+  // Inertia adapter are *optional* peers, and a Vue app type-checking this package
+  // must not be asked for modules it will never install. Both results are cast.
   const reactSpecifier = "react";
-  const reactServerSpecifier = "react-dom/server";
+  const inertiaReactSpecifier = "@inertiajs/react";
-  const [reactMod, serverMod] = await Promise.all([
-    import(reactSpecifier) as Promise<{
-      createElement: (type: unknown, props: unknown) => unknown;
-    }>,
-    import(reactServerSpecifier) as Promise<{ renderToString: (element: unknown) => string }>,
+  const [reactMod, inertiaReact] = await Promise.all([
+    import(reactSpecifier) as Promise<ReactModule>,
+    _importInertiaReact(inertiaReactSpecifier),
   ]);
-  const element = reactMod.createElement(pageMod.default, { ...page.props, url: page.url });
-  return { head: [], body: serverMod.renderToString(element) };
+  let head: string[] = [];
+  // `<App>` owns the head manager, the page context and the layout resolution —
+  // rendering the page component alone gets the markup and none of the rest.
+  // `onHeadUpdate` is called synchronously during render on the server (Inertia's
+  // head manager only debounces in a browser), so `head` is populated by the time
+  // whichever renderer we were handed to has produced its shell.
+  const element = reactMod.createElement(inertiaReact.App, {
+    initialPage: page,
+    initialComponent: pageMod.default,
+    resolveComponent: () => pageMod.default,
+    onHeadUpdate: (elements: string[]) => {
+      head = elements;
+    },
+  });
+  return { element, head: () => head };
+}
+/**
+ * Import `@inertiajs/react`, turning "not installed" into a sentence that says what
+ * to do about it.
+ *
+ * A bare specifier rather than `Bun.resolveSync(spec, cwd)`, matching how `react`
+ * and `react-dom/server` are already loaded here. Node resolution walks up from this
+ * module, so a normal flat install finds the app's own copy — and a workspace that
+ * keeps the adapter beside the framework instead of at the app root still resolves,
+ * which the cwd form does not.
+ *
+ * The raw failure names a module path and a package, which reads like a bug in the
+ * framework rather than a missing dependency in the app — and React SSR did not need
+ * this package until `<Head>` started working, so an app upgrading into it meets the
+ * error without having changed anything of its own.
+ */
+async function _importInertiaReact(specifier: string): Promise<InertiaReactModule> {
+  try {
+    return (await import(specifier)) as InertiaReactModule;
+  } catch (err) {
+    throw new Error(
+      `Inertia SSR needs "@inertiajs/react" installed. Install it with: bun add @inertiajs/react\n` +
+        `  Cause: ${(err as Error).message ?? String(err)}`,
+    );
+  }
+}
+async function _renderReact(page: SsrPage, modPath: string): Promise<SsrResult> {
+  const { element, head } = await _prepareReactRender(page, modPath);
+  const reactServerSpecifier = "react-dom/server";
+  const serverMod = (await import(reactServerSpecifier)) as {
+    renderToString: (element: unknown) => string;
+  };
+  const html = serverMod.renderToString(element);
+  return { head: head(), body: pageScript(page) + rootOpen(true) + html + ROOT_CLOSE };
 }

package/src/types.ts CHANGED Viewed

@@ -42,12 +42,16 @@ 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;
+  htmlTemplate?: string | undefined;
   /** Current asset version string. Used for cache-busting (409 responses). */
-  version?: string;
+  version?: string | undefined;
   /** Public URL prefix for built assets. Default: '/assets' */
-  assetsUrl?: string;
+  assetsUrl?: string | undefined;
 }