@owlmeans/test-ui 0.1.18-rc.5 → 0.1.18-rc.51

package/README.md

@@ -6,19 +6,22 @@ These are **not** end-to-end UI tests — they exercise individual components in
 
 ## Exports
 
-- `launchBrowser(opts?)` — return the shared chromium instance for this `bun test` process. Idempotent.
-- `closeBrowser()` — tear it down. Call from `afterAll`.
-- `withPage(fn)` — convenience: lease a fresh context+page for the duration of `fn`, then dispose the context.
-- `mountComponent({ url, component?, props? })` — opens a fresh context, navigates to a harness URL with the component / props encoded, returns `{ page, close }` so the spec can assert against `page.locator(...)` and dispose the context when done.
+- `browserHelper.launchBrowser(opts?)` — return the shared chromium instance for this `bun test` process. Idempotent.
+- `browserHelper.closeBrowser()` — tear it down. Call from `afterAll`.
+- `browserHelper.withPage(fn)` — convenience: lease a fresh context+page for the duration of `fn`, then dispose the context.
+- `mountComponent({ url, component?, props?, consentGeo? })` — opens a fresh context, navigates to a harness URL with the component / props encoded, returns `{ page, close }` so the spec can assert against `page.locator(...)` and dispose the context when done. `consentGeo` pins where the visitor is before the first navigation.
+- `consentGeoTestHelper.mockConsentGeo(pageOrContext, geo)` / `.traceCalls(page)` — answer the page's same-origin `/cdn-cgi/trace` from an init script (`'US'`, or `{ country?, fail?, delayMs?, gpc? }`), so a consent test does not depend on the runner's own country; count the trace requests.
+- `makePageHelper(page)` — drives one page of an OwlMeans app: `.acceptConsent(opts?)`, `.answerMarketingConsent(opts?)`, `.loginViaDispatcher(baseUrl, token, opts?)`, `.loginViaSupervisorForm(opts)`, `.saveScreenshot(dir, name)`.
+- `supervisorAuthHelper` — bearers without a browser: `.pregenerateAuthToken(opts)` (signed offline) and `.authenticateViaSupervisorApi(opts)` (the live supervisor flow over the API).
 - `Browser`, `BrowserContext`, `Page`, `Locator` — re-exports of the Playwright types so consumers don't need a direct `playwright` import.
 
 ## Spec shape
 
 ```ts
 import { afterAll, describe, expect, test } from 'bun:test'
-import { closeBrowser, mountComponent } from '@owlmeans/test-ui'
+import { browserHelper, mountComponent } from '@owlmeans/test-ui'
 
-afterAll(async () => { await closeBrowser() })
+afterAll(async () => { await browserHelper.closeBrowser() })
 
 describe('LoginForm — acceptance', () => {
   test('renders the heading from the SKILL example', async () => {
@@ -58,7 +61,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.52
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/test-ui",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.499Z",
+  "version": "0.1.18-rc.51",
+  "generatedAt": "2026-10-08T21:27:54.284Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/testing-ui/SKILL.md

@@ -1,16 +1,29 @@
 ---
 name: testing-ui
-description: Category-D component-level acceptance tests for OwlMeans Common UI packages (web-panel, web-client, client-panel, client-wl, web-flow, web-wl, client, client-i18n) and new shadcn UI + Tailwind v4 packages. Run under bun test, drive a real chromium via Playwright as a library — not the Playwright runner. Auto-invoked when writing tests in those packages.
+description: Category-D component-level acceptance tests for OwlMeans Common UI packages (web-panel, web-client, web-consent, web-router, mui-panel, client-panel, client-wl, web-flow, web-wl, client, client-i18n) and shadcn UI + Tailwind v4 packages. Run under bun test, drive a real chromium via Playwright as a library — not the Playwright runner. Auto-invoked when writing tests in those packages.
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
 # UI Acceptance Tests — Category D (bun test + Playwright as a library)
 
-Category D applies to packages that ship rendered React UI: `client`, `client-i18n`, `client-panel`, `client-wl`, `web-client`, `web-flow`, `web-panel`, `web-wl`. Tests are **component-level acceptance** — they mount one component in a real browser and assert against rendered DOM. They are **not** end-to-end tests (no router-deep navigation, no live backend).
+**Install:** `"@owlmeans/test-ui": "^0.1.18-rc.51"` in `devDependencies`
+
+`@owlmeans/test-ui` depends on `playwright`, so the browser library arrives with it; add
+`playwright` to `devDependencies` as well when a spec imports a launcher itself. The Vite harness
+below is the consuming package's own, so a package that builds one also declares `vite` and
+`@vitejs/plugin-react`, plus `@tailwindcss/vite` and `tailwindcss` for a shadcn package. A
+smoke-only package that serves a `data:` URL needs none of those.
+
+Category D applies to packages that ship a rendered surface: `client`, `client-i18n`, `client-panel`, `client-wl`, `mui-panel`, `web-client`, `web-consent`, `web-flow`, `web-oauth`, `web-panel`, `web-router`, `web-wl`. Tests are **component-level acceptance** — they mount one component in a real browser and assert against rendered DOM. They are **not** end-to-end tests (no live backend).
 
 The runner is **`bun test`** — same as categories A/B/C — kept consistent so contributors only learn one harness. Playwright is consumed as a **library** (`playwright` package, not `@playwright/test`). The `playwright` library exposes `chromium`, `firefox`, `webkit` browser launchers; specs drive them directly from inside `bun:test` blocks.
 
-Service-only "client-*" packages (`client-flow`, `client-socket`, `web-router`, `web-db`) belong to category A — they have no rendered UI.
+A client-side package that ships no component belongs to category A, however browser-flavoured its
+name — `client-config`, `client-context`, `client-entrypoint`, `client-flow`, `client-job`,
+`client-resource`, `client-route`, `client-socket`, `web-db`, `web-gtm` and
+`web-router-react-router` are all services, models and adapters. `@owlmeans/web-router` is the one
+that is not: it drives the real History API, so its routing behaviour is only observable in a
+browser and its specs mount a full harness here.
 
 Auth-related UI packages (`web-oidc-rp`, `web-oidc-provider`, `client-auth`, `client-payment`) belong to category B and use `bun test` + `@owlmeans/test-auth`, not the chromium harness.
 
@@ -20,9 +33,9 @@ Auth-related UI packages (`web-oidc-rp`, `web-oidc-provider`, `client-auth`, `cl
 <your-package>/
 ├── src/...
 └── tests/
-    ├── harness/              # per-package: components registry + mount config
+    ├── harness/              # per-package: the app the specs drive
     │   ├── index.html        # copy of @owlmeans/test-ui/harness/index.html
-    │   └── mount.tsx         # registers components, reads ?component= and ?props=
+    │   └── mount.tsx         # boots the package's real surface into #root
     ├── context.ts            # one place that boots the harness server, exports HARNESS_URL
     └── <area>.spec.ts        # *.spec.ts only
 ```
@@ -39,38 +52,69 @@ Downloads the chromium binary the `playwright` library drives. CI installs it in
 
 | Helper | Purpose |
 |---|---|
-| `launchBrowser(opts?)` | Return the shared chromium for this `bun test` process. Idempotent. |
-| `closeBrowser()` | Tear it down. Call from `afterAll`. |
-| `withPage(fn)` | Lease a fresh context+page for the duration of `fn`, dispose context on completion. |
-| `mountComponent({ url, component?, props? })` | Open a fresh context, navigate to the harness URL with `?component=` and `?props=` set, return `{ page, close }`. |
+| `browserHelper.launchBrowser(opts?)` | Return the shared chromium for this `bun test` process. Idempotent. |
+| `browserHelper.closeBrowser()` | Tear it down. Call from `afterAll`. |
+| `browserHelper.withPage(fn)` | Lease a fresh context+page for the duration of `fn`, dispose context on completion. |
+| `mountComponent(opts)` | Open a fresh context, navigate to `opts.url`, return `Mounted` = `{ page, close }`. `component` and `props`, when given, are appended as `?component=` and `?props=`; omit them when the harness mounts a fixed root, which is what every harness here does. |
+| `MountOptions` | `{ url, component?, props?, waitUntil?, timeout? }` — `waitUntil` defaults to `domcontentloaded`, see below. |
+| `makePageHelper(page).acceptConsent({ timeout? })` | Wait up to `timeout` (default 5s) for the consent store to SETTLE — `[data-consent-dialog]` up (bar or window), or `<html data-consent="decided">` — then accept all and wait for it to detach. Returns whether it answered one; a decision made without UI returns `false` at once. |
+| `consentGeoTestHelper.mockConsentGeo(pageOrContext, geo)` / `.traceCalls(page)` | Pin where the visitor is: an init script answering the same-origin `/cdn-cgi/trace` (`'US'`, or `{ country?, fail?: true \| 'hang', delayMs?, gpc? }`), installed for the NEXT navigation; counts the calls in the page. `mountComponent({ …, consentGeo })` installs it before the first one. |
+| `makePageHelper(page).saveScreenshot(dir, name)` | Full-page PNG to `<dir>/<name>.png`, creating `dir`. Returns the absolute path. |
 | Re-exports: `Browser`, `BrowserContext`, `Page`, `Locator` | Playwright types — no direct `playwright` import needed. |
 
+### Authenticated specs
+
+`@owlmeans/test-ui` also carries the supervisor-login helpers, so a spec can reach a screen that
+sits behind auth without hand-rolling a token:
+
+| Helper | Purpose |
+|---|---|
+| `supervisorAuthHelper.pregenerateAuthToken(opts)` | Mint an `ED25519-BASIC-TOKEN …` bearer offline from a trusted private key — no browser, no round trip. Options: `{ userId, pk, scopes?, role?, entityId?, profileId?, source? }`. |
+| `supervisorAuthHelper.authenticateViaSupervisorApi(opts)` | Drive the live PK supervisor flow over the backend API (init → sign → authenticate → dispatch), registering the user on first use. Options: `{ apiBaseUrl, userId, pk, paths?, fetchImpl? }`. |
+| `makePageHelper(page).loginViaDispatcher(baseUrl, token, opts?)` | Inject a bearer through the standard `/dispatcher?token=…` route, wait for the app to navigate away, then answer marketing consent (see below). Options: `{ dispatcherPath?, waitUntil?, marketingConsent? }`. |
+| `makePageHelper(page).loginViaSupervisorForm(opts)` | Drive the real login form end-to-end — navigate, answer consent, fill user id + key, submit, wait for the landing, then answer marketing consent (see below). Options: `{ baseUrl, userId, pk, path?, expectPath?, timeout?, waitUntil?, consent?, screenshotDir?, marketingConsent? }`. |
+| `makePageHelper(page).answerMarketingConsent(opts?)` | Answer the `@owlmeans/web-marketing-consent` full-page step if it is shown right after login. Options: `{ accept?: 'all' \| 'none' \| 'skip', terms?: 'accept' \| 'leave', timeout? }`, default `accept: 'all'`, `terms: 'accept'`, `timeout: 30_000`. Returns whether the step was actually shown and answered — `false` means it never appeared. Throws if a Terms box could not be confirmed. |
+
+These need a project whose backend trusts the private key they sign with, so they belong to specs
+that run against a real app rather than a mounted component. See `[[supervisor-auth]]` for the
+server and web wiring they assume.
+
 ## Spec shape
 
 ```ts
 import { afterAll, describe, expect, test } from 'bun:test'
-import { closeBrowser, mountComponent } from '@owlmeans/test-ui'
+import { browserHelper, mountComponent } from '@owlmeans/test-ui'
 import { HARNESS_URL } from './context.js'
 
-afterAll(async () => { await closeBrowser() })
+// Browser work does not fit bun's 5s default: a cold harness compiles the app on first request,
+// and the first test to run pays for the Vite boot happening in the same process.
+const TIMEOUT = 30_000
+
+afterAll(async () => { await browserHelper.closeBrowser() })
+
+// The harness is a real app, so a spec picks its case by opening a path on it.
+const open = async (path: string) =>
+  mountComponent({ url: `${HARNESS_URL.replace(/\/$/, '')}${path}` })
 
 describe('<package> — <component>', () => {
   test('renders the SKILL.md happy-path example', async () => {
-    const { page, close } = await mountComponent({
-      url: HARNESS_URL,
-      component: 'LoginForm',
-      props: { redirect: '/' },
-    })
+    const { page, close } = await open('/login')
     try {
       expect(await page.locator('h1').textContent()).toBe('Sign in')
       expect(await page.getByRole('button', { name: /sign in/i }).isVisible()).toBe(true)
     } finally {
       await close()
     }
-  })
+  }, TIMEOUT)
 })
 ```
 
+**Every chromium test carries its own timeout** — the third argument to `test`. Bun's default is
+5s, which a cold harness blows through before the first assertion, and `bunfig.toml`'s
+`[test] timeout` does not raise it (bun 1.4.0 reads the section but ignores that key). 30s covers a
+mounted component against a Vite harness; a suite that drives a login form or a consent gate needs
+60s. `bun test --timeout=<ms>` raises a whole run from the command line.
+
 Use `bun:test`'s `expect` against awaited Playwright DOM queries (`textContent()`, `isVisible()`, `getAttribute()`). Don't import `expect` from `@playwright/test` — that would pull in the full runner and create two parallel test toolchains.
 
 ## Per-package `tests/context.ts`
@@ -93,7 +137,12 @@ export const getHarnessUrl = async (): Promise<string> => {
     configFile: false,
     root: resolve(here, './harness'),
     plugins: [react()],
+    // Pre-bundle the third-party runtime deps the mounted components pull in. A dependency
+    // discovered mid-transform makes Vite re-optimize and reload the page underneath the
+    // navigation, and the first `goto` of a cold run pays for that as a timeout.
+    optimizeDeps: { include: ['<runtime dep the components import>'] },
     server: { port: 0 },
+    logLevel: 'warn',
   })
   await server.listen()
   const local = server.resolvedUrls?.local?.[0]
@@ -105,29 +154,44 @@ export const getHarnessUrl = async (): Promise<string> => {
 export const HARNESS_URL = await getHarnessUrl()
 ```
 
-The per-package `tests/harness/mount.tsx` reads `?component=<name>` and `?props=<json>`, dynamic-imports the component from the consumer's `src/`, and renders it via `react-dom/client` inside `<div id="root">`. Each consuming UI package wires its own providers (MUI theme for legacy packages, or Tailwind CSS + `@` alias for shadcn packages; plus i18n, router) the way the real app does — that's why mount.tsx is per-package, not in `@owlmeans/test-ui`.
+List in `optimizeDeps.include` every non-`@owlmeans` runtime package the components reach — the
+toast library, the icon set, a form library. It is the difference between a cold run that passes
+and one that times out on its first navigation for no visible reason.
+
+The per-package `tests/harness/mount.tsx` statically imports what the package ships and renders it
+via `react-dom/client` into the `<div id="root">` that `index.html` provides. It builds a real
+application — `@owlmeans/web-panel` wires a context, the framework entrypoints and a `NavLayout`
+over its screens; `@owlmeans/web-router` compiles a route tree behind the browser router plugin —
+so a spec selects its case by the path it opens rather than by naming a component. A harness that
+needs variants of one surface reads its own query string for them, the way `@owlmeans/web-consent`
+picks a locale, a category set or the policy view. `mountComponent`'s `component` and `props`
+options are the ready-made form of that convention, for a harness written to read them.
+Each consuming UI package wires its own providers (a theme provider for the `mui-*` packages, or Tailwind CSS + the `@` alias for shadcn packages; plus i18n, router) the way the real app does — that's why mount.tsx is per-package, not in `@owlmeans/test-ui`.
 
 ## Smoke-only baseline
 
-For a package that only needs to prove the bun-test + chromium pipeline works (e.g. `web-panel`'s pilot), skip the Vite harness and serve a `data:text/html` URL inline:
+For a package that only needs to prove the bun-test + chromium pipeline works, skip the Vite harness and serve a `data:text/html` URL inline. Use this for a first spec in a package that has no harness yet — `web-panel` keeps one alongside a full Vite + chromium harness (`tests/harness/` plus a `tests/context.ts` wiring the Tailwind plugin, the `@` alias and a react dedupe), and that harness is the reference to copy for any package rendering real components:
 
 ```ts
 import { afterAll, describe, expect, test } from 'bun:test'
-import { closeBrowser, mountComponent } from '@owlmeans/test-ui'
+import { browserHelper, mountComponent } from '@owlmeans/test-ui'
 
 const harness = `data:text/html,${encodeURIComponent('<h1 id="t">hello</h1>')}`
 
-afterAll(async () => { await closeBrowser() })
+afterAll(async () => { await browserHelper.closeBrowser() })
 
 describe('chromium smoke', () => {
   test('reads a heading from a data: URL', async () => {
     const { page, close } = await mountComponent({ url: harness })
     try { expect(await page.locator('#t').textContent()).toBe('hello') }
     finally { await close() }
-  })
+  }, 30_000)
 })
 ```
 
+A smoke spec needs the same explicit timeout as any other: bun runs every spec file of a package
+in one process, so the first test to start pays for whatever harness the sibling files boot.
+
 ## Wiring `bun test`
 
 Per-package `package.json`:
@@ -142,7 +206,7 @@ Same line as categories A/B/C. No `playwright.config.ts`, no `bun x playwright t
 
 ## Tailwind + shadcn packages
 
-For shadcn-based OwlMeans packages the `tests/context.ts` Vite config needs two additions beyond the standard setup:
+For shadcn-based OwlMeans packages the `tests/context.ts` Vite config needs three additions beyond the standard setup:
 
 ```ts
 import tailwindcss from '@tailwindcss/vite'
@@ -154,11 +218,16 @@ const server = await createServer({
   plugins: [react(), tailwindcss()],               // add Tailwind v4 Vite plugin
   resolve: {
     alias: { '@': resolve(here, '../src/@') },     // resolve @/ to the package's local copy
+    dedupe: ['react', 'react-dom'],                // one React across the workspace links
   },
+  optimizeDeps: { include: ['sonner'] },           // pre-bundle, never discover mid-navigation
   server: { port: 0 },
+  logLevel: 'warn',
 })
 ```
 
+`dedupe` is not optional in a workspace: symlinked sibling packages otherwise resolve their own React copy and every hook throws.
+
 `tests/harness/mount.tsx` imports the package CSS so components render with Tailwind styles:
 
 ```tsx
@@ -166,6 +235,15 @@ import '../../src/@/globals.css'
 // ... dynamic component mounting ...
 ```
 
+### Testing routed UI (navigation, layouts)
+
+A spec that exercises navigation opens a **path** on the harness origin instead of a `?component=` query, and `mount.tsx` builds a real context with real entrypoints — the OwlMeans router drives the History API, so nothing about the routing may be faked. Two shapes the harness must get right, because a spec that trips them fails obscurely:
+
+- **Leave the context un-initialized** (`ready` false). The Router compiles the entrypoint tree into routes only while the context is un-initialized; a pre-readied context renders a blank page.
+- **Give every entrypoint that has children one child declared `default: true`**, or the parent's own path renders blank.
+
+Spread the framework's own `entrypoints` (exported by the panel package) into the harness list: the panel context registers the api-config middleware, which resolves one of them during init and throws before any route is compiled if they are missing.
+
 Shadcn components are plain React — no theme provider needed. Assert via `getByRole` / text as usual. To verify that Tailwind classes took visual effect, read computed styles:
 
 ```ts
@@ -182,5 +260,117 @@ See `[[shadcn-web]]` for the full `@` alias contract and `tests/context.ts` patt
 - **No mocks.** Render the real component with real client-context wiring (state, i18n, router) the way the app does. For network calls, use Playwright's `page.route(...)` to a static fixture — never point at a live backend.
 - **Cover SKILL.md and README.md cases first.** Each component the package documents gets at least one acceptance spec for its happy path.
 - **Max 3-4 tests per component**: render, primary interaction, one edge case.
-- **Always `close()` the page and `closeBrowser()` in `afterAll`.** A leaked context blocks the bun process from exiting.
+- **Always pass a timeout as `test`'s third argument.** 30s for a mounted component, 60s for a
+  suite that drives a login or a consent gate. Bun's 5s default is for in-process work, and
+  `bunfig.toml`'s `[test] timeout` is not a way to change it.
+- **Always `close()` the page and `browserHelper.closeBrowser()` in `afterAll`.** A leaked context blocks the bun process from exiting.
 - **Chromium only by default.** Add `firefox` or `webkit` per package only when the feature has documented cross-browser concerns — call `chromium.launch` / `firefox.launch` explicitly in that case.
+
+## `mountComponent` waits for `domcontentloaded`, not `load`
+
+Playwright's own default is `load`, and it is wrong for any page that is a real application:
+`load` waits for EVERY subresource, so one analytics beacon, long-poll or third-party pixel that
+never settles holds the navigation open until it times out — with the page fully rendered and
+working the whole time. The failure reads as "the site is down", and the first instinct is to go
+looking at the server.
+
+`mountComponent` therefore navigates with `domcontentloaded` and lets the spec wait for the
+selector it actually needs. That wait IS the assertion; the load event never was. Pass
+`waitUntil` explicitly for the rare case that wants otherwise.
+
+The rule is not `mountComponent`'s alone — **every** navigation helper here follows it, including
+`makePageHelper(page).loginViaSupervisorForm` and `.loginViaDispatcher`. A helper that navigates on playwright's default
+turns "someone added a tag manager" into "the whole login-driven suite times out", with the browser
+showing a working login form the entire time. Any new helper that calls `page.goto` passes
+`domcontentloaded` and takes a `waitUntil` override.
+
+`makePageHelper(page).saveScreenshot(dir, name)` is the fastest way to see what the browser actually had on
+screen when an assertion timed out; `.loginViaSupervisorForm` takes a `screenshotDir` that captures
+the filled form just before submit.
+
+## The consent dialog blocks the login form, and the failure blames the button
+
+An OwlMeans app asks for cookie consent **before** it will start an authentication flow, and the
+surface — the bar on its transparent overlay, or the preferences window — offers no dismissal: a
+decision is what the gate is waiting for. Until it is
+answered the overlay intercepts pointer events, so a login form renders, resolves, reports itself
+`visible, enabled and stable`, and still cannot be clicked. Playwright retries for the full timeout
+and then reports `click: Timeout … waiting for getByTestId('supervisor-submit')`, naming the
+button. Nothing is wrong with the button; read the `subtree intercepts pointer events` line, which
+names `[data-consent-dialog]`.
+
+`makePageHelper(page).loginViaSupervisorForm` therefore calls `.acceptConsent()` after navigating. `.acceptConsent` is
+public for specs that drive their own login: it waits for the consent store to SETTLE — never while
+the visitor is still being located, when the transparent overlay is up and would take the click —
+then clicks `[data-consent-accept-all]` on whichever surface asks, waits for it to detach, and
+reports whether it answered one. It accepts **all** categories deliberately — a spec asserting a
+narrower decision must make that decision itself rather than inherit a silent minimum.
+
+**Where the app asks depends on where the runner is.** With the geo gate on, a Cloudflare-proxied
+app asks only visitors located in a consent country — and the trace answers with the RUNNER's
+country. A spec whose assertions need the surface pins it: `mountComponent({ url, consentGeo: 'PL' })`
+or `consentGeoTestHelper.mockConsentGeo(context, 'PL')` before the navigation; a spec about the
+automatic decision pins `'US'`. Never `page.route` for it — interception disables the cache for
+every request, and a vite-served application stalls on its hundreds of unbundled modules.
+
+**A `false` is cheap when the app says so, and costs the full wait when it cannot.** An app on a
+consent package that marks `<html data-consent>` settles at once on a stored or automatic
+decision. One older than that marker — or one that ships no consent widget — only ever settles by
+showing a dialog, so a page with none pays the timeout: 5s by `.acceptConsent`'s own default, but
+`.loginViaSupervisorForm` passes its `timeout` straight through and that defaults to `60_000`.
+Drive an app with no widget with `consent: 'ignore'`, which skips the call entirely; that is also
+the switch a spec flips when it wants to answer the dialog itself.
+
+## `makePageHelper(page).answerMarketingConsent` — cheap absence detection, unlike the cookie dialog
+
+`makePageHelper(page).loginViaSupervisorForm` and `.loginViaDispatcher` both call `.answerMarketingConsent({ accept:
+'all', timeout })` right after they confirm the app has navigated away from login/dispatch, passing
+their **own** `timeout` through explicitly rather than relying on this helper's internal default —
+both of them already budget more than one round trip (login + terms + items) into the value they
+pick. Both also default `marketingConsent` (their own option, not `.answerMarketingConsent`'s) to
+`'save'` — pass `'ignore'` to skip the call in a spec that drives the step itself.
+`@owlmeans/web-marketing-consent` renders a full-page step, when shown, with `[data-marketing-consent]`
+(root, carrying `data-state="loading"` while its status read is outstanding and `"ready"` once it can
+render), `[data-marketing-consent-terms]` (the Terms checkbox, Terms mode only, with `data-version`),
+`[data-marketing-consent-terms-error]` (Terms record failed — the person stays and retries),
+`[data-marketing-consent-all]` (select-all, never ticks Terms), `[data-marketing-consent-item="<key>"]`
+(per-consent), `[data-marketing-consent-save]`, `[data-marketing-consent-skip]` (shown whenever the
+step is optional-only — i.e. `!loading && !terms.needed` — not only after a failed save),
+`[data-marketing-consent-skip-note]`, `[data-marketing-consent-signout]` (shown while a Terms box or
+the loading state is up) and `[data-marketing-consent-error]`.
+
+Unlike `makePageHelper(page).acceptConsent`, whose `false` return deliberately costs the full wait (see above),
+`.answerMarketingConsent` does NOT pay the full `timeout` (default `30_000`) when the step is absent.
+The screen is opt-in per app and most applications and environments don't have it wired in yet, and this helper
+is called unconditionally by both login helpers — a full-timeout tax on every login, on every app,
+whether or not the screen exists, would be an unacceptable regression to every existing suite. It
+instead races `[data-marketing-consent]` against the generic "the app has already landed" /
+"still on the login screen" markers the login helpers themselves already rely on (`#app-prompt`,
+`[data-login-method]`) via the same `locator('a, b, c').first().waitFor({ state: 'visible' })` idiom
+`.loginViaSupervisorForm` uses for its own dialog-vs-form race. By the time a login helper calls this,
+one of those markers has typically already rendered, so on an app without the screen the race
+resolves as soon as it does — no fixed sleep, and no meaningful added latency over what the login
+helper already paid to get there.
+
+Once the step's root is present, it may still be `data-state="loading"` (its own status read is
+outstanding) — the helper races that attribute clearing against the whole root detaching on its own
+(nothing was pending, so it auto-continued while this waited), via two `page.waitForSelector` calls
+rather than an in-page `waitForFunction`/`evaluate` (this package's `tsconfig` has no `lib: dom`, so
+no TS runs inside the browser context here). An older `web-marketing-consent` that predates
+`data-state` entirely satisfies the "not loading" selector immediately, so this costs nothing there.
+
+When a Terms box is present, `opts.terms` (default `'accept'`) ticks it before saving; `'leave'`
+keeps it unticked, for a spec that means to exercise the blocked state itself — the confirm click
+still fires (with `{ force: true }`, since the control is never natively `disabled`), and the helper
+then *expects* the box to still be up afterward. `opts.accept` (default `'all'`) additionally clicks
+select-all when present, `'none'` saves with every item unchecked, and `'skip'` clicks
+`[data-marketing-consent-skip]` instead of saving — valid only when no Terms box is on screen.
+
+Returns `false` when the step never appeared. Otherwise it **throws** in two cases rather than
+silently swallowing them: a `[data-marketing-consent-terms-error]` after attempting to confirm
+Terms, and a Terms box still on screen after a failed/blocked confirm (Skip is never offered there
+on purpose, so there is no fallback and no honest way to report success). Short of those, it returns
+`true` whether the save succeeded outright or fell back to clicking
+`[data-marketing-consent-skip]` after a save error on an optional-only screen (logged as a console
+warning, never thrown) — the step is "answered" either way, so a spec is never permanently blocked
+behind a flaky save.

package/build/browser/types.d.ts

@@ -0,0 +1,22 @@
+import type { Browser, LaunchOptions, Page } from 'playwright';
+/** The one chromium a `bun test` process shares, and the pages specs drive off it. */
+export interface BrowserHelper {
+    /**
+     * Launch (or return) a single shared chromium instance for the current
+     * `bun test` process. UI specs hold a fixture page off this browser; the
+     * suite calls {@link BrowserHelper.closeBrowser} from `afterAll` to tear it down once.
+     */
+    launchBrowser: (opts?: LaunchOptions) => Promise<Browser>;
+    /**
+     * Tear down the shared browser. Idempotent — safe to call from multiple
+     * `afterAll` hooks.
+     */
+    closeBrowser: () => Promise<void>;
+    /**
+     * Convenience that launches the browser, runs a callback with a fresh
+     * context + page, and closes the context on completion. The browser
+     * itself stays alive across calls so multiple specs share it cheaply.
+     */
+    withPage: <T>(fn: (page: Page) => Promise<T>) => Promise<T>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/browser/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/browser/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAE9D,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACzD;;;OAGG;IACH,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC;;;;OAIG;IACH,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;CAC5D"}

package/build/browser/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/browser/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/browser/types.ts"],"names":[],"mappings":""}

package/build/browser.d.ts

@@ -1,19 +1,11 @@
-import type { Browser, LaunchOptions } from 'playwright';
-/**
- * Launch (or return) a single shared chromium instance for the current
- * `bun test` process. UI specs hold a fixture page off this browser; the
- * suite calls `closeBrowser()` from `afterAll` to tear it down once.
- */
+import type { Browser, LaunchOptions, Page } from 'playwright';
+import type { BrowserHelper } from './browser/types.js';
+export declare const createBrowserHelper: () => BrowserHelper;
+export declare const browserHelper: BrowserHelper;
+/** @deprecated compat:factory-refactor — use `browserHelper.launchBrowser(…)` */
 export declare const launchBrowser: (opts?: LaunchOptions) => Promise<Browser>;
-/**
- * Tear down the shared browser. Idempotent — safe to call from multiple
- * `afterAll` hooks.
- */
+/** @deprecated compat:factory-refactor — use `browserHelper.closeBrowser()` */
 export declare const closeBrowser: () => Promise<void>;
-/**
- * Convenience that launches the browser, runs a callback with a fresh
- * context + page, and closes the context on completion. The browser
- * itself stays alive across calls so multiple specs share it cheaply.
- */
-export declare const withPage: <T>(fn: (page: import('playwright').Page) => Promise<T>) => Promise<T>;
+/** @deprecated compat:factory-refactor — use `browserHelper.withPage(…)` */
+export declare const withPage: <T>(fn: (page: Page) => Promise<T>) => Promise<T>;
 //# sourceMappingURL=browser.d.ts.map

package/build/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAKxD;;;;GAIG;AACH,eAAO,MAAM,aAAa,UAAgB,aAAa,KAAQ,OAAO,CAAC,OAAO,CAO7E,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAa,OAAO,CAAC,IAAI,CAOjD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,MAC1B,CAAC,IAAI,EAAE,OAAO,YAAY,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAClD,OAAO,CAAC,CAAC,CASX,CAAA"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAMvD,eAAO,MAAM,mBAAmB,QAAO,aA+BtC,CAAA;AAED,eAAO,MAAM,aAAa,eAAwB,CAAA;AAElD,iFAAiF;AACjF,eAAO,MAAM,aAAa,UAAgB,aAAa,KAAQ,OAAO,CAAC,OAAO,CACrC,CAAA;AAEzC,+EAA+E;AAC/E,eAAO,MAAM,YAAY,QAAa,OAAO,CAAC,IAAI,CAAuC,CAAA;AAEzF,4EAA4E;AAC5E,eAAO,MAAM,QAAQ,GAAU,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAC1C,CAAA"}

package/build/browser.js

@@ -1,47 +1,44 @@
 import { chromium } from 'playwright';
+// Process-wide on purpose: every spec of a `bun test` run shares one browser.
 let shared;
 let inflight;
-/**
- * Launch (or return) a single shared chromium instance for the current
- * `bun test` process. UI specs hold a fixture page off this browser; the
- * suite calls `closeBrowser()` from `afterAll` to tear it down once.
- */
-export const launchBrowser = async (opts = {}) => {
-    if (shared != null)
+export const createBrowserHelper = () => {
+    const launchBrowser = async (opts = {}) => {
+        if (shared != null)
+            return shared;
+        if (inflight != null)
+            return inflight;
+        inflight = chromium.launch({ headless: true, ...opts });
+        shared = await inflight;
+        inflight = undefined;
         return shared;
-    if (inflight != null)
-        return inflight;
-    inflight = chromium.launch({ headless: true, ...opts });
-    shared = await inflight;
-    inflight = undefined;
-    return shared;
-};
-/**
- * Tear down the shared browser. Idempotent — safe to call from multiple
- * `afterAll` hooks.
- */
-export const closeBrowser = async () => {
-    const b = shared;
-    shared = undefined;
-    inflight = undefined;
-    if (b != null) {
-        await b.close();
-    }
-};
-/**
- * Convenience that launches the browser, runs a callback with a fresh
- * context + page, and closes the context on completion. The browser
- * itself stays alive across calls so multiple specs share it cheaply.
- */
-export const withPage = async (fn) => {
-    const browser = await launchBrowser();
-    const context = await browser.newContext();
-    const page = await context.newPage();
-    try {
-        return await fn(page);
-    }
-    finally {
-        await context.close();
-    }
+    };
+    const closeBrowser = async () => {
+        const b = shared;
+        shared = undefined;
+        inflight = undefined;
+        if (b != null) {
+            await b.close();
+        }
+    };
+    const withPage = async (fn) => {
+        const browser = await launchBrowser();
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        try {
+            return await fn(page);
+        }
+        finally {
+            await context.close();
+        }
+    };
+    return { launchBrowser, closeBrowser, withPage };
 };
+export const browserHelper = createBrowserHelper();
+/** @deprecated compat:factory-refactor — use `browserHelper.launchBrowser(…)` */
+export const launchBrowser = async (opts = {}) => await browserHelper.launchBrowser(opts);
+/** @deprecated compat:factory-refactor — use `browserHelper.closeBrowser()` */
+export const closeBrowser = async () => await browserHelper.closeBrowser();
+/** @deprecated compat:factory-refactor — use `browserHelper.withPage(…)` */
+export const withPage = async (fn) => await browserHelper.withPage(fn);
 //# sourceMappingURL=browser.js.map

package/build/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGrC,IAAI,MAA2B,CAAA;AAC/B,IAAI,QAAsC,CAAA;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,IAAI,GAAkB,EAAE,EAAoB,EAAE;IAChF,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,MAAM,CAAA;IACjC,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,QAAQ,CAAA;IACrC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,CAAA;IACvD,MAAM,GAAG,MAAM,QAAQ,CAAA;IACvB,QAAQ,GAAG,SAAS,CAAA;IACpB,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,IAAmB,EAAE;IACpD,MAAM,CAAC,GAAG,MAAM,CAAA;IAChB,MAAM,GAAG,SAAS,CAAA;IAClB,QAAQ,GAAG,SAAS,CAAA;IACpB,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QACd,MAAM,CAAC,CAAC,KAAK,EAAE,CAAA;IACjB,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAC3B,EAAmD,EACvC,EAAE;IACd,MAAM,OAAO,GAAG,MAAM,aAAa,EAAE,CAAA;IACrC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAA;IAC1C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;IACpC,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,IAAI,CAAC,CAAA;IACvB,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAA;IACvB,CAAC;AACH,CAAC,CAAA"}
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAIrC,8EAA8E;AAC9E,IAAI,MAA2B,CAAA;AAC/B,IAAI,QAAsC,CAAA;AAE1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAkB,EAAE;IACrD,MAAM,aAAa,GAAG,KAAK,EAAE,IAAI,GAAkB,EAAE,EAAoB,EAAE;QACzE,IAAI,MAAM,IAAI,IAAI;YAAE,OAAO,MAAM,CAAA;QACjC,IAAI,QAAQ,IAAI,IAAI;YAAE,OAAO,QAAQ,CAAA;QACrC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,CAAA;QACvD,MAAM,GAAG,MAAM,QAAQ,CAAA;QACvB,QAAQ,GAAG,SAAS,CAAA;QACpB,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IAED,MAAM,YAAY,GAAG,KAAK,IAAmB,EAAE;QAC7C,MAAM,CAAC,GAAG,MAAM,CAAA;QAChB,MAAM,GAAG,SAAS,CAAA;QAClB,QAAQ,GAAG,SAAS,CAAA;QACpB,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;YACd,MAAM,CAAC,CAAC,KAAK,EAAE,CAAA;QACjB,CAAC;IACH,CAAC,CAAA;IAED,MAAM,QAAQ,GAAG,KAAK,EAAK,EAA8B,EAAc,EAAE;QACvE,MAAM,OAAO,GAAG,MAAM,aAAa,EAAE,CAAA;QACrC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAA;QAC1C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;QACpC,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,IAAI,CAAC,CAAA;QACvB,CAAC;gBAAS,CAAC;YACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAA;QACvB,CAAC;IACH,CAAC,CAAA;IAED,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAA;AAClD,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAA;AAElD,iFAAiF;AACjF,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,IAAI,GAAkB,EAAE,EAAoB,EAAE,CAChF,MAAM,aAAa,CAAC,aAAa,CAAC,IAAI,CAAC,CAAA;AAEzC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,IAAmB,EAAE,CAAC,MAAM,aAAa,CAAC,YAAY,EAAE,CAAA;AAEzF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAK,EAA8B,EAAc,EAAE,CAC9E,MAAM,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA"}

package/build/consent/types.d.ts

@@ -0,0 +1,36 @@
+import type { BrowserContext, Page } from 'playwright';
+/**
+ * A fake answer from Cloudflare's trace endpoint: a country code (`'US'`), or
+ * `{ country?, fail?, delayMs?, gpc? }`.
+ */
+export type ConsentGeoMock = string | ConsentGeoMockOptions;
+export interface ConsentGeoMockOptions {
+    /** The `loc=` the fake trace answers with. Defaults to `PL` — a consent country. */
+    country?: string;
+    /** `true` answers 404 (the host is not behind Cloudflare); `'hang'` never answers. */
+    fail?: boolean | 'hang';
+    /** Answer only after this many ms — long enough to see the spinner. */
+    delayMs?: number;
+    /** Send Global Privacy Control (`navigator.globalPrivacyControl`). */
+    gpc?: boolean;
+    /** The trace path the page asks. Defaults to `/cdn-cgi/trace`. */
+    path?: string;
+}
+/**
+ * Pinning where a visitor is, so a consent test does not depend on where its runner happens to be:
+ * every app behind Cloudflare answers the trace with the RUNNER's country.
+ */
+export interface ConsentGeoTestHelper {
+    /**
+     * Answer the page's same-origin trace request from inside the page: an init script that wraps
+     * `window.fetch` before any page script runs, and counts the calls in
+     * `window.__consentTraceCalls`. Never `page.route` — interception disables the cache for every
+     * request, and a vite-served application stalls on its hundreds of unbundled modules.
+     *
+     * Applies to the NEXT navigation of the page or context it is installed on.
+     */
+    mockConsentGeo: (target: Page | BrowserContext, geo: ConsentGeoMock) => Promise<void>;
+    /** How many trace requests the page made since it loaded (`mockConsentGeo` only). */
+    traceCalls: (page: Page) => Promise<number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/consent/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/consent/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,qBAAqB,CAAA;AAE3D,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sFAAsF;IACtF,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IACvB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,IAAI,GAAG,cAAc,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACrF,qFAAqF;IACrF,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5C"}

package/build/consent/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/consent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/consent/types.ts"],"names":[],"mappings":""}