@dokebi/template-inertia 0.0.0-stage → 0.1.1

package/AI.md

@@ -0,0 +1,74 @@
+# AI 작업 안내 — @dokebi/template-inertia 0.1.1
+
+Inertia(v3) 서버 어댑터다. 첫 요청은 HTML(+ `script[data-page]` JSON), 이후 `X-Inertia` 요청은 page JSON으로 답한다. Vite manifest를 읽어 스크립트·스타일·버전을 채우고 빌드 파일을 직접 내보낸다. 선택적으로 첫 HTML을 같은 프로세스에서 서버 렌더링(SSR, D-0039)한다. Vue·Vite는 서버 의존성이 아니다(앱의 개발 의존성). Node >=24.0.0, core ^0.2.0, @dokebi/web(peer). 세부는 [README](README.md)다.
+
+## 1. 설치와 프로젝트 구성
+
+```sh
+npx dokebi add @dokebi/template-inertia            # src/infra/inertia/shared.ts(공통 props)
+npx dokebi app add admin --inertia [--ssr] --domain admin.a.com   # @dokebi/app 앱 + Vite 빌드 준비
+npm run build                                       # dist/(브라우저) + dist/ssr/(서버, --ssr)
+```
+
+- `src/infra/inertia/shared.ts`의 `export async function shared(request)`가 모든 페이지 props에 합쳐진다(호출 props가 우선).
+- Inertia 앱의 app.ts: `inertia: { title, vite: { manifest: 'dist/.vite/manifest.json', entry: 'src/apps/<앱>/views/app.js', base: '/build/' }, ssr?: { bundle: 'dist/ssr/<앱>/ssr.js' } }`.
+
+## 2. 설정 `options.dokebi-template-inertia`(앱마다는 `scope`로 덮어씀)
+
+| 키 | 뜻 |
+|---|---|
+| `title` | 문서 제목(기본 빈 문자열) |
+| `rootId` | 루트 요소 id(기본 `app`, `^[A-Za-z][A-Za-z0-9_-]*$`) |
+| `version` · `scripts` · `styles` | 자산 버전과 URL(`/`로 시작하는 로컬 URL). 없으면 `INERTIA_VERSION_DEFAULT` 경고 |
+| `vite: { manifest, entry, base? }` | manifest에서 scripts·styles·version 계산. 위 셋과 함께 쓰면 거부 |
+| `ssr: { bundle, failure? }` | 서버 렌더링. `failure`: `fallback`(기본) · `error` |
+
+## 3. 페이지 렌더
+
+```ts
+// @dokebi/app 앱 라우트: page.inertia가 앱 설정을 쓰는 렌더러
+route.get('/orders', async (request, reply, page) =>
+  page.inertia!.render(request, reply, 'Orders/Index', {
+    orders: await listOrders(),                          // JSON 값
+    stats: () => computeStats(),                         // lazy: 요청된 경우만 평가(동시 평가)
+  }),
+);
+route.post('/orders', async (request, reply, page) => {
+  await createOrder(request.body);
+  return page.inertia!.redirect(request, reply, '/orders');   // mutation은 303
+});
+```
+
+- `render(request, reply, component, props?)`: GET/HEAD에서만. 핸들러에서 반환·await. component는 `/`로 구분된 `[A-Za-z0-9][A-Za-z0-9_-]*` 조각.
+- props: JSON 값 또는 비동기 lazy 함수. partial reload(`only`·`except`)는 선택된 것만 평가하고 `errors`는 항상 포함. 비JSON 값·순환은 실패.
+- `redirect(request, reply, localUrl)`: GET/HEAD 302, mutation 303, Inertia의 `#` 이동은 409 + `X-Inertia-Redirect`.
+- `location(request, reply, url)`: 로컬 또는 http(s) 외부 이동. Inertia 요청은 409 + `X-Inertia-Location`.
+- 오래된 version의 Inertia 요청은 props 평가 없이 409 + `X-Inertia-Location`(새로고침 유도).
+- 응답에 `Vary: X-Inertia`, `Cache-Control: no-store`가 붙고 HTML에 넣는 JSON·제목·URL은 escape된다.
+
+## 4. 빌드 파일 서빙
+
+`vite`를 쓰면 manifest(최대 4MiB)를 setup에서 한 번 읽어 entry에서 닿는 파일(정적·동적 청크, CSS, assets)만 `<base><파일>` 정확한 경로로 내보낸다(`cache-control: public, max-age=31536000, immutable`). manifest 자체와 목록 밖 파일, `dist/ssr/`는 내보내지 않는다. manifest가 없으면 시작 실패(`Vite manifest not found: … Build the views first (npm run build).`), entry가 없으면 시작 실패.
+
+## 5. SSR(D-0039)
+
+- `ssr.bundle`은 `render(page) → { head: string[]; body: string }`을 export하는 빌드 파일이다. Inertia v3에서는 `createInertiaApp({ resolve, layout })`을 서버에서 page 없이 부르면 `(page, renderToString)` 함수를 준다(`--ssr`이 만드는 `views/ssr.js` 참고).
+- 번들은 시작 때 한 번 import한다. **없거나 `render`가 없으면 시작 실패.**
+- 요청 중 render가 던지거나 모양이 틀리거나 body에 `id="<rootId>"`가 없으면: `fallback`은 그 요청을 CSR로 답하고 `INERTIA_SSR_FAILED`(error) 로그, `error`는 요청 실패(500).
+- head에 `<title>`이 있으면 설정 title은 빠진다. Inertia 이동(JSON)은 SSR을 거치지 않는다.
+- 브라우저 진입은 `el.hasAttribute('data-server-rendered')`면 `createSSRApp`으로 hydration한다. 서버·브라우저가 같은 레이아웃을 고르도록 페이지 모듈을 바꾸지 말고 `layout` 옵션을 쓴다(동시에 여러 템플릿을 그리므로).
+- `ssrStats()` → `{ renders, failures }`(health·대시보드용). `scope({ ssr: false })`로 앱별로 끌 수 있다.
+
+## 6. 범위(scope)
+
+`await api.scope({ title?, rootId?, version?, scripts?, styles?, vite?, ssr?, shared? })` → 그 설정의 렌더러. 정하지 않은 값은 플러그인 옵션, `shared`는 플러그인 shared 뒤에 합쳐진다. @dokebi/app이 앱마다 부른다.
+
+## 7. 주의 사항
+
+- props에 비밀·개인정보를 넣지 않는다(HTML에 그대로 실린다). 인증·인가·CSRF는 앱이 구현한다.
+- 데이터 조회·수정 API는 Inertia 응답이 아니라 일반 JSON 라우트(REST)로 만든다.
+- 배포에는 빌드별 version(또는 `vite`)을 꼭 쓴다. 기본 version이면 자산이 바뀌어도 클라이언트가 모른다.
+- deferred·merge·once props, Precognition, session flash는 없다. 있다고 가정하지 않는다.
+- 앱 인스턴스마다 새 플러그인. 전체 drain 뒤에 responder가 닫힌다.
+
+근거: `examples/24-template-inertia`(실제 Chrome: CSR·SSR·cluster, 측정), `examples/26-scaffold`(CLI가 만든 SSR 앱의 빌드·서버 렌더), `examples/25-playground`, D-0027·D-0031·D-0039.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dokebi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @dokebi/template-inertia 0.1.1
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node >=24.0.0, core ^0.2.0, 선택 패키지다(npm 공개). ID는 `dokebi-template-inertia`이며 `dokebi-web`에 의존한다. `@dokebi/web`은 peer 의존성이다(예전의 고정 버전 dependency가 아니다). EJS·Vue·Vite를 서버 패키지의 필수 의존성으로 설치하지 않는다.
+
+플러그인 계약 v2([D-0028](../../docs/decisions/D-0028-plugin-contract-v2.md))를 따른다. `createPlugin({ app: app.view, options?, entry? })`이며 `app`은 필수다. 예전 `web`·`dependencies`·`shared` 입력은 없다. web은 `providerDependency`로 연결한다: 같은 앱에 `dokebi-web`이 등록되어 있으면 그것을 쓰고, 없으면 `@dokebi/web`에서 만든다. 요청별 공통 props는 `entry.shared`로 넘긴다.
+
+```ts
+import { createPlugin as createInertia } from '@dokebi/template-inertia';
+import { createPlugin as createWeb } from '@dokebi/web';
+const web = createWeb({ app: app.view }); // 주소를 읽거나 라우트를 직접 붙일 때 먼저 등록
+app.register(web);
+const pages = createInertia({
+  app: app.view,
+  options: { version: 'build-hash', scripts: ['/assets/app.js'], styles: ['/assets/app.css'] },
+  entry: { shared: (request) => ({ user: String(request.headers['x-user'] ?? 'guest') }) },
+});
+// 업무 플러그인이 web과 pages를 의존성으로 선언한 setup 안에서:
+// context.get(web).route({ method: 'GET', url: '/', handler: (req, reply) =>
+//   context.get(pages).render(req, reply, 'Home', { counter: { value: 0 } }) });
+```
+
+위 x-user는 API 예시이며 인증 수단이 아니다. 앱의 인증 결과에서 사용자 props를 만든다. `render(request, reply, component, props?)`는 GET/HEAD에서만 호출하며 handler에서 반드시 반환/await한다. 초기 접근은 HTML과 JSON page script, 이후 X-Inertia 요청은 page JSON으로 응답한다. Inertia v3의 `script[data-page="app"]` 형식이다. `rootId` 기본 app, title 기본 빈 문자열, version 기본 development다. version을 설정하지 않으면 setup에서 한 번 warn 로그(`code: INERTIA_VERSION_DEFAULT`)를 남긴다. 그 상태에서는 자산이 바뀌어도 클라이언트가 감지하지 못하므로 실제 배포에서는 빌드별 version과 해당 manifest의 scripts/styles를 지정한다. Vite 빌드를 쓰면 `vite: { manifest, entry, base? }`로 대신 지정할 수 있다. setup에서 manifest(`.vite/manifest.json`, 작업 폴더 기준 상대 또는 절대 경로, 최대 4MiB)를 한 번 읽어 entry의 스크립트, entry와 import한 청크의 CSS, manifest 내용 해시(SHA-256 앞 32자) version을 채운다. `base`(기본 `/`)는 빌드 파일의 URL 접두사다. `vite`와 `version`·`scripts`·`styles`를 함께 쓰면 거부한다. entry가 manifest에 없으면 시작이 실패하고 오류에 entry 이름이 나온다([ISSUE-0005](../../docs/issues/ISSUE-0005-playground-findings.md) PG-07). manifest 파일이 없으면 `Vite manifest not found: <경로>. Build the views first (npm run build).`로 실패한다.
+
+빌드 파일은 이 플러그인이 dokebi-web으로 직접 내보낸다([D-0031](../../docs/decisions/D-0031-project-layout.md) 보완 1). entry에서 닿는 파일만 대상이다. 정적·동적 import 청크, CSS, assets가 여기에 들어간다. 각 파일은 `<base><파일>`의 정확한 경로에 GET 경로로 등록되고, 와일드카드 경로는 쓰지 않는다. 그래서 manifest 자체나 목록에 없는 파일은 내보내지 않는다. 앱 여럿이 같은 청크를 쓰면 한 번만 등록한다. 파일 위치는 manifest가 `<outDir>/.vite/manifest.json`이면 outDir이고, 그렇지 않으면 manifest가 있는 폴더다. 응답에는 확장자별 content-type과 `cache-control: public, max-age=31536000, immutable`이 붙는다. 이름에 해시가 든 빌드 파일을 전제로 하기 때문이다. CDN이나 다른 정적 서버로 낼 때도 같은 경로에 두면 된다.
+
+```yaml
+dokebi-template-inertia:
+  title: My app
+  vite: { manifest: dist/.vite/manifest.json, entry: src/apps/shop/views/app.js, base: /build/ }
+```
+
+잘못된 옵션은 팩토리에서 `INVALID_PLUGIN_OPTIONS`다. asset URL은 `/`로 시작하는 로컬 절대 URL만 허용하며 파일 서빙은 앱/정적 서버 책임이다.
+
+props는 JSON 값 또는 비동기 lazy 함수다. shared(request)와 호출 props를 요청마다 합치고 호출 props가 우선한다. 동일 component의 partial-data/partial-except는 선택 props만 평가한다(except 우선). 선택된 lazy 함수는 `Promise.all`로 동시에 평가하고 결과 객체의 키 순서는 원래 순서를 유지한다. errors는 항상 포함한다. 비JSON 값·순환은 성공 응답 대신 실패한다. HTML에 넣는 JSON/제목/asset 속성을 escape하며 Vary: X-Inertia와 Cache-Control: no-store를 설정한다. 오래된 version은 props 평가 없이409 + X-Inertia-Location/Version을 반환한다.
+
+`redirect(request, reply, localUrl)`은 GET/HEAD302, mutation303이며 Inertia fragment 이동은409 + X-Inertia-Redirect다. `location(request, reply, url)`은 로컬 또는 HTTP(S) 이동으로 Inertia409 + X-Inertia-Location, 일반 요청302다. 외부 목적지는 신뢰된 앱 코드에서 선택한다.
+
+Vue 페이지 이동·초기 props는 Inertia, 이후 조회·수정은 `fetch('/api/...')` REST로 구분한다. API 라우트는 JSON·상태 코드를 직접 반환하며 Inertia 응답으로 포장하지 않는다. 페이지/API의 업무 서비스와 인증·인가를 공유하고 쿠키 인증 mutation의 CSRF를 앱에서 검증한다. 서버별 상태 공유가 필요하면 선택 DB/Redis를 연결한다.
+
+공통 Template 기반 클래스는 없다. EJS 문자열 엔진과 HTTP 응답 어댑터를 독립 클래스로 조합한다. 전체 요청 drain 뒤 responder를 닫으며 Application마다 새 인스턴스를 만든다. 옵션은 `options`가 없으면 app.config의 dokebi-template-inertia 값을 사용한다.
+
+## 설치
+
+`dokebi add`는 정적 설치 선언으로 진입 파일 `src/infra/inertia/shared.ts`(`export async function shared(_request) { return {}; }`)를 만들고 생성 코드가 이를 `entry`로 넘긴다. 설치 모듈(installModule)은 없다. web은 manifest 의존성으로 함께 설치·순서 검사된다.
+
+지원 범위는 초기 HTML·페이지 이동·shared/lazy/partial props·redirect·version 협상·서버 렌더링(아래 SSR 절)이다. deferred/merge/once props, Precognition, 서버 session flash 및 Inertia form 검증 redirect 저장소는 제공하지 않는다. REST422 오류 처리는 예제에 구현되어 있다. Vue persistent layout은 Vue 클라이언트 책임이다.
+
+[예제24](../../examples/24-template-inertia/README.md)에 실제 Vue3 + Inertia + REST, 인증/CSRF fixture와 Chrome 자동 검증이 있다. `npm test -w @dokebi/template-inertia`는 HTTP 프로토콜 회귀다.
+
+## 범위별 문서 설정 (D-0030)
+
+`scope({ title?, rootId?, version?, scripts?, styles?, vite?, shared? })`는 자기 문서 설정과 추가 공통 props를 가진 렌더러를 돌려준다(비동기, `vite`면 manifest를 읽는다). 정하지 않은 값은 플러그인 옵션을 따른다. `shared`는 플러그인 공통 props 뒤에 합쳐진다. @dokebi/app이 앱마다 다른 Vite 진입점에 쓴다.
+
+## 서버 렌더링(SSR, D-0039)
+
+`ssr: { bundle, failure? }`를 주면 페이지의 첫 HTML을 서버에서 그린다. 별도 SSR 프로세스 없이 같은 프로세스에서 SSR 빌드 산출물을 시작 때 한 번 import하고, 전체 페이지 요청마다 그 `render(page)`를 부른다. Inertia 이동(`X-Inertia`)은 지금처럼 JSON이고 SSR을 거치지 않는다.
+
+- `bundle`: `render(page) → Promise<{ head: string[]; body: string }>`를 export하는 빌드 파일(작업 폴더 기준 또는 절대 경로). Inertia v3의 `createInertiaApp`은 서버에서 `page` 없이 부르면 `(page, renderToString)` 함수를 돌려주므로 `export const render = async (page) => (await app)(page, renderToString)`이면 된다(예제 24의 `client/ssr.js`).
+- 번들이 없거나 `render`가 없으면 **시작이 실패한다.** SSR을 켰는데 조용히 CSR이 되는 일을 막는다.
+- 요청 중 `render`가 던지거나, 모양이 틀리거나(`head` 문자열 배열·`body` 문자열), `body`에 `id="<rootId>"`가 없으면 `failure`를 따른다. `fallback`(기본)은 그 요청을 CSR 페이지로 답하고 `INERTIA_SSR_FAILED` 오류 로그를 남긴다. `error`는 요청을 실패시킨다(개발 중 바로 보기).
+- `head`는 `</head>` 앞에 넣는다. 그 안에 `<title>`이 있으면(페이지의 `<Head>`) 설정한 `title`은 빠진다. `body`는 기본 `<script data-page>`·빈 루트 대신 들어간다.
+- 브라우저 진입점은 `el.hasAttribute('data-server-rendered')`면 `createSSRApp`으로 hydration한다.
+- `ssrStats()`는 시작 뒤 렌더 수와 실패 수다(health·대시보드용).
+- `scope({ ssr })`: 앱마다 번들을 정한다. 생략하면 플러그인 옵션을 따르고 `false`면 끈다. 같은 파일은 한 번만 import한다.
+
+측정(예제 24, 같은 프로세스, 순차 400회): CSR 0.20~0.24ms, SSR 0.24~0.28ms(작은 페이지), SSR 450장 뒤 heap +1.1MB.

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { type Awaitable } from '@dokebi/core';
+import type { FastifyRequest } from 'fastify';
+import { type InertiaApi, type Props } from './responder.js';
+export type { InertiaApi, InertiaOptions, InertiaPage, InertiaSsrResult, Json, Props, } from './responder.js';
+export type InertiaShared = (request: FastifyRequest) => Awaitable<Props>;
+export interface InertiaEntry {
+    readonly shared?: InertiaShared;
+}
+/**
+ * Server rendering of the first HTML of a page (D-0039), in this process: the SSR build output is
+ * imported once at start and its `render(page)` is called for every full page load.
+ */
+export interface InertiaSsrOptions {
+    /** SSR build output exporting `render(page)`, relative to the working directory or absolute. */
+    readonly bundle: string;
+    /**
+     * When render throws: `fallback` (default) answers the client-rendered page and logs the error;
+     * `error` fails the request, which is easier to notice while developing.
+     */
+    readonly failure?: 'fallback' | 'error';
+}
+/** Counts since start, for health checks and dashboards. */
+export interface InertiaSsrStats {
+    readonly renders: number;
+    readonly failures: number;
+}
+/** Document settings for one part of the app (for example one app of @dokebi/app). */
+export interface InertiaScopeOptions {
+    readonly title?: string;
+    readonly rootId?: string;
+    readonly version?: string;
+    readonly scripts?: readonly string[];
+    readonly styles?: readonly string[];
+    readonly vite?: {
+        readonly manifest: string;
+        readonly entry: string;
+        readonly base?: string;
+    };
+    /** Server rendering for this scope; unset uses the plugin's `ssr`, `false` turns it off. */
+    readonly ssr?: InertiaSsrOptions | false;
+    /** Props merged after the plugin's shared props for every page of this scope. */
+    readonly shared?: InertiaShared;
+}
+export interface InertiaPluginApi extends InertiaApi {
+    /**
+     * A renderer with its own document settings and extra shared props. Reads the Vite manifest
+     * when `vite` is given; unset fields come from the plugin options.
+     */
+    scope(options: InertiaScopeOptions): Promise<InertiaApi>;
+    /** Server renders and render failures of every scope since start (zero without `ssr`). */
+    ssrStats(): InertiaSsrStats;
+}
+/**
+ * Assets read from a Vite build manifest at setup: the entry script, the CSS of the entry and
+ * of the chunks it imports, and a version derived from the manifest content.
+ */
+export interface InertiaViteOptions {
+    /** Path of .vite/manifest.json, relative to the working directory, or absolute. */
+    readonly manifest: string;
+    /** Manifest key of the entry, usually its source path such as `client/main.ts`. */
+    readonly entry: string;
+    /** URL prefix the built files are served under. Default `/`. */
+    readonly base: string;
+}
+export declare const createPlugin: import("@dokebi/core").PluginFactory<InertiaPluginApi>;

package/dist/index.js

@@ -0,0 +1,299 @@
+import { createHash } from 'node:crypto';
+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, providerDependency, } from '@dokebi/core';
+import { InertiaResponder, normalizeInertiaOptions, } from './responder.js';
+const MANIFEST_MAX_BYTES = 4 * 1024 * 1024;
+function parseVite(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input) || types.isProxy(input))
+        throw new TypeError('Invalid Inertia vite options');
+    const { manifest, entry, base = '/', ...rest } = input;
+    if (Object.keys(rest).length ||
+        typeof manifest !== 'string' ||
+        !manifest ||
+        typeof entry !== 'string' ||
+        !entry ||
+        typeof base !== 'string' ||
+        !/^\/(?:[^/\\\s]+\/)*$/.test(base))
+        throw new TypeError('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');
+    const { bundle, failure = 'fallback', ...rest } = input;
+    if (Object.keys(rest).length ||
+        typeof bundle !== 'string' ||
+        !bundle ||
+        (failure !== 'fallback' && failure !== 'error'))
+        throw new TypeError('Invalid Inertia ssr options');
+    return Object.freeze({ bundle, failure });
+}
+/**
+ * Imports the SSR bundle. A missing file or a bundle without `render` stops the start: SSR that
+ * was asked for must not quietly become client rendering.
+ */
+async function loadBundle(bundle) {
+    const path = resolve(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 });
+    });
+    if (!info.isFile())
+        throw new Error(`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)`);
+    return module.render;
+}
+const CONTENT_TYPES = {
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.wasm': 'application/wasm',
+};
+/**
+ * Reads the manifest once and returns the document asset settings for the entry, plus the built
+ * files the entry can load (its chunks, their CSS and assets) so they can be served.
+ */
+async function viteAssets(vite) {
+    const path = resolve(vite.manifest);
+    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 });
+    });
+    if (!info.isFile() || info.size > MANIFEST_MAX_BYTES)
+        throw new Error('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));
+    const styles = [];
+    const files = new Map();
+    const strings = (value) => Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+    const serve = (file) => {
+        // Manifest paths are relative to outDir; anything that leaves it is not served.
+        if (typeof file !== 'string' || file.split('/').some((part) => part === '..' || !part))
+            return;
+        files.set(vite.base + file, join(outDir, file));
+    };
+    const seen = new Set();
+    // Static imports decide the document CSS; dynamic imports are only served.
+    const collect = (key, linked) => {
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        const chunk = Object.hasOwn(manifest, key) ? manifest[key] : undefined;
+        if (!chunk)
+            return;
+        serve(chunk.file);
+        for (const asset of strings(chunk.assets))
+            serve(asset);
+        for (const imported of strings(chunk.imports))
+            collect(imported, linked);
+        for (const imported of strings(chunk.dynamicImports))
+            collect(imported, false);
+        for (const css of strings(chunk.css)) {
+            serve(css);
+            if (linked && !styles.includes(vite.base + css))
+                styles.push(vite.base + css);
+        }
+    };
+    collect(vite.entry, true);
+    return {
+        scripts: [vite.base + entry.file],
+        styles,
+        version: createHash('sha256').update(text).digest('hex').slice(0, 32),
+        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'),
+});
+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');
+    return Object.freeze({
+        document: normalizeInertiaOptions(rest),
+        defaultVersion: false,
+        vite: parseVite(vite),
+        ...(ssr ? { ssr } : {}),
+    });
+}
+/** Accepts a plain object or the namespace of the user entry module (src/inertia/shared.ts). */
+function parseEntry(input) {
+    if (input === undefined)
+        return {};
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        types.isProxy(input) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(input)))
+        throw new TypeError('Invalid Inertia entry');
+    let shared;
+    for (const key of Reflect.ownKeys(input)) {
+        // Module namespaces carry Symbol.toStringTag; only string exports are entry fields.
+        if (typeof key !== 'string')
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(input, key);
+        if (key !== 'shared' || !descriptor || !('value' in descriptor))
+            throw new TypeError('Invalid Inertia entry');
+        shared = descriptor.value;
+    }
+    if (shared !== undefined && typeof shared !== 'function')
+        throw new TypeError('Inertia shared must be a function');
+    return shared === undefined ? {} : { shared: shared };
+}
+class InertiaRuntime {
+    settings;
+    shared;
+    constructor(settings, shared) {
+        this.settings = settings;
+        this.shared = shared;
+    }
+    async setup(context) {
+        if (this.settings.defaultVersion)
+            context.logger.log('warn', 'Inertia asset version is not configured', {
+                code: 'INERTIA_VERSION_DEFAULT',
+            });
+        const server = context.getDependency(web);
+        // Built files are served at their exact URL (no wildcard), once even if apps share chunks.
+        const served = new Set();
+        const built = async (options) => {
+            const { files, ...assets } = await viteAssets(options);
+            for (const [url, file] of files) {
+                if (served.has(url))
+                    continue;
+                served.add(url);
+                const type = CONTENT_TYPES[extname(file).toLowerCase()] ?? 'application/octet-stream';
+                server.route({
+                    method: 'GET',
+                    url,
+                    handler: async (_request, reply) => reply
+                        .type(type)
+                        .header('cache-control', 'public, max-age=31536000, immutable')
+                        .send(await readFile(file)),
+                });
+            }
+            return assets;
+        };
+        const document = this.settings.vite
+            ? normalizeInertiaOptions({
+                ...this.settings.document,
+                ...(await built(this.settings.vite)),
+            })
+            : this.settings.document;
+        // One import per bundle file, shared by the scopes that name it.
+        const bundles = new Map();
+        const stats = { renders: 0, failures: 0 };
+        const serverRendering = async (ssr) => {
+            if (!ssr)
+                return undefined;
+            const path = resolve(ssr.bundle);
+            let render = bundles.get(path);
+            if (!render) {
+                render = loadBundle(ssr.bundle);
+                bundles.set(path, render);
+            }
+            return Object.freeze({
+                render: await render,
+                failure: ssr.failure,
+                rendered: () => {
+                    stats.renders++;
+                },
+                failed: (error, component) => {
+                    stats.failures++;
+                    context.logger.log('error', 'Inertia SSR render failed', {
+                        code: 'INERTIA_SSR_FAILED',
+                        bundle: ssr.bundle,
+                        component,
+                        fallback: ssr.failure === 'fallback',
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                },
+            });
+        };
+        const responders = [];
+        context.defer(() => {
+            for (const responder of responders)
+                responder.close();
+        });
+        const api = (responder) => {
+            responders.push(responder);
+            return Object.freeze({
+                render: responder.render.bind(responder),
+                redirect: responder.redirect.bind(responder),
+                location: responder.location.bind(responder),
+            });
+        };
+        const root = api(new InertiaResponder(document, this.shared, await serverRendering(this.settings.ssr)));
+        const shared = this.shared;
+        return Object.freeze({
+            ...root,
+            ssrStats: () => Object.freeze({ ...stats }),
+            scope: async (options) => {
+                const { shared: extra, vite, ssr: ssrInput, ...fields } = (options ?? {});
+                const ssr = ssrInput === undefined ? this.settings.ssr : parseSsr(ssrInput);
+                if (extra !== undefined && typeof extra !== 'function')
+                    throw new TypeError('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');
+                const scoped = normalizeInertiaOptions({
+                    ...document,
+                    ...fields,
+                    ...(vite === undefined ? {} : await built(parseVite(vite))),
+                });
+                const merged = shared && extra
+                    ? async (request) => ({ ...(await shared(request)), ...(await extra(request)) })
+                    : (extra ?? shared);
+                return api(new InertiaResponder(scoped, merged, await serverRendering(ssr)));
+            },
+        });
+    }
+}
+export const createPlugin = definePlugin({
+    name: 'dokebi-template-inertia',
+    version: '0.1.1',
+    core: '^0.2.0',
+    options: parseOptions,
+    entry: parseEntry,
+    dependencies: () => [web],
+    instance: ({ options, entry }) => new InertiaRuntime(options, entry?.shared),
+});

package/dist/responder.d.ts

@@ -0,0 +1,56 @@
+import type { Awaitable } from '@dokebi/core';
+import type { FastifyReply, FastifyRequest } from 'fastify';
+export type Json = null | boolean | number | string | readonly Json[] | {
+    readonly [key: string]: Json;
+};
+export type Props = Readonly<Record<string, Json | (() => Awaitable<Json>)>>;
+export interface InertiaOptions {
+    version?: string;
+    rootId?: string;
+    title?: string;
+    scripts?: readonly string[];
+    styles?: readonly string[];
+}
+/** The page object Inertia hands to the client and to the SSR bundle. */
+export interface InertiaPage {
+    readonly component: string;
+    readonly props: Readonly<Record<string, Json>>;
+    readonly url: string;
+    readonly version: string;
+    readonly clearHistory: boolean;
+    readonly encryptHistory: boolean;
+}
+/** What an SSR bundle's `render(page)` returns: head tags and the root (script + element). */
+export interface InertiaSsrResult {
+    readonly head: readonly string[];
+    readonly body: string;
+}
+/**
+ * Server rendering of the first HTML (D-0039). `failure: 'fallback'` answers a render error with
+ * the client-rendered page; `'error'` lets the request fail. `failed` sees every error either way.
+ */
+export interface InertiaSsr {
+    readonly render: (page: InertiaPage) => Promise<InertiaSsrResult>;
+    readonly failure: 'fallback' | 'error';
+    readonly rendered?: () => void;
+    readonly failed?: (error: unknown, component: string) => void;
+}
+export interface InertiaApi {
+    render(request: FastifyRequest, reply: FastifyReply, component: string, props?: Props): Promise<FastifyReply>;
+    redirect(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply;
+    location(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply;
+}
+export type NormalizedInertiaOptions = Readonly<Required<InertiaOptions>>;
+/** Validates and fills defaults; the result is accepted again unchanged. */
+export declare function normalizeInertiaOptions(options?: InertiaOptions): NormalizedInertiaOptions;
+export declare class InertiaResponder implements InertiaApi {
+    #private;
+    readonly shared?: ((request: FastifyRequest) => Awaitable<Props>) | undefined;
+    readonly ssr?: InertiaSsr | undefined;
+    readonly options: NormalizedInertiaOptions;
+    constructor(options?: InertiaOptions, shared?: ((request: FastifyRequest) => Awaitable<Props>) | undefined, ssr?: InertiaSsr | undefined);
+    close(): void;
+    render(request: FastifyRequest, reply: FastifyReply, component: string, input?: Props): Promise<never>;
+    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

@@ -0,0 +1,182 @@
+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');
+    return value;
+}
+function vary(reply) {
+    const values = String(reply.getHeader('vary') ?? '')
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (!values.some((value) => value.toLowerCase() === 'x-inertia') && !values.includes('*'))
+        values.push('X-Inertia');
+    reply.header('Vary', values.join(', '));
+    // Page props may contain user-specific state, including on version mismatch responses.
+    reply.header('Cache-Control', 'no-store');
+}
+/** 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');
+    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');
+    }
+    const normalized = {
+        version: options.version ?? 'development',
+        rootId: options.rootId ?? 'app',
+        title: options.title ?? '',
+        scripts: Object.freeze([...(options.scripts ?? [])]),
+        styles: Object.freeze([...(options.styles ?? [])]),
+    };
+    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');
+    for (const asset of [...normalized.scripts, ...normalized.styles])
+        localUrl(asset);
+    return Object.freeze(normalized);
+}
+export class InertiaResponder {
+    shared;
+    ssr;
+    options;
+    #closed = false;
+    constructor(options = {}, shared, ssr) {
+        this.shared = shared;
+        this.ssr = ssr;
+        this.options = normalizeInertiaOptions(options);
+    }
+    close() {
+        this.#closed = true;
+    }
+    #check() {
+        if (this.#closed)
+            throw new Error('Inertia responder is closed');
+    }
+    async render(request, reply, component, input = {}) {
+        this.#check();
+        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');
+        vary(reply);
+        const inertia = request.headers['x-inertia'] === 'true';
+        if (inertia &&
+            request.headers['x-inertia-version'] !== undefined &&
+            request.headers['x-inertia-version'] !== this.options.version) {
+            return reply
+                .code(409)
+                .header('X-Inertia-Location', localUrl(request.url))
+                .header('X-Inertia-Version', this.options.version)
+                .send();
+        }
+        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'
+            ? new Set(request.headers[key]
+                .split(',')
+                .map((x) => x.trim())
+                .filter(Boolean))
+            : new Set();
+        const only = list('x-inertia-partial-data'), except = list('x-inertia-partial-except');
+        const selected = Object.entries(props).filter(([key]) => key === 'errors' || !partial || !((only.size > 0 && !only.has(key)) || except.has(key)));
+        // Lazy props run concurrently; every rejection is observed by Promise.all.
+        const values = await Promise.all(selected.map(async ([, value]) => (typeof value === 'function' ? await value() : value)));
+        const resolved = Object.create(null);
+        resolved.errors = {};
+        selected.forEach(([key], index) => {
+            resolved[key] = values[index];
+        });
+        const page = {
+            component,
+            props: resolved,
+            url: request.url,
+            version: this.options.version,
+            clearHistory: false,
+            encryptHistory: false,
+        };
+        // 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;
+        });
+        if (inertia)
+            return reply.header('X-Inertia', 'true').type('application/json; charset=utf-8').send(json);
+        const { rootId, title, scripts, styles } = this.options;
+        // 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
+            .replace(/</g, '\\u003c')
+            .replace(/\//g, '\\/')
+            .replace(/\u2028/g, '\\u2028')
+            .replace(/\u2029/g, '\\u2029');
+        // A <title> from the page's <Head> replaces the configured one.
+        const head = rendered?.head ?? [];
+        const titled = head.some((tag) => /^<title[\s>]/i.test(tag));
+        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">${titled ? '' : `<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.join('')}</head><body>${rendered?.body ?? `<script data-page="${rootId}" type="application/json">${safeJson}</script><div id="${rootId}"></div>`}</body></html>`);
+    }
+    /**
+     * The SSR bundle's head and root for this page, or undefined to answer client rendered
+     * (failure 'fallback'). The page object is a fresh copy, so the bundle cannot change the props.
+     */
+    async #serverRender(page, rootId) {
+        const ssr = this.ssr;
+        try {
+            const result = await ssr.render(page);
+            const { head, body } = (result ?? {});
+            if (!Array.isArray(head) ||
+                head.some((tag) => typeof tag !== 'string') ||
+                typeof body !== 'string')
+                throw new TypeError('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)`);
+            ssr.rendered?.();
+            return { head, body };
+        }
+        catch (error) {
+            ssr.failed?.(error, page.component);
+            if (ssr.failure === 'error')
+                throw error;
+            return undefined;
+        }
+    }
+    redirect(request, reply, url) {
+        this.#check();
+        localUrl(url);
+        vary(reply);
+        if (request.headers['x-inertia'] === 'true' && url.includes('#'))
+            return reply.code(409).header('X-Inertia-Redirect', url).send();
+        return reply.redirect(url, ['GET', 'HEAD'].includes(request.method) ? 302 : 303);
+    }
+    location(request, reply, url) {
+        this.#check();
+        if (url.startsWith('/'))
+            localUrl(url);
+        else if (!/^https?:$/.test(new URL(url).protocol) || /[\r\n]/.test(url))
+            throw new TypeError('Invalid location');
+        vary(reply);
+        return request.headers['x-inertia'] === 'true'
+            ? reply.code(409).header('X-Inertia-Location', url).send()
+            : reply.redirect(url, 302);
+    }
+}

package/options.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "rootId": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
+    },
+    "title": {
+      "type": "string"
+    },
+    "scripts": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^/[^/]"
+      }
+    },
+    "styles": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^/[^/]"
+      }
+    },
+    "vite": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["manifest", "entry"],
+      "description": "Read scripts, styles and version from a Vite build manifest at startup. Replaces version, scripts and styles.",
+      "properties": {
+        "manifest": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path of .vite/manifest.json, relative to the working directory"
+        },
+        "entry": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Manifest key of the entry, e.g. src/apps/<app>/views/app.js"
+        },
+        "base": {
+          "type": "string",
+          "pattern": "^/(?:[^/\\\\\\s]+/)*$",
+          "description": "URL prefix of the built files (default /)"
+        }
+      }
+    },
+    "ssr": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["bundle"],
+      "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.",
+      "properties": {
+        "bundle": {
+          "type": "string",
+          "minLength": 1,
+          "description": "SSR build output that exports render(page), relative to the working directory, e.g. dist/ssr/<app>/ssr.js"
+        },
+        "failure": {
+          "enum": ["fallback", "error"],
+          "description": "When render throws: answer the client-rendered page and log (fallback, default) or fail the request (error)"
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@dokebi/template-inertia",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "options.schema.json",
+    "README.md",
+    "AI.md",
+    "LICENSE",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test .tmp/tests/tests/*.test.js"
+  },
+  "peerDependencies": {
+    "@dokebi/core": "^0.2.0",
+    "@dokebi/web": "^0.1.0",
+    "fastify": "^5.12.7"
+  },
+  "dokebi": {
+    "schemaVersion": 2,
+    "id": "dokebi-template-inertia",
+    "core": "^0.2.0",
+    "dependencies": [
+      {
+        "name": "dokebi-web",
+        "version": "^0.1.0"
+      }
+    ],
+    "install": {
+      "entry": {
+        "source": "templates/shared.ts",
+        "target": "src/infra/inertia/shared.ts"
+      }
+    },
+    "optionsSchema": "options.schema.json",
+    "documentation": "AI.md"
+  },
+  "devDependencies": {
+    "@dokebi/web": "0.1.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/templates/shared.ts

@@ -0,0 +1,7 @@
+import type { FastifyRequest } from 'fastify';
+
+// dokebi-template-inertia entry (src/infra/inertia/shared.ts). Props returned here are merged into every page, before the
+// props passed to render(). Never put secrets here; derive user data from your own auth.
+export async function shared(_request: FastifyRequest) {
+  return {};
+}