fix(workspace): start the macOS rail below the traffic lights (#1806)

apps/electron-backend-e2e/src/window-controls.e2e.ts

@@ -187,3 +187,69 @@ test.describe('Custom window controls', () => {
         }
     });
 });
+
+test.describe('macOS traffic lights', () => {
+    test.skip(
+        process.platform !== 'darwin',
+        'Only macOS draws the native traffic lights over the rail'
+    );
+
+    test('@electron the first rail link starts with the content area, clear of the lights', async ({
+        dataDir,
+    }) => {
+        const app = await launchElectronApp(dataDir);
+
+        try {
+            const page = app.mainWindow;
+            await expect(page.locator('.app-rail')).toHaveClass(/is-macos/);
+            const firstLink = page.locator('.app-rail a').first();
+            await expect(firstLink).toBeVisible();
+
+            const [linkBox, contentBox] = await Promise.all([
+                firstLink.boundingBox(),
+                page.locator('.workspace-content').boundingBox(),
+            ]);
+            // Aligned with the content area, where the dashboard hero starts.
+            expect(
+                Math.abs((linkBox?.y ?? 0) - (contentBox?.y ?? -100))
+            ).toBeLessThanOrEqual(1);
+
+            const lights = await app.electronApp.evaluate(({ BrowserWindow }) =>
+                BrowserWindow.getAllWindows()[0]?.getWindowButtonPosition()
+            );
+            expect(lights, 'native window button position').toBeTruthy();
+            const lightsY = lights?.y ?? Number.NaN;
+            // The buttons are about 14pt tall; keep a visible gap below them,
+            // measured in window pixels (CSS pixels times the zoom factor).
+            const linkTopInWindowPixels = async (): Promise<number> => {
+                const [box, zoom] = await Promise.all([
+                    firstLink.boundingBox(),
+                    page.evaluate(() => window.outerWidth / window.innerWidth),
+                ]);
+                return (box?.y ?? Number.NaN) * zoom;
+            };
+            expect(await linkTopInWindowPixels()).toBeGreaterThanOrEqual(
+                lightsY + 14 + 16
+            );
+
+            // App zoom scales CSS pixels but not the native buttons: at the
+            // smallest zoom the inset must still clear them.
+            for (let step = 0; step < 8; step++) {
+                await page.evaluate(() =>
+                    window.electron.adjustZoomLevel('out')
+                );
+            }
+            await expect
+                .poll(() =>
+                    page.evaluate(() => window.outerWidth / window.innerWidth)
+                )
+                .toBeLessThan(0.6);
+            await expect
+                .poll(linkTopInWindowPixels)
+                .toBeGreaterThanOrEqual(lightsY + 14 + 8);
+            await page.evaluate(() => window.electron.adjustZoomLevel('reset'));
+        } finally {
+            await closeElectronApp(app);
+        }
+    });
+});