@noego/wood 0.6.1 → 0.7.0

package/docs/native-browser-testing.md

@@ -0,0 +1,164 @@
+# Native renderer test hosts
+
+`testWood(config)` now accepts an explicit renderer host. This is application
+composition and lifecycle support, not a new browser-testing language.
+
+```ts
+import { testWood } from '@noego/wood';
+import { resourceCase } from '@noego/testing';
+import { it, expect } from 'vitest';
+
+it('renders a conversation', resourceCase(async () => {
+  const env = await testWood('./wood.config.yml')
+    .select({main: {}, renderer: {path: ['main.chat']}})
+    .browser()
+    .use(preparedDatabase.stub)
+    .build();
+
+  const page = await env.open('main.chat', {
+    params: {id: '42'},
+    query: {filter: 'active'},
+  });
+  // The return value IS playwright.Page, not a proxy or Wood surface.
+  await page.getByRole('button', {name: 'Send'}).click();
+  await expect.poll(() => page.locator('.message').count()).toBe(1);
+}));
+```
+
+The test still declares any necessary schema/JSON data and application seams.
+There is no automatic migration execution or copied application database.
+
+## Host and types
+
+`.browser()` and `.browser('playwright')` select Playwright/Chromium. `open()`
+returns `Promise<Page>` from Playwright. Use the ordinary locator, evaluate,
+screenshot, context and page APIs. The test runner's assertions remain the test
+runner's; Wood does not wrap them.
+
+`.browser('happy_dom')` selects a real `Window` from happy-dom:
+
+```ts
+const env = await testWood('./wood.config.yml')
+  .select({main: {}, renderer: {path: ['main.chat']}})
+  .browser('happy_dom')
+  .build();
+const window = await env.open('main.chat');
+window.document.querySelector('button')?.click();
+await env.settle();
+expect(window.document.querySelector('.message')?.textContent).toBe('Sent');
+await env.dispose();
+```
+
+The chosen type survives `.select()`, `.use()`, and replacement methods in
+any order. These native environments intentionally do not expose Wood's old
+`click`, `fill`, `exists`, `frontend`, or `rendererRoot` surfaces. Main `api`,
+`rawApi`, `get`, `controller`, and the main root remain available. There is no
+phantom second renderer container in the Node test process.
+
+No `.browser()` call preserves the pre-existing testWood behavior, including
+runner-provided DOM hosting, during migration. This additive release does not
+change every old `open()` call's return type.
+
+## One browser for the run, many isolated tabs
+
+Use the framework's Vitest global setup for one Chromium BrowserServer across
+all fork workers:
+
+```ts
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globalSetup: ['@noego/wood/browser-test-setup'],
+  },
+});
+```
+
+An existing custom global setup can instead call
+`startSharedWoodBrowser(rootDir)` from `@noego/wood/testing` and return its
+`dispose()` as part of runner teardown. An existing `WOOD_BROWSER_WS_ENDPOINT`
+is borrowed, not replaced or closed by a second setup owner.
+
+Every built environment lazily owns its own BrowserContext. Each `open()`
+creates a Page in that context; tabs belonging to that environment share its
+browser storage and main backend, while different environments do not share
+cookies/storage or backend roots. `env.dispose()` closes only its pages and
+context. The runner closes the shared Chromium server. Ordinary cases should close their
+environment or Page, not call `close()` on the borrowed shared Browser. With no global setup,
+Wood uses a worker-local browser pool; that is reuse per worker, not a promise
+of one browser across processes. An explicit shared endpoint that fails to
+connect produces an error rather than silently launching another Chromium.
+
+Happy-dom needs no Chromium. Each open owns a separate native Window/VM realm,
+DOM, timers and storage. Windows from one environment share the main backend.
+No Node global `window`/`document` swapping is performed. This is test-state
+isolation, **not a security sandbox**: evaluate only trusted application/test
+code. Happy-dom's JavaScript-evaluation safety warning is not suppressed.
+
+## What the framework assembles
+
+The native host consumes the original Wood config, the selected views/layouts,
+production controllers and companion data loaders. It uses the production
+renderer generator and Vite's Svelte pipeline to compile the selected renderer.
+Only compiled code is cached; dependency changes invalidate it. Each native
+realm creates its own real renderer container and navigation state.
+
+Optional global CSS belongs in application configuration, not a test harness:
+
+```yaml
+renderer:
+  componentDir: ui
+  openapi: ui/stitch.yaml
+  controllers: ui/controllers
+  css: [ui/styles.css]
+```
+
+The bridge is built from the production operation catalogue. Renderer calls
+enter the same selected main router, validation, middleware, IoC scope and
+controller as `env.api`. Out-of-aperture main calls and renderer `open()` calls
+fail; importing a complete typed API does not widen selection.
+
+A compose hook may publish backend events through its standard `context.events`
+source, or return its existing `events` source. The native host subscribes to
+that source automatically. Initial subscription registration completes before
+`open()` resolves; RPC waits for admitted subscriptions too. The framework does
+not fabricate replayed events to hide late-subscription bugs.
+
+Renderer trace deliveries use Wood's trace ingress. `env.settle()` drains host
+bridge deliveries; a configured application trace persistence writer still owns
+its durable commit barrier. There is no pretend durable batch acknowledgement.
+
+## Lifecycle and scope of this first version
+
+Building records application composition without opening a tab or Window.
+First `open()` compiles the selected renderer and acquires the host. Native
+Playwright reload remounts the renderer without duplicating subscriptions.
+Closing an environment fences new opens, joins admitted opens, attempts all
+cleanup steps, and reports cleanup failures without abandoning other resources.
+Page mount errors include the route and browser diagnostics.
+
+Main-process `class/function/method/value/middleware` seams retain the existing
+NoEgo contract. **Renderer-side Node replacement objects/closures and `.load()`
+overrides are not transferred into native realms in this first version.** Those
+requests fail rather than silently applying to an unused Node renderer. Keep
+such tests on the existing in-process renderer lane until a separately designed
+renderer-replacement transport exists. Production renderer controllers and
+loaders themselves do run in both new hosts.
+
+Native browser hosts do not claim real Electron IPC, window controls, GPU or
+OS integration. They are not an emulator for Electron-only methods.
+
+Existing `browser.createHarness()`, application adapters, and old tests remain
+available until an explicit later migration. Do not mass-convert the suite as
+part of adopting this foundation.
+
+## Validation
+
+- `npm run typecheck`
+- `npm run build`
+- `npx tsc -p qualification/native_browser/tsconfig.json`
+- `npx vitest run src/testing/native_browser/native_browser.test.ts`
+- `npm test` (the Wood runner now owns its shared browser globally)
+
+The native contract tests use real Chromium and real happy-dom, not mocked
+browser/page implementations. The declaration fixture checks native return
+types, chain preservation and rejection of the wrong host's APIs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/wood",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,6 +47,12 @@
       "import": "./dist/testing/index.js",
       "default": "./dist/testing/index.js"
     },
+    "./testing-api": {
+      "types": "./dist/testing-api.d.ts",
+      "require": "./dist/testing-api.cjs",
+      "import": "./dist/testing-api.js",
+      "default": "./dist/testing-api.js"
+    },
     "./trace-testing": {
       "types": "./dist/trace-testing/index.d.ts",
       "require": "./dist/trace-testing/index.cjs",
@@ -117,7 +123,17 @@
     "./navigation-shell": "./src/components/NavigationShell.svelte",
     "./components": "./src/components/index.js",
     "./loader": "./loaders/loader.mjs",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./browser-test-setup": {
+      "types": "./dist/browser-test-setup.d.ts",
+      "import": "./dist/browser-test-setup.js",
+      "require": "./dist/browser-test-setup.cjs"
+    },
+    "./fetch": {
+      "types": "./dist/fetch.d.ts",
+      "import": "./dist/fetch.js",
+      "require": "./dist/fetch.cjs"
+    }
   },
   "scripts": {
     "build": "tsup",
@@ -129,6 +145,7 @@
   "dependencies": {
     "@noego/ioc": "^0.8.0",
     "@noego/logger": "^0.2.0",
+    "@noego/runtime": "^0.2.0",
     "@noego/stitch": "^1.1.0",
     "@noego/telemetry": "^0.2.0",
     "@noego/trace": "^0.2.0",
@@ -142,11 +159,13 @@
     "rxjs": "^7.x"
   },
   "peerDependencies": {
-    "@noego/testing": ">=0.6.0",
+    "@noego/testing": ">=0.7.0",
     "@sveltejs/vite-plugin-svelte": "^4.0.0",
     "electron": ">=28.0.0",
+    "happy-dom": "^20.14.0",
     "playwright": "^1.40.0",
-    "svelte": "^5.x"
+    "svelte": "^5.x",
+    "vite": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "@sveltejs/vite-plugin-svelte": {
@@ -157,10 +176,16 @@
     },
     "@noego/testing": {
       "optional": true
+    },
+    "happy-dom": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@noego/testing": "^0.6.0",
+    "@noego/testing": "^0.7.0",
     "@sveltejs/vite-plugin-svelte": "^4.0.4",
     "@types/better-sqlite3": "^9.6.0",
     "@types/js-yaml": "^4.x",
@@ -169,6 +194,7 @@
     "electron-builder": "^25.x",
     "electron-vite": "^2.x",
     "esbuild": "^0.25.x",
+    "happy-dom": "^20.14.0",
     "playwright": "^1.40.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",

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

@@ -2,7 +2,7 @@ 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';
+import { createBrowserFixture } from '../testing/browser';
 
 type ReproSnapshot = {
   pageCreateCount: number;
@@ -142,7 +142,7 @@ describe('NavigationShell failed transition recovery', () => {
 
     const pageErrors: string[] = [];
     const consoleErrors: string[] = [];
-    const harness = await browser.createHarness({
+    const harness = await createBrowserFixture({
       rootDir: woodRoot,
       browser: { headless: true },
       page: {
@@ -158,7 +158,7 @@ describe('NavigationShell failed transition recovery', () => {
     const mounted = await harness.mountComponent(
       path.join(rootDir, 'ui', 'NavigationShellRepro.svelte'),
     );
-    await mounted.locator('[data-repro-view]').waitFor({ state: 'visible', timeout: 5_000 }).catch(
+    await mounted.page.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` +
@@ -170,16 +170,16 @@ describe('NavigationShell failed transition recovery', () => {
     );
 
     await expect.poll(async () => {
-      return (await mounted.locator('[data-repro-view]').textContent())?.replace(/\s+/g, ' ').trim();
+      return (await mounted.page.locator('[data-repro-view]').textContent())?.replace(/\s+/g, ' ').trim();
     }).toBe('thread=1;controller=initial-page');
 
-    await mounted.evaluate(() => {
+    await mounted.page.evaluate(() => {
       (window as unknown as {
         __WOOD_NAVIGATION_REPRO_GO__: (threadId: string) => void;
       }).__WOOD_NAVIGATION_REPRO_GO__('2');
     });
     await expect.poll(async () => {
-      return await mounted.evaluate(() => {
+      return await mounted.page.evaluate(() => {
         return (window as unknown as {
           __WOOD_NAVIGATION_REPRO__: { layoutCreateCount: number };
         }).__WOOD_NAVIGATION_REPRO__.layoutCreateCount;
@@ -187,23 +187,23 @@ describe('NavigationShell failed transition recovery', () => {
     }).toBe(1);
     await expect.poll(() => pageErrors.length + consoleErrors.length).toBeGreaterThan(0);
 
-    await mounted.evaluate(() => {
+    await mounted.page.evaluate(() => {
       (window as unknown as {
         __WOOD_NAVIGATION_REPRO_GO__: (threadId: string) => void;
       }).__WOOD_NAVIGATION_REPRO_GO__('2');
     });
     await expect.poll(async () => {
-      return await mounted.evaluate(() => {
+      return await mounted.page.evaluate(() => {
         return (window as unknown as {
           __WOOD_NAVIGATION_REPRO__: { pageCreateCount: number };
         }).__WOOD_NAVIGATION_REPRO__.pageCreateCount;
       });
     }).toBe(2);
     await expect.poll(async () => {
-      return (await mounted.locator('[data-repro-view]').textContent())?.replace(/\s+/g, ' ').trim();
+      return (await mounted.page.locator('[data-repro-view]').textContent())?.replace(/\s+/g, ' ').trim();
     }).toBe('thread=2;controller=page-2');
 
-    const snapshot = await mounted.evaluate<ReproSnapshot>(() => {
+    const snapshot = await mounted.page.evaluate<ReproSnapshot>(() => {
       const state = (window as unknown as {
         __WOOD_NAVIGATION_REPRO__: Omit<ReproSnapshot, 'rendered' | 'pageErrors'>;
       }).__WOOD_NAVIGATION_REPRO__;

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

@@ -0,0 +1,57 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { expect, test } from 'vitest';
+import { resourceCase } from '@noego/testing';
+import { createBrowserFixture } from '../testing/browser';
+
+test('retains every renderer cleanup failure and disposes remaining owners once', resourceCase(async (resources) => {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'wood-shell-cleanup-'));
+  resources.own({ dispose: () => rmSync(root, { recursive: true, force: true }) });
+  const woodRoot = path.resolve(__dirname, '../..');
+  writeFileSync(path.join(root, 'View.svelte'), '<main>cleanup probe</main>');
+  writeFileSync(path.join(root, 'Probe.svelte'), `<script lang="ts">
+    import '/@fs/${woodRoot}/src/client/global_polyfill.ts';
+    import NavigationShell from '/@fs/${woodRoot}/src/components/NavigationShell.svelte';
+    import View from './View.svelte';
+    const ledger: string[] = [];
+    const controllerError = new Error('controller failed');
+    const layoutError = new Error('layout scope failed');
+    const pageError = new Error('page scope failed');
+    const observerError = new Error('observer failed');
+    const entry = { key: 'main.probe', windowName: 'main', pageName: 'probe',
+      layoutPaths: [], layoutControllers: [], view: View, layouts: [] };
+    const initialControllerSet = {
+      controller: { dispose() { ledger.push('controller'); throw controllerError; } },
+      layoutControllers: [],
+      layoutScopes: [{ async dispose() { ledger.push('layout'); throw layoutError; } }],
+      pageScope: { async dispose() { ledger.push('page'); throw pageError; } },
+    };
+    let shell: any;
+    (window as any).__CHECK_CLEANUP__ = async () => {
+      const first = shell.disposeNavigation();
+      const same = first === shell.disposeNavigation();
+      try { await first; throw new Error('missing failure'); }
+      catch (error: any) {
+        const flatten = (value: any): any[] => value?.errors ? value.errors.flatMap(flatten) : [value];
+        return { same, ledger, errors: flatten(error).map((value: any) => value.message),
+          original: flatten(error).includes(controllerError) && flatten(error).includes(layoutError)
+            && flatten(error).includes(pageError) && flatten(error).includes(observerError) };
+      }
+    };
+  </script>
+  <NavigationShell bind:this={shell} manifest={{ [entry.key]: entry }} initialEntry={entry}
+    {initialControllerSet} getViewManifestEntryFn={() => entry}
+    onLifecycleError={() => { throw observerError; }} />`);
+  const harness = await createBrowserFixture({ rootDir: woodRoot, browser: { headless: true } });
+  resources.own({ dispose: () => harness.destroy() });
+  const mounted = await harness.mountComponent(path.join(root, 'Probe.svelte'));
+  await mounted.page.locator('main').waitFor({ state: 'visible' });
+  const result = await mounted.page.evaluate(() => (window as any).__CHECK_CLEANUP__());
+  expect(result).toEqual({
+    same: true,
+    ledger: ['controller', 'layout', 'page'],
+    errors: ['controller failed', 'observer failed', 'layout scope failed', 'observer failed', 'page scope failed', 'observer failed'],
+    original: true,
+  });
+}), 60_000);

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

@@ -2,7 +2,7 @@ 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';
+import { createBrowserFixture } from '../testing/browser';
 
 type ScopeReproSnapshot = {
   scopeDisposeCounts: Record<string, number>;
@@ -184,7 +184,7 @@ describe('NavigationShell renderer scope ownership', () => {
 
       const pageErrors: string[] = [];
       const consoleErrors: string[] = [];
-      const harness = await browser.createHarness({
+      const harness = await createBrowserFixture({
         rootDir: woodRoot,
         browser: { headless: true },
         page: {
@@ -200,7 +200,7 @@ describe('NavigationShell renderer scope ownership', () => {
       const mounted = await harness.mountComponent(
         path.join(rootDir, 'ui', 'NavigationShellScopesRepro.svelte'),
       );
-      await mounted.locator('[data-repro-view]').waitFor({ state: 'visible', timeout: 5_000 }).catch(
+      await mounted.page.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` +
@@ -223,10 +223,10 @@ describe('NavigationShell renderer scope ownership', () => {
       };
 
       const renderedController = async () =>
-        (await mounted.locator('[data-repro-view]').textContent())?.replace(/\s+/g, ' ').trim();
+        (await mounted.page.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 result = await mounted.page.evaluate<Omit<ScopeReproSnapshot, 'rendered' | 'pageErrors'> & { rendered: string }>(() => {
           const state = (window as unknown as {
             __WOOD_SCOPE_REPRO__: Omit<ScopeReproSnapshot, 'rendered' | 'pageErrors'>;
           }).__WOOD_SCOPE_REPRO__;

package/src/components/NavigationShell.svelte

@@ -36,7 +36,8 @@
     pageScope?: ScopeLike | null;
     layoutScopes?: Array<ScopeLike | null>;
   };
-  type CreateControllerSetFn = (entry: ViewManifestEntry, preservedDepth?: number) => Promise<ControllerSet>;
+  type RouteInput = { params: Record<string, string>; query: Record<string, string> };
+  type CreateControllerSetFn = (entry: ViewManifestEntry, preservedDepth?: number, route?: RouteInput) => Promise<ControllerSet>;
   type GetViewManifestEntryFn = (viewKey: string) => ViewManifestEntry | null;
   type NavigationOptions = {
     preserveLayouts?: boolean;
@@ -54,6 +55,7 @@
   let {
     manifest,
     initialEntry,
+    initialRoute = { params: {}, query: {} },
     initialController,
     initialLayoutControllers,
     createViewControllerFn,
@@ -65,6 +67,7 @@
   }: {
     manifest: Record<string, ViewManifestEntry>;
     initialEntry: ViewManifestEntry;
+    initialRoute?: RouteInput;
     initialController?: unknown;
     initialLayoutControllers?: Array<unknown>;
     createViewControllerFn?: CreateViewControllerFn;
@@ -110,9 +113,9 @@
   let activeEntry = $state(getInitialEntry());
   let activeController = $state(getInitialController());
   let activeLayoutControllers: Array<unknown> = $state(getInitialLayoutControllers());
-  let activeParams: Record<string, unknown> = $state({});
-  let activeQuery: Record<string, unknown> = $state({});
-  let activePageKey = $state(createNavigationMountKey(getInitialEntry().key, {}));
+  let activeParams: Record<string, unknown> = $state({ ...initialRoute.params });
+  let activeQuery: Record<string, unknown> = $state({ ...initialRoute.query });
+  let activePageKey = $state(createNavigationMountKey(getInitialEntry().key, initialRoute.params));
   let activeLayoutKeys: string[] = $state(
     getInitialEntry().layoutPaths.map((_, index) =>
       createLayoutMountKey(getInitialEntry(), index, activePageKey),
@@ -242,10 +245,17 @@
     await cleanupAll(layoutControllers.map(controller => () => disposeControllerLifecycle(controller)), 'Wood layout cleanup failed');
   }
 
+  // Navigation may recover for the user, but the owning host must still observe
+  // every failure when it settles and disposes this renderer.
+  const lifecycleErrors: unknown[] = [];
   function reportNavigationError(context: string, error: unknown): void {
+    lifecycleErrors.push(error);
     const message = error instanceof Error ? error.message : String(error);
     console.error(`[wood] ${context}: ${message}`);
-    try { onLifecycleError?.(error); } catch (observerError) { console.error('[wood] lifecycle error observer failed', observerError); }
+    try { onLifecycleError?.(error); } catch (observerError) {
+      lifecycleErrors.push(observerError);
+      console.error('[wood] lifecycle error observer failed', observerError);
+    }
   }
 
   async function disposeStagedControllers(
@@ -266,11 +276,13 @@
   async function createTransitionControllers(
     entry: ViewManifestEntry,
     preservedDepth: number,
+    route: RouteInput,
   ): 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);
+      // the scopes it created before rethrowing). The route feeds the
+      // page/layout data loaders and controller initialize().
+      return createControllerSetFn(entry, preservedDepth, route);
     }
 
     const [controllerResult, layoutControllersResult] = await Promise.allSettled([
@@ -337,7 +349,10 @@
     const previousLayoutControllers = [...activeLayoutControllers];
     const previousPageScope = activePageScope;
     const previousLayoutScopes = [...activeLayoutScopes];
-    const nextSet = await createTransitionControllers(entry, preservedDepth);
+    const nextSet = await createTransitionControllers(entry, preservedDepth, {
+      params: { ...navEntry.params },
+      query: { ...navEntry.query },
+    });
     const { controller, layoutControllers } = nextSet;
 
     if (destroyed) {
@@ -477,23 +492,34 @@
     navigation.replace(route, {}, {});
   });
 
-  onDestroy(() => {
+  let navigationDisposal: Promise<void> | undefined;
+  /** Awaitable lifecycle hook for the framework host, including staged navigation. */
+  export function disposeNavigation(): Promise<void> {
+    if (navigationDisposal) return navigationDisposal;
     destroyed = true;
-    unsubscribe();
-    unsubscribeWindowNavigate?.();
-    void navigationTransitionQueue
-      .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);
-      });
+    navigationDisposal = Promise.resolve().then(async () => {
+      try { unsubscribe(); } catch (error) { reportNavigationError('navigation unsubscribe failed', error); }
+      try { unsubscribeWindowNavigate?.(); } catch (error) { reportNavigationError('window navigation unsubscribe failed', error); }
+      await navigationTransitionQueue;
+      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 = [];
+      if (lifecycleErrors.length) {
+        throw Object.assign(new Error('Wood navigation lifecycle failed'), {
+          errors: [...lifecycleErrors], cause: lifecycleErrors[0],
+        });
+      }
+    });
+    return navigationDisposal;
+  }
+
+  onDestroy(() => {
+    // Svelte does not await onDestroy; the host awaits the same memoized promise.
+    void disposeNavigation().catch((error: unknown) => console.error('[wood] navigation teardown failed', error));
   });
 </script>
 

package/src/navigation/layout_preservation.ts

@@ -13,7 +13,9 @@
  * both mark it `preserve: true`. `NavigationOptions.preserveLayouts`
  * overrides the declaration in both directions.
  */
-import type { NavigationOptions } from './index.js';
+export interface NavigationOptions {
+  preserveLayouts?: boolean;
+}
 
 /** The layout stack of one view, in the shape both callers can supply. */
 export interface LayoutStack {