From d9de9dc26488f0c402a0b995482770d348270656 Mon Sep 17 00:00:00 2001
From: Boris Tyshkevich <btyshkevich@altinity.com>
Date: Tue, 30 Jun 2026 13:19:22 +0200
Subject: [PATCH 1/2] test(e2e): add WebKit/Safari to the Playwright matrix +
 CI (#69)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

WebKit/Safari is the engine most likely to diverge on the app's
`html{zoom}` × getBoundingClientRect/viewport-unit layout, and it was the
one engine the e2e suite never exercised. Add a `webkit` Playwright project
and install+run it in the CI `e2e` job alongside Chromium and Firefox.

The empirical pass/fail and the supported-browser decision come from CI:
Playwright's WebKit launches only on the Linux runners (the frozen
mac14-arm64 build SIGTRAPs under the dev sandbox, as do chromium/firefox
locally — these have always been Linux-CI-only). README "Supported
browsers" + CHANGELOG record the stance once CI reports.

Part of #69. Phase 0 of #68 — a regression net before the CM6 (#21) and
schema-graph (#66) refactors churn the coordinate paths.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NmXkYvYKwEf8Mvotxs3GN4
---
 .github/workflows/ci.yml |  4 ++--
 playwright.config.js     | 10 +++++++---
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b734c13..679893d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -79,8 +79,8 @@ jobs:
           node-version: '22'
       - run: npm install --no-audit --no-fund
       - name: Install Playwright browsers
-        run: npx playwright install --with-deps chromium firefox
-      - name: E2E (Playwright — Chromium + Firefox)
+        run: npx playwright install --with-deps chromium firefox webkit
+      - name: E2E (Playwright — Chromium + Firefox + WebKit)
         run: npm run test:e2e
       - uses: actions/upload-artifact@v7
         if: ${{ failure() }}
diff --git a/playwright.config.js b/playwright.config.js
index 18c156a..a9a75b7 100644
--- a/playwright.config.js
+++ b/playwright.config.js
@@ -5,8 +5,8 @@ import { defineConfig } from '@playwright/test';
 // behind the selection when a scrollbar shrinks the textarea's client box —
 // can only be caught in a real engine. These run separately from `npm test`.
 //
-// Setup once per machine: `npx playwright install chromium firefox`.
-// Run all engines: `npm run test:e2e`. One engine: `npm run test:e2e -- --project=firefox`.
+// Setup once per machine: `npx playwright install chromium firefox webkit`.
+// Run all engines: `npm run test:e2e`. One engine: `npm run test:e2e -- --project=webkit`.
 export default defineConfig({
   testDir: './tests/e2e',
   testMatch: '**/*.spec.js',
@@ -22,9 +22,13 @@ export default defineConfig({
     baseURL: 'http://127.0.0.1:5599',
   },
   // Render-layer + DOM-API bugs are engine-specific (e.g. Firefox's
-  // execCommand('insertText') on <textarea>), so the suite runs on both engines.
+  // execCommand('insertText') on <textarea>, WebKit's handling of
+  // `html{zoom}` × getBoundingClientRect), so the suite runs on all three
+  // engines — WebKit is the Safari proxy and the one most likely to diverge on
+  // the zoom-based layout (see docs/ADR-0001 + README "Supported browsers").
   projects: [
     { name: 'chromium', use: { browserName: 'chromium' } },
     { name: 'firefox', use: { browserName: 'firefox' } },
+    { name: 'webkit', use: { browserName: 'webkit' } },
   ],
 });

From 85fa4edad0c30be8e3565e568c37d975e73b16d2 Mon Sep 17 00:00:00 2001
From: Boris Tyshkevich <btyshkevich@altinity.com>
Date: Tue, 30 Jun 2026 13:24:25 +0200
Subject: [PATCH 2/2] docs(readme,changelog): record the Safari/WebKit
 supported-browser decision (#69)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI ran the e2e suite on all three engines — 36 passed (12 specs × Chromium /
Firefox / WebKit), WebKit included — so the `html{zoom}` × getBoundingClientRect
layout holds on Safari for the tested surfaces.

- README: new "Supported browsers" section (desktop Chromium/Firefox/Safari
  supported; Safari verified green on CI); e2e section updated to three engines
  + the `npx playwright install chromium firefox webkit` hint; defers the full
  browser/ClickHouse/IdP matrix + the narrow-viewport stance to #71.
- CHANGELOG [Unreleased]: note the WebKit e2e coverage + the stance.
- playwright.config: drop a misdirecting docs/ADR-0001 citation (ADR-0001 is
  reactivity, not the zoom layout).

Part of #69.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NmXkYvYKwEf8Mvotxs3GN4
---
 CHANGELOG.md         |  7 +++++++
 README.md            | 24 ++++++++++++++++++++++--
 playwright.config.js |  2 +-
 3 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8473579..c23f59e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,13 @@ auto-generated per-PR notes; this file is the curated, human-readable history.
 
 ## [Unreleased]
 
+### Added
+- Playwright e2e now runs on **WebKit** in addition to Chromium and Firefox, so
+  Safari regressions on the `html{zoom}`-based layout fail CI instead of
+  shipping silently. README gained a **Supported browsers** stance: desktop
+  Chromium/Firefox/Safari are supported (Safari verified green on CI); the full
+  browser/ClickHouse/IdP matrix is tracked in #71. (#69)
+
 ## [0.1.5] - 2026-06-29
 
 ### Added
diff --git a/README.md b/README.md
index befd19b..a03051e 100644
--- a/README.md
+++ b/README.md
@@ -445,6 +445,24 @@ docs/         ARCHITECTURE.md, DEPLOYMENT.md, ASSET-DISTRIBUTION.md,
               CLICKHOUSE-OAUTH.md, CLICKHOUSE-OSS-OAUTH.md
 ```
 
+## Supported browsers
+
+Current **desktop** engines — Chromium (Chrome/Edge), Firefox, and **Safari
+(WebKit)** — are all supported. The whole layout and the pointer/caret/drag math
+ride on `html { zoom: var(--zoom) }`, and WebKit is the engine most likely to
+diverge on `zoom` × `getBoundingClientRect`/viewport units, so it is exercised
+on **every CI run**: the Playwright e2e suite runs the editor-alignment,
+editor-insertion, schema-graph and EXPLAIN-pipeline specs on all three engines
+(`webkit` included as of #69), and Safari/WebKit passes them. A regression that
+breaks Safari now fails CI rather than shipping silently.
+
+> There is no responsive CSS today (fixed px, `overflow:hidden` on
+> `html`/`body`), so the app targets **desktop** browsers; the formal
+> narrow-viewport stance is part of the matrix in #71.
+
+The full system-requirements matrix — minimum browser versions, supported
+ClickHouse server versions, and IdP/OAuth requirements — is tracked in #71.
+
 ## Testing
 
 ```bash
@@ -463,10 +481,12 @@ suite needs no mocking libraries.
 happy-dom has no real layout or scrollbars, so render-layer bugs (e.g. the
 editor highlight drifting behind the selection when a scrollbar shrinks the
 textarea's client box) can't be caught by the unit suite. A small Playwright
-harness mounts the real `src/` modules in Chromium for those cases.
+harness mounts the real `src/` modules in **Chromium, Firefox and WebKit** for
+those cases — WebKit is the Safari proxy and the engine most likely to diverge
+on the `html{zoom}`-based layout (see [Supported browsers](#supported-browsers)).
 
 ```bash
-npx playwright install chromium   # once per machine
+npx playwright install chromium firefox webkit   # once per machine
 npm run test:e2e
 ```
 
diff --git a/playwright.config.js b/playwright.config.js
index a9a75b7..e044c94 100644
--- a/playwright.config.js
+++ b/playwright.config.js
@@ -25,7 +25,7 @@ export default defineConfig({
   // execCommand('insertText') on <textarea>, WebKit's handling of
   // `html{zoom}` × getBoundingClientRect), so the suite runs on all three
   // engines — WebKit is the Safari proxy and the one most likely to diverge on
-  // the zoom-based layout (see docs/ADR-0001 + README "Supported browsers").
+  // the zoom-based layout (see README "Supported browsers").
   projects: [
     { name: 'chromium', use: { browserName: 'chromium' } },
     { name: 'firefox', use: { browserName: 'firefox' } },