@finesoft/front 0.1.75 → 0.1.77

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

@@ -0,0 +1,163 @@
+# Pitfall: SSR hydration mismatch
+
+## Symptom
+
+After SSR, the browser console logs a hydration warning:
+
+```
+[Vue warn]: Hydration node mismatch — server rendered "<div>Loading...</div>" but client expected "<div>Welcome, Alice</div>"
+```
+
+The page flickers between the SSR-rendered content and the client-rendered content. State that should be already loaded triggers a refetch.
+
+## Root cause (most common)
+
+The server and the browser produced **different `Page` objects** for the same URL because something they read disagreed between sides:
+
+- Random / time-based values (`Math.random()`, `Date.now()`)
+- Reading `window` / `localStorage` / `document.cookie` on the server (these are `undefined`)
+- Reading `process.env` on the browser (these are `undefined` after bundling)
+- User-Agent-dependent rendering when SSR didn't see the real UA
+- Async race: the controller's `execute()` returned different data on each call
+
+The hydration cache (`PrefetchedIntents`) lookup missed, so the browser re-ran the controller — and got a different result.
+
+## Root cause (less common)
+
+The `PrefetchedIntents` key (intentId + stable-stringified params) doesn't match between server and browser:
+
+- Params object has values that don't stringify deterministically (Maps, Sets, class instances, Symbols)
+- Controller mutates `params` in place — the dispatch key was computed from the original, but the controller saw the mutated version
+
+## Diagnosis
+
+```ts
+// In your view, log the page on both sides:
+console.log("[hydration]", typeof window === "undefined" ? "SSR" : "CSR", page);
+```
+
+Compare the two logs. The first different field is the root cause.
+
+For `PrefetchedIntents` debugging, log the cache state in the browser:
+
+```ts
+startBrowserApp({
+    bootstrap,
+    onBeforeStart(framework) {
+        console.log("[prefetched]", framework.prefetchedIntents.dump());
+    },
+    mount: /* ... */,
+});
+```
+
+If the dump shows the intent **with different params** than what the browser's first navigation tries to dispatch, you've got a key mismatch.
+
+## Fix
+
+### Stop reading platform-only globals at module level
+
+```ts
+// BAD
+const userId = localStorage.getItem("uid"); // throws on SSR
+const isDarkMode = matchMedia("(prefers-color-scheme: dark)").matches; // throws on SSR
+const csrfToken = document.querySelector("meta[name=csrf]")?.content; // null on SSR
+
+export class HomeController extends BaseController {
+    /* uses userId */
+}
+```
+
+```ts
+// GOOD
+export class HomeController extends BaseController {
+    async execute(_params, container) {
+        // resolve from DI; the request scope has the right value on each side
+        const session = container.resolve<Session>("session");
+        return { kind: "home", userId: session.userId };
+    }
+}
+```
+
+Cookies are accessible on both sides via `container.resolve("session")` (after you register it). `localStorage` is browser-only — if the SSR side needs the same value, surface it via a cookie or query param.
+
+### Don't use randomness / time-based logic in `execute()`
+
+```ts
+// BAD — server and browser compute different values
+async execute() {
+    return { kind: "home", randomGreeting: pick(greetings) };
+}
+```
+
+If you need randomness, compute it once on the server and let the client reuse it via `PrefetchedIntents` (it does, automatically). Don't try to "re-randomize on the client" — that's exactly what causes mismatch.
+
+For time-based logic, decide on the server and ship the result:
+
+```ts
+async execute() {
+    const isOfficeHours = new Date().getHours() >= 9 && new Date().getHours() < 17;
+    return { kind: "home", isOfficeHours };
+}
+```
+
+Both sides will see `isOfficeHours: true` because the browser reads from cache, not re-evaluates.
+
+### Make `params` JSON-clean
+
+```ts
+// BAD — dispatchAction with non-serializable params
+framework.dispatch({
+    intentId: "search",
+    params: {
+        query: "widget",
+        filters: new Set(["red", "small"]), // Sets don't JSON.stringify well
+        startDate: new Date(), // becomes ISO string, OK, but...
+        validator: new Validator(), // class instance — won't survive
+    },
+});
+```
+
+```ts
+// GOOD — primitives + plain objects only
+framework.dispatch({
+    intentId: "search",
+    params: {
+        query: "widget",
+        filters: ["red", "small"],
+        startDate: "2026-05-14",
+    },
+});
+```
+
+The `PrefetchedIntents` cache uses **stable stringification** — same keys in different order produce the same key, and circular references are detected. But non-JSON values are coerced to strings or dropped silently.
+
+### Don't mutate `params`
+
+```ts
+// BAD
+async execute(params, container) {
+    params.userId = container.resolve("session").userId;   // mutation
+    return loadFor(params);
+}
+```
+
+```ts
+// GOOD
+async execute(params, container) {
+    const effective = { ...params, userId: container.resolve("session").userId };
+    return loadFor(effective);
+}
+```
+
+The dispatcher computed the cache key from the original `params`. If you mutate it, the next dispatch with the original shape misses the cache.
+
+## Why `stableStringify` matters
+
+The framework's `stableStringify` (in `packages/core/src/prefetched-intents/stable-stringify.ts`) handles object key ordering. It uses a `seen` Set with `try/finally` cleanup to support DAGs (same object referenced multiple times) — without the cleanup, a DAG would be reported as a false circular reference and the key would silently differ between server and browser.
+
+If you see "Circular reference detected" warnings during SSR but the data is genuinely a DAG, file a bug — the cleanup is supposed to handle this.
+
+## Related
+
+- [Pitfall: SSR vs CSR globals](./ssr-vs-csr-globals.md) — where the platform-only globals live
+- [Chapter 4: Rendering & hydration](../04-rendering-and-hydration.md) — how `PrefetchedIntents` works

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) —— 应用长大后的推荐布局