feat: add electron mailbox demo example

Author: GuillaumeLagrange

.github/workflows/codspeed.yml

@@ -74,3 +74,63 @@ jobs:
             pnpm turbo run bench --filter=@codspeed/benchmark.js-plugin
             pnpm --workspace-concurrency 1 -r bench-tinybench
             pnpm --workspace-concurrency 1 -r bench-vitest
+
+  electron-e2e:
+    name: Run electron inbox e2e
+    runs-on: codspeed-macro
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          submodules: true
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+
+      # The example links @codspeed/playwright to packages/playwright via the
+      # `link:` protocol, so the in-repo plugin must be built (under the repo's
+      # own Node version) before the example installs and resolves the symlink.
+      - name: Set up Node.js (repo)
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - name: Install repo dependencies
+        run: pnpm install --frozen-lockfile --prefer-offline
+
+      - name: Build @codspeed/playwright
+        run: pnpm turbo run build --filter=@codspeed/playwright
+
+      - name: Set up Node.js (example)
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: examples/with-electron-and-walltime/package.json
+          cache: pnpm
+          cache-dependency-path: examples/with-electron-and-walltime/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: examples/with-electron-and-walltime
+        run: pnpm install --frozen-lockfile
+
+      - name: Build electron app
+        working-directory: examples/with-electron-and-walltime
+        run: pnpm --filter @mail-client-demo/electron build
+
+      - name: Install Playwright browsers
+        working-directory: examples/with-electron-and-walltime
+        run: pnpm --filter @mail-client-demo/electron exec playwright install --with-deps chromium
+
+      - name: Run electron inbox e2e under codspeed
+        uses: CodSpeedHQ/action@runner-alpha
+        env:
+          CODSPEED_WALLTIME_PROFILER: "samply"
+        with:
+          working-directory: examples/with-electron-and-walltime
+          run: xvfb-run -a pnpm bench:electron
+          mode: walltime
+          runner-version: 4.16.2-alpha.2

examples/with-electron-and-walltime/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+out/
+.codspeed/
+*.log
+.DS_Store
+.vscode/
+.idea/
+coverage/

examples/with-electron-and-walltime/README.md

@@ -0,0 +1,50 @@
+# mail-client benchmarks
+
+A TypeScript mail-client backend-for-frontend with a small Electron client on top, instrumented with [CodSpeed](https://codspeed.io) so the performance-sensitive surface (search, threading, bulk mutations, persistence) is benchmarked in CI.
+
+## Why
+
+Mail clients have a strict performance bar — every interaction needs to feel instant. This repo isolates the data-and-state layer of such a client, benchmarks its hot paths in walltime and memory mode, and exercises the same code from an Electron renderer so the user-facing impact of a code change is visible alongside the CodSpeed numbers.
+
+## Stack
+
+- **TypeScript** on Node.js `24.11.1` (pinned via `package.json` `engines`).
+- **pnpm workspaces** — model, electron app, and benches live as separate packages.
+- Two benchmark-authoring paths, both with first-class CodSpeed support:
+  - **vitest** `bench()` + **`@codspeed/vitest-plugin`** — declarative, sits next to test suites.
+  - **tinybench** + **`@codspeed/tinybench-plugin`** — standalone scripts, fine-grained control.
+- **electron-vite** + **vanilla TS** for the client — minimal renderer code, straightforward to profile.
+
+## Layout
+
+```
+packages/
+  model/                 @mail-client-demo/model
+    src/                 Email, Inbox, seed generator, store + persistence
+    bench/               vitest benchmarks
+apps/
+  electron/              @mail-client-demo/electron
+    src/main/            Electron main process — owns the AppState + IPC
+    src/preload/         contextBridge for the renderer
+    src/renderer/        vanilla TS inbox UI
+```
+
+## Run
+
+```bash
+pnpm install
+pnpm electron            # launch the Electron client (dev mode)
+pnpm bench               # local wall-clock benches
+pnpm bench:codspeed      # instrumented run (walltime), uploads to CodSpeed
+pnpm typecheck           # typecheck all workspace packages
+```
+
+## CI
+
+This example is benchmarked in CI by the repository-root
+`.github/workflows/codspeed-electron-example.yml` workflow, which runs the
+Electron inbox e2e on the CodSpeed macro runner, with OIDC auth (no static token
+required).
+
+To benchmark the model package (walltime/memory) locally, use the `bench` and
+`bench:codspeed` scripts described above.

examples/with-electron-and-walltime/apps/electron/electron.vite.config.ts

@@ -0,0 +1,32 @@
+import { resolve } from "node:path";
+import { defineConfig, externalizeDepsPlugin } from "electron-vite";
+
+export default defineConfig({
+  main: {
+    plugins: [externalizeDepsPlugin({ exclude: ["@mail-client-demo/model"] })],
+    build: {
+      rollupOptions: {
+        input: { index: resolve(import.meta.dirname, "src/main/index.ts") },
+        output: {
+          format: "es",
+        },
+      },
+    },
+  },
+  preload: {
+    plugins: [externalizeDepsPlugin()],
+    build: {
+      rollupOptions: {
+        input: { index: resolve(import.meta.dirname, "src/preload/index.ts") },
+      },
+    },
+  },
+  renderer: {
+    root: resolve(import.meta.dirname, "src/renderer"),
+    build: {
+      rollupOptions: {
+        input: { index: resolve(import.meta.dirname, "src/renderer/index.html") },
+      },
+    },
+  },
+});

examples/with-electron-and-walltime/apps/electron/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@mail-client-demo/electron",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Electron mail-client that renders the @mail-client-demo/model inbox.",
+  "type": "module",
+  "main": "out/main/index.js",
+  "scripts": {
+    "dev": "electron-vite dev",
+    "build": "electron-vite build",
+    "preview": "electron-vite preview",
+    "typecheck": "tsc --noEmit",
+    "bench": "node test/inbox.e2e.ts"
+  },
+  "dependencies": {
+    "@mail-client-demo/model": "workspace:*"
+  },
+  "devDependencies": {
+    "@codspeed/playwright": "link:../../../../packages/playwright",
+    "@types/node": "^25.9.1",
+    "electron": "^42.2.0",
+    "electron-vite": "^5.0.0",
+    "playwright": "^1.60.0",
+    "tsx": "^4.22.3",
+    "vite": "^7.3.3"
+  }
+}

examples/with-electron-and-walltime/apps/electron/src/main/index.ts

@@ -0,0 +1,145 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Action, AppState, EmailId } from "@mail-client-demo/model";
+import {
+  generateEmails,
+  Inbox,
+  makeInitialState,
+  openDatabase,
+  reduce,
+  syncStateToDisk,
+} from "@mail-client-demo/model";
+import { app, BrowserWindow, ipcMain } from "electron";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Big enough that the naive implementations FEEL slow:
+//   buildThreads (O(n²))                            ~1.5–2 s
+//   sync (full JSON snapshot of 50k emails)         ~150–300 ms PER ACTION
+//   bulkArchive of 500 ids                          ~150–250 ms
+// Every IPC mutation runs through store.dispatch -> reduce -> syncStateToDisk,
+// so the sync cost is paid on every keystroke / button click and every UI
+// interaction feels the lag. Optimization will collapse all of it.
+const EMAIL_COUNT = 50_000;
+
+let state: AppState | null = null;
+let db: ReturnType<typeof openDatabase> | null = null;
+
+interface Timed<T> {
+  result: T;
+  durationMs: number;
+}
+
+function timed<T>(fn: () => T): Timed<T> {
+  const t0 = performance.now();
+  const result = fn();
+  return { result, durationMs: performance.now() - t0 };
+}
+
+function dispatch(action: Action): { durationMs: number; syncMs: number } {
+  const t0 = performance.now();
+  if (!state || !db) return { durationMs: 0, syncMs: 0 };
+  state = reduce(state, action);
+  const sync = syncStateToDisk(state, db);
+  return {
+    durationMs: performance.now() - t0,
+    syncMs: sync.durationMs,
+  };
+}
+
+/**
+ * Sync the current state to disk. Called from every read-only IPC handler so
+ * the audit-trail file stays current with each user interaction (and so the
+ * naive full-snapshot cost is felt on every UI op, not just mutations).
+ */
+function syncCurrentState(): number {
+  if (!state || !db) return 0;
+  return syncStateToDisk(state, db).durationMs;
+}
+
+function getInbox(): Inbox {
+  return new Inbox(state ? state.emails : []);
+}
+
+function createWindow() {
+  const win = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    title: "Inbox",
+    backgroundColor: "#0f1419",
+    webPreferences: {
+      preload: join(__dirname, "../preload/index.mjs"),
+      contextIsolation: true,
+      sandbox: false,
+    },
+  });
+
+  if (process.env.ELECTRON_RENDERER_URL) {
+    win.loadURL(process.env.ELECTRON_RENDERER_URL);
+  } else {
+    win.loadFile(join(__dirname, "../renderer/index.html"));
+  }
+}
+
+app.whenReady().then(() => {
+  const seedStart = performance.now();
+  const emails = generateEmails({ count: EMAIL_COUNT });
+  state = makeInitialState(emails);
+  const dbPath = join(app.getPath("userData"), "state.json");
+  db = openDatabase(dbPath);
+  console.log(
+    `[main] seeded ${EMAIL_COUNT} emails in ${(performance.now() - seedStart).toFixed(1)} ms`,
+  );
+  console.log(`[main] persistence path: ${dbPath}`);
+
+  // Initial sync so disk reflects the seeded state.
+  const initialSync = syncStateToDisk(state, db);
+  console.log(`[main] initial sync: ${initialSync.durationMs.toFixed(1)} ms`);
+
+  ipcMain.handle("inbox:list", () => {
+    const t = timed(() => getInbox().sortByDate(getInbox().visible()).slice(0, 200));
+    const syncMs = syncCurrentState();
+    return { ...t, syncMs };
+  });
+
+  ipcMain.handle("inbox:search", (_evt, query: string) => {
+    const t = timed(() => getInbox().sortByDate(getInbox().search(query)).slice(0, 50));
+    const syncMs = syncCurrentState();
+    return { ...t, syncMs };
+  });
+
+  ipcMain.handle("inbox:threads", () => {
+    const t = timed(() => {
+      const threads = getInbox().buildThreads();
+      threads.sort((a, b) => b.lastReceivedAt - a.lastReceivedAt);
+      return threads.slice(0, 50);
+    });
+    const syncMs = syncCurrentState();
+    return { ...t, syncMs };
+  });
+
+  ipcMain.handle("inbox:archive", (_evt, ids: EmailId[]) => {
+    const { durationMs, syncMs } = dispatch({ type: "ARCHIVE", ids, at: Date.now() });
+    return { result: ids.length, durationMs, syncMs };
+  });
+
+  ipcMain.handle("inbox:stats", () => {
+    if (!state) return { total: 0, visible: 0, pendingOps: 0 };
+    const inbox = getInbox();
+    return {
+      total: state.emails.length,
+      visible: inbox.visible().length,
+      pendingOps: state.pendingOps.length,
+    };
+  });
+
+  createWindow();
+});
+
+app.on("window-all-closed", () => {
+  if (process.platform !== "darwin") app.quit();
+});
+
+app.on("activate", () => {
+  if (BrowserWindow.getAllWindows().length === 0) createWindow();
+});

examples/with-electron-and-walltime/apps/electron/src/preload/index.ts

@@ -0,0 +1,33 @@
+import type { Email, EmailId, Thread } from "@mail-client-demo/model";
+import { contextBridge, ipcRenderer } from "electron";
+
+export interface TimedWithSync<T> {
+  result: T;
+  durationMs: number;
+  syncMs: number;
+}
+
+export interface ArchiveResult {
+  result: number;
+  durationMs: number;
+  syncMs: number;
+}
+
+export interface InboxStats {
+  total: number;
+  visible: number;
+  pendingOps: number;
+}
+
+const api = {
+  list: (): Promise<TimedWithSync<Email[]>> => ipcRenderer.invoke("inbox:list"),
+  search: (query: string): Promise<TimedWithSync<Email[]>> =>
+    ipcRenderer.invoke("inbox:search", query),
+  threads: (): Promise<TimedWithSync<Thread[]>> => ipcRenderer.invoke("inbox:threads"),
+  archive: (ids: EmailId[]): Promise<ArchiveResult> => ipcRenderer.invoke("inbox:archive", ids),
+  stats: (): Promise<InboxStats> => ipcRenderer.invoke("inbox:stats"),
+};
+
+contextBridge.exposeInMainWorld("inbox", api);
+
+export type InboxBridge = typeof api;