@brandlab-digital/conformance 3.7.0 → 3.8.0

package/dist/site-system/journeys/page-helpers.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Functions the site-system journeys run inside the page under test. Each one is self-contained: it uses DOM globals
+ * and the other helpers in this file only, because `pageHelpersSource()` injects their source into every document
+ * (as `window.__brandlabSiteSystem`, through Playwright's init script, which a Content Security Policy does not
+ * block). The pure parts (colour, contrast, placement) are unit-tested in Node.
+ */
+/**
+ * The placements `phone_link_click` accepts: site-next's PHONE_CALL_PLACEMENTS (conformance cannot depend on
+ * site-next; a test reads the site-next source and compares). Injected into the page with the helpers.
+ */
+export declare const SITE_SYSTEM_PHONE_PLACEMENTS: readonly string[];
+export type Rgba = [number, number, number, number];
+/** What `watchDisclosure` has seen, in `performance.now()` milliseconds. */
+export interface DisclosureWatch {
+    enter: number | null;
+    leave: number | null;
+    opened: number | null;
+    closed: number | null;
+    open: boolean;
+}
+/**
+ * Whether an element is rendered: connected, with a box, not `visibility: hidden`, not fully transparent and not
+ * inside a closed `<details>` (outside its summary). Chromium gives the content of a closed `<details>` a box, so
+ * the box alone is not enough; `checkVisibility()` settles it where the browser has it.
+ */
+export declare function isRendered(element: Element | null | undefined): boolean;
+/** A short, readable name for an element in a failure message. */
+export declare function describeElement(element: Element): string;
+/** The accessible name, approximately: aria-label, aria-labelledby, the rendered text, then the title. */
+export declare function accessibleName(element: Element): string;
+/**
+ * Where a telephone link reports its tap, exactly as site-next's shared listener resolves it: its own valid
+ * `data-phone-location`, then a `<header>` or `<footer>` ancestor, then the nearest ancestor with a valid value,
+ * otherwise `page`. `invalid` is the nearest declared value when it is not an allowed placement (the listener then
+ * reports the link somewhere else, silently).
+ */
+export declare function phonePlacement(link: Element): {
+    placement: string;
+    invalid: string | null;
+};
+/** Parse a computed colour. `rgb()`/`rgba()` directly; any other syntax (oklch, lab, color()) through a canvas pixel. */
+export declare function parseColour(value: string): Rgba | null;
+/** `top` painted over an opaque `bottom`. */
+export declare function compositeColour(top: Rgba, bottom: Rgba): Rgba;
+/** The WCAG contrast ratio of two opaque colours. */
+export declare function contrastRatio(first: Rgba, second: Rgba): number;
+/**
+ * The opaque colour behind an element, from its own and its ancestors' background colours over a white canvas.
+ * `null` when a background image (a photo or gradient) is in the way: the contrast cannot be computed there.
+ */
+export declare function backgroundBehind(element: Element): Rgba | null;
+/**
+ * Non-text contrast (WCAG 1.4.11) of icon-only controls inside `root`: a link or button with no visible text whose
+ * icon is an SVG must reach 3:1 against what is behind it. Returns one line per failure; controls over a photo are
+ * counted in `unmeasured`.
+ */
+export declare function iconContrastProblems(root: Element): {
+    problems: string[];
+    checked: number;
+    unmeasured: number;
+};
+/**
+ * The phone call bar: the shared `MobileCallBar`, or any fixed or sticky element along the bottom of the screen that
+ * holds a visible telephone link (outside the header and dialogs). `null` when none is on screen.
+ */
+export declare function findCallBar(): Element | null;
+/** Visible quote actions in `root`: links or buttons named like the quote action, or the shared quote hooks. */
+export declare function quoteActions(root: Element, name: {
+    source: string;
+    flags: string;
+}): Element[];
+/** The order of the first visible phone link and quote action in `root`. */
+export declare function actionOrder(root: Element, name: {
+    source: string;
+    flags: string;
+}): 'phone-first' | 'quote-first' | 'incomplete';
+/**
+ * The hero: the shared hero section, else the smallest block around the page's visible H1 that holds a phone link
+ * and a quote action, never above the H1's own section and never `<main>` (without a section, never a block holding
+ * an H2). When none holds both, the H1's section (or its parent): its order then reads "incomplete".
+ */
+export declare function heroRegion(name: {
+    source: string;
+    flags: string;
+}): Element | null;
+/** A point in the page that is not on an interactive element, a menu or anything in `avoid`. */
+export declare function outsidePoint(avoid: Element[]): {
+    x: number;
+    y: number;
+} | null;
+/** Tag an element so Playwright and axe can find it by `[data-brandlab-journey~="<name>"]`. */
+export declare function markElement(element: Element, name: string): void;
+/**
+ * Watch one disclosure: when the pointer enters and leaves its item (and panel), and when the panel it controls
+ * becomes rendered or hidden, timed with `performance.now()`. Attribute and tree changes are sampled at once; style
+ * changes without a DOM change (CSS `:hover`) every animation frame.
+ */
+export declare function watchDisclosure(trigger: Element, panelId: string): void;
+/** The current state of `watchDisclosure`'s watch. */
+export declare function watchState(): DisclosureWatch | null;
+/**
+ * After a Tab press: is the focused element fully hidden under the sticky header or the call bar? Samples nine points
+ * across the visible part of its box; it is hidden when the header or call bar is on top at every one. `repeat` is
+ * true once focus comes back to an element it has already visited.
+ */
+export declare function focusStep(): {
+    done: boolean;
+    repeat: boolean;
+    obscured: string | null;
+    covered: 'header' | 'call bar' | null;
+};
+/**
+ * `focusStep` one animation frame after the focus moved (capped at 50 ms, since a background page may not paint), so
+ * a sticky bar that hides on its observer's next frame is measured after it moved, not mid-transition.
+ */
+export declare function focusStepAfterFrame(): Promise<ReturnType<typeof focusStep>>;
+/** Elements a Tab press can reach, roughly: enough to bound the K5 walk. */
+export declare function tabbableCount(): number;
+declare const PAGE_HELPERS: {
+    isRendered: typeof isRendered;
+    describeElement: typeof describeElement;
+    accessibleName: typeof accessibleName;
+    phonePlacement: typeof phonePlacement;
+    parseColour: typeof parseColour;
+    compositeColour: typeof compositeColour;
+    contrastRatio: typeof contrastRatio;
+    backgroundBehind: typeof backgroundBehind;
+    iconContrastProblems: typeof iconContrastProblems;
+    findCallBar: typeof findCallBar;
+    quoteActions: typeof quoteActions;
+    actionOrder: typeof actionOrder;
+    heroRegion: typeof heroRegion;
+    outsidePoint: typeof outsidePoint;
+    markElement: typeof markElement;
+    watchDisclosure: typeof watchDisclosure;
+    watchState: typeof watchState;
+    focusStep: typeof focusStep;
+    focusStepAfterFrame: typeof focusStepAfterFrame;
+    tabbableCount: typeof tabbableCount;
+};
+/** `window.__brandlabSiteSystem` in a page the journeys opened. */
+export type SiteSystemPageHelpers = typeof PAGE_HELPERS;
+/** The init script that defines `window.__brandlabSiteSystem` in every document of the page. */
+export declare function pageHelpersSource(): string;
+export {};
+//# sourceMappingURL=page-helpers.d.ts.map

package/dist/site-system/journeys/page-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-helpers.d.ts","sourceRoot":"","sources":["../../../src/site-system/journeys/page-helpers.ts"],"names":[],"mappings":"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"}

package/dist/site-system/journeys/page-helpers.js

@@ -0,0 +1,426 @@
+/**
+ * Functions the site-system journeys run inside the page under test. Each one is self-contained: it uses DOM globals
+ * and the other helpers in this file only, because `pageHelpersSource()` injects their source into every document
+ * (as `window.__brandlabSiteSystem`, through Playwright's init script, which a Content Security Policy does not
+ * block). The pure parts (colour, contrast, placement) are unit-tested in Node.
+ */
+/**
+ * The placements `phone_link_click` accepts: site-next's PHONE_CALL_PLACEMENTS (conformance cannot depend on
+ * site-next; a test reads the site-next source and compares). Injected into the page with the helpers.
+ */
+export const SITE_SYSTEM_PHONE_PLACEMENTS = Object.freeze(['header', 'footer', 'hero', 'cta', 'fab', 'contact', 'location', 'page']);
+/**
+ * Whether an element is rendered: connected, with a box, not `visibility: hidden`, not fully transparent and not
+ * inside a closed `<details>` (outside its summary). Chromium gives the content of a closed `<details>` a box, so
+ * the box alone is not enough; `checkVisibility()` settles it where the browser has it.
+ */
+export function isRendered(element) {
+    if (!element || !element.isConnected)
+        return false;
+    for (let details = element.closest('details:not([open])'); details; details = details.parentElement?.closest('details:not([open])') ?? null) {
+        const summary = Array.from(details.children).find((child) => child.tagName === 'SUMMARY');
+        if (!summary || !summary.contains(element))
+            return false;
+    }
+    if (typeof element.checkVisibility === 'function' && !element.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }))
+        return false;
+    const rect = element.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0)
+        return false;
+    if (getComputedStyle(element).visibility !== 'visible')
+        return false;
+    for (let node = element; node; node = node.parentElement) {
+        if (getComputedStyle(node).opacity === '0')
+            return false;
+    }
+    return true;
+}
+/** A short, readable name for an element in a failure message. */
+export function describeElement(element) {
+    const tag = element.tagName.toLowerCase();
+    const label = element.getAttribute('aria-label') ?? element.innerText ?? element.textContent ?? '';
+    const text = label.replace(/\s+/g, ' ').trim().slice(0, 40);
+    const href = element.getAttribute('href');
+    return `${tag}${text ? ` "${text}"` : ''}${href ? ` (${href})` : ''}`;
+}
+/** The accessible name, approximately: aria-label, aria-labelledby, the rendered text, then the title. */
+export function accessibleName(element) {
+    const label = element.getAttribute('aria-label');
+    if (label && label.trim())
+        return label.trim();
+    const labelledBy = element.getAttribute('aria-labelledby');
+    if (labelledBy) {
+        const text = labelledBy.split(/\s+/).map((id) => document.getElementById(id)?.textContent ?? '').join(' ').trim();
+        if (text)
+            return text.replace(/\s+/g, ' ');
+    }
+    const text = (element.innerText ?? element.textContent ?? '').replace(/\s+/g, ' ').trim();
+    return text || (element.getAttribute('title') ?? '').trim();
+}
+/**
+ * Where a telephone link reports its tap, exactly as site-next's shared listener resolves it: its own valid
+ * `data-phone-location`, then a `<header>` or `<footer>` ancestor, then the nearest ancestor with a valid value,
+ * otherwise `page`. `invalid` is the nearest declared value when it is not an allowed placement (the listener then
+ * reports the link somewhere else, silently).
+ */
+export function phonePlacement(link) {
+    const valid = (node) => {
+        const value = node.getAttribute('data-phone-location')?.trim().toLowerCase();
+        return value && SITE_SYSTEM_PHONE_PLACEMENTS.includes(value) ? value : undefined;
+    };
+    const nearest = link.closest('[data-phone-location]');
+    const invalid = nearest && !valid(nearest) ? nearest.getAttribute('data-phone-location') : null;
+    const own = valid(link);
+    if (own)
+        return { placement: own, invalid };
+    if (link.closest('header'))
+        return { placement: 'header', invalid };
+    if (link.closest('footer'))
+        return { placement: 'footer', invalid };
+    for (let node = link.parentElement?.closest('[data-phone-location]') ?? null; node; node = node.parentElement?.closest('[data-phone-location]') ?? null) {
+        const value = valid(node);
+        if (value)
+            return { placement: value, invalid };
+    }
+    return { placement: 'page', invalid };
+}
+/** Parse a computed colour. `rgb()`/`rgba()` directly; any other syntax (oklch, lab, color()) through a canvas pixel. */
+export function parseColour(value) {
+    const text = value.trim().toLowerCase();
+    if (text === 'transparent')
+        return [0, 0, 0, 0];
+    const match = /^rgba?\(([^)]+)\)$/.exec(text);
+    if (match) {
+        const parts = match[1].split(/[\s,/]+/).filter(Boolean);
+        if (parts.length < 3)
+            return null;
+        const channel = (part) => (part.endsWith('%') ? (Number.parseFloat(part) / 100) * 255 : Number.parseFloat(part));
+        const alphaPart = parts[3];
+        const alpha = alphaPart === undefined ? 1 : alphaPart.endsWith('%') ? Number.parseFloat(alphaPart) / 100 : Number.parseFloat(alphaPart);
+        const rgba = [channel(parts[0]), channel(parts[1]), channel(parts[2]), alpha];
+        return rgba.every((part) => Number.isFinite(part)) ? rgba : null;
+    }
+    if (typeof document === 'undefined')
+        return null;
+    const canvas = document.createElement('canvas');
+    canvas.width = 1;
+    canvas.height = 1;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    if (!context)
+        return null;
+    context.clearRect(0, 0, 1, 1);
+    context.fillStyle = value;
+    context.fillRect(0, 0, 1, 1);
+    const [red = 0, green = 0, blue = 0, alpha = 0] = Array.from(context.getImageData(0, 0, 1, 1).data);
+    return [red, green, blue, alpha / 255];
+}
+/** `top` painted over an opaque `bottom`. */
+export function compositeColour(top, bottom) {
+    const alpha = top[3];
+    return [
+        top[0] * alpha + bottom[0] * (1 - alpha),
+        top[1] * alpha + bottom[1] * (1 - alpha),
+        top[2] * alpha + bottom[2] * (1 - alpha),
+        1,
+    ];
+}
+/** The WCAG contrast ratio of two opaque colours. */
+export function contrastRatio(first, second) {
+    const luminance = (colour) => {
+        const [red, green, blue] = colour.slice(0, 3).map((channel) => {
+            const value = channel / 255;
+            return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+        });
+        return 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+    };
+    const [light, dark] = [luminance(first), luminance(second)].sort((left, right) => right - left);
+    return (light + 0.05) / (dark + 0.05);
+}
+/**
+ * The opaque colour behind an element, from its own and its ancestors' background colours over a white canvas.
+ * `null` when a background image (a photo or gradient) is in the way: the contrast cannot be computed there.
+ */
+export function backgroundBehind(element) {
+    const layers = [];
+    for (let node = element; node; node = node.parentElement) {
+        const style = getComputedStyle(node);
+        if (style.backgroundImage && style.backgroundImage !== 'none')
+            return null;
+        const colour = parseColour(style.backgroundColor);
+        if (colour && colour[3] > 0) {
+            layers.push(colour);
+            if (colour[3] >= 1)
+                break;
+        }
+    }
+    return layers.reverse().reduce((bottom, top) => compositeColour(top, bottom), [255, 255, 255, 1]);
+}
+/**
+ * Non-text contrast (WCAG 1.4.11) of icon-only controls inside `root`: a link or button with no visible text whose
+ * icon is an SVG must reach 3:1 against what is behind it. Returns one line per failure; controls over a photo are
+ * counted in `unmeasured`.
+ */
+export function iconContrastProblems(root) {
+    const problems = [];
+    let checked = 0;
+    let unmeasured = 0;
+    const paintOf = (svg) => {
+        for (const shape of Array.from(svg.querySelectorAll('path, circle, rect, ellipse, line, polyline, polygon, text, use'))) {
+            if (!isRendered(shape))
+                continue;
+            const style = getComputedStyle(shape);
+            for (const [paint, opacity] of [[style.fill, style.fillOpacity], [style.stroke, style.strokeOpacity]]) {
+                if (!paint || paint === 'none' || paint.startsWith('url('))
+                    continue;
+                const colour = parseColour(paint);
+                const alpha = colour ? colour[3] * Number(opacity || 1) * Number(style.opacity || 1) : 0;
+                if (colour && alpha > 0)
+                    return [colour[0], colour[1], colour[2], alpha];
+            }
+        }
+        return null;
+    };
+    for (const control of Array.from(root.querySelectorAll('a[href], button'))) {
+        if (!isRendered(control))
+            continue;
+        if ((control.innerText ?? '').trim())
+            continue;
+        const svg = control.querySelector('svg');
+        if (!svg || !isRendered(svg))
+            continue;
+        const paint = paintOf(svg);
+        if (!paint)
+            continue;
+        const background = backgroundBehind(svg);
+        if (!background) {
+            unmeasured += 1;
+            continue;
+        }
+        checked += 1;
+        const ratio = contrastRatio(compositeColour(paint, background), background);
+        if (ratio < 3)
+            problems.push(`${describeElement(control)}: its icon is ${ratio.toFixed(2)}:1 against its background (needs 3:1)`);
+    }
+    return { problems, checked, unmeasured };
+}
+/**
+ * The phone call bar: the shared `MobileCallBar`, or any fixed or sticky element along the bottom of the screen that
+ * holds a visible telephone link (outside the header and dialogs). `null` when none is on screen.
+ */
+export function findCallBar() {
+    const tagged = Array.from(document.querySelectorAll('[data-bl="call-bar"], [data-bl="callbar"], [data-bl="mobile-call-bar"]')).find(isRendered);
+    if (tagged)
+        return tagged;
+    const height = window.innerHeight;
+    for (const element of Array.from(document.body.querySelectorAll('*'))) {
+        const position = getComputedStyle(element).position;
+        if (position !== 'fixed' && position !== 'sticky')
+            continue;
+        if (element.closest('header, dialog, [role="dialog"]'))
+            continue;
+        const rect = element.getBoundingClientRect();
+        if (rect.height <= 0 || rect.bottom < height - 4 || rect.top < height / 2)
+            continue;
+        if (!isRendered(element))
+            continue;
+        if (Array.from(element.querySelectorAll('a[href^="tel:"]')).some(isRendered))
+            return element;
+    }
+    return null;
+}
+/** Visible quote actions in `root`: links or buttons named like the quote action, or the shared quote hooks. */
+export function quoteActions(root, name) {
+    const pattern = new RegExp(name.source, name.flags);
+    return Array.from(root.querySelectorAll('a[href], button')).filter((element) => {
+        if (!isRendered(element) || element.getAttribute('href')?.startsWith('tel:'))
+            return false;
+        if (element.matches('[data-bl="quote-button"], [data-bl-cta^="quote"], [data-lead-cta^="quote"]'))
+            return true;
+        return pattern.test(accessibleName(element));
+    });
+}
+/** The order of the first visible phone link and quote action in `root`. */
+export function actionOrder(root, name) {
+    const phone = Array.from(root.querySelectorAll('a[href^="tel:"]')).find(isRendered);
+    const quote = quoteActions(root, name)[0];
+    if (!phone || !quote)
+        return 'incomplete';
+    return phone.compareDocumentPosition(quote) & Node.DOCUMENT_POSITION_FOLLOWING ? 'phone-first' : 'quote-first';
+}
+/**
+ * The hero: the shared hero section, else the smallest block around the page's visible H1 that holds a phone link
+ * and a quote action, never above the H1's own section and never `<main>` (without a section, never a block holding
+ * an H2). When none holds both, the H1's section (or its parent): its order then reads "incomplete".
+ */
+export function heroRegion(name) {
+    const heading = Array.from(document.querySelectorAll('h1')).find(isRendered);
+    if (!heading)
+        return null;
+    const tagged = heading.closest('[data-bl-section="hero"]');
+    if (tagged)
+        return tagged;
+    const section = heading.closest('section');
+    const fallback = section ?? heading.parentElement;
+    for (let node = heading.parentElement; node && node !== document.body && node.tagName !== 'MAIN'; node = node.parentElement) {
+        if (!section && node.querySelector('h2'))
+            break;
+        if (Array.from(node.querySelectorAll('a[href^="tel:"]')).some(isRendered) && quoteActions(node, name).length > 0)
+            return node;
+        if (node === section)
+            break;
+    }
+    return fallback && fallback.tagName !== 'MAIN' ? fallback : heading;
+}
+/** A point in the page that is not on an interactive element, a menu or anything in `avoid`. */
+export function outsidePoint(avoid) {
+    const interactive = 'a[href], button, input, select, textarea, label, summary, details, iframe, video, audio, [role="button"], [role="link"], [role="menuitem"], [role="tab"], [tabindex], [contenteditable=""], [contenteditable="true"]';
+    for (let row = 9; row >= 3; row -= 1) {
+        for (let column = 1; column <= 9; column += 1) {
+            const x = Math.round((window.innerWidth * column) / 10);
+            const y = Math.round((window.innerHeight * row) / 10);
+            const element = document.elementFromPoint(x, y);
+            if (!element || avoid.some((region) => region.contains(element)))
+                continue;
+            if (element.closest(interactive) || element.closest('header, nav, dialog, [role="dialog"]'))
+                continue;
+            return { x, y };
+        }
+    }
+    return null;
+}
+/** Tag an element so Playwright and axe can find it by `[data-brandlab-journey~="<name>"]`. */
+export function markElement(element, name) {
+    const names = new Set((element.getAttribute('data-brandlab-journey') ?? '').split(/\s+/).filter(Boolean));
+    names.add(name);
+    element.setAttribute('data-brandlab-journey', [...names].join(' '));
+}
+/**
+ * Watch one disclosure: when the pointer enters and leaves its item (and panel), and when the panel it controls
+ * becomes rendered or hidden, timed with `performance.now()`. Attribute and tree changes are sampled at once; style
+ * changes without a DOM change (CSS `:hover`) every animation frame.
+ */
+export function watchDisclosure(trigger, panelId) {
+    const item = trigger.closest('li') ?? trigger.parentElement ?? trigger;
+    const panel = () => document.getElementById(panelId);
+    const inside = (node) => node instanceof Node && (item.contains(node) || Boolean(panel()?.contains(node)));
+    const state = { enter: null, leave: null, opened: null, closed: null, open: isRendered(panel()) };
+    const sample = () => {
+        const open = isRendered(panel());
+        if (open === state.open)
+            return;
+        state.open = open;
+        if (open && state.opened === null)
+            state.opened = performance.now();
+        if (!open && state.closed === null)
+            state.closed = performance.now();
+    };
+    const onOver = (event) => {
+        if (state.enter === null && inside(event.target))
+            state.enter = performance.now();
+    };
+    const onOut = (event) => {
+        if (state.leave === null && inside(event.target) && !inside(event.relatedTarget))
+            state.leave = performance.now();
+    };
+    const observer = new MutationObserver(sample);
+    observer.observe(document.documentElement, { attributes: true, childList: true, subtree: true });
+    let frame = 0;
+    const loop = () => {
+        sample();
+        frame = requestAnimationFrame(loop);
+    };
+    loop();
+    document.addEventListener('pointerover', onOver, true);
+    document.addEventListener('pointerout', onOut, true);
+    const previous = window.__brandlabSiteSystemWatch;
+    previous?.stop();
+    window.__brandlabSiteSystemWatch = {
+        state,
+        stop() {
+            observer.disconnect();
+            cancelAnimationFrame(frame);
+            document.removeEventListener('pointerover', onOver, true);
+            document.removeEventListener('pointerout', onOut, true);
+        },
+    };
+}
+/** The current state of `watchDisclosure`'s watch. */
+export function watchState() {
+    const watch = window.__brandlabSiteSystemWatch;
+    return watch ? { ...watch.state } : null;
+}
+/**
+ * After a Tab press: is the focused element fully hidden under the sticky header or the call bar? Samples nine points
+ * across the visible part of its box; it is hidden when the header or call bar is on top at every one. `repeat` is
+ * true once focus comes back to an element it has already visited.
+ */
+export function focusStep() {
+    const element = document.activeElement;
+    const store = window;
+    store.__brandlabSiteSystemFocus ??= new WeakSet();
+    if (!element || element === document.body || element === document.documentElement)
+        return { done: true, repeat: false, obscured: null, covered: null };
+    const repeat = store.__brandlabSiteSystemFocus.has(element);
+    store.__brandlabSiteSystemFocus.add(element);
+    const header = document.querySelector('[data-brandlab-journey~="header"]')
+        ?? Array.from(document.querySelectorAll('[data-bl="header"], header')).find((candidate) => isRendered(candidate) && !candidate.closest('main, article, section, aside, footer'))
+        ?? null;
+    const callBar = findCallBar();
+    if (header?.contains(element) || callBar?.contains(element))
+        return { done: false, repeat, obscured: null, covered: null };
+    const rect = element.getBoundingClientRect();
+    const left = Math.max(rect.left, 0);
+    const right = Math.min(rect.right, window.innerWidth);
+    const top = Math.max(rect.top, 0);
+    const bottom = Math.min(rect.bottom, window.innerHeight);
+    if (right - left < 1 || bottom - top < 1)
+        return { done: false, repeat, obscured: null, covered: null };
+    let coveredBy = null;
+    for (const fx of [0.15, 0.5, 0.85]) {
+        for (const fy of [0.15, 0.5, 0.85]) {
+            const hit = document.elementFromPoint(left + (right - left) * fx, top + (bottom - top) * fy);
+            if (!hit || element.contains(hit))
+                return { done: false, repeat, obscured: null, covered: null };
+            if (header?.contains(hit))
+                coveredBy ??= 'header';
+            else if (callBar?.contains(hit))
+                coveredBy ??= 'call bar';
+            else
+                return { done: false, repeat, obscured: null, covered: null };
+        }
+    }
+    return { done: false, repeat, obscured: describeElement(element), covered: coveredBy };
+}
+/**
+ * `focusStep` one animation frame after the focus moved (capped at 50 ms, since a background page may not paint), so
+ * a sticky bar that hides on its observer's next frame is measured after it moved, not mid-transition.
+ */
+export function focusStepAfterFrame() {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(focusStep());
+        };
+        requestAnimationFrame(() => finish());
+        setTimeout(finish, 50);
+    });
+}
+/** Elements a Tab press can reach, roughly: enough to bound the K5 walk. */
+export function tabbableCount() {
+    const selector = 'a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), select:not([disabled]), textarea:not([disabled]), summary, iframe, [tabindex]:not([tabindex="-1"])';
+    return Array.from(document.querySelectorAll(selector)).filter(isRendered).length;
+}
+const PAGE_HELPERS = {
+    isRendered, describeElement, accessibleName, phonePlacement, parseColour, compositeColour, contrastRatio, backgroundBehind,
+    iconContrastProblems, findCallBar, quoteActions, actionOrder, heroRegion, outsidePoint, markElement, watchDisclosure,
+    watchState, focusStep, focusStepAfterFrame, tabbableCount,
+};
+/** The init script that defines `window.__brandlabSiteSystem` in every document of the page. */
+export function pageHelpersSource() {
+    const names = Object.keys(PAGE_HELPERS);
+    return `(() => {\nconst SITE_SYSTEM_PHONE_PLACEMENTS = ${JSON.stringify(SITE_SYSTEM_PHONE_PLACEMENTS)};\n${Object.values(PAGE_HELPERS).map((helper) => helper.toString()).join('\n')}\nwindow.__brandlabSiteSystem = { ${names.join(', ')} };\n})();`;
+}
+//# sourceMappingURL=page-helpers.js.map