docs: record macOS popup main integration

.project-docs/30-worklog/tasks/20260818-macos-popup-main-8f21.md

@@ -0,0 +1,71 @@
+# Task: Integrate macOS popup lag fix on main
+
+## Identity
+
+- Task ID: 20260818-macos-popup-main-8f21
+- Mode: Integration
+- Branch: main
+- Worktree: D:\Datas\OthersProjects\makelore
+- Base commit: b03ce985787a4f4efa1b2814c2fa9f60592e9663
+- Owner: developer
+- Status: Completed
+
+## Scope
+
+- Integrate the reviewed macOS popup compositing implementation from source
+  commit `0f761f3` into the currently clean local `main` at `b03ce985`.
+- Keep source task records and evidence in their owning feature worktree; write
+  only this integration task's record to the canonical branch.
+- Run merged-main verification and leave remote `origin/main` and push state
+  unchanged.
+
+## Intent And Constraints
+
+- Preserve all existing local `main` commits and unrelated peer work. Do not
+  rebase, reset, stash, force-push, or discard changes.
+- Integrate only `src/main.tsx`, `src/styles/globals.css`, and
+  `tests/e2e/popup-performance.spec.ts` from the reviewed source. Do not
+  promote the source task's unverified macOS performance claim into canonical
+  memory.
+- Preserve Main/IPC ownership, hardware-acceleration/native-vibrancy policy,
+  accessibility behavior, and non-Darwin popup visuals. Keep the real signed
+  macOS validation caveat explicit.
+- If a conflict appears outside this bounded source seam, stop for a semantic
+  decision rather than guessing.
+
+## Outcome
+
+- Merged the reviewed macOS popup fix into `main` as commit
+  `fc42c17aabdedba0d99d5a4eccfd406fb243f926` (normal `--no-ff` merge of source
+  commit `0f761f3`; the abbreviated local tip is `fc42c17`).
+- The canonical merge contains only `src/main.tsx`, `src/styles/globals.css`,
+  and `tests/e2e/popup-performance.spec.ts`. Source feature task records and
+  evidence remain in their owning worktree, as required by the documentation
+  boundary. Existing local `main` history and non-Darwin behavior are intact.
+
+## Verification
+
+- `corepack pnpm@10.33.4 run typecheck` — passed.
+- `corepack pnpm@10.33.4 run build:vite` — passed; existing dynamic-import and
+  chunk-size warnings only.
+- `corepack pnpm@10.33.4 exec node ./node_modules/@playwright/test/cli.js test
+  tests/e2e/popup-performance.spec.ts --reporter=line` — passed (1 test).
+- `corepack pnpm@10.33.4 test` — first run had one Vitest worker exit after
+  175/176 files and 2,114/2,120 tests completed; immediate rerun passed all
+  176 files and 2,120 tests.
+- Source/merged-tree scoped ESLint and final Sol reviewer both passed.
+- Documentation drift and final clean-tree checks are required before releasing
+  this integration task.
+
+## Follow-ups
+
+- Remote push was not performed; `origin/main` remains unchanged.
+- Run signed macOS x64/arm64 package smoke and a short GPU/vibrancy trace before
+  claiming measured frame-time improvement. Sheet/nested-dialog physical
+  coverage remains a release follow-up.
+
+## Promotion Candidates
+
+- None. The source task deliberately keeps the platform-scoped rendering rule
+  and performance evidence task-scoped until physical macOS measurements
+  confirm the compositor result.

src/main.tsx

@@ -10,6 +10,11 @@ import './styles/globals.css';
 import 'katex/dist/katex.min.css';
 import { initializeDefaultTransports } from './lib/api-client';
 
+const platform = window.electron?.platform;
+if (platform) {
+  document.documentElement.dataset.platform = platform;
+}
+
 initializeDefaultTransports();
 
 ReactDOM.createRoot(document.getElementById('root')!).render(

src/styles/globals.css

@@ -219,6 +219,48 @@
   backdrop-filter: blur(18px) saturate(135%);
 }
 
+/* Chromium's backdrop sampling is disproportionately expensive for transient
+ * layers in macOS Electron windows. Keep the optimization platform-scoped so
+ * the shared materials remain unchanged elsewhere. */
+html[data-platform='darwin'] :is(
+  [role='dialog'],
+  [role='alertdialog'],
+  [role='menu'],
+  [role='listbox'],
+  [role='tooltip'],
+  .fixed.inset-0
+),
+html[data-platform='darwin'] :is(
+  [role='dialog'],
+  [role='alertdialog'],
+  [role='menu'],
+  [role='listbox'],
+  [role='tooltip'],
+  .fixed.inset-0
+) .glass-surface {
+  -webkit-backdrop-filter: none !important;
+  backdrop-filter: none !important;
+}
+
+html[data-platform='darwin'] :is(
+  [role='dialog'],
+  [role='alertdialog'],
+  [role='menu'],
+  [role='listbox'],
+  [role='tooltip'],
+  .fixed.inset-0
+).glass-surface,
+html[data-platform='darwin'] :is(
+  [role='dialog'],
+  [role='alertdialog'],
+  [role='menu'],
+  [role='listbox'],
+  [role='tooltip'],
+  .fixed.inset-0
+) .glass-surface {
+  background-color: hsl(var(--background));
+}
+
 /* Sidebar material: keep the rail visibly white while allowing a restrained
  * amount of the canvas to show through. A low white alpha reads as gray over
  * the transparent native window material, so the light surface needs to stay

tests/e2e/popup-performance.spec.ts

@@ -0,0 +1,62 @@
+import { expect, getStableWindow, test } from './fixtures/electron';
+
+type PopupStyles = {
+  contentBackdropFilter: string;
+  overlayBackdropFilter: string;
+};
+
+async function readPopupStyles(page: Awaited<ReturnType<typeof getStableWindow>>): Promise<PopupStyles> {
+  return await page.evaluate(() => {
+    const content = document.querySelector<HTMLElement>('[role="dialog"]');
+    const overlay = [...document.querySelectorAll<HTMLElement>('.fixed.inset-0')]
+      .find((element) => element.getAttribute('role') !== 'dialog');
+    if (!overlay || !content) {
+      throw new Error('Expected the open dialog overlay and content');
+    }
+
+    const contentStyle = getComputedStyle(content);
+    const overlayStyle = getComputedStyle(overlay);
+    return {
+      contentBackdropFilter: contentStyle.backdropFilter,
+      overlayBackdropFilter: overlayStyle.backdropFilter,
+    };
+  });
+}
+
+test.describe('shared popup rendering cost', () => {
+  test('disables transient popup backdrop filters only on macOS', async ({ launchElectronApp }) => {
+    const app = await launchElectronApp({ skipSetup: true });
+
+    try {
+      const page = await getStableWindow(app);
+      const actualPlatform = await page.evaluate(() => window.electron.platform);
+      await expect(page.locator('html')).toHaveAttribute('data-platform', actualPlatform);
+
+      await expect(page.getByTestId('ai-module-selection-page')).toBeVisible();
+      await page.getByTestId('ai-module-option-programming').click();
+      await expect(page.getByTestId('main-layout')).toBeVisible();
+      await page.getByTestId('sidebar-member-menu-trigger').click();
+      await page.getByTestId('sidebar-nav-settings').click();
+      await expect(page.getByTestId('settings-page')).toBeVisible();
+      await page.getByTestId('settings-reveal-additional').click();
+      await expect(page.getByRole('dialog')).toBeVisible();
+
+      await page.evaluate(() => {
+        document.documentElement.dataset.platform = 'darwin';
+      });
+      await expect.poll(() => readPopupStyles(page)).toEqual({
+        contentBackdropFilter: 'none',
+        overlayBackdropFilter: 'none',
+      });
+
+      await page.evaluate(() => {
+        document.documentElement.dataset.platform = 'win32';
+      });
+      const nonMacStyles = await readPopupStyles(page);
+      expect(nonMacStyles.contentBackdropFilter).not.toBe('none');
+      expect(nonMacStyles.overlayBackdropFilter).not.toBe('none');
+    } finally {
+      await app.evaluate(({ app: electronApp }) => electronApp.quit());
+    }
+  });
+});