@noego/wood 0.4.10 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/wood",
-  "version": "0.4.10",
+  "version": "0.5.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,6 +23,7 @@
     "src/client/app_env.ts",
     "src/client/controller_contract.ts",
     "src/controller/controller_lifecycle.ts",
+    "src/navigation/layout_preservation.ts",
     "src/navigation/navigation_identity.ts",
     "src/runtime/app_env.ts"
   ],
@@ -125,20 +126,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 +153,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,
+  );
+});