screenshot-ready 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,239 @@
-# Temporary Holding Version
+# screenshot-ready
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Get a Playwright or Puppeteer page ready for `page.screenshot()`: wait for web fonts, load lazy images, hide cookie banners and freeze animations, in one call with a time budget.
+
+```bash
+npm install screenshot-ready
+```
+
+## Why
+
+`page.screenshot()` looks fine on example.com. On real sites the same call keeps producing captures like these:
+
+- **Blank boxes where images should be.** `<img loading="lazy">` and IntersectionObserver loaders only fetch images near the viewport. A full-page capture never scrolls, so everything below the first screen comes out empty.
+- **A cookie banner over the page.** Half the sites you capture show a consent dialog, often with a dark backdrop and the page scroll locked behind it.
+- **Text in the wrong font, or no text at all.** The load event can fire before web fonts arrive. With `font-display: block` the text is invisible until they do.
+- **Two captures of the same page never match.** Spinners, fade-ins, carousels and the blinking caret make every capture a little different, which breaks visual diffs.
+- **A capture taken while data is still arriving.** The page fires its API calls after load and the capture shows loading skeletons.
+
+`screenshot-ready` fixes these with small, bounded steps that run inside the page. It works with Playwright and Puppeteer pages and has no runtime dependencies.
+
+## Quick start
+
+### Playwright
+
+```js
+import { chromium } from 'playwright';
+import { prepareForCapture } from 'screenshot-ready';
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+await page.goto('https://example.com', { waitUntil: 'load' });
+
+await prepareForCapture(page);
+await page.screenshot({ path: 'page.png', fullPage: true });
+
+await browser.close();
+```
+
+### Puppeteer
+
+```js
+import puppeteer from 'puppeteer';
+import { prepareForCapture } from 'screenshot-ready';
+
+const browser = await puppeteer.launch();
+const page = await browser.newPage();
+await page.setViewport({ width: 1280, height: 800 });
+await page.goto('https://example.com', { waitUntil: 'load' });
+
+await prepareForCapture(page);
+await page.screenshot({ path: 'page.png', fullPage: true });
+
+await browser.close();
+```
+
+CommonJS works too: `const { prepareForCapture } = require('screenshot-ready')`.
+
+### One call
+
+```js
+import { readyScreenshot } from 'screenshot-ready';
+
+const png = await readyScreenshot(page, { fullPage: true, path: 'page.png', prepare: { timeout: 10000 } });
+```
+
+Everything except `prepare` goes to `page.screenshot()` unchanged.
+
+## What prepareForCapture does
+
+In this order, each step with its own cap, all inside a total budget (`timeout`, default 15 seconds):
+
+1. **Hide consent banners** (`consent`). Known consent platforms by selector, plus fixed overlays that mention cookies or consent and offer a choice. Nothing is clicked.
+2. **Hide your selectors** (`hide`). Chat widgets, promo bars, anything you list.
+3. **Wait for web fonts** (`fonts`, 3 s cap).
+4. **Scroll through the page** (`lazy`, 5 s cap, up to 20,000 px) so lazy images, IntersectionObserver loaders and scroll-reveal effects fire, then scroll back.
+5. **Wait for the network to go quiet** (`network`, 3 s cap, 500 ms of quiet). Requests started by the scroll are counted.
+6. **Wait for images to load and decode** (`images`, 3 s cap).
+7. **Hide consent banners again**, for dialogs that showed up late.
+8. **Wait for fonts again** (1 s cap), for fonts used by content that just loaded.
+9. **Freeze animations** (`freeze`). Finite animations and transitions jump to their end state, infinite ones pause, the caret is hidden, playing media pauses.
+
+It never throws. A step that fails or runs out of time is reported and the rest still run:
+
+```js
+const report = await prepareForCapture(page);
+// { ms: 1840, timedOut: false, steps: [{ step: 'consent', ms: 12, ok: true, timedOut: false, result: { hidden: 2, ... } }, ...] }
+```
+
+Turn any step off or tune it:
+
+```js
+await prepareForCapture(page, {
+  timeout: 10000,
+  consent: { selectors: ['.my-site-cookie-bar'] },
+  hide: ['#intercom-container', '.promo-ribbon'],
+  lazy: { maxHeight: 8000 },
+  network: { quietMs: 800 },
+  freeze: false,
+});
+```
+
+## API
+
+Every helper takes a Playwright or Puppeteer `Page` as its first argument. Times are in milliseconds, sizes in CSS pixels. The helpers return a result object and report timeouts in it instead of throwing. They do throw if the page itself is gone (closed or crashed); `prepareForCapture` catches that too.
+
+### `prepareForCapture(page, options?)`
+
+Runs the steps above. Options:
+
+| Option | Default | |
+|---|---|---|
+| `timeout` | `15000` | Total budget. The last two quick steps may add up to about a second. |
+| `consent` | `true` | `false`, or options for `hideConsentBanners` (without `timeout`). |
+| `hide` | `[]` | Selectors to hide. |
+| `hideMode` | `'visibility'` | `'visibility'` keeps the layout, `'display'` removes the element from it. |
+| `fonts` | `true` | `false`, or `{ timeout }`. |
+| `lazy` | `true` | `false`, or options for `scrollThrough`. |
+| `network` | `true` | `false`, or options for `waitForNetworkQuiet`. |
+| `images` | `true` | `false`, or options for `waitForImages`. |
+| `freeze` | `true` | `false`, or options for `freezeAnimations`. |
+
+Returns `{ ms, timedOut, steps }`, where each step is `{ step, ms, ok, timedOut, skipped?, error?, result? }`.
+
+### `readyScreenshot(page, options?)`
+
+`prepareForCapture(page, options.prepare)`, then `page.screenshot(rest)`. Returns what `page.screenshot()` returns.
+
+### `hideConsentBanners(page, options?)`
+
+| Option | Default | |
+|---|---|---|
+| `selectors` | `[]` | More selectors to hide. |
+| `replaceBuiltIn` | `false` | Use only your selectors. |
+| `heuristics` | `true` | Also match fixed overlays by text and buttons. |
+| `unlockScroll` | `true` | Reset `overflow: hidden` (and a pinned `position: fixed` body) left by the dialog. |
+| `timeout` | `2000` | |
+
+Returns `{ hidden, bySelector, byHeuristic, overlays, scrollUnlocked, details, timedOut }`. `details` lists what was hidden, like `div#onetrust-consent-sdk`.
+
+Built-in selectors cover OneTrust, Cookiebot, Didomi, Quantcast Choice, TrustArc, Usercentrics, Osano, Google Funding Choices, Sourcepoint, CookieYes, Complianz, iubenda, Termly, Borlabs, Ketch, CookieConsent and Klaro. The list is exported as `CONSENT_SELECTORS`.
+
+The heuristic pass looks for elements that are `position: fixed` (or sticky, or a dialog), visible, mention cookies or consent (English plus common European languages) and contain an accept, reject or settings button. It skips elements that look like page content (a full-screen element with `main`, `nav`, `h1`, video or several images) and menus with many links. When it hides a banner it also hides an empty full-screen dimming layer behind it.
+
+Elements are hidden with a stylesheet rule and a `data-screenshot-ready-hidden` attribute, not removed, so page scripts that hold references to them keep working. The selector rules stay in the page, so a banner the platform injects later is hidden as well.
+
+### `hideElements(page, selectors, options?)`
+
+Hides elements with a stylesheet rule. `options.mode`: `'visibility'` (default) or `'display'`. Returns how many elements matched.
+
+### `waitForFonts(page, options?)`
+
+Waits for `document.fonts` to finish loading, including fonts that start loading during the wait. `timeout` default 3000. Returns `{ timedOut, loaded, pending, failed }` with family names.
+
+### `scrollThrough(page, options?)`
+
+Scrolls down in viewport-sized steps, then back to the original position. If the window does not scroll but a full-height container does (common in app layouts), it scrolls that container.
+
+| Option | Default | |
+|---|---|---|
+| `timeout` | `5000` | Stop scrolling after this long. |
+| `maxHeight` | `20000` | Stop this far down (infinite feeds keep growing). |
+| `stepRatio` | `0.85` | Step size as a share of the viewport height. |
+| `stepDelayMs` | `0` | Extra wait per step, for pages that load on a scroll debounce. |
+
+Returns `{ steps, reachedPx, pageHeight, scroller, timedOut }`.
+
+### `loadLazyContent(page, options?)`
+
+`scrollThrough`, then waits for the network to go quiet and for images to decode. Takes the `scrollThrough` options plus `loadTimeout` (default 5000).
+
+### `waitForNetworkQuiet(page, options?)` and `trackRequests(page)`
+
+Waits until no request has been open for `quietMs` (default 500), up to `timeout` (default 5000). After `relaxAfterMs` (default half the timeout) up to two open requests still count as quiet, so long-polls and analytics beacons do not hold the capture forever. `maxInflight` sets the strict allowance (default 0).
+
+It listens to the page's request events, so it only sees requests that start after the call. To count everything, start tracking before you navigate:
+
+```js
+const tracker = trackRequests(page);
+await page.goto(url);
+await tracker.waitForQuiet({ quietMs: 500, timeout: 5000 });
+tracker.stop();
+```
+
+Given an object without events (a Frame), it falls back to watching Resource Timing entries inside the page.
+
+### `waitForImages(page, options?)`
+
+Waits for rendered `<img>` elements within `maxHeight` (default 20000) to load and decode, up to `timeout` (default 5000). Broken images count as settled. Lazy images the browser will not fetch at the current scroll position (off to the side in a carousel, or clipped inside a collapsed panel) are skipped, since they are not in the capture. Returns `{ total, ready, broken, pending, timedOut }`.
+
+### `freezeAnimations(page, options?)`
+
+| Option | Default | |
+|---|---|---|
+| `caret` | `true` | Hide the text caret. |
+| `pauseMedia` | `true` | Pause playing video and audio. |
+
+Returns `{ finished, paused, media, timedOut }`. Playwright users can also pass `animations: 'disabled'` and `caret: 'hide'` to `page.screenshot()`; this helper does the same for Puppeteer and also covers transitions that start after the call.
+
+## Limits
+
+Be aware of what this does not do:
+
+- **Consent banners inside cross-origin iframes** are hidden through their container on the page (Sourcepoint, for example), but the library cannot look inside the iframe. A platform outside the built-in list that renders only in an iframe needs your own selector.
+- **Closed shadow roots** cannot be inspected. Open shadow roots are searched.
+- **The heuristics are conservative on purpose.** They will miss some custom banners. Add a selector for those rather than loosening the rules.
+- **Hiding is not consenting.** The site behaves as if the visitor has not chosen yet, so content that waits for consent (some embeds, some ads) stays empty.
+- **JavaScript-driven motion** (a carousel on `setInterval`, canvas or WebGL animations) is not frozen. Hide it or wait for a known state.
+- **Lazy content past `maxHeight`** is left alone, so infinite feeds stay finite. Raise `maxHeight` if your pages are taller.
+- **Network quiet** only sees requests that start after the call, unless you use `trackRequests` before navigating.
+- **Bot checks and logins** are out of scope. If the site serves a challenge page, that is what gets captured.
+- Tested with Chromium in Playwright and Puppeteer. The code uses standard DOM APIs, but Firefox and WebKit are not part of the test suite yet.
+
+## Don't want to run browsers?
+
+Running headless browsers in production means keeping Chromium and its system libraries installed, sizing memory for it and handling crashes and timeouts. [SnapRender](https://snap-render.com) does this as a hosted API, including cookie banner removal and lazy-image loading for full-page captures (free plan: 200 captures a month).
+
+```js
+const url = 'https://app.snap-render.com/v1/screenshot?url=https://example.com&full_page=true&lazy_load=true';
+const res = await fetch(url, { headers: { 'X-API-Key': process.env.SNAPRENDER_API_KEY } });
+await fs.promises.writeFile('page.png', Buffer.from(await res.arrayBuffer()));
+```
+
+Related: [pagequiet](https://github.com/User0856/pagequiet) watches pages for visible changes and alerts only when the text a reader sees changes.
+
+## Development
+
+```bash
+npm install
+npx playwright install chromium
+npx puppeteer browsers install chrome
+npm run build
+npm test
+```
+
+The tests drive headless Chromium through both Playwright and Puppeteer against local fixture pages (lazy images, consent banners, slow web fonts, animations) served on 127.0.0.1.
+
+## License
+
+MIT

package/dist/cjs/consent.d.ts

@@ -0,0 +1,50 @@
+import { type PageLike } from './page.js';
+/**
+ * Containers of common consent management platforms (CMPs). Hidden with a stylesheet rule, so a banner the
+ * CMP injects after the call is hidden too. Kept to IDs and class names the vendors use for the banner itself.
+ */
+export declare const CONSENT_SELECTORS: readonly string[];
+export interface HideConsentOptions {
+    /** More selectors to hide, on top of the built-in list. */
+    selectors?: string[];
+    /** Use only `selectors` (yours) instead of adding them to the built-in list. Default false. */
+    replaceBuiltIn?: boolean;
+    /** Also find consent banners by position and text (fixed overlays that mention cookies and offer a choice). Default true. */
+    heuristics?: boolean;
+    /** Undo the scroll lock (overflow hidden on html/body) a consent dialog leaves behind. Default true. */
+    unlockScroll?: boolean;
+    /** Give up after this many ms. Default 2000. */
+    timeout?: number;
+}
+export interface HideConsentResult {
+    /** Elements hidden in total. */
+    hidden: number;
+    /** Elements matched by the selector list. */
+    bySelector: number;
+    /** Elements matched by the position and text heuristics. */
+    byHeuristic: number;
+    /** Empty full-screen backdrops hidden along with a banner. */
+    overlays: number;
+    /** True when overflow or position on html/body was reset. */
+    scrollUnlocked: boolean;
+    /** Short descriptions of what was hidden, like `div#onetrust-consent-sdk`. */
+    details: string[];
+    timedOut: boolean;
+}
+export declare const HIDDEN_ATTRIBUTE = "data-screenshot-ready-hidden";
+/**
+ * Hides cookie and consent banners without clicking anything: known consent platforms by selector, plus
+ * fixed overlays that talk about cookies or consent and offer a choice. It never clicks "accept", so no
+ * consent is given and the page does not reload. Elements are hidden with CSS, not removed, so page scripts
+ * that reference them keep working.
+ */
+export declare function hideConsentBanners(page: PageLike, options?: HideConsentOptions): Promise<HideConsentResult>;
+export interface HideElementsOptions {
+    /** 'visibility' keeps the layout (default), 'display' removes the element from the layout. */
+    mode?: 'visibility' | 'display';
+}
+/**
+ * Hides elements you name (chat widgets, promo bars, ads) with a stylesheet rule, so they stay hidden if they
+ * are re-rendered. Returns how many elements matched at the time of the call.
+ */
+export declare function hideElements(page: PageLike, selectors: string[], options?: HideElementsOptions): Promise<number>;

package/dist/cjs/consent.js

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HIDDEN_ATTRIBUTE = exports.CONSENT_SELECTORS = void 0;
+exports.hideConsentBanners = hideConsentBanners;
+exports.hideElements = hideElements;
+const page_js_1 = require("./page.js");
+/**
+ * Containers of common consent management platforms (CMPs). Hidden with a stylesheet rule, so a banner the
+ * CMP injects after the call is hidden too. Kept to IDs and class names the vendors use for the banner itself.
+ */
+exports.CONSENT_SELECTORS = [
+    // OneTrust
+    '#onetrust-consent-sdk',
+    '#onetrust-banner-sdk',
+    '.onetrust-pc-dark-filter',
+    // Cookiebot
+    '#CybotCookiebotDialog',
+    '#CybotCookiebotDialogBodyUnderlay',
+    // Didomi
+    '#didomi-host',
+    '#didomi-popup',
+    '#didomi-notice',
+    '.didomi-popup-backdrop',
+    // Quantcast Choice
+    '#qc-cmp2-container',
+    '.qc-cmp2-container',
+    '#qcCmpUi',
+    // TrustArc
+    '#truste-consent-track',
+    '#consent_blackbar',
+    '#trustarc-banner-overlay',
+    '.truste_overlay',
+    '.truste_box_overlay',
+    // Usercentrics
+    '#usercentrics-root',
+    '#usercentrics-cmp-ui',
+    // Osano
+    '.osano-cm-window',
+    '.osano-cm-dialog',
+    // Google Funding Choices
+    '.fc-consent-root',
+    // Sourcepoint
+    '[id^="sp_message_container"]',
+    // CookieYes
+    '.cky-consent-container',
+    '.cky-overlay',
+    // Complianz
+    '#cmplz-cookiebanner-container',
+    // iubenda
+    '#iubenda-cs-banner',
+    // Termly
+    '#termly-code-snippet-support',
+    // Borlabs Cookie
+    '#BorlabsCookieBox',
+    // Ketch
+    '#lanyard_root',
+    // CookieConsent (orestbida) v3
+    '#cc-main',
+    // Cookie Consent by Osano (open-source script)
+    '.cc-window.cc-banner',
+    '.cc-window.cc-floating',
+    // Klaro
+    '.klaro .cookie-notice',
+    '.klaro .cookie-modal',
+];
+exports.HIDDEN_ATTRIBUTE = 'data-screenshot-ready-hidden';
+function consentInPage(arg) {
+    const ATTR = arg.attr;
+    const details = [];
+    const describe = (el) => {
+        const id = el.id ? `#${el.id}` : '';
+        const cls = !id && typeof el.className === 'string' && el.className.trim() ? `.${el.className.trim().split(/\s+/).slice(0, 2).join('.')}` : '';
+        return `${el.tagName.toLowerCase()}${id}${cls}`;
+    };
+    const roots = [document];
+    const collectShadowRoots = (root) => {
+        for (const el of Array.from(root.querySelectorAll('*'))) {
+            if (el.shadowRoot) {
+                roots.push(el.shadowRoot);
+                collectShadowRoots(el.shadowRoot);
+            }
+        }
+    };
+    collectShadowRoots(document);
+    const allIn = (root) => root === document ? (document.body ? Array.from(document.body.querySelectorAll('*')) : []) : Array.from(root.querySelectorAll('*'));
+    // A stylesheet in the document plus the attribute: wins over the CMP's own inline styles and keeps applying
+    // when the CMP re-renders. Inside shadow roots the document stylesheet does not apply, so those get an
+    // inline !important style as well.
+    const hide = (el, kind) => {
+        if (el.hasAttribute(ATTR))
+            return false;
+        el.setAttribute(ATTR, kind);
+        if (el.getRootNode() !== document && el instanceof HTMLElement)
+            el.style.setProperty('display', 'none', 'important');
+        if (details.length < 50)
+            details.push(describe(el));
+        return true;
+    };
+    const styleId = 'screenshot-ready-consent-style';
+    let style = document.getElementById(styleId);
+    if (!style) {
+        style = document.createElement('style');
+        style.id = styleId;
+        (document.head || document.documentElement).appendChild(style);
+    }
+    const valid = arg.selectors.filter((sel) => {
+        try {
+            document.querySelector(sel);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    // One rule per selector, so one bad selector cannot void the rest.
+    style.textContent = [...valid.map((sel) => `${sel}{display:none!important}`), `[${ATTR}]{display:none!important}`].join('\n');
+    let bySelector = 0;
+    for (const root of roots) {
+        for (const sel of valid) {
+            for (const el of Array.from(root.querySelectorAll(sel))) {
+                if (hide(el, 'cmp'))
+                    bySelector += 1;
+            }
+        }
+    }
+    let byHeuristic = 0;
+    let overlays = 0;
+    if (arg.heuristics) {
+        const vw = window.innerWidth;
+        const vh = window.innerHeight;
+        const consentText = /\b(cookies?|cookie-?richtlinie|consent|gdpr|dsgvo|ccpa|datenschutz\w*|einwilligung|consentement|consentimiento|consenso|toestemming|privacy (settings|preferences|choices|center)|your privacy|tracking technolog\w+)\b/i;
+        const actionText = /\b(accept|agree|allow|got it|i understand|understood|ok(ay)?|reject|decline|deny|refuse|manage|customi[sz]e|preferences|settings|necessary|essential|continue|akzeptieren|zustimmen|ablehnen|einverstanden|accepter|refuser|aceptar|rechazar|accetta|accetto|rifiuta|accepteren|weigeren|aceitar|rejeitar)\b/i;
+        const controls = 'button, a, [role="button"], input[type="button"], input[type="submit"]';
+        const visible = (el, cs) => {
+            if (cs.display === 'none' || cs.visibility === 'hidden' || Number(cs.opacity) === 0)
+                return false;
+            const r = el.getBoundingClientRect();
+            return r.width > 0 && r.height > 0;
+        };
+        const hasAction = (el) => Array.from(el.querySelectorAll(controls)).some((c) => {
+            const t = (c.innerText || c.value || c.getAttribute('aria-label') || '').trim();
+            return t.length > 0 && t.length <= 40 && actionText.test(t);
+        });
+        // Things a consent banner does not contain. Guards against hiding a fixed full-screen app shell.
+        const looksLikePage = (el) => el.querySelector('main, article, nav, h1, video, canvas') !== null || el.querySelectorAll('img').length > 3;
+        // Many visible links: a menu or footer that happens to mention cookies, unless the text reads like a
+        // consent notice (some consent walls list partners and policies as links).
+        const consentSentence = /\b(we|this (site|website)|our partners)\b[^.]{0,60}\buses?\b[^.]{0,40}\bcookies\b|\bcookies? (to|for|and similar)\b|\b(your|votre|ihre|su|tua|uw) (consent|consentement|einwilligung|consentimiento|consenso|toestemming)\b|\buse of cookies\b/i;
+        const navLike = (el, text) => Array.from(el.querySelectorAll('a[href]')).filter((a) => a.getClientRects().length > 0).length >= 10 && !consentSentence.test(text);
+        const banners = [];
+        for (const root of roots) {
+            for (const el of allIn(root)) {
+                if (el.closest(`[${ATTR}]`))
+                    continue;
+                const cs = getComputedStyle(el);
+                const isDialog = el.matches('dialog[open], [role="dialog"], [role="alertdialog"], [aria-modal="true"]');
+                if (cs.position !== 'fixed' && cs.position !== 'sticky' && !isDialog)
+                    continue;
+                if (!visible(el, cs))
+                    continue;
+                const text = (el.innerText || el.textContent || '').trim();
+                if (text.length === 0 || text.length > 3000)
+                    continue;
+                if (!consentText.test(text) || !hasAction(el))
+                    continue;
+                if (navLike(el, text))
+                    continue;
+                const r = el.getBoundingClientRect();
+                const large = r.width * r.height >= vw * vh * 0.5;
+                if (large && looksLikePage(el))
+                    continue;
+                // A sticky element is part of the page flow (headers, footers): only hide it when the text is clearly a
+                // consent notice, not a "Cookie settings" link among others.
+                if (cs.position === 'sticky' && !consentSentence.test(text))
+                    continue;
+                if (hide(el, 'heuristic')) {
+                    byHeuristic += 1;
+                    banners.push(el);
+                }
+            }
+        }
+        // Empty dimming layers that sit behind a consent dialog.
+        if (banners.length > 0 || bySelector > 0) {
+            for (const root of roots) {
+                for (const el of allIn(root)) {
+                    if (el.closest(`[${ATTR}]`))
+                        continue;
+                    const cs = getComputedStyle(el);
+                    if (cs.position !== 'fixed' || !visible(el, cs))
+                        continue;
+                    if ((el.innerText || '').trim().length > 0)
+                        continue;
+                    if (el.querySelector('img, svg, video, canvas, iframe, picture'))
+                        continue;
+                    const z = parseInt(cs.zIndex, 10);
+                    if (!(z >= 10))
+                        continue;
+                    const r = el.getBoundingClientRect();
+                    if (r.width < vw * 0.9 || r.height < vh * 0.9)
+                        continue;
+                    const tinted = !/rgba?\(\s*0,\s*0,\s*0,\s*0\s*\)|transparent/.test(cs.backgroundColor) || (cs.backdropFilter && cs.backdropFilter !== 'none');
+                    if (!tinted)
+                        continue;
+                    if (hide(el, 'overlay'))
+                        overlays += 1;
+                }
+            }
+        }
+    }
+    let scrollUnlocked = false;
+    if (arg.unlockScroll && bySelector + byHeuristic + overlays > 0) {
+        for (const el of [document.documentElement, document.body]) {
+            if (!el)
+                continue;
+            const cs = getComputedStyle(el);
+            if (cs.overflowY === 'hidden' || cs.overflow === 'hidden') {
+                el.style.setProperty('overflow', 'visible', 'important');
+                scrollUnlocked = true;
+            }
+            // Scroll locks that pin the body in place: position fixed with a negative top.
+            if (el === document.body && cs.position === 'fixed') {
+                el.style.setProperty('position', 'static', 'important');
+                el.style.setProperty('top', 'auto', 'important');
+                scrollUnlocked = true;
+            }
+        }
+    }
+    return { hidden: bySelector + byHeuristic + overlays, bySelector, byHeuristic, overlays, scrollUnlocked, details, timedOut: false };
+}
+/**
+ * Hides cookie and consent banners without clicking anything: known consent platforms by selector, plus
+ * fixed overlays that talk about cookies or consent and offer a choice. It never clicks "accept", so no
+ * consent is given and the page does not reload. Elements are hidden with CSS, not removed, so page scripts
+ * that reference them keep working.
+ */
+async function hideConsentBanners(page, options = {}) {
+    const timeoutMs = Math.max(0, options.timeout ?? 2000);
+    const selectors = [...(options.replaceBuiltIn ? [] : exports.CONSENT_SELECTORS), ...(options.selectors ?? [])];
+    const arg = { selectors, heuristics: options.heuristics ?? true, unlockScroll: options.unlockScroll ?? true, attr: exports.HIDDEN_ATTRIBUTE };
+    const result = await (0, page_js_1.withTimeout)((0, page_js_1.inPage)(page, consentInPage, arg), timeoutMs + page_js_1.GRACE_MS);
+    if (result.timedOut)
+        return { hidden: 0, bySelector: 0, byHeuristic: 0, overlays: 0, scrollUnlocked: false, details: [], timedOut: true };
+    return result.value;
+}
+function hideInPage(arg) {
+    const styleId = 'screenshot-ready-hide-style';
+    let style = document.getElementById(styleId);
+    if (!style) {
+        style = document.createElement('style');
+        style.id = styleId;
+        (document.head || document.documentElement).appendChild(style);
+    }
+    const rule = arg.mode === 'display' ? 'display:none!important' : 'visibility:hidden!important';
+    let matched = 0;
+    const rules = [];
+    for (const sel of arg.selectors) {
+        try {
+            matched += document.querySelectorAll(sel).length;
+            rules.push(`${sel}{${rule}}`);
+        }
+        catch {
+            // invalid selector: skip it
+        }
+    }
+    style.textContent = (style.textContent ? style.textContent + '\n' : '') + rules.join('\n');
+    return matched;
+}
+/**
+ * Hides elements you name (chat widgets, promo bars, ads) with a stylesheet rule, so they stay hidden if they
+ * are re-rendered. Returns how many elements matched at the time of the call.
+ */
+async function hideElements(page, selectors, options = {}) {
+    if (selectors.length === 0)
+        return 0;
+    const result = await (0, page_js_1.withTimeout)((0, page_js_1.inPage)(page, hideInPage, { selectors, mode: options.mode ?? 'visibility' }), 2000 + page_js_1.GRACE_MS);
+    return result.timedOut ? 0 : result.value;
+}

package/dist/cjs/fonts.d.ts

@@ -0,0 +1,20 @@
+import { type PageLike } from './page.js';
+export interface WaitForFontsOptions {
+    /** Give up after this many ms. Default 3000. */
+    timeout?: number;
+}
+export interface WaitForFontsResult {
+    /** True when fonts were still loading when the timeout hit. */
+    timedOut: boolean;
+    /** Font faces that finished loading. */
+    loaded: number;
+    /** Families still loading at the end. */
+    pending: string[];
+    /** Families that failed to load (the browser falls back to another font for these). */
+    failed: string[];
+}
+/**
+ * Waits until the page's web fonts have loaded (or failed), so text is not captured in a fallback font or
+ * invisible while a font with `font-display: block` downloads.
+ */
+export declare function waitForFonts(page: PageLike, options?: WaitForFontsOptions): Promise<WaitForFontsResult>;