@finesoft/front 0.1.76 → 0.1.78

package/docs/01-getting-started.md

@@ -0,0 +1,230 @@
+# 1. Getting started
+
+A working `@finesoft/front` app in five minutes. By the end you have a Vue/React/Svelte page rendering on the server, hydrating in the browser, and ready to deploy.
+
+## Prerequisites
+
+- Node.js `>= 22.12.0`
+- A package manager: pnpm (recommended), npm, or yarn
+- A view layer (Vue 3, React 19, or Svelte 5) — these docs use Vue, but every example translates one-to-one
+
+## Scaffold a new app
+
+```bash
+npx @finesoft/create-app my-app
+cd my-app
+pnpm install
+pnpm dev
+```
+
+The scaffolder generates a runnable app with routing, SSR, and proxy already wired. Open <http://localhost:5173>.
+
+If you want to understand what was generated, the rest of this page builds the same setup from scratch.
+
+## Add to an existing project
+
+```bash
+pnpm add @finesoft/front
+pnpm add -D vite hono
+```
+
+Peer dependencies: `hono >= 4.0.0`. Optional but recommended: `@hono/node-server` for Node deployment, `vite >= 5.0.0` for the dev server.
+
+## Minimal project layout
+
+```
+my-app/
+├── src/
+│   ├── bootstrap.ts       # routes + controllers (shared SSR + CSR)
+│   ├── main.ts            # browser entry
+│   ├── ssr.ts             # SSR entry
+│   ├── App.vue            # root component
+│   └── lib/
+│       └── controllers/
+│           └── home.ts
+├── index.html
+├── vite.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+## Vite config
+
+```ts
+// vite.config.ts
+import { finesoftFrontViteConfig } from "@finesoft/front";
+import vue from "@vitejs/plugin-vue";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+    plugins: [
+        vue(),
+        finesoftFrontViteConfig({
+            ssr: { entry: "src/ssr.ts" },
+            i18n: { messagesDir: "src/locales" },
+            adapter: "auto",
+        }),
+    ],
+});
+```
+
+What `finesoftFrontViteConfig` adds:
+
+- A Hono-based dev server that runs your SSR entry on every request
+- Locale JSON auto-loading from `messagesDir`
+- A build pipeline that emits both the client bundle and a server entry
+- Platform adapter wiring for `adapter: "auto" | "node" | "vercel" | "cloudflare" | "netlify" | "static"`
+
+## Bootstrap (shared by SSR and CSR)
+
+```ts
+// src/bootstrap.ts
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { HomeController } from "./lib/controllers/home";
+
+export function bootstrap(framework: Framework): void {
+    defineRoutes(framework, [{ path: "/", intentId: "home", controller: new HomeController() }]);
+}
+```
+
+The same `bootstrap()` runs on both sides. This is what guarantees the server and browser resolve URLs identically.
+
+## Controller
+
+```ts
+// src/lib/controllers/home.ts
+import { BaseController, type Container } from "@finesoft/front";
+
+interface HomePage {
+    kind: "home";
+    title: string;
+    items: string[];
+}
+
+export class HomeController extends BaseController<Record<string, string>, HomePage> {
+    readonly intentId = "home";
+
+    async execute(_params: Record<string, string>, _container: Container): Promise<HomePage> {
+        return {
+            kind: "home",
+            title: "Welcome",
+            items: ["one", "two", "three"],
+        };
+    }
+
+    fallback(_params: Record<string, string>, error: unknown): HomePage {
+        return { kind: "home", title: "Failed", items: [] };
+    }
+}
+```
+
+`BaseController` wraps `execute()` in `try/catch` and calls `fallback()` on error. Always provide a `fallback` — see [error handling](./08-observability.md#error-handling-via-fallback) for why.
+
+## 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: "Error" }),
+    async renderApp(page) {
+        const html = await renderToString(createSSRApp(App, { page }));
+        return { html, head: `<title>${(page as { title: string }).title}</title>`, css: "" };
+    },
+});
+
+export { serializeServerData };
+```
+
+`createSSRRender` returns a function that takes a URL and returns rendered HTML + serialized prefetched intent data. The Vite plugin and adapters call it for you — you do not invoke it directly.
+
+## Browser entry
+
+```ts
+// src/main.ts
+import { startBrowserApp } from "@finesoft/front/browser";
+import { createSSRApp } from "vue";
+import App from "./App.vue";
+import { bootstrap } from "./bootstrap";
+
+startBrowserApp({
+    bootstrap,
+    mount(target, { framework }) {
+        const app = createSSRApp(App, { framework });
+        app.mount(target);
+    },
+});
+```
+
+`startBrowserApp` reads the SSR-injected `PrefetchedIntents` from the DOM, creates the `Framework`, runs the same `bootstrap()` as the server, and triggers the first page. By the time `mount()` runs the framework already has the initial `Page` ready.
+
+Import from `@finesoft/front/browser` (not `@finesoft/front`) on the client to avoid pulling server-only modules into your client bundle.
+
+## Root component (Vue example)
+
+```vue
+<!-- src/App.vue -->
+<script setup lang="ts">
+import { computed } from "vue";
+import type { Framework } from "@finesoft/front";
+
+const props = defineProps<{ framework?: Framework; page?: { title: string; items: string[] } }>();
+
+// SSR receives `page` directly; CSR pulls the current page from the framework.
+const page = computed(() => props.page ?? props.framework?.getCurrentPage());
+</script>
+
+<template>
+    <main>
+        <h1>{{ page?.title }}</h1>
+        <ul>
+            <li v-for="item in page?.items" :key="item">{{ item }}</li>
+        </ul>
+    </main>
+</template>
+```
+
+## index.html
+
+```html
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <!--head-->
+    </head>
+    <body>
+        <div id="app"><!--ssr--></div>
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>
+```
+
+The `<!--head-->` and `<!--ssr-->` placeholders are where the framework injects the SSR head fragment and rendered HTML. The placeholder names are exported as `SSR_PLACEHOLDERS` if you need them.
+
+## Run it
+
+```bash
+pnpm dev          # development with HMR
+pnpm build        # production build
+pnpm preview      # serve the production build locally
+```
+
+Done. You have an app that:
+
+- Renders on the server with prefetched data
+- Hydrates without an extra fetch (SSR data is reused via `PrefetchedIntents`)
+- Routes client-side without page reloads
+- Is ready to deploy to any of the supported adapters
+
+## Next
+
+- [Routing & controllers](./02-routing-and-controllers.md) — define more routes and control how they render
+- [Project structure](./engineering/project-structure.md) — recommended layout once the app grows past a handful of pages

package/docs/02-routing-and-controllers.md

@@ -0,0 +1,203 @@
+# 2. Routing & controllers
+
+The framework's routing layer maps URLs to **intents**, intents to **controllers**, and controllers produce **pages**. This chapter covers all three.
+
+## The mental model
+
+```
+URL  ──Router.resolve()──▶  RouteMatch { intent, renderMode, guards }
+                                │
+                                ▼
+                       IntentDispatcher.dispatch(intent)
+                                │
+                                ▼
+                         Controller.execute()  →  Page
+```
+
+A route definition combines:
+
+- A **path pattern** (`/products/:id`)
+- An **intent id** (logical name for the operation; one intent can have multiple routes)
+- A **controller instance** (where the page data is produced)
+- An optional **render mode** (`ssr` / `csr` / `prerender`)
+- Optional **guards** (`beforeLoad` / `afterLoad`)
+
+## Defining routes
+
+```ts
+// src/bootstrap.ts
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { HomeController } from "./lib/controllers/home";
+import { ProductController } from "./lib/controllers/product";
+import { authGuard } from "./lib/guards/auth";
+
+export function bootstrap(framework: Framework): void {
+    defineRoutes(framework, [
+        // Plain SSR route
+        { path: "/", intentId: "home", controller: new HomeController() },
+
+        // Dynamic segment
+        { path: "/products/:id", intentId: "product", controller: new ProductController() },
+
+        // CSR-only (server returns an empty shell)
+        {
+            path: "/dashboard",
+            intentId: "dashboard",
+            controller: new DashboardController(),
+            renderMode: "csr",
+        },
+
+        // Statically prerendered at build time
+        {
+            path: "/about",
+            intentId: "about",
+            controller: new AboutController(),
+            renderMode: "prerender",
+        },
+
+        // Protected route — reuses the home intent but gates with a guard
+        {
+            path: "/admin",
+            intentId: "home",
+            controller: new HomeController(),
+            beforeLoad: [authGuard],
+        },
+    ]);
+}
+```
+
+### Route options
+
+| Field        | Type                             | Notes                                                                |
+| ------------ | -------------------------------- | -------------------------------------------------------------------- |
+| `path`       | `string`                         | Path pattern with `:param` placeholders. Trailing `/` is normalized. |
+| `intentId`   | `string`                         | Logical operation name. Used to register the controller.             |
+| `controller` | `BaseController<TParams, TPage>` | Optional if the intent is already registered.                        |
+| `renderMode` | `"ssr" \| "csr" \| "prerender"`  | Default `"ssr"`. See [chapter 4](./04-rendering-and-hydration.md).   |
+| `beforeLoad` | `BeforeLoadGuard[]`              | Run before the controller. See [chapter 3](./03-middleware.md).      |
+| `afterLoad`  | `AfterLoadGuard[]`               | Run after the page is produced.                                      |
+
+### Path patterns
+
+- Static: `/about`
+- Parameterized: `/products/:id`, `/users/:userId/posts/:postId`
+- Trailing wildcard: `/files/*`
+- Optional segment is **not** supported — write two routes instead.
+
+Parameters are passed to `controller.execute(params, container)` as a string-keyed object.
+
+## Writing a controller
+
+```ts
+// src/lib/controllers/product.ts
+import { BaseController, type Container, type HttpClient } from "@finesoft/front";
+
+interface ProductPage {
+    kind: "product";
+    id: string;
+    name: string;
+    price: number;
+}
+
+export class ProductController extends BaseController<{ id: string }, ProductPage> {
+    readonly intentId = "product";
+
+    async execute(params: { id: string }, container: Container): Promise<ProductPage> {
+        const http = container.resolve<HttpClient>("http");
+        const product = await http.get<{ name: string; price: number }>(
+            `/api/products/${params.id}`,
+        );
+        return {
+            kind: "product",
+            id: params.id,
+            name: product.name,
+            price: product.price,
+        };
+    }
+
+    fallback(params: { id: string }, _error: unknown): ProductPage {
+        return { kind: "product", id: params.id, name: "Not available", price: 0 };
+    }
+}
+```
+
+### Controller contract
+
+| Member     | Required | Purpose                                                                            |
+| ---------- | -------- | ---------------------------------------------------------------------------------- |
+| `intentId` | yes      | Must match the route's `intentId` (or the `IntentDispatcher.register` call).       |
+| `execute`  | yes      | Produce the page. Receives parsed path params and the request-scoped DI container. |
+| `fallback` | yes      | Return a degraded page when `execute()` throws. Must be synchronous and total.     |
+
+`BaseController` wraps `execute()` in `try/catch` and routes any error through `fallback()`. The framework never throws out of `dispatch()` — your `fallback()` is the last line of defense.
+
+### Why `fallback` is mandatory
+
+A thrown error in `execute()` during SSR would otherwise crash the request and either 500 or render a blank document. `fallback()` lets you return a structured "error" `Page` that your view layer renders as a graceful failure (banner, retry button, etc.). See the [error handling section in observability](./08-observability.md#error-handling-via-fallback) for patterns.
+
+## Render modes
+
+| Mode          | Server returns                               | When to use                                              |
+| ------------- | -------------------------------------------- | -------------------------------------------------------- |
+| `"ssr"`       | Fully rendered HTML + serialized data        | Default. Best for SEO and TTFB-sensitive pages.          |
+| `"csr"`       | Empty shell HTML; controller runs in browser | Authenticated dashboards, heavy-personalization pages.   |
+| `"prerender"` | Static HTML built at deploy time             | Marketing, docs, blog. Combine with ISR (see chapter 4). |
+
+The mode is **per-route**, so you can mix freely. The framework rebuilds prerendered routes at build time; SSR routes execute on every request.
+
+## Registering controllers without routes
+
+You can register a controller for an intent without exposing it as a route. This is useful for intents triggered only by `dispatchAction`:
+
+```ts
+framework.intentDispatcher.register("checkout", new CheckoutController());
+
+// Elsewhere:
+const page = await framework.intentDispatcher.dispatch({
+    intentId: "checkout",
+    params: { cartId },
+});
+```
+
+Routes are simply intent dispatches keyed by URL.
+
+## One intent, many routes
+
+Same intent can serve different URLs:
+
+```ts
+defineRoutes(framework, [
+    { path: "/", intentId: "home", controller: new HomeController() },
+    { path: "/welcome", intentId: "home" }, // reuses the registered HomeController
+    { path: "/landing/:slug", intentId: "home" }, // same intent, params differ
+]);
+```
+
+This avoids duplicating controller instances when only the URL surface differs. Authenticated `/admin` reusing the `home` intent in the earlier example is the same pattern.
+
+## Inspecting the resolved match
+
+For diagnostics or custom routing, call `Router.resolve()` directly:
+
+```ts
+const match = framework.router.resolve("/products/42");
+// {
+//   intent: { intentId: "product", params: { id: "42" } },
+//   action: { kind: "flow", url: "/products/42" },
+//   renderMode: "ssr",
+//   guards: { before: [...], after: [...] },
+// }
+```
+
+`router.resolve()` returns `null` for unmatched URLs — handle this in your server-side 404 logic.
+
+## Try it
+
+A live `Router` instance is registered with the sample routes below. Type a URL on the left and watch `Router.resolve()` produce a `RouteMatch` on the right — the same code path the framework uses at runtime.
+
+<Ch02RouteResolver />
+
+## Next
+
+- [Middleware](./03-middleware.md) — gating navigation, redirects, denies
+- [Rendering & hydration](./04-rendering-and-hydration.md) — what happens after the controller produces a page

package/docs/03-middleware.md

@@ -0,0 +1,220 @@
+# 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.
+
+## 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.
+
+<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