npm - @zerotal/inertia - Versions diffs - 1.9.0 → 1.11.0 - Mend

@zerotal/inertia 1.9.0 → 1.11.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 (11) hide show

package/CHANGELOG.md +78 -0
package/api-surface.md +10 -0
package/package.json +5 -3
package/src/commands/InertiaBuildCommand.ts +14 -0
package/src/global.d.ts +2 -0
package/src/inertia.ts +37 -47
package/src/pageScript.ts +65 -0
package/src/ssr/head.ts +107 -0
package/src/ssr/renderPage.ts +170 -15
package/src/testing.ts +97 -0
package/src/types.ts +3 -3

package/CHANGELOG.md CHANGED Viewed

@@ -8,6 +8,84 @@ follows the Zerotal monorepo's unified versioning.
 ## [Unreleased]
+## [1.11.0] — 2026-08-31
+### Added
+- **`@zerotal/inertia/testing` — `renderPage()`.** `assertInertia("home")` proves the
+  _server_ named a component and handed it props. It proves nothing about the
+  component, and a page can throw on its first paint while every such test passes: the
+  route answers `200`, the payload is correct, and the failure happens in a browser
+  the suite never opened. An app shipped a blank page to production with **614 passing
+  tests** exactly that way — a layout callback read `page.props`, which the callback
+  is not given.
+  `renderPage(Component, props, { shared })` builds the tree through Inertia's own
+  `<App>`, so `usePage()`, `<Head>` and a persistent layout all behave as they do in
+  the browser, and lets whatever it throws escape. It is not a DOM — `useEffect` does
+  not run — which is the point: it proves the tree _builds_, which is what nothing
+  else checked.
+### Documented
+- **[Persistent layouts](/docs/inertia/rendering#persistent-layouts)**, which this
+  package documented nowhere — not in the README, not in `api-surface.md`. The
+  callback is handed the page **element**, not the page props, so the natural
+  `(page) => <Layout search={page.props.search}>{page}</Layout>` throws on the first
+  paint and only in a browser. The page now shows the `usePage()` form and says why
+  the wrong one typechecks.
+### Fixed
+- **`zt inertia:build` fails when it produces nothing.** A build could report success
+  with zero artefacts, and that is the shape that reaches production: the deploy sees
+  exit 0, restarts, and serves a page with no script and no stylesheet. The health
+  check passes — the server is fine and the HTML is fine, there is just nothing in
+  it. An app had to assert the files exist in its own deploy script to catch it.
+## [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

package/api-surface.md CHANGED Viewed

@@ -319,3 +319,13 @@ type RenderArgs = [props?: Record<string, unknown>]
 type RenderProps = {    [x: string]: unknown;}
 type RouteTable = Readonly<Record<string, string>> | ReadonlyMap<string, string>
+## ./testing  `(./src/testing.ts)`
+function renderPage = (component: unknown, props?: Record<string, unknown>, options?: RenderPageOptions) => Promise<string>
+interface RenderPageOptions = {
+  component?: string | undefined
+  shared?: Record<string, unknown> | undefined
+  url?: string | undefined
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/inertia",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -8,7 +8,8 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./testing": "./src/testing.ts"
   },
   "files": [
     "CHANGELOG.md",
@@ -33,7 +34,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.9.0"
+    "@zerotal/core": "1.11.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",
@@ -60,6 +61,7 @@
     }
   },
   "devDependencies": {
+    "@inertiajs/react": "^3.7.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "typescript": "^5.8.0"

package/src/commands/InertiaBuildCommand.ts CHANGED Viewed

@@ -79,6 +79,20 @@ export class InertiaBuildCommand extends Command {
       throw new Error("Frontend build failed.");
     }
+    // `success` with no artefacts is not a build, and it is the shape that reaches
+    // production: a deploy runs this, sees exit 0, restarts, and serves a page with
+    // no script and no stylesheet. The health check passes — the server is fine, the
+    // HTML is fine, there is simply nothing in it. An app had to assert the files
+    // exist in its own deploy script to catch it, which is the framework's job.
+    if (result.outputs.length === 0) {
+      throw new Error(
+        `Frontend build reported success and produced no files ` +
+          `(entry point: resources/js/app.tsx). An empty output directory serves a ` +
+          `page with no script and no stylesheet, which a health check cannot tell ` +
+          `from a working one.`,
+      );
+    }
     // Chunks are named after their content, so the ones this build replaced
     // would otherwise stay behind — and ship.
     //

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

@@ -10,7 +10,9 @@ 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";
@@ -274,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) {
@@ -316,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();
       },
     });
@@ -325,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();
     },
   });
@@ -435,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, "\\/");
+  // 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/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,139 @@ 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) };
+  return _elementFor(reactMod, inertiaReact, page, pageMod.default);
+}
+/**
+ * Wrap an already-resolved page component in Inertia's `<App>`.
+ *
+ * Split out so a test can render a component it imported directly, without a pages
+ * directory or a module path — see `@zerotal/inertia/testing`.
+ *
+ * @internal
+ */
+function _elementFor(
+  reactMod: ReactModule,
+  inertiaReact: InertiaReactModule,
+  page: SsrPage,
+  component: unknown,
+): PreparedReactRender {
+  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: component,
+    resolveComponent: () => component,
+    onHeadUpdate: (elements: string[]) => {
+      head = elements;
+    },
+  });
+  return { element, head: () => head };
+}
+/**
+ * Build the `<App>` element for a component the caller already has.
+ *
+ * @param page - The `{ component, props, url }` page to render.
+ * @param component - The page component itself.
+ * @internal
+ */
+export async function _prepareComponentRender(
+  page: SsrPage,
+  component: unknown,
+): Promise<PreparedReactRender> {
+  const reactSpecifier = "react";
+  const inertiaReactSpecifier = "@inertiajs/react";
+  const [reactMod, inertiaReact] = await Promise.all([
+    import(reactSpecifier) as Promise<ReactModule>,
+    _importInertiaReact(inertiaReactSpecifier),
+  ]);
+  return _elementFor(reactMod, inertiaReact, page, component);
+}
+/**
+ * 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/testing.ts ADDED Viewed

@@ -0,0 +1,97 @@
+/**
+ * `@zerotal/inertia/testing` — render a page component the way a browser will.
+ *
+ * ## The gap this fills
+ *
+ * `assertInertia("home")` proves the *server* named a component and handed it props.
+ * It proves nothing about the component. A page can throw on its first paint — a
+ * destructured prop that is not there, a layout callback reading `page.props` that
+ * the callback never receives — and the route still answers `200` with a correct
+ * payload, because the throw happens in a browser that the test never opened.
+ *
+ * An app shipped a blank `/mail` to production with **614 passing tests**. Every one
+ * of them asserted a value or a status code. The console said
+ * `Cannot read properties of undefined (reading 'search')`, from a layout callback,
+ * on a page whose Inertia payload was perfect.
+ *
+ * {@link renderPage} proves one thing and one thing only: that the component tree
+ * can be built without throwing. That is precisely the thing nothing else checks,
+ * and it is about forty lines an app should not have to write.
+ *
+ * ## What it does not do
+ *
+ * It is not a DOM. Nothing here clicks, and `useEffect` does not run — this is
+ * `renderToString`, so it exercises the render pass. For assertions about behaviour
+ * after paint, use the browser harness in `@zerotal/testing/browser`.
+ *
+ * @example
+ * ```ts
+ * import { renderPage } from "@zerotal/inertia/testing";
+ * import Home from "../resources/js/pages/home.tsx";
+ *
+ * test("home renders", async () => {
+ *   await renderPage(Home, { title: "Hello" });
+ * });
+ * ```
+ *
+ * @module
+ */
+import { _prepareComponentRender } from "./ssr/renderPage.ts";
+/** Extras a page render may need beyond its own props. */
+export interface RenderPageOptions {
+  /**
+   * Shared props the app's `Inertia.share()` would have added — `auth`, `flash`,
+   * `errors`, and anything else a layout reads. A page that destructures one of
+   * these throws without it, which is a real failure but rarely the one you are
+   * testing for, so seed the shape your app actually shares.
+   */
+  shared?: Record<string, unknown> | undefined;
+  /** The URL the page believes it is at. Some layouts branch on it. Default `"/"`. */
+  url?: string | undefined;
+  /** The component name recorded in the page object. Default `"page"`. */
+  component?: string | undefined;
+}
+/**
+ * Render an Inertia page component to HTML, throwing whatever it throws.
+ *
+ * Renders through `@inertiajs/react`'s own `<App>`, so `usePage()`, `<Head>` and a
+ * persistent layout all behave as they do in the browser — a layout attached with
+ * `Page.layout` is resolved and rendered too, which is the case worth catching.
+ *
+ * @param component - The page component, imported directly.
+ * @param props - The props the server would send. Merged over `options.shared`.
+ * @param options - Shared props, URL and component name.
+ * @returns The rendered HTML, for a `toContain` if you want one.
+ * @throws Whatever the component throws, unchanged — the point is that it surfaces.
+ *
+ * @example
+ * ```ts
+ * const html = await renderPage(Profile, { user }, { shared: { auth: { user } } });
+ * expect(html).toContain(user.name);
+ * ```
+ */
+export async function renderPage(
+  component: unknown,
+  props: Record<string, unknown> = {},
+  options: RenderPageOptions = {},
+): Promise<string> {
+  const page = {
+    component: options.component ?? "page",
+    props: { ...(options.shared ?? {}), ...props },
+    url: options.url ?? "/",
+    version: "test",
+  };
+  const { element } = await _prepareComponentRender(page, component);
+  // Specifier via a variable: `react-dom/server` is an optional peer, and a Vue app
+  // type-checking this package must not be asked for a module it will never install.
+  const reactServerSpecifier = "react-dom/server";
+  const serverMod = (await import(reactServerSpecifier)) as {
+    renderToString: (element: unknown) => string;
+  };
+  return serverMod.renderToString(element);
+}

package/src/types.ts CHANGED Viewed

@@ -49,9 +49,9 @@ export interface PageObject {
  */
 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;
 }