@finesoft/front 0.5.0 → 0.5.2

package/docs/03-middleware.md

@@ -1,220 +1,18 @@
-# 3. Middleware
+# Guarded page loading
 
-Middleware runs in two phases around the controller. A guard inspects the navigation, then returns one of four results to control what happens next.
+URL, SSR and structured navigation use the same guarded page loader. Global, route and navigation guards run before and after page execution; every Split destination is checked.
 
-## 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
+## Guard / 守卫
 
 ```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();
-}
+import { next, redirect, type BeforeLoadGuard } from "@finesoft/front";
+export const signedIn: BeforeLoadGuard = (context) =>
+    context.getCookie("session")
+        ? next()
+        : redirect("/login?next=" + encodeURIComponent(context.url));
+// app.beforeLoad: [signedIn], or home.route("/account", { beforeLoad: [signedIn] })
 ```
 
-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.
-
-## Try it
-
-Build a `beforeLoad` chain of three guards, pick the result each one returns, then run it through the **real** `runBeforeLoadGuards()` from `@finesoft/core`. The pipeline below shows where the chain short-circuits and what the final `MiddlewareResult` looks like.
+Guards return `next()`, `deny(status, message)`, `redirect(url, status)` or `rewrite(url)`. First non-next result stops that chain. A browser redirect continues through host admission; SSR emits an HTTP redirect. Operation policies are a separate portable layer: protect data operations there too, instead of relying only on page guards. A warm HTML cache must not bypass the current request’s checks.
 
 <Ch03MiddlewarePlayground />
-
-## 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

@@ -1,338 +1,11 @@
-# 4. Rendering & hydration
+# Rendering and 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, the second axis they compose with — **app architecture** (flat single page vs structured navigation + islands) — and the `PrefetchedIntents` machinery that ties them together.
+SSR, CSR and prerender determine when HTML is produced. All modes use the same page session and one native application root, with layout around Outlet. There are no root/entries renderer modes or separate chrome roots.
 
-## The three modes side by side
+In the browser, call `createBrowserApp({ definition, target })`, mount or hydrate the same App using native APIs, then await `app.ready`. On the server use `createSSRRender({ definition, render: app => nativeRender(app) })`. See [getting started](./01-getting-started.md) for React and the templates for Vue/Svelte.
 
-|                             | 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                             |
+Outlet subscribes to stable `AppSnapshot` values. EntryId keeps its wrapper stable; EntryId plus pageType determines the child component identity. Hidden entries remain in the same native tree with their drafts and context. A pageType change recreates the child. Native commit hooks acknowledge only the revision actually rendered; the browser then restores its scroll and DOM state.
 
-Mode is **per-route**. Mix freely.
+SSR materializes public projections while request resources are alive and performs one native render. Hydration explicitly carries `{ tree, pages }`, with page results associated with entries. Protocol/build mismatches trigger fresh loading; persisted sessions have their own version. Denied data does not enter the wire.
 
-## Two axes: render mode × app architecture
-
-Render mode is one axis. The **app architecture** is a second, orthogonal axis:
-
-- **Flat single page** — `createSSRRender` on the server, a single client mount that re-renders on each navigation. One root, one visible page. (See [SSR pipeline](#ssr-pipeline) below.)
-- **Structured navigation + islands** — `createSSRNavigationRender` on the server, per-destination _islands_ on the client: independent roots that stay alive across tab/stack switches. (See [Navigation](./11-navigation.md) and [Islands SSR](#islands-ssr-structured-architecture-approach-c) below.)
-
-The two axes compose into a matrix — render mode decides _when/where_ HTML is produced; architecture decides _how_ the app is structured:
-
-|               | Flat single page          | Structured nav + islands (approach C) |
-| ------------- | ------------------------- | ------------------------------------- |
-| **ssr**       | ✅ `svelte-minimal`       | ✅ `vue-minimal`, `react-minimal`     |
-| **csr**       | ◐ shell → one client root | ◐ shell → islands mount client-side   |
-| **prerender** | ◐ cached flat SSR         | ◐ cached approach-C SSR               |
-
-✅ demonstrated by a starter template · ◐ composes by design, no starter template yet.
-
-**Islands are SSR'd or CSR'd as a consequence of the mode, not as a separate choice:** under `ssr`/`prerender` the framework server-renders each visible island and the client _adopts and hydrates_ it; under `csr` there is no server HTML, so every island mounts fresh on the client. The per-mode sub-dimensions still apply on top — CSR has two triggers ([below](#csr-client-side-render)), prerender has build-time-static and runtime-ISR forms ([below](#prerender-static--isr)). Session restoration + DOM restore are a further orthogonal layer (client-side, post-hydration) that stacks onto any cell — see [Session restoration](./12-session-restoration.md).
-
-## 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
-
-## Islands SSR (structured architecture, "approach C")
-
-The structured architecture renders the **chrome** (tab bar, headers — the persistent frame) and the **island content** (the active page) as **independent hydration roots**, placed as siblings under the mount node:
-
-```html
-<div id="app">
-    <div data-fs-chrome><!-- chrome SSR'd here --></div>
-    <main data-fs-outlet><!-- each visible island SSR'd here --></main>
-</div>
-```
-
-**Server** — `renderApp` renders the chrome; `renderIslandsHtml(snapshot, renderEntry)` renders each visible destination into the outlet with shared markers (`data-fs-entry` / `data-fs-intent` / `data-fs-key`) so the client can match them:
-
-```ts
-// src/ssr.ts — structured entry (createSSRNavigationRender)
-async renderApp(page, _framework, snapshot) {
-    const chromeHtml = await renderToString(createSSRApp(App, { snapshot }));
-    const islandsHtml = await renderIslandsHtml(snapshot, (entry) =>
-        renderToString(createSSRApp(VIEWS[entry.intent], { page: entry.page })),
-    );
-    return {
-        html: `<div data-fs-chrome>${chromeHtml}</div><main data-fs-outlet>${islandsHtml}</main>`,
-        head: `<title>${page.title}</title>`,
-        css: "",
-    };
-}
-```
-
-**Client** — `resolveIslandsShell(target)` locates (or creates) the chrome/outlet siblings and reports whether the chrome was server-rendered (`hydrate`). The island orchestrator adopts each SSR'd container by `data-fs-key` and calls your `mountEntry(entry, container)` with `entry.hydrate = true`, so you hydrate the existing DOM rather than create new:
-
-```ts
-// src/main.ts
-const mountEntry = (entry, container) => {
-    const factory = entry.hydrate ? createSSRApp : createApp; // hydrate SSR'd vs mount fresh (client nav)
-    const app = factory(VIEWS[entry.intent], { page: entry.page, controller: ctx.app });
-    app.mount(container);
-    return { unmount: () => app.unmount() };
-};
-
-startBrowserApp({
-    bootstrap,
-    mount,
-    callbacks,
-    navigation: { ...navigation.toBrowserConfig(), mountEntry },
-});
-```
-
-> **Synchronous-mount contract.** After `mountEntry` returns, the island's DOM must already exist: the framework restores `data-restore-root` fields on the next animation frame (see [Session restoration](./12-session-restoration.md)). Vue/Svelte `.mount()` satisfies this synchronously. **React** commits asynchronously, so wrap the **client-mount** path in `flushSync(() => root.render(view))` — only client-mounted islands need it (SSR'd islands already have their DOM from the server). See `templates/react-minimal/src/main.tsx`.
-
-Complete examples: `templates/vue-minimal` and `templates/react-minimal` (both `ssr` + structured navigation + islands + session restoration).
-
-## 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`) also cache `prerender` routes at runtime: a route is rendered on its **first** request and the HTML kept in an in-memory LRU (`ISR_CACHE_MAX = 1000` entries, evicted least-recently-used). Subsequent requests serve the cached HTML without re-running the controller.
-
-Mark routes `prerender` per route (`renderMode: "prerender"`) or per glob via the Vite plugin (config-level wins over route-level):
-
-```ts
-finesoftFrontViteConfig({
-    ssr: { entry: "src/ssr.ts" },
-    renderModes: { "/blog/*": "prerender" },
-});
-```
-
-The runtime cache has **no TTL and no background regeneration** — entries live until LRU-evicted or the process restarts. Time-based stale-while-revalidate is delegated to the CDN by the platform adapters (Netlify emits a real `stale-while-revalidate` header; Cloudflare a plain `max-age`; node/Vercel none). See [server & deployment](./09-server-and-deployment.md#isr-incremental-static-regeneration) for the full picture.
-
-## `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
+CSR returns an HTML shell. Prerender produces static HTML. Runtime public HTML reuse still executes current guards and rendering, so it is not a render-skipping guarantee. During cleanup, await session disposal before unmounting the application's native root.