@finesoft/front 0.5.1 → 0.5.2

package/docs/zh/pitfalls/i18n-bundle-size.md

@@ -1,182 +1,12 @@
-# 陷阱：i18n 包体积
+# 语言包体积
 
-## 症状
+静态导入所有语言会增加浏览器包体积。在应用声明中使用生成的语言 loader。
 
-Lighthouse 抱怨首屏 JS 载荷过大。网络面板首屏有个巨大 chunk。你的 `dist/client/assets/index-*.js` 比应有的大，`vp build --analyze` 显示 messages 文件夹占了 bundle 的大头。
-
-## 根因
-
-翻译被打进了主客户端 chunk 而不是按 locale 拆。要么：
-
-- 你在模块顶层直接 import 了 `src/locales/*.json`：
-
-    ```ts
-    import zh from "../locales/zh-Hans.json";
-    import en from "../locales/en-US.json";
-    import ja from "../locales/ja-JP.json";
-    ```
-
-    三个 locale 都进了每个用户的 bundle，即使每个用户只看到一种。
-
-- 你在模块顶层构造了一个 `Translator`，所有 messages 都内联：
-
-    ```ts
-    const t = new SimpleTranslator({
-        locale: "en-US",
-        messages: { ...zhMessages, ...enMessages, ...jaMessages },
-    });
-    ```
-
-- 你通过 `serializeServerData` 把翻译序列化进了 HTML，每个 SSR 页面响应都带全字典。
-
-## 修法
-
-### 用 `messagesDir` 而不是静态 import
-
-配置 Vite 插件：
+## Loader / 加载器
 
 ```ts
-finesoftFrontViteConfig({
-    i18n: { messagesDir: "src/locales" },
-});
-```
-
-插件生成按 locale 的 loader。服务端从磁盘读；浏览器端动态 import 对应 chunk。Vite 把每个 locale 的 JSON 拆成独立 chunk，只有匹配解析后 locale 的 chunk 被请求。
-
-```
-dist/client/assets/
-├── index-abc123.js       ← 主 bundle（无翻译）
-├── locale-en-US-def456.js ← 只有 en-US 访客加载
-├── locale-zh-Hans-789.js  ← 只有 zh-Hans 访客加载
-└── locale-ja-JP-xyz.js    ← 只有 ja-JP 访客加载
+import { loadMessages } from "virtual:finesoft-front/i18n-loader";
+// defineWebApp({ ..., loadMessages })
 ```
 
-### 别把翻译序列化进 HTML
-
-框架**故意不**把字典放进 `PrefetchedIntents`。浏览器和初始渲染并行拉自己的 locale chunk。
-
-如果你在用自己的机制手动注入翻译进页面，停下：
-
-```html
-<!-- 不好 —— 每个 SSR 响应都带字典 -->
-<script>
-    window.__TRANSLATIONS__ = { hello: "你好" /* 几百个 key */ };
-</script>
-```
-
-```ts
-// 好 —— 框架作为独立 chunk 加载
-// （用 messagesDir 时自动处理）
-```
-
-### 检查实际发了什么
-
-```bash
-vp build
-ls -lah dist/client/assets/locale-*
-ls -lah dist/client/assets/index-*
-```
-
-加新 locale JSON 时 index chunk 应该不变。变了就有问题。
-
-可视化拆解：
-
-```bash
-vp build --analyze
-```
-
-打开交互式 bundle treemap。locale chunk 应该小（KB 级）、独立、有名字。
-
-## 「多大算太大」
-
-首屏关键 JS（index chunk）大致阈值：
-
-- 静态营销站：<50 KB gzipped
-- 标准 SPA：<150 KB gzipped
-- 重 dashboard：<300 KB gzipped
-
-翻译把 index chunk 推过这些，就该拆开。按 locale 的 10-50 KB chunk 正常，不用担心。
-
-## 服务端：字典被缓存，不打包
-
-服务端框架第一次请求时从磁盘读 locale JSON 并缓存：
-
-```
-请求 1（zh-Hans）：磁盘读 zh-Hans.json，缓存
-请求 2（zh-Hans）：从缓存返回
-请求 3（en-US）：磁盘读 en-US.json，缓存
-```
-
-你也不发巨大的 SSR bundle —— `tsdown` 打包服务端入口，但 locale JSON 是运行时从磁盘读的，没嵌入。
-
-这意味着：
-
-- ✅ 冷启动成本：每个 locale 一次磁盘读，每个 worker 一次
-- ✅ 稳态：零开销 —— locale 留在 `Map` 里
-- ❌ 可变性：编辑 JSON，服务器保持缓存的旧版本直到重启
-
-可变性问题通常不是问题 —— 翻译入源代码控制，重新部署就重新加载。运行时更新翻译的话，用自定义 `loadMessages` 回调从服务拉。
-
-## 字典确实巨大怎么办
-
-单 locale 字典是几 MB（罕见 —— 大多数应用 <100 KB）：
-
-### 按 namespace 拆
-
-```
-src/locales/
-├── en-US/
-│   ├── common.json
-│   ├── checkout.json
-│   ├── admin.json
-│   └── help-center.json
-└── zh-Hans/
-    └── ...
-```
-
-写自定义 `loadMessages` 只加载某页面需要的 namespace：
-
-```ts
-createSSRRender({
-    bootstrap,
-    async loadMessages(locale) {
-        // 只 eager 加载 "common"；其他按需懒加载
-        return import(`./locales/${locale}/common.json`);
-    },
-    async renderApp(page) {
-        /* ... */
-    },
-});
-```
-
-视图层渲染 admin 字符串前调 `await translator.loadNamespace("admin")`。
-
-### 视图挂载时懒加载
-
-非常大的可选字典（帮助内容、错误码消息），从视图层按需拉，而不是框架启动时。框架不需要知道 —— 它们只是数据。
-
-## 网络侧优化
-
-正确拆分后还能加速 locale 拉取：
-
-- 给 locale chunk 设长 `Cache-Control`（Vite 内容 hash 文件名让这安全）
-- 预加载用户的 locale chunk：
-    ```html
-    <link rel="preload" href="/assets/locale-en-US-def456.js" as="script" crossorigin />
-    ```
-- 高流量应用，让 locale chunk 走主 JS 同一 HTTP/2 连接 push
-
-## 为什么不直接把翻译放 HTML
-
-因为：
-
-- 每个页面响应都带完整字典 —— 包括用户从不访问的页面的内容
-- 当 HTML 按 locale 变化并含字典时，CDN 层无法缓存
-- SSR 延迟随字典大小线性增长
-
-按 locale 的 chunk 是正确权衡：发一次、永久缓存、只对用户实际拥有的 locale 发。
-
-## 参考
-
-- [第 5 章：i18n](../05-i18n.md) —— locale 处理全貌
-- Vite 插件源：`packages/server/src/vite-plugin.ts`（搜 `messagesDir`）
+使用相同路由、构建设置检查生产分块及 gzip 总量。入口变小可能只是字节移到别的分块。水合前 SSR 与客户端语言需一致。

package/docs/zh/pitfalls/proxy-binary-payloads.md

@@ -20,11 +20,12 @@
 
 PNG 以 `0x89 0x50 0x4E 0x47 0x0D 0x0A 0x1A 0x0A` 开头 —— 开头的 `0x89` 不是合法 UTF-8，变成 `0xEF 0xBF 0xBD`。浏览器的图片解码从第 0 字节起看到垃圾，直接放弃。
 
-当前实现用 `response.arrayBuffer()`，字节原样转发：
+当前实现按块读取并执行 10 MiB 上限，最终合并为 `ArrayBuffer`，字节原样转发：
 
 ```ts
 // packages/server/src/proxy.ts
-const body = await resp.arrayBuffer();
+const body = await readProxyBody(resp);
+if (!body) return c.text("Proxy response too large", 502);
 return c.newResponse(body, resp.status, respHeaders);
 ```
 
@@ -61,7 +62,7 @@ curl -s http://localhost:3000/api/image.png | sha256sum
 
 ## 什么情况下会撞到
 
-当前版本（用 `arrayBuffer`）不会撞到。这条陷阱主要作为以下场景的历史参照：
+当前版本（按原始字节读取）不会撞到。这条陷阱主要作为以下场景的历史参照：
 
 - **从旧版本升级** —— 升级后验证二进制端点
 - **写自己的自定义 proxy 逻辑** —— 抄旧示例会把 bug 引回来
@@ -69,7 +70,7 @@ curl -s http://localhost:3000/api/image.png | sha256sum
 
 ## 自定义 proxy —— 写对
 
-你自己写 proxy 代码（在框架的 `registerProxyRoutes` 之外），用 `arrayBuffer`：
+自定义代理也必须保留原始字节；以下 `arrayBuffer` 示例仅适用于已有独立体积限制的响应。对不可信上游优先使用框架的有界读取实现：
 
 ```ts
 // 好
@@ -108,14 +109,9 @@ app.all("/api/*", async (c) => {
 
 `resp.body` 是 `ReadableStream`。直接返回它流式转字节不缓冲。但你失去大小守卫 —— 只在信任上游时这么干。
 
-## 大小限制在两处
+## 一套实现执行两次大小检查
 
-框架强制 `MAX_RESPONSE_SIZE = 10 * 1024 * 1024`（10 MB）在两条路径：
-
-1. **运行时**（`registerProxyRoutes`）：先查 `Content-Length` 头，再查 fetch 后的 `body.byteLength`
-2. **生成代码**（`generateProxyCode`）：serverless 内联版本发同样两条检查
-
-改一处大小限制，两处都改。测试 `generated proxy code embeds the same response size limit as runtime (parity)` 强制这点。
+框架在 `registerProxyRoutes` 中执行 `MAX_RESPONSE_SIZE = 10 * 1024 * 1024`（10 MB）限制：先查 `Content-Length` 头，再按块累计实际字节；超过限制立即取消读取。`generateProxyCode` 只生成对同一实现的注册调用，开发环境和部署产物不会各自维护不同的限制。测试实际执行生成的注册代码与构建后的部署入口，覆盖二进制载荷及超限拒绝。
 
 ## 为什么 `Content-Length` 和 `byteLength` 都要
 
@@ -124,7 +120,7 @@ app.all("/api/*", async (c) => {
 两次检查覆盖两种：
 
 - 声明的 `Content-Length` 触发快速拒绝，避免下载 100MB 再拒
-- 实际收到的字节数最终拒绝，防 `Content-Length` 缺失或撒谎
+- 实际收到的字节数超限时立即拒绝，防 `Content-Length` 缺失或撒谎
 
 ## 参考
 

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

@@ -1,163 +1,7 @@
-# 陷阱：SSR Hydration 不匹配
+# 水合不一致
 
-## 症状
+浏览器与 SSR 共享同一页面声明、App 和 Outlet 视图表。SSR 使用 `createSSRRender({ definition, render: app => nativeRender(app) })`；浏览器根据 `app.shouldHydrate` 选择原生 hydrate 或 mount，完成挂载后再等待 `app.ready`。
 
-SSR 之后浏览器控制台打 hydration warning：
+先水合服务器快照，再恢复持久化状态。避免首次渲染读取随机数、时间或浏览器独有全局。不要在挂载前等待 ready，也不要手动改动 Outlet 的子树。
 
-```
-[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` 怎么工作
+显式声明公开数据投影；嵌套对象需要嵌套声明或 codec。wire/buildId 不匹配时重新加载。排查时同时检查实际浏览器警告、页面 DOM、网络请求和 entry 身份。

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

@@ -1,176 +1,15 @@
-# 陷阱：SSR 与 CSR 的全局变量
+# 运行环境边界
 
-## 症状
+全部 API 从 `@finesoft/front` 导入，各自的运行环境要求仍然保留。包条件与编译器选择内部实现，不加载未使用的 UI 或平台依赖。
 
-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：
+## Boundaries / 边界
 
 ```ts
-// 在 import 时检查
-if (typeof window !== "undefined") {
-    // SSR 永不调用
-    setupAnalytics();
-}
+import { defineOperation } from "@finesoft/front";
+// createBrowserApp: browser
+// startNodeHandler: Node
+// createHttpHandler: Request/Response host (Node or Worker)
+// finesoftFrontViteConfig: build configuration
 ```
 
-但 `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) —— 注册跨平台服务
+共享声明模块加载时勿读取 window/document/storage。UI 绑定只选择需要的框架。Node DNS、文件系统不能进入浏览器/Worker 图。使用实际安装产物验证对应运行环境，源码别名可能掩盖缺失产物。