@dokebi/template-inertia 0.1.3 → 0.4.0

package/dist/props.js

@@ -1,3 +1,4 @@
+import { InertiaUsageError } from './errors.js';
 const BRAND = Symbol.for('dokebi.template-inertia.prop');
 /**
  * A prop value with Inertia protocol behaviour (D-0052), made by `defer`, `merge`, `deepMerge` or
@@ -30,7 +31,7 @@ export function isInertiaProp(value) {
 const NAME = /^[^,\s]{1,128}$/;
 function checkValue(value, helper) {
     if (value === undefined || isInertiaProp(value))
-        throw new TypeError(`${helper}() takes a JSON value or a function, not ${String(value)}`);
+        throw new InertiaUsageError('INVALID_PROP_HELPER', `${helper}() takes a JSON value or a function, not ${String(value)}`);
     return value;
 }
 function mergeSettings(options) {
@@ -40,7 +41,7 @@ function mergeSettings(options) {
         !['append', 'prepend', 'deep'].includes(mode) ||
         !Array.isArray(fields) ||
         fields.some((field) => typeof field !== 'string' || !NAME.test(field)))
-        throw new TypeError('Invalid Inertia merge options');
+        throw new InertiaUsageError('INVALID_PROP_HELPER', 'Invalid Inertia merge options');
     return Object.freeze({ mode, matchOn: Object.freeze([...fields]) });
 }
 function onceSettings(options) {
@@ -48,7 +49,7 @@ function onceSettings(options) {
     if (Object.keys(rest).length ||
         (key !== undefined && (typeof key !== 'string' || !NAME.test(key))) ||
         (ttlMs !== undefined && !(typeof ttlMs === 'number' && Number.isFinite(ttlMs) && ttlMs > 0)))
-        throw new TypeError('Invalid Inertia once options');
+        throw new InertiaUsageError('INVALID_PROP_HELPER', 'Invalid Inertia once options');
     return Object.freeze({ key, ttlMs });
 }
 /**
@@ -57,14 +58,14 @@ function onceSettings(options) {
  */
 export function defer(fn, options) {
     if (typeof fn !== 'function')
-        throw new TypeError('defer() takes a function');
+        throw new InertiaUsageError('INVALID_PROP_HELPER', 'defer() takes a function');
     const settings = typeof options === 'string' ? { group: options } : (options ?? {});
     const { group = 'default', merge, once, rescue = false, ...rest } = settings;
     if (Object.keys(rest).length ||
         typeof group !== 'string' ||
         !NAME.test(group) ||
         typeof rescue !== 'boolean')
-        throw new TypeError('Invalid Inertia defer options');
+        throw new InertiaUsageError('INVALID_PROP_HELPER', 'Invalid Inertia defer options');
     return new InertiaProp(fn, group, merge === undefined ? undefined : mergeSettings(merge), once === undefined ? undefined : onceSettings(once), rescue);
 }
 /** A prop the client merges into the value it holds on partial reloads (pagination, feeds). */

package/dist/responder.d.ts

@@ -1,7 +1,8 @@
 import type { Awaitable, Logger } from '@dokebi/core';
+import { diagnostics } from '@dokebi/core/libraries';
+import type { WebErrorResponse } from '@dokebi/web';
 import type { FastifyReply, FastifyRequest } from 'fastify';
 import { type InertiaProp } from './props.js';
-import { type Repeats } from './repeats.js';
 export type Json = null | boolean | number | string | readonly Json[] | {
     readonly [key: string]: Json;
 };
@@ -13,6 +14,44 @@ export interface InertiaOptions {
     title?: string;
     scripts?: readonly string[];
     styles?: readonly string[];
+    /**
+     * Inertia history encryption of the pages (D-0062): `true`, `false`, or `'sealed'` (default):
+     * on for sealed requests (seal hosts), so props kept in the browser history are encrypted too.
+     */
+    encryptHistory?: boolean | 'sealed';
+    /**
+     * The page component of error answers (D-0074), rendered with `{ status, error, message,
+     * hint }` (and `fix` while developing) for Inertia visits and full page loads; `false` or
+     * unset: JSON for visits, dokebi-web's small HTML page for page loads.
+     */
+    errorPage?: string | false;
+}
+/** What `answerError` reads of a dokebi-web error answer (`WebErrorResponse`). */
+export type InertiaErrorResponse = Pick<WebErrorResponse, 'request' | 'reply' | 'status' | 'body' | 'format' | 'sealed'>;
+/** Per response history settings; unset values come from the scope (`encryptHistory`) and session. */
+export interface InertiaRenderOptions {
+    /** Encrypt this page in the browser history (Inertia `encryptHistory`). */
+    readonly encryptHistory?: boolean;
+    /**
+     * Clear the encrypted history before showing this page. Unset: true for the first page after
+     * the session was destroyed or regenerated (@dokebi/session 0.2 `historyReset`, logout, login).
+     */
+    readonly clearHistory?: boolean;
+}
+/**
+ * What the plugin gives a responder besides its options: the sealing of a request (dokebi-web
+ * `sealOf`) and the session's history reset signal.
+ */
+export interface InertiaHooks {
+    readonly sealOf?: (request: FastifyRequest) => {
+        encode(text: string): string;
+    } | undefined;
+    readonly historyReset?: (request: FastifyRequest) => Promise<boolean>;
+    /**
+     * The validation redirect of an Inertia request (D-0074 §3): flashes `errors` (and `old`) in
+     * the session and answers 303 back; false when the request has no session or no way back.
+     */
+    readonly validation?: (request: FastifyRequest, reply: FastifyReply, errors: Readonly<Record<string, string>>) => Promise<boolean>;
 }
 /** The page object Inertia hands to the client and to the SSR bundle. */
 export interface InertiaPage {
@@ -48,7 +87,7 @@ export type InertiaFlash = (request: FastifyRequest) => Promise<Record<string, J
 /** Where the responder reports prop evaluation (debug) and rescued prop failures (error). */
 export interface InertiaDiagnostics {
     readonly logger: Logger;
-    readonly repeats: Repeats;
+    readonly repeats: InstanceType<typeof diagnostics.Repeats>;
 }
 /** What an SSR bundle's `render(page)` returns: head tags and the root (script + element). */
 export interface InertiaSsrResult {
@@ -66,10 +105,17 @@ export interface InertiaSsr {
     readonly failed?: (error: unknown, component: string) => void;
 }
 export interface InertiaApi {
-    render(request: FastifyRequest, reply: FastifyReply, component: string, props?: Props): Promise<FastifyReply>;
+    render(request: FastifyRequest, reply: FastifyReply, component: string, props?: Props, options?: InertiaRenderOptions): Promise<FastifyReply>;
     redirect(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply;
     location(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply;
+    /**
+     * Answers an error of this scope's requests (D-0074 §3; dokebi-app and the plugin call it from
+     * dokebi-web's error responders): the validation redirect, or the `errorPage` component.
+     * Resolves to false when it wrote nothing.
+     */
+    answerError(response: InertiaErrorResponse): Promise<boolean>;
 }
+export declare function vary(reply: FastifyReply): void;
 export type NormalizedInertiaOptions = Readonly<Required<InertiaOptions>>;
 /** Validates and fills defaults; the result is accepted again unchanged. */
 export declare function normalizeInertiaOptions(options?: InertiaOptions): NormalizedInertiaOptions;
@@ -79,10 +125,18 @@ export declare class InertiaResponder implements InertiaApi {
     readonly ssr?: InertiaSsr | undefined;
     readonly diagnostics?: InertiaDiagnostics | undefined;
     readonly flash?: InertiaFlash | undefined;
+    readonly hooks: InertiaHooks;
     readonly options: NormalizedInertiaOptions;
-    constructor(options?: InertiaOptions, shared?: ((request: FastifyRequest) => Awaitable<Props>) | undefined, ssr?: InertiaSsr | undefined, diagnostics?: InertiaDiagnostics | undefined, flash?: InertiaFlash | undefined);
+    constructor(options?: InertiaOptions, shared?: ((request: FastifyRequest) => Awaitable<Props>) | undefined, ssr?: InertiaSsr | undefined, diagnostics?: InertiaDiagnostics | undefined, flash?: InertiaFlash | undefined, hooks?: InertiaHooks);
     close(): void;
-    render(request: FastifyRequest, reply: FastifyReply, component: string, input?: Props): Promise<never>;
+    render(request: FastifyRequest, reply: FastifyReply, component: string, input?: Props, history?: InertiaRenderOptions): Promise<never>;
+    /**
+     * The error answer of an Inertia request or page load (D-0074 §3), for dokebi-web's error
+     * responders: the validation redirect (an Inertia request refused with 422 VALIDATION_FAILED,
+     * with a session), then the `errorPage` component. False leaves the answer to dokebi-web (JSON
+     * for visits, a small HTML page for page loads).
+     */
+    answerError(response: InertiaErrorResponse): Promise<boolean>;
     redirect(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply<import("fastify").RouteGenericInterface, import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>;
     location(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply<import("fastify").RouteGenericInterface, import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>;
 }

package/dist/responder.js

@@ -1,15 +1,16 @@
+import { diagnostics } from '@dokebi/core/libraries';
+import { InertiaError, InertiaUsageError } from './errors.js';
 import { isInertiaProp } from './props.js';
-import { errorText } from './repeats.js';
 const escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char] ?? char);
 function localUrl(value) {
     if (typeof value !== 'string' ||
         !value.startsWith('/') ||
         value.startsWith('//') ||
         [...value].some((char) => char === '\\' || char.charCodeAt(0) <= 32))
-        throw new TypeError('Expected a local absolute URL');
+        throw new InertiaUsageError('INVALID_URL', 'Expected a local absolute URL');
     return value;
 }
-function vary(reply) {
+export function vary(reply) {
     const values = String(reply.getHeader('vary') ?? '')
         .split(',')
         .map((value) => value.trim())
@@ -20,17 +21,31 @@ function vary(reply) {
     // Page props may contain user-specific state, including on version mismatch responses.
     reply.header('Cache-Control', 'no-store');
 }
+/** A page component name: `Error`, `Pages/Error`. */
+function validComponent(component) {
+    return (typeof component === 'string' &&
+        component.length <= 256 &&
+        component.split('/').every((part) => /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(part)));
+}
 /** Validates and fills defaults; the result is accepted again unchanged. */
 export function normalizeInertiaOptions(options = {}) {
     if (!options ||
         typeof options !== 'object' ||
         Array.isArray(options) ||
-        Object.keys(options).some((key) => !['version', 'rootId', 'title', 'scripts', 'styles'].includes(key)))
-        throw new TypeError('Invalid Inertia options');
+        Object.keys(options).some((key) => ![
+            'version',
+            'rootId',
+            'title',
+            'scripts',
+            'styles',
+            'encryptHistory',
+            'errorPage',
+        ].includes(key)))
+        throw new InertiaUsageError('INVALID_SCOPE', 'Invalid Inertia options');
     for (const assets of [options.scripts, options.styles]) {
         if (assets !== undefined &&
             (!Array.isArray(assets) || assets.some((asset) => typeof asset !== 'string')))
-            throw new TypeError('Assets must be arrays of URLs');
+            throw new InertiaUsageError('INVALID_SCOPE', 'Assets must be arrays of URLs');
     }
     const normalized = {
         version: options.version ?? 'development',
@@ -38,28 +53,79 @@ export function normalizeInertiaOptions(options = {}) {
         title: options.title ?? '',
         scripts: Object.freeze([...(options.scripts ?? [])]),
         styles: Object.freeze([...(options.styles ?? [])]),
+        encryptHistory: options.encryptHistory ?? 'sealed',
+        errorPage: options.errorPage ?? false,
     };
     if (typeof normalized.version !== 'string' ||
         typeof normalized.title !== 'string' ||
         typeof normalized.rootId !== 'string' ||
-        !/^[A-Za-z][A-Za-z0-9_-]*$/.test(normalized.rootId))
-        throw new TypeError('Invalid Inertia document settings');
+        !/^[A-Za-z][A-Za-z0-9_-]*$/.test(normalized.rootId) ||
+        (typeof normalized.encryptHistory !== 'boolean' && normalized.encryptHistory !== 'sealed') ||
+        (normalized.errorPage !== false && !validComponent(normalized.errorPage)))
+        throw new InertiaUsageError('INVALID_SCOPE', 'Invalid Inertia document settings');
     for (const asset of [...normalized.scripts, ...normalized.styles])
         localUrl(asset);
     return Object.freeze(normalized);
 }
+const UNSUPPORTED = 'Page props must be JSON serializable';
+/**
+ * Fails on a value JSON.stringify would drop or change silently (undefined, a function, a
+ * symbol, NaN or ±Infinity; a BigInt or a cycle fails in stringify itself). A plain walk before
+ * a stringify without replacer: a replacer takes V8 off its fast path (4.8× the stringify time
+ * for a 30 KB page, D-0068). Objects with toJSON are checked as what toJSON returns.
+ */
+function checkJson(value, depth) {
+    if (depth > 512)
+        return; // deeper than this is a cycle or abuse; stringify reports it
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++)
+            checkValue(value[index], index, depth);
+        return;
+    }
+    const object = value;
+    for (const key in object)
+        if (Object.hasOwn(object, key))
+            checkValue(object[key], key, depth);
+}
+function checkValue(value, key, depth) {
+    const type = typeof value;
+    if (type === 'string' || type === 'boolean')
+        return;
+    if (type === 'number') {
+        if (Number.isFinite(value))
+            return;
+    }
+    else if (type === 'object') {
+        if (value === null)
+            return;
+        const json = value.toJSON;
+        if (typeof json === 'function')
+            checkValue(json.call(value, String(key)), key, depth);
+        else
+            checkJson(value, depth + 1);
+        return;
+    }
+    throw new InertiaUsageError('INVALID_PROPS', UNSUPPORTED);
+}
 export class InertiaResponder {
     shared;
     ssr;
     diagnostics;
     flash;
+    hooks;
     options;
+    /**
+     * Every value of a page is checked outside production (where the mistake is made and seen);
+     * in production only the top-level props are, and the page goes to JSON.stringify as it is.
+     */
+    #deepCheck = process.env.NODE_ENV !== 'production';
     #closed = false;
-    constructor(options = {}, shared, ssr, diagnostics, flash) {
+    constructor(options = {}, shared, ssr, diagnostics, flash, hooks = {}) {
         this.shared = shared;
         this.ssr = ssr;
         this.diagnostics = diagnostics;
         this.flash = flash;
+        this.hooks = hooks;
         this.options = normalizeInertiaOptions(options);
     }
     close() {
@@ -67,16 +133,66 @@ export class InertiaResponder {
     }
     #check() {
         if (this.#closed)
-            throw new Error('Inertia responder is closed');
+            throw new InertiaError('CLOSED', 'Inertia responder is closed');
     }
-    async render(request, reply, component, input = {}) {
+    async render(request, reply, component, input = {}, history = {}) {
         this.#check();
+        if (history === null ||
+            typeof history !== 'object' ||
+            (history.encryptHistory !== undefined && typeof history.encryptHistory !== 'boolean') ||
+            (history.clearHistory !== undefined && typeof history.clearHistory !== 'boolean'))
+            throw new InertiaUsageError('INVALID_RENDER', 'Inertia render options are { encryptHistory?, clearHistory? } booleans');
         if (!['GET', 'HEAD'].includes(request.method))
-            throw new Error('Render pages using GET/HEAD; redirect mutations or use REST');
-        if (typeof component !== 'string' ||
-            component.length > 256 ||
-            !component.split('/').every((part) => /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(part)))
-            throw new TypeError('Invalid page component');
+            throw new InertiaError('METHOD_NOT_ALLOWED', 'Render pages using GET/HEAD; redirect mutations or use REST');
+        if (!validComponent(component))
+            throw new InertiaUsageError('INVALID_RENDER', 'Invalid page component');
+        return this.#page(request, reply, component, input, history, true);
+    }
+    /**
+     * The error answer of an Inertia request or page load (D-0074 §3), for dokebi-web's error
+     * responders: the validation redirect (an Inertia request refused with 422 VALIDATION_FAILED,
+     * with a session), then the `errorPage` component. False leaves the answer to dokebi-web (JSON
+     * for visits, a small HTML page for page loads).
+     */
+    async answerError(response) {
+        if (this.#closed)
+            return false;
+        const { request, reply, status, body } = response;
+        const inertia = request.headers['x-inertia'] === 'true';
+        const validation = body.error === 'VALIDATION_FAILED' &&
+            body.errors !== null &&
+            typeof body.errors === 'object' &&
+            !Array.isArray(body.errors);
+        if (inertia && validation && this.hooks.validation) {
+            if (await this.hooks.validation(request, reply, body.errors))
+                return true;
+            // No session or no way back: the 422 JSON with `errors` (onHttpException reads it).
+            return false;
+        }
+        const component = this.options.errorPage;
+        if (component === false || validation)
+            return false;
+        const accept = request.headers.accept;
+        // A page load (GET) of a sealed host is a page too: the error page leaves sealed like any.
+        const pageLoad = response.format === 'html' ||
+            (response.sealed &&
+                ['GET', 'HEAD'].includes(request.method) &&
+                typeof accept === 'string' &&
+                accept.includes('text/html'));
+        if (!inertia && !pageLoad)
+            return false;
+        const text = (value) => (typeof value === 'string' ? value : null);
+        reply.code(status);
+        await this.#page(request, reply, component, {
+            status,
+            error: body.error,
+            message: text(body.message),
+            hint: text(body.hint),
+            ...(typeof body.fix === 'string' ? { fix: body.fix } : {}),
+        }, {}, false);
+        return true;
+    }
+    async #page(request, reply, component, input, history, session) {
         vary(reply);
         const inertia = request.headers['x-inertia'] === 'true';
         if (inertia &&
@@ -88,6 +204,10 @@ export class InertiaResponder {
                 .header('X-Inertia-Version', this.options.version)
                 .send();
         }
+        // A sealed request (seal host, D-0062): the props leave as one sealed frame, never as HTML.
+        const sealer = this.hooks.sealOf?.(request);
+        if (sealer && this.ssr && !inertia)
+            throw new InertiaError('SEAL_SSR_CONFLICT', 'A sealed page cannot be server rendered: SSR writes the props as plain HTML. Turn off ssr for this app or seal for its hosts.');
         const props = { ...(await this.shared?.(request)), ...input };
         const partial = inertia && request.headers['x-inertia-partial-component'] === component;
         const list = (key) => typeof request.headers[key] === 'string'
@@ -109,14 +229,47 @@ export class InertiaResponder {
                 return isInertiaProp(value) && value.group !== undefined;
             });
         const values = await Promise.all(meta.selected.map(([key, value, prop]) => this.#evaluate(component, key, value, prop, meta.rescued)));
-        // Read after the props: a failed render leaves the flash for the next page.
-        const flash = this.flash && !deferredFetch ? await this.flash(request) : undefined;
-        const resolved = Object.create(null);
-        resolved.errors = {};
+        // Read after the props: a failed render leaves the flash for the next page. An error page
+        // leaves it (and the history reset) for the page the user goes to next.
+        const flash = this.flash && session && !deferredFetch ? await this.flash(request) : undefined;
+        // Read like the flash: once, by the page that shows it (logout or login happened before).
+        const clearHistory = history.clearHistory ??
+            (this.hooks.historyReset && session && !deferredFetch
+                ? await this.hooks.historyReset(request)
+                : false);
+        const configured = this.options.encryptHistory;
+        const encryptHistory = history.encryptHistory ?? (configured === 'sealed' ? sealer !== undefined : configured);
+        // An ordinary object: JSON.stringify of a null-prototype object leaves V8's fast path (2×
+        // slower for a 30 KB page, D-0068). `__proto__` is defined as an own key, never assigned.
+        const resolved = { errors: {} };
         meta.selected.forEach(([key], index) => {
-            if (values[index] !== RESCUED)
+            if (values[index] === RESCUED)
+                return;
+            if (key === '__proto__')
+                Object.defineProperty(resolved, key, {
+                    value: values[index],
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
+            else
                 resolved[key] = values[index];
         });
+        // D-0074 §3: the `errors` of a validation redirect become the `errors` prop of this page
+        // (under errors the handler passed itself); the rest of the flash (`old`, notices) stays flash.
+        let pageFlash = flash;
+        const flashed = flash?.errors;
+        if (flash && flashed !== undefined) {
+            const { errors: _taken, ...rest } = flash;
+            pageFlash = rest;
+            if (flashed !== null && typeof flashed === 'object' && !Array.isArray(flashed)) {
+                const own = resolved.errors;
+                resolved.errors =
+                    own !== null && typeof own === 'object' && !Array.isArray(own)
+                        ? { ...flashed, ...own }
+                        : flashed;
+            }
+        }
         const logger = this.diagnostics?.logger;
         if (logger?.isEnabled('debug') && (meta.lazy.length || meta.announced))
             logger.log('debug', 'Inertia props resolved', {
@@ -132,25 +285,43 @@ export class InertiaResponder {
             props: resolved,
             url: request.url,
             version: this.options.version,
-            clearHistory: false,
-            encryptHistory: false,
+            clearHistory,
+            encryptHistory,
             ...meta.page,
             ...(meta.rescued.length ? { rescuedProps: meta.rescued } : {}),
-            ...(flash && Object.keys(flash).length ? { flash } : {}),
+            ...(pageFlash && Object.keys(pageFlash).length ? { flash: pageFlash } : {}),
         };
-        // Reject unsupported values rather than silently dropping application data.
-        const json = JSON.stringify(page, (_key, value) => {
-            if (value === undefined ||
-                typeof value === 'function' ||
-                typeof value === 'symbol' ||
-                typeof value === 'bigint' ||
-                (typeof value === 'number' && !Number.isFinite(value)))
-                throw new TypeError('Page props must be JSON serializable');
-            return value;
-        });
+        // Reject unsupported values rather than silently dropping application data (D-0047).
+        if (this.#deepCheck)
+            checkJson(page, 0);
+        else
+            for (const key in resolved) {
+                // Shallow: a missing (undefined) or non-JSON top-level prop, the usual mistake.
+                const value = resolved[key];
+                if (value === null || typeof value === 'object')
+                    continue;
+                checkValue(value, key, 1);
+            }
+        const json = JSON.stringify(page);
+        if (logger?.isEnabled('debug') && (sealer || clearHistory))
+            logger.log('debug', 'Inertia page history and seal', {
+                component,
+                sealed: sealer !== undefined,
+                encryptHistory,
+                clearHistory,
+            });
+        // The XHR answer is JSON: dokebi-web seals it on the way out for a sealed request.
         if (inertia)
             return reply.header('X-Inertia', 'true').type('application/json; charset=utf-8').send(json);
         const { rootId, title, scripts, styles } = this.options;
+        if (sealer) {
+            // `E:<ts>:<base64>` holds no HTML specials; the client opens it before Inertia starts
+            // (`sealInertia` of @dokebi/seal/http). No SSR here (refused above).
+            const frame = sealer.encode(json);
+            return reply
+                .type('text/html; charset=utf-8')
+                .send(`<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escapeHtml(title)}</title>${styles.map((url) => `<link rel="stylesheet" href="${escapeHtml(url)}">`).join('')}${scripts.map((url) => `<script type="module" src="${escapeHtml(url)}"></script>`).join('')}</head><body><script data-page="${rootId}" type="application/json" data-sealed="true">${escapeHtml(frame)}</script><div id="${rootId}"></div></body></html>`);
+        }
         // Only the first HTML is server rendered; Inertia visits above stay JSON.
         const rendered = this.ssr ? await this.#serverRender(JSON.parse(json), rootId) : undefined;
         const safeJson = json
@@ -189,7 +360,7 @@ export class InertiaResponder {
                     code: 'INERTIA_PROP_RESCUED',
                     component,
                     prop: key,
-                    error: errorText(error),
+                    error: diagnostics.describeError(error),
                     ...(repeated ? { repeated } : {}),
                 });
             return RESCUED;
@@ -207,10 +378,10 @@ export class InertiaResponder {
             if (!Array.isArray(head) ||
                 head.some((tag) => typeof tag !== 'string') ||
                 typeof body !== 'string')
-                throw new TypeError('SSR render must return { head: string[], body: string }');
+                throw new InertiaUsageError('SSR_INVALID_RESULT', 'SSR render must return { head: string[], body: string }');
             // The client mounts on the root id; a bundle built for another id would never hydrate.
             if (!body.includes(`id="${rootId}"`))
-                throw new TypeError(`SSR body has no element with id "${rootId}" (rootId option)`);
+                throw new InertiaUsageError('SSR_INVALID_RESULT', `SSR body has no element with id "${rootId}" (rootId option)`);
             ssr.rendered?.();
             return { head, body };
         }
@@ -234,7 +405,7 @@ export class InertiaResponder {
         if (url.startsWith('/'))
             localUrl(url);
         else if (!/^https?:$/.test(new URL(url).protocol) || /[\r\n]/.test(url))
-            throw new TypeError('Invalid location');
+            throw new InertiaUsageError('INVALID_URL', 'Invalid location');
         vary(reply);
         return request.headers['x-inertia'] === 'true'
             ? reply.code(409).header('X-Inertia-Location', url).send()

package/dist/vite-dev.d.ts

@@ -1,9 +1,5 @@
-/** The part of Vite's dev server used here. */
-export interface ViteDevServer {
-    middlewares(request: unknown, response: unknown, next: (error?: unknown) => void): void;
-    ssrLoadModule(url: string): Promise<Record<string, unknown>>;
-    close(): Promise<void>;
-}
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import type { Logger } from '@dokebi/core';
 export declare const viteDevRequested: () => boolean;
 /** The part of a Node response the dev route finishes. */
 export interface DevResponse {
@@ -12,13 +8,55 @@ export interface DevResponse {
     end(): unknown;
 }
 /**
- * The `next` of Vite's middlewares on a dev route: no error means Vite has nothing for the URL
- * (404); an error is reported (logged by the caller) and answered 500, never dropped (D-0047).
+ * The `next` of Vite's middlewares: no error means Vite has nothing for the URL (404); an error is
+ * reported (logged by the caller) and answered 500, never dropped (D-0047).
  */
 export declare function viteFallthrough(response: DevResponse, error: unknown, report: (error: unknown) => void): void;
+/** Header that carries the host key; the host answers no HTTP request without it. */
+export declare const VITE_HOST_KEY_HEADER = "x-dokebi-vite-key";
+/** The one Vite of a development session and the loopback port it answers on. */
+export interface ViteHost {
+    /** Where clients reach the host: `http://127.0.0.1:<port>`. */
+    readonly url: string;
+    /** Secret every HTTP request must carry in `x-dokebi-vite-key`. */
+    readonly key: string;
+    /** The port of HTTP and of the HMR socket (Vite's client connects to it). */
+    readonly port: number;
+    /** The loopback addresses listening on `port`. */
+    readonly hosts: readonly string[];
+    /** Closes Vite, the listeners and every connection; resolves once, however often called. */
+    close(): Promise<void>;
+}
+/** What an app process uses: the host's files for `<base>*` and server rendering. */
+export interface ViteDev {
+    /** Answers a dev route request from the host (status, headers and body as Vite sent them). */
+    forward(request: IncomingMessage, response: ServerResponse, report: (error: unknown) => void): void;
+    /** Loads `entry` (relative to the project root) through Vite and calls its `render(page)`. */
+    render(entry: string, page: unknown): Promise<unknown>;
+    /** Releases this process's connections (and its own host, when it started one). */
+    close(): Promise<void>;
+}
+/**
+ * Starts the project's Vite (its vite.config.*) in middleware mode behind a loopback HTTP server
+ * of its own (127.0.0.1 and ::1 on one free port, `exclusive` so a cluster worker binds it
+ * itself). On that port:
+ * - HTTP requests with the key: Vite's middlewares (modules, pre-bundled dependencies,
+ *   `@vite/client`), a ping (`/__dokebi/vite-host`) and server rendering
+ *   (`POST /__dokebi/vite-host/ssr`). Without the key: 403 (a page cannot read sources through
+ *   DNS rebinding; app processes check page hosts before forwarding).
+ * - WebSocket upgrades of Vite's client (HMR): Vite answers them and keeps its token check
+ *   (cross-site WebSocket hijacking). @dokebi/websocket answers every upgrade on the app's port,
+ *   so HMR cannot share that one.
+ */
+export declare function startViteHost(logger: Logger, root?: string): Promise<ViteHost>;
+/**
+ * Connects this process to a Vite host and checks that it answers with the key. Requests share
+ * keep-alive connections; `close` ends them (the host keeps running).
+ */
+export declare function connectViteDev(logger: Logger, url: string, key: string): Promise<ViteDev>;
 /**
- * Starts the project's Vite (its vite.config.*) in middleware mode. The HMR socket gets a free
- * port of its own: @dokebi/websocket answers every upgrade on the app's HTTP server and closes
- * the ones that are not its routes, so HMR cannot share that server.
+ * The Vite of this process: the host of `dokebi dev` when `DOKEBI_VITE_DEV_URL` and
+ * `DOKEBI_VITE_DEV_KEY` name one, otherwise a host started here (then each process, each cluster
+ * worker, has its own Vite: run cluster apps through `dokebi dev`).
  */
-export declare function startViteDev(root?: string): Promise<ViteDevServer>;
+export declare function openViteDev(logger: Logger, environment?: NodeJS.ProcessEnv, root?: string): Promise<ViteDev>;