steppy-dev 0.3.0__py3-none-any.whl

steppy/templates/conftest.py.j2

@@ -0,0 +1,2405 @@
+"""
+Auto-generated by Steppy. Do not edit manually — changes will be overwritten.
+Re-generate with: steppy generate
+"""
+import base64
+import hashlib
+import hmac
+import json
+import os
+import re
+import time
+import warnings
+from pathlib import Path
+
+import pytest
+import yaml
+from playwright.sync_api import Browser, BrowserContext, Page, expect
+
+# ── Config ──────────────────────────────────────────────────────────────────
+
+CONFIG_PATH = Path(__file__).parent.parent.parent / "config.yaml"
+CREDENTIALS_PATH = Path(__file__).parent.parent.parent / "credentials.yaml"
+AUTH_DIR = Path(__file__).parent.parent.parent / ".auth"
+# SCREENSHOTS_DIR is defined after CONFIG loads — it is resolved from
+# `config.output.screenshots_dir` at runtime (see below).
+TRACES_DIR = Path(__file__).parent.parent.parent / "output" / "traces"
+VIDEOS_DIR = Path(__file__).parent.parent.parent / "output" / "videos"
+
+# Playwright trace mode (FLAWS §6.1): "" (off) | "on" | "on-failure". Set by
+# `steppy run --trace` / config.report.trace via the STEPPY_TRACE env var. When
+# off, the trace helpers below are complete no-ops (byte-identical behavior).
+TRACE_MODE = os.environ.get("STEPPY_TRACE", "")
+
+# Playwright video mode (FLAWS §6.1): "" (off) | "on" | "on-failure". Set by
+# `steppy run --video` / config.report.video via the STEPPY_VIDEO env var. When
+# off, `_video_context_kwargs()` returns {} so `new_context` is byte-identical.
+VIDEO_MODE = os.environ.get("STEPPY_VIDEO", "")
+
+# Static default viewport from config. NOTE: the per-screenshot sidecar records
+# the *actual* runtime viewport via `page.viewport_size`
+# (see take_screenshot_with_bbox) so the guide renderer scales cursor bounding
+# boxes against the size the browser truly ran at — not this default — which
+# matters when `screenshot.layouts` declares per-layout viewports.
+VIEWPORT_FOR_CURSOR = {"width": {{ config.screenshot.viewport.width }}, "height": {{ config.screenshot.viewport.height }}}
+SCREENSHOT_FULL_PAGE = {{ "True" if config.screenshot.full_page else "False" }}
+
+# Named layouts (e.g. desktop/mobile). Empty unless `screenshot.layouts` is
+# declared in config.yaml. Populated layouts let `steppy run --guide` (or
+# `--layouts ...`) parametrize fixtures over per-layout viewports.
+LAYOUT_VIEWPORTS = {
+{%- for name, layout in config.screenshot.layouts.items() %}
+    {{ name | tojson }}: {"width": {{ layout.width }}, "height": {{ layout.height }}},
+{%- endfor %}
+}
+
+# Per-layout capture devicePixelRatio (mirrors LAYOUT_VIEWPORTS). A value >1
+# makes Playwright render the page at that pixel density, so narrow (e.g.
+# mobile) captures carry enough pixels to stay crisp when the guide displays
+# them at the content-column width. Layouts without an entry fall back to
+# `_get_scale_factor()` (the `screenshot.device_scale_factor` default, itself 1
+# unless configured). This does NOT set is_mobile/has_touch — only density.
+LAYOUT_SCALE_FACTORS = {
+{%- for name, layout in config.screenshot.layouts.items() %}
+    {{ name | tojson }}: {{ layout.device_scale_factor }},
+{%- endfor %}
+}
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Recursively merge override into base. Override values win."""
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+_ENV_REF = re.compile(r"\$\{([A-Za-z_]\w*)(?::-([^}]*))?\}")
+
+
+def _interp_env(obj):
+    """Substitute ${VAR} / ${VAR:-default} in every string leaf of the config.
+
+    Mirrors steppy.config._interpolate_env so ${ENV_VAR} references (e.g. auth
+    credentials) resolve at test runtime from the worker/CI environment. Silent:
+    an unset var with no default is left as the literal ${...}.
+    """
+    if isinstance(obj, dict):
+        return {k: _interp_env(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_interp_env(v) for v in obj]
+    if isinstance(obj, str):
+        def _sub(m):
+            name, default = m.group(1), m.group(2)
+            if name in os.environ:
+                return os.environ[name]
+            if default is not None:
+                return default
+            return m.group(0)
+        return _ENV_REF.sub(_sub, obj)
+    return obj
+
+
+with open(CONFIG_PATH) as f:
+    CONFIG = yaml.safe_load(f)
+
+if CREDENTIALS_PATH.exists():
+    with open(CREDENTIALS_PATH) as f:
+        _creds = yaml.safe_load(f)
+    if _creds:
+        CONFIG = _deep_merge(CONFIG, _creds)
+
+# Resolve ${VAR} references against the environment (after the overlay merge).
+CONFIG = _interp_env(CONFIG)
+
+# Per-app URL overrides for parallel mode. ``steppy run --workers N >= 2``
+# runs workers inside the Docker stack network, where the host-facing
+# ``apps.<role>.url`` (e.g. http://localhost:4200) doesn't resolve. The
+# coordinator passes a JSON {role: internal_url} map; we splice it into
+# CONFIG so every downstream reference to ``app["url"]`` keeps working
+# unchanged. Unset (the default in single-worker mode) → no-op.
+_BASE_URL_OVERRIDE = __import__("os").environ.get("STEPPY_BASE_URL_OVERRIDE", "").strip()
+if _BASE_URL_OVERRIDE:
+    try:
+        for _role, _url in json.loads(_BASE_URL_OVERRIDE).items():
+            if _role in CONFIG.get("apps", {}):
+                CONFIG["apps"][_role]["url"] = _url
+    except (json.JSONDecodeError, TypeError, AttributeError):
+        pass  # malformed override silently ignored; coordinator validates upstream
+
+# Capture root. Resolved from config at runtime — NOT baked at generate time —
+# so editing config.yaml takes effect without re-running ``steppy generate``,
+# and the generated file stays identical for every project. Same mechanism as
+# COVERAGE_RAW_DIR below, and the same value ``steppy guide`` / ``steppy build``
+# default to, so the writer and its readers cannot disagree (FLAWS §4.6).
+# The double fallback is load-bearing: CONFIG is raw YAML, so an absent
+# ``output:`` block is None here and pydantic's default_factory never runs.
+SCREENSHOTS_DIR = Path(__file__).parent.parent.parent / (
+    (CONFIG.get("output") or {}).get("screenshots_dir") or "output/screenshots"
+)
+
+# Tolerate empty-string values: the parallel coordinator's compose override
+# sets these env vars to '' (rather than unsetting them) for the false case,
+# and ``int('')`` would raise. Treat unset OR empty as "0".
+HEADED = bool(int(__import__("os").environ.get("HEADED") or "0"))
+SCREENSHOTS_ENABLED = bool(int(__import__("os").environ.get("STEPPY_SCREENSHOTS") or "0"))
+SKIP_ASSERTS = bool(int(__import__("os").environ.get("STEPPY_NO_ASSERTS") or "0"))
+# Set by ``steppy run --guide``. Steps gated with ``only-in: test`` are skipped
+# when this is True; ``only-in: guide`` are skipped when False.
+GUIDE_MODE = bool(int(__import__("os").environ.get("STEPPY_GUIDE_MODE") or "0"))
+
+# Coverage recording. Set by ``steppy run --coverage``; off by default — the
+# recorder helpers below return/accept ``None`` and plain runs attach no
+# listeners, no init scripts, and no CDP session. The run id groups every
+# record of one run under ``<records_dir>/raw/<run_id>/``; the parallel
+# coordinator already exports STEPPY_RUN_ID, so worker records from all
+# stacks land in the same shared run directory on the output/ bind mount.
+COVERAGE_ENABLED = bool(int(__import__("os").environ.get("STEPPY_COVERAGE") or "0"))
+COVERAGE_RUN_ID = (__import__("os").environ.get("STEPPY_RUN_ID") or "").strip() or time.strftime(
+    "%Y%m%dT%H%M%SZ", time.gmtime()
+)
+COVERAGE_RAW_DIR = (
+    Path(__file__).parent.parent.parent
+    / ((CONFIG.get("coverage") or {}).get("records_dir") or "output/coverage")
+    / "raw"
+)
+
+# Locale parametrization. When STEPPY_LOCALES is set (typically by
+# ``steppy run --guide``), each role fixture is parametrized over these
+# locales — the configured app i18n.localstorage value is injected before any
+# page script runs and screenshots land under
+# ``output/screenshots/<scenario>/<locale>/``. When unset, fixtures run once
+# with no locale forced and screenshots use the flat per-scenario folder.
+_LOCALES_ENV = __import__("os").environ.get("STEPPY_LOCALES", "").strip()
+LOCALES_FOR_RUN = [l for l in _LOCALES_ENV.split(",") if l] or [None]
+CURRENT_LOCALE: "str | None" = None
+
+# Layout parametrization. Set by ``steppy run --guide`` (or ``--layouts``) when
+# ``screenshot.layouts`` is configured. Each test is parametrized over the
+# cartesian product of LOCALES_FOR_RUN × LAYOUTS_FOR_RUN, with every role page
+# it requests bound in lockstep (see pytest_generate_tests). Screenshots land
+# under ``output/screenshots/<scenario>/[<locale>/]<layout>/``. When unset
+# (default), no layout dimension is added and the path stays flat.
+_LAYOUTS_ENV = __import__("os").environ.get("STEPPY_LAYOUTS", "").strip()
+LAYOUTS_FOR_RUN = [l for l in _LAYOUTS_ENV.split(",") if l] or [None]
+CURRENT_LAYOUT: "str | None" = None
+
+# Layout name treated as active when no explicit layout is parametrized.
+# Matches the default Playwright viewport (desktop-sized) and lets the
+# ``layouts:`` step filter act as a "this step is for that layout" gate even
+# in test mode.
+DEFAULT_TEST_LAYOUT = "desktop"
+
+# Events-plugin opt-in: pull the plugin's hook functions into the conftest
+# namespace so pytest collects them as if they were defined here. Two
+# independent gates, because the plugin has two independent sinks:
+#
+#   STEPPY_EMIT_EVENTS=1     stdout ``STEPPY-EVT::`` lines, parsed live by the
+#                            parallel coordinator (``steppy run --workers N``)
+#   STEPPY_EVENTS_DIR=<dir>  per-test JSONL, consumed by ``steppy bundle create``
+#                            (``steppy run --bundle``)
+#
+# A plain single-worker run sets neither and the import never happens, keeping
+# pytest output byte-identical to the historic behaviour.
+#
+# Why direct import and not ``pytest_plugins = [...]`` — pytest 8 hard-fails
+# when ``pytest_plugins`` is declared in a non-rootdir conftest (this conftest
+# lives at ``tests/e2e/conftest.py``). Direct import sidesteps that
+# restriction: pytest just discovers hook names in the conftest module.
+#
+# The imported names must never collide with a hook this conftest defines
+# itself (``pytest_generate_tests``, ``pytest_collection_modifyitems``,
+# ``pytest_runtest_makereport``) — the import would silently shadow it.
+if __import__("os").environ.get("STEPPY_EMIT_EVENTS") == "1" or __import__("os").environ.get("STEPPY_EVENTS_DIR"):
+    import sys as _sys
+    _sys.path.insert(0, str(Path(__file__).resolve().parent))
+    try:
+        from _steppy_events import (
+            pytest_configure,
+            pytest_collection_finish,
+            pytest_runtest_protocol,
+            pytest_runtest_logstart,
+            pytest_runtest_logreport,
+            pytest_sessionfinish,
+        )
+    except ImportError as _evt_err:
+        # ``_steppy_events.py`` missing or stale (an older ``steppy generate``
+        # output predating a hook this import expects). Emit a warning event so
+        # the coordinator can surface it to the user — without the plugin, only
+        # synthetic per-scenario test counts reach the live progress UI, and a
+        # results bundle's ``tests[]`` will be empty. Re-run ``steppy generate``
+        # to restore it.
+        print(
+            "STEPPY-EVT::warning::events-plugin-missing::"
+            + str(_evt_err)
+            + " (run `steppy generate` to refresh tests/e2e/)",
+            flush=True,
+        )
+
+
+def _step_runs(only_in, layouts):
+    """Return False when a step's ``only-in`` / ``layouts`` filters exclude it
+    from the current run. Centralises the predicate so generated test files can
+    just call ``if _step_runs(...): <body>``.
+
+    - ``only-in: test`` → skip in guide mode
+    - ``only-in: guide`` → skip outside guide mode
+    - ``layouts: [...]`` → step runs iff the active layout is in the whitelist.
+      The active layout is ``CURRENT_LAYOUT`` when a layout is parametrized,
+      otherwise ``DEFAULT_TEST_LAYOUT`` (the default Playwright viewport is
+      desktop-sized, so a step gated to ``layouts: [mobile]`` is skipped in
+      plain test mode).
+    """
+    if only_in == "test" and GUIDE_MODE:
+        return False
+    if only_in == "guide" and not GUIDE_MODE:
+        return False
+    if layouts:
+        active = CURRENT_LAYOUT or DEFAULT_TEST_LAYOUT
+        if active not in layouts:
+            return False
+    return True
+
+
+# ── Per-step events (STEPPY_STEP_EVENTS) ────────────────────────────────────
+#
+# Every generated step body is bracketed by ``_steppy_mark_step`` /
+# ``_steppy_end_step``. Off, they are one env lookup each. On, they write
+# ``step-start`` / ``step-end`` records into the same per-test JSONL the events
+# plugin already owns, which is what lets a results bundle report WHICH step a
+# test died in (``manifest.tests[].failed_step``) instead of only that it died.
+#
+# The calls are emitted unconditionally by the generator, never gated at
+# template time, so a generated test file does not depend on the environment it
+# was generated in.
+
+STEP_EVENTS = os.environ.get("STEPPY_STEP_EVENTS") == "1"
+
+
+def _steppy_current_nodeid():
+    """The running test's pytest node id, or None.
+
+    ``PYTEST_CURRENT_TEST`` is ``"<nodeid> (call)"`` — the phase suffix is
+    appended by pytest, so strip the LAST " (" group rather than splitting from
+    the left, since a parametrized id can legitimately contain " (".
+    """
+    raw = os.environ.get("PYTEST_CURRENT_TEST")
+    if not raw:
+        return None
+    return raw.rsplit(" (", 1)[0] or None
+
+
+def _steppy_step_record(kind, step_number, **fields):
+    """Write one step record. Never raises — a broken sink must not fail a test.
+
+    The sink is the events plugin's ``_record``, so step records land in the
+    same ``<scenario>__<locale>-<layout>.jsonl`` as the test records and inherit
+    their scenario/locale/layout attribution for free. It is only importable
+    when the events gate above put this directory on ``sys.path``, and it
+    early-returns when no events dir is configured — so step events are
+    automatically inert outside a ``steppy run --bundle``.
+    """
+    if not STEP_EVENTS:
+        return
+    try:
+        from _steppy_events import _record
+
+        _record(kind, _steppy_current_nodeid(), step=step_number, **fields)
+    except Exception:
+        pass
+
+
+def _steppy_mark_step(step_number, step_title, action):
+    """Mark the start of a step."""
+    _steppy_step_record("step-start", step_number, title=step_title, action=action)
+
+
+def _steppy_end_step(step_number):
+    """Mark a step as completed.
+
+    Deliberately NOT emitted from a ``finally``: a step that raises must leave
+    its ``step-start`` unclosed, because that unclosed marker IS the answer to
+    "which step failed". A test that dies in fixture teardown closes every step
+    it ran and therefore correctly reports no failed step at all.
+    """
+    _steppy_step_record("step-end", step_number)
+
+
+# ── Auth helpers ────────────────────────────────────────────────────────────
+
+def _get_storage_state(role: str) -> str | None:
+    """Return path to cached auth state if valid, else None."""
+    state_path = AUTH_DIR / f"{role}.json"
+    if not state_path.exists():
+        return None
+    ttl = CONFIG.get("auth", {}).get("storage_state_ttl", 3600)
+    if time.time() - state_path.stat().st_mtime > ttl:
+        return None
+    return str(state_path)
+
+
+_DEFAULT_VIEWPORT = {"width": 1280, "height": 720}
+
+_FORM_DEFAULTS = {
+    "username_selector": "input[name='username']",
+    "password_selector": "input[name='password']",
+    "submit_selector": "button[data-action-button-primary='true']",
+}
+
+
+def _form_selectors() -> dict:
+    """Merge the login-form selector defaults with the configured overrides.
+
+    Accepts both the current ``auth.form`` block and the legacy ``auth.auth0``
+    key (mode ``auth0`` was renamed ``form`` in FLAWS §6.2; CONFIG here is raw
+    YAML, so both spellings can still reach us)."""
+    auth = CONFIG.get("auth", {})
+    overrides = auth.get("form") or auth.get("auth0") or {}
+    return {**_FORM_DEFAULTS, **overrides}
+
+
+def _get_viewport() -> dict:
+    """Return viewport config with sensible defaults."""
+    return CONFIG.get("screenshot", {}).get("viewport", _DEFAULT_VIEWPORT)
+
+
+def _get_viewport_for_layout(layout) -> dict:
+    """Pick the viewport for the active layout. Falls back to the default
+    viewport when no layout is set or the layout name has no entry in
+    ``LAYOUT_VIEWPORTS`` (which would only happen if a CLI ran with a layout
+    name that wasn't declared in config — the validator should catch that)."""
+    if layout and layout in LAYOUT_VIEWPORTS:
+        return LAYOUT_VIEWPORTS[layout]
+    return _get_viewport()
+
+
+def _get_scale_factor() -> int:
+    """Default capture devicePixelRatio (used for the no-layout viewport and as
+    the fallback for layouts that don't override it)."""
+    return CONFIG.get("screenshot", {}).get("device_scale_factor", 1)
+
+
+def _get_scale_factor_for_layout(layout) -> int:
+    """Pick the capture devicePixelRatio for the active layout, mirroring
+    ``_get_viewport_for_layout``. Falls back to the default scale factor when no
+    layout is set or the layout has no entry in ``LAYOUT_SCALE_FACTORS``."""
+    if layout and layout in LAYOUT_SCALE_FACTORS:
+        return LAYOUT_SCALE_FACTORS[layout]
+    return _get_scale_factor()
+
+
+def _totp_now(secret: str, digits: int = 6, period: int = 30) -> str:
+    """Current TOTP code for a base32 ``secret`` (RFC 6238, HMAC-SHA1)."""
+    key = base64.b32decode(secret.strip().replace(" ", "").upper() + "=" * (-len(secret.strip().replace(" ", "")) % 8))
+    counter = int(time.time()) // period
+    mac = hmac.new(key, counter.to_bytes(8, "big"), hashlib.sha1).digest()
+    offset = mac[-1] & 0x0F
+    code = (int.from_bytes(mac[offset : offset + 4], "big") & 0x7FFFFFFF) % (10**digits)
+    return str(code).zfill(digits)
+
+
+def _fill_totp(page: Page, form: dict, credentials: dict) -> None:
+    """Fill a TOTP/MFA code after the password submit, when configured (FLAWS §6.2).
+
+    No-op unless both ``auth.form.totp_selector`` and the app credentials'
+    ``totp_secret`` are set. Tolerates a missing prompt (trusted device)."""
+    totp_selector = form.get("totp_selector")
+    totp_secret = credentials.get("totp_secret")
+    if not totp_selector or not totp_secret:
+        return
+    try:
+        page.wait_for_selector(totp_selector, timeout=10000)
+    except Exception:
+        return  # no MFA prompt this session — nothing to fill
+    page.fill(totp_selector, _totp_now(totp_secret))
+    submit = form.get("totp_submit_selector") or form["submit_selector"]
+    page.locator(submit).click()
+    page.wait_for_load_state("networkidle", timeout=15000)
+
+
+def fill_login_credentials(page: Page, role: str) -> None:
+    """Fill the hosted login form with credentials from config. Call after the
+    login page appears.
+
+    Handles both single-page and two-step (identifier-first) flows. Works
+    against any IdP (Auth0, Keycloak, …) via the ``auth.form`` selectors.
+    """
+    app = CONFIG["apps"][role]
+    form = _form_selectors()
+
+    # Step 1: Fill username / email
+    page.wait_for_selector(form["username_selector"], timeout=15000)
+    page.fill(form["username_selector"], app["auth"]["credentials"]["username"])
+
+    # Check if password field is already visible (single-page flow)
+    pwd_visible = page.locator(form["password_selector"]).is_visible()
+
+    if pwd_visible:
+        # Single-page: fill password and submit once
+        page.fill(form["password_selector"], app["auth"]["credentials"]["password"])
+        page.locator(form["submit_selector"]).click()
+        page.wait_for_load_state("networkidle", timeout=15000)
+    else:
+        # Two-step (identifier-first): submit username, wait for password field
+        page.locator(form["submit_selector"]).click()
+        page.wait_for_selector(form["password_selector"], timeout=15000)
+        page.fill(form["password_selector"], app["auth"]["credentials"]["password"])
+        page.locator(form["submit_selector"]).click()
+        page.wait_for_load_state("networkidle", timeout=15000)
+
+    # Optional TOTP/MFA step (no-op unless configured)
+    _fill_totp(page, form, app["auth"]["credentials"])
+
+    # Handle optional consent screen
+    consent = form.get("consent_selector")
+    if consent:
+        try:
+            page.wait_for_selector(consent, timeout=3000)
+            page.click(consent)
+        except Exception:
+            pass
+
+
+# Back-compat alias (the action/helper was historically named ``auth0``).
+fill_auth0_credentials = fill_login_credentials
+
+
+def _new_role_context(browser: Browser, role: str, **extra) -> BrowserContext:
+    """Create a browser context configured for ``role``.
+
+    Single definition of what a Steppy context IS: the layout's viewport and
+    capture density, the app's base URL, the browser locale/timezone, video
+    recording when enabled, and the insecure-origin polyfill.
+
+    Every auth mode builds its context here. Previously each of the six call
+    sites spelled the kwargs out, so every browser-capability feature
+    (device_scale_factor, video, locale/timezone, the polyfill) had to be
+    threaded through all six — and missing one silently degraded a single auth
+    mode with no test failure.
+
+    ``extra`` carries per-mode kwargs, e.g. ``storage_state=``.
+    """
+    app = CONFIG["apps"][role]
+    context = browser.new_context(
+        viewport=_get_viewport_for_layout(CURRENT_LAYOUT),
+        device_scale_factor=_get_scale_factor_for_layout(CURRENT_LAYOUT),
+        base_url=app["url"],
+        locale=_resolve_browser_locale(role),
+        timezone_id=_resolve_browser_timezone(role),
+        **_video_context_kwargs(),
+        **extra,
+    )
+    _apply_insecure_origin_polyfill(context)
+    return context
+
+
+def _authenticate_auth0(browser: Browser, role: str) -> BrowserContext:
+    """Perform Auth0 login and cache the storage state."""
+    app = CONFIG["apps"][role]
+
+    context = _new_role_context(browser, role)
+    page = context.new_page()
+    page.goto("/")
+
+    fill_login_credentials(page, role)
+
+    # Wait for redirect back to app
+    page.wait_for_url(f"{app['url']}/**", timeout=15000)
+    page.wait_for_load_state("networkidle")
+
+    # Cache state
+    AUTH_DIR.mkdir(parents=True, exist_ok=True)
+    context.storage_state(path=str(AUTH_DIR / f"{role}.json"))
+    page.close()
+    return context
+
+
+def get_authenticated_context(browser: Browser, role: str) -> BrowserContext:
+    """Get an authenticated browser context for the given role."""
+    app = CONFIG["apps"][role]
+    mode = app["auth"]["mode"]
+
+    if mode in ("form", "auth0"):
+        state = _get_storage_state(role)
+        if state:
+            return _new_role_context(browser, role, storage_state=state)
+        return _authenticate_auth0(browser, role)
+
+    elif mode == "storage-state":
+        return _new_role_context(browser, role, storage_state=app["auth"]["storage_state_path"])
+
+    elif mode == "bypass":
+        context = _new_role_context(browser, role)
+        bypass = app["auth"].get("bypass", {})
+        if bypass.get("cookie"):
+            context.add_cookies([bypass["cookie"]])
+        return context
+
+    elif mode == "token":
+        return _authenticate_token(browser, role)
+
+    else:
+        raise ValueError(f"Unknown auth mode: {mode}")
+
+
+def _authenticate_token(browser: Browser, role: str) -> BrowserContext:
+    """Fetch a token from the configured endpoint and inject it (FLAWS §6.2).
+
+    Mirrors ``steppy.auth.authenticate_token`` but uses the stdlib
+    (``urllib``/``json``) so generated projects need no extra runtime deps.
+    ``inject_as``: ``localStorage`` | ``cookie`` | ``header``.
+    """
+    import urllib.request
+    from urllib.parse import urlparse
+
+    app = CONFIG["apps"][role]
+    token_cfg = app["auth"].get("token")
+    if not token_cfg:
+        raise ValueError(f"Token auth for role '{role}' requires apps.{role}.auth.token")
+
+    body = token_cfg.get("body")
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(
+        token_cfg["endpoint"],
+        data=data,
+        method=token_cfg.get("method", "POST"),
+        headers={"Content-Type": "application/json"} if data is not None else {},
+    )
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        payload = json.loads(resp.read().decode("utf-8"))
+    token = payload.get("token") or payload.get("access_token") or payload
+    if not isinstance(token, str):
+        raise ValueError(f"Token endpoint returned invalid data for role '{role}'")
+
+    inject_as = token_cfg["inject_as"]
+    key = token_cfg["key"]
+
+    context = _new_role_context(browser, role)
+
+    if inject_as == "header":
+        # Default request header on the context; `key` is the header name.
+        context.set_extra_http_headers({key: token})
+    elif inject_as == "cookie":
+        domain = urlparse(app["url"]).hostname
+        if not domain:
+            raise ValueError(f"Cannot derive a cookie domain from apps.{role}.url")
+        context.add_cookies([{"name": key, "value": token, "domain": domain, "path": "/"}])
+    elif inject_as == "localStorage":
+        page = context.new_page()
+        page.goto(app["url"])
+        # Pass key/token as arguments (not interpolated) — the token is
+        # network-sourced and could contain a quote (mirrors FLAWS §3.3).
+        page.evaluate("([k, v]) => localStorage.setItem(k, v)", [key, token])
+        page.close()
+    else:
+        raise ValueError(f"Unknown token inject_as: {inject_as}")
+
+    return context
+
+
+# ── Locale init script ──────────────────────────────────────────────────────
+
+# Warned-about (role, locale) pairs, so a 40-scenario run reports each gap once
+# rather than once per test.
+_LOCALE_NOT_SWITCHABLE: set = set()
+
+
+def _base_language(tag: str) -> str:
+    """Bare language subtag of ``tag``, lowercased (``fr-BE`` -> ``fr``).
+
+    **Byte-mirrored** from ``base_language`` in ``src/steppy/locales.py`` --
+    generated tests are standalone and cannot import steppy, so the body lives
+    in both places. Guard: ``tests/test_conftest_locale_mirror.py``. Apply any
+    change to both.
+    """
+    return tag.replace("_", "-").split("-", 1)[0].lower()
+
+
+def _warn_locale_not_switchable(role: str, locale: str, declared) -> None:
+    """Report that the app was NOT switched into ``locale``.
+
+    Skipping silently is the worst option available here, and it is what this
+    used to do: the run still captures a full set of screenshots and still files
+    them under the locale's directory, so ``steppy build`` publishes one
+    language's screenshots on another language's page and nothing at any stage
+    reports a problem. A warning lands in pytest's summary without ``-s``.
+    """
+    marker = (role, locale)
+    if marker in _LOCALE_NOT_SWITCHABLE:
+        return
+    _LOCALE_NOT_SWITCHABLE.add(marker)
+    warnings.warn(
+        f"apps.{role}.i18n.localstorage.values has no entry for locale {locale!r} "
+        f"(declared: {', '.join(declared) or 'none'}), so the app was not switched "
+        f"into it. Screenshots for this locale will show the app's default language "
+        f"while being filed under {locale!r}/. Add the entry to config.yaml.",
+        stacklevel=2,
+    )
+
+
+def _apply_locale_init_script(context: BrowserContext, role: str, locale) -> None:
+    """If the app declares ``i18n.localstorage`` and a locale is active, inject
+    a ``localStorage.setItem`` init script so the value is in place before any
+    page script runs. No-op when locale is None or the app has no i18n block.
+
+    A regional locale falls back to its bare language (``fr-BE`` -> ``fr``), the
+    same rung ``GuideText.get`` and ``pick_locale`` use, so a project can add
+    ``fr-BE`` without rewriting its i18n map. When neither key exists the run
+    warns rather than skipping quietly -- see ``_warn_locale_not_switchable``.
+    """
+    if not locale:
+        return
+    app = CONFIG.get("apps", {}).get(role, {})
+    i18n = app.get("i18n") or {}
+    ls = i18n.get("localstorage") or {}
+    key = ls.get("key")
+    values = ls.get("values") or {}
+    if not key:
+        return
+    if locale in values:
+        value = values[locale]
+    else:
+        bare = _base_language(locale)
+        if bare in values:
+            value = values[bare]
+        else:
+            _warn_locale_not_switchable(role, locale, sorted(values))
+            return
+    script = (
+        "try { window.localStorage.setItem("
+        + json.dumps(key) + ", " + json.dumps(value)
+        + "); } catch (e) {}"
+    )
+    context.add_init_script(script)
+
+
+# ── Fixtures ────────────────────────────────────────────────────────────────
+
+_INSECURE_ORIGIN_POLYFILL = r"""
+// Steppy parallel-mode polyfill: make a Docker-internal HTTP origin look
+// like a secure context to the Auth0 SPA SDK (and any other library that
+// gates on Web Crypto).
+//
+// Background: browsers only treat HTTPS / localhost / 127.0.0.1 / *.localhost
+// as secure contexts. ``http://editor-frontend`` reached through Docker DNS
+// is not. The standard escape hatch — Chromium's
+// ``--unsafely-treat-insecure-origin-as-secure`` flag — is silently
+// ignored by Playwright's headless Chromium because Playwright doesn't
+// create the ``Local State`` file Chromium reads for that flag (see
+// microsoft/playwright#22944 and #27768). The flag fix is therefore not
+// available to us; we patch the runtime instead.
+//
+// What we polyfill:
+//   * ``window.isSecureContext`` → true   (some libs check this directly)
+//   * ``window.crypto.subtle.digest('SHA-256', data)``  (the only Web
+//     Crypto operation @auth0/auth0-spa-js performs — PKCE challenge
+//     generation. Token-signature verification is server-side; the SDK
+//     just decodes the JWT to read claims and trusts the back-channel
+//     token-exchange response.)
+//
+// Pure-JS FIPS 180-2 SHA-256. Returns a Promise<ArrayBuffer> so the
+// signature matches the real Web Crypto API; auth0-spa-js does
+// ``await crypto.subtle.digest(...)``.
+(() => {
+  try {
+    Object.defineProperty(window, 'isSecureContext', {
+      configurable: true, get: () => true,
+    });
+  } catch (e) { /* readonly in some builds; not fatal */ }
+
+  const K = new Uint32Array([
+    0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,
+    0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,
+    0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,
+    0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,
+    0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,
+    0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,
+    0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,
+    0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2,
+  ]);
+  const rotr = (x, n) => ((x >>> n) | (x << (32 - n))) >>> 0;
+
+  function sha256(bytes) {
+    const len = bytes.length;
+    const padded = new Uint8Array(((len + 9 + 63) >> 6) << 6);
+    padded.set(bytes);
+    padded[len] = 0x80;
+    const dv = new DataView(padded.buffer);
+    // length in bits (big-endian, 64-bit). Length fits in 32 bits for our use.
+    dv.setUint32(padded.length - 4, len * 8, false);
+
+    const H = new Uint32Array([
+      0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,
+      0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19,
+    ]);
+    const W = new Uint32Array(64);
+    for (let off = 0; off < padded.length; off += 64) {
+      for (let t = 0; t < 16; t++) W[t] = dv.getUint32(off + t * 4, false);
+      for (let t = 16; t < 64; t++) {
+        const s0 = rotr(W[t-15], 7) ^ rotr(W[t-15], 18) ^ (W[t-15] >>> 3);
+        const s1 = rotr(W[t-2], 17) ^ rotr(W[t-2], 19) ^ (W[t-2] >>> 10);
+        W[t] = (W[t-16] + s0 + W[t-7] + s1) >>> 0;
+      }
+      let a=H[0],b=H[1],c=H[2],d=H[3],e=H[4],f=H[5],g=H[6],h=H[7];
+      for (let t = 0; t < 64; t++) {
+        const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+        const ch = (e & f) ^ ((~e) & g);
+        const T1 = (h + S1 + ch + K[t] + W[t]) >>> 0;
+        const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+        const maj = (a & b) ^ (a & c) ^ (b & c);
+        const T2 = (S0 + maj) >>> 0;
+        h = g; g = f; f = e; e = (d + T1) >>> 0;
+        d = c; c = b; b = a; a = (T1 + T2) >>> 0;
+      }
+      H[0] = (H[0] + a) >>> 0; H[1] = (H[1] + b) >>> 0;
+      H[2] = (H[2] + c) >>> 0; H[3] = (H[3] + d) >>> 0;
+      H[4] = (H[4] + e) >>> 0; H[5] = (H[5] + f) >>> 0;
+      H[6] = (H[6] + g) >>> 0; H[7] = (H[7] + h) >>> 0;
+    }
+    const out = new Uint8Array(32);
+    const outDv = new DataView(out.buffer);
+    for (let i = 0; i < 8; i++) outDv.setUint32(i * 4, H[i], false);
+    return out.buffer;
+  }
+
+  function toBytes(data) {
+    if (data instanceof ArrayBuffer) return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    throw new TypeError('Polyfill digest: expected BufferSource');
+  }
+
+  const subtle = (window.crypto && window.crypto.subtle) || {};
+  const realDigest = subtle.digest && subtle.digest.bind(subtle);
+  const polyfillDigest = (algorithm, data) => {
+    const name = typeof algorithm === 'string' ? algorithm : (algorithm && algorithm.name);
+    if (name === 'SHA-256') {
+      try { return Promise.resolve(sha256(toBytes(data))); }
+      catch (e) { return Promise.reject(e); }
+    }
+    if (realDigest) return realDigest(algorithm, data);
+    return Promise.reject(new Error('Polyfill: unsupported algorithm ' + name));
+  };
+
+  try {
+    if (!window.crypto) window.crypto = {};
+    if (!window.crypto.subtle) {
+      Object.defineProperty(window.crypto, 'subtle', {
+        configurable: true, value: { digest: polyfillDigest },
+      });
+    } else if (!window.crypto.subtle.digest) {
+      window.crypto.subtle.digest = polyfillDigest;
+    }
+  } catch (e) { /* best effort */ }
+})();
+"""
+
+
+def _needs_insecure_origin_polyfill() -> bool:
+    """True when the worker is hitting at least one Docker-internal HTTP
+    origin. In single-worker mode the override is unset and the host's
+    ``http://localhost:<port>`` URLs are already secure contexts — no
+    polyfill needed."""
+    if not _BASE_URL_OVERRIDE:
+        return False
+    try:
+        for url in json.loads(_BASE_URL_OVERRIDE).values():
+            if isinstance(url, str) and url.startswith("http://"):
+                return True
+    except (json.JSONDecodeError, TypeError, AttributeError):
+        return False
+    return False
+
+
+def _apply_insecure_origin_polyfill(context: BrowserContext) -> None:
+    """Inject the secure-context / crypto.subtle polyfill into every page
+    of ``context`` (parallel mode only — no-op otherwise)."""
+    if _needs_insecure_origin_polyfill():
+        context.add_init_script(_INSECURE_ORIGIN_POLYFILL)
+
+
+@pytest.fixture(scope="session")
+def browser_instance(playwright):
+    """Single browser instance shared across all tests."""
+    browser = playwright.chromium.launch(headless=not HEADED)
+    yield browser
+    browser.close()
+
+
+def _locale_id(value):
+    """Pytest param id: locale code, or 'default' when no locale is forced."""
+    return value or "default"
+
+
+def _locale_layout_params():
+    """Cartesian product of LOCALES_FOR_RUN × LAYOUTS_FOR_RUN as a list of
+    ``(locale, layout)`` tuples. Used as the ``params=`` for role fixtures."""
+    return [(locale, layout) for locale in LOCALES_FOR_RUN for layout in LAYOUTS_FOR_RUN]
+
+
+def _locale_layout_id(value):
+    """Pytest param id: ``<locale>-<layout>``, with ``default`` substituted when
+    a dimension is unset. Renders as e.g. ``fr-mobile``, ``default-default``."""
+    locale, layout = value
+    return f"{locale or 'default'}-{layout or 'default'}"
+
+
+# Role page-fixture names, baked from the project's roles. Used by the
+# scenario-layout parametrization hook to spot which fixtures to parametrize.
+_PAGE_FIXTURES = {
+{%- for role in roles %}
+    "{{ role }}_page", "{{ role }}_page_noauth",
+{%- endfor %}
+}
+
+
+def _effective_run_layouts(scenario_layouts):
+    """Resolve the layout dimension for one scenario module.
+
+    ``scenario_layouts`` is the module's baked ``SCENARIO_LAYOUTS`` (``None``
+    when the scenario declares none). Semantics:
+      * no declaration -> ``LAYOUTS_FOR_RUN`` unchanged (byte-identical default).
+      * declaration + no run-level ``--layouts`` (``LAYOUTS_FOR_RUN == [None]``)
+        -> the declaration is authoritative (a plain ``steppy run`` parametrizes
+        the whole flow over its declared layouts).
+      * declaration + run-level ``--layouts`` -> intersection in run-selected
+        order (``--layouts``/``--guide`` filters the declared set).
+    An empty result means the scenario's declaration is disjoint from the run
+    selection; ``pytest_collection_modifyitems`` deselects those scenarios."""
+    if not scenario_layouts:
+        return LAYOUTS_FOR_RUN
+    if LAYOUTS_FOR_RUN == [None]:
+        return list(scenario_layouts)
+    return [l for l in LAYOUTS_FOR_RUN if l in scenario_layouts]
+
+
+def pytest_generate_tests(metafunc):
+    """Own the (locale x layout) parametrization of the role page fixtures so a
+    per-scenario ``SCENARIO_LAYOUTS`` can narrow (or, on a plain run, drive) the
+    layout dimension. Modules with no declaration yield exactly
+    ``_locale_layout_params()`` -> collection identical to the pre-feature run.
+
+    Every role page a test requests is bound under ONE ``parametrize`` call, so
+    the roles move in lockstep: a two-role scenario runs once per (locale,
+    layout), not once per pairing of each role's (locale, layout). Separate
+    calls on independent argnames multiply, and the mixed items were not just
+    redundant but wrong — ``CURRENT_LOCALE``/``CURRENT_LAYOUT`` are one global
+    every role fixture writes, so the last one set up decided the screenshot
+    directory for pages that were built at the other role's viewport."""
+    page_fixtures = [f for f in metafunc.fixturenames if f in _PAGE_FIXTURES]
+    if not page_fixtures:
+        return
+    scenario_layouts = getattr(metafunc.module, "SCENARIO_LAYOUTS", None)
+    if not scenario_layouts:
+        params = _locale_layout_params()
+    else:
+        layouts = _effective_run_layouts(scenario_layouts)
+        if not layouts:
+            # Declaration disjoint from the run selection: leave the fixtures
+            # unparametrized (an empty parametrize + id callable would crash on
+            # pytest's empty-set sentinel) — pytest_collection_modifyitems
+            # deselects the item before any fixture runs.
+            return
+        params = [(locale, layout) for locale in LOCALES_FOR_RUN for layout in layouts]
+    if len(page_fixtures) == 1:
+        # A string argname makes pytest wrap each value itself, so request.param
+        # stays the bare (locale, layout) tuple and single-role ids are unchanged.
+        metafunc.parametrize(page_fixtures[0], params, ids=_locale_layout_id, indirect=True)
+        return
+    # An id callable would be applied to each argname's value and the results
+    # hyphen-joined (``fr-mobile-fr-mobile``), hence one precomputed id per set.
+    metafunc.parametrize(
+        page_fixtures,
+        [tuple(p for _ in page_fixtures) for p in params],
+        ids=[_locale_layout_id(p) for p in params],
+        indirect=True,
+    )
+
+
+def pytest_collection_modifyitems(config, items):
+    """Silently deselect scenarios whose declared layouts are disjoint from the
+    run's selected layouts (e.g. ``--layouts mobile`` against a desktop-only
+    scenario); otherwise they'd surface as a spurious 'empty parameter set' skip.
+    No-op when no run-level layout selection is active (nothing can be disjoint)."""
+    if LAYOUTS_FOR_RUN == [None]:
+        return
+    kept, removed = [], []
+    for item in items:
+        scenario_layouts = getattr(item.module, "SCENARIO_LAYOUTS", None)
+        if scenario_layouts and not _effective_run_layouts(scenario_layouts):
+            removed.append(item)
+        else:
+            kept.append(item)
+    if removed:
+        config.hook.pytest_deselected(items=removed)
+        items[:] = kept
+
+
+def _resolve_browser_locale(role: str) -> "str | None":
+    """Pick the Playwright BrowserContext locale for ``role``.
+
+    ``--guide`` runs pass ``STEPPY_LOCALES`` and parametrize the role fixture
+    over those values, setting ``CURRENT_LOCALE`` per parametrization — that
+    wins, so internationalized captures render dates / numbers in the locale
+    they're being captured for. Otherwise the static ``apps.<role>.locale``
+    from config.yaml is used (makes test runs deterministic regardless of host
+    OS or container locale). Returns ``None`` when neither is set — Playwright
+    then uses the browser default (historic behaviour, backwards-compatible).
+    """
+    if CURRENT_LOCALE:
+        return CURRENT_LOCALE
+    return CONFIG.get("apps", {}).get(role, {}).get("locale")
+
+
+def _resolve_browser_timezone(role: str) -> "str | None":
+    """Pick the Playwright BrowserContext ``timezone_id`` for ``role`` from
+    ``apps.<role>.timezone`` in config.yaml. Returns ``None`` when unset."""
+    return CONFIG.get("apps", {}).get(role, {}).get("timezone")
+
+
+# ── Playwright trace (FLAWS §6.1) ─────────────────────────────────────────────
+
+def _maybe_start_trace(context: BrowserContext) -> None:
+    """Start tracing on the context when trace mode is enabled (no-op if off)."""
+    if not TRACE_MODE:
+        return
+    try:
+        context.tracing.start(screenshots=True, snapshots=True, sources=True)
+    except Exception:
+        pass  # tracing is a debug aid; never let it break the test
+
+
+def _maybe_stop_trace(context: BrowserContext, request) -> None:
+    """Stop tracing and, for ``on`` (always) or ``on-failure`` (only failures),
+    save ``output/traces/<nodeid>.zip``. ``_steppy_call_failed`` is stamped by
+    ``pytest_runtest_makereport`` before fixture teardown."""
+    if not TRACE_MODE:
+        return
+    failed = getattr(request.node, "_steppy_call_failed", False)
+    keep = TRACE_MODE == "on" or (TRACE_MODE == "on-failure" and failed)
+    try:
+        if keep:
+            TRACES_DIR.mkdir(parents=True, exist_ok=True)
+            path = TRACES_DIR / f"{_sanitise_nodeid(request.node.nodeid)}.zip"
+            context.tracing.stop(path=str(path))
+            print(f"\n[steppy] trace: {path}", flush=True)
+        else:
+            context.tracing.stop()
+    except Exception:
+        pass
+
+
+# ── Playwright video (FLAWS §6.1) ─────────────────────────────────────────────
+
+def _video_context_kwargs() -> dict:
+    """`record_video_dir=` kwargs for `new_context` when video is on (else {}).
+
+    Unlike tracing (started on the returned context), video must be requested at
+    context-construction time, so this is spliced into every `new_context(...)`.
+    When off it returns {} → the call is byte-identical to the pre-feature form."""
+    if not VIDEO_MODE:
+        return {}
+    VIDEOS_DIR.mkdir(parents=True, exist_ok=True)
+    return {"record_video_dir": str(VIDEOS_DIR)}
+
+
+def _maybe_save_video(video, request) -> None:
+    """Keep (``on`` / failed ``on-failure``) or drop the recorded video.
+
+    ``video`` is the ``page.video`` handle captured before the page/context were
+    closed; Playwright finalizes the file on context close, so this runs after."""
+    if not video:
+        return
+    failed = getattr(request.node, "_steppy_call_failed", False)
+    keep = VIDEO_MODE == "on" or (VIDEO_MODE == "on-failure" and failed)
+    try:
+        if keep:
+            path = VIDEOS_DIR / f"{_sanitise_nodeid(request.node.nodeid)}.webm"
+            video.save_as(str(path))
+            print(f"\n[steppy] video: {path}", flush=True)
+        video.delete()
+    except Exception:
+        pass
+
+
+{% for role in roles %}
+
+@pytest.fixture
+def {{ role }}_page(request, browser_instance) -> Page:
+    """Authenticated {{ role }} browser page. Parametrized (indirect, via
+    ``pytest_generate_tests``) over the cartesian product of STEPPY_LOCALES and
+    the scenario's effective layouts, in lockstep with any other role page the
+    test requests; otherwise yields a single un-localed, default-viewport page."""
+    global CURRENT_LOCALE, CURRENT_LAYOUT
+    locale, layout = request.param
+    CURRENT_LOCALE = locale
+    CURRENT_LAYOUT = layout
+    ctx = get_authenticated_context(browser_instance, "{{ role }}")
+    _maybe_start_trace(ctx)
+    _apply_locale_init_script(ctx, "{{ role }}", locale)
+    page = ctx.new_page()
+    _attach_page_diagnostics(page)
+    _cov = _coverage_start(ctx, page, "{{ role }}", noauth=False)
+    yield page
+    _coverage_stop_and_write(_cov, request)
+    _maybe_stop_trace(ctx, request)
+    _video = page.video if VIDEO_MODE else None
+    page.close()
+    ctx.close()
+    _maybe_save_video(_video, request)
+    CURRENT_LOCALE = None
+    CURRENT_LAYOUT = None
+
+
+@pytest.fixture
+def {{ role }}_page_noauth(request, browser_instance) -> Page:
+    """Unauthenticated {{ role }} browser page (for login-flow scenarios).
+    Parametrized indirect via ``pytest_generate_tests`` (see ``{{ role }}_page``)."""
+    global CURRENT_LOCALE, CURRENT_LAYOUT
+    locale, layout = request.param
+    CURRENT_LOCALE = locale
+    CURRENT_LAYOUT = layout
+    ctx = _new_role_context(browser_instance, "{{ role }}")
+    _maybe_start_trace(ctx)
+    _apply_locale_init_script(ctx, "{{ role }}", locale)
+    page = ctx.new_page()
+    _attach_page_diagnostics(page)
+    _cov = _coverage_start(ctx, page, "{{ role }}", noauth=True)
+    yield page
+    _coverage_stop_and_write(_cov, request)
+    _maybe_stop_trace(ctx, request)
+    _video = page.video if VIDEO_MODE else None
+    page.close()
+    ctx.close()
+    _maybe_save_video(_video, request)
+    CURRENT_LOCALE = None
+    CURRENT_LAYOUT = None
+{% endfor %}
+
+
+# ── Failure debugging ───────────────────────────────────────────────────────
+
+def _sanitise_nodeid(nodeid: str) -> str:
+    """Make a pytest nodeid filesystem-safe for use as a screenshot filename."""
+    return (
+        nodeid
+        .replace("/", "_")
+        .replace("\\", "_")
+        .replace("::", "__")
+        .replace("[", "(")
+        .replace("]", ")")
+    )
+
+
+def _attach_page_diagnostics(page: Page) -> None:
+    """Attach passive listeners to capture console messages, JS errors, and
+    failed network requests for later inspection by the failure hook.
+
+    Critical for headless parallel-mode runs where the browser is inside a
+    worker container — without these, a ``Page.click: Timeout … waiting for
+    locator(.login-cta)`` failure gives you no hint that the SPA never
+    bootstrapped because, e.g., a script tag 404'd or the Auth0 SDK threw
+    on a misconfigured redirect URI.
+
+    The listeners append to lists stored on the page object; the failure
+    hook reads them via ``getattr``. Setting attributes on a Playwright
+    Page is fine — it's a regular Python object with no __slots__.
+    """
+    page._steppy_console: list[str] = []  # type: ignore[attr-defined]
+    page._steppy_errors: list[str] = []  # type: ignore[attr-defined]
+    page._steppy_failed_requests: list[str] = []  # type: ignore[attr-defined]
+
+    def _on_console(msg):
+        try:
+            page._steppy_console.append(f"[{msg.type}] {msg.text}")  # type: ignore[attr-defined]
+        except Exception:
+            pass
+
+    def _on_pageerror(exc):
+        try:
+            page._steppy_errors.append(str(exc))  # type: ignore[attr-defined]
+        except Exception:
+            pass
+
+    def _on_requestfailed(req):
+        try:
+            page._steppy_failed_requests.append(  # type: ignore[attr-defined]
+                f"{req.method} {req.url}  →  {req.failure}"
+            )
+        except Exception:
+            pass
+
+    page.on("console", _on_console)
+    page.on("pageerror", _on_pageerror)
+    page.on("requestfailed", _on_requestfailed)
+
+
+def _dump_page_diagnostics(page: Page, prefix: str = "  ") -> None:
+    """Print the diagnostics captured by ``_attach_page_diagnostics`` for one
+    page. Truncates each section so a chatty SPA doesn't drown the test log."""
+    console = getattr(page, "_steppy_console", None)
+    errors = getattr(page, "_steppy_errors", None)
+    failed = getattr(page, "_steppy_failed_requests", None)
+    if errors:
+        print(f"{prefix}JS errors ({len(errors)}):", flush=True)
+        for line in errors[-10:]:
+            print(f"{prefix}  {line}", flush=True)
+    if failed:
+        print(f"{prefix}Failed requests ({len(failed)}):", flush=True)
+        for line in failed[-10:]:
+            print(f"{prefix}  {line}", flush=True)
+    if console:
+        recent_problems = [m for m in console if m.startswith(("[error]", "[warning]"))]
+        sample = recent_problems[-10:] if recent_problems else console[-5:]
+        print(f"{prefix}Console (showing {len(sample)} of {len(console)}):", flush=True)
+        for line in sample:
+            print(f"{prefix}  {line}", flush=True)
+
+
+# ── Coverage recorder (STEPPY_COVERAGE=1) ───────────────────────────────────
+# Captures three web-standard signals per page fixture — route trail, network
+# requests, V8 JS coverage — and writes one raw record JSON per fixture
+# instance to ``<records_dir>/raw/<run_id>/<scenario>/``. Raw and lossless on
+# purpose: all interpretation (route normalization, API classification,
+# source-map decoding) happens steppy-side at merge (`steppy coverage`), so
+# rules can evolve without recapturing. Framework-agnostic: URL, History API,
+# CDP Profiler, and request events only.
+
+_COVERAGE_HISTORY_HOOK = """
+(() => {
+  if (window.__steppyRouteHook) return;
+  window.__steppyRouteHook = true;
+  var emit = function (kind) {
+    try { window.__steppy_route_event({ u: String(location.href), k: kind, t: Date.now() }); }
+    catch (e) {}
+  };
+  var wrap = function (fn, kind) {
+    return function () { var r = fn.apply(this, arguments); emit(kind); return r; };
+  };
+  try { history.pushState = wrap(history.pushState, "push"); } catch (e) {}
+  try { history.replaceState = wrap(history.replaceState, "replace"); } catch (e) {}
+  window.addEventListener("popstate", function () { emit("pop"); });
+  window.addEventListener("hashchange", function () { emit("hash"); });
+  emit("init");
+})();
+"""
+
+_COVERAGE_MAX_REQUESTS = 2000
+
+
+def _coverage_start(context: BrowserContext, page: Page, role: str, noauth: bool):
+    """Begin coverage recording for one page fixture.
+
+    Returns the recorder state dict, or ``None`` when ``STEPPY_COVERAGE`` is
+    off (``_coverage_stop_and_write`` no-ops on ``None``).
+
+    Route trail is layered: ``framenavigated`` is authoritative (Playwright
+    counts History-API URL changes as navigations), while the injected
+    history hook enriches the trail with push/replace/pop/hash kinds and
+    backstops Playwright behaviour changes. Handlers only append to plain
+    lists — no Playwright calls inside event handlers (sync-API reentry is
+    forbidden), same pattern as ``_attach_page_diagnostics``. JS coverage
+    uses a CDP ``Profiler`` session (Chromium only; playwright-python has no
+    ``page.coverage`` API) and degrades to ``js_coverage.ok = false``.
+    """
+    if not COVERAGE_ENABLED:
+        return None
+    state = {
+        "page": page,
+        "context": context,
+        "role": role,
+        "noauth": noauth,
+        "locale": CURRENT_LOCALE,
+        "layout": CURRENT_LAYOUT,
+        "started_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "nav_events": [],
+        "spa_events": [],
+        "requests": [],
+        "requests_dropped": 0,
+        "cdp": None,
+        "js_error": None,
+    }
+
+    def _on_framenavigated(frame):
+        try:
+            if frame.parent_frame is None:
+                state["nav_events"].append(
+                    {"u": frame.url, "k": "nav", "t": time.time() * 1000}
+                )
+        except Exception:
+            pass
+
+    def _on_request(request):
+        try:
+            if len(state["requests"]) >= _COVERAGE_MAX_REQUESTS:
+                state["requests_dropped"] += 1
+                return
+            state["requests"].append(
+                {"m": request.method, "u": request.url, "rt": request.resource_type}
+            )
+        except Exception:
+            pass
+
+    page.on("framenavigated", _on_framenavigated)
+    context.on("request", _on_request)
+    try:
+        context.expose_binding(
+            "__steppy_route_event",
+            lambda source, payload: state["spa_events"].append(payload),
+        )
+        context.add_init_script(_COVERAGE_HISTORY_HOOK)
+    except Exception:
+        pass  # SPA kind-tagging is enrichment; framenavigated stays authoritative
+    try:
+        cdp = context.new_cdp_session(page)
+        cdp.send("Profiler.enable")
+        # Debugger.enable pins script sources so getScriptSource still works
+        # at teardown; function-granularity coverage is enough for module
+        # mapping and far cheaper than block coverage.
+        cdp.send("Debugger.enable")
+        cdp.send("Profiler.startPreciseCoverage", {"callCount": False, "detailed": False})
+        state["cdp"] = cdp
+    except Exception as exc:
+        state["js_error"] = str(exc)
+    return state
+
+
+def _coverage_map_info(source: str, script_url: str) -> dict:
+    """Extract the script's sourceMappingURL reference.
+
+    Inline ``data:`` maps are decoded and persisted NOW (gzipped,
+    content-hash-deduplicated under ``raw/<run_id>/_maps/``) because they
+    only exist at record time. External map URLs are stored as plain strings;
+    the merge step resolves them on local disk via ``coverage.sourcemap_dir``.
+    """
+    marker = "sourceMappingURL="
+    ref = ""
+    for chunk in (source[-1024:], source):  # tail first — the comment is conventionally last
+        pos = chunk.rfind(marker)
+        if pos != -1:
+            tokens = chunk[pos + len(marker):].split()
+            ref = tokens[0].rstrip("*/").strip() if tokens else ""
+            break
+    if not ref:
+        return {"kind": "none", "reason": "no sourceMappingURL"}
+    if ref.startswith("data:"):
+        try:
+            import base64
+            import gzip
+            import hashlib
+
+            raw = base64.b64decode(ref.split(",", 1)[1])
+            digest = hashlib.sha256(raw).hexdigest()
+            maps_dir = COVERAGE_RAW_DIR / COVERAGE_RUN_ID / "_maps"
+            maps_dir.mkdir(parents=True, exist_ok=True)
+            blob = maps_dir / (digest + ".json.gz")
+            if not blob.exists():
+                blob.write_bytes(gzip.compress(raw))
+            return {"kind": "inline", "hash": digest}
+        except Exception as exc:
+            return {"kind": "none", "reason": "inline map decode failed: " + str(exc)}
+    return {"kind": "external", "url": ref}
+
+
+def _coverage_collect_js(state) -> dict:
+    """Stop CDP profiling and shape the per-script coverage payload.
+
+    Per executed script (http(s) URLs only): the executed function start
+    offsets, a ``line_starts`` newline-offset table computed from the script
+    source (the source itself is discarded — never persisted), and the source
+    map reference. Every CDP step is individually guarded; any failure
+    degrades to ``ok: false`` instead of losing the rest of the record.
+    """
+    cdp = state.get("cdp")
+    if cdp is None:
+        return {
+            "ok": False,
+            "reason": state.get("js_error") or "cdp unavailable",
+            "scripts": [],
+        }
+    scripts = []
+    try:
+        result = cdp.send("Profiler.takePreciseCoverage").get("result", [])
+        for entry in result:
+            url = entry.get("url") or ""
+            if not url.startswith(("http://", "https://")):
+                continue  # anonymous evals, init scripts, extensions
+            offsets = sorted(
+                {
+                    f["ranges"][0]["startOffset"]
+                    for f in entry.get("functions", [])
+                    if f.get("ranges") and f["ranges"][0].get("count", 0) > 0
+                }
+            )
+            if not offsets:
+                continue
+            source = None
+            try:
+                source = cdp.send(
+                    "Debugger.getScriptSource", {"scriptId": entry["scriptId"]}
+                ).get("scriptSource")
+            except Exception:
+                source = None
+            if source is None:
+                try:
+                    resp = state["page"].request.get(url, timeout=10000)
+                    source = resp.text() if resp.ok else None
+                except Exception:
+                    source = None
+            line_starts = None
+            map_info = {"kind": "none", "reason": "script source unavailable"}
+            if source is not None:
+                line_starts = [0]
+                idx = source.find("\n")
+                while idx != -1:
+                    line_starts.append(idx + 1)
+                    idx = source.find("\n", idx + 1)
+                map_info = _coverage_map_info(source, url)
+            scripts.append(
+                {
+                    "url": url,
+                    "executed_offsets": offsets,
+                    "line_starts": line_starts,
+                    "map": map_info,
+                }
+            )
+    except Exception as exc:
+        return {"ok": False, "reason": str(exc), "scripts": []}
+    finally:
+        for command in ("Profiler.stopPreciseCoverage", "Profiler.disable", "Debugger.disable"):
+            try:
+                cdp.send(command)
+            except Exception:
+                pass
+        try:
+            cdp.detach()
+        except Exception:
+            pass
+    scripts.sort(key=lambda s: s["url"])
+    return {"ok": True, "reason": None, "scripts": scripts}
+
+
+def _coverage_stop_and_write(state, request) -> None:
+    """Finish recording and write the raw record JSON. Never raises — a
+    recorder bug must not fail the test run. Must be called BEFORE
+    ``page.close()`` (the JS-coverage flush needs the live page/context)."""
+    if state is None:
+        return
+    try:
+        scenario = getattr(request.module, "SCENARIO", None) or _sanitise_nodeid(
+            request.node.name
+        )
+        failed = getattr(request.node, "_steppy_call_failed", None)
+        outcome = "unknown" if failed is None else ("failed" if failed else "passed")
+        record = {
+            "steppy_coverage_record": 1,
+            "run_id": COVERAGE_RUN_ID,
+            "scenario": scenario,
+            "role": state["role"],
+            "noauth": state["noauth"],
+            "locale": state["locale"],
+            "layout": state["layout"],
+            "asserts_enabled": not SKIP_ASSERTS,
+            "guide_mode": GUIDE_MODE,
+            "outcome": outcome,
+            "started_at": state["started_at"],
+            "finished_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "nav_events": state["nav_events"],
+            "spa_events": [e for e in state["spa_events"] if isinstance(e, dict)],
+            "requests": state["requests"],
+            "requests_dropped": state["requests_dropped"],
+            "js_coverage": _coverage_collect_js(state),
+        }
+        folder = COVERAGE_RAW_DIR / COVERAGE_RUN_ID / scenario
+        folder.mkdir(parents=True, exist_ok=True)
+        suffix = f"{state['locale'] or 'default'}-{state['layout'] or 'default'}"
+        name = f"{state['role']}_page{'_noauth' if state['noauth'] else ''}__{suffix}.json"
+        (folder / name).write_text(json.dumps(record, indent=2), encoding="utf-8")
+    except Exception as exc:
+        print(f"[steppy] coverage record failed: {exc}", flush=True)
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    """Capture a screenshot, URL, title, JS errors, and failed requests from
+    every active ``*_page`` fixture when a test fails. Lands under
+    ``output/screenshots/_failures/`` with details printed inline so the user
+    can diagnose without re-running with extra flags.
+
+    Best-effort: any exception during capture is swallowed so a debug aid
+    never compounds a real test failure.
+
+    Also stamps the call-phase outcome onto the item: makereport(call) fires
+    before fixture finalizers, so the coverage recorder's teardown can record
+    whether the scenario passed.
+    """
+    outcome = yield
+    rep = outcome.get_result()
+    if rep.when == "call":
+        item._steppy_call_failed = rep.failed
+    if rep.when != "call" or not rep.failed:
+        return
+    failure_dir = SCREENSHOTS_DIR / "_failures"
+    try:
+        failure_dir.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return
+    safe_id = _sanitise_nodeid(item.nodeid)
+    for fixture_name, value in item.funcargs.items():
+        if not (fixture_name.endswith("_page") or fixture_name.endswith("_page_noauth")):
+            continue
+        if not hasattr(value, "screenshot"):
+            continue
+        path = failure_dir / f"{safe_id}__{fixture_name}.png"
+        try:
+            value.screenshot(path=str(path), full_page=True, timeout=5000)
+        except Exception:
+            path = None
+        try:
+            url = value.url
+        except Exception:
+            url = "<unknown>"
+        try:
+            title = value.title()
+        except Exception:
+            title = "<unknown>"
+        print(
+            f"\n[steppy] {fixture_name} failure  url={url}  title={title!r}",
+            flush=True,
+        )
+        if path is not None:
+            print(f"  screenshot: {path}", flush=True)
+        _dump_page_diagnostics(value, prefix="  ")
+
+
+# ── Capture / interpolation helpers ─────────────────────────────────────────
+
+{% raw %}
+def _interp(s, _vars):
+    """Substitute {{var}} placeholders in `s` from `_vars`. No-op if no braces."""
+    if not s or "{{" not in s:
+        return s
+    out = s
+    for k, v in _vars.items():
+        out = out.replace("{{" + k + "}}", str(v))
+    return out
+
+
+def _interp_shell(s, _vars):
+    """Like _interp, but shell-quote each substituted value.
+
+    Used only for `capture from.type=shell` commands, where a {{var}} may hold
+    DOM-scraped or HTTP-sourced content. Quoting the *values* (not the author's
+    static command template) neutralizes shell metacharacters so page content
+    can't inject into the subprocess.
+    """
+    import shlex
+    if not s or "{{" not in s:
+        return s
+    out = s
+    for k, v in _vars.items():
+        out = out.replace("{{" + k + "}}", shlex.quote(str(v)))
+    return out
+{% endraw %}
+
+
+def _interp_val(s, _vars):
+    """Like ``_interp`` but ALSO resolves ${VAR} / ${VAR:-default} from the
+    environment.
+
+    Used only at fill/select VALUE sites so secret placeholders emitted by
+    ``steppy record`` (e.g. ${STEPPY_ADMIN_TOKEN}) resolve at run time from the
+    worker/CI environment. Selector and target sites keep plain ``_interp`` — their
+    semantics are unchanged. An unset var with no default is left as the literal
+    ${...} (same silent policy as ``_interp_env``). Defined after the endraw
+    marker above so it stays out of the ``_interp`` unit-test extract.
+    """
+    if isinstance(s, str) and "${" in s:
+        def _sub(m):
+            name, default = m.group(1), m.group(2)
+            if name in os.environ:
+                return os.environ[name]
+            if default is not None:
+                return default
+            return m.group(0)
+        s = _ENV_REF.sub(_sub, s)
+    return _interp(s, _vars)
+
+
+def _resolve_date_obj(expr):
+    """Resolve a relative/dynamic date expression to a ``datetime.date`` AT RUN
+    TIME (so generated tests stay valid forever). Shared by ``fill-date`` (which
+    formats the result) and ``pick-date`` (which needs the date object to compute
+    month deltas and the target day).
+
+    Grammar:
+      today               -> current date
+      this-<weekday>      -> that weekday in the current (Monday-anchored) week
+      next-<weekday>      -> the next strictly-future occurrence of that weekday
+      ±N[d|w|m|y]         -> offset by N days / weeks / months / years (e.g. +7d, -1m)
+      YYYY-MM-DD          -> ISO literal
+    """
+    import calendar
+    import datetime
+    import re as _re
+
+    expr = (expr or "").strip().lower()
+    today = datetime.date.today()
+    weekdays = {
+        "monday": 0, "tuesday": 1, "wednesday": 2, "thursday": 3,
+        "friday": 4, "saturday": 5, "sunday": 6,
+    }
+    if expr == "today":
+        d = today
+    elif expr.startswith("this-") and expr[5:] in weekdays:
+        d = today - datetime.timedelta(days=today.weekday() - weekdays[expr[5:]])
+    elif expr.startswith("next-") and expr[5:] in weekdays:
+        delta = (weekdays[expr[5:]] - today.weekday()) % 7 or 7
+        d = today + datetime.timedelta(days=delta)
+    elif _re.match(r"^[+-]\d+[dwmy]$", expr):
+        sign = 1 if expr[0] == "+" else -1
+        n = sign * int(expr[1:-1])
+        unit = expr[-1]
+        if unit == "d":
+            d = today + datetime.timedelta(days=n)
+        elif unit == "w":
+            d = today + datetime.timedelta(weeks=n)
+        elif unit == "m":
+            month_index = today.year * 12 + (today.month - 1) + n
+            year, month0 = divmod(month_index, 12)
+            month = month0 + 1
+            day = min(today.day, calendar.monthrange(year, month)[1])
+            d = datetime.date(year, month, day)
+        else:  # 'y'
+            year = today.year + n
+            day = min(today.day, calendar.monthrange(year, today.month)[1])
+            d = datetime.date(year, today.month, day)
+    else:
+        d = datetime.date.fromisoformat(expr)
+    return d
+
+
+def _resolve_date(expr, fmt="%d/%m/%Y"):
+    """Resolve a date expression (see ``_resolve_date_obj``) and format it with
+    ``fmt``. Driven by the ``fill-date`` action."""
+    return _resolve_date_obj(expr).strftime(fmt)
+
+
+def _open_datepicker(page, selector, panel, trigger, timeout):
+    """Open a PrimeNG (date|time)picker panel from its host: prefer a showIcon
+    ``trigger`` button, else the inner <input>, else the host; wait for ``panel``."""
+    host = page.locator(selector)
+    opener = None
+    if trigger:
+        trig = host.locator(trigger)
+        if trig.count():
+            opener = trig.first
+    if opener is None:
+        inp = host.locator("input")
+        opener = inp.first if inp.count() else host
+    opener.click()
+    page.wait_for_selector(panel, state="visible", timeout=timeout)
+
+
+def _pick_date(page, selector, expr, *, panel, next_btn, prev_btn, day_cell, trigger="", timeout=30000):
+    """Drive a calendar widget (PrimeNG ``p-datepicker`` by default) to a target
+    date computed at run time. Opens the panel from ``selector``, steps forward
+    or backward to the target month, clicks the day cell, and waits for the panel
+    to close. Selectors are config-driven so non-PrimeNG kits can retarget."""
+    import datetime
+    import re as _re
+
+    target = _resolve_date_obj(expr)
+    today = datetime.date.today()
+    months = (target.year - today.year) * 12 + (target.month - today.month)
+    _open_datepicker(page, selector, panel, trigger, timeout)
+    step_btn = next_btn if months >= 0 else prev_btn
+    for _ in range(abs(months)):
+        page.locator(step_btn).first.click()
+        page.wait_for_timeout(120)
+    # Exact day match so "1" doesn't match "10"/"11"/… (substring filter would).
+    page.locator(day_cell).filter(
+        has_text=_re.compile(rf"^\s*{target.day}\s*$")
+    ).first.click()
+    page.wait_for_selector(panel, state="hidden", timeout=timeout)
+
+
+def _pick_time(page, selector, value, *, panel, hour_picker, minute_picker, trigger="", timeout=30000):
+    """Drive a PrimeNG ``timeOnly`` picker to a target ``HH:MM``. Opens the panel
+    (showIcon trigger -> inner <input> -> host), spins each column's up/down arrow
+    until its value <span> reads the target, then presses Escape to close so the
+    overlay can't intercept later clicks. Column-scoped (``{col} button`` first/
+    last + ``{col} > span``) so it works regardless of whether PrimeNG tags the
+    arrows with increment/decrement classes. Assumes ``stepHour``/``stepMinute``
+    == 1 (PrimeNG default). Selectors are config-driven for non-PrimeNG kits."""
+    target_h, target_m = (int(p) for p in value.strip().split(":"))
+    _open_datepicker(page, selector, panel, trigger, timeout)
+    _panel = page.locator(panel).last
+
+    def _spin(col_sel, target_val, modulo):
+        # Bounded by ``modulo`` so a stuck widget can't loop forever.
+        buttons = _panel.locator(col_sel + " button")        # first=up, last=down
+        value_span = _panel.locator(col_sel + " > span")     # direct-child value
+        for _ in range(modulo):
+            current = int((value_span.first.inner_text() or "0").strip())
+            if current == target_val:
+                return
+            diff = (target_val - current) % modulo
+            # Step the short way around the dial.
+            (buttons.first if diff <= modulo // 2 else buttons.last).click()
+            page.wait_for_timeout(80)
+
+    _spin(hour_picker, target_h, 24)
+    _spin(minute_picker, target_m, 60)
+    page.keyboard.press("Escape")
+    page.wait_for_selector(panel, state="hidden", timeout=timeout)
+
+
+_SYNTHETIC_CLICK_JS = """
+el => {
+  el.scrollIntoView({block: 'center'});
+  const target = el.querySelector('button, input, [role="button"]') || el;
+  const r = target.getBoundingClientRect();
+  const opts = {bubbles: true, cancelable: true, view: window, button: 0,
+                clientX: r.left + r.width / 2, clientY: r.top + r.height / 2};
+  target.dispatchEvent(new MouseEvent('mousedown', opts));
+  target.dispatchEvent(new MouseEvent('mouseup', opts));
+  target.dispatchEvent(new MouseEvent('click', opts));
+}
+"""
+
+
+_WAIT_COMPARATOR = re.compile(r"^(>=|<=|==|!=|>|<)\s*(\d+)$")
+
+
+def _wait_until(locator, spec: str, timeout: int, interval: int = 100) -> None:
+    """Block until a *state* predicate holds on ``locator``, not just presence.
+
+    Playwright's own ``wait_for`` accepts only visible/hidden/detached/attached,
+    which cannot say "the form has finished pre-filling" — so scenarios polled
+    it by hand. The dominant shape in the corpus, 47 times over, was:
+
+        deadline = time.time() + 10
+        while time.time() < deadline:
+            if page.input_value(sel):
+                break
+            page.wait_for_timeout(100)
+
+    Polled from Python rather than through ``wait_for_function`` on purpose: the
+    predicate has to observe the element through *Playwright's* locator, which
+    understands ``text=``/``>>`` and the other selector engines that
+    ``document.querySelector`` does not.
+
+    spec:
+      value-not-empty     -- the input has a value
+      value:<text>        -- the input's value equals <text>
+      text:<text>         -- the element's text contains <text>
+      count:<cmp><n>      -- how many elements match, e.g. count:>=2
+    """
+    deadline = time.monotonic() + timeout / 1000.0
+    last = None
+    while True:
+        try:
+            if spec == "value-not-empty":
+                last = locator.first.input_value(timeout=timeout)
+                if last:
+                    return
+            elif spec.startswith("value:"):
+                want = spec[6:]
+                last = locator.first.input_value(timeout=timeout)
+                if last == want:
+                    return
+            elif spec.startswith("text:"):
+                want = spec[5:]
+                last = locator.first.inner_text(timeout=timeout)
+                if want in last:
+                    return
+            elif spec.startswith("count:"):
+                match = _WAIT_COMPARATOR.match(spec[6:])
+                comparator, expected = match.group(1), int(match.group(2))
+                last = locator.count()
+                if {
+                    ">=": last >= expected,
+                    "<=": last <= expected,
+                    "==": last == expected,
+                    "!=": last != expected,
+                    ">": last > expected,
+                    "<": last < expected,
+                }[comparator]:
+                    return
+            else:  # pragma: no cover - validation rejects this at parse time
+                raise AssertionError(f"_wait_until: unknown predicate {spec!r}")
+        except AssertionError:
+            raise
+        except Exception as exc:  # the element may not exist yet
+            last = f"<{type(exc).__name__}>"
+        if time.monotonic() >= deadline:
+            raise AssertionError(f"wait-for until={spec!r} not satisfied within {timeout}ms (last saw {last!r})")
+        time.sleep(interval / 1000.0)
+
+
+def _assert_stays_hidden(locator, ms: int, message: str = "", interval: int = 250) -> None:
+    """Assert an element stays absent for ``ms``, rather than becoming absent.
+
+    ``expect(...).to_be_hidden()`` auto-waits for the element to *become* hidden,
+    which passes the instant it is not there yet — the opposite of what "prove
+    the replacement wizard never opens" needs. The corpus spells this as a
+    for-loop of one-shot counts; this is that loop, once.
+    """
+    deadline = time.monotonic() + ms / 1000.0
+    while True:
+        if locator.count() and locator.first.is_visible():
+            raise AssertionError(message or f"element appeared within {ms}ms but was expected to stay hidden")
+        if time.monotonic() >= deadline:
+            return
+        time.sleep(interval / 1000.0)
+
+
+_WHEN_FORMS = ("visible(", "hidden(", "count(", "contains(")
+
+
+def _when(page, spec: str, _vars: dict) -> bool:
+    """Evaluate a step's ``when:`` condition against the live page.
+
+    Deliberately NOT the assertion grammar: an assertion auto-waits, which is
+    the opposite of what a condition wants. "Click it if it is there" must
+    answer now, from what is rendered now — waiting 30s for an element that was
+    never going to appear would make every guarded step pay the timeout.
+
+    Supported: visible(sel) | hidden(sel) | count(sel, <cmp>N) | contains(sel, "text")
+    """
+    spec = (spec or "").strip()
+    head, _, rest = spec.partition("(")
+    inner = rest[:-1] if rest.endswith(")") else rest
+    if head == "visible":
+        loc = page.locator(_interp(inner.strip(), _vars))
+        return bool(loc.count()) and loc.first.is_visible()
+    if head == "hidden":
+        loc = page.locator(_interp(inner.strip(), _vars))
+        return not loc.count() or not loc.first.is_visible()
+    if head == "contains":
+        selector, _, text = inner.partition(",")
+        loc = page.locator(_interp(selector.strip(), _vars))
+        if not loc.count():
+            return False
+        return _interp(text.strip().strip('"').strip("'"), _vars) in loc.first.inner_text()
+    if head == "count":
+        selector, _, raw = inner.rpartition(",")
+        loc = page.locator(_interp(selector.strip(), _vars))
+        match = _WAIT_COMPARATOR.match(raw.strip())
+        if not match:
+            return loc.count() == int(raw.strip())
+        comparator, expected = match.group(1), int(match.group(2))
+        found = loc.count()
+        return {
+            ">=": found >= expected,
+            "<=": found <= expected,
+            "==": found == expected,
+            "!=": found != expected,
+            ">": found > expected,
+            "<": found < expected,
+        }[comparator]
+    raise AssertionError(f"_when: unsupported condition {spec!r}")
+
+
+def call_helper(page, dotted: str, args=None, kwargs=None, _vars=None, pass_page: bool = True):
+    """Run a project helper function as a first-class step.
+
+    The project root is already on ``sys.path``: pytest is launched as
+    ``python -m pytest`` from it, and ``python -m`` puts the working directory
+    at ``sys.path[0]``. (The worker image sets ``WORKDIR /steppy/project`` for
+    the same reason.) So the three-line ``sys.path.insert`` preamble that opens
+    2 334 custom blocks in the measured corpus was never necessary, and nothing
+    here reproduces it.
+
+    String arguments go through ``_interp`` so a value captured by an earlier
+    step reaches the helper as ``{{var}}``; non-strings pass through untouched,
+    which is what keeps ``args: [6]`` an int.
+    """
+    import importlib
+
+    module_name, _, fn_name = dotted.rpartition(".")
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:
+        raise AssertionError(
+            f"call: cannot import {module_name!r} for {dotted!r}. "
+            f"Helper modules are imported from the project root ({Path.cwd()})."
+        ) from exc
+    try:
+        fn = getattr(module, fn_name)
+    except AttributeError as exc:
+        raise AssertionError(f"call: {module_name!r} has no attribute {fn_name!r}") from exc
+
+    _vars = _vars if _vars is not None else {}
+    resolved_args = [_interp(a, _vars) if isinstance(a, str) else a for a in (args or [])]
+    resolved_kwargs = {k: (_interp(v, _vars) if isinstance(v, str) else v) for k, v in (kwargs or {}).items()}
+    if pass_page:
+        return fn(page, *resolved_args, **resolved_kwargs)
+    return fn(*resolved_args, **resolved_kwargs)
+
+
+def synthetic_click(locator) -> None:
+    """Dispatch a manual mousedown/mouseup/click sequence on a locator's element
+    (Cmd 12 — ``click synthetic: true``). For custom widgets that swallow
+    Playwright's native ``.click()`` and only react to raw DOM MouseEvents."""
+    locator.evaluate(_SYNTHETIC_CLICK_JS)
+
+
+def capture(spec: dict, _vars: dict, retry: int = 1, interval: float = 0.2) -> str:
+    """Fetch a value from an external source. Retries with `interval` seconds between attempts.
+
+    spec.type:
+      - 'redis':  requires 'key'. Reads CONFIG['redis'] for connection.
+      - 'http':   requires 'url'. Optional 'json_path' (e.g. '$.code') and 'headers'.
+      - 'shell':  requires 'command'. Returns stdout (trimmed).
+      - 'date':   requires 'date' (today|next-monday|+7d|YYYY-MM-DD). Optional
+                  'format' (strftime, default '%Y-%m-%d'; '%V'/'%G' give the ISO
+                  week and year). Pure — resolved at run time, never cached.
+    All string fields are run through _interp() so they can reference earlier captures.
+    """
+    # Gate shell capture up front (not inside the retry loop) so the reason is
+    # surfaced cleanly rather than wrapped in a retry AssertionError.
+    if spec.get("type") == "shell" and not CONFIG.get("security", {}).get("allow_shell_capture", False):
+        raise RuntimeError(
+            "capture from.type=shell is disabled. It runs a shell command with "
+            "page-derived values and is a command-injection vector, so it is "
+            "opt-in: set security.allow_shell_capture: true in config.yaml to "
+            "enable it (see SECURITY.md)."
+        )
+    last_err = None
+    for _ in range(max(1, retry)):
+        try:
+            t = spec.get("type")
+            if t == "redis":
+                import redis  # type: ignore
+                cfg = CONFIG.get("redis", {})
+                r = redis.Redis(
+                    host=cfg.get("host", "localhost"),
+                    port=cfg.get("port", 6379),
+                    db=cfg.get("db", 0),
+                    decode_responses=True,
+                )
+                v = r.get(_interp(spec["key"], _vars))
+                if v is not None:
+                    return v
+            elif t == "http":
+                import httpx  # type: ignore
+                headers = spec.get("headers") or {}
+                resp = httpx.get(_interp(spec["url"], _vars), headers=headers, timeout=5)
+                resp.raise_for_status()
+                if "json_path" in spec:
+                    import jsonpath_ng  # type: ignore
+                    matches = jsonpath_ng.parse(spec["json_path"]).find(resp.json())
+                    if matches:
+                        return str(matches[0].value)
+                else:
+                    return resp.text
+            elif t == "date":
+                # No I/O and nothing to retry: `_resolve_date` is pure. It is
+                # here rather than in a new action because the value's *use* is
+                # already what `capture` is for — binding a `{{var}}` that later
+                # selectors and values interpolate.
+                return _resolve_date(
+                    _interp(spec["date"], _vars),
+                    _interp(spec.get("format") or "%Y-%m-%d", _vars),
+                )
+            elif t == "shell":
+                import subprocess
+                out = subprocess.run(
+                    _interp_shell(spec["command"], _vars),
+                    shell=True,
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                )
+                return out.stdout.strip()
+            else:
+                raise ValueError(f"Unknown capture type: {t!r}")
+        except Exception as e:
+            last_err = e
+        time.sleep(interval)
+    raise AssertionError(f"capture failed after {retry} attempts: spec={spec} last_err={last_err}")
+
+
+def capture_dom(page, spec: dict, _vars: dict, retry: int = 1, interval: float = 0.2) -> str:
+    """Read a value out of the live DOM and store it in ``_vars`` (interpolatable
+    by later steps via _interp), replacing the ``globals()[...]`` capture-and-reuse
+    hack. Retries with ``interval`` seconds between attempts.
+
+    spec (from.type == 'dom'):
+      - 'selector':  required. The element to read (first match is used).
+      - 'extract':   text (default) | attribute | regex.
+      - 'attribute': attribute name when extract == 'attribute'.
+      - 'regex':     pattern applied to the extracted string; returns group 1
+                     (or group 0 if the pattern has no groups). Required when
+                     extract == 'regex'; also honored as a post-filter otherwise.
+    """
+    import re as _re
+
+    extract = spec.get("extract", "text")
+    last_err = None
+    for _ in range(max(1, retry)):
+        try:
+            loc = page.locator(_interp(spec["selector"], _vars)).first
+            loc.wait_for(state="visible", timeout=10000)
+            if extract == "attribute":
+                raw = loc.get_attribute(_interp(spec["attribute"], _vars))
+            else:
+                raw = loc.inner_text()
+            if raw is None:
+                raise ValueError("capture_dom: extracted value is None")
+            raw = raw.strip()
+            pattern = spec.get("regex")
+            if pattern:
+                m = _re.search(pattern, raw)
+                if not m:
+                    raise ValueError(f"capture_dom: regex {pattern!r} did not match {raw!r}")
+                return m.group(1) if m.groups() else m.group(0)
+            return raw
+        except Exception as e:
+            last_err = e
+        time.sleep(interval)
+    raise AssertionError(f"capture_dom failed after {retry} attempts: spec={spec} last_err={last_err}")
+
+
+# ── Screenshot helper ───────────────────────────────────────────────────────
+
+def _screenshot_folder(scenario: str) -> Path:
+    """Return the folder PNGs/sidecars for ``scenario`` should land in.
+
+    When ``CURRENT_LOCALE`` is set (parametrized run), images go under a
+    per-locale subdir so the build can serve a different screenshot set per
+    language. Otherwise they fall back to the legacy flat layout.
+    """
+    folder = SCREENSHOTS_DIR / scenario
+    if CURRENT_LOCALE:
+        folder = folder / CURRENT_LOCALE
+    if CURRENT_LAYOUT:
+        folder = folder / CURRENT_LAYOUT
+    folder.mkdir(parents=True, exist_ok=True)
+    return folder
+
+
+def _screenshot_mask_kwargs(page: Page) -> dict:
+    """Build page.screenshot(mask=...) kwargs from `screenshot.mask` config.
+
+    Returns {} when no mask selectors are configured, so output is byte-identical
+    for projects that don't redact. Otherwise returns solid-box masks over every
+    matched element (secrets/personal-data redaction — see SECURITY.md).
+    """
+    masks = CONFIG.get("screenshot", {}).get("mask", []) or []
+    if not masks:
+        return {}
+    color = CONFIG.get("screenshot", {}).get("mask_color", "#000000")
+    return {"mask": [page.locator(sel) for sel in masks], "mask_color": color}
+
+
+def take_screenshot(page: Page, scenario: str, step: int, suffix: str = ""):
+    """Capture a screenshot if STEPPY_SCREENSHOTS is enabled."""
+    if not SCREENSHOTS_ENABLED:
+        return
+    folder = _screenshot_folder(scenario)
+    name = f"step-{step:02d}{'-' + suffix if suffix else ''}.png"
+    page.screenshot(path=str(folder / name), **_screenshot_mask_kwargs(page))
+
+
+def _apply_highlight(page: Page, selector: str) -> None:
+    """Outline + tint an element for a guide screenshot. Best-effort."""
+    highlight_css = CONFIG.get("screenshot", {})
+    color = highlight_css.get("highlight_color", "rgba(255, 0, 0, 0.3)")
+    border = highlight_css.get("highlight_border", "2px solid red")
+    try:
+        page.eval_on_selector(
+            selector,
+            f"el => {% raw %}{{{% endraw %} el.style.outline = '{border}'; el.style.backgroundColor = '{color}'; {% raw %}}}{% endraw %}"
+        )
+    except Exception:
+        pass  # Element might not exist; screenshot without highlight
+
+
+def _clear_highlight(page: Page, selector: str) -> None:
+    """Undo :func:`_apply_highlight`. Best-effort."""
+    try:
+        page.eval_on_selector(
+            selector,
+            "el => {% raw %}{{% endraw %} el.style.outline = ''; el.style.backgroundColor = ''; {% raw %}}{% endraw %}"
+        )
+    except Exception:
+        pass
+
+
+def highlight_and_screenshot(page: Page, selector: str, scenario: str, step: int):
+    """Highlight an element and take a screenshot (for guide generation)."""
+    if not SCREENSHOTS_ENABLED:
+        return
+    _apply_highlight(page, selector)
+    take_screenshot(page, scenario, step)
+    _clear_highlight(page, selector)
+
+
+# Per-frame suffix for multi-frame captures (step-NN-a.png, -b, …). One
+# declaration: the two frame builders below must agree on the alphabet and
+# on the ceiling it puts on frame count.
+FRAME_LETTERS = "abcdefghijklmnopqrstuvwxyz"
+
+
+# ── Cursor sidecar helper ───────────────────────────────────────────────────
+
+def _safe_bbox(page: Page, selector: str):
+    """Return locator.bounding_box() or None on any failure."""
+    try:
+        return page.locator(selector).first.bounding_box(timeout=1000)
+    except Exception:
+        return None
+
+
+def _scroll_into_view(page: Page, selector: str) -> None:
+    """Best-effort scroll so *selector* is in the viewport.
+
+    The single place the scroll policy (which locator, what timeout, swallow
+    failures) is expressed — the cursor-bbox timing invariant below depends on
+    it, and so do the fill-form frame helpers that anchor a viewport.
+    """
+    try:
+        page.locator(selector).first.scroll_into_view_if_needed(timeout=1000)
+    except Exception:
+        pass
+
+
+def _safe_bbox_scrolled(page: Page, selector: str):
+    """Scroll the element into view, then return its bounding box.
+
+    Playwright actions (click/fill/...) auto-scroll the element into view before
+    firing. Capturing the bbox *before* the action therefore yields stale
+    viewport coordinates when the element was off-screen (e.g. inside a scrolled
+    modal). Scrolling first keeps the captured bbox aligned with the viewport
+    the subsequent screenshot will see.
+    """
+    _scroll_into_view(page, selector)
+    return _safe_bbox(page, selector)
+
+
+def _safe_bbox_locator(page: Page, locator):
+    """Like ``_safe_bbox_scrolled`` but for an already-resolved Playwright
+    Locator (used by actions that disambiguate via ``within``/``match`` or that
+    build their target locator imperatively, e.g. ``confirm``). Scroll into view,
+    then return its bounding box or None on any failure."""
+    try:
+        locator.scroll_into_view_if_needed(timeout=1000)
+    except Exception:
+        pass
+    try:
+        return locator.bounding_box(timeout=1000)
+    except Exception:
+        return None
+
+
+def _offset_for_full_page(page: Page):
+    """Return (scrollX, scrollY) when full_page screenshots are in use, else (0, 0)."""
+    if not SCREENSHOT_FULL_PAGE:
+        return (0, 0)
+    try:
+        return (
+            int(page.evaluate("() => window.scrollX || 0")),
+            int(page.evaluate("() => window.scrollY || 0")),
+        )
+    except Exception:
+        return (0, 0)
+
+
+def take_screenshot_with_bbox(
+    page: Page,
+    scenario: str,
+    step: int,
+    action: str,
+    selector: str | None = None,
+    selectors: list | None = None,
+    precaptured_bbox: dict | None = None,
+    precaptured_bboxes: list | None = None,
+    highlight: bool = False,
+    frame: str | None = None,
+):
+    """Capture a screenshot and a JSON sidecar containing the target bounding box(es).
+
+    - selector / precaptured_bbox: single-target actions (click, fill, hover, ...).
+    - selectors / precaptured_bboxes: multi-target actions (fill-form).
+    - precaptured_* win over live resolution so the caller can capture BEFORE the action
+      mutates the DOM. If both are None and a selector is supplied we fall back to
+      resolving it at screenshot time.
+    - If neither selector nor list is supplied, target is None (hidden cursor in guide).
+    - No-op when STEPPY_SCREENSHOTS is not enabled.
+    """
+    if not SCREENSHOTS_ENABLED:
+        return
+
+    folder = _screenshot_folder(scenario)
+    stem = f"step-{step:02d}" + (f"-{frame}" if frame else "")
+    png_path = folder / f"{stem}.png"
+    json_path = folder / f"{stem}.json"
+
+    dx, dy = _offset_for_full_page(page)
+
+    def _apply_offset(bbox):
+        if not bbox:
+            return None
+        return {
+            "x": bbox.get("x", 0) + dx,
+            "y": bbox.get("y", 0) + dy,
+            "width": bbox.get("width", 0),
+            "height": bbox.get("height", 0),
+        }
+
+    target_payload = None
+    if selectors is not None or precaptured_bboxes is not None:
+        sels = selectors or []
+        bboxes = precaptured_bboxes
+        if bboxes is None:
+            bboxes = [_safe_bbox(page, s) for s in sels]
+        fields = []
+        for i, bbox in enumerate(bboxes):
+            fields.append({
+                "selector": sels[i] if i < len(sels) else None,
+                "bbox": _apply_offset(bbox),
+            })
+        target_payload = {"kind": "multi", "fields": fields}
+    elif selector is not None or precaptured_bbox is not None:
+        bbox = precaptured_bbox if precaptured_bbox is not None else _safe_bbox(page, selector)
+        target_payload = {
+            "kind": "single",
+            "selector": selector,
+            "bbox": _apply_offset(bbox),
+        }
+
+    # Optional highlight parity with highlight_and_screenshot (applied AFTER bbox capture).
+    if highlight and selector:
+        _apply_highlight(page, selector)
+
+    page.screenshot(path=str(png_path), **_screenshot_mask_kwargs(page))
+
+    if highlight and selector:
+        _clear_highlight(page, selector)
+
+    sidecar = {
+        "step": step,
+        "screenshot": png_path.name,
+        "action": action,
+        # Record the viewport this page actually ran at, which is the space its
+        # bboxes were measured in. The guide renderer scales cursor bboxes
+        # against this value. `CURRENT_LAYOUT` is only the fallback (a context
+        # built without a viewport reports None): it is one global shared by
+        # every role page a test holds, so it describes this page only while
+        # those pages are parametrized in lockstep.
+        "viewport": page.viewport_size or _get_viewport_for_layout(CURRENT_LAYOUT),
+        # Capture devicePixelRatio for THIS layout. The guide renderer multiplies
+        # viewport * this to get the screenshot's intrinsic pixel width, which it
+        # uses to cap the displayed `<img>` width so a dense (e.g. mobile DSF=3)
+        # capture is never upscaled. Absent in legacy sidecars ⇒ readers default 1.
+        "device_scale_factor": _get_scale_factor_for_layout(CURRENT_LAYOUT),
+        "target": target_payload,
+    }
+    json_path.write_text(json.dumps(sidecar, indent=2), encoding="utf-8")
+
+
+def take_fillform_progressive_frames(
+    page: Page,
+    scenario: str,
+    step: int,
+    fields: list,
+):
+    """Capture a fill-form step field-by-field with a single-target cursor per frame.
+
+    ``fields`` is an ordered list of ``(selector, value)`` tuples. For each
+    field, the function:
+      1. Scrolls the field into view (so its bbox lines up with the
+         screenshot's viewport).
+      2. Captures the current form state with a single-target ``fill-form``
+         sidecar pointing at THIS field (cursor will travel here, click,
+         then type).
+      3. Fills the field on the real page.
+
+    After every field is filled, a final "settled" frame is captured with no
+    cursor target — the form's fully-filled end state.
+
+    Frames are emitted as ``step-NN-a``, ``-b``, … in field declaration order,
+    plus one extra letter for the settled frame. Reuses the existing letter
+    scheme so the guide builder's frame discovery loop in
+    ``_frame_screenshot_path`` works unchanged.
+
+    Capture time grows with field count (one screenshot + one fill per field),
+    so authors should opt in deliberately on forms where the field-by-field
+    progression adds clarity.
+    """
+    if not SCREENSHOTS_ENABLED:
+        return
+    if not fields:
+        return
+
+    # +1 for the settled frame; if we'd overflow the alphabet, bail on the
+    # settled frame rather than corrupting the sequence.
+    n_fields = len(fields)
+    if n_fields >= len(FRAME_LETTERS):
+        n_fields = len(FRAME_LETTERS) - 1
+
+    for i in range(n_fields):
+        selector, value = fields[i]
+        bbox = _safe_bbox_scrolled(page, selector)
+        take_screenshot_with_bbox(
+            page,
+            scenario,
+            step,
+            "fill-form",
+            selector=selector,
+            precaptured_bbox=bbox,
+            frame=FRAME_LETTERS[i],
+        )
+        try:
+            page.locator(selector).first.fill(value)
+        except Exception:
+            pass
+
+    # Settled frame: form fully filled, no cursor target. Anchor on the last
+    # field so the viewport is sensible (matches the user's final scroll
+    # position in real use).
+    if fields:
+        _scroll_into_view(page, fields[-1][0])
+    take_screenshot_with_bbox(
+        page,
+        scenario,
+        step,
+        "fill-form",
+        frame=FRAME_LETTERS[n_fields],
+    )
+
+
+def take_fillform_frames(
+    page: Page,
+    scenario: str,
+    step: int,
+    selectors: list,
+):
+    """Capture as many frames as needed so every form field appears, fully
+    in-viewport, in at least one screenshot.
+
+    Strategy: repeatedly pick the first field not yet covered, scroll it into
+    view, take a frame, and mark every field whose bbox center now lies inside
+    the viewport as covered. Stops when every field is covered, or when a pass
+    makes no progress (safety net against pathological forms).
+
+    Frame suffixes are ``a``, ``b``, ``c``, … in capture order. Each sidecar
+    contains bboxes for every field in the original declaration order (with
+    the per-frame viewport), so the guide renderer can decide per frame which
+    fields to animate.
+    """
+    if not SCREENSHOTS_ENABLED:
+        return
+    if not selectors:
+        return
+
+    _vp = page.viewport_size or _get_viewport_for_layout(CURRENT_LAYOUT)
+    vw = _vp.get("width", 1280)
+    vh = _vp.get("height", 720)
+
+    def _in_viewport(bbox):
+        if not bbox:
+            return False
+        cx = bbox.get("x", 0) + bbox.get("width", 0) / 2
+        cy = bbox.get("y", 0) + bbox.get("height", 0) / 2
+        return 0 <= cx <= vw and 0 <= cy <= vh
+
+    covered = [False] * len(selectors)
+    frame_idx = 0
+
+    while not all(covered) and frame_idx < len(FRAME_LETTERS):
+        # Anchor this frame on the first uncovered field.
+        try:
+            anchor = next(i for i, c in enumerate(covered) if not c)
+        except StopIteration:
+            break
+        _scroll_into_view(page, selectors[anchor])
+
+        bboxes = [_safe_bbox(page, s) for s in selectors]
+        newly_covered = [i for i, b in enumerate(bboxes) if _in_viewport(b) and not covered[i]]
+        if not newly_covered:
+            # No progress — anchor field didn't become visible. Force-mark it so
+            # the loop terminates; the guide will fall back to hiding its cursor.
+            covered[anchor] = True
+            frame_idx += 1
+            continue
+
+        for i in newly_covered:
+            covered[i] = True
+
+        take_screenshot_with_bbox(
+            page,
+            scenario,
+            step,
+            "fill-form",
+            selectors=selectors,
+            precaptured_bboxes=bboxes,
+            frame=FRAME_LETTERS[frame_idx],
+        )
+        frame_idx += 1
+{% if tours_enabled %}
+
+
+# ── In-app tours (config.yaml `tours.enabled`) ────────────────────────────────
+# Plain Python, appended only when tours are on. It rebinds three module-level
+# names instead of editing their bodies (callers look them up at call time), so
+# the hooks and helpers above stay byte-identical for tours-off projects.
+#
+# * every browser context gets the overlay's kill switch, so an app that starts
+#   a tour on its own cannot cover the elements an unrelated test clicks; the
+#   tour replay (`test_<slug>__tour`) lifts it for itself;
+# * a replay writes no coverage record (it would overwrite the scenario's);
+# * `steppy run --guide` deselects replays: guide captures are not tours.
+_TOURS_KILL_SWITCH_JS = "globalThis.__STEPPY_TOURS_DISABLED__ = true;"
+
+
+def _tours_replay_role(node):
+    """The role a `test_<slug>__tour` function was generated for, else None."""
+    return getattr(getattr(node, "function", None), "_steppy_tour_role", None)
+
+
+def _tours_with_kill_switch(build):
+    def _new_role_context(browser, role, **extra):
+        context = build(browser, role, **extra)
+        context.add_init_script(_TOURS_KILL_SWITCH_JS)
+        return context
+
+    return _new_role_context
+
+
+def _tours_skip_replay_coverage(write):
+    def _coverage_stop_and_write(state, request):
+        if state is not None and _tours_replay_role(request.node) is not None:
+            cdp = state.get("cdp")
+            if cdp is not None:
+                try:
+                    cdp.detach()
+                except Exception:
+                    pass
+            return
+        write(state, request)
+
+    return _coverage_stop_and_write
+
+
+def _tours_deselect_in_guide_mode(hook):
+    def pytest_collection_modifyitems(config, items):
+        if GUIDE_MODE:
+            replays = [item for item in items if _tours_replay_role(item) is not None]
+            if replays:
+                config.hook.pytest_deselected(items=replays)
+                items[:] = [item for item in items if _tours_replay_role(item) is None]
+        hook(config, items)
+
+    return pytest_collection_modifyitems
+
+
+_new_role_context = _tours_with_kill_switch(_new_role_context)
+_coverage_stop_and_write = _tours_skip_replay_coverage(_coverage_stop_and_write)
+pytest_collection_modifyitems = _tours_deselect_in_guide_mode(pytest_collection_modifyitems)
+{% endif %}