From 32ed21bb209008aad2e19772af6a244275cf4c98 Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Tue, 29 Sep 2026 12:36:04 -0500
Subject: [PATCH 1/6] fix(navigation): make NavigationManagerSession
 thread-local instead of session-scoped

PageNavigationController/PageEmbedController render their view via a
servlet forward, so setPageLater()/runLater() and the ZK desktop that
consumes them (ZKNavigationManager.init(), doAfterCompose()) always run
on the same thread within the same request. A session-scoped bean was
therefore both unnecessary and unsafe: concurrent tabs/iframes in the
same HTTP session would race on the single shared page/params slot.

Replaces the @Scope("session") bean with a ThreadLocal holder (same
public API) and adds a request-completion filter to clear it, so
pooled threads don't retain a stale instance across requests.

Refs #107, #108

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../dynamia/navigation/NavigationManager.java | 14 +++--
 .../navigation/NavigationManagerSession.java  | 50 ++++++++++++++---
 ...NavigationManagerSessionCleanupFilter.java | 53 +++++++++++++++++++
 3 files changed, 108 insertions(+), 9 deletions(-)
 create mode 100644 platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilter.java

diff --git a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
index cd8b8030..67581556 100644
--- a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
+++ b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
@@ -105,7 +105,12 @@ static NavigationManager getCurrent() {
     }
 
     /**
-     * Delegate set current {@link Page} using a {@link NavigationManagerSession} when NavigationManager is builded
+     * Delegate set current {@link Page} using a {@link NavigationManagerSession} when NavigationManager is builded.
+     * <p>
+     * {@link NavigationManagerSession} is thread-local: this must be called on the same thread that
+     * will forward into the target ZK desktop (e.g. from a controller rendering an {@code index}/
+     * {@code embed} ZUL view via a server-side forward), never before an HTTP redirect — a redirect
+     * is a new request on a possibly different thread, so the value would not be picked up.
      *
      * @param page
      */
@@ -114,7 +119,8 @@ static void setPageLater(Page page) {
     }
 
     /**
-     * Delegate set current {@link Page} using a {@link NavigationManagerSession} when NavigationManager is builded
+     * Delegate set current {@link Page} using a {@link NavigationManagerSession} when NavigationManager is builded.
+     * See {@link #setPageLater(Page)} for the thread-affinity requirement.
      *
      * @param page
      * @param params
@@ -132,7 +138,9 @@ static void setPageLater(String path, Map<String, Serializable> params) {
     }
 
     /**
-     * Delegate callback to run when {@link NavigationManager} are builded. Its store a Queue using {@link NavigationManagerSession}
+     * Delegate callback to run when {@link NavigationManager} are builded. Its store a Queue using {@link NavigationManagerSession}.
+     * See {@link #setPageLater(Page)} for the thread-affinity requirement — this must be called on
+     * the same thread that will build the target {@link NavigationManager}.
      *
      * @param callback
      */
diff --git a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java
index 85184286..b68aa047 100644
--- a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java
+++ b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java
@@ -1,26 +1,64 @@
 package tools.dynamia.navigation;
 
-import org.springframework.context.annotation.Scope;
 import tools.dynamia.commons.Callback;
-import tools.dynamia.integration.Containers;
-import tools.dynamia.integration.sterotypes.Component;
 
 import java.io.Serializable;
 import java.util.LinkedList;
 import java.util.Map;
 import java.util.Queue;
 
-@Component
-@Scope("session")
+/**
+ * Holds a navigation intent (a {@link Page} plus optional params, and/or queued {@link Callback}s)
+ * so it can be picked up by the {@link NavigationManager} of a ZK desktop that is about to be built.
+ * <p>
+ * This is a {@link ThreadLocal} holder, not a session-scoped bean: the only supported flow is a
+ * server-side forward (e.g. {@code RequestDispatcher.forward()}, as used by
+ * {@code PageNavigationController}/{@code PageEmbedController} to render an {@code index}/{@code embed}
+ * ZUL view) where the code calling {@link #setPage(Page, Map)}/{@link #runLater(Callback)} and the
+ * ZK desktop bootstrap that consumes it ({@code ZKNavigationManager.init()},
+ * {@code ZKNavigationComposer.doAfterCompose()}) run on the very same thread, within the very same
+ * HTTP request.
+ * </p>
+ * <p>
+ * <b>Do not</b> call {@link #setPage(Page, Map)}/{@link #runLater(Callback)} before an HTTP
+ * <b>redirect</b> expecting a later request to pick it up — a redirect is a new request, possibly
+ * served by a different thread, and the thread-local value won't be there. If that use case ever
+ * arises it needs a different, explicit hand-off mechanism, not this class.
+ * </p>
+ * <p>
+ * Using a thread-local (instead of the session-scoped bean this class used to be) is what makes it
+ * safe for multiple ZK desktops to bootstrap concurrently in the same HTTP session — e.g. several
+ * {@code <iframe>}s, each loading its own ZK page, or several real browser tabs opened at once. A
+ * session-scoped slot would be shared and overwritten across those concurrent requests; a
+ * thread-local is naturally isolated per request/thread.
+ * </p>
+ *
+ * @author Mario A. Serrano Leones
+ */
 public class NavigationManagerSession implements Serializable {
 
+    private static final ThreadLocal<NavigationManagerSession> CURRENT =
+            ThreadLocal.withInitial(NavigationManagerSession::new);
+
     private Page page;
     private Map<String, Serializable> pageParams;
 
     private Queue<Callback> runLaterQueue = new LinkedList<>();
 
+    /**
+     * Returns the instance bound to the current thread, creating it lazily.
+     */
     public static NavigationManagerSession getInstance() {
-        return Containers.get().findObject(NavigationManagerSession.class);
+        return CURRENT.get();
+    }
+
+    /**
+     * Removes the instance bound to the current thread. Must be called once the request that
+     * populated it (and forwarded into the target ZK desktop) has finished, so pooled threads don't
+     * retain a stale instance across unrelated requests.
+     */
+    public static void clear() {
+        CURRENT.remove();
     }
 
     public void setPage(Page page, Map<String, Serializable> params) {
diff --git a/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilter.java b/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilter.java
new file mode 100644
index 00000000..e1ce4c1c
--- /dev/null
+++ b/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilter.java
@@ -0,0 +1,53 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.web.navigation;
+
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.springframework.web.filter.OncePerRequestFilter;
+import tools.dynamia.integration.sterotypes.Component;
+import tools.dynamia.navigation.NavigationManagerSession;
+
+import java.io.IOException;
+
+/**
+ * Clears the thread-local {@link NavigationManagerSession} once a request finishes, so pooled
+ * request-handling threads don't retain a stale navigation intent (page/params/queued callbacks)
+ * across unrelated later requests.
+ * <p>
+ * {@link NavigationManagerSession} is populated and consumed within the same request/thread (a
+ * controller sets a pending page, then a server-side forward into the ZK desktop's view consumes
+ * it on that same thread) — see its Javadoc for the full contract. This filter only guarantees the
+ * thread-local is removed afterward regardless of how the request completes.
+ *
+ * @author Mario A. Serrano Leones
+ */
+@Component
+public class NavigationManagerSessionCleanupFilter extends OncePerRequestFilter {
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
+            throws ServletException, IOException {
+        try {
+            filterChain.doFilter(request, response);
+        } finally {
+            NavigationManagerSession.clear();
+        }
+    }
+}

From 2a4246e74a887bd95dc368c3a381914ca4397be1 Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Tue, 29 Sep 2026 12:39:59 -0500
Subject: [PATCH 2/6] feat(navigation): add stable instance id and
 session-level registry to NavigationManager

Adds NavigationManager#getId(), a framework-agnostic identifier
generated once per instance (BaseNavigationManager), so a manager can
be correlated to "which tab/iframe/desktop" it belongs to when several
instances are active in the same session at once.

Adds NavigationManagerRegistry (@Scope("session")), tracking every
active instance keyed by id. BaseNavigationManager self-registers on
construction. ZKNavigationManager wires best-effort unregistration via
a ZK DesktopCleanup listener when a desktop (tab/iframe) is destroyed;
correctness doesn't depend on this firing, since the registry itself
is session-scoped and is discarded along with the whole session.

Enables a future host shell embedding multiple ZK iframes to enumerate
or target a specific open tab/iframe's navigation instead of only
reaching "the current one" implicitly resolved from the executing
request/desktop.

Refs #107, #109, #110

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../navigation/BaseNavigationManager.java     | 18 ++++
 .../dynamia/navigation/NavigationManager.java | 15 +++
 .../navigation/NavigationManagerRegistry.java | 98 +++++++++++++++++++
 .../zk/navigation/ZKNavigationManager.java    | 15 ++-
 4 files changed, 145 insertions(+), 1 deletion(-)
 create mode 100644 platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerRegistry.java

diff --git a/platform/core/navigation/src/main/java/tools/dynamia/navigation/BaseNavigationManager.java b/platform/core/navigation/src/main/java/tools/dynamia/navigation/BaseNavigationManager.java
index 3817b891..8c5632d4 100644
--- a/platform/core/navigation/src/main/java/tools/dynamia/navigation/BaseNavigationManager.java
+++ b/platform/core/navigation/src/main/java/tools/dynamia/navigation/BaseNavigationManager.java
@@ -26,6 +26,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.UUID;
 
 /**
  * <p>
@@ -81,6 +82,7 @@ public abstract class BaseNavigationManager implements Serializable, NavigationM
 
     private NavigationBuilder currentNavigationBuilder;
     private Map<String, Serializable> currentPageParams;
+    private final String id;
 
     /**
      * Creates a new BaseNavigationManager with the given {@link ModuleContainer}.
@@ -91,6 +93,22 @@ public BaseNavigationManager(ModuleContainer container) {
         this.logger = new SLF4JLoggingService(BaseNavigationManager.class);
         this.attributes = new HashMap<>();
         this.container = container;
+        this.id = UUID.randomUUID().toString();
+        var registry = NavigationManagerRegistry.getInstance();
+        if (registry != null) {
+            registry.register(this);
+        }
+    }
+
+    /**
+     * Returns a stable, framework-agnostic identifier for this instance, generated once at
+     * construction time.
+     *
+     * @return an opaque, stable id for this instance
+     */
+    @Override
+    public String getId() {
+        return id;
     }
 
     /**
diff --git a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
index 67581556..191a7067 100644
--- a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
+++ b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
@@ -339,4 +339,19 @@ static void runLater(Callback callback) {
      * @param navigationBuilder the navigation builder to set
      */
     void setCurrentNavigationBuilder(NavigationBuilder navigationBuilder);
+
+    /**
+     * Returns a stable identifier for this {@link NavigationManager} instance, unique within the
+     * current user session, framework-agnostic (it never references a UI-specific concept such as a
+     * ZK {@code Desktop} id).
+     * <p>
+     * Used to correlate a manager instance with "which tab/iframe/desktop" it belongs to when more
+     * than one instance is active in the same session at once (e.g. several {@code <iframe>}s, each
+     * loading its own page, or several real browser tabs opened concurrently) — for logging,
+     * debugging, and for a session-level registry of active instances (see
+     * {@code NavigationManagerRegistry}).
+     *
+     * @return an opaque, stable id for this instance
+     */
+    String getId();
 }
diff --git a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerRegistry.java b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerRegistry.java
new file mode 100644
index 00000000..66bec13b
--- /dev/null
+++ b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerRegistry.java
@@ -0,0 +1,98 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.navigation;
+
+import org.springframework.context.annotation.Scope;
+import tools.dynamia.integration.Containers;
+import tools.dynamia.integration.sterotypes.Component;
+
+import java.io.Serializable;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Session-level registry of every {@link NavigationManager} instance currently active for the
+ * user's session, keyed by {@link NavigationManager#getId()}.
+ * <p>
+ * With one {@code NavigationManager} instance per ZK desktop (real browser tab, or one of several
+ * {@code <iframe>}s each loading its own ZK page), this registry lets a host shell — or any
+ * session-level code — enumerate or look up every tab/iframe currently open, instead of only being
+ * able to reach "the current one" implicitly resolved from whatever request/desktop is executing.
+ * </p>
+ * <p>
+ * Registration happens as soon as a manager instance is built (see {@code BaseNavigationManager}).
+ * Explicit unregistration (e.g. a ZK desktop being destroyed because its tab/iframe was closed) is
+ * best-effort — see the UI-framework-specific wiring for details. It is not required for
+ * correctness: since this registry is itself session-scoped, every entry is discarded automatically
+ * when the whole session ends, regardless of whether individual instances were unregistered first.
+ * </p>
+ *
+ * @author Mario A. Serrano Leones
+ */
+@Component
+@Scope("session")
+public class NavigationManagerRegistry implements Serializable {
+
+    private final Map<String, NavigationManager> instances = new ConcurrentHashMap<>();
+
+    public static NavigationManagerRegistry getInstance() {
+        return Containers.get().findObject(NavigationManagerRegistry.class);
+    }
+
+    /**
+     * Registers a manager instance, keyed by {@link NavigationManager#getId()}.
+     *
+     * @param manager the instance to register; ignored if null
+     */
+    public void register(NavigationManager manager) {
+        if (manager != null) {
+            instances.put(manager.getId(), manager);
+        }
+    }
+
+    /**
+     * Removes a manager instance from the registry.
+     *
+     * @param id the id of the instance to remove, as returned by {@link NavigationManager#getId()}
+     */
+    public void unregister(String id) {
+        if (id != null) {
+            instances.remove(id);
+        }
+    }
+
+    /**
+     * Returns every manager instance currently registered for this session.
+     *
+     * @return an unmodifiable snapshot-view of the active instances
+     */
+    public Collection<NavigationManager> getActiveInstances() {
+        return Collections.unmodifiableCollection(instances.values());
+    }
+
+    /**
+     * Finds a registered manager instance by id.
+     *
+     * @param id the id, as returned by {@link NavigationManager#getId()}
+     * @return the matching instance, or null if none is registered with that id
+     */
+    public NavigationManager find(String id) {
+        return id != null ? instances.get(id) : null;
+    }
+}
diff --git a/platform/ui/zk/src/main/java/tools/dynamia/zk/navigation/ZKNavigationManager.java b/platform/ui/zk/src/main/java/tools/dynamia/zk/navigation/ZKNavigationManager.java
index de25b290..76a1516b 100644
--- a/platform/ui/zk/src/main/java/tools/dynamia/zk/navigation/ZKNavigationManager.java
+++ b/platform/ui/zk/src/main/java/tools/dynamia/zk/navigation/ZKNavigationManager.java
@@ -23,11 +23,13 @@
 import org.zkoss.zk.ui.Desktop;
 import org.zkoss.zk.ui.event.Event;
 import org.zkoss.zk.ui.event.EventQueues;
+import org.zkoss.zk.ui.util.DesktopCleanup;
 import tools.dynamia.commons.logger.LoggingService;
 import tools.dynamia.commons.logger.SLF4JLoggingService;
 import tools.dynamia.integration.Containers;
 import tools.dynamia.navigation.BaseNavigationManager;
 import tools.dynamia.navigation.ModuleContainer;
+import tools.dynamia.navigation.NavigationManagerRegistry;
 import tools.dynamia.navigation.NavigationManagerSession;
 import tools.dynamia.navigation.Page;
 import tools.dynamia.navigation.PageEvent;
@@ -72,10 +74,21 @@ public ZKNavigationManager(ModuleContainer container) {
 
     @PostConstruct
     public void init() {
-        LOGGER.info("Initializing new " + getClass().getSimpleName() + " for desktop " + ZKUtil.getCurrentDesktop());
+        Desktop desktop = ZKUtil.getCurrentDesktop();
+        LOGGER.info("Initializing new " + getClass().getSimpleName() + " for desktop " + desktop);
 
         NavigationManagerSession.getInstance().updateNavManager(this);
 
+        if (desktop != null) {
+            String managerId = getId();
+            desktop.addListener((DesktopCleanup) cleanedUpDesktop -> {
+                try {
+                    NavigationManagerRegistry.getInstance().unregister(managerId);
+                } catch (RuntimeException e) {
+                    LOGGER.warn("Unable to unregister NavigationManager " + managerId + " on desktop cleanup: " + e.getMessage());
+                }
+            });
+        }
     }
 
     @Override

From 0b2b8310932f7f9e7172690238d2ef8ed8d3438b Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Tue, 29 Sep 2026 12:51:11 -0500
Subject: [PATCH 3/6] test(navigation): cover ThreadLocal
 NavigationManagerSession, instance id, and registry

- NavigationManagerSessionTest: same-thread get/set roundtrip, updateNavManager
  consuming/clearing pending state, runLater/executeQueue ordering, clear()
  behavior, and the key property motivating the redesign: a page set on one
  thread must not be visible from another (concurrent tab/iframe isolation).
- BaseNavigationManagerIdTest: getId() is non-null, stable, and unique per
  instance.
- NavigationManagerRegistryTest: register/unregister/find/getActiveInstances,
  including BaseNavigationManager's self-registration when a registry is
  reachable via Containers, and that construction doesn't fail without one.
- NavigationManagerSessionCleanupFilterTest: clears the thread-local after a
  successful chain and after the chain throws; the pending page stays visible
  to the chain itself.

TestNavigationManager is a minimal concrete BaseNavigationManager used only
by these tests (BaseNavigationManager itself is abstract; the only real
implementation, ZKNavigationManager, requires a ZK desktop).

Verified with `mvn test` on platform/core/navigation and platform/core/web
(-am): 21 new tests, all green, no regressions in the reactor.

Refs #107, #108, #109, #110

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../BaseNavigationManagerIdTest.java          |  50 +++++++
 .../NavigationManagerRegistryTest.java        | 138 ++++++++++++++++++
 .../NavigationManagerSessionTest.java         | 135 +++++++++++++++++
 .../navigation/TestNavigationManager.java     |  55 +++++++
 ...gationManagerSessionCleanupFilterTest.java |  90 ++++++++++++
 5 files changed, 468 insertions(+)
 create mode 100644 platform/core/navigation/src/test/java/tools/dynamia/navigation/BaseNavigationManagerIdTest.java
 create mode 100644 platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerRegistryTest.java
 create mode 100644 platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java
 create mode 100644 platform/core/navigation/src/test/java/tools/dynamia/navigation/TestNavigationManager.java
 create mode 100644 platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilterTest.java

diff --git a/platform/core/navigation/src/test/java/tools/dynamia/navigation/BaseNavigationManagerIdTest.java b/platform/core/navigation/src/test/java/tools/dynamia/navigation/BaseNavigationManagerIdTest.java
new file mode 100644
index 00000000..3cd2523a
--- /dev/null
+++ b/platform/core/navigation/src/test/java/tools/dynamia/navigation/BaseNavigationManagerIdTest.java
@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.navigation;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+/**
+ * Covers {@link NavigationManager#getId()} / {@link BaseNavigationManager}'s implementation: a
+ * stable, framework-agnostic identifier per instance, used to correlate a manager with "which
+ * tab/iframe/desktop" it belongs to (see {@link NavigationManagerRegistry}).
+ */
+public class BaseNavigationManagerIdTest {
+
+    @Test
+    public void shouldHaveNonNullId() {
+        NavigationManager manager = new TestNavigationManager();
+        assertNotNull(manager.getId());
+    }
+
+    @Test
+    public void shouldBeStableAcrossCalls() {
+        NavigationManager manager = new TestNavigationManager();
+        assertEquals(manager.getId(), manager.getId());
+    }
+
+    @Test
+    public void differentInstancesShouldHaveDifferentIds() {
+        NavigationManager one = new TestNavigationManager();
+        NavigationManager other = new TestNavigationManager();
+        assertNotEquals(one.getId(), other.getId());
+    }
+}
diff --git a/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerRegistryTest.java b/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerRegistryTest.java
new file mode 100644
index 00000000..fe653b6a
--- /dev/null
+++ b/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerRegistryTest.java
@@ -0,0 +1,138 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.navigation;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import tools.dynamia.integration.Containers;
+import tools.dynamia.integration.SimpleObjectContainer;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Covers {@link NavigationManagerRegistry}: the session-level registry of active
+ * {@link NavigationManager} instances that lets a host shell (or any session-level code) enumerate
+ * or target a specific open tab/iframe instead of only reaching "the current" implicit instance.
+ */
+public class NavigationManagerRegistryTest {
+
+    @BeforeEach
+    public void resetContainers() {
+        Containers.get().removeAllContainers();
+    }
+
+    @AfterEach
+    public void cleanupContainers() {
+        Containers.get().removeAllContainers();
+    }
+
+    @Test
+    public void registerShouldMakeInstanceFindableById() {
+        NavigationManagerRegistry registry = new NavigationManagerRegistry();
+        TestNavigationManager manager = new TestNavigationManager();
+
+        registry.register(manager);
+
+        assertSame(manager, registry.find(manager.getId()));
+    }
+
+    @Test
+    public void registerShouldIgnoreNull() {
+        NavigationManagerRegistry registry = new NavigationManagerRegistry();
+        registry.register(null);
+        assertTrue(registry.getActiveInstances().isEmpty());
+    }
+
+    @Test
+    public void unregisterShouldRemoveInstance() {
+        NavigationManagerRegistry registry = new NavigationManagerRegistry();
+        TestNavigationManager manager = new TestNavigationManager();
+        registry.register(manager);
+
+        registry.unregister(manager.getId());
+
+        assertNull(registry.find(manager.getId()));
+        assertTrue(registry.getActiveInstances().isEmpty());
+    }
+
+    @Test
+    public void findWithUnknownOrNullIdShouldReturnNull() {
+        NavigationManagerRegistry registry = new NavigationManagerRegistry();
+        assertNull(registry.find("does-not-exist"));
+        assertNull(registry.find(null));
+    }
+
+    @Test
+    public void getActiveInstancesShouldReflectMultipleRegistrations() {
+        NavigationManagerRegistry registry = new NavigationManagerRegistry();
+        TestNavigationManager tab1 = new TestNavigationManager();
+        TestNavigationManager tab2 = new TestNavigationManager();
+
+        registry.register(tab1);
+        registry.register(tab2);
+
+        assertEquals(2, registry.getActiveInstances().size());
+        assertTrue(registry.getActiveInstances().contains(tab1));
+        assertTrue(registry.getActiveInstances().contains(tab2));
+    }
+
+    @Test
+    public void getActiveInstancesShouldBeUnmodifiable() {
+        NavigationManagerRegistry registry = new NavigationManagerRegistry();
+        assertTrue(assertThrowsUnsupported(() -> registry.getActiveInstances().add(new TestNavigationManager())));
+    }
+
+    private boolean assertThrowsUnsupported(Runnable action) {
+        try {
+            action.run();
+            return false;
+        } catch (UnsupportedOperationException e) {
+            return true;
+        }
+    }
+
+    /**
+     * {@code BaseNavigationManager} self-registers on construction when a
+     * {@link NavigationManagerRegistry} is reachable through {@link Containers}, which is how
+     * registration actually happens outside of tests (no explicit wiring needed by callers).
+     */
+    @Test
+    public void baseNavigationManagerShouldSelfRegisterWhenRegistryIsAvailable() {
+        NavigationManagerRegistry registry = new NavigationManagerRegistry();
+        SimpleObjectContainer container = new SimpleObjectContainer();
+        container.addObject(registry);
+        Containers.get().installObjectContainer(container);
+
+        TestNavigationManager manager = new TestNavigationManager();
+
+        assertSame(manager, registry.find(manager.getId()));
+    }
+
+    /**
+     * Outside a Spring/Containers context (e.g. a plain unit test instantiating a manager directly,
+     * as most of this module's own tests do), construction must not fail just because no registry
+     * is reachable.
+     */
+    @Test
+    public void baseNavigationManagerShouldNotFailWithoutARegistry() {
+        new TestNavigationManager();
+    }
+}
diff --git a/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java b/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java
new file mode 100644
index 00000000..9c8979bb
--- /dev/null
+++ b/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java
@@ -0,0 +1,135 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.navigation;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Covers {@link NavigationManagerSession}'s thread-local behavior: it replaced a
+ * {@code @Scope("session")} bean specifically to isolate concurrent requests (e.g. several ZK
+ * desktops/iframes bootstrapping at once in the same HTTP session) from each other, so the key
+ * property under test is isolation across threads, not just the plain getter/setter contract.
+ */
+public class NavigationManagerSessionTest {
+
+    @AfterEach
+    public void cleanup() {
+        NavigationManagerSession.clear();
+    }
+
+    @Test
+    public void setPageAndGetPageShouldRoundtripOnSameThread() {
+        Page page = new Page("page", "Page", "the/page");
+        Map<String, java.io.Serializable> params = new HashMap<>();
+        params.put("k", "v");
+
+        NavigationManagerSession.getInstance().setPage(page, params);
+
+        assertSame(page, NavigationManagerSession.getInstance().getPage());
+        assertEquals(params, NavigationManagerSession.getInstance().getPageParams());
+    }
+
+    @Test
+    public void getInstanceShouldReturnSameInstanceWithinAThread() {
+        assertSame(NavigationManagerSession.getInstance(), NavigationManagerSession.getInstance());
+    }
+
+    @Test
+    public void updateNavManagerShouldConsumeAndClearPendingPage() {
+        Page page = new Page("page", "Page", "the/page");
+        NavigationManagerSession.getInstance().setPage(page, null);
+
+        TestNavigationManager navManager = new TestNavigationManager();
+        NavigationManagerSession.getInstance().updateNavManager(navManager);
+
+        assertSame(page, navManager.getCurrentPage());
+        assertNull(NavigationManagerSession.getInstance().getPage());
+        assertNull(NavigationManagerSession.getInstance().getPageParams());
+    }
+
+    @Test
+    public void runLaterShouldQueueAndExecuteInOrder() {
+        List<Integer> executed = new ArrayList<>();
+        NavigationManagerSession.getInstance().runLater(() -> executed.add(1));
+        NavigationManagerSession.getInstance().runLater(() -> executed.add(2));
+        NavigationManagerSession.getInstance().runLater(() -> executed.add(3));
+
+        NavigationManagerSession.getInstance().executeQueue();
+
+        assertEquals(List.of(1, 2, 3), executed);
+    }
+
+    @Test
+    public void executeQueueShouldDrainTheQueue() {
+        NavigationManagerSession.getInstance().runLater(() -> {
+        });
+        NavigationManagerSession.getInstance().executeQueue();
+
+        // a second call must be a no-op, not re-run anything or fail
+        NavigationManagerSession.getInstance().executeQueue();
+    }
+
+    @Test
+    public void clearShouldDropTheCurrentThreadInstance() {
+        Page page = new Page("page", "Page", "the/page");
+        NavigationManagerSession session = NavigationManagerSession.getInstance();
+        session.setPage(page, null);
+
+        NavigationManagerSession.clear();
+
+        NavigationManagerSession afterClear = NavigationManagerSession.getInstance();
+        assertNull(afterClear.getPage());
+    }
+
+    /**
+     * The whole point of moving away from session scope: a page/params set on one thread must not
+     * leak into a different thread handling a concurrent request (e.g. another tab/iframe
+     * bootstrapping at the same time in the same HTTP session).
+     */
+    @Test
+    public void pendingPageSetOnOneThreadShouldNotBeVisibleOnAnother() throws Exception {
+        Page page = new Page("page", "Page", "the/page");
+        NavigationManagerSession.getInstance().setPage(page, null);
+
+        ExecutorService executor = Executors.newSingleThreadExecutor();
+        try {
+            Future<Page> otherThreadPage = executor.submit(() -> NavigationManagerSession.getInstance().getPage());
+            assertNull(otherThreadPage.get(5, TimeUnit.SECONDS));
+        } finally {
+            executor.shutdownNow();
+            assertTrue(executor.awaitTermination(5, TimeUnit.SECONDS));
+        }
+
+        // still present on the original thread
+        assertSame(page, NavigationManagerSession.getInstance().getPage());
+    }
+}
diff --git a/platform/core/navigation/src/test/java/tools/dynamia/navigation/TestNavigationManager.java b/platform/core/navigation/src/test/java/tools/dynamia/navigation/TestNavigationManager.java
new file mode 100644
index 00000000..c4da6d04
--- /dev/null
+++ b/platform/core/navigation/src/test/java/tools/dynamia/navigation/TestNavigationManager.java
@@ -0,0 +1,55 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.navigation;
+
+import java.util.function.Consumer;
+
+/**
+ * Minimal concrete {@link BaseNavigationManager} used only to exercise its behavior in tests, since
+ * {@link BaseNavigationManager} itself is abstract and its only real implementation
+ * ({@code ZKNavigationManager}) lives in the {@code zk} module and requires a ZK desktop.
+ */
+public class TestNavigationManager extends BaseNavigationManager {
+
+    public TestNavigationManager(ModuleContainer container) {
+        super(container);
+    }
+
+    public TestNavigationManager() {
+        this(new ModuleContainer());
+    }
+
+    @Override
+    public void closePage(Page page) {
+        // no-op for tests
+    }
+
+    @Override
+    public void sendEvent(PageEvent evt) {
+        // no-op for tests
+    }
+
+    @Override
+    public void onPageEvent(Page page, Consumer<PageEvent> evt) {
+        // no-op for tests
+    }
+
+    @Override
+    public void clearPageEvents(Page page) {
+        // no-op for tests
+    }
+}
diff --git a/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilterTest.java b/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilterTest.java
new file mode 100644
index 00000000..b05f9158
--- /dev/null
+++ b/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilterTest.java
@@ -0,0 +1,90 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.web.navigation;
+
+import jakarta.servlet.ServletException;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockFilterChain;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+import tools.dynamia.navigation.NavigationManagerSession;
+import tools.dynamia.navigation.Page;
+
+import java.io.IOException;
+
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+/**
+ * Covers {@link NavigationManagerSessionCleanupFilter}: it must clear the thread-local
+ * {@link NavigationManagerSession} after the request completes, including when the rest of the
+ * chain throws, so pooled request-handling threads don't retain a stale navigation intent across
+ * unrelated later requests.
+ */
+public class NavigationManagerSessionCleanupFilterTest {
+
+    private final NavigationManagerSessionCleanupFilter filter = new NavigationManagerSessionCleanupFilter();
+
+    @AfterEach
+    public void cleanup() {
+        NavigationManagerSession.clear();
+    }
+
+    @Test
+    public void shouldClearSessionAfterSuccessfulChain() throws ServletException, IOException {
+        Page page = new Page("page", "Page", "the/page");
+        NavigationManagerSession.getInstance().setPage(page, null);
+
+        filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), new MockFilterChain());
+
+        assertNull(NavigationManagerSession.getInstance().getPage());
+    }
+
+    @Test
+    public void pendingPageShouldStillBeVisibleToTheChain() throws ServletException, IOException {
+        Page page = new Page("page", "Page", "the/page");
+        NavigationManagerSession.getInstance().setPage(page, null);
+
+        MockFilterChain chain = new MockFilterChain() {
+            @Override
+            public void doFilter(jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response) {
+                assertSame(page, NavigationManagerSession.getInstance().getPage());
+            }
+        };
+
+        filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), chain);
+    }
+
+    @Test
+    public void shouldClearSessionEvenWhenChainThrows() {
+        NavigationManagerSession.getInstance().setPage(new Page("page", "Page", "the/page"), null);
+
+        MockFilterChain failingChain = new MockFilterChain() {
+            @Override
+            public void doFilter(jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response) throws ServletException {
+                throw new ServletException("boom");
+            }
+        };
+
+        assertThrows(ServletException.class, () ->
+                filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), failingChain));
+
+        assertNull(NavigationManagerSession.getInstance().getPage());
+    }
+}

From 0e267d8fb2c888764645aa5314b5efc983a21f27 Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Tue, 29 Sep 2026 15:08:42 -0500
Subject: [PATCH 4/6] refactor(navigation): replace ThreadLocal with
 ScopedValue for NavigationManagerSession

Java 25 (this project's target) finalized ScopedValue (JEP 506), the
structured-concurrency-friendly replacement for ThreadLocal in exactly
this kind of "bind a value for the dynamic extent of a request" use
case, with better behavior under virtual threads and no manual cleanup
step (the binding is torn down automatically when the bound run/call
returns, even on exception).

NavigationManagerSession.SCOPE is now a ScopedValue<NavigationManagerSession>;
getInstance() throws NoSuchElementException if called outside a bound
scope, instead of the old ThreadLocal's implicit lazy-create. Renamed
NavigationManagerSessionCleanupFilter -> NavigationManagerSessionScopeFilter,
since its role changed from "clear afterward" to "bind the scope around
the whole request" via ScopedValue.where(...).call(...) - the filter
was only just introduced on this branch, so this is not an API break.

Updated tests accordingly, including a concurrency test proving two
threads bootstrapping concurrently (simulating two iframes/tabs) never
see each other's pending page - the actual property this whole change
exists to guarantee.

Verified with `mvn clean test` on platform/core/navigation and
platform/core/web (-am): all green, no regressions.

Refs #107, #108

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../dynamia/navigation/NavigationManager.java |  16 +-
 .../navigation/NavigationManagerSession.java  |  52 ++++---
 .../NavigationManagerSessionTest.java         | 121 +++++++++------
 ... NavigationManagerSessionScopeFilter.java} |  29 ++--
 ...gationManagerSessionCleanupFilterTest.java |  90 -----------
 ...vigationManagerSessionScopeFilterTest.java | 144 ++++++++++++++++++
 6 files changed, 273 insertions(+), 179 deletions(-)
 rename platform/core/web/src/main/java/tools/dynamia/web/navigation/{NavigationManagerSessionCleanupFilter.java => NavigationManagerSessionScopeFilter.java} (52%)
 delete mode 100644 platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilterTest.java
 create mode 100644 platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilterTest.java

diff --git a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
index 191a7067..37031940 100644
--- a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
+++ b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
@@ -107,10 +107,12 @@ static NavigationManager getCurrent() {
     /**
      * Delegate set current {@link Page} using a {@link NavigationManagerSession} when NavigationManager is builded.
      * <p>
-     * {@link NavigationManagerSession} is thread-local: this must be called on the same thread that
-     * will forward into the target ZK desktop (e.g. from a controller rendering an {@code index}/
-     * {@code embed} ZUL view via a server-side forward), never before an HTTP redirect — a redirect
-     * is a new request on a possibly different thread, so the value would not be picked up.
+     * {@link NavigationManagerSession} is a {@link ScopedValue}: this must be called within the same
+     * scope that will forward into the target ZK desktop (e.g. from a controller rendering an
+     * {@code index}/{@code embed} ZUL view via a server-side forward, with the scope established by
+     * a request-lifecycle filter around the whole request), never before an HTTP redirect — a
+     * redirect is a new request, possibly with no scope bound at all, so the value would not be
+     * picked up. Throws {@link java.util.NoSuchElementException} if no scope is currently bound.
      *
      * @param page
      */
@@ -120,7 +122,7 @@ static void setPageLater(Page page) {
 
     /**
      * Delegate set current {@link Page} using a {@link NavigationManagerSession} when NavigationManager is builded.
-     * See {@link #setPageLater(Page)} for the thread-affinity requirement.
+     * See {@link #setPageLater(Page)} for the scope requirement.
      *
      * @param page
      * @param params
@@ -139,8 +141,8 @@ static void setPageLater(String path, Map<String, Serializable> params) {
 
     /**
      * Delegate callback to run when {@link NavigationManager} are builded. Its store a Queue using {@link NavigationManagerSession}.
-     * See {@link #setPageLater(Page)} for the thread-affinity requirement — this must be called on
-     * the same thread that will build the target {@link NavigationManager}.
+     * See {@link #setPageLater(Page)} for the scope requirement — this must be called within the
+     * same scope that will build the target {@link NavigationManager}.
      *
      * @param callback
      */
diff --git a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java
index b68aa047..96a5a79a 100644
--- a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java
+++ b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java
@@ -11,34 +11,43 @@
  * Holds a navigation intent (a {@link Page} plus optional params, and/or queued {@link Callback}s)
  * so it can be picked up by the {@link NavigationManager} of a ZK desktop that is about to be built.
  * <p>
- * This is a {@link ThreadLocal} holder, not a session-scoped bean: the only supported flow is a
+ * Backed by a {@link ScopedValue}, not a session-scoped bean: the only supported flow is a
  * server-side forward (e.g. {@code RequestDispatcher.forward()}, as used by
  * {@code PageNavigationController}/{@code PageEmbedController} to render an {@code index}/{@code embed}
  * ZUL view) where the code calling {@link #setPage(Page, Map)}/{@link #runLater(Callback)} and the
  * ZK desktop bootstrap that consumes it ({@code ZKNavigationManager.init()},
- * {@code ZKNavigationComposer.doAfterCompose()}) run on the very same thread, within the very same
- * HTTP request.
+ * {@code ZKNavigationComposer.doAfterCompose()}) run within the same dynamic scope — the whole
+ * request, wrapped by a request-lifecycle filter that binds a fresh instance for its duration (see
+ * {@code NavigationManagerSessionScopeFilter}).
  * </p>
  * <p>
- * <b>Do not</b> call {@link #setPage(Page, Map)}/{@link #runLater(Callback)} before an HTTP
- * <b>redirect</b> expecting a later request to pick it up — a redirect is a new request, possibly
- * served by a different thread, and the thread-local value won't be there. If that use case ever
- * arises it needs a different, explicit hand-off mechanism, not this class.
+ * {@link #getInstance()} throws {@link java.util.NoSuchElementException} if called outside that
+ * scope — e.g. a background job, or test code that hasn't bound one itself via
+ * {@code ScopedValue.where(NavigationManagerSession.SCOPE, new NavigationManagerSession()).run(...)}.
+ * This is intentional: failing fast beats silently creating a throwaway instance whose state would
+ * be lost the moment the call returns.
  * </p>
  * <p>
- * Using a thread-local (instead of the session-scoped bean this class used to be) is what makes it
- * safe for multiple ZK desktops to bootstrap concurrently in the same HTTP session — e.g. several
- * {@code <iframe>}s, each loading its own ZK page, or several real browser tabs opened at once. A
- * session-scoped slot would be shared and overwritten across those concurrent requests; a
- * thread-local is naturally isolated per request/thread.
+ * Using a scoped value (instead of the session-scoped bean this class used to be, or a plain
+ * {@link ThreadLocal}) is what makes it safe for multiple ZK desktops to bootstrap concurrently in
+ * the same HTTP session — e.g. several {@code <iframe>}s, each loading its own ZK page, or several
+ * real browser tabs opened at once — and plays correctly with virtual threads and structured
+ * concurrency: the binding is strictly scoped to the dynamic extent of the request that created it,
+ * torn down automatically (even on exception) with no manual cleanup step, and never leaks into an
+ * unrelated request that happens to reuse the same platform thread.
  * </p>
  *
  * @author Mario A. Serrano Leones
  */
 public class NavigationManagerSession implements Serializable {
 
-    private static final ThreadLocal<NavigationManagerSession> CURRENT =
-            ThreadLocal.withInitial(NavigationManagerSession::new);
+    /**
+     * Scoped-value key binding a {@link NavigationManagerSession} to the dynamic extent of the
+     * request bootstrapping a ZK desktop. Exposed so the request-lifecycle filter that establishes
+     * the binding doesn't need extra indirection; ordinary callers should use {@link #getInstance()}
+     * instead of touching this directly.
+     */
+    public static final ScopedValue<NavigationManagerSession> SCOPE = ScopedValue.newInstance();
 
     private Page page;
     private Map<String, Serializable> pageParams;
@@ -46,19 +55,12 @@ public class NavigationManagerSession implements Serializable {
     private Queue<Callback> runLaterQueue = new LinkedList<>();
 
     /**
-     * Returns the instance bound to the current thread, creating it lazily.
+     * Returns the instance bound to the current scope.
+     *
+     * @throws java.util.NoSuchElementException if called outside a bound scope
      */
     public static NavigationManagerSession getInstance() {
-        return CURRENT.get();
-    }
-
-    /**
-     * Removes the instance bound to the current thread. Must be called once the request that
-     * populated it (and forwarded into the target ZK desktop) has finished, so pooled threads don't
-     * retain a stale instance across unrelated requests.
-     */
-    public static void clear() {
-        CURRENT.remove();
+        return SCOPE.get();
     }
 
     public void setPage(Page page, Map<String, Serializable> params) {
diff --git a/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java b/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java
index 9c8979bb..c5fe2865 100644
--- a/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java
+++ b/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java
@@ -16,13 +16,13 @@
  */
 package tools.dynamia.navigation;
 
-import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
 
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.NoSuchElementException;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
 import java.util.concurrent.Future;
@@ -31,105 +31,134 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
- * Covers {@link NavigationManagerSession}'s thread-local behavior: it replaced a
+ * Covers {@link NavigationManagerSession}'s {@link ScopedValue}-backed behavior: it replaced a
  * {@code @Scope("session")} bean specifically to isolate concurrent requests (e.g. several ZK
  * desktops/iframes bootstrapping at once in the same HTTP session) from each other, so the key
- * property under test is isolation across threads, not just the plain getter/setter contract.
+ * property under test is isolation across scopes, not just the plain getter/setter contract.
+ * <p>
+ * In production the scope is bound by {@code NavigationManagerSessionScopeFilter} around the whole
+ * request; these tests bind it themselves via {@link #inScope} to exercise the class in isolation.
  */
 public class NavigationManagerSessionTest {
 
-    @AfterEach
-    public void cleanup() {
-        NavigationManagerSession.clear();
+    private void inScope(Runnable body) {
+        ScopedValue.where(NavigationManagerSession.SCOPE, new NavigationManagerSession()).run(body);
     }
 
     @Test
-    public void setPageAndGetPageShouldRoundtripOnSameThread() {
+    public void getInstanceOutsideAScopeShouldThrow() {
+        assertThrows(NoSuchElementException.class, NavigationManagerSession::getInstance);
+    }
+
+    @Test
+    public void setPageAndGetPageShouldRoundtripWithinAScope() {
         Page page = new Page("page", "Page", "the/page");
         Map<String, java.io.Serializable> params = new HashMap<>();
         params.put("k", "v");
 
-        NavigationManagerSession.getInstance().setPage(page, params);
+        inScope(() -> {
+            NavigationManagerSession.getInstance().setPage(page, params);
 
-        assertSame(page, NavigationManagerSession.getInstance().getPage());
-        assertEquals(params, NavigationManagerSession.getInstance().getPageParams());
+            assertSame(page, NavigationManagerSession.getInstance().getPage());
+            assertEquals(params, NavigationManagerSession.getInstance().getPageParams());
+        });
     }
 
     @Test
-    public void getInstanceShouldReturnSameInstanceWithinAThread() {
-        assertSame(NavigationManagerSession.getInstance(), NavigationManagerSession.getInstance());
+    public void getInstanceShouldReturnSameInstanceWithinAScope() {
+        inScope(() -> assertSame(NavigationManagerSession.getInstance(), NavigationManagerSession.getInstance()));
     }
 
     @Test
     public void updateNavManagerShouldConsumeAndClearPendingPage() {
         Page page = new Page("page", "Page", "the/page");
-        NavigationManagerSession.getInstance().setPage(page, null);
 
-        TestNavigationManager navManager = new TestNavigationManager();
-        NavigationManagerSession.getInstance().updateNavManager(navManager);
+        inScope(() -> {
+            NavigationManagerSession.getInstance().setPage(page, null);
 
-        assertSame(page, navManager.getCurrentPage());
-        assertNull(NavigationManagerSession.getInstance().getPage());
-        assertNull(NavigationManagerSession.getInstance().getPageParams());
+            TestNavigationManager navManager = new TestNavigationManager();
+            NavigationManagerSession.getInstance().updateNavManager(navManager);
+
+            assertSame(page, navManager.getCurrentPage());
+            assertNull(NavigationManagerSession.getInstance().getPage());
+            assertNull(NavigationManagerSession.getInstance().getPageParams());
+        });
     }
 
     @Test
     public void runLaterShouldQueueAndExecuteInOrder() {
         List<Integer> executed = new ArrayList<>();
-        NavigationManagerSession.getInstance().runLater(() -> executed.add(1));
-        NavigationManagerSession.getInstance().runLater(() -> executed.add(2));
-        NavigationManagerSession.getInstance().runLater(() -> executed.add(3));
 
-        NavigationManagerSession.getInstance().executeQueue();
+        inScope(() -> {
+            NavigationManagerSession.getInstance().runLater(() -> executed.add(1));
+            NavigationManagerSession.getInstance().runLater(() -> executed.add(2));
+            NavigationManagerSession.getInstance().runLater(() -> executed.add(3));
+
+            NavigationManagerSession.getInstance().executeQueue();
+        });
 
         assertEquals(List.of(1, 2, 3), executed);
     }
 
     @Test
     public void executeQueueShouldDrainTheQueue() {
-        NavigationManagerSession.getInstance().runLater(() -> {
-        });
-        NavigationManagerSession.getInstance().executeQueue();
+        inScope(() -> {
+            NavigationManagerSession.getInstance().runLater(() -> {
+            });
+            NavigationManagerSession.getInstance().executeQueue();
 
-        // a second call must be a no-op, not re-run anything or fail
-        NavigationManagerSession.getInstance().executeQueue();
+            // a second call must be a no-op, not re-run anything or fail
+            NavigationManagerSession.getInstance().executeQueue();
+        });
     }
 
     @Test
-    public void clearShouldDropTheCurrentThreadInstance() {
-        Page page = new Page("page", "Page", "the/page");
-        NavigationManagerSession session = NavigationManagerSession.getInstance();
-        session.setPage(page, null);
-
-        NavigationManagerSession.clear();
+    public void scopeShouldNotLeakOutsideItsDynamicExtent() {
+        inScope(() -> NavigationManagerSession.getInstance().setPage(new Page("page", "Page", "the/page"), null));
 
-        NavigationManagerSession afterClear = NavigationManagerSession.getInstance();
-        assertNull(afterClear.getPage());
+        assertThrows(NoSuchElementException.class, NavigationManagerSession::getInstance);
     }
 
     /**
-     * The whole point of moving away from session scope: a page/params set on one thread must not
-     * leak into a different thread handling a concurrent request (e.g. another tab/iframe
-     * bootstrapping at the same time in the same HTTP session).
+     * The whole point of moving away from session scope: a page bound in one scope must not leak
+     * into a different, concurrently-running scope — e.g. two tabs/iframes bootstrapping at the same
+     * time in the same HTTP session, each on its own thread, each binding its own scope.
      */
     @Test
-    public void pendingPageSetOnOneThreadShouldNotBeVisibleOnAnother() throws Exception {
-        Page page = new Page("page", "Page", "the/page");
-        NavigationManagerSession.getInstance().setPage(page, null);
+    public void pendingPageBoundInOneScopeShouldNotBeVisibleInAnotherConcurrentScope() throws Exception {
+        Page pageA = new Page("a", "A", "the/a");
+        Page pageB = new Page("b", "B", "the/b");
+        java.util.concurrent.CountDownLatch bothBound = new java.util.concurrent.CountDownLatch(2);
 
-        ExecutorService executor = Executors.newSingleThreadExecutor();
+        ExecutorService executor = Executors.newFixedThreadPool(2);
         try {
-            Future<Page> otherThreadPage = executor.submit(() -> NavigationManagerSession.getInstance().getPage());
-            assertNull(otherThreadPage.get(5, TimeUnit.SECONDS));
+            Future<Page> observedByA = executor.submit(() -> observeOwnPageAfterBothAreBound(pageA, bothBound));
+            Future<Page> observedByB = executor.submit(() -> observeOwnPageAfterBothAreBound(pageB, bothBound));
+
+            assertSame(pageA, observedByA.get(5, TimeUnit.SECONDS));
+            assertSame(pageB, observedByB.get(5, TimeUnit.SECONDS));
         } finally {
             executor.shutdownNow();
             assertTrue(executor.awaitTermination(5, TimeUnit.SECONDS));
         }
+    }
 
-        // still present on the original thread
-        assertSame(page, NavigationManagerSession.getInstance().getPage());
+    private Page observeOwnPageAfterBothAreBound(Page page, java.util.concurrent.CountDownLatch bothBound) {
+        Page[] observed = new Page[1];
+        inScope(() -> {
+            NavigationManagerSession.getInstance().setPage(page, null);
+            bothBound.countDown();
+            try {
+                bothBound.await(5, TimeUnit.SECONDS);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+            observed[0] = NavigationManagerSession.getInstance().getPage();
+        });
+        return observed[0];
     }
 }
diff --git a/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilter.java b/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilter.java
similarity index 52%
rename from platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilter.java
rename to platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilter.java
index e1ce4c1c..e31a7ec2 100644
--- a/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilter.java
+++ b/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilter.java
@@ -27,27 +27,34 @@
 import java.io.IOException;
 
 /**
- * Clears the thread-local {@link NavigationManagerSession} once a request finishes, so pooled
- * request-handling threads don't retain a stale navigation intent (page/params/queued callbacks)
- * across unrelated later requests.
+ * Binds a fresh {@link NavigationManagerSession} to the {@link ScopedValue} scope of the whole
+ * request, so a controller earlier in the chain (e.g. {@code PageNavigationController}/
+ * {@code PageEmbedController}) can stash a pending page/callback and the ZK desktop bootstrap
+ * later in the same request (reached via a server-side forward) can pick it up — see
+ * {@link NavigationManagerSession}'s Javadoc for the full contract.
  * <p>
- * {@link NavigationManagerSession} is populated and consumed within the same request/thread (a
- * controller sets a pending page, then a server-side forward into the ZK desktop's view consumes
- * it on that same thread) — see its Javadoc for the full contract. This filter only guarantees the
- * thread-local is removed afterward regardless of how the request completes.
+ * The binding is torn down automatically by {@link ScopedValue.Carrier#call} once the request
+ * finishes, whether normally or via an exception — no manual cleanup needed, and nothing leaks into
+ * a later, unrelated request even if the servlet container reuses this thread for it.
  *
  * @author Mario A. Serrano Leones
  */
 @Component
-public class NavigationManagerSessionCleanupFilter extends OncePerRequestFilter {
+public class NavigationManagerSessionScopeFilter extends OncePerRequestFilter {
 
     @Override
     protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
             throws ServletException, IOException {
         try {
-            filterChain.doFilter(request, response);
-        } finally {
-            NavigationManagerSession.clear();
+            ScopedValue.where(NavigationManagerSession.SCOPE, new NavigationManagerSession())
+                    .call(() -> {
+                        filterChain.doFilter(request, response);
+                        return null;
+                    });
+        } catch (ServletException | IOException | RuntimeException e) {
+            throw e;
+        } catch (Exception e) {
+            throw new ServletException(e);
         }
     }
 }
diff --git a/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilterTest.java b/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilterTest.java
deleted file mode 100644
index b05f9158..00000000
--- a/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionCleanupFilterTest.java
+++ /dev/null
@@ -1,90 +0,0 @@
-/*
- * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
- * Colombia / South America
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package tools.dynamia.web.navigation;
-
-import jakarta.servlet.ServletException;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.Test;
-import org.springframework.mock.web.MockFilterChain;
-import org.springframework.mock.web.MockHttpServletRequest;
-import org.springframework.mock.web.MockHttpServletResponse;
-import tools.dynamia.navigation.NavigationManagerSession;
-import tools.dynamia.navigation.Page;
-
-import java.io.IOException;
-
-import static org.junit.jupiter.api.Assertions.assertNull;
-import static org.junit.jupiter.api.Assertions.assertSame;
-import static org.junit.jupiter.api.Assertions.assertThrows;
-
-/**
- * Covers {@link NavigationManagerSessionCleanupFilter}: it must clear the thread-local
- * {@link NavigationManagerSession} after the request completes, including when the rest of the
- * chain throws, so pooled request-handling threads don't retain a stale navigation intent across
- * unrelated later requests.
- */
-public class NavigationManagerSessionCleanupFilterTest {
-
-    private final NavigationManagerSessionCleanupFilter filter = new NavigationManagerSessionCleanupFilter();
-
-    @AfterEach
-    public void cleanup() {
-        NavigationManagerSession.clear();
-    }
-
-    @Test
-    public void shouldClearSessionAfterSuccessfulChain() throws ServletException, IOException {
-        Page page = new Page("page", "Page", "the/page");
-        NavigationManagerSession.getInstance().setPage(page, null);
-
-        filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), new MockFilterChain());
-
-        assertNull(NavigationManagerSession.getInstance().getPage());
-    }
-
-    @Test
-    public void pendingPageShouldStillBeVisibleToTheChain() throws ServletException, IOException {
-        Page page = new Page("page", "Page", "the/page");
-        NavigationManagerSession.getInstance().setPage(page, null);
-
-        MockFilterChain chain = new MockFilterChain() {
-            @Override
-            public void doFilter(jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response) {
-                assertSame(page, NavigationManagerSession.getInstance().getPage());
-            }
-        };
-
-        filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), chain);
-    }
-
-    @Test
-    public void shouldClearSessionEvenWhenChainThrows() {
-        NavigationManagerSession.getInstance().setPage(new Page("page", "Page", "the/page"), null);
-
-        MockFilterChain failingChain = new MockFilterChain() {
-            @Override
-            public void doFilter(jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response) throws ServletException {
-                throw new ServletException("boom");
-            }
-        };
-
-        assertThrows(ServletException.class, () ->
-                filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), failingChain));
-
-        assertNull(NavigationManagerSession.getInstance().getPage());
-    }
-}
diff --git a/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilterTest.java b/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilterTest.java
new file mode 100644
index 00000000..1e62134c
--- /dev/null
+++ b/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilterTest.java
@@ -0,0 +1,144 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.web.navigation;
+
+import jakarta.servlet.ServletException;
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockFilterChain;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+import tools.dynamia.navigation.NavigationManagerSession;
+import tools.dynamia.navigation.Page;
+
+import java.io.IOException;
+import java.util.NoSuchElementException;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Covers {@link NavigationManagerSessionScopeFilter}: it must bind a fresh
+ * {@link NavigationManagerSession} for the dynamic extent of the request (so a controller can stash
+ * a pending page and a later forward can consume it), and that binding must be torn down once the
+ * request finishes — including when the chain throws — with no leakage into an unrelated request
+ * that happens to reuse the same thread. The concurrency test is the actual property motivating the
+ * whole redesign: two "requests" (e.g. two iframes bootstrapping at once) must not see each other's
+ * pending page.
+ */
+public class NavigationManagerSessionScopeFilterTest {
+
+    private final NavigationManagerSessionScopeFilter filter = new NavigationManagerSessionScopeFilter();
+
+    @Test
+    public void chainShouldSeeItsOwnPendingPage() throws ServletException, IOException {
+        Page page = new Page("page", "Page", "the/page");
+
+        MockFilterChain chain = new MockFilterChain() {
+            @Override
+            public void doFilter(jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response) {
+                NavigationManagerSession.getInstance().setPage(page, null);
+                assertSame(page, NavigationManagerSession.getInstance().getPage());
+            }
+        };
+
+        filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), chain);
+    }
+
+    @Test
+    public void noScopeShouldBeBoundBeforeTheFilterRuns() {
+        assertThrows(NoSuchElementException.class, NavigationManagerSession::getInstance);
+    }
+
+    @Test
+    public void scopeShouldNotBeVisibleAfterFilterReturns() throws ServletException, IOException {
+        filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), new MockFilterChain());
+
+        assertThrows(NoSuchElementException.class, NavigationManagerSession::getInstance);
+    }
+
+    @Test
+    public void scopeShouldBeTornDownEvenWhenChainThrows() {
+        MockFilterChain failingChain = new MockFilterChain() {
+            @Override
+            public void doFilter(jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response) throws ServletException {
+                NavigationManagerSession.getInstance().setPage(new Page("page", "Page", "the/page"), null);
+                throw new ServletException("boom");
+            }
+        };
+
+        assertThrows(ServletException.class, () ->
+                filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), failingChain));
+
+        assertThrows(NoSuchElementException.class, NavigationManagerSession::getInstance);
+    }
+
+    /**
+     * Simulates two ZK desktops (e.g. two {@code <iframe>}s) bootstrapping concurrently through the
+     * same filter instance, each on its own thread: each must only ever see its own pending page,
+     * never the other's.
+     */
+    @Test
+    public void concurrentRequestsShouldGetIsolatedSessions() throws Exception {
+        Page pageA = new Page("a", "A", "the/a");
+        Page pageB = new Page("b", "B", "the/b");
+        CountDownLatch bothSetTheirPage = new CountDownLatch(2);
+
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        try {
+            Future<Page> futureA = executor.submit(() -> runThroughFilter(pageA, bothSetTheirPage));
+            Future<Page> futureB = executor.submit(() -> runThroughFilter(pageB, bothSetTheirPage));
+
+            assertSame(pageA, futureA.get(5, TimeUnit.SECONDS));
+            assertSame(pageB, futureB.get(5, TimeUnit.SECONDS));
+        } finally {
+            executor.shutdownNow();
+            assertTrue(executor.awaitTermination(5, TimeUnit.SECONDS));
+        }
+    }
+
+    private Page runThroughFilter(Page page, CountDownLatch bothSetTheirPage) throws ServletException, IOException {
+        AtomicReference<Page> observed = new AtomicReference<>();
+        MockFilterChain chain = new MockFilterChain() {
+            @Override
+            public void doFilter(jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response) throws ServletException {
+                NavigationManagerSession.getInstance().setPage(page, null);
+                bothSetTheirPage.countDown();
+                try {
+                    // wait until both threads have set their own page before reading back, so a
+                    // shared/leaky binding would actually have a chance to show the wrong page
+                    if (!bothSetTheirPage.await(5, TimeUnit.SECONDS)) {
+                        throw new ServletException("timed out waiting for the other request");
+                    }
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    throw new ServletException(e);
+                }
+                observed.set(NavigationManagerSession.getInstance().getPage());
+            }
+        };
+
+        filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), chain);
+        return observed.get();
+    }
+}

From 812b3a1560082019e8a1c52b2b706eb004cb8aa9 Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Tue, 29 Sep 2026 22:59:29 -0500
Subject: [PATCH 5/6] feat(navigation): hand off unconsumed navigation intent
 across requests

With NavigationManagerSession bound per request (ScopedValue), an intent
recorded right before an HTTP redirect (e.g. a LoginListener calling
setPageLater/runLater, or a ZK command doing setPageLater + sendRedirect)
was lost when the scope ended.

NavigationManagerSessionScopeFilter now parks any still-pending intent in
the HTTP session at the end of the request and restores it into the next
request's instance, where the first desktop bootstrap consumes it. The
parked state is transient (queued callbacks are not serializable) and
never shared across sessions.

- Filter is ordered before the Spring Security chain (@Order
  HIGHEST_PRECEDENCE + 10) so the scope is already bound when login
  listeners run on AuthenticationSuccessEvent.
- NavigationManagerSession: hasPendingState(), absorb(other) and an
  onPending hook. The hook makes the filter create the HTTP session when
  the intent is recorded, before a redirect commits the response (found
  with the demo app: a first request with no session lost the intent).
- Javadoc of NavigationManager.setPageLater no longer forbids redirects.

Refs #107, #108

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GXVz2G6v1fqFdQjRSh9XZF
---
 .../dynamia/navigation/NavigationManager.java |  7 +-
 .../navigation/NavigationManagerSession.java  | 63 ++++++++++++
 .../NavigationManagerSessionTest.java         | 39 ++++++++
 .../NavigationManagerSessionScopeFilter.java  | 83 +++++++++++++++-
 ...vigationManagerSessionScopeFilterTest.java | 97 +++++++++++++++++++
 5 files changed, 285 insertions(+), 4 deletions(-)

diff --git a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
index 37031940..abe7b936 100644
--- a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
+++ b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManager.java
@@ -110,9 +110,10 @@ static NavigationManager getCurrent() {
      * {@link NavigationManagerSession} is a {@link ScopedValue}: this must be called within the same
      * scope that will forward into the target ZK desktop (e.g. from a controller rendering an
      * {@code index}/{@code embed} ZUL view via a server-side forward, with the scope established by
-     * a request-lifecycle filter around the whole request), never before an HTTP redirect — a
-     * redirect is a new request, possibly with no scope bound at all, so the value would not be
-     * picked up. Throws {@link java.util.NoSuchElementException} if no scope is currently bound.
+     * a request-lifecycle filter around the whole request). If the request ends (e.g. with an HTTP
+     * redirect) before any desktop consumed the value, the filter hands it off through the HTTP
+     * session to the next request. Throws {@link java.util.NoSuchElementException} if no scope is
+     * currently bound.
      *
      * @param page
      */
diff --git a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java
index 96a5a79a..3e273ad8 100644
--- a/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java
+++ b/platform/core/navigation/src/main/java/tools/dynamia/navigation/NavigationManagerSession.java
@@ -21,6 +21,12 @@
  * {@code NavigationManagerSessionScopeFilter}).
  * </p>
  * <p>
+ * A redirect starts a new request, so an intent recorded right before one (e.g. by a login listener)
+ * would be lost with the scope. The filter therefore carries any still-pending intent across
+ * requests through the HTTP session ({@link #hasPendingState()}/{@link #absorb(NavigationManagerSession)}):
+ * it is restored into the next request's instance and consumed by the first desktop that bootstraps.
+ * </p>
+ * <p>
  * {@link #getInstance()} throws {@link java.util.NoSuchElementException} if called outside that
  * scope — e.g. a background job, or test code that hasn't bound one itself via
  * {@code ScopedValue.where(NavigationManagerSession.SCOPE, new NavigationManagerSession()).run(...)}.
@@ -54,6 +60,26 @@ public class NavigationManagerSession implements Serializable {
 
     private Queue<Callback> runLaterQueue = new LinkedList<>();
 
+    private transient Runnable onPending;
+
+    /**
+     * Registers a hook invoked every time an intent is recorded ({@link #setPage(Page, Map)} or
+     * {@link #runLater(Callback)}). The request-lifecycle filter uses it to make sure an HTTP session
+     * exists <i>before</i> the response may be committed (e.g. by a redirect), because that session is
+     * where an unconsumed intent is parked for the next request.
+     *
+     * @param onPending the hook, or null to clear it
+     */
+    public void setOnPending(Runnable onPending) {
+        this.onPending = onPending;
+    }
+
+    private void notifyPending() {
+        if (onPending != null) {
+            onPending.run();
+        }
+    }
+
     /**
      * Returns the instance bound to the current scope.
      *
@@ -66,6 +92,7 @@ public static NavigationManagerSession getInstance() {
     public void setPage(Page page, Map<String, Serializable> params) {
         this.page = page;
         this.pageParams = params;
+        notifyPending();
     }
 
     public void updateNavManager(NavigationManager navigationManager) {
@@ -81,6 +108,7 @@ public void runLater(Callback callback) {
             runLaterQueue = new LinkedList<>();
         }
         runLaterQueue.add(callback);
+        notifyPending();
     }
 
     public void executeQueue() {
@@ -92,6 +120,41 @@ public void executeQueue() {
         }
     }
 
+    /**
+     * Tells whether this instance still holds a navigation intent nobody has consumed: a pending
+     * {@link Page} (not yet handed to a {@link NavigationManager} via {@link #updateNavManager}) or
+     * queued {@link Callback}s (not yet run via {@link #executeQueue()}).
+     *
+     * @return true if there is a pending page or at least one queued callback
+     */
+    public boolean hasPendingState() {
+        return page != null || (runLaterQueue != null && !runLaterQueue.isEmpty());
+    }
+
+    /**
+     * Moves the pending intent of {@code other} into this instance, leaving {@code other} empty.
+     * Used by the request-lifecycle filter to carry an unconsumed intent across requests (e.g. a
+     * login that queues a page and then redirects). A pending page in {@code other} replaces the one
+     * held here; its queued callbacks are appended after the ones already queued.
+     *
+     * @param other the instance to drain; ignored if null or the same instance
+     */
+    public void absorb(NavigationManagerSession other) {
+        if (other == null || other == this) {
+            return;
+        }
+        if (other.page != null) {
+            this.page = other.page;
+            this.pageParams = other.pageParams;
+            other.page = null;
+            other.pageParams = null;
+        }
+        if (other.runLaterQueue != null) {
+            other.runLaterQueue.forEach(this::runLater);
+            other.runLaterQueue.clear();
+        }
+    }
+
     public Page getPage() {
         return page;
     }
diff --git a/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java b/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java
index c5fe2865..e52d1dc0 100644
--- a/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java
+++ b/platform/core/navigation/src/test/java/tools/dynamia/navigation/NavigationManagerSessionTest.java
@@ -116,6 +116,45 @@ public void executeQueueShouldDrainTheQueue() {
         });
     }
 
+    @Test
+    public void hasPendingStateShouldReflectPageAndQueue() {
+        inScope(() -> {
+            var session = NavigationManagerSession.getInstance();
+            assertTrue(!session.hasPendingState());
+
+            session.runLater(() -> {
+            });
+            assertTrue(session.hasPendingState());
+            session.executeQueue();
+            assertTrue(!session.hasPendingState());
+
+            session.setPage(new Page("page", "Page", "the/page"), null);
+            assertTrue(session.hasPendingState());
+        });
+    }
+
+    @Test
+    public void absorbShouldMoveThePageAndAppendTheQueue() {
+        List<Integer> executed = new ArrayList<>();
+        Page page = new Page("page", "Page", "the/page");
+        Map<String, java.io.Serializable> params = new HashMap<>();
+        params.put("k", "v");
+
+        var source = new NavigationManagerSession();
+        source.setPage(page, params);
+        source.runLater(() -> executed.add(2));
+
+        var target = new NavigationManagerSession();
+        target.runLater(() -> executed.add(1));
+        target.absorb(source);
+        target.executeQueue();
+
+        assertSame(page, target.getPage());
+        assertEquals(params, target.getPageParams());
+        assertEquals(List.of(1, 2), executed);
+        assertTrue(!source.hasPendingState());
+    }
+
     @Test
     public void scopeShouldNotLeakOutsideItsDynamicExtent() {
         inScope(() -> NavigationManagerSession.getInstance().setPage(new Page("page", "Page", "the/page"), null));
diff --git a/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilter.java b/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilter.java
index e31a7ec2..4d2fcaac 100644
--- a/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilter.java
+++ b/platform/core/web/src/main/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilter.java
@@ -20,11 +20,18 @@
 import jakarta.servlet.ServletException;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
+import jakarta.servlet.http.HttpSession;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
 import org.springframework.web.filter.OncePerRequestFilter;
+import org.springframework.web.util.WebUtils;
+import tools.dynamia.commons.logger.LoggingService;
+import tools.dynamia.commons.logger.SLF4JLoggingService;
 import tools.dynamia.integration.sterotypes.Component;
 import tools.dynamia.navigation.NavigationManagerSession;
 
 import java.io.IOException;
+import java.io.Serializable;
 
 /**
  * Binds a fresh {@link NavigationManagerSession} to the {@link ScopedValue} scope of the whole
@@ -36,17 +43,36 @@
  * The binding is torn down automatically by {@link ScopedValue.Carrier#call} once the request
  * finishes, whether normally or via an exception — no manual cleanup needed, and nothing leaks into
  * a later, unrelated request even if the servlet container reuses this thread for it.
+ * <p>
+ * <b>Hand-off across requests.</b> Some callers record a navigation intent and then end the request
+ * without forwarding into a desktop — typically a login listener followed by an HTTP redirect, or a
+ * ZK event that calls {@code sendRedirect}. If the instance still has a pending intent when the
+ * request ends, it is parked in the HTTP session and restored into the next request's instance, so
+ * the first desktop that bootstraps consumes it. Parked state is never shared between sessions, and
+ * it is not persisted with the session (queued callbacks are not serializable).
+ * <p>
+ * <b>Ordering.</b> Registered with the highest precedence so the scope is already bound when Spring
+ * Security authenticates the user and fires its login listeners, which run before the rest of the
+ * chain.
  *
  * @author Mario A. Serrano Leones
  */
 @Component
+@Order(Ordered.HIGHEST_PRECEDENCE + 10)
 public class NavigationManagerSessionScopeFilter extends OncePerRequestFilter {
 
+    static final String HAND_OFF_ATTRIBUTE = NavigationManagerSessionScopeFilter.class.getName() + ".HAND_OFF";
+
+    private static final LoggingService LOGGER = new SLF4JLoggingService(NavigationManagerSessionScopeFilter.class);
+
     @Override
     protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
             throws ServletException, IOException {
+        var current = new NavigationManagerSession();
+        current.setOnPending(() -> ensureSession(request));
+        restoreParkedState(request, current);
         try {
-            ScopedValue.where(NavigationManagerSession.SCOPE, new NavigationManagerSession())
+            ScopedValue.where(NavigationManagerSession.SCOPE, current)
                     .call(() -> {
                         filterChain.doFilter(request, response);
                         return null;
@@ -55,6 +81,61 @@ protected void doFilterInternal(HttpServletRequest request, HttpServletResponse
             throw e;
         } catch (Exception e) {
             throw new ServletException(e);
+        } finally {
+            parkPendingState(request, current);
+        }
+    }
+
+    private void ensureSession(HttpServletRequest request) {
+        try {
+            request.getSession(true);
+        } catch (IllegalStateException e) {
+            LOGGER.warn("Cannot create HTTP session to hand off navigation state: " + e.getMessage());
+        }
+    }
+
+    private void restoreParkedState(HttpServletRequest request, NavigationManagerSession target) {
+        HttpSession session = request.getSession(false);
+        if (session == null) {
+            return;
+        }
+        synchronized (WebUtils.getSessionMutex(session)) {
+            if (session.getAttribute(HAND_OFF_ATTRIBUTE) instanceof HandOff handOff) {
+                session.removeAttribute(HAND_OFF_ATTRIBUTE);
+                target.absorb(handOff.state());
+            }
+        }
+    }
+
+    private void parkPendingState(HttpServletRequest request, NavigationManagerSession current) {
+        if (!current.hasPendingState()) {
+            return;
+        }
+        try {
+            HttpSession session = request.getSession(true);
+            synchronized (WebUtils.getSessionMutex(session)) {
+                HandOff handOff = session.getAttribute(HAND_OFF_ATTRIBUTE) instanceof HandOff existing ? existing : new HandOff();
+                handOff.state().absorb(current);
+                session.setAttribute(HAND_OFF_ATTRIBUTE, handOff);
+            }
+        } catch (IllegalStateException e) {
+            LOGGER.warn("Pending navigation state dropped: no HTTP session available at end of request (" + e.getMessage() + ")");
+        }
+    }
+
+    /**
+     * Session attribute holding the parked intent. The state is {@code transient}: queued callbacks
+     * are not serializable, so after a session passivation the parked intent is simply gone.
+     */
+    private static final class HandOff implements Serializable {
+        private static final long serialVersionUID = 1L;
+        private transient NavigationManagerSession state;
+
+        NavigationManagerSession state() {
+            if (state == null) {
+                state = new NavigationManagerSession();
+            }
+            return state;
         }
     }
 }
diff --git a/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilterTest.java b/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilterTest.java
index 1e62134c..e39b84e9 100644
--- a/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilterTest.java
+++ b/platform/core/web/src/test/java/tools/dynamia/web/navigation/NavigationManagerSessionScopeFilterTest.java
@@ -21,10 +21,13 @@
 import org.springframework.mock.web.MockFilterChain;
 import org.springframework.mock.web.MockHttpServletRequest;
 import org.springframework.mock.web.MockHttpServletResponse;
+import org.springframework.mock.web.MockHttpSession;
 import tools.dynamia.navigation.NavigationManagerSession;
 import tools.dynamia.navigation.Page;
 
 import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
 import java.util.NoSuchElementException;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.ExecutorService;
@@ -33,6 +36,9 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicReference;
 
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -141,4 +147,95 @@ public void doFilter(jakarta.servlet.ServletRequest request, jakarta.servlet.Ser
         filter.doFilter(new MockHttpServletRequest(), new MockHttpServletResponse(), chain);
         return observed.get();
     }
+
+    /** A login-style flow: intent recorded, request ends (redirect) without any desktop consuming it. */
+    @Test
+    public void unconsumedIntentShouldBeHandedOffToTheNextRequestOfTheSameSession() throws ServletException, IOException {
+        var session = new MockHttpSession();
+        Page page = new Page("page", "Page", "the/page");
+        List<String> ran = new ArrayList<>();
+
+        runRequest(session, () -> {
+            NavigationManagerSession.getInstance().setPage(page, null);
+            NavigationManagerSession.getInstance().runLater(() -> ran.add("cb"));
+        });
+
+        AtomicReference<Page> restored = new AtomicReference<>();
+        runRequest(session, () -> {
+            restored.set(NavigationManagerSession.getInstance().getPage());
+            // a desktop bootstrap consumes it
+            NavigationManagerSession.getInstance().updateNavManager(noOpNavigationManager());
+            NavigationManagerSession.getInstance().executeQueue();
+        });
+        assertSame(page, restored.get());
+        assertEquals(List.of("cb"), ran);
+
+        AtomicReference<Page> third = new AtomicReference<>();
+        runRequest(session, () -> third.set(NavigationManagerSession.getInstance().getPage()));
+        assertNull(third.get(), "an intent consumed by a desktop must not be handed off again");
+    }
+
+
+    /** First contact of a browser (no session yet): intent recorded, then a redirect commits the response. */
+    @Test
+    public void intentShouldSurviveRedirectWhenRequestHadNoSessionYet() throws ServletException, IOException {
+        Page page = new Page("page", "Page", "the/page");
+        var firstRequest = new MockHttpServletRequest();
+        var firstResponse = new MockHttpServletResponse() {
+            @Override
+            public void sendRedirect(String location) throws IOException {
+                super.sendRedirect(location);
+                setCommitted(true);
+            }
+        };
+
+        filter.doFilter(firstRequest, firstResponse, new MockFilterChain() {
+            @Override
+            public void doFilter(jakarta.servlet.ServletRequest req, jakarta.servlet.ServletResponse res) throws IOException {
+                NavigationManagerSession.getInstance().setPage(page, null);
+                ((jakarta.servlet.http.HttpServletResponse) res).sendRedirect("/next");
+            }
+        });
+
+        var session = firstRequest.getSession(false);
+        assertNotNull(session, "a session must be created before the redirect commits the response");
+
+        AtomicReference<Page> restored = new AtomicReference<>();
+        runRequest((MockHttpSession) session, () -> restored.set(NavigationManagerSession.getInstance().getPage()));
+        assertSame(page, restored.get());
+    }
+    @Test
+    public void intentShouldNotLeakToAnotherSession() throws ServletException, IOException {
+        runRequest(new MockHttpSession(), () ->
+                NavigationManagerSession.getInstance().setPage(new Page("page", "Page", "the/page"), null));
+
+        AtomicReference<Page> other = new AtomicReference<>();
+        runRequest(new MockHttpSession(), () -> other.set(NavigationManagerSession.getInstance().getPage()));
+        assertNull(other.get());
+    }
+
+    @Test
+    public void filterShouldRunBeforeSpringSecurity() {
+        var order = NavigationManagerSessionScopeFilter.class.getAnnotation(org.springframework.core.annotation.Order.class);
+        assertNotNull(order);
+        assertTrue(order.value() < -100, "must precede the Spring Security filter chain (order -100)");
+    }
+
+    private void runRequest(MockHttpSession session, Runnable body) throws ServletException, IOException {
+        var request = new MockHttpServletRequest();
+        request.setSession(session);
+        filter.doFilter(request, new MockHttpServletResponse(), new MockFilterChain() {
+            @Override
+            public void doFilter(jakarta.servlet.ServletRequest req, jakarta.servlet.ServletResponse res) {
+                body.run();
+            }
+        });
+    }
+
+    private static tools.dynamia.navigation.NavigationManager noOpNavigationManager() {
+        return (tools.dynamia.navigation.NavigationManager) java.lang.reflect.Proxy.newProxyInstance(
+                NavigationManagerSessionScopeFilterTest.class.getClassLoader(),
+                new Class<?>[]{tools.dynamia.navigation.NavigationManager.class},
+                (proxy, method, args) -> method.getReturnType() == boolean.class ? Boolean.TRUE : null);
+    }
 }

From 7809c5c8159461e3b748bc0422487c689e147245 Mon Sep 17 00:00:00 2001
From: Mario Serrano <mario@dynamiasoluciones.com>
Date: Tue, 29 Sep 2026 22:59:29 -0500
Subject: [PATCH 6/6] docs(demo-zk-books): add navigation hand-off demo
 endpoints

Real-world cases for verifying NavigationManagerSession and its filter:
a filter at Spring Security's order that records setPageLater/runLater
and redirects (simulated login), a controller doing the same, a bare
desktop that only shows what was handed off, and a callbacks counter.
Endpoints live under /demo/handoff/*.

Refs #107, #108

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GXVz2G6v1fqFdQjRSh9XZF
---
 .../handoff/HandOffDemoController.java        | 45 +++++++++++++++++++
 .../handoff/HandOffDemoLoginFilter.java       | 39 ++++++++++++++++
 .../mybookstore/handoff/HandOffDemoState.java | 15 +++++++
 3 files changed, 99 insertions(+)
 create mode 100644 examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoController.java
 create mode 100644 examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoLoginFilter.java
 create mode 100644 examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoState.java

diff --git a/examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoController.java b/examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoController.java
new file mode 100644
index 00000000..ee0c10d9
--- /dev/null
+++ b/examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoController.java
@@ -0,0 +1,45 @@
+package mybookstore.handoff;
+
+import jakarta.servlet.http.HttpServletResponse;
+import org.springframework.http.MediaType;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.ResponseBody;
+import org.springframework.web.servlet.ModelAndView;
+import tools.dynamia.navigation.NavigationManager;
+
+import java.io.IOException;
+
+/**
+ * Real-world navigation hand-off cases for manual/automated verification of
+ * {@code NavigationManagerSession} and its request-scope filter:
+ * <ul>
+ *   <li>{@code /demo/handoff/redirect} — records a page + callback, then redirects (like a ZK command
+ *   that calls {@code setPageLater} and {@code sendRedirect}). The target desktop must open Invoices (not the default page).</li>
+ *   <li>{@code /demo/handoff/desktop} — builds a ZK desktop <i>without</i> choosing a page itself, so it
+ *   can only show what was handed off by a previous request (or the default page if nothing was).</li>
+ *   <li>{@code /demo/handoff/login} — see {@link HandOffDemoLoginFilter}.</li>
+ *   <li>{@code /demo/handoff/status} — how many queued callbacks have run.</li>
+ * </ul>
+ */
+@Controller
+public class HandOffDemoController {
+
+    @GetMapping("/demo/handoff/redirect")
+    public void redirect(HttpServletResponse response) throws IOException {
+        NavigationManager.setPageLater("library/invoices");
+        NavigationManager.runLater(HandOffDemoState.CALLBACKS_RUN::incrementAndGet);
+        response.sendRedirect("/demo/handoff/desktop");
+    }
+
+    @GetMapping("/demo/handoff/desktop")
+    public ModelAndView desktop() {
+        return new ModelAndView("embed");
+    }
+
+    @GetMapping(value = "/demo/handoff/status", produces = MediaType.APPLICATION_JSON_VALUE)
+    @ResponseBody
+    public String status() {
+        return "{\"callbacksRun\":" + HandOffDemoState.CALLBACKS_RUN.get() + "}";
+    }
+}
diff --git a/examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoLoginFilter.java b/examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoLoginFilter.java
new file mode 100644
index 00000000..4d9e6827
--- /dev/null
+++ b/examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoLoginFilter.java
@@ -0,0 +1,39 @@
+package mybookstore.handoff;
+
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+import tools.dynamia.navigation.NavigationManager;
+
+import java.io.IOException;
+
+/**
+ * Simulates what a real login does in an app that uses Spring Security: a listener reacting to the
+ * authentication success ({@code LoginListener.onLoginSuccess}) calls {@code setPageLater}/{@code runLater}
+ * <b>inside the security filter chain</b> (order -100, before any controller) and the request ends with an
+ * HTTP redirect. Both things must work: the navigation scope must already be bound at that point, and the
+ * pending intent must survive the redirect.
+ * <p>
+ * Try: {@code GET /demo/handoff/login} (redirects to {@code /demo/handoff/desktop}, which must open Customers).
+ */
+@Component
+@Order(-100)
+public class HandOffDemoLoginFilter extends OncePerRequestFilter {
+
+    @Override
+    protected boolean shouldNotFilter(HttpServletRequest request) {
+        return !"/demo/handoff/login".equals(request.getRequestURI());
+    }
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
+            throws ServletException, IOException {
+        NavigationManager.setPageLater("library/customers");
+        NavigationManager.runLater(HandOffDemoState.CALLBACKS_RUN::incrementAndGet);
+        response.sendRedirect("/demo/handoff/desktop");
+    }
+}
diff --git a/examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoState.java b/examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoState.java
new file mode 100644
index 00000000..daffc42a
--- /dev/null
+++ b/examples/demo-zk-books/src/main/java/mybookstore/handoff/HandOffDemoState.java
@@ -0,0 +1,15 @@
+package mybookstore.handoff;
+
+import java.util.concurrent.atomic.AtomicInteger;
+
+/**
+ * Counts how many {@code NavigationManager.runLater} callbacks queued by the hand-off demo endpoints
+ * actually ran, so the flow can be verified from the outside (see {@link HandOffDemoController}).
+ */
+final class HandOffDemoState {
+
+    static final AtomicInteger CALLBACKS_RUN = new AtomicInteger();
+
+    private HandOffDemoState() {
+    }
+}