@noego/wood 0.4.10 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/wood",
-  "version": "0.4.10",
+  "version": "0.5.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -125,20 +125,22 @@
     "prepublishOnly": "npm run build && npm run typecheck && npm test"
   },
   "dependencies": {
-    "@noego/ioc": "^0.3.1",
-    "@noego/logger": "^0.0.4",
+    "@noego/ioc": "^0.7.0",
+    "@noego/logger": "^0.2.0",
     "@noego/stitch": "^1.0.3",
-    "@noego/telemetry": "^0.0.1",
-    "@noego/trace": "^0.0.6",
+    "@noego/telemetry": "^0.1.0",
+    "@noego/trace": "^0.2.0",
     "ajv": "^8.x",
     "ajv-formats": "^3.x",
     "chokidar": "^4.x",
     "glob": "^11.x",
     "js-yaml": "^4.x",
     "path-to-regexp": "^8.x",
+    "reflect-metadata": "^0.2.2",
     "rxjs": "^7.x"
   },
   "peerDependencies": {
+    "@noego/testing": ">=0.5.0",
     "@sveltejs/vite-plugin-svelte": "^4.0.0",
     "electron": ">=28.0.0",
     "playwright": "^1.40.0",
@@ -150,12 +152,18 @@
     },
     "playwright": {
       "optional": true
+    },
+    "@noego/testing": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@noego/testing": "^0.5.0",
     "@sveltejs/vite-plugin-svelte": "^4.0.4",
+    "@types/better-sqlite3": "^9.6.0",
     "@types/js-yaml": "^4.x",
     "@types/node": "^20.10.4",
+    "better-sqlite3": "^12.11.1",
     "electron-builder": "^25.x",
     "electron-vite": "^2.x",
     "esbuild": "^0.25.x",

package/src/components/NavigationShell.scopes.browser.test.ts

@@ -0,0 +1,363 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, test } from 'vitest';
+import { browser } from '../testing/browser';
+
+type ScopeReproSnapshot = {
+  scopeDisposeCounts: Record<string, number>;
+  controllerDisposeCounts: Record<string, number>;
+  setCreateCalls: string[];
+  createdIds: string[];
+  rendered: string;
+  pageErrors: string[];
+};
+
+describe('NavigationShell renderer scope ownership', () => {
+  const harnesses: Array<{ destroy(): Promise<void> }> = [];
+  const tempRoots: string[] = [];
+
+  afterEach(async () => {
+    while (harnesses.length > 0) {
+      await harnesses.pop()?.destroy();
+    }
+    while (tempRoots.length > 0) {
+      rmSync(tempRoots.pop()!, { recursive: true, force: true });
+    }
+  });
+
+  test(
+    'disposes page scopes, preserves layout scopes, and retains borrowed page scopes across transitions',
+    async () => {
+      const woodRoot = path.resolve(__dirname, '../..');
+      const rootDir = mkdtempSync(path.join(os.tmpdir(), 'wood-navigation-shell-scopes-repro-'));
+      tempRoots.push(rootDir);
+      mkdirSync(path.join(rootDir, 'ui'), { recursive: true });
+
+      writeFileSync(
+        path.join(rootDir, 'ui', 'ReproView.svelte'),
+        `<script lang="ts">
+          let { data = {} } = $props<{ data?: { id?: string } }>();
+        </script>
+
+        <main data-repro-view>controller={data.id ?? 'missing'}</main>`,
+      );
+
+      writeFileSync(
+        path.join(rootDir, 'ui', 'ReproLayout.svelte'),
+        `<script lang="ts">
+          import type { Snippet } from 'svelte';
+          let { children }: { children: Snippet } = $props();
+        </script>
+
+        <section data-repro-layout>{@render children()}</section>`,
+      );
+
+      writeFileSync(
+        path.join(rootDir, 'ui', 'NavigationShellScopesRepro.svelte'),
+        `<script lang="ts">
+          import '/@fs/${woodRoot}/src/client/global_polyfill.ts';
+          import NavigationShell from '/@fs/${woodRoot}/src/components/NavigationShell.svelte';
+          import { getNavigation } from '/@fs/${woodRoot}/src/navigation/index.ts';
+          import ReproLayout from './ReproLayout.svelte';
+          import ReproView from './ReproView.svelte';
+
+          type ScopeReproState = {
+            scopeDisposeCounts: Record<string, number>;
+            controllerDisposeCounts: Record<string, number>;
+            setCreateCalls: string[];
+            createdIds: string[];
+          };
+
+          const state: ScopeReproState = {
+            scopeDisposeCounts: {},
+            controllerDisposeCounts: {},
+            setCreateCalls: [],
+            createdIds: [],
+          };
+          (window as unknown as { __WOOD_SCOPE_REPRO__: ScopeReproState })
+            .__WOOD_SCOPE_REPRO__ = state;
+
+          function makeScope(id: string) {
+            state.scopeDisposeCounts[id] = 0;
+            state.createdIds.push(id);
+            return {
+              id,
+              disposed: false,
+              async dispose() {
+                this.disposed = true;
+                state.scopeDisposeCounts[id] += 1;
+              },
+            };
+          }
+
+          function makeController(id: string) {
+            state.controllerDisposeCounts[id] = 0;
+            state.createdIds.push(id);
+            return {
+              data: { id },
+              async dispose() {
+                state.controllerDisposeCounts[id] += 1;
+              },
+            };
+          }
+
+          function makeEntry(
+            pageName: string,
+            layoutControllerName: string | null,
+            preserve: boolean,
+          ) {
+            return {
+              key: \`main.\${pageName}\`,
+              windowName: 'main',
+              pageName,
+              layoutPaths: layoutControllerName ? ['ui/ReproLayout.svelte'] : [],
+              layoutControllers: layoutControllerName ? [layoutControllerName] : [],
+              layoutPreserve: layoutControllerName ? [preserve] : [],
+              view: ReproView,
+              layouts: layoutControllerName ? [ReproLayout] : [],
+            };
+          }
+
+          // A/B share a preservable layout L1; C has no layouts; D/E share a
+          // NON-preservable layout L2 (page-scope owned); F has no layouts.
+          const entries = [
+            makeEntry('A', 'L1', true),
+            makeEntry('B', 'L1', true),
+            makeEntry('C', null, false),
+            makeEntry('D', 'L2', false),
+            makeEntry('E', 'L2', false),
+            makeEntry('F', null, false),
+          ];
+          const manifest = Object.fromEntries(entries.map((entry) => [entry.key, entry]));
+
+          // Mirrors the generated createControllerSet factory in
+          // src/codegen/renderer_app_generator.ts: one page scope per set, a
+          // dedicated scope per preservable layout, null (page-scope owned)
+          // otherwise, and undefined/null placeholders below preservedDepth.
+          function buildControllerSet(entry: any, preservedDepth = 0) {
+            state.setCreateCalls.push(\`\${entry.pageName}:\${preservedDepth}\`);
+            const pageScope = makeScope(\`scope:\${entry.pageName}\`);
+            const layoutControllers: unknown[] = [];
+            const layoutScopes: Array<unknown> = [];
+            for (let i = 0; i < preservedDepth; i += 1) {
+              layoutControllers.push(undefined);
+              layoutScopes.push(null);
+            }
+            for (let i = preservedDepth; i < entry.layoutControllers.length; i += 1) {
+              const name = entry.layoutControllers[i];
+              const preservable = entry.layoutPreserve?.[i] === true;
+              layoutControllers.push(makeController(\`ctrl:\${name}\`));
+              layoutScopes.push(preservable ? makeScope(\`scope:\${name}\`) : null);
+            }
+            const controller = makeController(\`ctrl:\${entry.pageName}\`);
+            return { controller, layoutControllers, pageScope, layoutScopes };
+          }
+
+          const initialControllerSet = buildControllerSet(entries[0], 0);
+
+          async function createControllerSetFn(entry: any, preservedDepth = 0) {
+            return buildControllerSet(entry, preservedDepth);
+          }
+
+          function getViewManifestEntryFn(viewKey: string) {
+            return manifest[viewKey as keyof typeof manifest] ?? null;
+          }
+
+          const navigation = getNavigation();
+          navigation.replace(entries[0].key, {}, {});
+          (window as unknown as {
+            __WOOD_SCOPE_REPRO_GO__: (pageName: string, options?: Record<string, unknown>) => void;
+          }).__WOOD_SCOPE_REPRO_GO__ = (pageName: string, options?: Record<string, unknown>) => {
+            navigation.go(\`main.\${pageName}\`, {}, {}, options ?? {});
+          };
+        </script>
+
+        <NavigationShell
+          {manifest}
+          initialEntry={entries[0]}
+          {initialControllerSet}
+          {createControllerSetFn}
+          {getViewManifestEntryFn}
+        />`,
+      );
+
+      const pageErrors: string[] = [];
+      const consoleErrors: string[] = [];
+      const harness = await browser.createHarness({
+        rootDir: woodRoot,
+        browser: { headless: true },
+        page: {
+          beforeMount({ page }) {
+            page.on('pageerror', (error: Error) => pageErrors.push(error.message));
+            page.on('console', (message: { type(): string; text(): string }) => {
+              if (message.type() === 'error') consoleErrors.push(message.text());
+            });
+          },
+        },
+      });
+      harnesses.push(harness);
+      const mounted = await harness.mountComponent(
+        path.join(rootDir, 'ui', 'NavigationShellScopesRepro.svelte'),
+      );
+      await mounted.locator('[data-repro-view]').waitFor({ state: 'visible', timeout: 5_000 }).catch(
+        async (error: unknown) => {
+          throw new Error(
+            `${error instanceof Error ? error.message : String(error)}\n` +
+            `Page errors: ${pageErrors.join(' | ')}\n` +
+            `Console errors: ${consoleErrors.join(' | ')}\n` +
+            `HTML: ${await mounted.page.content()}`,
+          );
+        },
+      );
+
+      const go = async (pageName: string, options?: Record<string, unknown>) => {
+        await mounted.page.evaluate(
+          ({ pageName, options }: { pageName: string; options?: Record<string, unknown> }) => {
+            (window as unknown as {
+              __WOOD_SCOPE_REPRO_GO__: (pageName: string, options?: Record<string, unknown>) => void;
+            }).__WOOD_SCOPE_REPRO_GO__(pageName, options);
+          },
+          { pageName, options },
+        );
+      };
+
+      const renderedController = async () =>
+        (await mounted.locator('[data-repro-view]').textContent())?.replace(/\s+/g, ' ').trim();
+
+      const snapshot = async (): Promise<ScopeReproSnapshot> => {
+        const result = await mounted.evaluate<Omit<ScopeReproSnapshot, 'rendered' | 'pageErrors'> & { rendered: string }>(() => {
+          const state = (window as unknown as {
+            __WOOD_SCOPE_REPRO__: Omit<ScopeReproSnapshot, 'rendered' | 'pageErrors'>;
+          }).__WOOD_SCOPE_REPRO__;
+          return {
+            scopeDisposeCounts: { ...state.scopeDisposeCounts },
+            controllerDisposeCounts: { ...state.controllerDisposeCounts },
+            setCreateCalls: [...state.setCreateCalls],
+            createdIds: [...state.createdIds],
+            rendered: document.querySelector('[data-repro-view]')?.textContent?.replace(/\s+/g, ' ').trim() ?? '',
+          };
+        });
+        return { ...result, pageErrors: [...pageErrors] };
+      };
+
+      await expect.poll(renderedController).toBe('controller=ctrl:A');
+
+      // --- Behavior 1: A -> B with a preserved layout (layoutPreserve [true],
+      // default options): A's page scope disposed, layout scope kept, layout
+      // controller carried over (factory called with preservedDepth 1, no
+      // ctrl:L1 re-creation, no ctrl:L1/scope:L1 disposal).
+      await go('B');
+      await expect.poll(renderedController).toBe('controller=ctrl:B');
+      const afterB = await snapshot();
+      expect(afterB.pageErrors, 'no page errors after A -> B').toEqual([]);
+      expect(afterB.setCreateCalls, 'B set built with preservedDepth 1').toEqual(['A:0', 'B:1']);
+      expect(
+        afterB.createdIds.filter((id) => id === 'ctrl:L1'),
+        'preserved layout controller must not be re-created',
+      ).toHaveLength(1);
+      expect(afterB.scopeDisposeCounts, 'A page scope disposed; L1 layout scope preserved').toEqual({
+        'scope:A': 1,
+        'scope:L1': 0,
+        'scope:B': 0,
+      });
+      expect(afterB.controllerDisposeCounts, 'A page controller disposed; L1 layout controller preserved').toEqual({
+        'ctrl:A': 1,
+        'ctrl:L1': 0,
+        'ctrl:B': 0,
+      });
+
+      // --- Behavior 2: B -> C drops the preserved layout: the layout scope
+      // and layout controller are disposed along with B's page scope.
+      await go('C');
+      await expect.poll(renderedController).toBe('controller=ctrl:C');
+      const afterC = await snapshot();
+      expect(afterC.pageErrors, 'no page errors after B -> C').toEqual([]);
+      expect(afterC.scopeDisposeCounts, 'dropping the layout disposes its scope and B page scope').toEqual({
+        'scope:A': 1,
+        'scope:L1': 1,
+        'scope:B': 1,
+        'scope:C': 0,
+      });
+      expect(afterC.controllerDisposeCounts).toEqual({
+        'ctrl:A': 1,
+        'ctrl:L1': 1,
+        'ctrl:B': 1,
+        'ctrl:C': 0,
+      });
+
+      // --- Behavior 3 setup: C -> D. D's layout L2 is non-preservable, so its
+      // controller lives in D's page scope (layoutScopes entry null).
+      await go('D');
+      await expect.poll(renderedController).toBe('controller=ctrl:D');
+      const afterD = await snapshot();
+      expect(afterD.pageErrors, 'no page errors after C -> D').toEqual([]);
+      expect(afterD.scopeDisposeCounts['scope:C'], 'C page scope disposed').toBe(1);
+      expect(afterD.controllerDisposeCounts['ctrl:C'], 'C page controller disposed').toBe(1);
+      expect(afterD.createdIds, 'no dedicated scope created for a non-preservable layout')
+        .not.toContain('scope:L2');
+
+      // --- Behavior 3: D -> E with forced { preserveLayouts: true }. The
+      // borrowed layout controller (owned by D's page scope) is carried
+      // forward, so D's page scope must be RETAINED, not disposed.
+      await go('E', { preserveLayouts: true });
+      await expect.poll(renderedController).toBe('controller=ctrl:E');
+      const afterE = await snapshot();
+      expect(afterE.pageErrors, 'no page errors after D -> E').toEqual([]);
+      expect(afterE.setCreateCalls.at(-1), 'E set built with preservedDepth 1').toBe('E:1');
+      expect(
+        afterE.createdIds.filter((id) => id === 'ctrl:L2'),
+        'borrowed layout controller must not be re-created',
+      ).toHaveLength(1);
+      expect(
+        afterE.scopeDisposeCounts['scope:D'],
+        'D page scope must be retained while its layout controller is borrowed',
+      ).toBe(0);
+      expect(afterE.controllerDisposeCounts['ctrl:L2'], 'borrowed layout controller kept alive').toBe(0);
+      expect(afterE.controllerDisposeCounts['ctrl:D'], 'D page controller still disposed').toBe(1);
+
+      // --- Behavior 3 release: E -> F drops the borrowed layout, so the
+      // retained page scope of D is finally disposed, along with ctrl:L2.
+      await go('F');
+      await expect.poll(renderedController).toBe('controller=ctrl:F');
+      const finalSnapshot = await snapshot();
+      expect(
+        finalSnapshot,
+        'Final scope/controller ledger after A->B->C->D->E(forced)->F.',
+      ).toEqual({
+        scopeDisposeCounts: {
+          'scope:A': 1,
+          'scope:L1': 1,
+          'scope:B': 1,
+          'scope:C': 1,
+          'scope:D': 1,
+          'scope:E': 1,
+          'scope:F': 0,
+        },
+        controllerDisposeCounts: {
+          'ctrl:A': 1,
+          'ctrl:L1': 1,
+          'ctrl:B': 1,
+          'ctrl:C': 1,
+          'ctrl:D': 1,
+          'ctrl:L2': 1,
+          'ctrl:E': 1,
+          'ctrl:F': 0,
+        },
+        setCreateCalls: ['A:0', 'B:1', 'C:0', 'D:0', 'E:1', 'F:0'],
+        createdIds: [
+          'scope:A', 'ctrl:L1', 'scope:L1', 'ctrl:A',
+          'scope:B', 'ctrl:B',
+          'scope:C', 'ctrl:C',
+          'scope:D', 'ctrl:L2', 'ctrl:D',
+          'scope:E', 'ctrl:E',
+          'scope:F', 'ctrl:F',
+        ],
+        rendered: 'controller=ctrl:F',
+        pageErrors: [],
+      });
+      expect(consoleErrors, 'no console errors across the whole flow').toEqual([]);
+    },
+    60_000,
+  );
+});

package/src/components/NavigationShell.svelte

@@ -3,6 +3,7 @@
   import { getNavigation, type NavigationEntry } from '@noego/wood/navigation';
   import { disposeControllerLifecycle } from '../controller/controller_lifecycle';
   import { createNavigationMountKey } from '../navigation/navigation_identity';
+  import { computePreservedLayoutDepth as computeSharedPreservedLayoutDepth } from '../navigation/layout_preservation';
   import WoodRecursiveRender from './WoodRecursiveRender.svelte';
   import { getWoodAppEnv } from '../client/app_env';
 
@@ -20,6 +21,21 @@
 
   type CreateViewControllerFn = (entry: ViewManifestEntry) => Promise<unknown>;
   type CreateLayoutControllersFn = (entry: ViewManifestEntry, startIndex?: number) => Promise<Array<unknown>>;
+  type ScopeLike = { dispose?: () => Promise<void> };
+  /**
+   * A view lifecycle's controllers plus the IoC scopes that own them:
+   * one page scope shared by the view controller and non-preservable layout
+   * controllers, and a dedicated scope per preservable layout (null entries
+   * mean "owned by the page scope"). Legacy factory props produce sets with
+   * null scopes — controller-only lifecycle, no scope disposal.
+   */
+  type ControllerSet = {
+    controller: unknown;
+    layoutControllers: Array<unknown>;
+    pageScope?: ScopeLike | null;
+    layoutScopes?: Array<ScopeLike | null>;
+  };
+  type CreateControllerSetFn = (entry: ViewManifestEntry, preservedDepth?: number) => Promise<ControllerSet>;
   type GetViewManifestEntryFn = (viewKey: string) => ViewManifestEntry | null;
   type NavigationOptions = {
     preserveLayouts?: boolean;
@@ -41,27 +57,50 @@
     initialLayoutControllers,
     createViewControllerFn,
     createLayoutControllersFn,
+    initialControllerSet,
+    createControllerSetFn,
     getViewManifestEntryFn,
   }: {
     manifest: Record<string, ViewManifestEntry>;
     initialEntry: ViewManifestEntry;
-    initialController: unknown;
-    initialLayoutControllers: Array<unknown>;
-    createViewControllerFn: CreateViewControllerFn;
-    createLayoutControllersFn: CreateLayoutControllersFn;
+    initialController?: unknown;
+    initialLayoutControllers?: Array<unknown>;
+    createViewControllerFn?: CreateViewControllerFn;
+    createLayoutControllersFn?: CreateLayoutControllersFn;
+    initialControllerSet?: ControllerSet;
+    createControllerSetFn?: CreateControllerSetFn;
     getViewManifestEntryFn: GetViewManifestEntryFn;
   } = $props();
 
+  // Unified controller-set factory: prefer the scope-aware contract; wrap
+  // the legacy split factories (scope-less) for backward compatibility.
+  const buildControllerSet: CreateControllerSetFn = createControllerSetFn
+    ?? (async (entry, preservedDepth = 0) => ({
+      controller: await createViewControllerFn?.(entry),
+      layoutControllers: (await createLayoutControllersFn?.(entry, preservedDepth)) ?? [],
+      pageScope: null,
+      layoutScopes: [],
+    }));
+
+  async function disposeScope(scope: ScopeLike | null | undefined, context: string): Promise<void> {
+    if (!scope || typeof scope.dispose !== 'function') return;
+    try {
+      await scope.dispose();
+    } catch (error) {
+      reportNavigationError(context, error);
+    }
+  }
+
   function getInitialEntry(): ViewManifestEntry {
     return initialEntry;
   }
 
   function getInitialController(): unknown {
-    return initialController;
+    return initialControllerSet ? initialControllerSet.controller : initialController;
   }
 
   function getInitialLayoutControllers(): Array<unknown> {
-    return initialLayoutControllers;
+    return initialControllerSet ? initialControllerSet.layoutControllers : (initialLayoutControllers ?? []);
   }
 
   let activeEntry = $state(getInitialEntry());
@@ -78,6 +117,13 @@
   let navigationTransitionQueue: Promise<void> = Promise.resolve();
   let destroyed = false;
 
+  // Scope ownership (null = owned by the page scope / legacy scope-less set)
+  let activePageScope: ScopeLike | null = initialControllerSet?.pageScope ?? null;
+  let activeLayoutScopes: Array<ScopeLike | null> = [...(initialControllerSet?.layoutScopes ?? [])];
+  // Outgoing page scopes kept alive because forced preservation carried one
+  // of their layout controllers forward; disposed when those layouts leave.
+  let retainedPageScopes: Array<{ scope: ScopeLike; keys: Set<string> }> = [];
+
   let activePage = $derived({
     key: activeEntry.key,
     windowName: activeEntry.windowName,
@@ -161,49 +207,14 @@
     );
   }
 
-  function layoutIdentityMatches(
-    left: ViewManifestEntry,
-    right: ViewManifestEntry,
-    index: number,
-  ): boolean {
-    return (
-      left.layoutPaths[index] === right.layoutPaths[index] &&
-      left.layoutControllers[index] === right.layoutControllers[index]
-    );
-  }
-
-  function shouldPreserveLayout(
-    from: ViewManifestEntry,
-    to: ViewManifestEntry,
-    index: number,
-    options: NavigationOptions,
-  ): boolean {
-    if (options.preserveLayouts === false) {
-      return false;
-    }
-    if (options.preserveLayouts === true) {
-      return true;
-    }
-    return from.layoutPreserve?.[index] === true && to.layoutPreserve?.[index] === true;
-  }
-
   function computePreservedLayoutDepth(
     from: ViewManifestEntry,
     to: ViewManifestEntry,
     options: NavigationOptions,
   ): number {
-    const maxDepth = Math.min(from.layoutPaths.length, to.layoutPaths.length);
-    let depth = 0;
-    for (let index = 0; index < maxDepth; index += 1) {
-      if (!layoutIdentityMatches(from, to, index)) {
-        break;
-      }
-      if (!shouldPreserveLayout(from, to, index, options)) {
-        break;
-      }
-      depth += 1;
-    }
-    return depth;
+    // The rule itself lives in navigation/layout_preservation so the Node
+    // application slice preserves exactly what this component preserves.
+    return computeSharedPreservedLayoutDepth(from, to, options);
   }
 
   async function disposeControllerSet(
@@ -250,16 +261,24 @@
   async function createTransitionControllers(
     entry: ViewManifestEntry,
     preservedDepth: number,
-  ): Promise<{ controller: unknown; layoutControllers: Array<unknown> }> {
+  ): Promise<ControllerSet> {
+    if (createControllerSetFn) {
+      // The scope-aware factory owns its own failure cleanup (it disposes
+      // the scopes it created before rethrowing).
+      return createControllerSetFn(entry, preservedDepth);
+    }
+
     const [controllerResult, layoutControllersResult] = await Promise.allSettled([
-      createViewControllerFn(entry),
-      createLayoutControllersFn(entry, preservedDepth),
+      createViewControllerFn!(entry),
+      createLayoutControllersFn!(entry, preservedDepth),
     ]);
 
     if (controllerResult.status === 'fulfilled' && layoutControllersResult.status === 'fulfilled') {
       return {
         controller: controllerResult.value,
         layoutControllers: layoutControllersResult.value,
+        pageScope: null,
+        layoutScopes: [],
       };
     }
 
@@ -311,10 +330,15 @@
     const preservedLayoutKeys = activeLayoutKeys.slice(0, preservedDepth);
     const previousController = activeController;
     const previousLayoutControllers = [...activeLayoutControllers];
-    const { controller, layoutControllers } = await createTransitionControllers(entry, preservedDepth);
+    const previousPageScope = activePageScope;
+    const previousLayoutScopes = [...activeLayoutScopes];
+    const nextSet = await createTransitionControllers(entry, preservedDepth);
+    const { controller, layoutControllers } = nextSet;
 
     if (destroyed) {
       await disposeStagedControllers(controller, layoutControllers);
+      for (const scope of nextSet.layoutScopes ?? []) await disposeScope(scope, 'staged layout scope disposal failed');
+      await disposeScope(nextSet.pageScope, 'staged page scope disposal failed');
       return;
     }
 
@@ -325,6 +349,15 @@
     );
     const nextLayoutKeys = createLayoutMountKeys(entry, nextPageKey, preservedLayoutKeys);
 
+    // Merge scope ownership the same way controllers merge: preserved prefix
+    // keeps its scopes, the created suffix brings the new set's scopes.
+    const nextLayoutScopes: Array<ScopeLike | null> = [];
+    for (let index = 0; index < entry.layoutPaths.length; index += 1) {
+      nextLayoutScopes[index] = index < preservedDepth
+        ? (previousLayoutScopes[index] ?? null)
+        : ((nextSet.layoutScopes ?? [])[index] ?? null);
+    }
+
     activeEntry = entry;
     activeController = controller;
     activeLayoutControllers = nextLayoutControllers;
@@ -332,8 +365,44 @@
     activeQuery = { ...navEntry.query };
     activePageKey = nextPageKey;
     activeLayoutKeys = nextLayoutKeys;
+    activePageScope = nextSet.pageScope ?? null;
+    activeLayoutScopes = nextLayoutScopes;
 
     await disposeControllerSet(previousController, previousLayoutControllers, preservedDepth);
+
+    // Scope lifecycle for the outgoing page:
+    // - dedicated layout scopes past the preserved prefix are done -> dispose;
+    // - the page scope is done UNLESS forced preservation carried one of its
+    //   page-scope layout controllers forward -> retain it until they leave.
+    for (let index = preservedDepth; index < previousLayoutScopes.length; index += 1) {
+      await disposeScope(previousLayoutScopes[index], 'layout scope disposal failed');
+    }
+    const borrowedKeys = new Set<string>();
+    for (let index = 0; index < preservedDepth; index += 1) {
+      if (previousLayoutControllers[index] !== undefined && (previousLayoutScopes[index] ?? null) === null) {
+        borrowedKeys.add(preservedLayoutKeys[index]);
+      }
+    }
+    if (previousPageScope) {
+      if (borrowedKeys.size > 0) {
+        retainedPageScopes.push({ scope: previousPageScope, keys: borrowedKeys });
+      } else {
+        await disposeScope(previousPageScope, 'page scope disposal failed');
+      }
+    }
+
+    // Retained scopes whose borrowed layouts are no longer preserved are done.
+    const liveKeys = new Set(nextLayoutKeys);
+    const stillRetained: typeof retainedPageScopes = [];
+    for (const retained of retainedPageScopes) {
+      retained.keys = new Set([...retained.keys].filter((key) => liveKeys.has(key)));
+      if (retained.keys.size > 0) {
+        stillRetained.push(retained);
+      } else {
+        await disposeScope(retained.scope, 'retained page scope disposal failed');
+      }
+    }
+    retainedPageScopes = stillRetained;
   }
 
   function enqueueNavigationEntry(navEntry: NavigationEntry | null): void {
@@ -408,7 +477,15 @@
     unsubscribe();
     unsubscribeWindowNavigate?.();
     void navigationTransitionQueue
-      .then(() => disposeActiveControllers())
+      .then(async () => {
+        await disposeActiveControllers();
+        for (const scope of activeLayoutScopes) await disposeScope(scope, 'teardown layout scope disposal failed');
+        await disposeScope(activePageScope, 'teardown page scope disposal failed');
+        for (const retained of retainedPageScopes) {
+          await disposeScope(retained.scope, 'teardown retained scope disposal failed');
+        }
+        retainedPageScopes = [];
+      })
       .catch((error: unknown) => {
         reportNavigationError('navigation teardown failed', error);
       });