@noego/wood 0.1.3 → 0.2.1

package/dist/testing/mock_electron.js

@@ -1,66 +1,86 @@
-import { vi } from "vitest";
+function createMockFunction(implementation) {
+  let currentImplementation = implementation ?? (() => void 0);
+  const mock = ((...args) => {
+    mock.calls.push(args);
+    return currentImplementation(...args);
+  });
+  mock.calls = [];
+  mock.mockImplementation = (nextImplementation) => {
+    currentImplementation = nextImplementation;
+    return mock;
+  };
+  mock.mockResolvedValue = (value) => {
+    currentImplementation = () => Promise.resolve(value);
+    return mock;
+  };
+  mock.mockReturnValue = (value) => {
+    currentImplementation = () => value;
+    return mock;
+  };
+  return mock;
+}
 function mockElectron() {
   const mocks = {
     ipcMain: {
-      handle: vi.fn(),
-      removeHandler: vi.fn(),
-      on: vi.fn()
+      handle: createMockFunction(),
+      removeHandler: createMockFunction(),
+      on: createMockFunction()
     },
     ipcRenderer: {
-      invoke: vi.fn().mockResolvedValue(void 0),
-      send: vi.fn(),
-      on: vi.fn(),
-      removeListener: vi.fn()
+      invoke: createMockFunction().mockResolvedValue(void 0),
+      send: createMockFunction(),
+      on: createMockFunction(),
+      removeListener: createMockFunction()
     },
-    BrowserWindow: vi.fn().mockImplementation(() => ({
-      loadURL: vi.fn().mockResolvedValue(void 0),
-      loadFile: vi.fn().mockResolvedValue(void 0),
+    BrowserWindow: createMockFunction().mockImplementation(() => ({
+      loadURL: createMockFunction().mockResolvedValue(void 0),
+      loadFile: createMockFunction().mockResolvedValue(void 0),
       webContents: {
-        send: vi.fn(),
-        reload: vi.fn(),
-        on: vi.fn()
+        send: createMockFunction(),
+        reload: createMockFunction(),
+        on: createMockFunction()
       },
-      on: vi.fn(),
-      once: vi.fn(),
-      close: vi.fn(),
-      focus: vi.fn(),
-      show: vi.fn(),
-      destroy: vi.fn(),
-      isDestroyed: vi.fn().mockReturnValue(false)
+      on: createMockFunction(),
+      once: createMockFunction(),
+      close: createMockFunction(),
+      focus: createMockFunction(),
+      show: createMockFunction(),
+      destroy: createMockFunction(),
+      isDestroyed: createMockFunction().mockReturnValue(false)
     })),
     app: {
-      getPath: vi.fn((name) => `/mock/${name}`),
-      on: vi.fn(),
-      once: vi.fn(),
-      whenReady: vi.fn().mockResolvedValue(void 0),
+      getPath: createMockFunction((name) => `/mock/${name}`),
+      on: createMockFunction(),
+      once: createMockFunction(),
+      whenReady: createMockFunction().mockResolvedValue(void 0),
       isPackaged: false,
-      quit: vi.fn()
+      quit: createMockFunction()
     },
     dialog: {
-      showOpenDialog: vi.fn().mockResolvedValue({ filePaths: [], canceled: false }),
-      showSaveDialog: vi.fn().mockResolvedValue({ filePath: "", canceled: false }),
-      showMessageBox: vi.fn().mockResolvedValue({ response: 0 })
+      showOpenDialog: createMockFunction().mockResolvedValue({ filePaths: [], canceled: false }),
+      showSaveDialog: createMockFunction().mockResolvedValue({ filePath: "", canceled: false }),
+      showMessageBox: createMockFunction().mockResolvedValue({ response: 0 })
     },
     shell: {
-      openExternal: vi.fn().mockResolvedValue(void 0),
-      openPath: vi.fn().mockResolvedValue("")
+      openExternal: createMockFunction().mockResolvedValue(void 0),
+      openPath: createMockFunction().mockResolvedValue("")
     },
     safeStorage: {
-      encryptString: vi.fn().mockReturnValue(Buffer.from("")),
-      decryptString: vi.fn().mockReturnValue(""),
-      isEncryptionAvailable: vi.fn().mockReturnValue(true)
+      encryptString: createMockFunction().mockReturnValue(Buffer.from("")),
+      decryptString: createMockFunction().mockReturnValue(""),
+      isEncryptionAvailable: createMockFunction().mockReturnValue(true)
     },
     nativeTheme: {
       shouldUseDarkColors: false,
-      on: vi.fn()
+      on: createMockFunction()
     },
     globalShortcut: {
-      register: vi.fn().mockReturnValue(true),
-      unregister: vi.fn(),
-      unregisterAll: vi.fn()
+      register: createMockFunction().mockReturnValue(true),
+      unregister: createMockFunction(),
+      unregisterAll: createMockFunction()
     },
     contextBridge: {
-      exposeInMainWorld: vi.fn()
+      exposeInMainWorld: createMockFunction()
     }
   };
   return mocks;

package/dist/testing/mock_electron.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/testing/mock_electron.ts"],"sourcesContent":["import { vi } from 'vitest';\n\n/**\n * Comprehensive Electron mock for vitest.\n * Call this in your test setup or beforeAll.\n */\nexport function mockElectron(): Record<string, any> {\n  // This needs to be called with vi.mock in the test file itself\n  // because vi.mock is hoisted. This function returns the mock object.\n  const mocks = {\n    ipcMain: {\n      handle: vi.fn(),\n      removeHandler: vi.fn(),\n      on: vi.fn(),\n    },\n    ipcRenderer: {\n      invoke: vi.fn().mockResolvedValue(undefined),\n      send: vi.fn(),\n      on: vi.fn(),\n      removeListener: vi.fn(),\n    },\n    BrowserWindow: vi.fn().mockImplementation(() => ({\n      loadURL: vi.fn().mockResolvedValue(undefined),\n      loadFile: vi.fn().mockResolvedValue(undefined),\n      webContents: {\n        send: vi.fn(),\n        reload: vi.fn(),\n        on: vi.fn(),\n      },\n      on: vi.fn(),\n      once: vi.fn(),\n      close: vi.fn(),\n      focus: vi.fn(),\n      show: vi.fn(),\n      destroy: vi.fn(),\n      isDestroyed: vi.fn().mockReturnValue(false),\n    })),\n    app: {\n      getPath: vi.fn((name: string) => `/mock/${name}`),\n      on: vi.fn(),\n      once: vi.fn(),\n      whenReady: vi.fn().mockResolvedValue(undefined),\n      isPackaged: false,\n      quit: vi.fn(),\n    },\n    dialog: {\n      showOpenDialog: vi.fn().mockResolvedValue({ filePaths: [], canceled: false }),\n      showSaveDialog: vi.fn().mockResolvedValue({ filePath: '', canceled: false }),\n      showMessageBox: vi.fn().mockResolvedValue({ response: 0 }),\n    },\n    shell: {\n      openExternal: vi.fn().mockResolvedValue(undefined),\n      openPath: vi.fn().mockResolvedValue(''),\n    },\n    safeStorage: {\n      encryptString: vi.fn().mockReturnValue(Buffer.from('')),\n      decryptString: vi.fn().mockReturnValue(''),\n      isEncryptionAvailable: vi.fn().mockReturnValue(true),\n    },\n    nativeTheme: {\n      shouldUseDarkColors: false,\n      on: vi.fn(),\n    },\n    globalShortcut: {\n      register: vi.fn().mockReturnValue(true),\n      unregister: vi.fn(),\n      unregisterAll: vi.fn(),\n    },\n    contextBridge: {\n      exposeInMainWorld: vi.fn(),\n    },\n  };\n\n  return mocks;\n}\n\n/**\n * Get the vi.mock factory for Electron.\n * Usage: vi.mock('electron', () => getElectronMockFactory())\n */\nexport function getElectronMockFactory(): Record<string, any> {\n  return mockElectron();\n}\n"],"mappings":"AAAA,SAAS,UAAU;AAMZ,SAAS,eAAoC;AAGlD,QAAM,QAAQ;AAAA,IACZ,SAAS;AAAA,MACP,QAAQ,GAAG,GAAG;AAAA,MACd,eAAe,GAAG,GAAG;AAAA,MACrB,IAAI,GAAG,GAAG;AAAA,IACZ;AAAA,IACA,aAAa;AAAA,MACX,QAAQ,GAAG,GAAG,EAAE,kBAAkB,MAAS;AAAA,MAC3C,MAAM,GAAG,GAAG;AAAA,MACZ,IAAI,GAAG,GAAG;AAAA,MACV,gBAAgB,GAAG,GAAG;AAAA,IACxB;AAAA,IACA,eAAe,GAAG,GAAG,EAAE,mBAAmB,OAAO;AAAA,MAC/C,SAAS,GAAG,GAAG,EAAE,kBAAkB,MAAS;AAAA,MAC5C,UAAU,GAAG,GAAG,EAAE,kBAAkB,MAAS;AAAA,MAC7C,aAAa;AAAA,QACX,MAAM,GAAG,GAAG;AAAA,QACZ,QAAQ,GAAG,GAAG;AAAA,QACd,IAAI,GAAG,GAAG;AAAA,MACZ;AAAA,MACA,IAAI,GAAG,GAAG;AAAA,MACV,MAAM,GAAG,GAAG;AAAA,MACZ,OAAO,GAAG,GAAG;AAAA,MACb,OAAO,GAAG,GAAG;AAAA,MACb,MAAM,GAAG,GAAG;AAAA,MACZ,SAAS,GAAG,GAAG;AAAA,MACf,aAAa,GAAG,GAAG,EAAE,gBAAgB,KAAK;AAAA,IAC5C,EAAE;AAAA,IACF,KAAK;AAAA,MACH,SAAS,GAAG,GAAG,CAAC,SAAiB,SAAS,IAAI,EAAE;AAAA,MAChD,IAAI,GAAG,GAAG;AAAA,MACV,MAAM,GAAG,GAAG;AAAA,MACZ,WAAW,GAAG,GAAG,EAAE,kBAAkB,MAAS;AAAA,MAC9C,YAAY;AAAA,MACZ,MAAM,GAAG,GAAG;AAAA,IACd;AAAA,IACA,QAAQ;AAAA,MACN,gBAAgB,GAAG,GAAG,EAAE,kBAAkB,EAAE,WAAW,CAAC,GAAG,UAAU,MAAM,CAAC;AAAA,MAC5E,gBAAgB,GAAG,GAAG,EAAE,kBAAkB,EAAE,UAAU,IAAI,UAAU,MAAM,CAAC;AAAA,MAC3E,gBAAgB,GAAG,GAAG,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC;AAAA,IAC3D;AAAA,IACA,OAAO;AAAA,MACL,cAAc,GAAG,GAAG,EAAE,kBAAkB,MAAS;AAAA,MACjD,UAAU,GAAG,GAAG,EAAE,kBAAkB,EAAE;AAAA,IACxC;AAAA,IACA,aAAa;AAAA,MACX,eAAe,GAAG,GAAG,EAAE,gBAAgB,OAAO,KAAK,EAAE,CAAC;AAAA,MACtD,eAAe,GAAG,GAAG,EAAE,gBAAgB,EAAE;AAAA,MACzC,uBAAuB,GAAG,GAAG,EAAE,gBAAgB,IAAI;AAAA,IACrD;AAAA,IACA,aAAa;AAAA,MACX,qBAAqB;AAAA,MACrB,IAAI,GAAG,GAAG;AAAA,IACZ;AAAA,IACA,gBAAgB;AAAA,MACd,UAAU,GAAG,GAAG,EAAE,gBAAgB,IAAI;AAAA,MACtC,YAAY,GAAG,GAAG;AAAA,MAClB,eAAe,GAAG,GAAG;AAAA,IACvB;AAAA,IACA,eAAe;AAAA,MACb,mBAAmB,GAAG,GAAG;AAAA,IAC3B;AAAA,EACF;AAEA,SAAO;AACT;AAMO,SAAS,yBAA8C;AAC5D,SAAO,aAAa;AACtB;","names":[]}
+{"version":3,"sources":["../../src/testing/mock_electron.ts"],"sourcesContent":["type MockFunction = ((...args: any[]) => any) & {\n  calls: any[][];\n  mockImplementation: (implementation: (...args: any[]) => any) => MockFunction;\n  mockResolvedValue: (value: any) => MockFunction;\n  mockReturnValue: (value: any) => MockFunction;\n};\n\nfunction createMockFunction(implementation?: (...args: any[]) => any): MockFunction {\n  let currentImplementation = implementation ?? (() => undefined);\n  const mock = ((...args: any[]) => {\n    mock.calls.push(args);\n    return currentImplementation(...args);\n  }) as MockFunction;\n  mock.calls = [];\n  mock.mockImplementation = (nextImplementation: (...args: any[]) => any) => {\n    currentImplementation = nextImplementation;\n    return mock;\n  };\n  mock.mockResolvedValue = (value: any) => {\n    currentImplementation = () => Promise.resolve(value);\n    return mock;\n  };\n  mock.mockReturnValue = (value: any) => {\n    currentImplementation = () => value;\n    return mock;\n  };\n  return mock;\n}\n\n/**\n * Comprehensive Electron mock for tests.\n * Call this in your test setup or beforeAll.\n */\nexport function mockElectron(): Record<string, any> {\n  // This returns the mock object for use with a test runner's module mock factory.\n  const mocks = {\n    ipcMain: {\n      handle: createMockFunction(),\n      removeHandler: createMockFunction(),\n      on: createMockFunction(),\n    },\n    ipcRenderer: {\n      invoke: createMockFunction().mockResolvedValue(undefined),\n      send: createMockFunction(),\n      on: createMockFunction(),\n      removeListener: createMockFunction(),\n    },\n    BrowserWindow: createMockFunction().mockImplementation(() => ({\n      loadURL: createMockFunction().mockResolvedValue(undefined),\n      loadFile: createMockFunction().mockResolvedValue(undefined),\n      webContents: {\n        send: createMockFunction(),\n        reload: createMockFunction(),\n        on: createMockFunction(),\n      },\n      on: createMockFunction(),\n      once: createMockFunction(),\n      close: createMockFunction(),\n      focus: createMockFunction(),\n      show: createMockFunction(),\n      destroy: createMockFunction(),\n      isDestroyed: createMockFunction().mockReturnValue(false),\n    })),\n    app: {\n      getPath: createMockFunction((name: string) => `/mock/${name}`),\n      on: createMockFunction(),\n      once: createMockFunction(),\n      whenReady: createMockFunction().mockResolvedValue(undefined),\n      isPackaged: false,\n      quit: createMockFunction(),\n    },\n    dialog: {\n      showOpenDialog: createMockFunction().mockResolvedValue({ filePaths: [], canceled: false }),\n      showSaveDialog: createMockFunction().mockResolvedValue({ filePath: '', canceled: false }),\n      showMessageBox: createMockFunction().mockResolvedValue({ response: 0 }),\n    },\n    shell: {\n      openExternal: createMockFunction().mockResolvedValue(undefined),\n      openPath: createMockFunction().mockResolvedValue(''),\n    },\n    safeStorage: {\n      encryptString: createMockFunction().mockReturnValue(Buffer.from('')),\n      decryptString: createMockFunction().mockReturnValue(''),\n      isEncryptionAvailable: createMockFunction().mockReturnValue(true),\n    },\n    nativeTheme: {\n      shouldUseDarkColors: false,\n      on: createMockFunction(),\n    },\n    globalShortcut: {\n      register: createMockFunction().mockReturnValue(true),\n      unregister: createMockFunction(),\n      unregisterAll: createMockFunction(),\n    },\n    contextBridge: {\n      exposeInMainWorld: createMockFunction(),\n    },\n  };\n\n  return mocks;\n}\n\n/**\n * Get a module mock factory for Electron.\n * Usage: vi.mock('electron', () => getElectronMockFactory())\n */\nexport function getElectronMockFactory(): Record<string, any> {\n  return mockElectron();\n}\n"],"mappings":"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","names":[]}

package/docs/browser-testing.md

@@ -0,0 +1,212 @@
+# Browser Testing
+
+Wood includes a browser harness for tests that need real Svelte rendering,
+real CSS layout, browser APIs, or animation timing without booting a full
+Electron app.
+
+Use it when the behavior is visual or renderer-bound:
+
+- a Svelte component must mount in Chromium
+- layered layouts need real positioning
+- a page needs Wood route, controller, and navigation wiring
+- z-index, clipping, viewport placement, or animation stability matters
+- the test needs a controlled Wood bridge instead of real Electron IPC
+
+Do not use it for pure state or service behavior. Those tests should stay in
+Node and exercise the nearest owned boundary through the IoC container.
+
+## Import
+
+```ts
+import { browser } from '@noego/wood/testing';
+```
+
+The public testing entry point intentionally exports `browser` from
+`@noego/wood/testing`. There is no extra `/browser` segment in normal test
+imports.
+
+## Create a Harness
+
+```ts
+const harness = await browser.createHarness({
+  rootDir: process.cwd(),
+  componentDir: 'ui',
+  css: ['ui/app.css'],
+  bridge: {
+    operations: {
+      'settings.get': () => ({ readSpeed: 0 }),
+    },
+  },
+});
+
+try {
+  // mount components, trees, or routes here
+} finally {
+  await harness.destroy();
+}
+```
+
+`createHarness` starts a Vite dev server with the Svelte plugin, launches a
+Playwright browser, installs a Wood bridge fixture, and writes temporary mount
+entries under the configured `rootDir`.
+
+## Mount a Component
+
+```ts
+const mounted = await harness.mountComponent('ui/components/StatusPanel.svelte', {
+  props: {
+    title: 'Ready',
+  },
+});
+
+await mounted.expect.visible('[data-testid="status-panel"]');
+await mounted.expect.insideViewport('[data-testid="status-panel"]');
+```
+
+`mountComponent` takes a component file path, not an imported component object.
+The browser runtime imports and compiles the Svelte module through Vite. A Node
+test cannot pass an imported Svelte component class across the Playwright
+process boundary.
+
+## Mount a Route
+
+Use `viewsConfig` when the test needs Wood route metadata, controller creation,
+layouts, route params, or query values to exist before the page controller is
+constructed.
+
+```ts
+const harness = await browser.createHarness({
+  rootDir: process.cwd(),
+  componentDir: 'ui',
+  viewsConfig: 'ui/openapi/views.yaml',
+  css: ['ui/app.css'],
+  bridge: {
+    operations: {
+      'settings.get': () => ({ readSpeed: 0 }),
+    },
+  },
+});
+
+const page = await harness.mountRoute('main.settings', {
+  route: {
+    params: {},
+    query: {
+      tab: 'appearance',
+    },
+  },
+});
+
+await page.expect.visible('[data-testid="settings-page"]');
+```
+
+`mountRoute` can also boot a generated Wood app by passing `generatedApp`, but
+`viewsConfig` is preferred for route-level tests because it gives the harness
+the route manifest directly. Generated app mounting is useful for smoke tests
+against generated renderer output.
+
+## Mount a Layered Tree
+
+Use `mountTree` when the test needs layout layering but not a full views YAML
+route.
+
+```ts
+const mounted = await harness.mountTree({
+  layouts: [
+    {
+      component: 'ui/layouts/AppShell.svelte',
+      props: {
+        data: { sidebarOpen: true },
+      },
+    },
+  ],
+  view: {
+    component: 'ui/pages/Inbox.svelte',
+    props: {
+      data: { selectedThreadId: 'thread-1' },
+    },
+  },
+});
+
+await mounted.expect.notOverlapping('[data-testid="sidebar"]', '[data-testid="composer"]');
+```
+
+`mountTree` is a framework harness for Wood's layout composition. App-specific
+fixture builders can wrap it, but Wood should not know app concepts such as
+chat threads, settings themes, or domain-specific ready states.
+
+## Bridge Fixtures
+
+The harness installs a Wood bridge fixture before the page loads.
+
+```ts
+const mounted = await harness.mountComponent('ui/SaveButton.svelte', {
+  bridge: {
+    operations: {
+      'document.save': async (input) => ({ ok: true, input }),
+    },
+    events: {
+      'document.changed': { id: 'doc-1' },
+    },
+  },
+});
+
+await mounted.click('[data-testid="save"]');
+
+expect(mounted.bridge.calls('document.save')).toHaveLength(1);
+
+await mounted.bridge.emit('document.changed', { id: 'doc-2' });
+```
+
+Operations are keyed by the same channel shape Wood exposes on the renderer
+bridge, for example `settings.get` or `messages.send`. Static values are
+returned directly. Functions receive the operation input and a small context
+with the channel and recorded calls.
+
+## Assertions
+
+Every mounted surface exposes Playwright's `page` and `locator`, plus
+Wood-specific assertions for visual bugs:
+
+```ts
+await mounted.expect.visible('.popover');
+await mounted.expect.hidden('.menu');
+await mounted.expect.insideViewport('.composer', { margin: 8 });
+await mounted.expect.notClipped('.popover');
+await mounted.expect.notOverlapping('.toast', '.composer');
+await mounted.expect.zIndexAbove('.modal', '.backdrop');
+await mounted.expect.stableAfterAnimation('.drawer');
+await mounted.expect.screenshot('settings-drawer');
+```
+
+Screenshots are written to `test-results/wood-browser`.
+
+## Lifecycle
+
+Destroy the harness after each test:
+
+```ts
+const harnesses: Array<{ destroy(): Promise<void> }> = [];
+
+afterEach(async () => {
+  while (harnesses.length > 0) {
+    await harnesses.pop()?.destroy();
+  }
+});
+```
+
+Mounted surfaces also expose `destroy()`, but the harness owns the browser and
+Vite server. In most tests, destroying the harness is the important cleanup.
+
+## Boundary
+
+The browser harness is not a full Electron app:
+
+- Electron IPC is replaced by the Wood bridge fixture.
+- Main-process services do not boot unless the app explicitly reaches them
+  through a test-controlled operation.
+- Browser-only bugs are observable because Chromium renders the page.
+- Electron-only bugs still need an Electron + Playwright test.
+
+This boundary is intentional. It gives component, layout, and page tests a real
+browser while keeping setup small enough that developers can write the test
+without constructing a whole application runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/wood",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,6 +18,7 @@
     "dist",
     "bin",
     "loaders",
+    "docs",
     "src/components/",
     "src/client/controller_contract.ts",
     "src/controller/controller_lifecycle.ts",
@@ -98,16 +99,21 @@
     "rxjs": "^7.x"
   },
   "peerDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^4.0.0",
     "electron": ">=28.0.0",
     "playwright": "^1.40.0",
     "svelte": "^5.x"
   },
   "peerDependenciesMeta": {
+    "@sveltejs/vite-plugin-svelte": {
+      "optional": true
+    },
     "playwright": {
       "optional": true
     }
   },
   "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^4.0.4",
     "@types/js-yaml": "^4.x",
     "@types/node": "^20.10.4",
     "electron-builder": "^25.x",