diff --git a/documentation/HOWTO-which-gates-need-a-browser.md b/documentation/HOWTO-which-gates-need-a-browser.md index 45a8bb0c4..484202561 100644 --- a/documentation/HOWTO-which-gates-need-a-browser.md +++ b/documentation/HOWTO-which-gates-need-a-browser.md @@ -1,6 +1,6 @@ # Which gates need a browser -There are **238** checks in this repo. **148 run anywhere. 87 need a real browser.** If you are not +There are **238** checks in this repo. **97 need a real browser**; the rest run anywhere. If you are not the person who owns the browser seat, that second group is not yours to run — and knowing which is which saves you from a whole class of wrong answer. @@ -12,14 +12,16 @@ which saves you from a whole class of wrong answer. ## Telling them apart -Open the gate's file and look for one import: +**Ask the repo, don't grep:** ```bash -grep -l 'playwright\|chromium' internal/check-*.mjs +bun run browser-gates # lists every script that launches a browser ``` -If it imports `playwright` or launches `chromium`, it needs a browser. That is the whole test — the -name does not tell you. `check:packet-render` sounds like a file check and drives a browser; +That is the authoritative answer — the same detector `check:browser-gates-guarded` uses, so it +cannot drift from what is enforced. A grep for `playwright|chromium` also works today and is fine +for a quick look, but it is a heuristic: it finds files that *mention* the word, and it would miss a +file that reached the package by path. The name tells you nothing either. `check:packet-render` sounds like a file check and drives a browser; `check:composites-mount` sounds like it needs one and does not (it mounts every composite through Vite's SSR loader, no browser at all). @@ -27,8 +29,8 @@ Vite's SSR loader, no browser at all). | | Count | |---|---:| -| headless — run these yourself | **148** | -| **browser — not yours unless you own the seat** | **87** | +| headless — run these yourself | the remainder | +| **browser — not yours unless you own the seat** | **97** | | neither (shells out to `bun`/`php`) | 3 — `check:mobile`, `check:wp-embed`, `smoke:playground` | The browser group is, broadly: everything that renders a map (`check:map-paints`, @@ -60,6 +62,38 @@ and confusing them is the most common way to report something false: --- +## The guard: you cannot launch a browser by accident any more + +The rule above used to be remembered. It is now **enforced**. Every browser gate reaches Playwright +through `internal/lib/playwright-guarded.mjs`, which refuses to launch unless +`internal/browser-slot.sh` has exported `DOXA_BROWSER_SLOT`: + +```bash +internal/browser-slot.sh bun run check:packet-render # the only way to run one +``` + +Run a browser gate outside the slot and it does not fail — **it exits 75 and tells you the command**: + +``` +this gate launches a browser. Browsers run only on the browser seat, inside the slot: + internal/browser-slot.sh bun run