@finesoft/front 0.5.1 → 0.5.2

package/docs/zh/03-middleware.md

@@ -1,220 +1,18 @@
-# 3. 中间件
+# 页面守卫
 
-中间件分两个阶段，包在 Controller 周围。守卫检查导航后返回四种结果之一，决定下一步发生什么。
+URL、SSR、结构化导航共用页面加载器；执行前后运行全局、路由和导航守卫，每个 Split 目标都要检查。
 
-## 管线
-
-```
-Router.resolve()
-     │
-     ▼
-  beforeLoad 链        ← NavigationContext（此时还没有 Page）
-     │
-   next()? ──否──▶ 短路（redirect / rewrite / deny）
-     │ 是
-     ▼
-IntentDispatcher.dispatch()
-     │
-     ▼
-  afterLoad 链         ← PostLoadContext（已有 Page）
-     │
-   next()? ──否──▶ 短路
-     │ 是
-     ▼
-   render
-```
-
-守卫按数组顺序执行。第一个非 `next()` 的结果短路后续链。
-
-## 四种结果
-
-```ts
-import { next, redirect, rewrite, deny } from "@finesoft/front";
-
-next(); // 继续下一个守卫 / dispatcher
-redirect("/login"); // HTTP 302；导航到 URL
-redirect("/old", 301); // HTTP 301（永久）
-rewrite("/canonical"); // beforeLoad 里：内部重路由；afterLoad 里：canonical 信号
-deny(); // 403 Forbidden
-deny(404, "Not found"); // 自定义状态码 + 消息
-```
-
-### `next()`
-
-直通。管线继续。
-
-### `redirect(url, status?)`
-
-浏览器导航到 `url`，原始渲染被丢弃。服务端表现为 HTTP 重定向；浏览器表现为导航（通过 `History.pushState`）。
-
-适用：登录跳转、废弃路径、locale 前缀归一化。
-
-### `rewrite(url)`
-
-**`beforeLoad` 里的 rewrite** —— 内部重路由。Router 改为解析 `url`，_新_ match 的守卫和 Controller 跑。不产生 HTTP 重定向；地址栏保持原 URL。深度限制为 5 层，防死循环。
-
-**`afterLoad` 里的 rewrite** —— canonical 信号。框架在 SSR 响应里包含 `Content-Location` 头，但不重定向。浏览器收到原 URL 加一个提示：存在 canonical 版本。
-
-何时用哪个，见 [redirect vs rewrite](./pitfalls/redirect-vs-rewrite.md)。
-
-### `deny(status?, message?)`
-
-停止请求。默认 `403 Forbidden`。常见：`deny(401, "Login required")`、`deny(404, "Not found")`。
-
-## 写守卫
-
-守卫是从 context 到 `MiddlewareResult`（或 `Promise<MiddlewareResult>`）的函数。
-
-```ts
-// src/lib/guards/auth.ts
-import { next, redirect, type NavigationContext } from "@finesoft/front";
-
-export function authGuard(ctx: NavigationContext) {
-    const token = ctx.getCookie("token");
-    if (!token) {
-        return redirect(`/login?next=${encodeURIComponent(ctx.url.pathname)}`);
-    }
-    return next();
-}
-```
-
-### `NavigationContext`（beforeLoad）
-
-| 字段              | 类型                               | 说明                                    |
-| ----------------- | ---------------------------------- | --------------------------------------- |
-| `url`             | `URL`                              | 完整请求 URL。                          |
-| `intent`          | `Intent`                           | 解析后的 intent，包含路径参数。         |
-| `container`       | `Container`                        | 请求级 DI 容器。                        |
-| `getCookie(name)` | `(name: string) => string \| null` | 读 cookie（服务端 + 浏览器都可用）。    |
-| `getHeader(name)` | `(name: string) => string \| null` | 读请求头（仅服务端；浏览器返回 null）。 |
-| `isSsr`           | `boolean`                          | 服务端 `true`，浏览器 `false`。         |
-
-### `PostLoadContext`（afterLoad）
-
-继承自 `NavigationContext`，新增：
-
-| 字段   | 类型       | 说明                     |
-| ------ | ---------- | ------------------------ |
-| `page` | `BasePage` | Controller 产出的 Page。 |
-
-## 给路由挂守卫
-
-```ts
-defineRoutes(framework, [
-    {
-        path: "/admin",
-        intentId: "admin",
-        controller: new AdminController(),
-        beforeLoad: [authGuard, requireAdminRole],
-        afterLoad: [trackPageView],
-    },
-]);
-```
-
-路由上的守卫**叠加**在框架全局守卫之上（见下）。顺序：先全局，后路由级。
-
-## 全局守卫
-
-注册对每个导航都生效的守卫：
-
-```ts
-framework.middleware.use("beforeLoad", trackingGuard);
-framework.middleware.use("afterLoad", metricsGuard);
-```
-
-慎用。全局守卫每页都跑，包括 SSR —— 慢的全局守卫会乘到整个表面积上。
-
-## 常见模式
-
-### 鉴权
-
-```ts
-function authGuard(ctx: NavigationContext) {
-    const token = ctx.getCookie("session");
-    if (!token) return redirect("/login?next=" + encodeURIComponent(ctx.url.pathname));
-    return next();
-}
-```
-
-### 角色校验
-
-```ts
-async function requireAdmin(ctx: NavigationContext) {
-    const session = await ctx.container.resolve<SessionService>("session").current();
-    if (!session?.isAdmin) return deny(403, "Admin only");
-    return next();
-}
-```
-
-### Locale 前缀重定向
-
-```ts
-function localePrefixGuard(ctx: NavigationContext) {
-    if (/^\/(en|zh|ja)\//.test(ctx.url.pathname)) return next();
-    const detected = detectLocale(ctx); // 你自己的逻辑
-    return redirect(`/${detected}${ctx.url.pathname}`, 301);
-}
-```
-
-### A/B 测试 rewrite
+## Guard / 守卫
 
 ```ts
-function abTestGuard(ctx: NavigationContext) {
-    if (ctx.url.pathname !== "/landing") return next();
-    const variant = bucket(ctx.getCookie("uid"));
-    return variant === "B" ? rewrite("/landing-v2") : next();
-}
+import { next, redirect, type BeforeLoadGuard } from "@finesoft/front";
+export const signedIn: BeforeLoadGuard = (context) =>
+    context.getCookie("session")
+        ? next()
+        : redirect("/login?next=" + encodeURIComponent(context.url));
+// app.beforeLoad: [signedIn], or home.route("/account", { beforeLoad: [signedIn] })
 ```
 
-用户在地址栏看到 `/landing`；服务端渲染 `/landing-v2`。客户端无可见重定向，无闪屏。
-
-### afterLoad 分析
-
-```ts
-function trackPageView(ctx: PostLoadContext) {
-    ctx.container.resolve<EventRecorder>("eventRecorder").record({
-        name: "PageView",
-        fields: { intentId: ctx.intent.intentId, url: ctx.url.pathname },
-    });
-    return next();
-}
-```
-
-## 守卫顺序规则
-
-1. 全局 `beforeLoad` 守卫（注册顺序）
-2. 路由级 `beforeLoad` 守卫（数组顺序）
-3. Controller `execute()`
-4. 全局 `afterLoad` 守卫
-5. 路由级 `afterLoad` 守卫
-
-任一步返回非 `next()` 则停止。后续守卫不再跑。
-
-## 异步守卫
-
-守卫可以 `async`。管线在每个结果之间 await。全局守卫里别 await 太久（会乘到每个请求）。
-
-```ts
-async function rateLimitGuard(ctx: NavigationContext) {
-    const limiter = ctx.container.resolve<RateLimiter>("rateLimiter");
-    const allowed = await limiter.tryConsume(ctx.getCookie("uid") ?? "anon");
-    return allowed ? next() : deny(429, "Too many requests");
-}
-```
-
-## 注意事项
-
-- **守卫对框架状态必须是纯的。** 不要改 `ctx.intent.params` —— 需要改参数就构造新 intent 然后 `rewrite`。
-- **`afterLoad` 里的 `deny()` 会丢弃已产出的页面。** Controller 已经跑过了；deny 只阻断响应。如果 `execute()` 有副作用（写操作），副作用已经发生。
-- **浏览器端守卫拿不到请求头。** `getHeader()` 在客户端返回 `null`。cookie 仍然可用。
-
-## 实时演示
-
-构造一条三守卫的 `beforeLoad` 链，逐个选定每个 guard 的返回值，然后交给 `@finesoft/core` 里**真实**的 `runBeforeLoadGuards()` 跑一次。下方流水线会显示链路在哪一步短路、最终的 `MiddlewareResult` 是什么。
+守卫返回 `next()`、`deny(status, message)`、`redirect(url, status)` 或 `rewrite(url)`；首个非 next 结果终止当前链。浏览器重定向仍经过主机导航准入，SSR 则返回 HTTP 重定向。操作策略属于可移植运行时层，数据接口也需在那里授权。已缓存 HTML 不能绕过当前请求的检查。
 
 <Ch03MiddlewarePlayground />
-
-## 下一步
-
-- [渲染与 Hydration](./04-rendering-and-hydration.md) —— `afterLoad` 到 HTML 输出之间发生什么
-- [陷阱：redirect vs rewrite](./pitfalls/redirect-vs-rewrite.md) —— 二者之间怎么选

package/docs/zh/04-rendering-and-hydration.md

@@ -1,338 +1,11 @@
-# 4. 渲染与 Hydration
+# 渲染与水合
 
-页面从 Controller 输出到字节流再回到活着的浏览器应用要走的路。本章覆盖 SSR、CSR、prerender，它们正交组合的第二根轴 —— **应用架构**（扁平单页 vs 结构化导航 + islands）—— 以及把两端绑在一起的 `PrefetchedIntents` 机制。
+SSR、CSR、prerender 决定 HTML 的生成时机。三种模式都使用相同页面会话和单个原生应用根，布局包住 Outlet；不再选择 root/entries 模式，也没有单独 chrome 根。
 
-## 三种模式并排比
+浏览器调用 `createBrowserApp({ definition, target })`，用原生 API 挂载或水合相同的 App，再等待 `app.ready`。SSR 调用 `createSSRRender({ definition, render: app => nativeRender(app) })`。完整 React 代码见[快速开始](./01-getting-started.md)，Vue/Svelte 模板使用各自的原生 API。
 
-|                          | SSR                                     | CSR                           | Prerender                               |
-| ------------------------ | --------------------------------------- | ----------------------------- | --------------------------------------- |
-| HTML 何时生成            | 每次请求时在服务端                      | 构建期（仅空壳）              | 构建期，按路由                          |
-| 初始 body                | 完整渲染                                | 空 `<div id="app"></div>`     | 完整渲染                                |
-| Hydration 时需重新请求？ | 不需要（数据在 `PrefetchedIntents` 里） | 需要（Controller 在浏览器跑） | 不需要（数据在 `PrefetchedIntents` 里） |
-| TTFB                     | 一次 Controller 执行                    | 接近零                        | 静态文件直接发                          |
-| 个性化                   | 按请求 OK                               | 最好 —— 完全在客户端跑        | 无（所有人同一份 HTML）                 |
-| SEO                      | 好                                      | 需要支持 JS 的爬虫            | 最好                                    |
+Outlet 订阅稳定的 `AppSnapshot`，以 EntryId 保持外层元素，以 EntryId 与 pageType 共同确定页面组件身份。隐藏 entry 仍在同一组件树中，草稿与 context 保留；类型变化重建内部页面。原生提交钩子只确认实际提交的 revision，框架随后恢复对应页面的滚动和 DOM 状态。
 
-模式是**按路由**配置，自由混合。
+SSR 在释放请求资源前物化公开投影，原生组件只渲染一次。水合协议明确包含 `{ tree, pages }`，每份页面数据关联 entry。协议版本或 buildId 不匹配时重新加载；会话持久化另有版本。被守卫拒绝的页面数据不进入 wire。
 
-## 两根轴：渲染模式 × 应用架构
-
-渲染模式是一根轴。**应用架构**是正交的第二根轴：
-
-- **扁平单页** —— 服务端 `createSSRRender`，客户端单次挂载、每次导航重渲。一个 root、一个可见页。（见下方 [SSR 管线](#ssr-管线)。）
-- **结构化导航 + islands** —— 服务端 `createSSRNavigationRender`，客户端按目标挂为 _islands_：独立 root，切 tab / 栈时保活不销毁。（见 [导航](./11-navigation.md) 与下方 [Islands SSR](#islands-ssr结构化架构方案-c)。）
-
-两轴组合成矩阵 —— 渲染模式决定 HTML _何时/何地_ 产出，架构决定应用 _怎么组织_：
-
-|               | 扁平单页                | 结构化导航 + islands（方案 C）    |
-| ------------- | ----------------------- | --------------------------------- |
-| **ssr**       | ✅ `svelte-minimal`     | ✅ `vue-minimal`、`react-minimal` |
-| **csr**       | ◐ 空壳 → 单 client root | ◐ 空壳 → islands 客户端挂         |
-| **prerender** | ◐ 缓存扁平 SSR          | ◐ 缓存方案 C SSR                  |
-
-✅ 有 starter 模板实证 · ◐ 设计上成立，暂无 starter 模板。
-
-**islands 是 SSR 还是 CSR，是模式的结果、不是独立选项**：`ssr`/`prerender` 下框架服务端渲出每个可见 island、客户端 _收养并水合_；`csr` 下无服务端 HTML，每个 island 都在客户端新挂。每种模式的子维度仍叠加其上 —— CSR 有两个触发点（[见下](#csr客户端渲染)），prerender 有构建期静态与运行时 ISR 两种形态（[见下](#prerender静态--isr)）。会话恢复 + DOM 恢复是再一层正交（客户端、post-hydration），可叠加在任意格上 —— 见 [会话恢复](./12-session-restoration.md)。
-
-## SSR 管线
-
-```
-请求 URL
-    │
-    ▼
-Router.resolve()                 → RouteMatch
-    │
-    ▼
-beforeLoad 守卫                  → 可能 rewrite（内部）/ redirect / deny
-    │
-    ▼
-IntentDispatcher.dispatch()      → Page
-    │
-    ▼
-afterLoad 守卫                   → 可能 redirect / deny / 发出 canonical 信号
-    │
-    ▼
-renderApp(page)                  → { html, head, css }
-    │
-    ▼
-injectSSRContent()               → 最终 HTML，含：
-    • 渲染后的 body 放在 <!--ssr--> 里
-    • head 片段放在 <!--head--> 里
-    • 序列化的 PrefetchedIntents 放在 <script> 里
-    • <html lang="..." dir="..."> 属性
-```
-
-### SSR 入口
-
-```ts
-// src/ssr.ts
-import { createSSRRender, serializeServerData } from "@finesoft/front";
-import { createSSRApp } from "vue";
-import { renderToString } from "vue/server-renderer";
-import App from "./App.vue";
-import { bootstrap } from "./bootstrap";
-
-export const render = createSSRRender({
-    bootstrap,
-    getErrorPage: () => ({ kind: "error", title: "Something went wrong" }),
-    async renderApp(page) {
-        const app = createSSRApp(App, { page });
-        const html = await renderToString(app);
-        return {
-            html,
-            head: `<title>${escape(page.title)}</title>`,
-            css: "",
-        };
-    },
-});
-
-export { serializeServerData };
-```
-
-Vite 插件和 adapter 替你调用 `render(url, options)`。你返回 `{ html, head, css }`，框架处理注入和序列化。
-
-### `createSSRRender` 替你做了什么
-
-- 服务端跑一次 `bootstrap()`（同一个 worker 内跨请求缓存）
-- 每个请求创建请求级 DI 容器
-- 跑中间件管线
-- 调用你的 `renderApp()` 产出 body
-- 把 prefetched intent 结果序列化进 `<script id="__finesoft_data__">`
-- 根据解析出的 locale 设置 `<html lang dir>`
-- 根据 `deny()` / `redirect()` / `rewrite()` 结果设置 HTTP status
-- `afterLoad` 发出 rewrite 信号时加 `Content-Location` 头
-
-## Islands SSR（结构化架构，"方案 C"）
-
-结构化架构把 **chrome**（tab bar、header —— 持久外框）和 **island 内容**（当前活动页）渲为**独立的水合 root**，作为挂载节点下的 sibling：
-
-```html
-<div id="app">
-    <div data-fs-chrome><!-- chrome 渲在这 --></div>
-    <main data-fs-outlet><!-- 每个可见 island 渲在这 --></main>
-</div>
-```
-
-**服务端** —— `renderApp` 渲 chrome；`renderIslandsHtml(snapshot, renderEntry)` 把每个可见目标渲进 outlet，带上共享标记（`data-fs-entry` / `data-fs-intent` / `data-fs-key`）供客户端匹配：
-
-```ts
-// src/ssr.ts —— 结构化入口（createSSRNavigationRender）
-async renderApp(page, _framework, snapshot) {
-    const chromeHtml = await renderToString(createSSRApp(App, { snapshot }));
-    const islandsHtml = await renderIslandsHtml(snapshot, (entry) =>
-        renderToString(createSSRApp(VIEWS[entry.intent], { page: entry.page })),
-    );
-    return {
-        html: `<div data-fs-chrome>${chromeHtml}</div><main data-fs-outlet>${islandsHtml}</main>`,
-        head: `<title>${page.title}</title>`,
-        css: "",
-    };
-}
-```
-
-**客户端** —— `resolveIslandsShell(target)` 找到（或创建）chrome/outlet sibling，并报告 chrome 是否服务端渲过（`hydrate`）。island 编排器按 `data-fs-key` 收养每个 SSR'd 容器，调你的 `mountEntry(entry, container)` 时置 `entry.hydrate = true`，让你水合已有 DOM 而非新建：
-
-```ts
-// src/main.ts
-const mountEntry = (entry, container) => {
-    const factory = entry.hydrate ? createSSRApp : createApp; // 水合 SSR'd vs 新建（客户端导航）
-    const app = factory(VIEWS[entry.intent], { page: entry.page, controller: ctx.app });
-    app.mount(container);
-    return { unmount: () => app.unmount() };
-};
-
-startBrowserApp({
-    bootstrap,
-    mount,
-    callbacks,
-    navigation: { ...navigation.toBrowserConfig(), mountEntry },
-});
-```
-
-> **同步挂载契约。** `mountEntry` 返回后，island 的 DOM 必须已就绪：框架在下一帧回填 `data-restore-root` 字段（见 [会话恢复](./12-session-restoration.md)）。Vue/Svelte 的 `.mount()` 同步满足。**React** 异步提交 DOM，故须把**客户端新挂**路径用 `flushSync(() => root.render(view))` 包住 —— 仅客户端新挂的 island 需要（SSR'd island 的 DOM 已来自服务端）。见 `templates/react-minimal/src/main.tsx`。
-
-完整示例：`templates/vue-minimal` 与 `templates/react-minimal`（均为 `ssr` + 结构化导航 + islands + 会话恢复）。
-
-## CSR（客户端渲染）
-
-`renderMode: "csr"` 的路由，服务端返回最小空壳：
-
-```html
-<!doctype html>
-<html lang="en">
-    <head>
-        <!-- 这里注入 head -->
-    </head>
-    <body>
-        <div id="app"></div>
-        <!-- 没有 PrefetchedIntents script —— Controller 在浏览器跑 -->
-        <script type="module" src="/src/main.ts"></script>
-    </body>
-</html>
-```
-
-`startBrowserApp()` 触发首次导航时 Controller 在浏览器跑。CSR 适用：
-
-- 鉴权背后高度个性化的 dashboard
-- SEO 不重要的页面
-- 服务端渲染成本盖过延迟收益的页面
-
-## Prerender（静态 + ISR）
-
-```ts
-{ path: "/about", intentId: "about", controller: new AboutController(), renderMode: "prerender" }
-```
-
-构建期框架：
-
-1. 调 `controller.execute({}, container)`（参数来自静态路径）
-2. 跑 `renderApp()` 产 HTML
-3. 写 `dist/about.html` 到磁盘
-
-adapter 直接服务这些静态文件。请求时不跑 Controller。
-
-### 增量静态再生成（ISR）
-
-打包的服务器（`createServer`）和预览服务器（`vp preview`）会在运行时缓存 `prerender` 路由：路由在**首次**请求时渲染，HTML 存入内存 LRU（`ISR_CACHE_MAX = 1000` 条，按最近最少使用驱逐）。后续请求直接吐缓存、不再跑 controller。
-
-把路由标 `prerender`：路由级（`renderMode: "prerender"`）或经 Vite 插件按 glob 配置（配置级优先于路由级）：
-
-```ts
-finesoftFrontViteConfig({
-    ssr: { entry: "src/ssr.ts" },
-    renderModes: { "/blog/*": "prerender" },
-});
-```
-
-运行时缓存**无 TTL、无后台再生成** —— 条目存活到被 LRU 驱逐或进程重启为止。基于时间的 stale-while-revalidate 由平台 adapter 委托给 CDN（Netlify 发真正的 `stale-while-revalidate` 头；Cloudflare 发普通 `max-age`；node/Vercel 不发）。完整说明见 [服务器与部署](./09-server-and-deployment.md#isr增量静态再生成)。
-
-## `PrefetchedIntents` —— SSR → CSR 的桥梁
-
-关键机制：**同一个 Controller 在服务器产出页面，浏览器复用结果不重新请求。**
-
-### 工作原理
-
-1. SSR：Controller 跑，返回 `Page`。框架把 `(intentId, paramsKey) → Page` 存入 `PrefetchedIntents` map。
-2. 渲染：map 被 JSON 序列化进 `<script id="__finesoft_data__">{...}</script>`。
-3. 浏览器：`startBrowserApp` 读这个 script，调 `createPrefetchedIntentsFromDom()`，传给 `Framework.create()`。
-4. 浏览器首次导航：`IntentDispatcher.dispatch()` 用 `(intentId, paramsKey)` 查 map —— 命中则直接返回缓存的 `Page`，不调 Controller。
-
-### 稳定 key 生成
-
-查找 key 由 `intentId` + `params` 的**稳定 JSON 字符串化**生成。对象键的顺序不影响 key：
-
-```ts
-// 下面两个产出相同的 paramsKey：
-dispatch({ intentId: "product", params: { id: "42", color: "red" } });
-dispatch({ intentId: "product", params: { color: "red", id: "42" } });
-```
-
-如果你写的 Controller 用不同 `params` 形状解析同一个逻辑请求，dispatch 之前先归一化。
-
-### 缓存什么时候不命中
-
-- 浏览器导航到未在服务端 prefetch 的 intent（例如用户点击的动态路由）
-- `PrefetchedIntents.invalidate(intentId, params)` 之后变陈旧
-- 浏览器端的 mutation 守卫（自定义）
-
-不命中走普通 dispatcher 路径 —— `execute()` 在浏览器跑。
-
-## 一步一步看 Hydration
-
-```
-服务器                          浏览器
-──────                          ───────
-bootstrap(framework)
-    ▼                              │
-controller.execute()                │
-    ▼                              │
-Page A                              │
-    ▼                              │
-serialize → <script>                │
-    ▼                              │
-HTML 响应 ─────────────────────▶  接收 HTML
-                                    ▼
-                              createPrefetchedIntentsFromDom()
-                                    ▼
-                              Framework.create({ prefetchedIntents })
-                                    ▼
-                              bootstrap(framework)    ← 同份代码、同份路由
-                                    ▼
-                              dispatch(currentIntent)
-                                    ▼
-                              缓存命中 → Page A     ← 不重新请求
-                                    ▼
-                              mount(app)
-```
-
-bootstrap 跑两遍 —— 两端各一次 —— 输入相同。这就是浏览器初始路由和服务端渲染 HTML 一致的保证。
-
-## SSR head 注入
-
-`renderApp()` 返回 `head` 片段。框架把它注入到 `<!--head-->` 占位，同时还会注入：
-
-- `<script id="__finesoft_data__">` 序列化数据（仅 SSR 模式）
-- 客户端入口的 `<link>` / `<script>`（生产构建）
-- 来自解析 locale 的 `<html lang="..." dir="...">` 属性
-
-自定义 meta 标签放进你的 `head` 字符串：
-
-```ts
-async renderApp(page) {
-    return {
-        html: await renderToString(/*...*/),
-        head: [
-            `<title>${escape(page.title)}</title>`,
-            `<meta name="description" content="${escape(page.description)}">`,
-            `<meta property="og:title" content="${escape(page.title)}">`,
-        ].join(""),
-        css: "",
-    };
-}
-```
-
-用户提供的字符串永远要 escape —— 它们直接进 HTML。
-
-## CSS 注入
-
-如果渲染产出关键 CSS（如 Vue scoped 样式、`vanilla-extract`），通过 `css` 返回：
-
-```ts
-return {
-    html,
-    head: `<title>${title}</title>`,
-    css: extractedCriticalCss, // 作为 <style> 注入到 <head>
-};
-```
-
-Vite 管理的样式表保持 `css: ""` —— Vite 插件会处理。
-
-## 状态码
-
-SSR 响应的 HTTP 状态按以下优先级决定：
-
-1. 中间件结果：`deny(404)` → 404；`redirect(url, 301)` → 301 + `Location` 头。
-2. 页面级：`fallback()` 返回 `kind: "error"` 的 `Page` → 500（可通过 `getErrorPage` 配置）。
-3. 默认：200。
-
-通过 `afterLoad` 覆盖：
-
-```ts
-afterLoad: [
-    (ctx) => {
-        if (ctx.page.kind === "not-found") return deny(404, "Not found");
-        return next();
-    },
-],
-```
-
-## 流式 SSR
-
-当前不支持。框架在发字节前完整 await `renderApp()`。对大多数应用够用 —— Controller 内部 `execute()` 里并发 await 多个 HTTP 调用就能并行抓数据。
-
-如果某个大页面确实需要流式渲染，考虑用 CSR 渲染该页面 + 使用视图层自己的流式原语。
-
-## 下一步
-
-- [国际化](./05-i18n.md) —— locale 解析和字典加载
-- [陷阱：SSR Hydration 不匹配](./pitfalls/ssr-hydration-mismatch.md) —— 两端不一致时
+CSR 返回 HTML shell。prerender 输出静态 HTML；运行时公开 HTML 缓存仍先运行本次守卫与渲染，不能视为跳过业务执行。清理时应用先等待会话 dispose，再卸载自己的原生根。