@greendrake/e2e 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Greendrake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @greendrake/e2e
+
+A Playwright kit for single-page apps: the config factories an app would otherwise hand-copy, a same-origin SPA crawler, a clipped-content detector, a polling helper for asynchronous writes, and a standalone layout checker.
+
+## Install
+
+```sh
+bun add -d @greendrake/e2e
+```
+
+`@playwright/test` (`>=1.49.0`) is a peer dependency: the consumer pins its own Playwright, and this package resolves that copy. The package ships TypeScript source, which Node cannot load from `node_modules`, so a config importing it runs Playwright under bun: `bun --bun playwright test`. The `./poll` entry and the `check-layout` bin have no such requirement.
+
+## `spaPlaywright()`
+
+```js
+// playwright.config.js
+import { spaPlaywright } from '@greendrake/e2e'
+
+export default spaPlaywright({ defaultPort: '5173' })
+```
+
+The frontend port is `VITE_PORT`, falling back to `defaultPort` — the same pin `@greendrake/vite-preset` requires for `vite dev`, so the config targets the server the app actually started. Omit `defaultPort` in an app whose harness always supplies `VITE_PORT`: a missing port then throws rather than silently testing whatever happens to be listening on a default.
+
+What it returns (a `PlaywrightTestConfig` via `defineConfig`):
+
+- `testDir: './tests'`, `fullyParallel: true`, `workers: 5`, `retries: 0`, `forbidOnly` when `CI` is set.
+- `timeout: 120_000` — crawl-style specs visit every page and click through every link; Playwright's 30s default is sized for single-interaction tests.
+- Reporter: `html`, `open: 'never'`.
+- `use`: `baseURL` `http://localhost:<port>`, `trace: 'on-first-retry'`, `video: 'retain-on-failure'`.
+- One project, `chromium`, on `devices['Desktop Chrome']`.
+- No `webServer`: the app, and whatever backs it, are started by the caller.
+
+`overrides` is a `PlaywrightTestConfig` spread over the result last, key by key at the top level — an `overrides.use` replaces the whole `use` object rather than merging into it.
+
+## `serviceWorkerPlaywright()`
+
+```js
+// playwright.sw.config.js
+import { serviceWorkerPlaywright } from '@greendrake/e2e'
+import { fileURLToPath } from 'node:url'
+
+export default serviceWorkerPlaywright({
+    dist: fileURLToPath(new URL('./dist', import.meta.url)),
+    defaultPort: '4173'
+})
+```
+
+The config for a service-worker suite: specs in `./tests/sw`, run against a built app that `vite preview` serves statically, with no backend at all. Serving an existing `dist` rather than building one here is deliberate — a build can carry deploy-time artefacts fetched from production, which a test run must not depend on. Nothing in the suite needs an API either: the app boots, its calls park unanswered, and what is asserted is that it got far enough to say so. The worker under test is whichever one the app's own build emits.
+
+Options:
+
+- `dist` (required) — absolute path to the app's built output. The factory throws when it does not exist; build first.
+- `defaultPort` — as for `spaPlaywright()`.
+- `previewEnv` — extra environment for the preview server, for a Vite config that resolves something before it will start.
+- `notifications` — run on the full Chromium build (`channel: 'chromium'`) rather than the headless shell Playwright otherwise picks for a headless run. Required by any suite that asserts on notifications: the shell ships without the notification platform and hard-denies the permission — `grantPermissions()` is accepted and `Notification.permission` still reads `"denied"`, making a worker's push handling untestable. Off by default: the shell starts faster, and the two builds are not behaviourally identical.
+- `overrides` — as for `spaPlaywright()`.
+
+What it returns:
+
+- `testDir: './tests/sw'`, `fullyParallel: false`, `workers: 1` — every test drives the same origin's worker registration and cache storage, which are shared browser-wide state.
+- `forbidOnly` when `FORBID_ONLY` is set; `timeout: 60_000`; reporter `html`, `open: 'never'`.
+- `use`: `devices['Desktop Chrome']`, `baseURL` `http://localhost:<port>`, plus `channel: 'chromium'` under `notifications`.
+- `webServer`: `bun --bun vite preview` at `http://localhost:<port>`, `reuseExistingServer: false`, with `VITE_PORT` and `previewEnv` in its environment.
+
+## `crawlLocalLinks()`
+
+```js
+import { test } from '@playwright/test'
+import { crawlLocalLinks } from '@greendrake/e2e'
+
+test('every reachable page renders', async ({ page }) => {
+    const visited = await crawlLocalLinks(page, 'http://localhost:5173')
+    console.log(visited)
+})
+```
+
+`crawlLocalLinks(page, origin)` crawls every same-origin page link reachable from `/`, verifies each page renders content, exercises SPA navigation by clicking through links, fails on any uncaught page error, and returns the visited paths. It asserts with `expect` from `@playwright/test`, so it runs inside a test.
+
+Per page: navigate (`domcontentloaded`) and wait up to 10s for the body to hold more than 100 characters of text — `networkidle` is unreliable with keepalive and analytics requests; on timeout the pending requests are logged before the error propagates. A route may deliberately leave the site (an external-redirect stub); once off-origin, nothing on the page belongs to the app, so the crawler asserts that no page error occurred and moves on without harvesting — otherwise the foreign site's paths would be queued onto the app's origin. On-origin, the body must have text and no page error may have fired.
+
+Link harvesting takes `a[href]` elements, keeping root-relative hrefs and absolute same-origin URLs (reduced to their pathname) and dropping `#`, `mailto:`, `tel:` and any href whose last path segment carries a file extension. Each new path joins the queue. Then every visible, enabled page link on the page is clicked — a given href is click-tested once across the whole crawl, since nav menus repeat on every page — the body after the click must have text, and the page goes back. A click-through that fails is logged as a warning, not a failure. Failed network requests (other than aborts) are warned about as they happen; console errors are collected and reported as a warning at the end. Only `pageerror` events fail the crawl.
+
+## `findClippedContent()`
+
+```js
+import { expect, test } from '@playwright/test'
+import { findClippedContent } from '@greendrake/e2e'
+
+test('no collapsed boxes', async ({ page }) => {
+    await page.goto('/')
+    expect(await findClippedContent(page)).toEqual([])
+})
+```
+
+`findClippedContent(page)` returns the elements whose own content is clipped away and cannot be scrolled to — the signature of a box that collapsed under its contents.
+
+The usual cause is a grid or flex item that is also a scroll container. Such an item has no automatic minimum size (CSS Sizing 3 §3.4: the size of a scroll container's content does not constrain it), so its track or line collapses to nothing while its children keep their full height and are clipped. It is easy to write by accident — `overflow: hidden` for rounded corners on a grid card is enough — and the result is invisible content rather than an error. Engines disagree on which overflow values trigger it (`overflow: clip` is safe in Blink and not in older WebKit), so a page that looks right in one browser can collapse in another; run the check in every engine the app is used in.
+
+A box counts as clipped when its `overflow-y` is `hidden` or `clip` (`auto` and `scroll` are deliberate scroll containers, `visible` does not clip), its `scrollHeight` exceeds its `clientHeight` by more than a 4px rounding tolerance, and it has child elements — a clamped line of text has none and is intended truncation.
+
+Each `ClippedElement` carries `selector` (a readable path such as `div.News > a.Card`), `height` (rendered box height) and `contentHeight` (the height its content needs), `overflowY`, `parentDisplay` (the hazard is specific to grid and flex items) and `text` (the first 60 characters of the element's text).
+
+## `@greendrake/e2e/poll`
+
+```js
+import { pollUntil } from '@greendrake/e2e/poll'
+
+const row = await pollUntil(
+    () => listRows(),
+    rows => rows.find(row => row.id === expectedId)
+)
+```
+
+`pollUntil(produce, predicate, budgetMs = 5000, intervalMs = 200)` calls the async `produce` and applies `predicate` to its value until the predicate returns a truthy match, and returns that match; once the budget is spent it throws `pollUntil: predicate never satisfied within <budgetMs>ms`. It exists for verifying fire-and-forget writes (tracking calls, queued tasks): the row lands asynchronously, so a single fetch races the write and a wait-and-retry is required. The default budget covers a 1.5s client-side error debounce plus network slack.
+
+It is a separate subpath because the main entry loads `@playwright/test` through the config factories; importing that from a spec in an app that pins a different Playwright version loads a second `@playwright/test` copy — a hard collection error. `./poll` imports nothing, so a spec can use it under any pinned version.
+
+## `check-layout`
+
+The `check-layout` bin loads a URL in every engine, at phone and desktop widths, and reports any box whose content is clipped away unreachably — the `findClippedContent()` detection, inlined so the script runs as plain JavaScript against any URL with no TypeScript pipeline in the way.
+
+```sh
+bunx check-layout http://localhost:5173/
+bunx check-layout http://localhost:5173/ --css '.Card { overflow: hidden }'
+```
+
+`--css <stylesheet>` injects the stylesheet after the page loads and before measuring — how a fix is tried against a deployed page without deploying it, and how the check is confirmed to still catch the thing it exists to catch.
+
+Engines and viewports: `chromium` and `webkit` (an engine the resolved Playwright lacks is skipped), each at `phone` 390×844 and `desktop` 1280×800; every page load waits for `networkidle` with a 30s timeout. Per engine/viewport the script prints `ok`, or `CLIP` followed by the findings grouped by selector — the number of instances, the smallest box height, the largest content height, `overflow-y`, the parent's display and a sample of the hidden text — or `ERROR` with the first line of the failure when the page does not load.
+
+Exit code: `0` when nothing is clipped anywhere; `1` when anything is clipped or a page fails to load, so it can gate a deploy; `2` on a usage error (no URL) or when no Playwright can be resolved.
+
+Playwright is resolved from the caller's side, trying in order `playwright`, `playwright-core`, then a global bun install (`~/.bun/install/global/node_modules/playwright`). Install it in the workspace, or globally with `bun add -g playwright`.

package/bin/check-layout.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Load a URL in every engine, at phone and desktop widths, and report any box
+// whose content is clipped away unreachably — see src/findClippedContent.ts for
+// what that means and why engines disagree about it.
+//
+//   ./check-layout.mjs http://localhost:5173/news
+//   ./check-layout.mjs https://app.example.com/news --css '.News .Card { overflow: hidden }'
+//
+// --css injects a stylesheet before measuring, which is how a fix is tried
+// against a deployed page without deploying it, and how this check is confirmed
+// to still catch the thing it exists to catch.
+//
+// Exits non-zero when anything is clipped, so it can gate a deploy.
+
+import { createRequire } from 'node:module'
+
+const VIEWPORTS = [
+    {
+        name: 'phone',
+        width: 390,
+        height: 844
+    },
+    {
+        name: 'desktop',
+        width: 1280,
+        height: 800
+    }
+]
+
+const [url, ...rest] = process.argv.slice(2)
+if (!url) {
+    console.error('usage: check-layout.mjs <url> [--css <stylesheet>]')
+    process.exit(2)
+}
+const cssIndex = rest.indexOf('--css')
+const extraCSS = cssIndex === -1 ? null : rest[cssIndex + 1]
+
+// Playwright is a peer dependency: resolve it from wherever the caller has it
+// rather than pinning a path that only exists on one machine.
+const require = createRequire(import.meta.url)
+let playwright
+for (const candidate of ['playwright', 'playwright-core', `${process.env.HOME}/.bun/install/global/node_modules/playwright`]) {
+    try {
+        // Playwright is CommonJS, so an ESM import puts its exports behind
+        // `default` — except where the interop hoists them. Accept either.
+        const loaded = await import(require.resolve(candidate))
+        const exports = loaded.chromium ? loaded : loaded.default
+        if (exports?.chromium) {
+            playwright = exports
+            break
+        }
+    } catch {
+        continue
+    }
+}
+if (!playwright) {
+    console.error('No playwright available. Install it in the workspace, or globally: bun add -g playwright')
+    process.exit(2)
+}
+
+// Inlined rather than imported from src/: this runs as a plain script against
+// any URL, with no TypeScript pipeline in the way.
+const findClipped = tolerance => {
+    const describe = el => {
+        const name = e => e.tagName.toLowerCase() + (e.classList.length ? `.${[...e.classList].join('.')}` : '')
+        return el.parentElement ? `${name(el.parentElement)} > ${name(el)}` : name(el)
+    }
+    const found = []
+    for (const el of document.querySelectorAll('*')) {
+        const style = getComputedStyle(el)
+        if (style.overflowY !== 'hidden' && style.overflowY !== 'clip') continue
+        if (el.scrollHeight <= el.clientHeight + tolerance) continue
+        if (el.childElementCount === 0) continue
+        found.push({
+            selector: describe(el),
+            height: Math.round(el.getBoundingClientRect().height),
+            contentHeight: el.scrollHeight,
+            overflowY: style.overflowY,
+            parentDisplay: el.parentElement ? getComputedStyle(el.parentElement).display : '',
+            text: (el.textContent ?? '').trim().slice(0, 60)
+        })
+    }
+    return found
+}
+
+let failures = 0
+for (const engineName of ['chromium', 'webkit']) {
+    const engine = playwright[engineName]
+    if (!engine) continue
+    const browser = await engine.launch()
+    for (const viewport of VIEWPORTS) {
+        const context = await browser.newContext({ viewport: { width: viewport.width, height: viewport.height } })
+        const page = await context.newPage()
+        try {
+            await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 })
+            if (extraCSS) await page.addStyleTag({ content: extraCSS })
+            const clipped = await page.evaluate(findClipped, 4)
+            const label = `${engineName}/${viewport.name}`
+            if (clipped.length === 0) {
+                console.log(`ok    ${label}`)
+            } else {
+                failures += clipped.length
+                console.log(`CLIP  ${label}`)
+                // One component collapses once per instance; the selector is
+                // the finding and the count is the blast radius.
+                const bySelector = new Map()
+                for (const c of clipped) {
+                    const seen = bySelector.get(c.selector)
+                    if (seen) {
+                        seen.count++
+                        seen.height = Math.min(seen.height, c.height)
+                        seen.contentHeight = Math.max(seen.contentHeight, c.contentHeight)
+                    } else {
+                        bySelector.set(c.selector, { ...c, count: 1 })
+                    }
+                }
+                for (const c of bySelector.values()) {
+                    console.log(`      ${c.selector} ×${c.count}: ${c.height}px tall, up to ${c.contentHeight}px of content ` + `(overflow-y: ${c.overflowY}, parent display: ${c.parentDisplay})`)
+                    if (c.text) console.log(`        hidden: ${JSON.stringify(c.text)}`)
+                }
+            }
+        } catch (error) {
+            failures++
+            console.log(`ERROR ${engineName}/${viewport.name}: ${error.message.split('\n')[0]}`)
+        }
+        await context.close()
+    }
+    await browser.close()
+}
+
+process.exit(failures > 0 ? 1 : 0)

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "@greendrake/e2e",
+    "version": "0.1.0",
+    "description": "Playwright kit for single-page apps: config factories, a same-origin crawler, a clipped-content detector, a polling helper and a layout checker",
+    "license": "MIT",
+    "author": "Eugene Greendrake <eugene@greendrake.nz>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/greendrake/lib.git",
+        "directory": "e2e"
+    },
+    "homepage": "https://github.com/greendrake/lib/tree/main/e2e#readme",
+    "bugs": {
+        "url": "https://github.com/greendrake/lib/issues"
+    },
+    "type": "module",
+    "main": "src/main.ts",
+    "types": "src/main.ts",
+    "exports": {
+        ".": {
+            "types": "./src/main.ts",
+            "default": "./src/main.ts"
+        },
+        "./poll": {
+            "types": "./src/pollUntil.ts",
+            "default": "./src/pollUntil.ts"
+        }
+    },
+    "files": [
+        "src",
+        "bin"
+    ],
+    "bin": {
+        "check-layout": "./bin/check-layout.mjs"
+    },
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "check": "tsc --noEmit"
+    },
+    "prettier": "@greendrake/dev-config/prettier",
+    "peerDependencies": {
+        "@playwright/test": ">=1.49.0"
+    },
+    "devDependencies": {
+        "@greendrake/dev-config": "0.1.0",
+        "@playwright/test": "1.60.0",
+        "typescript": "6.0.3"
+    }
+}

package/src/crawlLocalLinks.ts

@@ -0,0 +1,179 @@
+import { expect, type Page } from '@playwright/test'
+
+// Crawl every same-origin page link reachable from '/': verify each page
+// renders content, exercise SPA navigation by clicking through links, and
+// fail on any uncaught page error. Returns the visited paths for reporting.
+
+const hasFileExtension = (url: string): boolean => {
+    const pathname = url.split('?')[0].split('#')[0]
+    const lastSegment = pathname.split('/').pop()
+    return !!lastSegment && lastSegment.includes('.') && !lastSegment.startsWith('.')
+}
+
+const isPageLink = (href: string | null): href is string => {
+    if (!href) return false
+    if (href.startsWith('#')) return false
+    if (href.startsWith('mailto:')) return false
+    if (href.startsWith('tel:')) return false
+    if (hasFileExtension(href)) return false
+    return true
+}
+
+export const crawlLocalLinks = async (page: Page, origin: string): Promise<string[]> => {
+    const visitedUrls = new Set<string>()
+    const urlsToVisit = ['/']
+    // Each distinct href is click-tested once across the whole crawl — nav
+    // menus repeat on every page and re-clicking them is pure wait time.
+    const clickedHrefs = new Set<string>()
+
+    // Track pending network requests for debugging
+    const pendingRequests = new Set<string>()
+    page.on('request', request => {
+        pendingRequests.add(request.url())
+    })
+    page.on('requestfinished', request => {
+        pendingRequests.delete(request.url())
+    })
+    page.on('requestfailed', request => {
+        pendingRequests.delete(request.url())
+        const url = request.url()
+        const reason = request.failure()?.errorText ?? 'unknown'
+        // Only warn about real failures of HTTP(S) requests. Aborted requests
+        // are normal when the test navigates away mid-load (e.g. via goBack()).
+        if ((url.startsWith('http://') || url.startsWith('https://')) && reason !== 'net::ERR_ABORTED') {
+            console.warn(`Request failed: ${url} (${reason})`)
+        }
+    })
+
+    const consoleErrors: string[] = []
+    page.on('console', msg => {
+        if (msg.type() === 'error') {
+            consoleErrors.push(msg.text())
+        }
+    })
+
+    const pageErrors: string[] = []
+    page.on('pageerror', error => {
+        pageErrors.push(error.message)
+    })
+
+    while (urlsToVisit.length > 0) {
+        const currentPath = urlsToVisit.shift()!
+        if (visitedUrls.has(currentPath)) {
+            continue
+        }
+
+        console.log(`Visiting: ${currentPath}`)
+        visitedUrls.add(currentPath)
+
+        await page.goto(`${origin}${currentPath}`, { waitUntil: 'domcontentloaded' })
+
+        // Wait for real content to render (networkidle is unreliable with
+        // keepalive/analytics requests).
+        try {
+            await page.waitForFunction(() => {
+                const body = document.body
+                return !!body && !!body.textContent && body.textContent.trim().length > 100
+            }, { timeout: 10000 })
+        } catch (error) {
+            console.error(`Pending requests: ${Array.from(pendingRequests).join(', ')}`)
+            throw error
+        }
+
+        // Routes may deliberately leave the site (external-redirect stubs like
+        // /store → a marketplace). Once off-origin, nothing on the page belongs
+        // to the app: harvesting there would queue the FOREIGN site's paths
+        // onto the origin under test. Reaching the redirect without a page
+        // error is the
+        // assertion. Checked after the content wait — the guard's replace can
+        // land any time during boot.
+        if (new URL(page.url()).origin !== new URL(origin).origin) {
+            console.log(`  → left origin (${page.url()}), skipping harvest`)
+            expect(pageErrors).toEqual([])
+            continue
+        }
+
+        const bodyText = await page.textContent('body')
+        expect(bodyText).toBeTruthy()
+        expect(pageErrors).toEqual([])
+
+        // Collect same-origin page links for the crawl queue.
+        const links = await page.evaluate(() => {
+            const fileExt = (url: string): boolean => {
+                const pathname = url.split('?')[0].split('#')[0]
+                const lastSegment = pathname.split('/').pop()
+                return !!lastSegment && lastSegment.includes('.') && !lastSegment.startsWith('.')
+            }
+            return Array.from(document.querySelectorAll('a[href]'))
+                .map(a => {
+                    const href = a.getAttribute('href')
+                    if (!href) return null
+                    if (href.startsWith('#') || href.startsWith('mailto:') || href.startsWith('tel:')) return null
+                    if (fileExt(href)) return null
+                    if (href.startsWith('http://') || href.startsWith('https://')) {
+                        try {
+                            const url = new URL(href)
+                            if (url.origin !== window.location.origin) return null
+                            if (fileExt(url.pathname)) return null
+                            return url.pathname
+                        } catch {
+                            return null
+                        }
+                    }
+                    return href.startsWith('/') ? href : null
+                })
+                .filter((href): href is string => href !== null)
+        })
+        for (const link of links) {
+            if (!visitedUrls.has(link) && !urlsToVisit.includes(link)) {
+                urlsToVisit.push(link)
+            }
+        }
+
+        // Click through the links on this page to exercise SPA navigation.
+        // Locators are re-resolved by index each iteration: goBack() rebuilds
+        // the DOM, so a locator captured before the click can go stale.
+        const linkCount = await page.locator('a[href]').count()
+        for (let i = 0; i < linkCount; i++) {
+            // A previous click may have landed on an external-redirect route;
+            // goBack() cannot always recover (location.replace rewrites the
+            // entry). Re-anchor on the page under test before continuing.
+            if (new URL(page.url()).origin !== new URL(origin).origin) {
+                await page.goto(`${origin}${currentPath}`, { waitUntil: 'domcontentloaded' })
+                await page.waitForTimeout(500)
+            }
+            const link = page.locator('a[href]').nth(i)
+            try {
+                const href = await link.getAttribute('href', { timeout: 2000 })
+                if (!isPageLink(href) || clickedHrefs.has(href)) {
+                    continue
+                }
+                if (href.startsWith('http://') || href.startsWith('https://')) {
+                    if (new URL(href).origin !== new URL(origin).origin) continue
+                }
+                if ((await link.isVisible()) && (await link.isEnabled())) {
+                    clickedHrefs.add(href)
+                    await link.click()
+                    // Brief settle for the router transition; content asserted below.
+                    await page.waitForTimeout(500)
+                    const postClickBody = await page.textContent('body')
+                    expect(postClickBody).toBeTruthy()
+                    await page.goBack()
+                    await page.waitForTimeout(500)
+                }
+            } catch (error) {
+                console.warn(`Warning: link #${i} click-through failed: ${(error as Error).message}`)
+            }
+        }
+    }
+
+    console.log(`\nTest Summary:`)
+    console.log(`Total unique pages visited: ${visitedUrls.size}`)
+    console.log(`Pages: ${Array.from(visitedUrls).join(', ')}`)
+
+    if (consoleErrors.length > 0) {
+        console.warn('Console errors detected:', consoleErrors)
+    }
+    expect(pageErrors).toEqual([])
+    return Array.from(visitedUrls)
+}

package/src/findClippedContent.ts

@@ -0,0 +1,62 @@
+import type { Page } from '@playwright/test'
+
+// Find elements whose own content is clipped away and cannot be scrolled to —
+// the signature of a box that collapsed under its contents.
+//
+// The usual cause is a grid or flex item that is also a scroll container. Such
+// an item has no automatic minimum size (CSS Sizing 3 §3.4: the size of a
+// scroll container's content does not constrain it), so its track or line
+// collapses to nothing while its children keep their full height and are
+// clipped. It is easy to write by accident — `overflow: hidden` for rounded
+// corners on a grid card is enough — and the result is invisible content
+// rather than an error.
+//
+// Engines disagree on which overflow values trigger it, so a page that looks
+// right in one browser can collapse in another. Run this in every engine the
+// app is used in; `overflow: clip` in particular is safe in Blink and not in
+// older WebKit.
+
+export interface ClippedElement {
+    // A readable path to the element, e.g. "div.News > a.Card".
+    selector: string
+    // Rendered box height, and the height its content actually needs.
+    height: number
+    contentHeight: number
+    overflowY: string
+    // The parent's display, since the hazard is specific to grid/flex items.
+    parentDisplay: string
+    text: string
+}
+
+// A box may sit a pixel or two under its content through rounding alone.
+const TOLERANCE_PX = 4
+
+export const findClippedContent = async (page: Page): Promise<ClippedElement[]> =>
+    page.evaluate(tolerance => {
+        const describe = (el: Element): string => {
+            const name = (e: Element) => e.tagName.toLowerCase() + (e.classList.length ? `.${[...e.classList].join('.')}` : '')
+            return el.parentElement ? `${name(el.parentElement)} > ${name(el)}` : name(el)
+        }
+
+        const found: ClippedElement[] = []
+        for (const el of document.querySelectorAll<HTMLElement>('*')) {
+            const style = getComputedStyle(el)
+            // Only boxes that clip without offering a scrollbar hide content
+            // for good; `auto`/`scroll` are deliberate scroll containers, and
+            // `visible` does not clip at all.
+            if (style.overflowY !== 'hidden' && style.overflowY !== 'clip') continue
+            if (el.scrollHeight <= el.clientHeight + tolerance) continue
+            // A collapsed box has children taller than itself. An ordinary
+            // truncation (a clamped line of text) has none, and is intended.
+            if (el.childElementCount === 0) continue
+            found.push({
+                selector: describe(el),
+                height: Math.round(el.getBoundingClientRect().height),
+                contentHeight: el.scrollHeight,
+                overflowY: style.overflowY,
+                parentDisplay: el.parentElement ? getComputedStyle(el.parentElement).display : '',
+                text: (el.textContent ?? '').trim().slice(0, 60)
+            })
+        }
+        return found
+    }, TOLERANCE_PX)

package/src/main.ts

@@ -0,0 +1,4 @@
+export { spaPlaywright, type SpaPlaywrightOptions } from './playwrightConfig'
+export { serviceWorkerPlaywright, type ServiceWorkerPlaywrightOptions } from './serviceWorkerConfig'
+export { crawlLocalLinks } from './crawlLocalLinks'
+export { findClippedContent, type ClippedElement } from './findClippedContent'

package/src/playwrightConfig.ts

@@ -0,0 +1,42 @@
+import { defineConfig, devices, type PlaywrightTestConfig } from '@playwright/test'
+
+export interface SpaPlaywrightOptions {
+    // Frontend port when VITE_PORT is unset (each app's .env.test convention).
+    // Omit it for apps whose harness always supplies VITE_PORT: a missing port
+    // then fails the run rather than silently testing whatever happens to be
+    // listening on a default.
+    defaultPort?: string
+    overrides?: PlaywrightTestConfig
+}
+
+// The config an SPA would otherwise hand-copy: chromium-only, ./tests dir, an
+// html reporter that never auto-opens, and a baseURL built from VITE_PORT.
+export const spaPlaywright = (options: SpaPlaywrightOptions = {}): PlaywrightTestConfig => {
+    const port = process.env.VITE_PORT || options.defaultPort
+    if (!port) {
+        throw new Error('spaPlaywright: VITE_PORT must be set (this app configures no defaultPort)')
+    }
+    return defineConfig({
+        testDir: './tests',
+        fullyParallel: true,
+        forbidOnly: !!process.env.CI,
+        retries: 0,
+        workers: 5,
+        // Crawl-style specs visit every page and click through every link;
+        // Playwright's 30s default is sized for single-interaction tests.
+        timeout: 120_000,
+        reporter: [['html', { open: 'never' }]],
+        use: {
+            baseURL: `http://localhost:${port}`,
+            trace: 'on-first-retry',
+            video: 'retain-on-failure'
+        },
+        projects: [
+            {
+                name: 'chromium',
+                use: { ...devices['Desktop Chrome'] }
+            }
+        ],
+        ...options.overrides
+    })
+}

package/src/pollUntil.ts

@@ -0,0 +1,21 @@
+// Poll an async producer until the predicate returns a truthy match, and
+// return that match. For verifying fire-and-forget writes (visit tracking,
+// queued tasks): the row lands asynchronously, so a single fetch races the
+// write and a wait-and-retry is required. The default budget covers the
+// visit lib's error debouncer (1500ms) plus network slack.
+//
+// Exposed as the `@greendrake/e2e/poll` subpath (not the barrel): the
+// barrel pulls in @playwright/test via the config factory, and importing
+// that from a spec loads a SECOND @playwright/test copy in apps that pin
+// a different playwright version — a hard collection error.
+export const pollUntil = async <T, M>(produce: () => Promise<T>, predicate: (value: T) => M | undefined, budgetMs = 5000, intervalMs = 200): Promise<M> => {
+    const deadline = Date.now() + budgetMs
+    for (;;) {
+        const match = predicate(await produce())
+        if (match) return match
+        if (Date.now() >= deadline) {
+            throw new Error(`pollUntil: predicate never satisfied within ${budgetMs}ms`)
+        }
+        await new Promise(resolve => setTimeout(resolve, intervalMs))
+    }
+}

package/src/serviceWorkerConfig.ts

@@ -0,0 +1,62 @@
+import { defineConfig, devices, type PlaywrightTestConfig } from '@playwright/test'
+import { existsSync } from 'node:fs'
+
+export interface ServiceWorkerPlaywrightOptions {
+    // The app's own dist/, which `vite preview` will serve. Absolute.
+    dist: string
+    // Frontend port when VITE_PORT is unset, per the app's harness convention.
+    defaultPort?: string
+    // Extra environment for the preview server, for configs that resolve
+    // something before they will start.
+    previewEnv?: Record<string, string>
+    // Run against the full Chromium build rather than the headless shell
+    // Playwright otherwise picks for a headless run. Required by any suite that
+    // asserts on notifications: the shell ships without the notification
+    // platform, so it hard-denies the permission — grantPermissions() is
+    // accepted and Notification.permission still reads "denied", making a
+    // worker's push handling untestable. Off by default because the shell
+    // starts faster and the two builds are not behaviourally identical — a
+    // suite driving several windows at once may pass on one and not the other.
+    notifications?: boolean
+    overrides?: PlaywrightTestConfig
+}
+
+// The service-worker suite's config: tests/sw/, run against a built app served
+// statically by `vite preview`, with no backend at all.
+//
+// Serving an existing dist rather than building one here is deliberate — a
+// build can carry deploy-time artefacts fetched from production, which a test
+// run must not depend on. Nothing in the suite needs an API either: the app
+// boots, its calls park unanswered, and what is asserted is that it got far
+// enough to say so.
+export const serviceWorkerPlaywright = ({ dist, defaultPort, previewEnv, notifications, overrides }: ServiceWorkerPlaywrightOptions): PlaywrightTestConfig => {
+    const port = process.env.VITE_PORT || defaultPort
+    if (!port) {
+        throw new Error('serviceWorkerPlaywright: VITE_PORT must be set (this app configures no defaultPort)')
+    }
+    if (!existsSync(dist)) {
+        throw new Error(`serviceWorkerPlaywright: no dist/ at ${dist} — run \`bun run build\` first`)
+    }
+    return defineConfig({
+        testDir: './tests/sw',
+        // One worker: every test drives the same origin's worker registration
+        // and cache storage, which are shared browser-wide state.
+        fullyParallel: false,
+        workers: 1,
+        forbidOnly: !!process.env.FORBID_ONLY,
+        reporter: [['html', { open: 'never' }]],
+        timeout: 60_000,
+        use: {
+            ...devices['Desktop Chrome'],
+            ...(notifications ? { channel: 'chromium' } : {}),
+            baseURL: `http://localhost:${port}`
+        },
+        webServer: {
+            command: 'bun --bun vite preview',
+            url: `http://localhost:${port}`,
+            reuseExistingServer: false,
+            env: { VITE_PORT: port, ...previewEnv }
+        },
+        ...overrides
+    })
+}