@finesoft/front 0.1.75 → 0.1.77

package/docs/03-middleware.md

@@ -0,0 +1,214 @@
+# 3. Middleware
+
+Middleware runs in two phases around the controller. A guard inspects the navigation, then returns one of four results to control what happens next.
+
+## Pipeline
+
+```
+Router.resolve()
+     │
+     ▼
+  beforeLoad chain        ← NavigationContext (no page yet)
+     │
+   next()? ──no──▶ short-circuit (redirect / rewrite / deny)
+     │ yes
+     ▼
+IntentDispatcher.dispatch()
+     │
+     ▼
+  afterLoad chain         ← PostLoadContext (page exists)
+     │
+   next()? ──no──▶ short-circuit
+     │ yes
+     ▼
+   render
+```
+
+Guards run in array order. The first non-`next()` result short-circuits the rest of the chain.
+
+## The four results
+
+```ts
+import { next, redirect, rewrite, deny } from "@finesoft/front";
+
+next(); // continue to the next guard / dispatcher
+redirect("/login"); // HTTP 302; navigate to URL
+redirect("/old", 301); // HTTP 301 (permanent)
+rewrite("/canonical"); // internal re-route in beforeLoad; canonicalization signal in afterLoad
+deny(); // 403 Forbidden
+deny(404, "Not found"); // custom status + message
+```
+
+### `next()`
+
+Pass-through. The pipeline continues.
+
+### `redirect(url, status?)`
+
+The browser navigates to `url` and the original render is abandoned. On the server this becomes an HTTP redirect; on the browser it becomes a navigation (via `History.pushState`).
+
+Use for: login redirects, deprecated paths, locale-prefix canonicalization.
+
+### `rewrite(url)`
+
+**`beforeLoad` rewrite** — internal re-route. The router resolves `url` instead, and the _new_ match's guards + controller run. No HTTP redirect is emitted; the original URL stays in the address bar. Bounded depth (5 levels) to prevent loops.
+
+**`afterLoad` rewrite** — canonicalization signal. The framework includes the rewrite URL in the SSR response as a `Content-Location` header without redirecting. Browsers receive the original URL with a hint that a canonical version exists.
+
+See [redirect vs rewrite](./pitfalls/redirect-vs-rewrite.md) for when to use which.
+
+### `deny(status?, message?)`
+
+Stops the request. Default `403 Forbidden`. Common: `deny(401, "Login required")`, `deny(404, "Not found")`.
+
+## Writing guards
+
+A guard is a function from context to a `MiddlewareResult` (or `Promise<MiddlewareResult>`).
+
+```ts
+// src/lib/guards/auth.ts
+import { next, redirect, type NavigationContext } from "@finesoft/front";
+
+export function authGuard(ctx: NavigationContext) {
+    const token = ctx.getCookie("token");
+    if (!token) {
+        return redirect(`/login?next=${encodeURIComponent(ctx.url.pathname)}`);
+    }
+    return next();
+}
+```
+
+### `NavigationContext` (beforeLoad)
+
+| Field             | Type                               | Notes                                                |
+| ----------------- | ---------------------------------- | ---------------------------------------------------- |
+| `url`             | `URL`                              | Full request URL.                                    |
+| `intent`          | `Intent`                           | Resolved intent with parsed path params.             |
+| `container`       | `Container`                        | Request-scoped DI container.                         |
+| `getCookie(name)` | `(name: string) => string \| null` | Read a cookie (server + browser).                    |
+| `getHeader(name)` | `(name: string) => string \| null` | Read a request header (server only; browser → null). |
+| `isSsr`           | `boolean`                          | `true` on server, `false` in browser.                |
+
+### `PostLoadContext` (afterLoad)
+
+Extends `NavigationContext` with:
+
+| Field  | Type       | Notes                                |
+| ------ | ---------- | ------------------------------------ |
+| `page` | `BasePage` | The page produced by the controller. |
+
+## Attaching guards to routes
+
+```ts
+defineRoutes(framework, [
+    {
+        path: "/admin",
+        intentId: "admin",
+        controller: new AdminController(),
+        beforeLoad: [authGuard, requireAdminRole],
+        afterLoad: [trackPageView],
+    },
+]);
+```
+
+Guards on a route run **in addition** to any global guards registered on the framework (see below). Order: globals first, then route-specific.
+
+## Global guards
+
+Register guards that apply to every navigation:
+
+```ts
+framework.middleware.use("beforeLoad", trackingGuard);
+framework.middleware.use("afterLoad", metricsGuard);
+```
+
+Use sparingly. Global guards run on every page, including SSR — slow global guards multiply across the entire surface area.
+
+## Common patterns
+
+### Authentication
+
+```ts
+function authGuard(ctx: NavigationContext) {
+    const token = ctx.getCookie("session");
+    if (!token) return redirect("/login?next=" + encodeURIComponent(ctx.url.pathname));
+    return next();
+}
+```
+
+### Role check
+
+```ts
+async function requireAdmin(ctx: NavigationContext) {
+    const session = await ctx.container.resolve<SessionService>("session").current();
+    if (!session?.isAdmin) return deny(403, "Admin only");
+    return next();
+}
+```
+
+### Locale prefix redirect
+
+```ts
+function localePrefixGuard(ctx: NavigationContext) {
+    if (/^\/(en|zh|ja)\//.test(ctx.url.pathname)) return next();
+    const detected = detectLocale(ctx); // your own logic
+    return redirect(`/${detected}${ctx.url.pathname}`, 301);
+}
+```
+
+### A/B test rewrite
+
+```ts
+function abTestGuard(ctx: NavigationContext) {
+    if (ctx.url.pathname !== "/landing") return next();
+    const variant = bucket(ctx.getCookie("uid"));
+    return variant === "B" ? rewrite("/landing-v2") : next();
+}
+```
+
+The user sees `/landing` in the address bar; the server renders `/landing-v2`. No client-visible redirect, no flicker.
+
+### After-load analytics
+
+```ts
+function trackPageView(ctx: PostLoadContext) {
+    ctx.container.resolve<EventRecorder>("eventRecorder").record({
+        name: "PageView",
+        fields: { intentId: ctx.intent.intentId, url: ctx.url.pathname },
+    });
+    return next();
+}
+```
+
+## Guard ordering rules
+
+1. Global `beforeLoad` guards (registration order)
+2. Route-specific `beforeLoad` guards (array order)
+3. Controller `execute()`
+4. Global `afterLoad` guards
+5. Route-specific `afterLoad` guards
+
+A non-`next()` result at any step stops the rest. Subsequent guards do not run.
+
+## Async guards
+
+Guards can be `async`. The pipeline awaits each result before moving on. Avoid long awaits in global guards (they multiply across every request).
+
+```ts
+async function rateLimitGuard(ctx: NavigationContext) {
+    const limiter = ctx.container.resolve<RateLimiter>("rateLimiter");
+    const allowed = await limiter.tryConsume(ctx.getCookie("uid") ?? "anon");
+    return allowed ? next() : deny(429, "Too many requests");
+}
+```
+
+## Caveats
+
+- **Guards must be pure with respect to the framework state.** Don't mutate `ctx.intent.params` — make a new intent and `rewrite` if you need to change params.
+- **`deny()` in `afterLoad` discards the produced page.** The controller already ran; deny only blocks the response. If `execute()` had side effects (writes), they already happened.
+- **Browser-side guards do not have access to request headers.** `getHeader()` returns `null` on the client. Cookies still work.
+
+## Next
+
+- [Rendering & hydration](./04-rendering-and-hydration.md) — what happens between `afterLoad` and HTML output
+- [Pitfalls: redirect vs rewrite](./pitfalls/redirect-vs-rewrite.md) — choosing between the two

package/docs/04-rendering-and-hydration.md

@@ -0,0 +1,271 @@
+# 4. Rendering & hydration
+
+How a page travels from controller output to bytes on the wire, then back into a live browser app. This chapter covers SSR, CSR, prerender, and the `PrefetchedIntents` machinery that ties them together.
+
+## The three modes side by side
+
+|                             | SSR                              | CSR                              | Prerender                        |
+| --------------------------- | -------------------------------- | -------------------------------- | -------------------------------- |
+| When HTML is built          | Per request, on the server       | At build time (shell only)       | At build time, per route         |
+| Initial body                | Fully rendered                   | Empty `<div id="app"></div>`     | Fully rendered                   |
+| Initial fetch on hydration? | No (data in `PrefetchedIntents`) | Yes (controller runs in browser) | No (data in `PrefetchedIntents`) |
+| TTFB                        | One controller execution         | Near-zero                        | Static file serve                |
+| Personalization             | Per-request OK                   | Best — runs entirely client-side | None (same HTML for everyone)    |
+| SEO                         | Good                             | Requires JS-aware crawlers       | Best                             |
+
+Mode is **per-route**. Mix freely.
+
+## SSR pipeline
+
+```
+Request URL
+    │
+    ▼
+Router.resolve()                 → RouteMatch
+    │
+    ▼
+beforeLoad guards                → may rewrite (internal) / redirect / deny
+    │
+    ▼
+IntentDispatcher.dispatch()      → Page
+    │
+    ▼
+afterLoad guards                 → may redirect / deny / signal canonicalization
+    │
+    ▼
+renderApp(page)                  → { html, head, css }
+    │
+    ▼
+injectSSRContent()               → final HTML with:
+    • rendered body in <!--ssr-->
+    • head fragment in <!--head-->
+    • serialized PrefetchedIntents in a <script> tag
+    • <html lang="..." dir="..."> attributes
+```
+
+### SSR entry
+
+```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: "Something went wrong" }),
+    async renderApp(page) {
+        const app = createSSRApp(App, { page });
+        const html = await renderToString(app);
+        return {
+            html,
+            head: `<title>${escape(page.title)}</title>`,
+            css: "",
+        };
+    },
+});
+
+export { serializeServerData };
+```
+
+The Vite plugin and adapters call `render(url, options)` for you. You return `{ html, head, css }`; the framework handles injection and serialization.
+
+### What `createSSRRender` does for you
+
+- Runs `bootstrap()` once on the server (cached across requests in the same worker)
+- Creates a request-scoped DI container per request
+- Runs the middleware pipeline
+- Calls your `renderApp()` to produce the body
+- Serializes prefetched intent results into a `<script id="__finesoft_data__">` tag
+- Sets `<html lang dir>` from the resolved locale
+- Sets HTTP status from `deny()` / `redirect()` / `rewrite()` results
+- Adds `Content-Location` header when `afterLoad` signaled a rewrite
+
+## CSR (client-side render)
+
+For routes marked `renderMode: "csr"`, the server returns a minimal shell:
+
+```html
+<!doctype html>
+<html lang="en">
+    <head>
+        <!-- head injected here -->
+    </head>
+    <body>
+        <div id="app"></div>
+        <!-- no PrefetchedIntents script — controller runs in browser -->
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>
+```
+
+The controller runs in the browser when `startBrowserApp()` triggers the first navigation. Use CSR for:
+
+- Heavily personalized dashboards behind auth
+- Pages where SEO doesn't matter
+- Pages where server-side rendering cost outweighs the latency benefit
+
+## Prerender (static + ISR)
+
+```ts
+{ path: "/about", intentId: "about", controller: new AboutController(), renderMode: "prerender" }
+```
+
+At build time the framework:
+
+1. Calls `controller.execute({}, container)` (path params from the static path)
+2. Runs `renderApp()` to produce HTML
+3. Writes `dist/about.html` to disk
+
+The adapter serves these static files directly. No controller runs at request time.
+
+### Incremental Static Regeneration (ISR)
+
+The bundled server (`createServer`) and the preview server (`vp preview`) support cached on-demand regeneration. Configure via `finesoftFrontViteConfig`:
+
+```ts
+finesoftFrontViteConfig({
+    ssr: { entry: "src/ssr.ts" },
+    isr: {
+        // routes that should regenerate on demand
+        routes: ["/blog/*"],
+        // cache TTL in seconds
+        ttl: 300,
+    },
+});
+```
+
+The first request after expiry triggers a fresh render; concurrent requests get the stale version until the regeneration completes. See [server & deployment](./09-server-and-deployment.md#isr) for details.
+
+## `PrefetchedIntents` — the SSR → CSR bridge
+
+The crucial mechanic: **the same controller produces a page on the server, and the browser reuses that result without refetching.**
+
+### How it works
+
+1. SSR: controller runs, returns `Page`. The framework stores `(intentId, paramsKey) → Page` in a `PrefetchedIntents` map.
+2. Render: the map is JSON-stringified into `<script id="__finesoft_data__">{...}</script>`.
+3. Browser: `startBrowserApp` reads the script, calls `createPrefetchedIntentsFromDom()`, passes it to `Framework.create()`.
+4. First navigation in the browser: `IntentDispatcher.dispatch()` checks the map by `(intentId, paramsKey)` — if hit, returns the cached `Page` directly without calling the controller.
+
+### Stable key generation
+
+The lookup key is generated from `intentId` + the **stable JSON stringification** of `params`. Object key order does not affect the key:
+
+```ts
+// These produce the same paramsKey:
+dispatch({ intentId: "product", params: { id: "42", color: "red" } });
+dispatch({ intentId: "product", params: { color: "red", id: "42" } });
+```
+
+If you write a controller that resolves the same logical request from different `params` shapes, factor it into a normalization step before dispatch.
+
+### When the cache misses
+
+- New navigation to an intent not prefetched on the server (e.g., dynamic route the user clicked)
+- Stale cache after `PrefetchedIntents.invalidate(intentId, params)`
+- Browser-side mutation guards (custom)
+
+A miss falls through to the regular dispatcher path — `execute()` runs in the browser.
+
+## Hydration step-by-step
+
+```
+Server                        Browser
+──────                        ───────
+bootstrap(framework)
+    ▼                              │
+controller.execute()                │
+    ▼                              │
+Page A                              │
+    ▼                              │
+serialize → <script>                │
+    ▼                              │
+HTML response ────────────────▶  Receive HTML
+                                    ▼
+                              createPrefetchedIntentsFromDom()
+                                    ▼
+                              Framework.create({ prefetchedIntents })
+                                    ▼
+                              bootstrap(framework)    ← same code, same routes
+                                    ▼
+                              dispatch(currentIntent)
+                                    ▼
+                              Cache hit → Page A     ← no refetch
+                                    ▼
+                              mount(app)
+```
+
+The bootstrap runs twice — once on each side — with identical inputs. This is what guarantees the browser-side initial route matches the server-rendered HTML.
+
+## SSR head injection
+
+`renderApp()` returns a `head` fragment. The framework injects it at the `<!--head-->` placeholder along with:
+
+- `<script id="__finesoft_data__">` with serialized data (SSR mode only)
+- `<link>` / `<script>` for client entry (production builds)
+- `<html lang="..." dir="...">` attributes from the resolved locale
+
+Custom meta tags go in your `head` string:
+
+```ts
+async renderApp(page) {
+    return {
+        html: await renderToString(/*...*/),
+        head: [
+            `<title>${escape(page.title)}</title>`,
+            `<meta name="description" content="${escape(page.description)}">`,
+            `<meta property="og:title" content="${escape(page.title)}">`,
+        ].join(""),
+        css: "",
+    };
+}
+```
+
+Always escape user-provided strings — they go straight into HTML.
+
+## CSS injection
+
+If your render produces critical CSS (e.g., Vue scoped styles or `vanilla-extract`), return it as `css`:
+
+```ts
+return {
+    html,
+    head: `<title>${title}</title>`,
+    css: extractedCriticalCss, // injected as <style> in <head>
+};
+```
+
+For Vite-managed stylesheets, leave `css: ""` — the Vite plugin handles them.
+
+## Status codes
+
+The HTTP status of the SSR response follows this priority:
+
+1. Middleware result: `deny(404)` → 404; `redirect(url, 301)` → 301 with `Location` header.
+2. Page-level: a `Page` of `kind: "error"` returned by `fallback()` results in 500 (configurable via `getErrorPage`).
+3. Default: 200.
+
+Override via `afterLoad`:
+
+```ts
+afterLoad: [
+    (ctx) => {
+        if (ctx.page.kind === "not-found") return deny(404, "Not found");
+        return next();
+    },
+],
+```
+
+## Streaming SSR
+
+Currently not supported. The framework awaits `renderApp()` fully before sending bytes. For most apps this is fine — `IntentDispatcher` parallelizes data fetching inside `execute()` if your controller awaits multiple HTTP calls together.
+
+If you need streaming for a specific large page, consider rendering it CSR and using your view layer's own streaming primitives.
+
+## Next
+
+- [i18n](./05-i18n.md) — locale resolution and dictionary loading
+- [Pitfalls: SSR hydration mismatch](./pitfalls/ssr-hydration-mismatch.md) — when the two sides disagree