@finesoft/front 0.5.1 → 0.5.2

package/docs/12-session-restoration.md

@@ -1,219 +1,11 @@
-# 12. Session restoration
+# Session restoration and multiple instances
 
-The framework already restores the **first screen**: SSR injects the prefetched intent results through `PrefetchedIntents`, and the browser reuses them on the first navigation. Structured navigation also carries the current tree across back/forward via `history.state`.
+Create embedded apps with `createBrowserApp({ definition, target, history: "memory", persistenceKey: "first", session: {}, domRestore: true })`. Each instance needs its own target and stable persistence key. Only one app per window may own browser history.
 
-But one class of state survives **none** of that: what the user was actually _doing_ when they **hard-reloaded, crashed the tab, or closed and came back** — which screen (or stack depth, or tab, or split column) they were on, the half-typed draft in a form, how far a list was scrolled. The in-memory `history.state` map is wiped by a full reload; `PrefetchedIntents` only covers the one server-rendered screen.
+Mount the native App, then await `app.ready`. Session reading/restoration starts after the first native commit acknowledgement; Outlet's commit never waits for restore. Register React persistence providers in a layout effect, and Vue/Svelte providers during native mount. `app.session.register(provider)` returns an unregister callback. Provider capture/restore accesses native business state directly; no separate NameStore is required.
 
-**Session restoration** fills that gap: it serializes a versioned, JSON-safe **session snapshot** (navigation position + app-registered state slices + navigation-scoped per-screen state) to a pluggable `Storage`, and rehydrates it on a fresh load. The framework ships **no UI** — it restores **state**, and your app re-renders from it however you like.
+Hidden pages retain native instances. Pop removes the entry and scoped draft. DOM restoration handles explicitly marked fields and scroll within `data-restore-root`, bounded by the owning app. Instances do not capture one another's inputs.
 
-It is entirely opt-in: an app that never passes `session` to `startBrowserApp` is **byte-for-byte unchanged**.
+`app.session.save()` and `clear()` return observable results. Adjacent unstarted implicit saves coalesce; explicit snapshots, load, restore and clear are ordered boundaries. Disposal captures the current state and waits for registered storage work. Browser shutdown still cannot guarantee an asynchronous write finishes.
 
-## The two scopes
-
-A snapshot captures two layers of state, serialized together and restored together across a reload:
-
-| Scope                       | Lives in | Keyed by       | Lifetime                                                                | SwiftUI analogue |
-| --------------------------- | -------- | -------------- | ----------------------------------------------------------------------- | ---------------- |
-| **Global slices**           | `slices` | `provider.key` | The whole session (theme, a cross-screen wizard draft…)                 | `@SceneStorage`  |
-| **Navigation-scoped state** | `scoped` | `entryKey`     | Bound to one navigation entry — dropped when that entry leaves the tree | `@State`         |
-
-- **Global slices** are app-wide. You register a `SessionStateProvider` per slice; the framework orchestrates _when_ it is captured and persisted. It never interprets the contents — it only moves them.
-- **Navigation-scoped state** is bound to a _navigation entry_, mirroring the position-scoped lifecycle of a SwiftUI view's `@State` (covered below).
-
-## Global slices: `SessionStateProvider`
-
-An app registers one provider per slice. `capture()` returns a JSON-safe synchronous value; `restore(data)` puts it back (your app calls `setState` / refills the form / scrolls):
-
-```ts
-import type { SessionStateProvider } from "@finesoft/front";
-
-const themeSlice: SessionStateProvider<string> = {
-    key: "theme",
-    capture: () => getCurrentTheme(),
-    restore: (theme) => applyTheme(theme),
-};
-```
-
-The framework moves the value verbatim and never inspects it — so **you** decide what to capture. Exclude sensitive fields right here in `capture()`; a slice you never register is never captured.
-
-## Navigation-scoped state: the SwiftUI `@State` lifecycle
-
-Navigation-scoped state is the interesting half. It is keyed by **entry identity**, not by visibility, and it follows the same position-scoped lifecycle as a SwiftUI view's `@State`:
-
-> `A` → push `B` → go back (pop `B`) to `A`: **`B`'s state is discarded, `A`'s state is still there.**
-
-The mechanism: each entry's state bag is stored under `entryKey = intent + " " + stableStringify(params)` — the same identity the navigation controller uses for a destination, so it is **stable across a reload**. After every committed navigation, the framework **prunes** the scoped map down to the entries **actually present in the tree** — note _present_, not _visible_. Any key whose entry is no longer in the tree is dropped.
-
-```ts
-import { sessionEntryKey } from "@finesoft/front";
-
-// When you render a screen, read/write its scoped bag with the entry's key:
-const key = sessionEntryKey("post", { id: 7 });
-store.scope.set(key, { scroll: 240, draft: "half a comment" });
-const bag = store.scope.get(key); // -> { scroll: 240, draft: "..." } | undefined
-```
-
-Walking through the lifecycle:
-
-- **push `B`** → tree `[A, B]`, present `{A, B}` → `A`'s state is **kept** (`A` is still on the stack, just not visible) and `B` gets its own scope.
-- **pop `B`** → tree `[A]`, present `{A}` → **`B`'s scope is pruned away**, `A`'s is kept intact; going back to `A` renders with its retained state.
-- **switch a TabView tab** → the other branches are still in the tree → their state is kept alive (exactly like SwiftUI keeping inactive tabs mounted).
-- **across a reload** → `scoped` is serialized into the snapshot; after reload, every entry still in the tree gets its scope back, and a later pop discards it as usual.
-
-`store.scope` is the `NavigationScopedState` instance held by the store — `get` / `set` / `delete` / `keys`, plus the `prune(presentKeys)` the framework calls for you. With the high-level `startBrowserApp({ session })` path you don't hold the store directly: the `SessionHandle` handed to your `mount` callback (context) exposes the same instance as `handle.scope` (still live after a restore rebuilds it), so you `handle.scope.get(entryKey)` / `set(entryKey, data)` the same way.
-
-### Flat vs structured: retention _is_ a stack
-
-That "keep `A` under `B`, drop `B` on pop, restore `A`" behavior is, by definition, **stack semantics** — so it only exists in **structured navigation**, where a stack/tree can hold entries that are _present but not visible_.
-
-A **flat single page has no stack**: `A → B` is a full-page replacement, so `presentKeys()` is always a single entry (the current URL). The moment you leave a screen its scope is pruned, and a browser **Back** re-renders it fresh.
-
-Both modes support "current-screen scope + restore-across-reload". If you want "go Back and keep the previous screen", build it as a structured stack — push instead of replace. That is precisely what `NavigationStack` is _for_; it is not a shortcoming of flat mode.
-
-## The snapshot
-
-`createSessionStore(options)` returns the `SessionStore` orchestrator. `capture()` assembles a snapshot without persisting; the snapshot model is:
-
-```ts
-interface SessionSnapshot {
-    readonly version: number;
-    readonly navigation?: SerializedNavigation | SessionUrlLocation; // structured tree | { url }
-    readonly slices: Readonly<Record<string, unknown>>; // provider.key -> capture()
-    readonly scoped: Readonly<Record<string, unknown>>; // entryKey -> state bag
-    readonly capturedAt: number; // epoch ms, for maxAgeMs expiry
-}
-```
-
-`navigation` is discriminated with a light guard: a `SerializedNavigation` always carries a `kind` (leaf/stack/tabs/split); a flat `SessionUrlLocation` carries a `url`. `isUrlLocation(nav)` tells them apart.
-
-The store exposes:
-
-```ts
-interface SessionStore {
-    register(provider: SessionStateProvider): () => void; // returns a disposer
-    readonly scope: NavigationScopedState;
-    capture(): SessionSnapshot; // assemble (nav + slices + scoped), no I/O
-    persist(snapshot?: SessionSnapshot): void; // capture() if omitted, then write
-    load(): SessionSnapshot | undefined; // read + validate (version / maxAge / shape)
-    restore(snapshot?: SessionSnapshot): void | Promise<void>; // load() if omitted, then apply
-    clear(): void; // remove the persisted snapshot
-    save(): void; // capture + persist — the manual escape hatch
-}
-```
-
-`load()` discards a snapshot whose version mismatches, whose `capturedAt` is older than `maxAgeMs`, or whose shape is malformed — it returns `undefined` rather than ever throwing into your app. A provider that throws in `capture()` / `restore()` is isolated: its slice is skipped, the error goes to `onError`, and the rest of the snapshot survives.
-
-## Persistence: `sessionStorage` by default, swappable
-
-The snapshot is encoded with a stable stringify and written as a single `storage.set(key, ...)`. `Storage` is the existing core dependency interface, so durability is **your** choice:
-
-```ts
-import { createWebStorage } from "@finesoft/front";
-
-createWebStorage("session"); // sessionStorage — tab-scoped, cleared when the tab closes (default)
-createWebStorage("local"); // localStorage — survives across tabs and restarts
-```
-
-`createWebStorage` maps `get`/`set`/`delete` onto `getItem`/`setItem`/`removeItem`, swallows quota errors on write (session restoration is best-effort — it never interrupts navigation), and degrades to a safe no-op when the chosen Web Storage is unavailable (e.g. private mode `SecurityError`).
-
-Because it is just the `Storage` interface, you can supply **any** implementation — an in-memory store for tests, or a server-synced `Storage` for cross-device restoration. The framework v1 ships no built-in server endpoint, but the seam is open.
-
-## Wiring it into the browser
-
-Pass an optional `session` to `startBrowserApp`. When present, the framework builds a `SessionStore`, registers your providers, wires a `SessionBridge` (auto-capture on navigation + `pagehide`/`visibilitychange`), runs the boot restore after the first navigation, and hands you a `SessionHandle`:
-
-```ts
-// src/main.ts
-import { startBrowserApp } from "@finesoft/front";
-import { bootstrap } from "./bootstrap";
-import { themeSlice, draftSlice } from "./lib/session";
-
-startBrowserApp({
-    bootstrap,
-    callbacks,
-    session: {
-        providers: [themeSlice, draftSlice],
-        // storage defaults to createWebStorage("session")
-        maxAgeMs: 1000 * 60 * 60 * 24, // discard snapshots older than a day (optional)
-    },
-    mount(target, { session, app }) {
-        // session: SessionHandle (save/clear/scope/...); app: unified nav+session handle.
-        // Auto-capture/restore already run; use session.save() / session.clear() as escape hatches.
-        // ... mount your UI; pass `app` (or `session`) to components ...
-        return () => undefined;
-    },
-});
-```
-
-When `session` is **absent**, none of this runs and the original `startBrowserApp` path is byte-for-byte unchanged.
-
-### Flat vs structured wiring (automatic)
-
-`startBrowserApp` picks the navigation adapter for you:
-
-- **With** a `navigation` config → the structured `createNavigationSessionAdapter(controller)`: it serializes the whole tree, and on restore `hydrate`s it back. Auto-capture is driven by the navigation handle's `subscribe`.
-- **Without** `navigation` (flat single page) → the `createUrlSessionAdapter` bound to `framework.perform(makeFlowAction(url))`: it captures `{ url }` and navigates on restore.
-
-You only choose the adapter directly if you are assembling the store yourself (e.g. on the server, or in tests).
-
-## The handle: manual save / clear / dispose
-
-The `SessionHandle` (delivered in the mount context) gives you the escape hatches — auto-capture already runs, but you can force a write, clear the snapshot, or tear everything down. The unified `app` handle merges navigation commands with session `save`/`clear`/`scope`, so components can hold a single object instead of assembling their own controller:
-
-```ts
-interface SessionHandle {
-    restore(currentUrl: string): void | Promise<void>; // boot restore (already called for you)
-    save(): void; // force an immediate persist
-    clear(): void; // drop the persisted snapshot (e.g. on logout)
-    dispose(): void; // unsubscribe navigation + remove pagehide/visibilitychange + clear timers
-}
-```
-
-Call `handle.clear()` on logout so the next user doesn't inherit a stale session; call `handle.dispose()` if you tear down the app instance yourself.
-
-### When does it capture?
-
-You rarely call `save()` — capture is automatic:
-
-- **On navigation change**: the bridge first prunes the scoped map to `adapter.presentKeys()` (this is where "pop `B` drops `B`'s state" actually lands), then **debounces** a write (default `SESSION_DEFAULT_DEBOUNCE_MS` = 500 ms, coalescing rapid navigations). Tune with `session.debounceMs`.
-- **On `pagehide` and `visibilitychange` (hidden)**: it persists **immediately** and cancels any pending debounce — more reliable than `beforeunload` on mobile (the last state is captured before the tab is backgrounded or reclaimed).
-
-## Deep-link policy: `shouldRestore`
-
-On boot the bridge reads the snapshot and applies it **only if** `shouldRestore(snapshot, currentUrl)` passes — a single boolean gate for the whole `nav + slices` restore. The default, `defaultShouldRestore`, honors **explicit deep links over a stale session**:
-
-| Snapshot `navigation`                   | Restores when…                                                               |
-| --------------------------------------- | ---------------------------------------------------------------------------- |
-| **Flat** (`SessionUrlLocation`)         | `currentUrl === snapshot.navigation.url` **or** the current path is root `/` |
-| **Structured** (`SerializedNavigation`) | the current path is root `/`                                                 |
-| **None** (slices only)                  | always (URL-independent)                                                     |
-
-So reloading the same page (or entering fresh at `/`) restores; opening a different deep link `/x` does **not** get overwritten by an old session. "Root" is the path `=== "/"` (query/hash stripped). Apps served under a base path should override the gate:
-
-```ts
-session: {
-    providers: [themeSlice],
-    shouldRestore: (snapshot, currentUrl) => currentUrl.startsWith("/app/"),
-}
-```
-
-Restoring to a different state than the SSR'd URL produces one client-side jump (SSR renders the URL's screen, then the client restores). That timing is exposed through the bridge so you can control it; a pure-CSR app can restore before first paint and avoid it entirely.
-
-## What is _not_ captured
-
-- **DOM you didn't register.** The framework never scans the DOM. State slices are whatever your providers `capture()` — nothing more.
-- **Anything when you register no providers.** With only navigation (or nothing) registered, capture is effectively zero — the privacy default.
-- **Sensitive fields you exclude.** `capture()` is your filter; strip tokens, PII, and the like there.
-- **A stale, expired, or malformed snapshot.** `load()` returns `undefined` instead of crashing the app to restore a bad state.
-
-## Backward compatibility
-
-- An app that doesn't pass `session` to `startBrowserApp` runs the **original path** with zero behavior change — the entire feature is gated behind that one field.
-- Session restoration adds no requirement on the server. A server-synced snapshot is possible by supplying your own `Storage`, but nothing is built in.
-- The framework restores **state**, never UI. Your `Page` models and how you render them are untouched.
-
-## Next
-
-- [Navigation](./11-navigation.md) — the structured tree whose entries scope per-screen state
-- [Rendering & hydration](./04-rendering-and-hydration.md) — how the first screen is already restored via prefetched results
-- [DI container](./07-di-container.md) — the `Storage` dependency that session restoration persists through
+Clean up with `try { await app.dispose(); } finally { nativeRoot.unmount(); }`, using Svelte's `unmount` function when applicable. Other instances can keep calling `other.perform({ kind: "flow", url: "/" })`. Session protocol v2 uses a navigation tree; old URL-only snapshots are incompatible. Business slices retain independent versions and migration contracts.

package/docs/README.md

@@ -2,7 +2,7 @@
 
 > **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.
+Portable TypeScript execution, Web, browser, SSR, HTTP and platform APIs through `@finesoft/front`. Standard UI adapters support React, Vue and Svelte. Local artifact tests distinguish Node, workerd and browser Worker from an actual deployment.
 
 ## Three entry points
 
@@ -20,14 +20,14 @@ A linear path. Each chapter assumes the previous one. By the end you can build,
 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
+9. [Server & deployment](./09-server-and-deployment.md) — data endpoints, Node/Worker hosts, 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
+- [Project structure](./engineering/project-structure.md) — recommended layout, application definitions and view bindings, 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
 
@@ -44,7 +44,7 @@ Each entry is **symptom → root cause → fix**, kept short.
 
 ### Extending the framework — advanced recipes
 
-Each recipe is a complete, runnable extension example with explanation.
+Recipes explain supported public contracts and show application snippets; platform extensions require their own runtime verification.
 
 - [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
@@ -57,16 +57,16 @@ Each recipe is a complete, runnable extension example with explanation.
 ```
 URL/Action → Router.resolve()
           → beforeLoad chain   (NavigationContext: redirect/rewrite/deny/next)
-          → IntentDispatcher   (controller.execute() → Page; fallback() on error)
+          → RuntimeHandle   (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.
+The same application declaration is used by server and browser hosts. 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.
+- **Code blocks** show contracts and integration snippets; application components and local variables come from the surrounding example.
 - **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

@@ -1,248 +1,48 @@
-# Advanced: custom action handler
+# Application actions
 
-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.
+The WebSession is the ActionDispatcher and navigation state owner. Native views, intercepted links and custom handlers share `app.perform(action)`. Actions cover both URL navigation and structured Stack, Tab and Split changes; there is no separate navigation command object.
 
-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.
+`FlowAction` loads a URL. Without an explicit navigation tree or codec, the departing page is released; structured apps retain their existing branches. Navigating to the current URL reloads its existing entry. An explicit `push` creates a new entry, including for an equal target.
 
-## Use case: confirmation-gated action
+`perform` resolves after guards, data loading, commit and native acknowledgement. It returns the resulting navigation snapshot; a rejected tree action returns an uncommitted snapshot with `rejection`. Compound actions execute in order and stop on rejection or failure. An optional second argument `{ signal }` reaches guarded page loading.
 
-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).
+`app.onAction(kind, handler)` and `app.removeAction(kind)` register or explicitly replace handlers on the same executor. Keep business data operations on `app.runtime.execute`. ExternalUrlAction opens a new window with `noopener,noreferrer`; `{ kind: "reuseEntry", entryId }` reveals a retained instance without requiring a second URL.
 
-```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:
+A handler receives `(action, invocation)`. When it delegates to another action, pass the same invocation to `app.perform(nextAction, invocation)` so the entire sequence shares cancellation. New URL navigation cancels earlier groups; structured edits remain serialized and invalidate an older URL still resolving. Modal and external actions do not replace background navigation.
 
-```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:
+Browser navigation and guard redirects accept HTTP(S). ExternalUrlAction also accepts `mailto:` and `tel:`. Invalid URLs and executable or unsupported protocols are rejected before browser handoff; applications requiring a custom protocol can explicitly replace that action handler.
 
-```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:
+## URL and structured actions
 
 ```ts
-framework.actionDispatcher.dispatch({
-    kind: "compound",
-    actions: [
-        makeFlowAction("/checkout/complete"),
-        makeConfirmAction("Add to email list?", { kind: "subscribe", email: user.email }),
-    ],
-});
+await app.perform({ kind: "flow", url: "/items/42" });
+await app.perform({ kind: "push", intent: "item", params: { id: 42 } });
+await app.perform({ kind: "selectTab", key: "favorites" });
+await app.perform({ kind: "pop" });
+await app.perform({ kind: "refresh" });
 ```
 
-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
+## Migrating existing consumers
 
-Action handlers run on the server during SSR if the controller dispatches them. Common patterns:
+| Previous API                                         | Replacement                                                                                                      |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `app.navigation.navigate(url)`                       | `app.perform({ kind: "flow", url })`                                                                             |
+| `app.navigation.push(intent, params)`                | `app.perform({ kind: "push", intent, params })`                                                                  |
+| `controller.apply(operation)`                        | `controller.perform(action)` with the same structured fields                                                     |
+| `controller.resolve()` at startup                    | `controller.start()`                                                                                             |
+| `app.actionDispatcher.onAction/removeAction`         | `app.onAction/removeAction`                                                                                      |
+| `FlowAction.entryId`                                 | `{ kind: "reuseEntry", entryId }`                                                                                |
+| `NavigationHandle`, `SessionHandle`, `SessionAccess` | `NavigationBridge` for cleanup; `SessionStore` for persistence; `BrowserSession.restoreFromUrl` for browser boot |
 
-- **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.
+The old navigation commands and forwarding methods are removed. All other tree operations use the corresponding Action kind. Pure tree-building functions remain available for immutable composition.
 
-If your handler depends on browser APIs that don't exist on the server, gate with `typeof window === "undefined"`.
+## Modal presentation
 
-## Testing
+Pass `onModal(page, { app, snapshot })` to `createBrowserApp`, then call:
 
 ```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();
-    });
-});
+import { makeFlowAction } from "@finesoft/front";
+await app.perform(makeFlowAction("/items/42", "modal"));
 ```
 
-## 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.**
+The host runs navigation policies and page guards before invoking `onModal` once. The callback renders the modal with the application's native UI; background navigation and history remain unchanged. A denial supplies an error page and sanitized snapshot, never rejected page data. Internal redirects remain modal, and external redirects hand off without delivering a modal. Register `onModal` before using modal actions. SSR views cannot perform browser actions.