@finesoft/front 0.1.76 → 0.1.77

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

@@ -0,0 +1,182 @@
+# Pitfall: i18n bundle size
+
+## Symptom
+
+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:
+
+```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
+```
+
+### 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`)

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

@@ -0,0 +1,133 @@
+# Pitfall: proxy binary payloads
+
+## Symptom
+
+You proxy an upstream that returns an image / PDF / protobuf, and:
+
+- Images come through corrupted (broken thumbnails, gray boxes)
+- PDFs fail to open ("invalid PDF structure")
+- Protobuf clients throw "unexpected wire type" / decoding errors
+- File sizes are slightly different between source and proxied response
+
+The headers look fine. The status is 200. The body is what's broken.
+
+## Root cause
+
+Earlier versions of the proxy forwarded responses via `response.text()`. `text()` decodes bytes as **UTF-8** — which works for JSON and HTML but **destroys** any non-UTF-8 byte sequence:
+
+- Bytes that aren't valid UTF-8 are replaced with `U+FFFD` (the replacement character, `0xEF 0xBF 0xBD`)
+- The decoded string is then re-encoded as UTF-8 when it goes back into the response, producing a **different byte sequence than the original**
+
+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:
+
+```ts
+// packages/server/src/proxy.ts
+const body = await resp.arrayBuffer();
+return c.newResponse(body, resp.status, respHeaders);
+```
+
+This preserves the response byte-for-byte. Images render correctly, PDFs open, protobuf decodes.
+
+## Verifying
+
+The framework's own test (`packages/server/test/proxy.test.ts`) checks this with a PNG signature:
+
+```ts
+const binary = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xfe]);
+const fetchMock = vi.fn(
+    async () =>
+        new Response(binary, {
+            status: 200,
+            headers: { "Content-Type": "image/png" },
+        }),
+);
+
+// ... after the handler runs ...
+
+expect(new Uint8Array(capturedBuffer)).toEqual(binary);
+```
+
+If you suspect a proxy is corrupting binaries:
+
+```bash
+# Compare hashes of direct vs proxied
+curl -s https://upstream.example/image.png | sha256sum
+curl -s http://localhost:3000/api/image.png | sha256sum
+```
+
+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:
+
+- **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
+- **Diagnosing if a third-party proxy in front of yours has the same issue** — apply the same `arrayBuffer` test against it
+
+## Custom proxies — get this right
+
+If you write your own proxy code (outside the framework's `registerProxyRoutes`), use `arrayBuffer`:
+
+```ts
+// GOOD
+app.all("/api/*", async (c) => {
+    const resp = await fetch(targetUrl);
+    const body = await resp.arrayBuffer();
+    return c.newResponse(body, resp.status, {
+        "Content-Type": resp.headers.get("Content-Type") ?? "application/octet-stream",
+    });
+});
+```
+
+```ts
+// BAD — corrupts non-UTF-8 bytes
+app.all("/api/*", async (c) => {
+    const resp = await fetch(targetUrl);
+    return c.text(await resp.text(), resp.status);
+});
+```
+
+## Streaming for large bodies
+
+For responses >10 MB, the framework's bundled proxy rejects with HTTP 502 to avoid loading them entirely into memory. If you need to support larger responses, write a streaming proxy:
+
+```ts
+app.all("/api/*", async (c) => {
+    const resp = await fetch(targetUrl);
+    return new Response(resp.body, {
+        status: resp.status,
+        headers: {
+            "Content-Type": resp.headers.get("Content-Type") ?? "application/octet-stream",
+        },
+    });
+});
+```
+
+`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
+
+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.
+
+## Why `Content-Length` and `byteLength` both
+
+`Content-Length` is what the upstream **claims**. `byteLength` is what actually arrived. Some upstreams send `Content-Length: 1000` but stream 10MB. Some omit `Content-Length` entirely.
+
+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
+
+## Related
+
+- [Chapter 9: Server & deployment — proxy routes](../09-server-and-deployment.md#proxy-routes)
+- The actual implementation: `packages/server/src/proxy.ts`
+- The regression test: `packages/server/test/proxy.test.ts`

package/docs/pitfalls/redirect-vs-rewrite.md

@@ -0,0 +1,147 @@
+# Pitfall: redirect vs rewrite
+
+## Symptom A — wrong URL in the address bar
+
+A guard runs `rewrite("/canonical")`, but the user sees `/canonical` in the address bar. You wanted the original URL preserved.
+
+## Symptom B — extra round-trip
+
+A guard runs `redirect("/login")`, the browser shows a flicker / network panel shows a 302 → 200 round-trip. You wanted in-process re-routing.
+
+## Symptom C — `afterLoad` rewrite seemed to issue a 301
+
+A guard in `afterLoad` returns `rewrite("/clean-url")`. The browser hits the rewrite URL, gets the canonical content, and your server logs show two requests. You expected one.
+
+## Root cause
+
+`redirect` and `rewrite` look similar but mean fundamentally different things, and `rewrite` itself behaves differently in `beforeLoad` vs `afterLoad`.
+
+| Result                            | What happens                                                             | Visible to user as                           | Use for                                           |
+| --------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------- | ------------------------------------------------- |
+| `redirect("/foo", 302)`           | HTTP 302 with `Location: /foo` (server) or `pushState("/foo")` (browser) | Address bar changes to `/foo`                | Auth gates, locale redirects, deprecated paths    |
+| `redirect("/foo", 301)`           | Same but cacheable as permanent                                          | Address bar changes; cached                  | Permanent canonicalization                        |
+| `rewrite("/foo")` in `beforeLoad` | Router resolves `/foo` instead; new match's guards + controller run      | Address bar stays original                   | A/B tests, feature-flag routing, internal aliases |
+| `rewrite("/foo")` in `afterLoad`  | `Content-Location: /foo` header; controller already ran                  | Address bar stays original; no extra request | Canonical-URL signal to crawlers; analytics dedup |
+
+## The semantic difference
+
+**Redirect** = "the user should be at a different URL." The address bar is the source of truth, and the framework tells the browser to update it.
+
+**Rewrite in `beforeLoad`** = "this URL maps to another internally." The user's URL stays; the framework picks a different controller to satisfy the request. Like Nginx's `rewrite ... last;`.
+
+**Rewrite in `afterLoad`** = "this content is also available at a canonical URL." The page already rendered (the controller already ran); the response just includes a hint via `Content-Location`. The browser does **not** follow it as a redirect — it's metadata.
+
+## Fix Symptom A — you used `redirect` when you wanted `rewrite`
+
+```ts
+// BAD — user sees /landing-v2 in address bar
+function abTestGuard(ctx: NavigationContext) {
+    if (ctx.url.pathname !== "/landing") return next();
+    return bucket(ctx) === "B" ? redirect("/landing-v2") : next();
+}
+```
+
+```ts
+// GOOD — user keeps /landing, server renders /landing-v2 internally
+function abTestGuard(ctx: NavigationContext) {
+    if (ctx.url.pathname !== "/landing") return next();
+    return bucket(ctx) === "B" ? rewrite("/landing-v2") : next();
+}
+```
+
+Same applies to mobile routing, feature flags, locale-based content swapping — anything where the user shouldn't notice the underlying URL changed.
+
+## Fix Symptom B — you used `rewrite` when you wanted `redirect`
+
+```ts
+// BAD — user remains on the protected URL; the wrong controller runs
+function authGuard(ctx: NavigationContext) {
+    if (!ctx.getCookie("token")) return rewrite("/login");
+    return next();
+}
+```
+
+If `rewrite` is used here:
+
+- The address bar stays at `/admin` (confusing — the user thinks they're already at admin)
+- A reload re-runs the login page logic but doesn't change the URL
+- Bookmarking `/admin` from this state bookmarks a broken URL
+
+```ts
+// GOOD — actually navigate to /login
+function authGuard(ctx: NavigationContext) {
+    if (!ctx.getCookie("token"))
+        return redirect("/login?next=" + encodeURIComponent(ctx.url.pathname));
+    return next();
+}
+```
+
+## Fix Symptom C — `afterLoad` rewrite is canonicalization, not 301
+
+If you actually want a 301 from `afterLoad`, use `redirect`:
+
+```ts
+afterLoad: [
+    (ctx) => {
+        if (ctx.url.search.includes("utm_")) {
+            const clean = ctx.url.pathname;
+            return redirect(clean, 301);
+        }
+        return next();
+    },
+],
+```
+
+But note: by the time `afterLoad` runs, **the controller already executed**. If `execute()` had side effects (writes, expensive computation), they happened. Use `beforeLoad` for redirects you want to fire before the work runs.
+
+If you want to ship the rendered page **and** signal "by the way, the canonical URL is /clean":
+
+```ts
+afterLoad: [
+    (ctx) => {
+        if (ctx.url.search.includes("utm_")) {
+            return rewrite(ctx.url.pathname);  // no extra request
+        }
+        return next();
+    },
+],
+```
+
+The response includes `Content-Location: /clean`. Crawlers (Google, Bing) use this for canonical resolution; analytics tools can deduplicate the variants.
+
+## The `rewrite` recursion depth limit
+
+`beforeLoad` rewrites recurse — the new URL's `beforeLoad` chain runs in full, including any rewrites it triggers. The framework caps this at **5 levels** (`MAX_SSR_REWRITE_DEPTH`) to prevent runaway loops.
+
+If you hit:
+
+```
+Error: Too many SSR rewrites (max 5): /a → /b → /c → /d → /e → /f
+```
+
+You have a guard loop. Common cause: a guard rewrites to a URL whose own guard rewrites back.
+
+```ts
+// BAD — /landing rewrites to /v2 which rewrites to /landing
+const landingGuard = (ctx) => (ctx.url.pathname === "/landing" ? rewrite("/v2") : next());
+const v2Guard = (ctx) =>
+    ctx.url.pathname === "/v2" && !ctx.getCookie("v2") ? rewrite("/landing") : next();
+```
+
+Fix the loop, not the depth limit.
+
+## Decision tree
+
+```
+Need to change what URL the user sees?
+├── Yes → redirect (302 for temporary, 301 for permanent)
+└── No, URL stays the same
+    ├── Need to swap which controller runs?    → rewrite in beforeLoad
+    ├── Already rendered; want canonical hint? → rewrite in afterLoad
+    └── Need to abort with an error?           → deny(status, message)
+```
+
+## Related
+
+- [Chapter 3: Middleware](../03-middleware.md) — the four results explained
+- The behavior change was deliberately introduced — see `packages/ssr/src/render.ts` `ssrRenderInternal` and the `rewriteUrl` field

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