@dokebi/template-inertia 0.1.1 → 0.1.3

package/AI.md

@@ -1,4 +1,4 @@
-# AI 작업 안내 — @dokebi/template-inertia 0.1.1
+# AI 작업 안내 — @dokebi/template-inertia 0.1.3
 
 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)다.
 
@@ -21,7 +21,7 @@ npm run build                                       # dist/(브라우저) + dist
 | `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` |
+| `ssr: { bundle, failure?, entry? }` | 서버 렌더링. `failure`: `fallback`(기본) · `error`. `entry`는 개발 모드에서 쓰는 번들의 원본 모듈(§5.1) |
 
 ## 3. 페이지 렌더
 
@@ -40,12 +40,50 @@ route.post('/orders', async (request, reply, page) => {
 ```
 
 - `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 값·순환은 실패.
+- props: JSON 값, 비동기 lazy 함수, 또는 §3.1 도우미. 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`.
+
+### 3.1 deferred·merge·once props(D-0052)
+
+```ts
+import { defer, merge, deepMerge, once } from '@dokebi/template-inertia';
+page.inertia!.render(request, reply, 'Orders/Index', {
+  orders: merge(() => listOrders(page), { matchOn: 'id' }), // partial reload 때 배열 뒤에 붙임(같은 id는 교체)
+  stats: defer(() => computeStats()),                       // 첫 페이지에서 빼고 화면 뒤 group 'default'로 가져옴
+  chart: defer(() => chart(), 'charts'),                    // group마다 요청 하나
+  feed: defer(() => feed(), { merge: true, rescue: true }), // 던지면 빼고 rescuedProps + error 로그
+  plans: once(() => listPlans(), { ttlMs: 3_600_000 }),     // 클라이언트가 가지면 다시 계산 안 함
+  settings: deepMerge({ theme: { dark: true } }),
+});
+```
+
+- `defer(fn, group? | { group?, merge?, once?, rescue? })`: 첫 로드(HTML·Inertia 방문)에서 계산하지 않고 page `deferredProps: { group: [이름] }`. 클라이언트가 `only`로 다시 요청할 때만 `fn`이 돈다. SSR 첫 HTML에도 값이 없다(Vue `<Deferred data="stats">`의 `#fallback`).
+- `merge(value | fn, { mode?: 'append' | 'prepend' | 'deep', matchOn? })`, `deepMerge(value | fn, { matchOn? })`: page `mergeProps`·`prependProps`·`deepMergeProps`·`matchPropsOn`(`"<prop>.<필드>"`). 클라이언트는 **partial reload에서만** 합친다(`router.reload({ only: ['orders'], data: { page: 2 } })`). `X-Inertia-Reset`(`reset: ['orders']`)이면 합치지 않고 바꾼다.
+- `once(value | fn, { key?, ttlMs? })`: page `onceProps: { key: { prop, expiresAt } }`. 클라이언트가 `X-Inertia-Except-Once-Props`로 가진 key를 알리면 첫 로드에서 계산하지 않는다. partial reload가 그 prop을 `only`로 요청하면 다시 계산한다.
+- 도우미는 `render` props·`shared` props 어디든 쓴다. 서로 감싸지 않는다(조합은 `defer` 옵션). group·key·matchOn에 쉼표·공백 금지.
+- partial reload는 지금처럼 `only`·`except`로 고르고, 고른 deferred·once도 계산한다(`except`만 주면 deferred도 포함). 알림 필드도 고른 props만.
+- rescue가 아닌 prop 함수의 실패는 지금처럼 요청 실패(500, web이 전체 오류 로그). rescue는 `INERTIA_PROP_RESCUED`(error, 10초에 한 번·`repeated`). debug: `Inertia props resolved`(evaluated·deferred·heldOnce·rescued), `Inertia prop failed`.
 - 오래된 version의 Inertia 요청은 props 평가 없이 409 + `X-Inertia-Location`(새로고침 유도).
 - 응답에 `Vary: X-Inertia`, `Cache-Control: no-store`가 붙고 HTML에 넣는 JSON·제목·URL은 escape된다.
 
+### 3.2 session flash(D-0055)
+
+@dokebi/session이 앱에 등록돼 있으면(선택 의존성, 자동으로 만들지 않음) 페이지 응답의 page **`flash` 필드**에 세션 flash가 들어간다. `takeFlash()`와 같아서 한 번 보이면 사라진다. 비어 있으면 필드가 없다. prop이 아니다(`props.flash` 아님).
+
+```ts
+route.post('/orders', async (request, reply, page) => {
+  await createOrder(request.body);
+  await request.session.flash('success', 'Order saved');      // @dokebi/session
+  return page.inertia!.redirect(request, reply, '/orders');   // 303
+});
+// Vue: usePage().flash.success, 또는 router.on('flash', (event) => toast(event.detail.flash))
+```
+
+- 클라이언트(3.9.1)는 flash를 history에 넣지 않아 뒤로 가기에 다시 보이지 않는다.
+- deferred props만 가져오는 partial reload는 flash를 읽지 않는다(클라이언트가 버리므로). 첫 HTML·방문·그 밖의 partial reload는 읽는다. props 평가가 실패한 렌더는 flash를 남긴다.
+- 세션 플러그인이 없으면 page는 전과 같다.
+
 ## 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가 없으면 시작 실패.
@@ -54,11 +92,24 @@ route.post('/orders', async (request, reply, page) => {
 
 - `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).
+- 요청 중 render가 던지거나 모양이 틀리거나 body에 `id="<rootId>"`가 없으면: `fallback`은 그 요청을 CSR로 답하고 `INERTIA_SSR_FAILED`(error) 로그, `error`는 요청 실패(500). 로그의 `error`는 이름·전체 메시지·스택·`Caused by:` 원인, URL 인증 정보만 `//***@`로 지우고 16KB 넘으면 잘라 표시이고, 같은 번들·컴포넌트는 10초에 한 번만 남기며 사이 횟수는 다음 로그의 `repeated`(D-0047). `ssrStats().failures`는 모두 센다.
 - head에 `<title>`이 있으면 설정 title은 빠진다. Inertia 이동(JSON)은 SSR을 거치지 않는다.
 - 브라우저 진입은 `el.hasAttribute('data-server-rendered')`면 `createSSRApp`으로 hydration한다. 서버·브라우저가 같은 레이아웃을 고르도록 페이지 모듈을 바꾸지 말고 `layout` 옵션을 쓴다(동시에 여러 템플릿을 그리므로).
 - `ssrStats()` → `{ renders, failures }`(health·대시보드용). `scope({ ssr: false })`로 앱별로 끌 수 있다.
 
+## 5.1 개발 모드(HMR, D-0045)
+
+- 환경 변수 `DOKEBI_VITE_DEV=1`(`dokebi dev`가 넣는다)이면 manifest·빌드 없이 **프로젝트의 Vite를 미들웨어 모드로** 한 프로세스에 하나 띄운다. 페이지 스크립트는 `<base>@vite/client`와 `<base><vite.entry>`, 스타일 링크 없음, version `dev`. `<base>*` 요청은 Vite가 답한다.
+- HMR 소켓은 프로세스마다 빈 포트 하나를 따로 쓴다(앱 포트는 @dokebi/websocket이 upgrade를 모두 받으므로). 브라우저는 페이지와 같은 호스트로 붙는다.
+- SSR은 요청마다 `ssrLoadModule(<원본 진입>)`. 원본 진입은 `ssr.entry`(예: `src/apps/admin/views/ssr.js`), 없으면 `vite.entry`와 같은 폴더의 `ssr.js`. 둘 다 없으면 시작 실패.
+- Vite가 프로젝트에 없으면 시작 실패(`npm install --save-dev vite`).
+- 호스트: Vite 자체 검사(`allowedHosts`)는 끄고, `<base>*`는 루프백 이름(`localhost`·`*.localhost`·127.x·::1), @dokebi/app의 `domains`, 이 프로세스가 Inertia 페이지로 답한 호스트에만 답한다(나머지 403). 그래서 hosts 파일·터널의 앱 도메인(예: `a.com`)으로도 개발할 수 있고 DNS rebinding은 막힌다.
+- cluster 앱은 `dokebi dev`에서 워커 1개로 돈다(@dokebi/cluster 0.1.2).
+- 절대 경로 import를 빌드에서 `external`로 둔 경우, 개발 서버는 그 경로 앞에 `<base>`를 붙인다. 개발 서버에서는 실제 파일로 풀어 주는 Vite 플러그인을 쓴다(플레이그라운드 `vite.config.ts` 참고).
+- 운영(`DOKEBI_VITE_DEV` 없음)에는 영향이 없다. 운영 서버에 이 변수를 넣지 않는다.
+- Vite 미들웨어가 오류를 넘기면 500으로 답하고 `INERTIA_VITE_DEV_FAILED`(error, 10초에 한 번·`repeated`) 로그를 남긴다. 처리할 것이 없을 때만 404.
+- debug 로그(D-0047): `Inertia settings resolved`·`Vite dev server started`(ms)·`Vite dev route registered`·`Vite manifest read`·`Inertia SSR bundle loaded`·`Inertia SSR renders the source through Vite`(쓰인 원본)·`Inertia scope created`, 요청마다는 개발 경로가 거절한 호스트 `Vite dev route refused a host`(debug가 켜졌을 때만).
+
 ## 6. 범위(scope)
 
 `await api.scope({ title?, rootId?, version?, scripts?, styles?, vite?, ssr?, shared? })` → 그 설정의 렌더러. 정하지 않은 값은 플러그인 옵션, `shared`는 플러그인 shared 뒤에 합쳐진다. @dokebi/app이 앱마다 부른다.
@@ -68,7 +119,7 @@ route.post('/orders', async (request, reply, page) => {
 - props에 비밀·개인정보를 넣지 않는다(HTML에 그대로 실린다). 인증·인가·CSRF는 앱이 구현한다.
 - 데이터 조회·수정 API는 Inertia 응답이 아니라 일반 JSON 라우트(REST)로 만든다.
 - 배포에는 빌드별 version(또는 `vite`)을 꼭 쓴다. 기본 version이면 자산이 바뀌어도 클라이언트가 모른다.
-- deferred·merge·once props, Precognition, session flash는 없다. 있다고 가정하지 않는다.
+- Precognition, `scrollProps`(무한 스크롤), `sharedProps`, 점 경로 partial reload(`only: ['user.name']`)는 없다. 있다고 가정하지 않는다. session flash는 @dokebi/session이 있을 때만(§3.2).
 - 앱 인스턴스마다 새 플러그인. 전체 drain 뒤에 responder가 닫힌다.
 
-근거: `examples/24-template-inertia`(실제 Chrome: CSR·SSR·cluster, 측정), `examples/26-scaffold`(CLI가 만든 SSR 앱의 빌드·서버 렌더), `examples/25-playground`, D-0027·D-0031·D-0039.
+근거: `examples/24-template-inertia`(실제 Chrome: CSR·SSR·cluster, 측정), `examples/26-scaffold`(CLI가 만든 SSR 앱의 빌드·서버 렌더), `examples/25-playground`, `tests/flash.test.ts`(세션 flash), D-0027·D-0031·D-0039·D-0045·D-0052·D-0055.

package/README.md

@@ -1,4 +1,4 @@
-# @dokebi/template-inertia 0.1.1
+# @dokebi/template-inertia 0.1.3
 
 Node >=24.0.0, core ^0.2.0, 선택 패키지다(npm 공개). ID는 `dokebi-template-inertia`이며 `dokebi-web`에 의존한다. `@dokebi/web`은 peer 의존성이다(예전의 고정 버전 dependency가 아니다). EJS·Vue·Vite를 서버 패키지의 필수 의존성으로 설치하지 않는다.
 
@@ -31,7 +31,7 @@ dokebi-template-inertia:
 
 잘못된 옵션은 팩토리에서 `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을 반환한다.
+props는 JSON 값, 비동기 lazy 함수 또는 deferred/merge/once 도우미(아래 절)다. 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다. 외부 목적지는 신뢰된 앱 코드에서 선택한다.
 
@@ -43,7 +43,7 @@ Vue 페이지 이동·초기 props는 Inertia, 이후 조회·수정은 `fetch('
 
 `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 클라이언트 책임이다.
+지원 범위는 초기 HTML·페이지 이동·shared/lazy/partial props·deferred/merge/once props(아래 절)·redirect·version 협상·서버 렌더링(아래 SSR 절)이다. Precognition, Inertia form 검증 redirect 저장소, `scrollProps`·`sharedProps`는 제공하지 않는다. session flash는 [@dokebi/session](../dokebi-session/README.md)이 등록돼 있을 때 page `flash` 필드로 전달된다([D-0055](../../docs/decisions/D-0055-session-store.md), 한 번 읽기). 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 프로토콜 회귀다.
 
@@ -51,6 +51,16 @@ Vue 페이지 이동·초기 props는 Inertia, 이후 조회·수정은 `fetch('
 
 `scope({ title?, rootId?, version?, scripts?, styles?, vite?, shared? })`는 자기 문서 설정과 추가 공통 props를 가진 렌더러를 돌려준다(비동기, `vite`면 manifest를 읽는다). 정하지 않은 값은 플러그인 옵션을 따른다. `shared`는 플러그인 공통 props 뒤에 합쳐진다. @dokebi/app이 앱마다 다른 Vite 진입점에 쓴다.
 
+## deferred·merge·once props([D-0052](../../docs/decisions/D-0052-inertia-deferred-merge-once.md))
+
+`defer`·`merge`·`deepMerge`·`once`를 import해 prop 값 자리(render props·shared props)에 쓴다. 일반 값·lazy 함수만 쓰면 page 객체는 예전과 같다.
+
+- `defer(fn, group?)` 또는 `defer(fn, { group?, merge?, once?, rescue? })`: 첫 로드(HTML·Inertia 방문, SSR 포함)에서 계산하지 않고 `deferredProps: { [group]: [prop] }`로 알린다(기본 group `default`). 클라이언트는 화면을 보인 뒤 group마다 partial reload 한 번으로 가져온다. `rescue: true`면 함수가 던질 때 그 prop만 빼고 `rescuedProps`에 넣으며 `INERTIA_PROP_RESCUED` 오류 로그를 남긴다.
+- `merge(value | fn, { mode?, matchOn? })`·`deepMerge(value | fn, { matchOn? })`: `mergeProps`(append)·`prependProps`·`deepMergeProps`, `matchOn`은 `matchPropsOn: ["<prop>.<필드>"]`. 클라이언트는 같은 컴포넌트의 partial reload에서만 합친다. `X-Inertia-Reset`에 든 prop은 알리지 않는다.
+- `once(value | fn, { key?, ttlMs? })`: `onceProps: { [key]: { prop, expiresAt } }`(`expiresAt`은 ms, 없으면 null). Inertia 방문의 `X-Inertia-Except-Once-Props`에 key가 있으면 계산하지 않는다(알림은 남겨 클라이언트가 가진 값을 옮긴다). partial reload가 요청하면 다시 계산한다.
+- partial reload는 `only`·`except`로 고른 것만 계산하며 deferred·once도 같다. 알림 필드도 고른 props만 적는다.
+- 오류: rescue가 아닌 함수의 실패는 예전처럼 render 실패(web이 500·전체 오류 로그). debug 로그 `Inertia props resolved`에 계산한 함수 prop·뺀 group·건너뛴 once·rescue가 나온다.
+
 ## 서버 렌더링(SSR, D-0039)
 
 `ssr: { bundle, failure? }`를 주면 페이지의 첫 HTML을 서버에서 그린다. 별도 SSR 프로세스 없이 같은 프로세스에서 SSR 빌드 산출물을 시작 때 한 번 import하고, 전체 페이지 요청마다 그 `render(page)`를 부른다. Inertia 이동(`X-Inertia`)은 지금처럼 JSON이고 SSR을 거치지 않는다.
@@ -64,3 +74,7 @@ Vue 페이지 이동·초기 props는 Inertia, 이후 조회·수정은 `fetch('
 - `scope({ ssr })`: 앱마다 번들을 정한다. 생략하면 플러그인 옵션을 따르고 `false`면 끈다. 같은 파일은 한 번만 import한다.
 
 측정(예제 24, 같은 프로세스, 순차 400회): CSR 0.20~0.24ms, SSR 0.24~0.28ms(작은 페이지), SSR 450장 뒤 heap +1.1MB.
+
+## 개발 모드(HMR, [D-0045](../../docs/decisions/D-0045-inertia-vite-dev.md))
+
+`DOKEBI_VITE_DEV=1`(`dokebi dev`가 넣는다)이면 빌드 없이 프로젝트의 Vite를 미들웨어 모드로 띄워 `<base>*`를 Vite가 답하고, 페이지는 `@vite/client`와 원본 진입을 불러온다. `.vue`를 고치면 새로고침 없이 바뀐다(HMR 소켓은 프로세스마다 따로 잡은 빈 포트). SSR은 요청마다 Vite로 원본(`ssr.entry`, 없으면 `vite.entry` 옆 `ssr.js`)을 그린다. 운영에는 영향이 없다.

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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 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 InertiaShared = (request: FastifyRequest) => Awaitable<Props>;
 export interface InertiaEntry {
     readonly shared?: InertiaShared;
@@ -18,6 +19,11 @@ export interface InertiaSsrOptions {
      * `error` fails the request, which is easier to notice while developing.
      */
     readonly failure?: 'fallback' | 'error';
+    /**
+     * Source module of the bundle (for example `src/apps/admin/views/ssr.js`), rendered through
+     * Vite in development (D-0045). Default: `ssr.js` beside the `vite.entry` when it exists.
+     */
+    readonly entry?: string;
 }
 /** Counts since start, for health checks and dashboards. */
 export interface InertiaSsrStats {

package/dist/index.js

@@ -1,10 +1,14 @@
 import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
 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 { 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';
+export { deepMerge, defer, InertiaProp, isInertiaProp, merge, once, } from './props.js';
 const MANIFEST_MAX_BYTES = 4 * 1024 * 1024;
 function parseVite(input) {
     if (input === null || typeof input !== 'object' || Array.isArray(input) || types.isProxy(input))
@@ -25,13 +29,14 @@ function parseSsr(input) {
         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;
+    const { bundle, failure = 'fallback', entry, ...rest } = input;
     if (Object.keys(rest).length ||
         typeof bundle !== 'string' ||
         !bundle ||
-        (failure !== 'fallback' && failure !== 'error'))
+        (failure !== 'fallback' && failure !== 'error') ||
+        (entry !== undefined && (typeof entry !== 'string' || !entry || entry.includes('..'))))
         throw new TypeError('Invalid Inertia ssr options');
-    return Object.freeze({ bundle, failure });
+    return Object.freeze({ bundle, failure, ...(entry ? { entry: entry } : {}) });
 }
 /**
  * Imports the SSR bundle. A missing file or a bundle without `render` stops the start: SSR that
@@ -136,6 +141,10 @@ const web = providerDependency({
     packageName: '@dokebi/web',
     load: () => import('@dokebi/web'),
 });
+const session = optionalDependency({
+    name: 'dokebi-session',
+    version: '^0.1.0',
+});
 function parseOptions(input) {
     const { vite, ssr: ssrInput, ...rest } = (input ?? {});
     const ssr = parseSsr(ssrInput);
@@ -194,10 +203,119 @@ class InertiaRuntime {
                 code: 'INERTIA_VERSION_DEFAULT',
             });
         const server = context.getDependency(web);
+        const logger = context.logger;
+        const sessions = context.getOptionalDependency(session);
+        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`.
+        const develop = viteDevRequested();
+        logger.log('debug', 'Inertia settings resolved', {
+            develop,
+            vite: this.settings.vite ? { ...this.settings.vite } : false,
+            ssr: this.settings.ssr ? { ...this.settings.ssr } : false,
+            defaultVersion: this.settings.defaultVersion,
+            shared: this.shared !== undefined,
+            flash: flash !== undefined,
+        });
+        // Per-request failures are logged once per interval with the count of repeats (D-0047).
+        const repeats = new Repeats();
+        let devServer;
+        const devBases = new Set();
+        // Vite refuses hosts other than localhost (DNS rebinding). Its check is off; instead the dev
+        // routes serve loopback names, the domains of @dokebi/app (the same in every cluster worker)
+        // and hosts this process answered with an Inertia page. An app domain (a.com through a hosts
+        // file or a tunnel) works; an unknown host does not.
+        const appDomains = context.app.config['dokebi-app']
+            ?.domains;
+        const pageHosts = new Set(Object.keys(appDomains ?? {}).map((host) => host.toLowerCase().replace(/:\d+$/, '')));
+        const hostName = (request) => server
+            .requestHost(request)
+            .replace(/:\d+$/, '')
+            .replace(/^\[(.*)\]$/, '$1');
+        const devHostAllowed = (host) => host === 'localhost' ||
+            host.endsWith('.localhost') ||
+            host === '::1' ||
+            /^127\.\d+\.\d+\.\d+$/.test(host) ||
+            pageHosts.has(host);
+        // Registered now: scopes are created later, from other plugins' setup.
+        context.defer(async () => {
+            if (devServer)
+                await (await devServer).close();
+        });
+        const viteDev = (base) => {
+            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', {
+                        ms: Math.round(performance.now() - begin),
+                        hosts: [...pageHosts].slice(0, 64),
+                    });
+                    return started;
+                });
+                context.logger.log('info', 'Inertia views are served by the Vite dev server', {
+                    code: 'INERTIA_VITE_DEV',
+                });
+            }
+            const current = devServer;
+            if (!devBases.has(base)) {
+                devBases.add(base);
+                // Modules, pre-bundled dependencies and @vite/client, under the Vite base.
+                server.route({
+                    method: 'GET', // Fastify adds HEAD
+                    url: `${base}*`,
+                    handler: async (request, reply) => {
+                        const host = hostName(request);
+                        if (!devHostAllowed(host)) {
+                            if (logger.isEnabled('debug'))
+                                logger.log('debug', 'Vite dev route refused a host', {
+                                    host: host.slice(0, 253),
+                                    base,
+                                });
+                            return reply
+                                .code(403)
+                                .type('text/plain; charset=utf-8')
+                                .send('This host has not been served an Inertia page by this app.');
+                        }
+                        const vite = await current;
+                        reply.hijack();
+                        vite.middlewares(request.raw, reply.raw, (error) => viteFallthrough(reply.raw, error, (failure) => {
+                            const repeated = repeats.take(`vite ${failure instanceof Error ? failure.name : typeof failure}`);
+                            if (repeated !== undefined)
+                                logger.log('error', 'Vite dev middleware failed', {
+                                    code: 'INERTIA_VITE_DEV_FAILED',
+                                    base,
+                                    error: errorText(failure),
+                                    ...(repeated ? { repeated } : {}),
+                                });
+                        }));
+                    },
+                });
+                logger.log('debug', 'Vite dev route registered', { url: `${base}*` });
+            }
+            return current;
+        };
         // Built files are served at their exact URL (no wildcard), once even if apps share chunks.
         const served = new Set();
         const built = async (options) => {
+            if (develop) {
+                await viteDev(options.base);
+                return {
+                    scripts: [`${options.base}@vite/client`, `${options.base}${options.entry}`],
+                    styles: [],
+                    version: 'dev',
+                };
+            }
             const { files, ...assets } = await viteAssets(options);
+            logger.log('debug', 'Vite manifest read', {
+                manifest: options.manifest,
+                entry: options.entry,
+                scripts: assets.scripts,
+                styles: assets.styles.length,
+                files: files.size,
+                version: assets.version,
+            });
             for (const [url, file] of files) {
                 if (served.has(url))
                     continue;
@@ -223,14 +341,43 @@ class InertiaRuntime {
         // 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) => {
+        const serverRendering = async (ssr, vite) => {
             if (!ssr)
                 return undefined;
-            const path = resolve(ssr.bundle);
-            let render = bundles.get(path);
-            if (!render) {
-                render = loadBundle(ssr.bundle);
-                bundles.set(path, render);
+            let render;
+            if (develop) {
+                // The source module through Vite on every render: an edit shows in the next first HTML.
+                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`);
+                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);
+                });
+            }
+            else {
+                const path = resolve(ssr.bundle);
+                render = bundles.get(path);
+                if (!render) {
+                    const begin = performance.now();
+                    render = loadBundle(ssr.bundle);
+                    bundles.set(path, render);
+                    await render;
+                    logger.log('debug', 'Inertia SSR bundle loaded', {
+                        bundle: path,
+                        failure: ssr.failure,
+                        ms: Math.round(performance.now() - begin),
+                    });
+                }
             }
             return Object.freeze({
                 render: await render,
@@ -240,13 +387,17 @@ class InertiaRuntime {
                 },
                 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),
-                    });
+                    // Every failure counts in ssrStats; the log repeats once per interval per component.
+                    const repeated = repeats.take(`ssr ${ssr.bundle} ${component}`);
+                    if (repeated !== undefined)
+                        context.logger.log('error', 'Inertia SSR render failed', {
+                            code: 'INERTIA_SSR_FAILED',
+                            bundle: ssr.bundle,
+                            component,
+                            fallback: ssr.failure === 'fallback',
+                            error: errorText(error),
+                            ...(repeated ? { repeated } : {}),
+                        });
                 },
             });
         };
@@ -257,13 +408,21 @@ class InertiaRuntime {
         });
         const api = (responder) => {
             responders.push(responder);
+            const render = responder.render.bind(responder);
             return Object.freeze({
-                render: responder.render.bind(responder),
+                render: develop
+                    ? (request, reply, component, props) => {
+                        pageHosts.add(hostName(request));
+                        return render(request, reply, component, props);
+                    }
+                    : render,
                 redirect: responder.redirect.bind(responder),
                 location: responder.location.bind(responder),
             });
         };
-        const root = api(new InertiaResponder(document, this.shared, await serverRendering(this.settings.ssr)));
+        // 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 shared = this.shared;
         return Object.freeze({
             ...root,
@@ -283,17 +442,26 @@ class InertiaRuntime {
                 const merged = shared && extra
                     ? async (request) => ({ ...(await shared(request)), ...(await extra(request)) })
                     : (extra ?? shared);
-                return api(new InertiaResponder(scoped, merged, await serverRendering(ssr)));
+                const scopedVite = vite === undefined ? this.settings.vite : parseVite(vite);
+                const responder = new InertiaResponder(scoped, merged, await serverRendering(ssr, scopedVite), diagnostics, flash);
+                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,
+                });
+                return api(responder);
             },
         });
     }
 }
 export const createPlugin = definePlugin({
     name: 'dokebi-template-inertia',
-    version: '0.1.1',
+    version: '0.1.3',
     core: '^0.2.0',
     options: parseOptions,
     entry: parseEntry,
-    dependencies: () => [web],
+    dependencies: () => [web, session],
     instance: ({ options, entry }) => new InertiaRuntime(options, entry?.shared),
 });

package/dist/props.d.ts

@@ -0,0 +1,77 @@
+import type { Awaitable } from '@dokebi/core';
+import type { Json } from './responder.js';
+/** A prop value or a function that computes it when the prop is sent. */
+export type PropValue = Json | (() => Awaitable<Json>);
+/** How the client combines a merge prop with the value it already holds (partial reloads only). */
+export interface MergeOptions {
+    /** `append` (default) adds arrays at the end, `prepend` at the start, `deep` merges nested. */
+    readonly mode?: 'append' | 'prepend' | 'deep';
+    /**
+     * Item fields that identify an entry (for example `id` or `data.id` under a deep merge): an
+     * incoming item replaces the held one with the same value instead of being added twice.
+     */
+    readonly matchOn?: string | readonly string[];
+}
+export interface OnceOptions {
+    /** Name the client remembers the value under (default: the prop name); pages can share it. */
+    readonly key?: string;
+    /** After this many milliseconds the client asks for the value again. Default: never. */
+    readonly ttlMs?: number;
+}
+export interface DeferOptions {
+    /** Deferred props of one group are fetched by one request after the page is shown. */
+    readonly group?: string;
+    /** The loaded value is merged into the held one (see `merge`). */
+    readonly merge?: true | MergeOptions;
+    /** Once loaded, the value is kept by the client and not computed again (see `once`). */
+    readonly once?: true | OnceOptions;
+    /**
+     * When the function throws, the prop is left out and named in `rescuedProps` (the client's
+     * `<Deferred>` shows its `rescue` slot) and the error is logged, instead of failing the request.
+     */
+    readonly rescue?: boolean;
+}
+declare const BRAND: unique symbol;
+/**
+ * A prop value with Inertia protocol behaviour (D-0052), made by `defer`, `merge`, `deepMerge` or
+ * `once`. Usable wherever a prop value is (render props and shared props).
+ */
+export declare class InertiaProp {
+    readonly value: PropValue;
+    readonly group: string | undefined;
+    readonly merge: Readonly<{
+        mode: 'append' | 'prepend' | 'deep';
+        matchOn: readonly string[];
+    }> | undefined;
+    readonly once: Readonly<{
+        key: string | undefined;
+        ttlMs: number | undefined;
+    }> | undefined;
+    readonly rescue: boolean;
+    readonly [BRAND] = true;
+    /** @internal */
+    constructor(value: PropValue, group: string | undefined, merge: Readonly<{
+        mode: 'append' | 'prepend' | 'deep';
+        matchOn: readonly string[];
+    }> | undefined, once: Readonly<{
+        key: string | undefined;
+        ttlMs: number | undefined;
+    }> | undefined, rescue: boolean);
+}
+/** True for a value made by the helpers, also from another copy of this package. */
+export declare function isInertiaProp(value: unknown): value is InertiaProp;
+/**
+ * A prop left out of the first page and fetched by the client right after it is shown, one
+ * request per group. `fn` runs only when a partial reload asks for the prop.
+ */
+export declare function defer(fn: () => Awaitable<Json>, options?: string | DeferOptions): InertiaProp;
+/** A prop the client merges into the value it holds on partial reloads (pagination, feeds). */
+export declare function merge(value: PropValue, options?: MergeOptions): InertiaProp;
+/** `merge` with nested objects merged key by key (and arrays inside them appended). */
+export declare function deepMerge(value: PropValue, options?: Omit<MergeOptions, 'mode'>): InertiaProp;
+/**
+ * A prop the client keeps after receiving it: later visits (to this or another page with the
+ * same key) do not compute it again until `ttlMs` passes or a partial reload asks for it.
+ */
+export declare function once(value: PropValue, options?: OnceOptions): InertiaProp;
+export {};

package/dist/props.js

@@ -0,0 +1,84 @@
+const BRAND = Symbol.for('dokebi.template-inertia.prop');
+/**
+ * A prop value with Inertia protocol behaviour (D-0052), made by `defer`, `merge`, `deepMerge` or
+ * `once`. Usable wherever a prop value is (render props and shared props).
+ */
+export class InertiaProp {
+    value;
+    group;
+    merge;
+    once;
+    rescue;
+    [BRAND] = true;
+    /** @internal */
+    constructor(value, group, merge, once, rescue) {
+        this.value = value;
+        this.group = group;
+        this.merge = merge;
+        this.once = once;
+        this.rescue = rescue;
+        Object.freeze(this);
+    }
+}
+/** True for a value made by the helpers, also from another copy of this package. */
+export function isInertiaProp(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[BRAND] === true);
+}
+// Names travel in comma separated headers and dotted paths; such characters cannot round-trip.
+const NAME = /^[^,\s]{1,128}$/;
+function checkValue(value, helper) {
+    if (value === undefined || isInertiaProp(value))
+        throw new TypeError(`${helper}() takes a JSON value or a function, not ${String(value)}`);
+    return value;
+}
+function mergeSettings(options) {
+    const { mode = 'append', matchOn = [], ...rest } = (options === true ? {} : (options ?? {}));
+    const fields = typeof matchOn === 'string' ? [matchOn] : matchOn;
+    if (Object.keys(rest).length ||
+        !['append', 'prepend', 'deep'].includes(mode) ||
+        !Array.isArray(fields) ||
+        fields.some((field) => typeof field !== 'string' || !NAME.test(field)))
+        throw new TypeError('Invalid Inertia merge options');
+    return Object.freeze({ mode, matchOn: Object.freeze([...fields]) });
+}
+function onceSettings(options) {
+    const { key, ttlMs, ...rest } = (options === true ? {} : (options ?? {}));
+    if (Object.keys(rest).length ||
+        (key !== undefined && (typeof key !== 'string' || !NAME.test(key))) ||
+        (ttlMs !== undefined && !(typeof ttlMs === 'number' && Number.isFinite(ttlMs) && ttlMs > 0)))
+        throw new TypeError('Invalid Inertia once options');
+    return Object.freeze({ key, ttlMs });
+}
+/**
+ * A prop left out of the first page and fetched by the client right after it is shown, one
+ * request per group. `fn` runs only when a partial reload asks for the prop.
+ */
+export function defer(fn, options) {
+    if (typeof fn !== 'function')
+        throw new TypeError('defer() takes a function');
+    const settings = typeof options === 'string' ? { group: options } : (options ?? {});
+    const { group = 'default', merge, once, rescue = false, ...rest } = settings;
+    if (Object.keys(rest).length ||
+        typeof group !== 'string' ||
+        !NAME.test(group) ||
+        typeof rescue !== 'boolean')
+        throw new TypeError('Invalid Inertia defer options');
+    return new InertiaProp(fn, group, merge === undefined ? undefined : mergeSettings(merge), once === undefined ? undefined : onceSettings(once), rescue);
+}
+/** A prop the client merges into the value it holds on partial reloads (pagination, feeds). */
+export function merge(value, options) {
+    return new InertiaProp(checkValue(value, 'merge'), undefined, mergeSettings(options), undefined, false);
+}
+/** `merge` with nested objects merged key by key (and arrays inside them appended). */
+export function deepMerge(value, options) {
+    return merge(value, { ...options, mode: 'deep' });
+}
+/**
+ * A prop the client keeps after receiving it: later visits (to this or another page with the
+ * same key) do not compute it again until `ttlMs` passes or a partial reload asks for it.
+ */
+export function once(value, options) {
+    return new InertiaProp(checkValue(value, 'once'), undefined, undefined, onceSettings(options), false);
+}

package/dist/repeats.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The full text of a caught value for the `error` log field (D-0047): name, whole message and
+ * stack, then each `cause` the same way. Only credentials in URLs (`//user:password@`) are
+ * removed; a text over 16 KB is cut and marked.
+ */
+export declare function errorText(error: unknown): string;
+/** How often a repeating error of the same kind is logged; repeats in between are counted. */
+export declare const REPEAT_INTERVAL_MS = 10000;
+/**
+ * Counts repeats of the same error key so a per-request path logs it once per interval (D-0047).
+ * The first occurrence is logged; later ones inside the interval are only counted and reported
+ * with the next logged occurrence of that key.
+ */
+export declare class Repeats {
+    #private;
+    /** The repeats to report with this occurrence, or undefined when it is only counted. */
+    take(key: string, now?: number): number | undefined;
+}

package/dist/repeats.js

@@ -0,0 +1,52 @@
+/**
+ * The full text of a caught value for the `error` log field (D-0047): name, whole message and
+ * stack, then each `cause` the same way. Only credentials in URLs (`//user:password@`) are
+ * removed; a text over 16 KB is cut and marked.
+ */
+export function errorText(error) {
+    const parts = [];
+    let current = error;
+    for (let depth = 0; current !== undefined && depth < 5; depth++) {
+        let text;
+        if (current instanceof Error)
+            text = current.stack ?? `${current.name}: ${current.message}`;
+        else if (typeof current === 'string')
+            text = current;
+        else {
+            try {
+                text = `NonError: ${JSON.stringify(current)}`;
+            }
+            catch {
+                text = `NonError: ${String(current)}`; // not serialisable (cycle, BigInt): its string form
+            }
+        }
+        parts.push(depth ? `Caused by: ${text}` : text);
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    const text = parts.join('\n').replace(/\/\/[^\s/@]*@/g, '//***@');
+    return text.length > 16_384
+        ? `${text.slice(0, 16_384)}… [truncated ${text.length - 16_384} characters]`
+        : text;
+}
+/** How often a repeating error of the same kind is logged; repeats in between are counted. */
+export const REPEAT_INTERVAL_MS = 10_000;
+/**
+ * Counts repeats of the same error key so a per-request path logs it once per interval (D-0047).
+ * The first occurrence is logged; later ones inside the interval are only counted and reported
+ * with the next logged occurrence of that key.
+ */
+export class Repeats {
+    #keys = new Map();
+    /** The repeats to report with this occurrence, or undefined when it is only counted. */
+    take(key, now = Date.now()) {
+        const entry = this.#keys.get(key);
+        if (entry && now < entry.until) {
+            entry.repeated++;
+            return undefined;
+        }
+        if (!entry && this.#keys.size >= 256)
+            this.#keys.clear();
+        this.#keys.set(key, { until: now + REPEAT_INTERVAL_MS, repeated: 0 });
+        return entry?.repeated ?? 0;
+    }
+}

package/dist/responder.d.ts

@@ -1,9 +1,12 @@
-import type { Awaitable } from '@dokebi/core';
+import type { Awaitable, Logger } from '@dokebi/core';
 import type { FastifyReply, FastifyRequest } from 'fastify';
+import { type InertiaProp } from './props.js';
+import { type Repeats } from './repeats.js';
 export type Json = null | boolean | number | string | readonly Json[] | {
     readonly [key: string]: Json;
 };
-export type Props = Readonly<Record<string, Json | (() => Awaitable<Json>)>>;
+/** Prop values: JSON, a lazy function, or a `defer`·`merge`·`deepMerge`·`once` prop (D-0052). */
+export type Props = Readonly<Record<string, Json | (() => Awaitable<Json>) | InertiaProp>>;
 export interface InertiaOptions {
     version?: string;
     rootId?: string;
@@ -19,6 +22,33 @@ export interface InertiaPage {
     readonly version: string;
     readonly clearHistory: boolean;
     readonly encryptHistory: boolean;
+    /** Props left out of this page by group; the client fetches each group after showing it. */
+    readonly deferredProps?: Readonly<Record<string, readonly string[]>>;
+    /** Props the client appends (arrays) or shallow merges (objects) on partial reloads. */
+    readonly mergeProps?: readonly string[];
+    readonly prependProps?: readonly string[];
+    readonly deepMergeProps?: readonly string[];
+    /** `<prop>.<field>` pairs: merged items with the same field value replace each other. */
+    readonly matchPropsOn?: readonly string[];
+    /** Once props by key: the client keeps them and names held keys in X-Inertia-Except-Once-Props. */
+    readonly onceProps?: Readonly<Record<string, {
+        readonly prop: string;
+        readonly expiresAt: number | null;
+    }>>;
+    /** Deferred props whose function threw and was rescued (left out of props). */
+    readonly rescuedProps?: readonly string[];
+    /**
+     * Flash data of the session (D-0055), read once; only when @dokebi/session is registered and
+     * has flash. The client fires its `flash` event and does not keep it in history.
+     */
+    readonly flash?: Readonly<Record<string, Json>>;
+}
+/** Reads (and removes) the flash of the request's session. */
+export type InertiaFlash = (request: FastifyRequest) => Promise<Record<string, Json>>;
+/** Where the responder reports prop evaluation (debug) and rescued prop failures (error). */
+export interface InertiaDiagnostics {
+    readonly logger: Logger;
+    readonly repeats: Repeats;
 }
 /** What an SSR bundle's `render(page)` returns: head tags and the root (script + element). */
 export interface InertiaSsrResult {
@@ -47,8 +77,10 @@ export declare class InertiaResponder implements InertiaApi {
     #private;
     readonly shared?: ((request: FastifyRequest) => Awaitable<Props>) | undefined;
     readonly ssr?: InertiaSsr | undefined;
+    readonly diagnostics?: InertiaDiagnostics | undefined;
+    readonly flash?: InertiaFlash | undefined;
     readonly options: NormalizedInertiaOptions;
-    constructor(options?: InertiaOptions, shared?: ((request: FastifyRequest) => Awaitable<Props>) | undefined, ssr?: InertiaSsr | undefined);
+    constructor(options?: InertiaOptions, shared?: ((request: FastifyRequest) => Awaitable<Props>) | undefined, ssr?: InertiaSsr | undefined, diagnostics?: InertiaDiagnostics | undefined, flash?: InertiaFlash | 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>;

package/dist/responder.js

@@ -1,3 +1,5 @@
+import { isInertiaProp } from './props.js';
+import { errorText } from './repeats.js';
 const escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char] ?? char);
 function localUrl(value) {
     if (typeof value !== 'string' ||
@@ -49,11 +51,15 @@ export function normalizeInertiaOptions(options = {}) {
 export class InertiaResponder {
     shared;
     ssr;
+    diagnostics;
+    flash;
     options;
     #closed = false;
-    constructor(options = {}, shared, ssr) {
+    constructor(options = {}, shared, ssr, diagnostics, flash) {
         this.shared = shared;
         this.ssr = ssr;
+        this.diagnostics = diagnostics;
+        this.flash = flash;
         this.options = normalizeInertiaOptions(options);
     }
     close() {
@@ -90,15 +96,37 @@ export class InertiaResponder {
                 .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 only = list('x-inertia-partial-data'), except = list('x-inertia-partial-except'), reset = list('x-inertia-reset'), 
+        // Once keys whose value the client holds; a full HTML load holds nothing.
+        held = inertia ? list('x-inertia-except-once-props') : new Set();
+        const meta = buildMetadata(props, partial, only, except, reset, held);
+        // The client ignores the flash of a deferred-props fetch (it keeps the page's), so such a
+        // request leaves the session's flash for the next page instead of using it up.
+        const deferredFetch = partial &&
+            only.size > 0 &&
+            [...only].every((key) => {
+                const value = Object.hasOwn(props, key) ? props[key] : undefined;
+                return isInertiaProp(value) && value.group !== undefined;
+            });
+        const values = await Promise.all(meta.selected.map(([key, value, prop]) => this.#evaluate(component, key, value, prop, meta.rescued)));
+        // Read after the props: a failed render leaves the flash for the next page.
+        const flash = this.flash && !deferredFetch ? await this.flash(request) : undefined;
         const resolved = Object.create(null);
         resolved.errors = {};
-        selected.forEach(([key], index) => {
-            resolved[key] = values[index];
+        meta.selected.forEach(([key], index) => {
+            if (values[index] !== RESCUED)
+                resolved[key] = values[index];
         });
+        const logger = this.diagnostics?.logger;
+        if (logger?.isEnabled('debug') && (meta.lazy.length || meta.announced))
+            logger.log('debug', 'Inertia props resolved', {
+                component,
+                partial,
+                evaluated: meta.lazy.slice(0, 64),
+                ...(meta.page.deferredProps ? { deferred: meta.page.deferredProps } : {}),
+                ...(meta.skippedOnce.length ? { heldOnce: meta.skippedOnce.slice(0, 64) } : {}),
+                ...(meta.rescued.length ? { rescued: meta.rescued } : {}),
+            });
         const page = {
             component,
             props: resolved,
@@ -106,6 +134,9 @@ export class InertiaResponder {
             version: this.options.version,
             clearHistory: false,
             encryptHistory: false,
+            ...meta.page,
+            ...(meta.rescued.length ? { rescuedProps: meta.rescued } : {}),
+            ...(flash && Object.keys(flash).length ? { flash } : {}),
         };
         // Reject unsupported values rather than silently dropping application data.
         const json = JSON.stringify(page, (_key, value) => {
@@ -134,6 +165,36 @@ export class InertiaResponder {
             .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 value of one selected prop. A function runs here; a rescued deferred prop that throws is
+     * logged and left out, any other failure rejects the render as before (D-0052).
+     */
+    async #evaluate(component, key, value, prop, rescued) {
+        if (typeof value !== 'function')
+            return value;
+        try {
+            return await value();
+        }
+        catch (error) {
+            if (!prop?.rescue || !this.diagnostics) {
+                // Rethrown unchanged: the web error handler answers 500 and logs the full error.
+                if (this.diagnostics?.logger.isEnabled('debug'))
+                    this.diagnostics.logger.log('debug', 'Inertia prop failed', { component, prop: key });
+                throw error;
+            }
+            rescued.push(key);
+            const repeated = this.diagnostics.repeats.take(`prop ${component} ${key}`);
+            if (repeated !== undefined)
+                this.diagnostics.logger.log('error', 'Inertia deferred prop failed and was rescued', {
+                    code: 'INERTIA_PROP_RESCUED',
+                    component,
+                    prop: key,
+                    error: errorText(error),
+                    ...(repeated ? { repeated } : {}),
+                });
+            return RESCUED;
+        }
+    }
     /**
      * 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.
@@ -180,3 +241,75 @@ export class InertiaResponder {
             : reply.redirect(url, 302);
     }
 }
+const RESCUED = Symbol('rescued');
+/**
+ * Which props this response computes and the page fields that announce the others, following
+ * the official adapters (D-0052): a partial reload selects by only/except and announces only the
+ * selected props; a first load leaves out deferred props (listed by group) and once props the
+ * client already holds. Reset props are not announced as merge props.
+ */
+function buildMetadata(props, partial, only, except, reset, held) {
+    const selected = [];
+    const lazy = [];
+    const skippedOnce = [];
+    const deferredProps = {};
+    const lists = { append: [], prepend: [], deep: [] };
+    const matchPropsOn = [];
+    const onceProps = {};
+    let announced = false;
+    const now = Date.now();
+    for (const [key, input] of Object.entries(props)) {
+        const prop = isInertiaProp(input) ? input : undefined;
+        const value = prop ? prop.value : input;
+        if (key === 'errors') {
+            selected.push([key, value, undefined]);
+            continue;
+        }
+        if (partial && ((only.size > 0 && !only.has(key)) || except.has(key)))
+            continue;
+        if (prop) {
+            announced = true;
+            if (prop.merge && !reset.has(key)) {
+                lists[prop.merge.mode].push(key);
+                for (const field of prop.merge.matchOn)
+                    matchPropsOn.push(`${key}.${field}`);
+            }
+            const onceKey = prop.once ? (prop.once.key ?? key) : undefined;
+            if (prop.once && onceKey !== undefined)
+                onceProps[onceKey] = {
+                    prop: key,
+                    expiresAt: prop.once.ttlMs === undefined ? null : now + prop.once.ttlMs,
+                };
+            if (!partial) {
+                // The client keeps its value (also for a deferred once prop: nothing to fetch).
+                if (onceKey !== undefined && held.has(onceKey)) {
+                    skippedOnce.push(key);
+                    continue;
+                }
+                if (prop.group !== undefined) {
+                    const group = deferredProps[prop.group] ?? [];
+                    group.push(key);
+                    deferredProps[prop.group] = group;
+                    continue;
+                }
+            }
+        }
+        if (typeof value === 'function')
+            lazy.push(key);
+        selected.push([key, value, prop]);
+    }
+    const page = {};
+    if (Object.keys(deferredProps).length)
+        page.deferredProps = deferredProps;
+    if (lists.append.length)
+        page.mergeProps = lists.append;
+    if (lists.prepend.length)
+        page.prependProps = lists.prepend;
+    if (lists.deep.length)
+        page.deepMergeProps = lists.deep;
+    if (matchPropsOn.length)
+        page.matchPropsOn = matchPropsOn;
+    if (Object.keys(onceProps).length)
+        page.onceProps = onceProps;
+    return { selected, lazy, skippedOnce, page, announced, rescued: [] };
+}

package/dist/vite-dev.d.ts

@@ -0,0 +1,24 @@
+/** The part of Vite's dev server used here. */
+export interface ViteDevServer {
+    middlewares(request: unknown, response: unknown, next: (error?: unknown) => void): void;
+    ssrLoadModule(url: string): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+}
+export declare const viteDevRequested: () => boolean;
+/** The part of a Node response the dev route finishes. */
+export interface DevResponse {
+    statusCode: number;
+    readonly headersSent: boolean;
+    end(): unknown;
+}
+/**
+ * The `next` of Vite's middlewares on a dev route: no error means Vite has nothing for the URL
+ * (404); an error is reported (logged by the caller) and answered 500, never dropped (D-0047).
+ */
+export declare function viteFallthrough(response: DevResponse, error: unknown, report: (error: unknown) => void): void;
+/**
+ * Starts the project's Vite (its vite.config.*) in middleware mode. The HMR socket gets a free
+ * port of its own: @dokebi/websocket answers every upgrade on the app's HTTP server and closes
+ * the ones that are not its routes, so HMR cannot share that server.
+ */
+export declare function startViteDev(root?: string): Promise<ViteDevServer>;

package/dist/vite-dev.js

@@ -0,0 +1,57 @@
+// Development mode (D-0045): with DOKEBI_VITE_DEV=1 (set by `dokebi dev`) pages load their code
+// from the project's Vite in middleware mode instead of a build, so a .vue edit reaches the
+// browser by hot module replacement. Vite is the project's dev dependency, found from the
+// working directory; this package does not depend on it.
+import { createRequire } from 'node:module';
+import { createServer } from 'node:net';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+export const viteDevRequested = () => process.env.DOKEBI_VITE_DEV === '1';
+/**
+ * The `next` of Vite's middlewares on a dev route: no error means Vite has nothing for the URL
+ * (404); an error is reported (logged by the caller) and answered 500, never dropped (D-0047).
+ */
+export function viteFallthrough(response, error, report) {
+    if (error !== undefined && error !== null) {
+        report(error);
+        if (!response.headersSent)
+            response.statusCode = 500;
+    }
+    else if (!response.headersSent)
+        response.statusCode = 404;
+    response.end();
+}
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            server.close(() => typeof address === 'object' && address ? resolve(address.port) : reject(new Error('port')));
+        });
+    });
+}
+/**
+ * Starts the project's Vite (its vite.config.*) in middleware mode. The HMR socket gets a free
+ * port of its own: @dokebi/websocket answers every upgrade on the app's HTTP server and closes
+ * the ones that are not its routes, so HMR cannot share that server.
+ */
+export async function startViteDev(root = process.cwd()) {
+    let entry;
+    try {
+        const require = createRequire(join(root, 'package.json'));
+        entry = join(dirname(require.resolve('vite/package.json')), 'dist/node/index.js');
+    }
+    catch (cause) {
+        throw new Error('DOKEBI_VITE_DEV=1 needs Vite in the project (npm install --save-dev vite)', {
+            cause,
+        });
+    }
+    const vite = (await import(pathToFileURL(entry).href));
+    return vite.createServer({
+        root,
+        appType: 'custom',
+        // Hosts are checked by the dev routes of the plugin (see index.ts), not by Vite.
+        server: { middlewareMode: true, allowedHosts: true, hmr: { port: await freePort() } },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dokebi/template-inertia",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,11 @@
       {
         "name": "dokebi-web",
         "version": "^0.1.0"
+      },
+      {
+        "name": "dokebi-session",
+        "version": "^0.1.0",
+        "optional": true
       }
     ],
     "install": {
@@ -53,7 +58,8 @@
     "documentation": "AI.md"
   },
   "devDependencies": {
-    "@dokebi/web": "0.1.1"
+    "@dokebi/session": "0.1.0",
+    "@dokebi/web": "0.1.2"
   },
   "publishConfig": {
     "access": "public",