@dokebi/template-inertia 0.1.3 → 0.4.0

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, 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;
@@ -46,6 +48,23 @@ export interface InertiaScopeOptions {
     readonly ssr?: InertiaSsrOptions | false;
     /** Props merged after the plugin's shared props for every page of this scope. */
     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 {
     /**

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,36 +141,92 @@ 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.1.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.
+ */
+const HISTORY_RESET_COOKIE = 'dokebi.history-reset';
+const HISTORY_RESET_SECONDS = 600;
+function hasCookie(header, name) {
+    const text = Array.isArray(header) ? header.join('; ') : (header ?? '');
+    if (text.length > 16_384)
+        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',
+    version: '^0.4.0',
 });
-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');
+/** SSR writes props as plain HTML: it cannot serve a sealed scope (D-0062). */
+function sealSsrConflict() {
+    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.');
+}
+/** 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). */
@@ -175,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.
@@ -183,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 {
@@ -208,7 +271,78 @@ class InertiaRuntime {
         const flash = sessions
             ? async (request) => (await sessions.of(request).takeFlash())
             : undefined;
-        // Development (D-0045): one Vite dev server for every scope, started by the first `vite`.
+        // D-0062: sealed requests (dokebi-web decides) and the session's history reset (logout, login).
+        // A page shown in the request that reset uses it at once; otherwise the reset cookie carries
+        // it to the next page, which also clears that cookie.
+        const resets = new WeakMap();
+        const sessionOf = (request) => 
+        // Static paths excluded by the session plugin have none (`request.session` is null).
+        request.session ? sessions?.of(request) : undefined;
+        const hooks = Object.freeze({
+            sealOf: (request) => server.sealOf(request),
+            ...(sessions
+                ? {
+                    historyReset: async (request) => {
+                        const now = sessionOf(request)?.historyReset?.() === true;
+                        const carried = hasCookie(request.headers.cookie, HISTORY_RESET_COOKIE);
+                        if (now || carried)
+                            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;
+                    },
+                }
+                : {}),
+        });
+        if (sessions) {
+            const carry = async (scope) => {
+                scope.addHook('onSend', async (request, reply, payload) => {
+                    const state = resets.get(request);
+                    const reset = sessionOf(request)?.historyReset?.() === true;
+                    if (!(reset && !state?.served) && !state?.read)
+                        return payload;
+                    const set = reset && !state?.served;
+                    reply.header('set-cookie', `${HISTORY_RESET_COOKIE}=${set ? '1' : ''}; Path=/; Max-Age=${set ? HISTORY_RESET_SECONDS : 0}; HttpOnly; SameSite=Lax${request.protocol === 'https' ? '; Secure' : ''}`);
+                    if (logger.isEnabled('debug'))
+                        logger.log('debug', 'Inertia history reset cookie', {
+                            operation: set ? 'set' : 'clear',
+                        });
+                    return payload;
+                });
+            };
+            // Without encapsulation (skip-override), so the hook sees every route.
+            carry[Symbol.for('skip-override')] = true;
+            server.register(carry, {});
+        }
+        // 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,
@@ -217,6 +351,10 @@ class InertiaRuntime {
             defaultVersion: this.settings.defaultVersion,
             shared: this.shared !== undefined,
             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();
@@ -247,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',
@@ -280,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}*` });
@@ -350,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);
@@ -395,7 +531,7 @@ class InertiaRuntime {
                             bundle: ssr.bundle,
                             component,
                             fallback: ssr.failure === 'fallback',
-                            error: errorText(error),
+                            error: describeError(error),
                             ...(repeated ? { repeated } : {}),
                         });
                 },
@@ -411,29 +547,48 @@ class InertiaRuntime {
             const render = responder.render.bind(responder);
             return Object.freeze({
                 render: develop
-                    ? (request, reply, component, props) => {
+                    ? (request, reply, component, props, options) => {
                         pageHosts.add(hostName(request));
-                        return render(request, reply, component, props);
+                        return render(request, reply, component, props, options);
                     }
                     : 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));
+        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, ...fields } = (options ?? {});
+                const { shared: extra, vite, ssr: ssrInput, sealed = false, ...fields } = (options ?? {});
+                if (typeof sealed !== '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', {
+                        code: 'SEAL_SSR_CONFLICT',
+                        title: typeof fields.title === 'string' ? fields.title.slice(0, 100) : null,
+                        fix: 'Set inertia.ssr: false for this app, or remove seal: true from its domains',
+                    });
+                    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,
@@ -443,25 +598,35 @@ class InertiaRuntime {
                     ? async (request) => ({ ...(await shared(request)), ...(await extra(request)) })
                     : (extra ?? shared);
                 const scopedVite = vite === undefined ? this.settings.vite : parseVite(vite);
-                const responder = new InertiaResponder(scoped, merged, await serverRendering(ssr, scopedVite), diagnostics, flash);
+                const responder = new InertiaResponder(scoped, merged, await serverRendering(ssr, scopedVite), diagnostics, flash, hooks);
                 logger.log('debug', 'Inertia scope created', {
                     title: scoped.title,
                     rootId: scoped.rootId,
                     vite: scopedVite ? scopedVite.entry : false,
                     ssr: ssr ? ssr.bundle : false,
                     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.1.3',
-    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),
+        },
+    ],
+});