Replace NavigationManagerSession session-scope with ThreadLocal

[marioserrano09]

Part of #107.

Problem

NavigationManagerSession (platform/core/navigation/.../NavigationManagerSession.java) is @Scope("session"): a single shared slot (page, pageParams, runLaterQueue) per HTTP session, used to hand off the initial page to whichever ZKNavigationManager desktop bean is constructed next.

When multiple tabs/iframes are opened concurrently in the same session (e.g. a host shell embedding several /page-embed/** iframes at once), each request's setPageLater(page, params) overwrites the previous pending page/params before the corresponding desktop's @PostConstruct (ZKNavigationManager.init()) consumes it. Result: wrong page shown in an iframe, duplicated pages, or a requested page silently dropped. Same race applies to runLaterQueue.

Key insight

The only real callers (PageNavigationController.navigate() / PageEmbedController) resolve the ModelAndView through ChainableUrlBasedViewResolver → InternalResourceView, which renders via RequestDispatcher.forward() to the .zul view. A servlet forward is synchronous, same thread — ZK creates the Desktop and runs ZKNavigationManager.init() (and later ZKNavigationComposer.doAfterCompose(), which drains runLaterQueue) within that same forwarded request, on the same thread that called setPageLater/runLater.

Session scope is therefore unnecessary and actively harmful under concurrency. No token/correlation mechanism is needed — a ThreadLocal naturally isolates each concurrent request (each tab/iframe bootstrap) without touching PageNavigationController/PageEmbedController at all. This supersedes and closes #111 (token propagation is no longer needed).

Change

• Replace the @Scope("session") Spring bean with a plain ThreadLocal<NavigationManagerSession> holder (getInstance() lazily creates a thread-local instance; keep the class name and public method signatures — setPage, updateNavManager, runLater, executeQueue, getPage, getPageParams — unchanged to preserve the public API).
• Add NavigationManagerSession.clear() to remove the thread-local entry.
• Register a servlet Filter (or equivalent request-lifecycle hook) that calls clear() in a finally after each request, so pooled threads don't retain a stale instance.
• Document the new contract on the class Javadoc: setPageLater/runLater must be called on the same thread that will render/forward into the target ZK desktop (i.e. before an HTTP forward, never before a redirect — a redirect is a new request on a possibly different thread and the thread-local won't survive it). No current caller in the repo violates this; flag it for future callers.

Affected files

• platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java
• platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java (Javadoc for setPageLater/runLater)
• platform/ui/zk/src/main/java/tools/dynamia/zk/navigation/ZKNavigationManager.java (init(), unchanged logic, just confirm still same-thread)
• new: request-lifecycle filter to clear the ThreadLocal (likely in platform/core/web or platform/ui/zk-starter)

[marioserrano09]

Implemented on branch feat/navigation-multi-desktop-support (commit 32ed21b): NavigationManagerSession is now a ThreadLocal holder instead of a @Scope("session") bean, with clear() called by a new NavigationManagerSessionCleanupFilter (OncePerRequestFilter) after every request. Public API (setPage, updateNavManager, runLater, executeQueue, getPage, getPageParams) unchanged. Javadoc on the class and on NavigationManager#setPageLater/runLater documents the thread-affinity contract. Full project build passes.

[marioserrano09]

Updated (commit 0e267d8): switched from ThreadLocal to ScopedValue (JEP 506, final in Java 25, this project's target). NavigationManagerSession.SCOPE is a ScopedValue<NavigationManagerSession>; the filter (renamed NavigationManagerSessionScopeFilter) now binds it via ScopedValue.where(...).call(...) around the whole request instead of clearing it afterward — the binding is torn down automatically on return or exception, no manual cleanup, and plays correctly with virtual threads/structured concurrency. getInstance() now throws NoSuchElementException outside a bound scope (fail-fast instead of a silent lazy-create). All tests updated, including a concurrency test with two threads bootstrapping simultaneously. mvn clean test green on both modules.

[marioserrano09]

Follow-up (commits 812b3a1, 7809c5c, PR #112): the per-request `ScopedValue` alone broke callers that record an intent and end the request without forwarding into a desktop. Found while reviewing dynamia-erp, whose `LoginListener`s call `setPageLater`/`runLater` inside `AuthenticationSuccessEvent` (Spring Security chain) and then redirect, and whose `EmpresaViewModel.save()` does `setPageLater` + `sendRedirect`.

Contract change: the "never before a redirect" rule from this issue's description no longer holds.

• `NavigationManagerSessionScopeFilter` parks any still-pending intent in the HTTP session at the end of the request and restores it into the next request's instance; the first desktop bootstrap consumes it. Parked state is `transient` (queued callbacks aren't serializable) and never shared across sessions.
• The filter is now `@Order(HIGHEST_PRECEDENCE + 10)`, so the scope is bound before Spring Security fires login listeners.
• `NavigationManagerSession` gained `hasPendingState()`, `absorb()` and an `onPending` hook. The hook creates the HTTP session when the intent is recorded, before a redirect commits the response — a bug the unit tests missed (first request with no session lost the intent) and the demo app caught.

Verification: unit tests (10 + 9) green. `examples/demo-zk-books` gained `/demo/handoff/` endpoints; from the packaged jar: login-style filter at order -100 + redirect from a fresh session, controller `setPageLater` + redirect, single consumption, 10 concurrent sessions doing the login flow (all land on the right page, 10 callbacks run), 45 concurrent `/page-embed/` on one session without cross-contamination. No `NoSuchElementException` or dropped-state warnings.

Known limits / not verified

• Not tested against a real Spring Security login (the demo has none) — needs a run against dynamia-erp.
• Residual race: the parked intent goes to the first request that arrives, not necessarily the intended one (e.g. two iframes opened right after a login). Better than the old shared slot; removing it needs a per-URL token (ruled out here).
• `Serializable` on `NavigationManagerSession` is vestigial; left untouched.

[marioserrano09]

Implementado y mergeado en #112 (cd0e6dd en main). Cerrado. Pendiente a nivel épica (#107): validación contra dynamia-erp con login real de Spring Security y documentar el contrato de hand-off en docs/backend/.