@browserless/screenshot 13.6.8 → 13.6.9

package/README.md

@@ -69,7 +69,6 @@ const buffer = await browserless.screenshot('https://example.com', {
 | `element`     | `string`   | —                           | CSS selector for element screenshot                                           |
 | `codeScheme`  | `string`   | `'atom-dark'`               | Prism.js theme for code highlighting                                          |
 | `waitUntil`   | `string`   | `'auto'`                    | When to consider navigation done                                              |
-| `waitForDom`  | `number`   | `0`                         | DOM stability window in ms (idle is `waitForDom / 10`, `0` disables DOM wait) |
 | `isPageReady` | `function` | `({ isWhite }) => !isWhite` | Custom readiness predicate for retry loop                                     |
 | `overlay`     | `object`   | `{}`                        | Browser overlay options                                                       |
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@browserless/screenshot",
   "description": "Capture high-quality screenshots of websites with overlay support, device emulation, and automated image optimization.",
   "homepage": "https://browserless.js.org/#/?id=screenshoturl-options",
-  "version": "13.6.8",
+  "version": "13.6.9",
   "main": "src/index.js",
   "author": {
     "email": "hello@microlink.io",
@@ -33,7 +33,7 @@
   ],
   "dependencies": {
     "@browserless/errors": "13.6.7",
-    "@browserless/goto": "13.6.8",
+    "@browserless/goto": "13.6.9",
     "@kikobeats/content-type": "~1.0.4",
     "@kikobeats/time-span": "~1.0.12",
     "automad-prism-themes": "~0.3.7",
@@ -52,7 +52,7 @@
     "svg-gradient": "~1.0.4"
   },
   "devDependencies": {
-    "@browserless/test": "13.6.8",
+    "@browserless/test": "13.6.9",
     "ava": "5"
   },
   "engines": {
@@ -71,5 +71,5 @@
     "timeout": "2m",
     "workerThreads": false
   },
-  "gitHead": "1967ae39bd38666f20239ecc1befd484ed8349e9"
+  "gitHead": "c625834b3b37e036432a0756d67eccc149861ad0"
 }

package/src/index.js

@@ -9,16 +9,18 @@ const isWhiteScreenshot = require('./is-white-screenshot')
 const waitForPrism = require('./pretty')
 const prettyTimeSpan = require('./time-span')
 const overlay = require('./overlay')
-const { waitForDomStability, resolveWaitForDom, DEFAULT_WAIT_FOR_DOM } = require('./wait-for-dom')
-const { waitForReady } = require('./wait-for-ready')
+const { waitForDomStability } = require('./wait-for-dom')
+const { waitForReady, paintSignals } = require('./wait-for-ready')
+const {
+  expandOverflow,
+  scrollFullPageToLoadContent,
+  prepareFullDocument,
+  resolveScrollTimeout,
+  tryHydrateScroll
+} = require('./prepare-full-document')
 
 const timeSpan = require('@kikobeats/time-span')()
 
-// Retry a page capture (screenshot/pdf) that races with a client-side
-// navigation. When the execution context is destroyed mid-capture, the page is
-// navigating: wait for it to settle via `waitUntilAuto` and retry in-place,
-// bounded by `timeout`, rather than failing the whole request. SPAs (e.g.
-// scribd) navigate client-side after load, so the initial capture often races.
 const captureWithNavigationRetry = async (capture, { page, goto, timeout }) => {
   const elapsed = timeSpan()
   while (true) {
@@ -32,7 +34,7 @@ const captureWithNavigationRetry = async (capture, { page, goto, timeout }) => {
   }
 }
 
-const getPageSnapshot = page =>
+const getPageMeta = page =>
   page.evaluate(() => ({
     title: document.title || '',
     bodyText: document.body ? document.body.innerText || '' : '',
@@ -41,6 +43,18 @@ const getPageSnapshot = page =>
 
 const defaultIsPageReady = ({ isWhite }) => !isWhite
 
+const checkPageReady = async (page, { isPageReady, response, screenshot, isWhite } = {}) => {
+  let pageMeta = {}
+  if (isPageReady !== defaultIsPageReady) {
+    const pageMetaResult = await pReflect(getPageMeta(page))
+    pageMeta = pageMetaResult.isRejected ? {} : pageMetaResult.value
+  }
+  const pageReadyResult = await pReflect(
+    isPageReady({ page, response, screenshot, isWhite, isWhiteScreenshot, ...pageMeta })
+  )
+  return !pageReadyResult.isRejected && !!pageReadyResult.value
+}
+
 const getBoundingClientRect = element => {
   const { top, left, height, width, x, y } = element.getBoundingClientRect()
   return { top, left, height, width, x, y }
@@ -64,41 +78,6 @@ const waitForImagesOnViewport = page =>
     )
   )
 
-const scrollFullPageToLoadContent = async (page, timeout) => {
-  const debug = require('debug-logfmt')('browserless:goto')
-
-  const duration = debug.duration()
-  const result = await page.evaluate(waitForDomStability, {
-    idle: timeout / 2 / 2,
-    timeout: timeout / 2
-  })
-
-  duration('waitForDomStability', result)
-
-  await page.evaluate(
-    timeout =>
-      new Promise(resolve => {
-        let currentScrollPosition = 0
-        const scrollStep = Math.floor(window.innerHeight)
-        const pageHeight = document.body.scrollHeight
-        const totalSteps = Math.ceil(pageHeight / scrollStep)
-        const stepDelay = timeout / 2 / totalSteps
-        const scrollNext = async () => {
-          if (currentScrollPosition >= pageHeight) {
-            resolve()
-            return
-          }
-          window.scrollBy(0, scrollStep)
-          currentScrollPosition += scrollStep
-          setTimeout(scrollNext, stepDelay)
-        }
-        scrollNext()
-      }),
-    timeout
-  )
-  await page.evaluate(() => window.scrollTo(0, 0))
-}
-
 const waitForElement = async (page, element) => {
   const screenshotOpts = {}
   if (element) {
@@ -114,7 +93,6 @@ const SCREENSHOT_DEFAULT_OPTS = {
   codeScheme: 'atom-dark',
   overlay: {},
   waitUntil: 'auto',
-  waitForDom: DEFAULT_WAIT_FOR_DOM,
   isPageReady: defaultIsPageReady
 }
 
@@ -128,7 +106,6 @@ module.exports = ({ goto, ...gotoOpts }) => {
         codeScheme = SCREENSHOT_DEFAULT_OPTS.codeScheme,
         overlay: overlayOpts = SCREENSHOT_DEFAULT_OPTS.overlay,
         waitUntil = SCREENSHOT_DEFAULT_OPTS.waitUntil,
-        waitForDom = SCREENSHOT_DEFAULT_OPTS.waitForDom,
         isPageReady = SCREENSHOT_DEFAULT_OPTS.isPageReady,
         ...opts
       } = {}
@@ -136,9 +113,17 @@ module.exports = ({ goto, ...gotoOpts }) => {
       let screenshot
       let response
 
+      const captureExpanded = (expand, screenshotOpts, timeout) =>
+        captureWithNavigationRetry(
+          async () => {
+            if (expand) await pReflect(expandOverflow(page))
+            return page.screenshot(screenshotOpts)
+          },
+          { page, goto, timeout }
+        )
+
       const beforeScreenshot = async (page, response, { element, fullPage = false } = {}) => {
         const timeout = goto.timeouts.action(opts.timeout)
-        const waitForDomOpts = resolveWaitForDom(waitForDom)
 
         let screenshotOpts = {}
         const tasks = [
@@ -152,13 +137,6 @@ module.exports = ({ goto, ...gotoOpts }) => {
           }
         ]
 
-        if (waitForDomOpts) {
-          tasks.push({
-            fn: () => page.evaluate(waitForDomStability, waitForDomOpts),
-            debug: 'beforeScreenshot:waitForDomStability'
-          })
-        }
-
         if (codeScheme && response) {
           tasks.push({
             fn: () => waitForPrism(page, response, { codeScheme, ...opts }),
@@ -166,12 +144,7 @@ module.exports = ({ goto, ...gotoOpts }) => {
           })
         }
 
-        if (fullPage) {
-          tasks.push({
-            fn: () => scrollFullPageToLoadContent(page, timeout, goto),
-            debug: 'beforeScreenshot:scrollFullPageToLoadContent'
-          })
-        } else if (element) {
+        if (element && !fullPage) {
           tasks.push({
             fn: async () => {
               screenshotOpts = await waitForElement(page, element)
@@ -185,7 +158,7 @@ module.exports = ({ goto, ...gotoOpts }) => {
             goto.run({
               fn: fn(),
               ...opts,
-              timeout: fullPage ? timeout * 2 : timeout
+              timeout
             })
           )
         )
@@ -199,34 +172,56 @@ module.exports = ({ goto, ...gotoOpts }) => {
         let retry = 0
         let isWhite = false
         let isReady = false
+        let didHydrateScroll = false
+        let didHydrateAttempt = false
 
         do {
-          screenshot = await captureWithNavigationRetry(() => page.screenshot(opts), {
-            page,
-            goto,
-            timeout
-          })
-          isWhite = await isWhiteScreenshot(screenshot)
-          const snapshotResult = await pReflect(getPageSnapshot(page))
-          const pageSnapshot = snapshotResult.isRejected ? {} : snapshotResult.value
-          const pageReadyResult = await pReflect(
-            opts.isPageReady({
-              page,
-              response: opts.response,
-              screenshot,
-              isWhite,
-              isWhiteScreenshot,
-              ...pageSnapshot
-            })
+          screenshot = await captureWithNavigationRetry(
+            () =>
+              page.screenshot({
+                ...opts,
+                ...(opts.fullPage ? { fullPage: false, path: undefined } : {})
+              }),
+            { page, goto, timeout }
           )
-          isReady = !pageReadyResult.isRejected && !!pageReadyResult.value
+          isWhite = await isWhiteScreenshot(screenshot)
+          isReady = await checkPageReady(page, {
+            isPageReady: opts.isPageReady,
+            response: opts.response,
+            screenshot,
+            isWhite
+          })
 
           if (isReady || elapsed() >= timeout) break
 
+          const remaining = timeout - elapsed()
+          if (opts.fullPage && !didHydrateAttempt && !isWhite) {
+            didHydrateAttempt = true
+            const { hydrated, info } = await tryHydrateScroll(page, remaining)
+            didHydrateScroll = hydrated
+            debug('screenshot:hydrateScroll', { remaining, hydrated, ...info })
+          }
+
           retry += 1
           await goto.waitUntilAuto(page, { timeout })
         } while (!isReady)
 
+        if (opts.fullPage) {
+          if (isReady) {
+            await prepareFullDocument(page, {
+              goto,
+              timeout: opts.timeout,
+              scrolled: didHydrateScroll
+            })
+          }
+          screenshot = await captureExpanded(
+            isReady,
+            { ...opts, fullPage: true },
+            resolveScrollTimeout(goto, opts.timeout)
+          )
+          isWhite = await isWhiteScreenshot(screenshot)
+        }
+
         return { isWhite, isReady, retry }
       }
 
@@ -239,9 +234,13 @@ module.exports = ({ goto, ...gotoOpts }) => {
         if (waitUntil !== 'auto') {
           ;({ response } = await goto(page, { ...opts, url, waitUntil }))
           const screenshotOpts = await beforeScreenshot(page, response, opts)
-          screenshot = await captureWithNavigationRetry(
-            () => page.screenshot({ ...opts, ...screenshotOpts }),
-            { page, goto, timeout: goto.timeouts.action(opts.timeout) }
+          if (opts.fullPage) {
+            await prepareFullDocument(page, { goto, timeout: opts.timeout })
+          }
+          screenshot = await captureExpanded(
+            opts.fullPage,
+            { ...opts, ...screenshotOpts },
+            goto.timeouts.action(opts.timeout)
           )
           debug('screenshot', { waitUntil, duration: timeScreenshot() })
         } else {
@@ -277,6 +276,13 @@ module.exports = ({ goto, ...gotoOpts }) => {
 module.exports.captureWithNavigationRetry = captureWithNavigationRetry
 module.exports.isWhiteScreenshot = isWhiteScreenshot
 module.exports.waitForDomStability = waitForDomStability
-module.exports.resolveWaitForDom = resolveWaitForDom
 module.exports.waitForReady = waitForReady
+module.exports.paintSignals = paintSignals
+module.exports.scrollFullPageToLoadContent = scrollFullPageToLoadContent
+module.exports.expandOverflow = expandOverflow
+module.exports.getPageMeta = getPageMeta
+module.exports.checkPageReady = checkPageReady
+module.exports.tryHydrateScroll = tryHydrateScroll
+module.exports.resolveScrollTimeout = resolveScrollTimeout
+module.exports.prepareFullDocument = prepareFullDocument
 module.exports.SCREENSHOT_DEFAULT_OPTS = SCREENSHOT_DEFAULT_OPTS

package/src/prepare-full-document.js

@@ -0,0 +1,249 @@
+'use strict'
+
+const debug = require('debug-logfmt')('browserless:prepare')
+const pReflect = require('p-reflect')
+
+const { waitForDomStability } = require('./wait-for-dom')
+
+const SCROLL_STEP_MS = 50
+const OVERFLOW_MIN_PX = 200
+const OVERFLOW_WAIT_MS = 1500
+const PRE_QUIET_MS = 50
+const POST_QUIET_MS = 200
+const SETTLE_MS = 400
+
+// The single overflow scanner: the tallest whole-document element that scrolls
+// its own overflow past minPx. Runs in the page.
+function findTallestOverflowScroller (minPx) {
+  let best = null
+  for (const el of document.querySelectorAll('*')) {
+    const style = window.getComputedStyle(el)
+    if (style.overflowY !== 'auto' && style.overflowY !== 'scroll') continue
+    if (el.scrollHeight <= el.clientHeight + minPx) continue
+    if (!best || el.scrollHeight > best.scrollHeight) best = el
+  }
+  return best
+}
+
+// page.evaluate only serializes the function it is given, so an in-page helper
+// can't be shared across evaluates by reference. Compose the scanner source in
+// front of `fn` on the Node side (no in-page eval, so page CSP is untouched) to
+// give every caller the same scanner.
+const evaluateInPage = (page, fn, ...args) => {
+  const source = `${findTallestOverflowScroller}\nreturn (${fn}).apply(null, arguments)`
+  // eslint-disable-next-line no-new-func
+  return page.evaluate(new Function(source), ...args)
+}
+
+const waitForOverflowHeight = (page, timeout = OVERFLOW_WAIT_MS) =>
+  evaluateInPage(
+    page,
+    (timeout, minPx) =>
+      new Promise(resolve => {
+        const started = Date.now()
+        let last = 0
+        let stable = 0
+        const tick = () => {
+          const scroll = findTallestOverflowScroller(minPx)
+          const height = scroll
+            ? scroll.scrollHeight
+            : (document.scrollingElement || document.documentElement).scrollHeight
+          const tall = height > window.innerHeight + minPx
+          if (height === last && tall) {
+            if (++stable >= 2) return resolve(height)
+          } else {
+            stable = 0
+            last = height
+          }
+          if (Date.now() - started >= timeout) return resolve(height)
+          // Shell pages grow late — poll a bit slower until content appears.
+          setTimeout(tick, tall ? 100 : 150)
+        }
+        tick()
+      }),
+    timeout,
+    OVERFLOW_MIN_PX
+  )
+
+const expandOverflow = (page, minPx = OVERFLOW_MIN_PX) =>
+  evaluateInPage(
+    page,
+    minPx => {
+      const scroll = findTallestOverflowScroller(minPx)
+      if (!scroll) return false
+      let el = scroll
+      while (el) {
+        const pos = window.getComputedStyle(el).position
+        el.style.setProperty('overflow', 'visible', 'important')
+        el.style.setProperty('height', 'auto', 'important')
+        el.style.setProperty('max-height', 'none', 'important')
+        if (pos === 'absolute' || pos === 'fixed') {
+          el.style.setProperty('position', 'relative', 'important')
+          el.style.setProperty('inset', 'auto', 'important')
+        }
+        if (el === document.documentElement) break
+        el = el.parentElement
+      }
+      return true
+    },
+    minPx
+  )
+
+const settleDom = async (page, { idle, timeout }, label) => {
+  const started = Date.now()
+  const result = await page.evaluate(waitForDomStability, { idle, timeout })
+  debug(label, { ...result, duration: Date.now() - started })
+}
+
+const scrollFullPageToLoadContent = async (page, timeout) => {
+  const preQuiet = Math.min(PRE_QUIET_MS, Math.floor(timeout / 20))
+  const postQuiet = Math.min(POST_QUIET_MS, Math.floor(timeout / 20))
+  const scrollBudget = Math.max(0, timeout - preQuiet - postQuiet)
+  const started = Date.now()
+
+  if (preQuiet > 0) {
+    await settleDom(page, { idle: preQuiet / 2, timeout: preQuiet }, 'waitForDomStability:pre')
+  }
+
+  const scroll = await evaluateInPage(
+    page,
+    (scrollBudget, stepMs, minPx) =>
+      new Promise(resolve => {
+        const doc = () => document.scrollingElement || document.documentElement
+        let root = null
+        let pageHeight = doc() ? doc().scrollHeight : 0
+        let viewport = window.innerHeight
+        let currentScrollPosition = 0
+        const scrollStarted = Date.now()
+
+        const measure = () => {
+          if (!root) {
+            const overflow = findTallestOverflowScroller(minPx)
+            if (overflow) root = overflow
+          }
+          if (root) {
+            pageHeight = root.scrollHeight
+            viewport = root.clientHeight || window.innerHeight
+          } else {
+            const el = doc()
+            pageHeight = el ? el.scrollHeight : 0
+            viewport = window.innerHeight
+          }
+        }
+
+        const finish = () => {
+          window.scrollTo(0, 0)
+          if (root) root.scrollTop = 0
+          resolve({
+            hasOverflow: !!root,
+            pageHeight,
+            viewport,
+            scrolledPx: currentScrollPosition,
+            duration: Date.now() - scrollStarted
+          })
+        }
+
+        const scrollNext = () => {
+          measure()
+          const step = Math.max(1, Math.floor(viewport * 0.95))
+          if (currentScrollPosition >= pageHeight || Date.now() - scrollStarted >= scrollBudget) {
+            return finish()
+          }
+          if (root) root.scrollBy(0, step)
+          else window.scrollBy(0, step)
+          currentScrollPosition += step
+          setTimeout(scrollNext, stepMs)
+        }
+
+        measure()
+        // Viewport-sized shell with no overflow yet: brief wait for the SPA
+        // scroller before falling through to window scroll / budget exit.
+        if (pageHeight <= viewport + 1 && !root) {
+          const waitUntil = scrollStarted + Math.min(1000, Math.floor(scrollBudget / 4))
+          const waitForRoot = () => {
+            measure()
+            if (root || Date.now() >= waitUntil) return scrollNext()
+            setTimeout(waitForRoot, stepMs)
+          }
+          return waitForRoot()
+        }
+        scrollNext()
+      }),
+    scrollBudget,
+    SCROLL_STEP_MS,
+    OVERFLOW_MIN_PX
+  )
+  debug('scrollFullPage', { ...scroll, duration: Date.now() - started })
+
+  if (postQuiet > 0) {
+    await settleDom(
+      page,
+      { idle: Math.min(100, postQuiet / 2), timeout: postQuiet },
+      'waitForDomStability:post'
+    )
+  }
+
+  const hydrated = !!(scroll?.hasOverflow && scroll.scrolledPx >= (scroll.viewport || 0))
+  return { ...scroll, hydrated, duration: Date.now() - started }
+}
+
+const resolveScrollTimeout = (goto, timeout) =>
+  typeof goto.timeouts.goto === 'function'
+    ? goto.timeouts.goto(timeout)
+    : goto.timeouts.action(timeout)
+
+// A hydrate scroll spends up to half the remaining budget (capped) scrolling,
+// and the capture that follows still needs time. Below HYDRATE_MIN_BUDGET_MS
+// there isn't enough left for both, so skip it.
+const HYDRATE_MIN_BUDGET_MS = 1000
+const HYDRATE_MAX_SCROLL_MS = 5000
+
+const tryHydrateScroll = async (page, remaining) => {
+  if (remaining <= HYDRATE_MIN_BUDGET_MS) return { hydrated: false, info: {} }
+  const hydrate = await pReflect(
+    scrollFullPageToLoadContent(page, Math.min(remaining / 2, HYDRATE_MAX_SCROLL_MS))
+  )
+  return {
+    hydrated: !hydrate.isRejected && !!hydrate.value?.hydrated,
+    info: hydrate.isRejected ? {} : hydrate.value
+  }
+}
+
+const prepareFullDocument = async (page, { goto, timeout, scrolled = false } = {}) => {
+  const scrollTimeout = resolveScrollTimeout(goto, timeout)
+  const elapsed = require('@kikobeats/time-span')({ format: n => Math.round(n) })()
+
+  if (!scrolled) {
+    const height = await pReflect(
+      waitForOverflowHeight(page, Math.min(OVERFLOW_WAIT_MS, Math.round(scrollTimeout / 8)))
+    )
+    debug('prepareFullDocument:overflowHeight', {
+      height: height.isRejected ? null : height.value,
+      duration: elapsed()
+    })
+
+    await scrollFullPageToLoadContent(page, scrollTimeout)
+    debug('prepareFullDocument:scroll', { duration: elapsed() })
+  } else {
+    debug('prepareFullDocument:skipScroll', { duration: elapsed() })
+  }
+
+  const settleMs = Math.min(SETTLE_MS, Math.max(0, scrollTimeout - elapsed()))
+  if (settleMs > 0 && typeof page.waitForNetworkIdle === 'function') {
+    await pReflect(page.waitForNetworkIdle({ idleTime: 200, concurrency: 2, timeout: settleMs }))
+  }
+
+  const expandResult = await pReflect(expandOverflow(page))
+  const expanded = !expandResult.isRejected && expandResult.value
+  debug('prepareFullDocument:expandOverflow', { expanded, duration: elapsed() })
+
+  return { expanded, duration: elapsed(), scrolled }
+}
+
+module.exports = {
+  expandOverflow,
+  scrollFullPageToLoadContent,
+  prepareFullDocument,
+  resolveScrollTimeout,
+  tryHydrateScroll
+}

package/src/wait-for-dom.js

@@ -1,19 +1,5 @@
 'use strict'
 
-const DEFAULT_WAIT_FOR_DOM = 0
-const WAIT_FOR_DOM_IDLE_RATIO = 10
-
-const resolveWaitForDom = waitForDom => {
-  const timeout = Number.isFinite(waitForDom) && waitForDom >= 0 ? waitForDom : DEFAULT_WAIT_FOR_DOM
-
-  if (timeout === 0) return undefined
-
-  return {
-    timeout,
-    idle: timeout / WAIT_FOR_DOM_IDLE_RATIO
-  }
-}
-
 const waitForDomStability = ({ idle, timeout } = {}) =>
   new Promise(resolve => {
     if (!document.body) return resolve({ status: 'no-body' })
@@ -45,9 +31,4 @@ const waitForDomStability = ({ idle, timeout } = {}) =>
     })()
   })
 
-module.exports = {
-  DEFAULT_WAIT_FOR_DOM,
-  WAIT_FOR_DOM_IDLE_RATIO,
-  resolveWaitForDom,
-  waitForDomStability
-}
+module.exports = { waitForDomStability }

package/src/wait-for-ready.js

@@ -1,47 +1,21 @@
 'use strict'
 
-// Navigation-tolerant readiness gate. Resolves once the page has been visually
-// quiet — document height stable, every image decoded, `readyState` complete —
-// for `quietMs`, bounded by `timeout`. Unlike a screenshot poll it takes no
-// screenshots (which are expensive under software rendering, e.g. the GPU-less
-// fleet's llvmpipe) and it survives a client-side navigation: when the
-// execution context is destroyed mid-check the quiet window resets and polling
-// continues instead of throwing (SPAs re-commit their own URL after load).
-
 const { setTimeout: sleep } = require('node:timers/promises')
 const { isContextDestroyed } = require('@browserless/errors')
 
-// Evaluated in-page: a cheap snapshot of the paint/settle signals. `images`
-// counts only images expected to settle: a lazy image well below the viewport
-// sits outside Chromium's lazy-load fetch threshold and never starts loading
-// without a scroll, so counting it could only stall the gate into its timeout.
-// `decoded` counts every counted image that finished loading — a broken `<img>`
-// counts too, so it can't stall the settle gate — while `painted` counts only
-// images a screenshot would actually see: successfully decoded, rendered at a
-// visible size (a 16×16 box or larger, so a tracking pixel doesn't count),
-// inside the viewport, and not hidden via CSS — so a blank shell can't pass for
-// content. `text` is the equivalent paint signal for imageless pages: visible
-// characters inside the viewport, counted up to 200 (the threshold consumers
-// rely on) and skipping text whose color matches its effective background
-// (invisible on capture), and `fonts` reports whether webfonts finished
-// loading — during a `font-display: block` period text renders invisible,
-// exactly when a capture would be white. `covered` reports whether the counted
-// content hides behind an opaque viewport-covering layer (a fixed white
-// loading overlay passes every DOM signal while a capture stays white):
-// hit-testing catches interactive overlays, and a root-level scan catches
-// `pointer-events: none` layers hit-testing can't see. `viewport` is the
-// in-page viewport height, so consumers can compare it against `height`
-// without relying on `page.viewport()`, which is null under
-// `defaultViewport: null`.
-const snapshot = () => {
-  // A document that is mid-parse or detached can have a null `documentElement`
-  // (the same state the text walk below guards against), so every dereference
-  // of it in this snapshot goes through `root`.
+const DEFAULT_QUIET_MS = 300
+const DEFAULT_POLL_MS = 150
+
+const paintSignals = () => {
+  const TEXT_PAINT_CAP = 200
+  const MIN_PAINTED_AREA_PX = 256
+  const LAZY_IMAGE_VIEWPORTS = 2
+  const CONTENT_SAMPLE_LIMIT = 4
+
   const root = document.documentElement
   const vw = window.innerWidth || (root ? root.clientWidth : 0)
   const vh = window.innerHeight || (root ? root.clientHeight : 0)
 
-  // Computed colors resolve to `rgb()`/`rgba()`; anything else is unknown.
   const parseColor = value => {
     const match = /rgba?\(([^)]+)\)/.exec(value || '')
     if (!match) return null
@@ -49,8 +23,6 @@ const snapshot = () => {
     return { r: parts[0], g: parts[1], b: parts[2], a: parts.length === 4 ? parts[3] : 1 }
   }
 
-  // First opaque background up the ancestor chain; the canvas default (white)
-  // when every ancestor is transparent.
   const effectiveBackground = el => {
     for (let node = el; node; node = node.parentElement) {
       const color = parseColor(window.getComputedStyle(node).backgroundColor)
@@ -62,8 +34,6 @@ const snapshot = () => {
   const sameColor = (a, b) =>
     Math.abs(a.r - b.r) < 10 && Math.abs(a.g - b.g) < 10 && Math.abs(a.b - b.b) < 10
 
-  // A layer only blanks a capture when it is itself painted solid: visible,
-  // full opacity, and an opaque background color or a background image.
   const isOpaqueLayer = el => {
     const style = window.getComputedStyle(el)
     if (style.visibility === 'hidden' || parseFloat(style.opacity) < 0.99) return false
@@ -78,13 +48,9 @@ const snapshot = () => {
     return width > 0 && height > 0 && width * height >= vw * vh * 0.9
   }
 
-  // Up to a handful of counted content samples — enough to hit-test without
-  // turning the snapshot into a layout storm. The clamp keeps each probe point
-  // inside the viewport; the rect checks below guarantee it stays inside the
-  // sampled content's own box.
   const contentPoints = []
   const samplePoint = (el, rect) => {
-    if (contentPoints.length >= 4) return
+    if (contentPoints.length >= CONTENT_SAMPLE_LIMIT) return
     contentPoints.push({
       el,
       x: Math.max(0, Math.min(vw - 1, rect.left + rect.width / 2)),
@@ -99,11 +65,9 @@ const snapshot = () => {
   for (let i = 0; i < imgs.length; i++) {
     const img = imgs[i]
     if (!img.complete) {
-      // Two viewports of headroom stays inside the smallest fetch threshold
-      // Chromium uses for lazy images (~1250px on fast connections), so an
-      // undecoded lazy image within it is loading and worth waiting for;
-      // beyond it, the fetch never starts.
-      if (img.loading === 'lazy' && img.getBoundingClientRect().top > vh * 2) continue
+      if (img.loading === 'lazy' && img.getBoundingClientRect().top > vh * LAZY_IMAGE_VIEWPORTS) {
+        continue
+      }
       images++
       continue
     }
@@ -111,7 +75,7 @@ const snapshot = () => {
     decoded++
     if (img.naturalWidth === 0) continue
     const rect = img.getBoundingClientRect()
-    if (rect.width * rect.height < 256) continue
+    if (rect.width * rect.height < MIN_PAINTED_AREA_PX) continue
     if (rect.bottom <= 0 || rect.right <= 0 || rect.top >= vh || rect.left >= vw) continue
     if (
       typeof img.checkVisibility === 'function' &&
@@ -122,21 +86,14 @@ const snapshot = () => {
     painted++
     samplePoint(img, rect)
   }
-  // Counting stops at 200 chars, so a text-heavy page costs a handful of nodes,
-  // not a full DOM walk; only a near-blank shell walks every text node.
+
   let text = 0
-  // A document that is mid-parse or detached can have neither `body` nor
-  // `documentElement`, and `createTreeWalker` throws on a null root. Text is only
-  // a paint signal, so a count that cannot be taken means "no text seen yet": the
-  // gate stays conservative and re-polls, rather than failing a render that would
-  // otherwise succeed. The same holds mid-walk — a DOM mutating under the walker
-  // must not take the capture down with it.
   const textRoot = document.body || root
   const walker = textRoot
     ? document.createTreeWalker(textRoot, window.NodeFilter.SHOW_TEXT)
     : { nextNode: () => null }
   try {
-    while (text < 200) {
+    while (text < TEXT_PAINT_CAP) {
       const node = walker.nextNode()
       if (!node) break
       const value = node.nodeValue.trim()
@@ -156,22 +113,13 @@ const snapshot = () => {
       const rect = range.getBoundingClientRect()
       if (rect.width === 0 || rect.height === 0) continue
       if (rect.bottom <= 0 || rect.right <= 0 || rect.top >= vh || rect.left >= vw) continue
-      // White-on-white (or any color-on-same-color) text passes every geometry
-      // check while a capture shows nothing: don't count it as painted text.
       const color = parseColor(window.getComputedStyle(el).color)
       if (color && (color.a < 0.05 || sameColor(color, effectiveBackground(el)))) continue
       text += value.length
       samplePoint(el, rect)
     }
-  } catch {
-    // Keep whatever was counted before the DOM shifted underneath the walk.
-  }
+  } catch {}
 
-  // Is this content sample's paint hidden behind an unrelated opaque,
-  // viewport-covering layer? Walk up from the hit-tested element: anything
-  // related to the sample (itself, an ancestor, a descendant) paints with it,
-  // and the walk stops at the first common ancestor — an ancestor's background
-  // always paints below its own descendants.
   const coveredAt = ({ el, x, y }) => {
     const top = document.elementFromPoint(x, y)
     if (!top) return false
@@ -182,14 +130,9 @@ const snapshot = () => {
     return false
   }
 
-  // Only pages the fast path could trust get the (layout-forcing) cover check.
   let covered = false
-  if (painted > 0 || text >= 200) {
+  if (painted > 0 || text >= TEXT_PAINT_CAP) {
     covered = contentPoints.some(coveredAt)
-    // `elementFromPoint` skips `pointer-events: none` elements, exactly how
-    // fading loading overlays are styled — scan root-level layers for one.
-    // Overlays mount as direct children of <body>; a deeper scan would cost a
-    // full styled DOM walk on every poll for a marginal case.
     if (!covered && document.body) {
       const layers = document.body.children
       for (let i = 0; i < layers.length && !covered; i++) {
@@ -222,20 +165,13 @@ const snapshot = () => {
   }
 }
 
-// 300ms of held quiet plus one 150ms poll to prove height stability puts the
-// gate's floor at ~450ms. The hold guards against lulls (a page momentarily
-// stable between async chunks); height stability + all images decoded +
-// `readyState === 'complete'` carry most of the settle signal, so a longer
-// hold buys little — below ~300ms it would start trusting coincidences.
-const waitForReady = async (page, { timeout, quietMs = 300, poll = 150 } = {}) => {
+const waitForReady = async (
+  page,
+  { timeout, quietMs = DEFAULT_QUIET_MS, poll = DEFAULT_POLL_MS } = {}
+) => {
   if (!Number.isFinite(timeout)) throw new TypeError('timeout must be a finite number')
-  // The quiet window must fit within the budget with room to observe it, or the
-  // gate could never satisfy its own requirement and would always time out.
   quietMs = Math.min(quietMs, Math.floor(timeout / 2))
   const deadline = Date.now() + timeout
-  // Never sleep past the deadline: with a poll larger than the remaining
-  // budget, a full-length sleep would overshoot the timeout and steal time
-  // from whatever shares the caller's budget (the blank-SPA screenshot poll).
   const nextPoll = () => sleep(Math.min(poll, Math.max(0, deadline - Date.now())))
   let lastHeight = -1
   let quietSince = 0
@@ -253,14 +189,10 @@ const waitForReady = async (page, { timeout, quietMs = 300, poll = 150 } = {}) =
   }
 
   while (Date.now() < deadline) {
-    let snap
+    let signals
     try {
-      snap = await page.evaluate(snapshot)
+      signals = await page.evaluate(paintSignals)
     } catch (error) {
-      // Only a client-side navigation tearing down the execution context is
-      // absorbed: reset the quiet window and keep polling. Any other evaluate
-      // failure is a real error and surfaces instead of masquerading as a
-      // timeout.
       if (!isContextDestroyed(error)) throw error
       resets++
       lastHeight = -1
@@ -269,16 +201,16 @@ const waitForReady = async (page, { timeout, quietMs = 300, poll = 150 } = {}) =
       continue
     }
 
-    last = snap
-    const imagesDecoded = snap.images === 0 || snap.decoded >= snap.images
-    const quiet = snap.complete && imagesDecoded && snap.height === lastHeight
+    last = signals
+    const imagesDecoded = signals.images === 0 || signals.decoded >= signals.images
+    const quiet = signals.complete && imagesDecoded && signals.height === lastHeight
 
     if (quiet) {
       if (quietSince === 0) quietSince = Date.now()
-      if (Date.now() - quietSince >= quietMs) return { ...snap, resets, timedOut: false }
+      if (Date.now() - quietSince >= quietMs) return { ...signals, resets, timedOut: false }
     } else {
       quietSince = 0
-      lastHeight = snap.height
+      lastHeight = signals.height
     }
 
     await nextPoll()
@@ -287,4 +219,4 @@ const waitForReady = async (page, { timeout, quietMs = 300, poll = 150 } = {}) =
   return { ...last, resets, timedOut: true }
 }
 
-module.exports = { waitForReady }
+module.exports = { waitForReady, paintSignals }