@finesoft/front 0.1.76 → 0.1.77

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

@@ -0,0 +1,176 @@
+# Pitfall: SSR vs CSR globals
+
+## Symptom
+
+The build succeeds. The dev server starts. The first request to any SSR route crashes with:
+
+```
+ReferenceError: window is not defined
+    at /src/lib/foo.ts:3:13
+```
+
+Or, more subtly:
+
+```
+TypeError: Cannot read properties of undefined (reading 'getItem')
+    at /src/lib/storage.ts:5:34
+```
+
+The browser-only global (`window`, `document`, `localStorage`, `navigator`, `matchMedia`, `IntersectionObserver`, ...) doesn't exist on Node — Node has none of them.
+
+## Root cause
+
+You're reading a browser-only global at **module evaluation time** in a file imported by your SSR entry. The module graph dragged it in even though you only use it on the client.
+
+Common entry points:
+
+- A `controllers/foo.ts` that imports a `lib/analytics.ts` with `window.gtag` at module top
+- A `lib/storage.ts` factory that calls `localStorage.getItem` at import time
+- An animation library auto-running `requestAnimationFrame` on import
+
+The same problem in reverse hits the browser:
+
+- Server-only code (`process.env.X`, Node `fs`, `path`) imported by something the browser bundle pulled in
+- Vite tree-shakes most, but not all, and dynamic imports can defeat tree-shaking
+
+## Diagnosis
+
+When the SSR entry crashes, the error message includes the file. Read top-to-bottom — the first `import` chain that touches a browser global is the offender.
+
+To find browser-only code preemptively, grep:
+
+```bash
+rg -n '\b(window|document|localStorage|sessionStorage|navigator|matchMedia|location)\b' src/
+```
+
+Cross-reference with what's imported transitively from `src/ssr.ts`. Anything reachable from `ssr.ts` must be SSR-safe.
+
+## Fix
+
+### Guard with an environment check
+
+```ts
+// GOOD — safe on both sides
+function getStoredTheme(): "light" | "dark" {
+    if (typeof window === "undefined") return "light";
+    return (localStorage.getItem("theme") as "light" | "dark") ?? "light";
+}
+```
+
+`typeof window === "undefined"` is the canonical SSR check. It's safer than `typeof process !== "undefined"` because some bundlers polyfill `process` on the client.
+
+### Move to lifecycle hooks
+
+```ts
+// BAD — runs at import time
+const analytics = createAnalytics(window.location.host);
+export function track(event: string) {
+    analytics.send(event);
+}
+```
+
+```ts
+// GOOD — runs after framework start in the browser
+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);
+}
+```
+
+Or use `startBrowserApp`'s `onBeforeStart`:
+
+```ts
+startBrowserApp({
+    bootstrap,
+    onBeforeStart(framework) {
+        const analytics = createAnalytics(window.location.host);
+        framework.container.register("analytics", () => analytics);
+    },
+    mount: /* ... */,
+});
+```
+
+Then resolve from DI in controllers/views — never touch `window` directly in shared code.
+
+### Conditional import
+
+For libraries that crash on import in Node (animation libs, audio libs), import dynamically only on the browser:
+
+```ts
+let confetti: ((options?: any) => void) | null = null;
+
+if (typeof window !== "undefined") {
+    import("canvas-confetti").then((m) => {
+        confetti = m.default;
+    });
+}
+
+export function celebrate() {
+    confetti?.();
+}
+```
+
+Or register the import in `onBeforeStart`:
+
+```ts
+onBeforeStart: async (framework) => {
+    const { default: confetti } = await import("canvas-confetti");
+    framework.container.register("confetti", () => confetti);
+},
+```
+
+### Use the framework's abstractions
+
+The framework provides DI keys that work on both sides:
+
+- `DEP_KEYS.PLATFORM` — the parsed user-agent on the server, navigator-derived on the client
+- `DEP_KEYS.STORAGE` — `localStorage` on the client, in-memory map on the server
+- `DEP_KEYS.LOCALE` — resolved locale on both sides
+
+Use these instead of reading globals directly. They're cross-platform by design.
+
+## Symptom: works locally, fails in production build
+
+Sometimes the dev server tolerates a global access (via Vite's lazy evaluation) but the production build crashes. The cause is usually a module that's tree-shaken in dev but not in prod, or vice versa.
+
+Test the production build before deploying:
+
+```bash
+pnpm build
+pnpm preview
+# hit the SSR routes
+```
+
+The `vp preview` server runs the same code path as production — if it doesn't crash, the deploy won't either (at least not from this class of bug).
+
+## Symptom: works in production but blank page in dev
+
+Inverse problem — server-only code leaked into the client bundle, and the browser crashed during hydration before the view layer mounted.
+
+Open browser devtools, check the console for `process is not defined` / `require is not defined`. The fix is the same: guard with `typeof window === "undefined"` (inverted: guard with `typeof window !== "undefined"`) or move to a lifecycle hook.
+
+## Why imports matter, not "code that runs"
+
+You may be tempted to "just not call the function" instead of guarding the import:
+
+```ts
+// import-time check
+if (typeof window !== "undefined") {
+    // never actually called on SSR
+    setupAnalytics();
+}
+```
+
+But the `import` itself runs the module's top-level code. If `lib/analytics.ts` calls `window.gtag` at module top-level (e.g., as part of `const analytics = window.gtag.bind(window)`), the crash happens **at import**, before your `if` check.
+
+Fix the imported module to be import-safe, not just call-safe.
+
+## Related
+
+- [Pitfall: SSR hydration mismatch](./ssr-hydration-mismatch.md) — when SSR runs but produces different output than CSR
+- [DI container](../07-di-container.md) — registering cross-platform services

package/docs/zh/01-getting-started.md

@@ -0,0 +1,230 @@
+# 1. 快速开始
+
+五分钟跑通一个 `@finesoft/front` 应用。读完你会有一个 Vue/React/Svelte 页面在服务端渲染、在浏览器 hydrate、并准备好部署。
+
+## 先决条件
+
+- Node.js `>= 22.12.0`
+- 一个包管理器：pnpm（推荐）、npm 或 yarn
+- 一个视图层：Vue 3、React 19 或 Svelte 5 —— 文档用 Vue 举例，但每个示例都能 1:1 翻译
+
+## 脚手架创建新应用
+
+```bash
+npx @finesoft/create-app my-app
+cd my-app
+pnpm install
+pnpm dev
+```
+
+脚手架生成一个可运行的应用，路由、SSR、proxy 已经接好。打开 <http://localhost:5173>。
+
+如果你想理解里面是怎么搭起来的，本页后面从零搭一份同样的配置。
+
+## 加进已有项目
+
+```bash
+pnpm add @finesoft/front
+pnpm add -D vite hono
+```
+
+Peer 依赖：`hono >= 4.0.0`。可选但推荐：`@hono/node-server`（Node 部署）、`vite >= 5.0.0`（dev server）。
+
+## 最小项目布局
+
+```
+my-app/
+├── src/
+│   ├── bootstrap.ts       # 路由 + Controller（SSR + CSR 共享）
+│   ├── main.ts            # 浏览器入口
+│   ├── ssr.ts             # SSR 入口
+│   ├── App.vue            # 根组件
+│   └── lib/
+│       └── controllers/
+│           └── home.ts
+├── index.html
+├── vite.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+## Vite 配置
+
+```ts
+// vite.config.ts
+import { finesoftFrontViteConfig } from "@finesoft/front";
+import vue from "@vitejs/plugin-vue";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+    plugins: [
+        vue(),
+        finesoftFrontViteConfig({
+            ssr: { entry: "src/ssr.ts" },
+            i18n: { messagesDir: "src/locales" },
+            adapter: "auto",
+        }),
+    ],
+});
+```
+
+`finesoftFrontViteConfig` 加的东西：
+
+- 基于 Hono 的 dev server，每个请求都跑你的 SSR 入口
+- 从 `messagesDir` 自动加载 locale JSON
+- 构建管线同时产出客户端 bundle 和服务端入口
+- `adapter: "auto" | "node" | "vercel" | "cloudflare" | "netlify" | "static"` 自动接入平台 adapter
+
+## Bootstrap（SSR 与 CSR 共享）
+
+```ts
+// src/bootstrap.ts
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { HomeController } from "./lib/controllers/home";
+
+export function bootstrap(framework: Framework): void {
+    defineRoutes(framework, [{ path: "/", intentId: "home", controller: new HomeController() }]);
+}
+```
+
+同一个 `bootstrap()` 在两端都跑。这就是 SSR 和 CSR 解析 URL 完全一致的保证。
+
+## Controller
+
+```ts
+// src/lib/controllers/home.ts
+import { BaseController, type Container } from "@finesoft/front";
+
+interface HomePage {
+    kind: "home";
+    title: string;
+    items: string[];
+}
+
+export class HomeController extends BaseController<Record<string, string>, HomePage> {
+    readonly intentId = "home";
+
+    async execute(_params: Record<string, string>, _container: Container): Promise<HomePage> {
+        return {
+            kind: "home",
+            title: "Welcome",
+            items: ["one", "two", "three"],
+        };
+    }
+
+    fallback(_params: Record<string, string>, error: unknown): HomePage {
+        return { kind: "home", title: "Failed", items: [] };
+    }
+}
+```
+
+`BaseController` 把 `execute()` 包在 `try/catch` 里，出错时调 `fallback()`。永远要写 `fallback` —— 原因见 [可观测性 · 错误处理](./08-observability.md#通过-fallback-处理错误)。
+
+## 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: "Error" }),
+    async renderApp(page) {
+        const html = await renderToString(createSSRApp(App, { page }));
+        return { html, head: `<title>${(page as { title: string }).title}</title>`, css: "" };
+    },
+});
+
+export { serializeServerData };
+```
+
+`createSSRRender` 返回一个函数，接 URL 输出渲染后的 HTML + 序列化的 prefetched intent 数据。Vite 插件和 adapter 会替你调用，不需要手动调。
+
+## 浏览器入口
+
+```ts
+// src/main.ts
+import { startBrowserApp } from "@finesoft/front/browser";
+import { createSSRApp } from "vue";
+import App from "./App.vue";
+import { bootstrap } from "./bootstrap";
+
+startBrowserApp({
+    bootstrap,
+    mount(target, { framework }) {
+        const app = createSSRApp(App, { framework });
+        app.mount(target);
+    },
+});
+```
+
+`startBrowserApp` 从 DOM 读 SSR 注入的 `PrefetchedIntents`，创建 `Framework`，跑同样的 `bootstrap()`，并触发首屏页面。`mount()` 跑的时候，框架已经准备好了初始的 `Page`。
+
+客户端从 `@finesoft/front/browser` 导入（不是 `@finesoft/front`），避免把服务端模块带进客户端 bundle。
+
+## 根组件（Vue 示例）
+
+```vue
+<!-- src/App.vue -->
+<script setup lang="ts">
+import { computed } from "vue";
+import type { Framework } from "@finesoft/front";
+
+const props = defineProps<{ framework?: Framework; page?: { title: string; items: string[] } }>();
+
+// SSR 直接收到 page；CSR 从 framework 取当前页面。
+const page = computed(() => props.page ?? props.framework?.getCurrentPage());
+</script>
+
+<template>
+    <main>
+        <h1>{{ page?.title }}</h1>
+        <ul>
+            <li v-for="item in page?.items" :key="item">{{ item }}</li>
+        </ul>
+    </main>
+</template>
+```
+
+## index.html
+
+```html
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <!--head-->
+    </head>
+    <body>
+        <div id="app"><!--ssr--></div>
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>
+```
+
+`<!--head-->` 和 `<!--ssr-->` 是框架注入 head 片段和渲染 HTML 的占位。占位名也通过 `SSR_PLACEHOLDERS` 导出。
+
+## 跑起来
+
+```bash
+pnpm dev          # 带 HMR 的开发服务器
+pnpm build        # 生产构建
+pnpm preview      # 本地预览生产构建
+```
+
+完成。你现在有一个应用：
+
+- 服务端渲染，带 prefetch 数据
+- Hydrate 不再多发请求（SSR 数据通过 `PrefetchedIntents` 复用）
+- 客户端路由无刷新
+- 已准备好部署到任一支持的 adapter
+
+## 下一步
+
+- [路由与 Controller](./02-routing-and-controllers.md) —— 定义更多路由、控制渲染方式
+- [项目结构](./engineering/project-structure.md) —— 应用长大后的推荐布局

package/docs/zh/02-routing-and-controllers.md

@@ -0,0 +1,197 @@
+# 2. 路由与 Controller
+
+框架的路由层把 URL 映射到 **intent**，把 intent 映射到 **Controller**，Controller 产出 **Page**。本章覆盖这三个概念。
+
+## 心智模型
+
+```
+URL  ──Router.resolve()──▶  RouteMatch { intent, renderMode, guards }
+                                │
+                                ▼
+                       IntentDispatcher.dispatch(intent)
+                                │
+                                ▼
+                         Controller.execute()  →  Page
+```
+
+一条路由定义包含：
+
+- **路径模式**（`/products/:id`）
+- **intent id**（操作的逻辑名；一个 intent 可以对应多条路由）
+- **Controller 实例**（产出页面数据）
+- 可选的**渲染模式**（`ssr` / `csr` / `prerender`）
+- 可选的**守卫**（`beforeLoad` / `afterLoad`）
+
+## 定义路由
+
+```ts
+// src/bootstrap.ts
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { HomeController } from "./lib/controllers/home";
+import { ProductController } from "./lib/controllers/product";
+import { authGuard } from "./lib/guards/auth";
+
+export function bootstrap(framework: Framework): void {
+    defineRoutes(framework, [
+        // 普通 SSR 路由
+        { path: "/", intentId: "home", controller: new HomeController() },
+
+        // 动态参数段
+        { path: "/products/:id", intentId: "product", controller: new ProductController() },
+
+        // 仅 CSR（服务端只返回空壳）
+        {
+            path: "/dashboard",
+            intentId: "dashboard",
+            controller: new DashboardController(),
+            renderMode: "csr",
+        },
+
+        // 构建期静态化
+        {
+            path: "/about",
+            intentId: "about",
+            controller: new AboutController(),
+            renderMode: "prerender",
+        },
+
+        // 受保护路由 —— 复用 home intent，但加守卫
+        {
+            path: "/admin",
+            intentId: "home",
+            controller: new HomeController(),
+            beforeLoad: [authGuard],
+        },
+    ]);
+}
+```
+
+### 路由选项
+
+| 字段         | 类型                             | 说明                                                           |
+| ------------ | -------------------------------- | -------------------------------------------------------------- |
+| `path`       | `string`                         | 路径模式，含 `:param` 占位。结尾的 `/` 会被归一化。            |
+| `intentId`   | `string`                         | 操作的逻辑名。用于注册 Controller。                            |
+| `controller` | `BaseController<TParams, TPage>` | 若 intent 已注册可省略。                                       |
+| `renderMode` | `"ssr" \| "csr" \| "prerender"`  | 默认 `"ssr"`。详见[第 4 章](./04-rendering-and-hydration.md)。 |
+| `beforeLoad` | `BeforeLoadGuard[]`              | Controller 之前执行。详见[第 3 章](./03-middleware.md)。       |
+| `afterLoad`  | `AfterLoadGuard[]`               | Page 产出之后执行。                                            |
+
+### 路径模式
+
+- 静态：`/about`
+- 带参数：`/products/:id`、`/users/:userId/posts/:postId`
+- 尾部通配：`/files/*`
+- **不**支持可选段 —— 写两条路由代替。
+
+参数以字符串键对象的形式传给 `controller.execute(params, container)`。
+
+## 写一个 Controller
+
+```ts
+// src/lib/controllers/product.ts
+import { BaseController, type Container, type HttpClient } from "@finesoft/front";
+
+interface ProductPage {
+    kind: "product";
+    id: string;
+    name: string;
+    price: number;
+}
+
+export class ProductController extends BaseController<{ id: string }, ProductPage> {
+    readonly intentId = "product";
+
+    async execute(params: { id: string }, container: Container): Promise<ProductPage> {
+        const http = container.resolve<HttpClient>("http");
+        const product = await http.get<{ name: string; price: number }>(
+            `/api/products/${params.id}`,
+        );
+        return {
+            kind: "product",
+            id: params.id,
+            name: product.name,
+            price: product.price,
+        };
+    }
+
+    fallback(params: { id: string }, _error: unknown): ProductPage {
+        return { kind: "product", id: params.id, name: "Not available", price: 0 };
+    }
+}
+```
+
+### Controller 契约
+
+| 成员       | 必需 | 用途                                                                        |
+| ---------- | ---- | --------------------------------------------------------------------------- |
+| `intentId` | 是   | 必须与路由的 `intentId` 一致（或与 `IntentDispatcher.register` 调用一致）。 |
+| `execute`  | 是   | 产出页面。接受解析后的路径参数和请求级 DI 容器。                            |
+| `fallback` | 是   | `execute()` 抛错时返回降级页面。必须同步且总能返回。                        |
+
+`BaseController` 把 `execute()` 包在 `try/catch` 里，错误都走 `fallback()`。框架从不让 `dispatch()` 抛错 —— 你的 `fallback()` 是最后一道防线。
+
+### 为什么 `fallback` 是必需的
+
+SSR 期间 `execute()` 抛错本来会让整个请求崩 —— 要么 500，要么渲出空白文档。`fallback()` 让你返回一个结构化的「错误」`Page`，让视图层渲成优雅失败（banner、重试按钮等）。完整模式见 [可观测性 · 错误处理](./08-observability.md#通过-fallback-处理错误)。
+
+## 渲染模式
+
+| 模式          | 服务端返回的内容                 | 适用场景                                    |
+| ------------- | -------------------------------- | ------------------------------------------- |
+| `"ssr"`       | 完整渲染的 HTML + 序列化数据     | 默认。SEO 和 TTFB 敏感的页面。              |
+| `"csr"`       | 空壳 HTML；Controller 在浏览器跑 | 鉴权后的 dashboard、高度个性化的页面。      |
+| `"prerender"` | 部署期生成的静态 HTML            | 营销页、文档、博客。结合 ISR（见第 4 章）。 |
+
+模式是**按路由**配置，可以自由混合。框架在构建期重生成 prerendered 路由；SSR 路由每次请求都执行。
+
+## 不绑路由也能注册 Controller
+
+可以为 intent 注册 Controller 但不暴露成路由。这对只通过 `dispatchAction` 触发的 intent 有用：
+
+```ts
+framework.intentDispatcher.register("checkout", new CheckoutController());
+
+// 别处：
+const page = await framework.intentDispatcher.dispatch({
+    intentId: "checkout",
+    params: { cartId },
+});
+```
+
+路由本质上就是按 URL 索引的 intent dispatch。
+
+## 一个 intent 多个路由
+
+同一个 intent 可以服务不同 URL：
+
+```ts
+defineRoutes(framework, [
+    { path: "/", intentId: "home", controller: new HomeController() },
+    { path: "/welcome", intentId: "home" }, // 复用已注册的 HomeController
+    { path: "/landing/:slug", intentId: "home" }, // 同 intent，参数不同
+]);
+```
+
+避免只是 URL 表面不同就复制 Controller 实例。前面例子里 `/admin` 复用 `home` intent 也是同一个套路。
+
+## 检查解析后的 match
+
+诊断或自定义路由时，可以直接调 `Router.resolve()`：
+
+```ts
+const match = framework.router.resolve("/products/42");
+// {
+//   intent: { intentId: "product", params: { id: "42" } },
+//   action: { kind: "flow", url: "/products/42" },
+//   renderMode: "ssr",
+//   guards: { before: [...], after: [...] },
+// }
+```
+
+未命中返回 `null` —— 在服务端 404 逻辑里处理它。
+
+## 下一步
+
+- [中间件](./03-middleware.md) —— 守卫导航、重定向、拒绝
+- [渲染与 Hydration](./04-rendering-and-hydration.md) —— Controller 产出 Page 之后发生什么