@finesoft/front 0.1.76 → 0.1.78

package/docs/10-features-platform-pwa.md

@@ -0,0 +1,238 @@
+# 10. Features, platform, PWA
+
+Three small, independent runtime helpers:
+
+- **Feature flags** — config that can change without redeploy
+- **Platform detection** — user-agent parsing for OS / browser / engine
+- **PWA mode** — detect whether the app is installed (standalone)
+
+Each is replaceable, each composable with custom providers.
+
+## Feature flags
+
+```ts
+const framework = Framework.create({
+    featureFlags: {
+        darkMode: true,
+        maxRetries: 3,
+        experimentalCheckout: false,
+    },
+});
+
+const flags = framework.container.resolve(DEP_KEYS.FEATURE_FLAGS);
+flags.get("darkMode"); // true
+flags.get("maxRetries"); // 3
+flags.get("missing"); // undefined
+flags.get("missing", "fallback"); // "fallback"
+```
+
+Flags can be any JSON-serializable value: booleans, strings, numbers, arrays, objects.
+
+### Static config
+
+The simplest case — flags shipped with the bundle:
+
+```ts
+Framework.create({
+    featureFlags: {
+        darkMode: process.env.NODE_ENV !== "production",
+        analytics: true,
+        cdnUrl: "https://cdn.example.com",
+    },
+});
+```
+
+Use this for flags driven by environment, not user attributes.
+
+### Remote providers
+
+Plug in a provider that fetches from a remote service (LaunchDarkly, GrowthBook, Unleash, your own config service):
+
+```ts
+import { type FeatureFlagsProvider } from "@finesoft/front";
+
+const remoteConfigProvider: FeatureFlagsProvider = {
+    async load() {
+        const resp = await fetch("https://config.example.com/flags");
+        return resp.json(); // { ...flags }
+    },
+};
+
+const framework = Framework.create({
+    featureFlags: {
+        darkMode: false,
+        maxRetries: 3,
+    },
+    featureFlagsProviders: [remoteConfigProvider],
+});
+```
+
+Providers run in registration order. Later providers override earlier values for the same key — "last registered wins."
+
+### Cache lifecycle
+
+The framework loads provider values once during `Framework.create()`. After that, flags are read synchronously from memory.
+
+To refresh, call `flags.refresh()`:
+
+```ts
+const flags = framework.container.resolve(DEP_KEYS.FEATURE_FLAGS);
+await flags.refresh(); // re-runs all providers
+```
+
+You'd typically call this on a timer or in response to a server-sent event.
+
+### Targeting
+
+Built-in flags are global (same value for every user). For per-user targeting, structure your provider to return a function or use a separate evaluation step:
+
+```ts
+class TargetingProvider implements FeatureFlagsProvider {
+    constructor(private userId: string) {}
+    async load() {
+        const resp = await fetch(`https://config.example.com/flags?userId=${this.userId}`);
+        return resp.json();
+    }
+}
+
+// Register per-request in a beforeLoad guard:
+async function flagsGuard(ctx) {
+    const userId = await getUserIdFromCookie(ctx);
+    const targeting = new TargetingProvider(userId);
+    const flags = await targeting.load();
+    ctx.container.register(DEP_KEYS.FEATURE_FLAGS, () => ({
+        get: (key, fallback) => flags[key] ?? fallback,
+    }));
+    return next();
+}
+```
+
+For complex bucketing, hand the user id to a dedicated service (GrowthBook SDK, etc.) and store its evaluator in DI.
+
+### SSR / CSR consistency
+
+Flags evaluated on the server and not re-evaluated on the browser would cause hydration mismatch. The framework serializes flag values into `PrefetchedIntents` if a controller reads them. Browser-side reads return the same value the server saw.
+
+For flags that _should_ differ (e.g., A/B variants), evaluate them in a `beforeLoad` guard and store the result in the request scope — both server and browser will use the value resolved by the server.
+
+## Platform detection
+
+```ts
+import { detectPlatform } from "@finesoft/front";
+
+const info = detectPlatform();
+// {
+//   os: "ios" | "android" | "macos" | "windows" | "linux" | "other",
+//   browser: "safari" | "chrome" | "firefox" | "edge" | ...,
+//   engine: "webkit" | "blink" | "gecko" | "other",
+//   isMobile: boolean,
+//   isTouch: boolean,
+//   isServer: boolean,
+// }
+```
+
+In the browser, `detectPlatform()` reads `navigator.userAgent`. On the server, parsing the request's `User-Agent` header is automatic via the framework:
+
+```ts
+const platform = framework.getPlatform();
+```
+
+For controllers and guards, resolve from DI:
+
+```ts
+const platform = ctx.container.resolve(DEP_KEYS.PLATFORM);
+if (platform.isMobile) {
+    return rewrite("/m" + ctx.url.pathname);
+}
+```
+
+### Reliability
+
+User-Agent strings lie — every modern browser embeds substrings of every other browser for compatibility. The framework's detection prioritizes well-known patterns and falls back to `"other"` on ambiguity. Don't make critical decisions on `browser` alone:
+
+- ✅ Adjust layout for `isMobile`
+- ✅ Hide Safari-only features for non-WebKit
+- ❌ Lock specific browsers out
+- ❌ Choose code paths based on browser version
+
+## PWA detection
+
+```ts
+import { getPWADisplayMode } from "@finesoft/front";
+
+const mode = getPWADisplayMode();
+// "standalone" | "twa" | "browser"
+```
+
+- `"standalone"` — running as an installed PWA (Safari add-to-home, Chrome install)
+- `"twa"` — Trusted Web Activity (Android, wrapped as a native app)
+- `"browser"` — regular browser tab
+
+The function reads `window.matchMedia("(display-mode: standalone)")` and Android's TWA referrer. Server-side: returns `"browser"`.
+
+### Common uses
+
+```ts
+const mode = getPWADisplayMode();
+
+if (mode === "browser") {
+    showInstallBanner();
+}
+
+if (mode === "standalone") {
+    // Customize navigation — installed app shouldn't show "Install" prompt
+    hideInstallButton();
+    enableNativeBackButtonHandling();
+}
+```
+
+### Service worker registration
+
+PWA install is independent of service workers — you can have one without the other. To register a service worker:
+
+```ts
+// src/main.ts
+startBrowserApp({
+    bootstrap,
+    mount,
+    onAfterStart() {
+        if ("serviceWorker" in navigator) {
+            navigator.serviceWorker.register("/sw.js");
+        }
+    },
+});
+```
+
+The framework does not ship a service worker generator. Use [Vite PWA](https://vite-pwa-org.netlify.app/) or hand-roll one.
+
+## Composing them
+
+A common navigation guard combining all three:
+
+```ts
+import { next, rewrite, DEP_KEYS } from "@finesoft/front";
+
+function mobilePwaGuard(ctx) {
+    const platform = ctx.container.resolve(DEP_KEYS.PLATFORM);
+    const flags = ctx.container.resolve(DEP_KEYS.FEATURE_FLAGS);
+
+    if (flags.get("mobilePwaRedesign") && platform.isMobile && !ctx.isSsr) {
+        if (getPWADisplayMode() === "standalone") {
+            return rewrite(`/pwa${ctx.url.pathname}`);
+        }
+    }
+    return next();
+}
+```
+
+This routes installed mobile PWA users to a different page tree without affecting other users.
+
+## Caveats
+
+- **Feature flags resolved server-side ship in HTML.** Don't store secrets in flags.
+- **Platform detection on the server uses request headers.** A bot or curl might not send a useful User-Agent — handle `"other"` gracefully.
+- **PWA detection on the server always returns `"browser"`.** Don't rely on it in SSR rendering paths; conditional UI based on PWA mode should be client-only or use `<noscript>` fallbacks.
+
+## Next
+
+- [Engineering: project structure](./engineering/project-structure.md) — where to put flag config, platform-aware code

package/docs/README.md

@@ -0,0 +1,72 @@
+# `@finesoft/front` documentation
+
+> **Language:** English (this page) · **[简体中文](./zh/README.md)**
+
+Full-stack TypeScript framework — router, DI, actions, SSR, and server — in one package. Works with **Vue**, **React**, or **Svelte**. Deploys to Node.js, Vercel, Cloudflare Workers, Netlify, or static hosting.
+
+## Three entry points
+
+Pick where to start based on what you need.
+
+### New to the framework — read top to bottom
+
+A linear path. Each chapter assumes the previous one. By the end you can build, render, and deploy a real app.
+
+1. [Getting started](./01-getting-started.md) — install, Vite config, first page
+2. [Routing & controllers](./02-routing-and-controllers.md) — route definitions, intents, controllers, render modes
+3. [Middleware](./03-middleware.md) — `beforeLoad` / `afterLoad`, redirect / rewrite / deny
+4. [Rendering & hydration](./04-rendering-and-hydration.md) — SSR / CSR / Prerender, `PrefetchedIntents`
+5. [Internationalization](./05-i18n.md) — `locale`, `Translator`, dictionary loading, RTL
+6. [HTTP client](./06-http-client.md) — `HttpClient` subclassing, interceptors, `HttpError`
+7. [DI container](./07-di-container.md) — registration, scopes, `DEP_KEYS`, dispose
+8. [Observability](./08-observability.md) — `Logger`, `EventRecorder`, impression tracking, `ReportCallback`
+9. [Server & deployment](./09-server-and-deployment.md) — `createServer`, proxy, adapters, Vite plugin
+10. [Features, platform, PWA](./10-features-platform-pwa.md) — feature flags, platform detection, PWA mode
+
+### Engineer working on an existing app — jump to practice
+
+Cross-cutting concerns and conventions. Read after you understand the basics.
+
+- [Project structure](./engineering/project-structure.md) — recommended layout, `bootstrap.ts` splitting, single source of truth
+- [Testing](./engineering/testing.md) — controllers, middleware, scoped DI, mocking the framework
+- [CI & release flow](./engineering/ci-release-flow.md) — changesets, the bundled release workflow, version reconciliation
+
+### Hit a problem — go to pitfalls
+
+Each entry is **symptom → root cause → fix**, kept short.
+
+- [SSR hydration mismatch](./pitfalls/ssr-hydration-mismatch.md)
+- [SSR vs CSR globals](./pitfalls/ssr-vs-csr-globals.md)
+- [Redirect vs rewrite](./pitfalls/redirect-vs-rewrite.md)
+- [Proxy binary payloads](./pitfalls/proxy-binary-payloads.md)
+- [Container scope leak](./pitfalls/container-scope-leak.md)
+- [i18n bundle size](./pitfalls/i18n-bundle-size.md)
+
+### Extending the framework — advanced recipes
+
+Each recipe is a complete, runnable extension example with explanation.
+
+- [Custom action handler](./advanced/custom-action-handler.md) — beyond `FlowAction` / `ExternalUrlAction`
+- [Custom event recorder](./advanced/custom-event-recorder.md) — wire Sentry / Datadog / your own pipeline
+- [Custom adapter](./advanced/custom-adapter.md) — target a new platform
+- [Inline proxy codegen](./advanced/inline-proxy-codegen.md) — generate self-contained proxy routes for serverless / edge
+- [Multi-tenant scopes](./advanced/multi-tenant-scopes.md) — per-tenant DI containers
+
+## At-a-glance
+
+```
+URL/Action → Router.resolve()
+          → beforeLoad chain   (NavigationContext: redirect/rewrite/deny/next)
+          → IntentDispatcher   (controller.execute() → Page; fallback() on error)
+          → afterLoad chain    (PostLoadContext)
+          → render             (SSR: HTML + serialized PrefetchedIntents; CSR: shell)
+```
+
+The same `bootstrap()` runs on the server and in the browser. SSR serializes prefetched intent results into HTML; the browser deserializes them into `PrefetchedIntents` so the first client navigation reuses server results without a refetch.
+
+## Conventions used in these docs
+
+- **Code blocks** are runnable as written unless a comment says otherwise.
+- **File paths** are relative to the project root (the directory containing `vite.config.ts`).
+- **`vp`** is the [Vite+](https://github.com/voidzero-dev/setup-vp) CLI. Use it instead of calling `pnpm` / `npm` / `vitest` / `tsdown` directly.
+- **`@finesoft/front`** is the only import surface for application code. Internal packages (`core`, `browser`, `ssr`, `server`) are bundled in and not published.

package/docs/advanced/custom-action-handler.md

@@ -0,0 +1,248 @@
+# Advanced: custom action handler
+
+The framework ships three action kinds: `flow` (in-app navigation), `external-url` (full browser navigation), and `compound` (a tuple of actions executed in order). For most apps these are enough.
+
+This recipe shows how to add your own — useful when you have a class of operations that need cross-cutting handling (analytics, confirmations, telemetry) without polluting every callsite.
+
+## Use case: confirmation-gated action
+
+We'll add a `"confirm"` action kind: dispatch it with `{ kind: "confirm", message, then }`, and the framework shows a confirmation dialog before dispatching `then` (which is itself an action).
+
+```ts
+dispatch({
+    kind: "confirm",
+    message: "Delete this item permanently?",
+    then: { kind: "flow", url: "/items/42/deleted" },
+});
+```
+
+The user clicks Cancel → no navigation. Clicks OK → the inner flow action fires.
+
+## Step 1: define the action type
+
+```ts
+// src/lib/actions/confirm.ts
+import { type Action } from "@finesoft/front";
+
+export interface ConfirmAction {
+    kind: "confirm";
+    message: string;
+    then: Action;
+}
+
+export function makeConfirmAction(message: string, then: Action): ConfirmAction {
+    return { kind: "confirm", message, then };
+}
+
+export function isConfirmAction(action: Action): action is ConfirmAction {
+    return (action as any).kind === "confirm";
+}
+```
+
+The shape is yours — `kind` just has to be unique among registered handlers.
+
+## Step 2: extend the `Action` type union
+
+TypeScript doesn't auto-expand the framework's `Action` type. Declare a module augmentation:
+
+```ts
+// src/lib/actions/confirm.ts
+declare module "@finesoft/front" {
+    interface ActionRegistry {
+        confirm: ConfirmAction;
+    }
+}
+```
+
+If the framework exposes `ActionRegistry` (most pluggable frameworks do), this lets TypeScript know about your new kind. If it doesn't, cast at registration time:
+
+```ts
+framework.actionDispatcher.register("confirm" as any, handleConfirm as any);
+```
+
+The runtime doesn't care — `kind` is a plain string at dispatch time.
+
+## Step 3: write the handler
+
+```ts
+// src/lib/actions/confirm.ts
+import type { Framework } from "@finesoft/front";
+
+export function registerConfirmHandler(framework: Framework): void {
+    framework.actionDispatcher.register("confirm", async (action: ConfirmAction) => {
+        if (typeof window === "undefined") {
+            // SSR: confirmation isn't possible — fall through to the inner action
+            await framework.actionDispatcher.dispatch(action.then);
+            return;
+        }
+
+        const confirmed = window.confirm(action.message);
+        if (!confirmed) return;
+
+        await framework.actionDispatcher.dispatch(action.then);
+    });
+}
+```
+
+Key points:
+
+- The handler runs on both server and client. On the server `window` doesn't exist — decide what "no UI" means for your action.
+- Recursive dispatch (`actionDispatcher.dispatch(action.then)`) goes through the regular pipeline, including any other custom handlers.
+- The framework already protects compound actions with a recursion-depth limit (default 4). Your handler is reached via dispatch, so it inherits that limit.
+
+## Step 4: register at app startup
+
+```ts
+// src/main.ts
+import { startBrowserApp } from "@finesoft/front/browser";
+import { bootstrap } from "./bootstrap";
+import { registerConfirmHandler } from "./lib/actions/confirm";
+
+startBrowserApp({
+    bootstrap,
+    onBeforeStart(framework) {
+        registerConfirmHandler(framework);
+    },
+    mount: /* ... */,
+});
+```
+
+Mirror on the SSR side:
+
+```ts
+// src/ssr.ts
+export const render = createSSRRender({
+    bootstrap,
+    onBeforeStart(framework) {
+        registerConfirmHandler(framework);
+    },
+    async renderApp(page) {
+        /* ... */
+    },
+});
+```
+
+Or, simpler: register inside `bootstrap()` so both sides get it automatically.
+
+## Step 5: use it
+
+```ts
+// In a view component
+import { makeConfirmAction, makeFlowAction } from "@finesoft/front";
+
+function onDelete(id: string) {
+    framework.actionDispatcher.dispatch(
+        makeConfirmAction(`Delete item ${id}?`, makeFlowAction(`/items/${id}/deleted`)),
+    );
+}
+```
+
+## Replacing an existing handler
+
+Each `kind` can be registered exactly once. The dispatcher warns on duplicate registrations and skips:
+
+```ts
+framework.actionDispatcher.register("flow", myFlowHandler);
+// [ActionDispatcher] kind="flow" already registered, skipping
+```
+
+To replace, unregister first:
+
+```ts
+framework.actionDispatcher.removeAction("flow");
+framework.actionDispatcher.register("flow", myFlowHandler);
+```
+
+Useful when you want to wrap the default flow handler with logging or analytics:
+
+```ts
+import { registerFlowActionHandler, type FlowActionDependencies } from "@finesoft/front";
+
+const baseHandler = framework.actionDispatcher.getHandler("flow"); // hypothetical
+framework.actionDispatcher.removeAction("flow");
+framework.actionDispatcher.register("flow", async (action) => {
+    console.log("[nav]", action.url);
+    await baseHandler(action);
+});
+```
+
+In practice, prefer middleware (`beforeLoad`) for cross-cutting concerns on navigation — replacing the flow handler is invasive.
+
+## Compound actions with custom kinds
+
+`CompoundAction` works with any registered kind:
+
+```ts
+framework.actionDispatcher.dispatch({
+    kind: "compound",
+    actions: [
+        makeFlowAction("/checkout/complete"),
+        makeConfirmAction("Add to email list?", { kind: "subscribe", email: user.email }),
+    ],
+});
+```
+
+Each inner action runs sequentially. A handler that throws short-circuits the remaining actions in the compound — wrap with `try/catch` if you want best-effort semantics.
+
+## Server-side considerations
+
+Action handlers run on the server during SSR if the controller dispatches them. Common patterns:
+
+- **External URLs**: the server can't navigate the user — most apps return early. The framework's built-in `external-url` handler does exactly that on SSR.
+- **Confirm-style**: no user to ask. Either auto-accept (use the inner action) or auto-reject (drop it).
+- **Telemetry-only**: works the same on both sides. Just record.
+
+If your handler depends on browser APIs that don't exist on the server, gate with `typeof window === "undefined"`.
+
+## Testing
+
+```ts
+import { afterEach, describe, expect, test, vi } from "vite-plus/test";
+import { Framework } from "@finesoft/front";
+import { registerConfirmHandler, makeConfirmAction } from "./confirm";
+
+describe("confirm action", () => {
+    afterEach(() => vi.restoreAllMocks());
+
+    test("dispatches inner action when confirmed", async () => {
+        const framework = Framework.create({});
+        registerConfirmHandler(framework);
+        vi.stubGlobal("window", { confirm: () => true });
+
+        const innerHandler = vi.fn();
+        framework.actionDispatcher.register("test", innerHandler);
+
+        await framework.actionDispatcher.dispatch(
+            makeConfirmAction("ok?", { kind: "test" } as any),
+        );
+
+        expect(innerHandler).toHaveBeenCalled();
+    });
+
+    test("skips inner action when cancelled", async () => {
+        const framework = Framework.create({});
+        registerConfirmHandler(framework);
+        vi.stubGlobal("window", { confirm: () => false });
+
+        const innerHandler = vi.fn();
+        framework.actionDispatcher.register("test", innerHandler);
+
+        await framework.actionDispatcher.dispatch(
+            makeConfirmAction("ok?", { kind: "test" } as any),
+        );
+
+        expect(innerHandler).not.toHaveBeenCalled();
+    });
+});
+```
+
+## When to use a custom action vs middleware
+
+| Concern                                         | Custom action | Middleware (`beforeLoad`)    |
+| ----------------------------------------------- | ------------- | ---------------------------- |
+| Confirmation before navigating to specific URLs | ✅            | ❌ (would run for every nav) |
+| Audit log on every navigation                   | ❌            | ✅                           |
+| New mechanism for performing an operation       | ✅            | ❌                           |
+| Gate-keeping all navigation to admin routes     | ❌            | ✅                           |
+
+Custom actions are for **new kinds of operations.** Middleware is for **cross-cutting concerns on existing operations.**