@finesoft/front 0.5.0 → 0.5.2

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

@@ -1,182 +1,12 @@
-# Pitfall: i18n bundle size
+# Locale bundle size
 
-## Symptom
+A static import of every locale adds those messages to the browser bundle. Use the generated locale loader at the application definition boundary.
 
-Lighthouse complains about a large initial JS payload. Network panel shows a huge chunk on first request. Your `dist/client/assets/index-*.js` is bigger than it should be, and `vp build --analyze` shows the messages folder dominating the bundle.
-
-## Root cause
-
-Translations got bundled into the main client chunk instead of being split per locale. Either:
-
-- You imported `src/locales/*.json` directly at module top:
-
-    ```ts
-    import zh from "../locales/zh-Hans.json";
-    import en from "../locales/en-US.json";
-    import ja from "../locales/ja-JP.json";
-    ```
-
-    All three locales now live in every user's bundle, even though each user only sees one.
-
-- You built a `Translator` with all messages inlined at module top:
-
-    ```ts
-    const t = new SimpleTranslator({
-        locale: "en-US",
-        messages: { ...zhMessages, ...enMessages, ...jaMessages },
-    });
-    ```
-
-- You serialized translations into HTML via `serializeServerData`, so every SSR page response includes the full dictionary.
-
-## Fix
-
-### Use `messagesDir` instead of static imports
-
-Configure the Vite plugin:
+## Loader / 加载器
 
 ```ts
-finesoftFrontViteConfig({
-    i18n: { messagesDir: "src/locales" },
-});
-```
-
-The plugin generates a per-locale loader. On the server it reads from disk; on the browser it dynamic-imports the appropriate chunk. Vite splits each locale's JSON into its own chunk, and only the chunk matching the resolved locale is fetched.
-
-```
-dist/client/assets/
-├── index-abc123.js       ← main bundle (no translations)
-├── locale-en-US-def456.js ← only loaded for en-US visitors
-├── locale-zh-Hans-789.js  ← only loaded for zh-Hans visitors
-└── locale-ja-JP-xyz.js    ← only loaded for ja-JP visitors
+import { loadMessages } from "virtual:finesoft-front/i18n-loader";
+// defineWebApp({ ..., loadMessages })
 ```
 
-### Don't serialize translations into HTML
-
-The framework deliberately does **not** include the dictionary in `PrefetchedIntents`. The browser fetches its locale chunk in parallel with the initial render.
-
-If you've been manually injecting translations into the page via your own mechanism, stop:
-
-```html
-<!-- BAD — every SSR response carries the dictionary -->
-<script>
-    window.__TRANSLATIONS__ = { hello: "你好" /* hundreds of keys */ };
-</script>
-```
-
-```ts
-// GOOD — the framework loads it as a separate chunk
-// (handled automatically when you use messagesDir)
-```
-
-### Check what's actually shipping
-
-```bash
-vp build
-ls -lah dist/client/assets/locale-*
-ls -lah dist/client/assets/index-*
-```
-
-The index chunk should not change when you add a new locale's JSON. If it does, something's wrong.
-
-For a visual breakdown:
-
-```bash
-vp build --analyze
-```
-
-This opens an interactive treemap of bundle contents. Locale chunks should be small (KB), separate, and named.
-
-## How big is "too big"?
-
-Rough thresholds for first-paint critical JS (the index chunk):
-
-- Static marketing site: <50 KB gzipped
-- Standard SPA: <150 KB gzipped
-- Heavy dashboard: <300 KB gzipped
-
-If translations push your index chunk past these, separate them. Per-locale chunks of 10-50 KB are normal and shouldn't worry you.
-
-## Server-side: the dictionary is cached, not bundled
-
-On the server, the framework reads the locale JSON from disk on first request and caches it for subsequent requests:
-
-```
-Request 1 (zh-Hans): disk read of zh-Hans.json, cached
-Request 2 (zh-Hans): served from cache
-Request 3 (en-US):   disk read of en-US.json, cached
-```
-
-You don't ship a huge SSR bundle either — `tsdown` packages your server entry, but the locale JSONs are read from disk at runtime, not embedded.
-
-This means:
-
-- ✅ Cold-start cost: one disk read per locale, once per worker
-- ✅ Steady-state: zero overhead — locales sit in a `Map`
-- ❌ Mutability: edit a JSON, server keeps the cached old version until restart
-
-The mutability issue isn't usually a problem because you commit translations to source control and a redeploy reloads them. For runtime-updated translations, use the custom `loadMessages` callback to fetch from a service.
-
-## What if my dictionary is genuinely huge?
-
-If a single locale's dictionary is multiple MB (rare — most apps fit in <100 KB):
-
-### Split by namespace
-
-```
-src/locales/
-├── en-US/
-│   ├── common.json
-│   ├── checkout.json
-│   ├── admin.json
-│   └── help-center.json
-└── zh-Hans/
-    └── ...
-```
-
-Build a custom `loadMessages` that loads only the namespaces a given page needs:
-
-```ts
-createSSRRender({
-    bootstrap,
-    async loadMessages(locale) {
-        // load only "common" eagerly; lazy-load others on demand
-        return import(`./locales/${locale}/common.json`);
-    },
-    async renderApp(page) {
-        /* ... */
-    },
-});
-```
-
-The view layer can then call `await translator.loadNamespace("admin")` before rendering admin-specific strings.
-
-### Lazy-load on view mount
-
-For very large optional dictionaries (help content, error code messages), fetch them on demand from the view layer rather than at framework startup. The framework doesn't need to know about them — they're just data.
-
-## Network-side optimization
-
-Even with proper splitting, you can speed up the locale fetch:
-
-- Set long `Cache-Control` on locale chunks (Vite's content-hash filenames make this safe)
-- Preload the user's locale chunk:
-    ```html
-    <link rel="preload" href="/assets/locale-en-US-def456.js" as="script" crossorigin />
-    ```
-- For high-traffic apps, push the locale chunk over the same HTTP/2 connection as the main JS
-
-## Why not just put translations in the HTML?
-
-Because:
-
-- Every page response ships the entire dictionary — including content for pages the user never visits
-- HTML can't be cached at the CDN level when it varies by locale and contains the dictionary
-- SSR latency increases linearly with dictionary size
-
-The per-locale chunk is the right tradeoff: shipped once, cached forever, only for the locale the user actually has.
-
-## Related
-
-- [Chapter 5: i18n](../05-i18n.md) — the full picture of locale handling
-- The Vite plugin source: `packages/server/src/vite-plugin.ts` (search for `messagesDir`)
+Inspect production chunks and gzip totals using identical routes and build settings. A smaller entry file alone may only move bytes into another chunk. SSR and client locale must agree before hydration.

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

@@ -20,11 +20,12 @@ Earlier versions of the proxy forwarded responses via `response.text()`. `text()
 
 A PNG file starts with `0x89 0x50 0x4E 0x47 0x0D 0x0A 0x1A 0x0A` — the leading `0x89` is not valid UTF-8, so it becomes `0xEF 0xBF 0xBD`. The browser's image decoder sees garbage starting at byte 0 and bails.
 
-The current implementation uses `response.arrayBuffer()` and forwards bytes verbatim:
+The current implementation counts streamed bytes against a 10 MiB limit, then combines the bounded chunks into an `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 @@ Different hash = corruption. Same hash = the proxy is fine, look elsewhere.
 
 ## When you'd hit this
 
-If you're on the current version (which uses `arrayBuffer`), you won't. This pitfall exists primarily as historical context for:
+If you're on the current version (which preserves raw bytes), you won't. This pitfall exists primarily as historical context for:
 
 - **Upgrading from an older version** — verify your binary endpoints after upgrade
 - **Building your own custom proxy logic** — if you copy from older examples, you'll reintroduce the bug
@@ -69,7 +70,7 @@ If you're on the current version (which uses `arrayBuffer`), you won't. This pit
 
 ## Custom proxies — get this right
 
-If you write your own proxy code (outside the framework's `registerProxyRoutes`), use `arrayBuffer`:
+Custom proxies must also preserve bytes. The `arrayBuffer` example below requires an independent response-size limit; prefer the framework's bounded reader for untrusted upstreams:
 
 ```ts
 // GOOD
@@ -108,14 +109,9 @@ app.all("/api/*", async (c) => {
 
 `resp.body` is a `ReadableStream`. Returning it directly streams bytes without buffering. But you lose the size-limit guard — only do this if you trust the upstream.
 
-## The size limit lives in two places
+## One implementation enforces both size checks
 
-The framework enforces `MAX_RESPONSE_SIZE = 10 * 1024 * 1024` (10 MB) in two paths:
-
-1. **Runtime** (`registerProxyRoutes`): checks `Content-Length` header first, then `body.byteLength` after fetch
-2. **Generated code** (`generateProxyCode`): the inlined version for serverless emits the same two checks
-
-If you change the limit in one place, change both. The test `generated proxy code embeds the same response size limit as runtime (parity)` enforces this.
+The framework enforces `MAX_RESPONSE_SIZE = 10 * 1024 * 1024` (10 MB) in `registerProxyRoutes`: it checks the `Content-Length` header first, then counts each received chunk and cancels immediately when the limit is exceeded. `generateProxyCode` emits a registration call to this same implementation, so development and deployment cannot drift into different limits. Tests execute generated registration and a built deployment entry, including binary payloads and oversize rejection.
 
 ## Why `Content-Length` and `byteLength` both
 
@@ -124,7 +120,7 @@ If you change the limit in one place, change both. The test `generated proxy cod
 The double check covers both:
 
 - Fast-reject on declared `Content-Length` to avoid downloading 100MB just to reject it
-- Final reject on actual bytes received in case `Content-Length` was missing or lying
+- Immediate rejection when actual received bytes exceed the budget in case `Content-Length` was missing or lying
 
 ## Related
 

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

@@ -1,163 +1,7 @@
-# Pitfall: SSR hydration mismatch
+# Hydration mismatch
 
-## Symptom
+Share the same page definition, App and Outlet view registry between browser and SSR. Use `createSSRRender({ definition, render: app => nativeRender(app) })` on the server. In the browser, select native hydrate or mount using `app.shouldHydrate`, mount first, then await `app.ready`.
 
-After SSR, the browser console logs a hydration warning:
+Hydrate the server snapshot before restoring persisted state. Avoid random values, time or browser globals during the first render. Do not await ready before mounting or manually mutate Outlet's child tree.
 
-```
-[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
+Declare explicit public projections; nested data needs a nested declaration or codec. Wire/buildId mismatches trigger fresh loading. Inspect browser warnings, DOM, requests and entry identity when diagnosing a mismatch.

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

@@ -1,176 +1,15 @@
-# Pitfall: SSR vs CSR globals
+# Environment boundaries
 
-## Symptom
+All APIs import from `@finesoft/front`; each API still requires its appropriate runtime. The package and compiler select internal implementations without loading unused UI or platform peers.
 
-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:
+## Boundaries / 边界
 
 ```ts
-// import-time check
-if (typeof window !== "undefined") {
-    // never actually called on SSR
-    setupAnalytics();
-}
+import { defineOperation } from "@finesoft/front";
+// createBrowserApp: browser
+// startNodeHandler: Node
+// createHttpHandler: Request/Response host (Node or Worker)
+// finesoftFrontViteConfig: build configuration
 ```
 
-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
+Do not read window/document/storage at module evaluation in shared application declarations. UI bindings select only the chosen framework. Node DNS and filesystem code must remain out of browser/Worker graphs. Test the built installed package in its actual runtime; source alias imports can hide missing artifacts.