@dokebi/template-inertia 0.2.0 → 0.4.0

package/dist/errors.js

@@ -0,0 +1,43 @@
+import { DokebiError } from '@dokebi/core';
+const PLUGIN = 'dokebi-template-inertia';
+const FIX = {
+    SSR_BUNDLE_MISSING: 'Build the views first (npm run build), or correct ssr.bundle.',
+    SSR_BUNDLE_INVALID: 'The SSR bundle must be a file that exports render(page).',
+    SSR_ENTRY_MISSING: 'Set ssr.entry (the source module of the SSR bundle, e.g. src/apps/<app>/views/ssr.js) for development, or put ssr.js beside vite.entry.',
+    VITE_MANIFEST_MISSING: 'Build the views first (npm run build), or correct vite.manifest.',
+    VITE_MANIFEST_INVALID: 'Point vite.manifest at .vite/manifest.json of a Vite build (at most 4 MB) and vite.entry at one of its entries.',
+    VITE_DEV_MISSING: 'npm install --save-dev vite (DOKEBI_VITE_DEV=1 serves the views through it).',
+    VITE_DEV_UNAVAILABLE: 'Run the app with dokebi dev, which starts one Vite dev host and sets DOKEBI_VITE_DEV_URL and DOKEBI_VITE_DEV_KEY; or unset both to start Vite in this process.',
+    SEAL_SSR_CONFLICT: 'Set inertia.ssr: false for the app of a seal host, or remove seal: true from its domains (D-0062).',
+    METHOD_NOT_ALLOWED: 'Render pages for GET/HEAD; redirect after POST/PUT/PATCH/DELETE (303).',
+    CLOSED: 'Render only while the application runs.',
+    INVALID_ENTRY: 'The Inertia entry (src/infra/inertia/shared.ts) exports only shared: (request) => props.',
+    INVALID_SCOPE: 'Give scope() document settings (title, rootId, version, scripts, styles or vite, ssr, encryptHistory), shared as a function and sealed as a boolean; vite replaces version, scripts and styles.',
+    INVALID_RENDER: 'render(request, reply, component, props?, { encryptHistory?, clearHistory? }): component is names of letters, digits, _ or - joined by /.',
+    INVALID_PROPS: 'Page props must be JSON values: no undefined, functions, symbols, NaN or Infinity (use null, or leave the prop out).',
+    INVALID_URL: 'Use a local absolute URL such as /posts/1 (not //host, no backslash or spaces).',
+    INVALID_PROP_HELPER: 'defer(fn, { group? }), merge(value, { deep?, matchOn? }), once(value, { key? }): a JSON value or a function, with the documented options.',
+    SSR_INVALID_RESULT: 'The SSR render(page) must return { head: string[], body: string } whose body has the root element (rootId).',
+};
+/** Failures of @dokebi/template-inertia; compare `code`, not the class. */
+export class InertiaError extends DokebiError {
+    constructor(code, message, options = {}) {
+        super(code, message, { plugin: PLUGIN, fix: FIX[code], ...options });
+        this.name = 'InertiaError';
+    }
+}
+/**
+ * A wrong argument (TypeError, as these were before 0.4.0) with the Dokebi error fields
+ * (`code`, `plugin`, `fix`): `isDokebiError` accepts it without inheritance (D-0063 §1).
+ */
+export class InertiaUsageError extends TypeError {
+    code;
+    plugin = PLUGIN;
+    fix;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TypeError';
+        this.code = code;
+        this.fix = FIX[code];
+    }
+}

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import { type Awaitable } from '@dokebi/core';
 import type { FastifyRequest } from 'fastify';
 import { type InertiaApi, type Props } from './responder.js';
+export { InertiaError, type InertiaErrorCode, InertiaUsageError, type InertiaUsageErrorCode, } from './errors.js';
+export { type InertiaPluginOptions, options } from './options.js';
 export { type DeferOptions, deepMerge, defer, InertiaProp, isInertiaProp, type MergeOptions, merge, type OnceOptions, once, type PropValue, } from './props.js';
-export type { InertiaApi, InertiaFlash, InertiaOptions, InertiaPage, InertiaRenderOptions, InertiaSsrResult, Json, Props, } from './responder.js';
+export type { InertiaApi, InertiaErrorResponse, InertiaFlash, InertiaOptions, InertiaPage, InertiaRenderOptions, InertiaSsrResult, Json, Props, } from './responder.js';
 export type InertiaShared = (request: FastifyRequest) => Awaitable<Props>;
 export interface InertiaEntry {
     readonly shared?: InertiaShared;
@@ -48,12 +50,22 @@ export interface InertiaScopeOptions {
     readonly shared?: InertiaShared;
     /** History encryption of this scope's pages (default `'sealed'`: on for sealed requests). */
     readonly encryptHistory?: boolean | 'sealed';
+    /**
+     * The error page component of this scope (D-0074); unset uses the plugin's `errorPage`,
+     * `false` turns it off for this scope.
+     */
+    readonly errorPage?: string | false;
     /**
      * This scope answers seal hosts (dokebi-app sets it, D-0062). Server rendering would write the
      * props as plain HTML, so `sealed` with SSR stops the start (`SEAL_SSR_CONFLICT`).
      */
     readonly sealed?: boolean;
 }
+/** The `inertia` engine contributed to `dokebi-web:view-engine` (web `WebViewEngine` shape). */
+export interface InertiaViewEngine {
+    readonly name: 'inertia';
+    scope(input: InertiaScopeOptions): Promise<InertiaApi>;
+}
 export interface InertiaPluginApi extends InertiaApi {
     /**
      * A renderer with its own document settings and extra shared props. Reads the Vite manifest

package/dist/index.js

@@ -4,15 +4,22 @@ import { readFile, stat } from 'node:fs/promises';
 import { basename, dirname, extname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { types } from 'node:util';
-import { definePlugin, optionalDependency, providerDependency, } from '@dokebi/core';
-import { errorText, Repeats } from './repeats.js';
-import { InertiaResponder, normalizeInertiaOptions, } from './responder.js';
-import { startViteDev, viteDevRequested, viteFallthrough } from './vite-dev.js';
+import { definePlugin, optionalDependency, } from '@dokebi/core';
+import { diagnostics } from '@dokebi/core/libraries';
+import { dependency as web } from '@dokebi/web/dependency';
+import { viewEngines } from '@dokebi/web/points';
+import { InertiaError, InertiaUsageError } from './errors.js';
+import { options } from './options.js';
+import { InertiaResponder, normalizeInertiaOptions, vary, } from './responder.js';
+import { openViteDev, viteDevRequested } from './vite-dev.js';
+export { InertiaError, InertiaUsageError, } from './errors.js';
+export { options } from './options.js';
 export { deepMerge, defer, InertiaProp, isInertiaProp, merge, once, } from './props.js';
 const MANIFEST_MAX_BYTES = 4 * 1024 * 1024;
+const { describeError, Repeats } = diagnostics;
 function parseVite(input) {
     if (input === null || typeof input !== 'object' || Array.isArray(input) || types.isProxy(input))
-        throw new TypeError('Invalid Inertia vite options');
+        throw new InertiaUsageError('INVALID_SCOPE', 'Invalid Inertia vite options');
     const { manifest, entry, base = '/', ...rest } = input;
     if (Object.keys(rest).length ||
         typeof manifest !== 'string' ||
@@ -21,21 +28,21 @@ function parseVite(input) {
         !entry ||
         typeof base !== 'string' ||
         !/^\/(?:[^/\\\s]+\/)*$/.test(base))
-        throw new TypeError('Invalid Inertia vite options');
+        throw new InertiaUsageError('INVALID_SCOPE', 'Invalid Inertia vite options');
     return Object.freeze({ manifest, entry, base });
 }
 function parseSsr(input) {
     if (input === undefined || input === false)
         return undefined;
     if (input === null || typeof input !== 'object' || Array.isArray(input) || types.isProxy(input))
-        throw new TypeError('Invalid Inertia ssr options');
+        throw new InertiaUsageError('INVALID_SCOPE', 'Invalid Inertia ssr options');
     const { bundle, failure = 'fallback', entry, ...rest } = input;
     if (Object.keys(rest).length ||
         typeof bundle !== 'string' ||
         !bundle ||
         (failure !== 'fallback' && failure !== 'error') ||
         (entry !== undefined && (typeof entry !== 'string' || !entry || entry.includes('..'))))
-        throw new TypeError('Invalid Inertia ssr options');
+        throw new InertiaUsageError('INVALID_SCOPE', 'Invalid Inertia ssr options');
     return Object.freeze({ bundle, failure, ...(entry ? { entry: entry } : {}) });
 }
 /**
@@ -47,13 +54,13 @@ async function loadBundle(bundle) {
     const info = await stat(path).catch((cause) => {
         if (cause.code !== 'ENOENT')
             throw cause;
-        throw new Error(`Inertia SSR bundle not found: ${bundle}. Build the views first (npm run build).`, { cause });
+        throw new InertiaError('SSR_BUNDLE_MISSING', `Inertia SSR bundle not found: ${bundle}. Build the views first (npm run build).`, { cause });
     });
     if (!info.isFile())
-        throw new Error(`Inertia SSR bundle is not a file: ${bundle}`);
+        throw new InertiaError('SSR_BUNDLE_INVALID', `Inertia SSR bundle is not a file: ${bundle}`);
     const module = (await import(pathToFileURL(path).href));
     if (typeof module.render !== 'function')
-        throw new Error(`Inertia SSR bundle ${bundle} does not export render(page)`);
+        throw new InertiaError('SSR_BUNDLE_INVALID', `Inertia SSR bundle ${bundle} does not export render(page)`);
     return module.render;
 }
 const CONTENT_TYPES = {
@@ -84,17 +91,17 @@ async function viteAssets(vite) {
     const info = await stat(path).catch((cause) => {
         if (cause.code !== 'ENOENT')
             throw cause;
-        throw new Error(`Vite manifest not found: ${vite.manifest}. Build the views first (npm run build).`, { cause });
+        throw new InertiaError('VITE_MANIFEST_MISSING', `Vite manifest not found: ${vite.manifest}. Build the views first (npm run build).`, { cause });
     });
     if (!info.isFile() || info.size > MANIFEST_MAX_BYTES)
-        throw new Error('Invalid Vite manifest file');
+        throw new InertiaError('VITE_MANIFEST_INVALID', 'Invalid Vite manifest file');
     // Vite writes <outDir>/.vite/manifest.json; a custom manifest name sits in outDir itself.
     const outDir = basename(dirname(path)) === '.vite' ? dirname(dirname(path)) : dirname(path);
     const text = await readFile(path, 'utf8');
     const manifest = JSON.parse(text);
     const entry = Object.hasOwn(manifest, vite.entry) ? manifest[vite.entry] : undefined;
     if (entry?.isEntry !== true || typeof entry.file !== 'string')
-        throw new Error('Vite manifest has no entry ' + JSON.stringify(vite.entry));
+        throw new InertiaError('VITE_MANIFEST_INVALID', 'Vite manifest has no entry ' + JSON.stringify(vite.entry));
     const styles = [];
     const files = new Map();
     const strings = (value) => Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
@@ -134,13 +141,6 @@ async function viteAssets(vite) {
         files,
     };
 }
-// Written here so the provider package resolves from @dokebi/template-inertia, not from core.
-const web = providerDependency({
-    name: 'dokebi-web',
-    version: '^0.2.0',
-    packageName: '@dokebi/web',
-    load: () => import('@dokebi/web'),
-});
 /**
  * Carries a history reset (login, logout) to the next page when the request that did it shows
  * no page itself (a POST that redirects): `clearHistory` then goes out with that next page.
@@ -153,33 +153,80 @@ function hasCookie(header, name) {
         return false;
     return text.split(';').some((part) => part.slice(0, part.indexOf('=')).trim() === name);
 }
+/**
+ * Where a validation redirect goes (D-0074 §3): the `Referer` when it is this host (another
+ * origin is never followed); otherwise `/` for a POST, PUT, PATCH or DELETE. A GET whose referer
+ * is missing or is itself has no way back (a redirect to itself would fail again, forever).
+ */
+function backTarget(request, host) {
+    const referer = request.headers.referer;
+    if (typeof referer === 'string' && referer.length <= 4096) {
+        let url;
+        if (URL.canParse(referer))
+            url = new URL(referer);
+        if (url &&
+            (url.protocol === 'http:' || url.protocol === 'https:') &&
+            url.host.toLowerCase() === host.toLowerCase()) {
+            const target = url.pathname + url.search;
+            if (!(['GET', 'HEAD'].includes(request.method) && target === request.url))
+                return target;
+        }
+    }
+    return ['GET', 'HEAD'].includes(request.method) ? undefined : '/';
+}
+/** Field names whose values never go into the session as old input. */
+const SECRET_FIELD = /pass(?:word|wd|phrase)?|secret|token|api[_-]?key|card|cvc|cvv|otp|pin$/i;
+/** Old input kept at most (as JSON text): a larger body is not flashed. */
+const OLD_MAX = 8192;
+/**
+ * The old input of a refused form (D-0074 §3): the body's top-level strings, numbers, booleans
+ * and nulls, without password-like fields; undefined when nothing is left or it is too large.
+ */
+function oldInput(body) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return undefined;
+    const old = {};
+    let kept = 0;
+    for (const [key, value] of Object.entries(body)) {
+        if (key === '__proto__' || SECRET_FIELD.test(key))
+            continue;
+        if (value === null ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && Number.isFinite(value)) ||
+            typeof value === 'string') {
+            old[key] = value;
+            kept++;
+        }
+    }
+    if (!kept || JSON.stringify(old).length > OLD_MAX)
+        return undefined;
+    return old;
+}
 const session = optionalDependency({
     name: 'dokebi-session',
-    version: '^0.1.0 || ^0.2.0',
+    version: '^0.4.0',
 });
 /** SSR writes props as plain HTML: it cannot serve a sealed scope (D-0062). */
 function sealSsrConflict() {
-    return Object.assign(new Error('An Inertia scope of seal hosts cannot use SSR: server rendering writes the props as plain HTML. Set ssr: false for this app or drop seal from its hosts.'), { code: 'SEAL_SSR_CONFLICT' });
+    return new InertiaError('SEAL_SSR_CONFLICT', 'An Inertia scope of seal hosts cannot use SSR: server rendering writes the props as plain HTML. Set ssr: false for this app or drop seal from its hosts.');
 }
-function parseOptions(input) {
-    const { vite, ssr: ssrInput, ...rest } = (input ?? {});
-    const ssr = parseSsr(ssrInput);
-    if (vite === undefined) {
-        const document = normalizeInertiaOptions(rest);
-        return Object.freeze({
-            document,
-            defaultVersion: rest.version === undefined,
-            ...(ssr ? { ssr } : {}),
-        });
-    }
-    // The manifest decides scripts, styles and version; setting them too would be ambiguous.
-    if (['version', 'scripts', 'styles'].some((key) => rest[key] !== undefined))
-        throw new TypeError('Inertia vite options replace version, scripts and styles');
+/** Settings of the parsed options (the declaration checked them, D-0063 §3). */
+function settings(parsed) {
+    const { vite, ssr, ...rest } = parsed;
+    const document = normalizeInertiaOptions(rest);
     return Object.freeze({
-        document: normalizeInertiaOptions(rest),
-        defaultVersion: false,
-        vite: parseVite(vite),
-        ...(ssr ? { ssr } : {}),
+        document,
+        defaultVersion: vite === undefined && rest.version === undefined,
+        ...(vite ? { vite: Object.freeze({ ...vite }) } : {}),
+        ...(ssr
+            ? {
+                ssr: Object.freeze({
+                    bundle: ssr.bundle,
+                    failure: ssr.failure,
+                    ...(ssr.entry ? { entry: ssr.entry } : {}),
+                }),
+            }
+            : {}),
     });
 }
 /** Accepts a plain object or the namespace of the user entry module (src/inertia/shared.ts). */
@@ -191,7 +238,7 @@ function parseEntry(input) {
         Array.isArray(input) ||
         types.isProxy(input) ||
         ![Object.prototype, null].includes(Object.getPrototypeOf(input)))
-        throw new TypeError('Invalid Inertia entry');
+        throw new InertiaUsageError('INVALID_ENTRY', 'Invalid Inertia entry');
     let shared;
     for (const key of Reflect.ownKeys(input)) {
         // Module namespaces carry Symbol.toStringTag; only string exports are entry fields.
@@ -199,11 +246,11 @@ function parseEntry(input) {
             continue;
         const descriptor = Object.getOwnPropertyDescriptor(input, key);
         if (key !== 'shared' || !descriptor || !('value' in descriptor))
-            throw new TypeError('Invalid Inertia entry');
+            throw new InertiaUsageError('INVALID_ENTRY', 'Invalid Inertia entry');
         shared = descriptor.value;
     }
     if (shared !== undefined && typeof shared !== 'function')
-        throw new TypeError('Inertia shared must be a function');
+        throw new InertiaUsageError('INVALID_ENTRY', 'Inertia shared must be a function');
     return shared === undefined ? {} : { shared: shared };
 }
 class InertiaRuntime {
@@ -242,6 +289,35 @@ class InertiaRuntime {
                             resets.set(request, { served: now, read: carried });
                         return now || carried;
                     },
+                    // D-0074 §3: flash errors and old input, 303 back; the next page gets `errors`.
+                    validation: async (request, reply, errors) => {
+                        const current = sessionOf(request);
+                        const target = backTarget(request, server.requestHost(request));
+                        if (!current?.flash || target === undefined) {
+                            if (logger.isEnabled('debug'))
+                                logger.log('debug', 'Inertia validation answered as JSON', {
+                                    reason: current?.flash ? 'no-way-back' : 'no-session',
+                                    method: request.method,
+                                    route: request.routeOptions.url ?? 'unmatched',
+                                });
+                            return false;
+                        }
+                        await current.flash('errors', { ...errors });
+                        const old = oldInput(request.body);
+                        if (old)
+                            await current.flash('old', old);
+                        if (logger.isEnabled('debug'))
+                            logger.log('debug', 'Inertia validation redirect', {
+                                method: request.method,
+                                route: request.routeOptions.url ?? 'unmatched',
+                                fields: Object.keys(errors).slice(0, 32),
+                                old: old ? Object.keys(old).length : 0,
+                                target: target.split('?', 1)[0]?.slice(0, 200),
+                            });
+                        vary(reply);
+                        reply.redirect(target, 303);
+                        return true;
+                    },
                 }
                 : {}),
         });
@@ -265,7 +341,8 @@ class InertiaRuntime {
             carry[Symbol.for('skip-override')] = true;
             server.register(carry, {});
         }
-        // Development (D-0045): one Vite dev server for every scope, started by the first `vite`.
+        // Development (D-0045): one Vite for every scope, reached by the first `vite` (the host of
+        // `dokebi dev`, shared by every worker, or one started in this process).
         const develop = viteDevRequested();
         logger.log('debug', 'Inertia settings resolved', {
             develop,
@@ -276,6 +353,8 @@ class InertiaRuntime {
             flash: flash !== undefined,
             historyReset: hooks.historyReset !== undefined,
             encryptHistory: this.settings.document.encryptHistory,
+            // D-0068: every page value is checked for JSON outside production, top-level props in it.
+            propsCheck: process.env.NODE_ENV === 'production' ? 'top-level' : 'deep',
         });
         // Per-request failures are logged once per interval with the count of repeats (D-0047).
         const repeats = new Repeats();
@@ -306,12 +385,13 @@ class InertiaRuntime {
             if (!devServer) {
                 const begin = performance.now();
                 // A start failure reaches setup or the request that awaits the server.
-                devServer = startViteDev().then((started) => {
-                    logger.log('debug', 'Vite dev server started', {
+                devServer = openViteDev(logger).then((opened) => {
+                    logger.log('debug', 'Vite dev server ready', {
                         ms: Math.round(performance.now() - begin),
+                        shared: process.env.DOKEBI_VITE_DEV_URL !== undefined,
                         hosts: [...pageHosts].slice(0, 64),
                     });
-                    return started;
+                    return opened;
                 });
                 context.logger.log('info', 'Inertia views are served by the Vite dev server', {
                     code: 'INERTIA_VITE_DEV',
@@ -339,16 +419,17 @@ class InertiaRuntime {
                         }
                         const vite = await current;
                         reply.hijack();
-                        vite.middlewares(request.raw, reply.raw, (error) => viteFallthrough(reply.raw, error, (failure) => {
+                        // Status, headers and body as the Vite host sent them (504 included).
+                        vite.forward(request.raw, reply.raw, (failure) => {
                             const repeated = repeats.take(`vite ${failure instanceof Error ? failure.name : typeof failure}`);
                             if (repeated !== undefined)
-                                logger.log('error', 'Vite dev middleware failed', {
+                                logger.log('error', 'Vite dev request failed', {
                                     code: 'INERTIA_VITE_DEV_FAILED',
                                     base,
-                                    error: errorText(failure),
+                                    error: describeError(failure),
                                     ...(repeated ? { repeated } : {}),
                                 });
-                        }));
+                        });
                     },
                 });
                 logger.log('debug', 'Vite dev route registered', { url: `${base}*` });
@@ -409,19 +490,15 @@ class InertiaRuntime {
                 const fallback = vite ? `${dirname(vite.entry)}/ssr.js` : undefined;
                 const source = ssr.entry ?? (fallback && existsSync(resolve(fallback)) ? fallback : undefined);
                 if (!source || !vite)
-                    throw new Error(`Inertia SSR in development needs the source of ${ssr.bundle}: set ssr.entry`);
+                    throw new InertiaError('SSR_ENTRY_MISSING', `Inertia SSR in development needs the source of ${ssr.bundle}: set ssr.entry`);
                 const dev = viteDev(vite.base);
                 logger.log('debug', 'Inertia SSR renders the source through Vite', {
                     source,
                     bundle: ssr.bundle,
                     entrySet: ssr.entry !== undefined,
                 });
-                render = Promise.resolve(async (page) => {
-                    const module = await (await dev).ssrLoadModule(`/${source}`);
-                    if (typeof module.render !== 'function')
-                        throw new Error(`Inertia SSR entry ${source} does not export render(page)`);
-                    return module.render(page);
-                });
+                // The Vite host loads the source and renders (one Vite for every worker).
+                render = Promise.resolve(async (page) => (await (await dev).render(source, page)));
             }
             else {
                 const path = resolve(ssr.bundle);
@@ -454,7 +531,7 @@ class InertiaRuntime {
                             bundle: ssr.bundle,
                             component,
                             fallback: ssr.failure === 'fallback',
-                            error: errorText(error),
+                            error: describeError(error),
                             ...(repeated ? { repeated } : {}),
                         });
                 },
@@ -477,19 +554,28 @@ class InertiaRuntime {
                     : render,
                 redirect: responder.redirect.bind(responder),
                 location: responder.location.bind(responder),
+                answerError: responder.answerError.bind(responder),
             });
         };
         // Prop evaluation (debug) and rescued deferred props (error) are logged by every scope.
         const diagnostics = Object.freeze({ logger, repeats });
         const root = api(new InertiaResponder(document, this.shared, await serverRendering(this.settings.ssr, this.settings.vite), diagnostics, flash, hooks));
+        // D-0074 §3: Inertia requests refused by validation go back with `errors` (with a session);
+        // the plugin's `errorPage` answers the rest. dokebi-app adds its own responder later, which
+        // dokebi-web asks first, so an app's requests use the app's scope.
+        server.errorResponder((response) => root.answerError(response));
+        logger.log('debug', 'Inertia error answers', {
+            validationRedirect: hooks.validation !== undefined,
+            errorPage: document.errorPage,
+        });
         const shared = this.shared;
-        return Object.freeze({
+        const plugin = Object.freeze({
             ...root,
             ssrStats: () => Object.freeze({ ...stats }),
             scope: async (options) => {
                 const { shared: extra, vite, ssr: ssrInput, sealed = false, ...fields } = (options ?? {});
                 if (typeof sealed !== 'boolean')
-                    throw new TypeError('Inertia scope sealed must be a boolean');
+                    throw new InertiaUsageError('INVALID_SCOPE', 'Inertia scope sealed must be a boolean');
                 const ssr = ssrInput === undefined ? this.settings.ssr : parseSsr(ssrInput);
                 if (sealed && ssr) {
                     logger.log('error', 'Inertia scope of seal hosts with SSR', {
@@ -500,9 +586,9 @@ class InertiaRuntime {
                     throw sealSsrConflict();
                 }
                 if (extra !== undefined && typeof extra !== 'function')
-                    throw new TypeError('Inertia scope shared must be a function');
+                    throw new InertiaUsageError('INVALID_SCOPE', 'Inertia scope shared must be a function');
                 if (vite !== undefined && ['version', 'scripts', 'styles'].some((key) => key in fields))
-                    throw new TypeError('Inertia vite options replace version, scripts and styles');
+                    throw new InertiaUsageError('INVALID_SCOPE', 'Inertia vite options replace version, scripts and styles');
                 const scoped = normalizeInertiaOptions({
                     ...document,
                     ...fields,
@@ -521,18 +607,26 @@ class InertiaRuntime {
                     shared: merged !== undefined,
                     sealed,
                     encryptHistory: scoped.encryptHistory,
+                    errorPage: scoped.errorPage,
                 });
                 return api(responder);
             },
         });
+        // D-0063 §5: the view engine `inertia` for dokebi-app (inert until a plugin collects it).
+        context.contribute(viewEngines, Object.freeze({
+            name: 'inertia',
+            scope: (input) => plugin.scope(input),
+        }));
+        return plugin;
     }
 }
 export const createPlugin = definePlugin({
     name: 'dokebi-template-inertia',
-    version: '0.2.0',
-    core: '^0.2.0',
-    options: parseOptions,
+    version: '0.4.0',
+    core: '^0.4.0',
+    options,
     entry: parseEntry,
+    contributes: [viewEngines],
     dependencies: () => [web, session],
-    instance: ({ options, entry }) => new InertiaRuntime(options, entry?.shared),
+    instance: ({ options, entry }) => new InertiaRuntime(settings(options), entry?.shared),
 });

package/dist/options.d.ts

@@ -0,0 +1,22 @@
+import { type OptionsOf } from '@dokebi/core';
+export declare const options: import("@dokebi/core").OptionsDeclaration<{
+    readonly encryptHistory: "sealed" | boolean;
+    readonly errorPage?: string;
+    readonly rootId?: string;
+    readonly scripts?: readonly string[];
+    readonly ssr?: {
+        readonly bundle: string;
+        readonly entry?: string;
+        readonly failure: "error" | "fallback";
+    };
+    readonly styles?: readonly string[];
+    readonly title?: string;
+    readonly version?: string;
+    readonly vite?: {
+        readonly base: string;
+        readonly entry: string;
+        readonly manifest: string;
+    };
+}>;
+/** The parsed options of dokebi-template-inertia (`options.dokebi-template-inertia`). */
+export type InertiaPluginOptions = OptionsOf<typeof options>;

package/dist/options.js

@@ -0,0 +1,84 @@
+import { defineOptions, option as o } from '@dokebi/core';
+/*
+ * Options of dokebi-template-inertia (D-0063 §3): one declaration is the parser and, at build
+ * time, options.schema.json. The rules are the hand parser's before wave B; the asset URL rule
+ * (no `//`, backslash, space or control character) is declared as a refinement.
+ */
+/** A local absolute URL: `/x`, not `//host`, without backslash, space or control characters. */
+const localAsset = o.string({
+    pattern: '^/[^/]',
+    refine: [
+        {
+            test: (value) => ![...value].some((char) => char === '\\' || char.charCodeAt(0) <= 32),
+            message: 'must be a local absolute URL without backslash, space or control characters',
+        },
+    ],
+});
+export const options = defineOptions({
+    version: o.string({
+        description: 'Asset version sent with every page; a client with another one reloads (409). Unset: development (and a warning).',
+    }),
+    rootId: o.string({
+        pattern: '^[A-Za-z][A-Za-z0-9_-]*$',
+        description: 'Id of the element the client app mounts on (default app).',
+    }),
+    title: o.string({ description: 'Document title of the first HTML.' }),
+    scripts: o.array(localAsset, { description: 'Module scripts of the first HTML.' }),
+    styles: o.array(localAsset, { description: 'Stylesheets of the first HTML.' }),
+    vite: o.object({
+        manifest: o.string({
+            minLength: 1,
+            required: true,
+            description: 'Path of .vite/manifest.json, relative to the working directory',
+        }),
+        entry: o.string({
+            minLength: 1,
+            required: true,
+            description: 'Manifest key of the entry, e.g. src/apps/<app>/views/app.js',
+        }),
+        base: o.string({
+            pattern: '^/(?:[^/\\\\\\s]+/)*$',
+            default: '/',
+            description: 'URL prefix of the built files (default /)',
+        }),
+    }, {
+        description: 'Read scripts, styles and version from a Vite build manifest at startup. Replaces version, scripts and styles.',
+    }),
+    ssr: o.object({
+        bundle: o.string({
+            minLength: 1,
+            required: true,
+            description: 'SSR build output that exports render(page), relative to the working directory, e.g. dist/ssr/<app>/ssr.js',
+        }),
+        failure: o.enum(['fallback', 'error'], {
+            default: 'fallback',
+            description: 'When render throws: answer the client-rendered page and log (fallback, default) or fail the request (error)',
+        }),
+        entry: o.string({
+            minLength: 1,
+            pattern: '^(?!.*\\.\\.)',
+            description: 'Development (D-0045): source module of the bundle rendered through Vite, e.g. src/apps/admin/views/ssr.js. Default: ssr.js beside vite.entry',
+        }),
+    }, {
+        description: 'Render the first HTML of each page on the server (D-0039) with the SSR build output, imported once at start. A missing bundle stops the start.',
+    }),
+    encryptHistory: o.union([o.boolean(), o.literal('sealed')], {
+        default: 'sealed',
+        description: 'Inertia history encryption (D-0062): true, false, or sealed (default) = on for requests of seal hosts',
+    }),
+    errorPage: o.string({
+        pattern: '^[A-Za-z0-9][A-Za-z0-9_-]*(?:/[A-Za-z0-9][A-Za-z0-9_-]*)*$',
+        description: 'Page component (for example Error) rendered with { status, error, message, hint } for error answers of Inertia visits and full page loads (D-0074). Unset: JSON for visits, a small HTML page for page loads.',
+    }),
+}, {
+    checks: [
+        {
+            path: 'vite',
+            message: 'replaces version, scripts and styles; set only one of them',
+            test: (value) => value.vite === undefined ||
+                (value.version === undefined &&
+                    value.scripts === undefined &&
+                    value.styles === undefined),
+        },
+    ],
+});