@finesoft/front 0.1.76 → 0.1.77

package/docs/zh/pitfalls/ssr-hydration-mismatch.md

@@ -0,0 +1,163 @@
+# 陷阱：SSR Hydration 不匹配
+
+## 症状
+
+SSR 之后浏览器控制台打 hydration warning：
+
+```
+[Vue warn]: Hydration node mismatch — server rendered "<div>Loading...</div>" but client expected "<div>Welcome, Alice</div>"
+```
+
+页面在 SSR 渲染内容和客户端渲染内容之间闪。本该已经加载完毕的状态触发重新请求。
+
+## 根因（最常见）
+
+服务端和浏览器为同一 URL 产出了**不同的 `Page` 对象**，因为两端读的东西在某处不一致：
+
+- 随机/时间相关值（`Math.random()`、`Date.now()`）
+- 在服务端读 `window` / `localStorage` / `document.cookie`（都是 `undefined`）
+- 在浏览器读 `process.env`（打包后是 `undefined`）
+- SSR 看不到真实 UA 时却做了 UA 相关的渲染
+- 异步竞争：Controller 的 `execute()` 每次返回不同数据
+
+hydration 缓存（`PrefetchedIntents`）查找未命中，浏览器重跑 Controller —— 拿到不同结果。
+
+## 根因（较不常见）
+
+`PrefetchedIntents` 的 key（intentId + 稳定字符串化的 params）在两端不匹配：
+
+- params 对象含不能确定性序列化的值（Map、Set、类实例、Symbol）
+- Controller 原地改 `params` —— dispatch key 是从原始 params 算的，Controller 看到的是改过的
+
+## 诊断
+
+```ts
+// 在 view 里两端都 log page：
+console.log("[hydration]", typeof window === "undefined" ? "SSR" : "CSR", page);
+```
+
+对比两份 log。第一个不同的字段就是根因。
+
+`PrefetchedIntents` 调试，浏览器里 log 缓存状态：
+
+```ts
+startBrowserApp({
+    bootstrap,
+    onBeforeStart(framework) {
+        console.log("[prefetched]", framework.prefetchedIntents.dump());
+    },
+    mount: /* ... */,
+});
+```
+
+dump 里有 intent 但 **params 跟浏览器首次 dispatch 不同**就是 key 不匹配。
+
+## 修法
+
+### 别在模块顶层读平台专属全局
+
+```ts
+// 不好
+const userId = localStorage.getItem("uid"); // SSR 抛错
+const isDarkMode = matchMedia("(prefers-color-scheme: dark)").matches; // SSR 抛错
+const csrfToken = document.querySelector("meta[name=csrf]")?.content; // SSR 是 null
+
+export class HomeController extends BaseController {
+    /* 用 userId */
+}
+```
+
+```ts
+// 好
+export class HomeController extends BaseController {
+    async execute(_params, container) {
+        // 从 DI resolve；请求 scope 里两端都有正确的值
+        const session = container.resolve<Session>("session");
+        return { kind: "home", userId: session.userId };
+    }
+}
+```
+
+cookie 两端都能通过 `container.resolve("session")` 拿到（注册之后）。`localStorage` 只在浏览器 —— SSR 也要同一个值时，通过 cookie 或 query 参数暴露。
+
+### `execute()` 里别用随机性/时间相关逻辑
+
+```ts
+// 不好 —— 服务端和浏览器算不同的值
+async execute() {
+    return { kind: "home", randomGreeting: pick(greetings) };
+}
+```
+
+需要随机性的话在服务端算一次，让客户端通过 `PrefetchedIntents` 复用（它会自动复用）。别尝试「在客户端重新随机」—— 那正是 hydration mismatch 的成因。
+
+时间相关逻辑在服务端决定后送出结果：
+
+```ts
+async execute() {
+    const isOfficeHours = new Date().getHours() >= 9 && new Date().getHours() < 17;
+    return { kind: "home", isOfficeHours };
+}
+```
+
+两端都看到同一个 `isOfficeHours: true`，因为浏览器从缓存读，不重新评估。
+
+### `params` 用纯 JSON 类型
+
+```ts
+// 不好 —— dispatchAction 带非可序列化 params
+framework.dispatch({
+    intentId: "search",
+    params: {
+        query: "widget",
+        filters: new Set(["red", "small"]), // Set JSON.stringify 不好
+        startDate: new Date(), // 变 ISO string，能用，但...
+        validator: new Validator(), // 类实例 —— 不会留下
+    },
+});
+```
+
+```ts
+// 好 —— 仅原语 + 纯对象
+framework.dispatch({
+    intentId: "search",
+    params: {
+        query: "widget",
+        filters: ["red", "small"],
+        startDate: "2026-05-14",
+    },
+});
+```
+
+`PrefetchedIntents` 缓存用**稳定字符串化** —— 同 key 不同顺序产出相同 key，能检测循环引用。但非 JSON 值会被强转为字符串或静默丢弃。
+
+### 别改 `params`
+
+```ts
+// 不好
+async execute(params, container) {
+    params.userId = container.resolve("session").userId;   // 改了
+    return loadFor(params);
+}
+```
+
+```ts
+// 好
+async execute(params, container) {
+    const effective = { ...params, userId: container.resolve("session").userId };
+    return loadFor(effective);
+}
+```
+
+dispatcher 用原始 `params` 算了 cache key。改了之后，下次同样形状的 dispatch 就缓存未命中。
+
+## 为什么 `stableStringify` 重要
+
+框架的 `stableStringify`（在 `packages/core/src/prefetched-intents/stable-stringify.ts`）处理对象键顺序。它用 `seen` Set + `try/finally` 清理来支持 DAG（同一对象被多次引用）—— 没有清理的话 DAG 会被误判为循环引用，key 在两端会悄悄不同。
+
+如果 SSR 期间看到 "Circular reference detected" warning 但数据确实是 DAG，提 bug —— 清理本该处理这个。
+
+## 参考
+
+- [陷阱：SSR vs CSR 全局变量](./ssr-vs-csr-globals.md) —— 平台专属全局住在哪
+- [第 4 章：渲染与 Hydration](../04-rendering-and-hydration.md) —— `PrefetchedIntents` 怎么工作

package/docs/zh/pitfalls/ssr-vs-csr-globals.md

@@ -0,0 +1,176 @@
+# 陷阱：SSR 与 CSR 的全局变量
+
+## 症状
+
+build 成功。dev server 起来。任何 SSR 路由的首次请求崩：
+
+```
+ReferenceError: window is not defined
+    at /src/lib/foo.ts:3:13
+```
+
+或者更隐蔽：
+
+```
+TypeError: Cannot read properties of undefined (reading 'getItem')
+    at /src/lib/storage.ts:5:34
+```
+
+浏览器专属全局（`window`、`document`、`localStorage`、`navigator`、`matchMedia`、`IntersectionObserver` 等）在 Node 上不存在 —— Node 没有。
+
+## 根因
+
+你在被 SSR 入口导入的文件**模块求值时**读了浏览器专属全局。即使你只在客户端用它，模块图也把它拖进来了。
+
+常见入口：
+
+- `controllers/foo.ts` 导入 `lib/analytics.ts`，后者顶层用 `window.gtag`
+- `lib/storage.ts` 工厂在 import 时调 `localStorage.getItem`
+- 动画库 import 时自动跑 `requestAnimationFrame`
+
+反过来浏览器也会遇到同样问题：
+
+- 服务端专属代码（`process.env.X`、Node `fs`、`path`）被浏览器 bundle 拖进来的东西 import 了
+- Vite 把大多数 tree-shake 掉，但不是全部，动态 import 也可能让 tree-shake 失效
+
+## 诊断
+
+SSR 入口崩时错误信息含文件。从上往下读 —— 第一条 `import` 链触到浏览器全局的就是元凶。
+
+预先找浏览器专属代码，grep：
+
+```bash
+rg -n '\b(window|document|localStorage|sessionStorage|navigator|matchMedia|location)\b' src/
+```
+
+交叉对照从 `src/ssr.ts` 传递可达的东西。从 `ssr.ts` 可达的任何代码都必须 SSR 安全。
+
+## 修法
+
+### 用环境检查守卫
+
+```ts
+// 好 —— 两端都安全
+function getStoredTheme(): "light" | "dark" {
+    if (typeof window === "undefined") return "light";
+    return (localStorage.getItem("theme") as "light" | "dark") ?? "light";
+}
+```
+
+`typeof window === "undefined"` 是 SSR 检查的标准写法。比 `typeof process !== "undefined"` 更安全，因为有些打包器在客户端 polyfill `process`。
+
+### 移到生命周期 hook
+
+```ts
+// 不好 —— import 时跑
+const analytics = createAnalytics(window.location.host);
+export function track(event: string) {
+    analytics.send(event);
+}
+```
+
+```ts
+// 好 —— 浏览器里 framework 启动之后跑
+let analytics: Analytics | null = null;
+
+export function track(event: string) {
+    if (!analytics) {
+        if (typeof window === "undefined") return;
+        analytics = createAnalytics(window.location.host);
+    }
+    analytics.send(event);
+}
+```
+
+或用 `startBrowserApp` 的 `onBeforeStart`：
+
+```ts
+startBrowserApp({
+    bootstrap,
+    onBeforeStart(framework) {
+        const analytics = createAnalytics(window.location.host);
+        framework.container.register("analytics", () => analytics);
+    },
+    mount: /* ... */,
+});
+```
+
+然后在 Controller / view 里从 DI resolve —— 共享代码里永远别直接碰 `window`。
+
+### 条件 import
+
+import 时崩 Node 的库（动画库、音频库），只在浏览器动态 import：
+
+```ts
+let confetti: ((options?: any) => void) | null = null;
+
+if (typeof window !== "undefined") {
+    import("canvas-confetti").then((m) => {
+        confetti = m.default;
+    });
+}
+
+export function celebrate() {
+    confetti?.();
+}
+```
+
+或在 `onBeforeStart` 里 import：
+
+```ts
+onBeforeStart: async (framework) => {
+    const { default: confetti } = await import("canvas-confetti");
+    framework.container.register("confetti", () => confetti);
+},
+```
+
+### 用框架的抽象
+
+框架提供两端都能用的 DI key：
+
+- `DEP_KEYS.PLATFORM` —— 服务端是解析的 user-agent，客户端是 navigator 派生
+- `DEP_KEYS.STORAGE` —— 客户端 `localStorage`，服务端内存 map
+- `DEP_KEYS.LOCALE` —— 两端解析后的 locale
+
+用这些替代直接读全局。它们就是为跨平台设计的。
+
+## 症状：本地能跑，生产构建挂
+
+有时 dev server 容忍某个全局访问（Vite 的懒求值），但生产构建崩。原因通常是某个模块 dev 下被 tree-shake 掉而 prod 下没被，或者反过来。
+
+部署前测生产构建：
+
+```bash
+pnpm build
+pnpm preview
+# 访问 SSR 路由
+```
+
+`vp preview` 跑生产同一代码路径 —— 它不崩，部署也不会崩（至少不会因为这类 bug）。
+
+## 症状：生产能跑，dev 里空白页
+
+反向问题 —— 服务端专属代码漏进了客户端 bundle，浏览器 hydration 之前就崩了。
+
+打开浏览器 devtools，看 console 里有没有 `process is not defined` / `require is not defined`。修法同前：用 `typeof window === "undefined"`（反过来用 `typeof window !== "undefined"`）守卫，或移到生命周期 hook。
+
+## 为什么 import 重要，不是「不调函数」
+
+你可能想「不调那个函数」而不是守卫 import：
+
+```ts
+// 在 import 时检查
+if (typeof window !== "undefined") {
+    // SSR 永不调用
+    setupAnalytics();
+}
+```
+
+但 `import` 本身会跑模块顶层代码。如果 `lib/analytics.ts` 顶层调了 `window.gtag`（如 `const analytics = window.gtag.bind(window)`），崩**发生在 import 时**，在你的 `if` 检查之前。
+
+修被 import 的模块让它 import 安全，不是只让 call 安全。
+
+## 参考
+
+- [陷阱：SSR Hydration 不匹配](./ssr-hydration-mismatch.md) —— SSR 跑了但产出与 CSR 不同
+- [DI 容器](../07-di-container.md) —— 注册跨平台服务

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finesoft/front",
-  "version": "0.1.76",
+  "version": "0.1.77",
   "description": "Full-stack framework: router, DI, actions, SSR, and server — all in one package",
   "license": "MIT",
   "files": [
@@ -10,6 +10,7 @@
     "dist/index.mjs",
     "dist/server-data-DGbiKzMS.d.mts",
     "dist/start-app-BdXBCcor.mjs",
+    "docs",
     "README.md"
   ],
   "type": "module",