@browserless/pdf 13.6.1 → 13.6.3

package/package.json

@@ -2,7 +2,7 @@
   "name": "@browserless/pdf",
   "description": "Convert websites to high-quality PDFs with customizable margins, background printing, and optimized scaling.",
   "homepage": "https://browserless.js.org/#/?id=pdfurl-options",
-  "version": "13.6.1",
+  "version": "13.6.3",
   "main": "src",
   "author": {
     "email": "hello@microlink.io",
@@ -30,8 +30,8 @@
     "website-to-pdf"
   ],
   "dependencies": {
-    "@browserless/goto": "13.6.1",
-    "@browserless/screenshot": "13.6.1",
+    "@browserless/goto": "13.6.3",
+    "@browserless/screenshot": "13.6.3",
     "@kikobeats/time-span": "~1.0.12",
     "debug-logfmt": "~1.4.10",
     "p-reflect": "~2.1.0",
@@ -47,5 +47,5 @@
     "test": "exit 0"
   },
   "license": "MIT",
-  "gitHead": "b3d84200cc13b038b1b255e0895e20e6a0683fd6"
+  "gitHead": "7bc1c12120186d999a5ddedbcad4e3b5b52fb8fb"
 }

package/src/index.js

@@ -1,16 +1,36 @@
 'use strict'
 
 const timeSpan = require('@kikobeats/time-span')({ format: n => Math.round(n) })
+const debug = require('debug-logfmt')('browserless:pdf')
+const createGoto = require('@browserless/goto')
 const pReflect = require('p-reflect')
+
 const {
   captureWithNavigationRetry,
   isWhiteScreenshot,
   waitForDomStability,
+  waitForReady,
   resolveWaitForDom,
-  DEFAULT_WAIT_FOR_DOM
+  SCREENSHOT_DEFAULT_OPTS
 } = require('@browserless/screenshot')
-const debug = require('debug-logfmt')('browserless:pdf')
-const createGoto = require('@browserless/goto')
+
+const PDF_DEFAULT_OPTS = {
+  waitForDom: SCREENSHOT_DEFAULT_OPTS.waitForDom,
+  margin: '0.35cm',
+  scale: 0.65,
+  printBackground: true,
+  waitUntil: 'auto'
+}
+
+// Share of the action budget the readiness gate may consume in `auto` mode. The
+// remainder is reserved for the blank-SPA screenshot poll to re-wait, so the
+// gate can't starve the fallback while total prepare stays within one `timeout`.
+const READY_BUDGET_RATIO = 0.5
+
+// Minimum visible characters for the text fast path. Matches the counting cap
+// in `waitForReady`'s snapshot, which stops walking text nodes once reached —
+// raising this above the cap would make the text fast path unreachable.
+const TEXT_PAINTED_MIN = 200
 
 const getMargin = unit => {
   if (!unit) return unit
@@ -26,83 +46,128 @@ const getMargin = unit => {
 module.exports = ({ goto, ...gotoOpts } = {}) => {
   goto = goto || createGoto(gotoOpts)
 
-  return function pdf (page) {
-    return async (
-      url,
-      {
-        margin = '0.35cm',
-        scale = 0.65,
-        printBackground = true,
-        waitUntil = 'auto',
-        waitForDom = DEFAULT_WAIT_FOR_DOM,
-        ...opts
-      } = {}
-    ) => {
-      let pdfBuffer
-      const waitForDomOpts = resolveWaitForDom(waitForDom)
-
-      const generatePdf = page =>
-        captureWithNavigationRetry(
+  // Render an already-prepared page to a PDF buffer. Split out from the load so
+  // a single load can be reused across page-range chunks (microlink-api's
+  // parallel renderer) without re-navigating.
+  const render = (page, opts = {}) => {
+    const {
+      margin = PDF_DEFAULT_OPTS.margin,
+      scale = PDF_DEFAULT_OPTS.scale,
+      printBackground = PDF_DEFAULT_OPTS.printBackground,
+      waitUntil,
+      waitForDom,
+      ...rest
+    } = opts
+    return captureWithNavigationRetry(
+      () => page.pdf({ ...rest, margin: getMargin(margin), printBackground, scale }),
+      { page, goto, timeout: goto.timeouts.action(rest.timeout) }
+    )
+  }
+
+  // Navigate `page` to `url` and wait until it is ready to print: DOM stability
+  // plus, in `auto` mode, a navigation-tolerant readiness gate. Only a page that
+  // settles still-blank falls back to the (expensive, navigation-fragile)
+  // screenshot poll.
+  const prepare = async (page, url, opts = {}) => {
+    const {
+      margin,
+      scale,
+      printBackground,
+      waitUntil = PDF_DEFAULT_OPTS.waitUntil,
+      waitForDom = PDF_DEFAULT_OPTS.waitForDom,
+      ...rest
+    } = opts
+    const waitForDomOpts = resolveWaitForDom(waitForDom)
+
+    const waitForDomStabilityResult = async page => {
+      if (!waitForDomOpts) return
+
+      const result = await pReflect(page.evaluate(waitForDomStability, waitForDomOpts))
+      debug(
+        'waitForDomStability',
+        result.isRejected
+          ? { ...waitForDomOpts, error: result.reason.message || result.reason }
+          : { ...waitForDomOpts, ...result.value }
+      )
+    }
+
+    if (waitUntil !== 'auto') {
+      await goto(page, { ...rest, url, waitUntil })
+      await waitForDomStabilityResult(page)
+      return
+    }
+
+    await goto(page, { ...rest, url, waitUntil, waitUntilAuto })
+    async function waitUntilAuto (page) {
+      await waitForDomStabilityResult(page)
+      const timeout = goto.timeouts.action(rest.timeout)
+      // One action budget shared by the readiness gate and the screenshot poll,
+      // so worst-case prepare stays within a single `timeout` instead of one
+      // per stage.
+      const elapsed = timeSpan()
+
+      // Cheap, navigation-tolerant readiness — no screenshots. Resolves once the
+      // page is visually quiet (height stable, images decoded, load complete),
+      // absorbing the client-side re-navigation that makes a screenshot poll
+      // throw `Execution context was destroyed`. Capped at a share of the budget
+      // so a slow gate still leaves the blank-SPA poll room to re-wait.
+      const ready = await waitForReady(page, { timeout: Math.round(timeout * READY_BUDGET_RATIO) })
+      debug('ready', { ...ready, duration: elapsed() })
+
+      // Fast path: the page settled with real painted content in a document
+      // taller than the viewport — a visibly rendered image (not a tracking
+      // pixel), or enough visible text with webfonts loaded (a pending
+      // `font-display: block` font renders text invisible, exactly when a
+      // capture would be white) — so it can't be a blank shell: skip the
+      // screenshot poll. Height and viewport come from the same in-page
+      // snapshot (`page.viewport()` is null under `defaultViewport: null`),
+      // and an unknown viewport skips the fast path rather than dropping the
+      // taller-than-viewport guard. A gate that timed out never settled, so
+      // don't trust its partial snapshot: fall through to the blank check.
+      const painted = ready.painted > 0 || (ready.text >= TEXT_PAINTED_MIN && ready.fonts)
+      if (!ready.timedOut && painted && ready.viewport > 0 && ready.height > ready.viewport) return
+
+      // Otherwise fall back to the screenshot poll — re-wait while the first
+      // paint is still blank — to keep the blank-SPA protection. The page has
+      // already settled, so the first capture won't race a navigation, and a
+      // non-blank page exits after that single shot without an extra re-wait.
+      let isWhite = false
+      let retry = -1
+      do {
+        ++retry
+        const screenshotTime = timeSpan()
+        const screenshot = await captureWithNavigationRetry(
           () =>
-            page.pdf({
-              ...opts,
-              margin: getMargin(margin),
-              printBackground,
-              scale
+            page.screenshot({
+              ...rest,
+              optimizeForSpeed: true,
+              type: 'jpeg',
+              quality: 30
             }),
-          { page, goto, timeout: goto.timeouts.action(opts.timeout) }
+          // The retry loop keeps its own clock, so hand it only what is left
+          // of the shared budget — a fresh full `timeout` here would let one
+          // navigation-racing capture double the worst-case prepare time.
+          { page, goto, timeout: Math.max(0, timeout - elapsed()) }
         )
+        isWhite = await isWhiteScreenshot(screenshot)
+        if (isWhite) await goto.waitUntilAuto(page, { timeout: rest.timeout })
+        debug('retry', { waitUntil, isWhite, retry, duration: screenshotTime() })
+      } while (isWhite && elapsed() < timeout)
 
-      const waitForDomStabilityResult = async page => {
-        if (!waitForDomOpts) return
-
-        const result = await pReflect(page.evaluate(waitForDomStability, waitForDomOpts))
-        debug(
-          'waitForDomStability',
-          result.isRejected
-            ? { ...waitForDomOpts, error: result.reason.message || result.reason }
-            : { ...waitForDomOpts, ...result.value }
-        )
-      }
+      debug({ waitUntil, isWhite, timeout, duration: require('pretty-ms')(elapsed()) })
+    }
+  }
 
-      if (waitUntil !== 'auto') {
-        await goto(page, { ...opts, url, waitUntil })
-        await waitForDomStabilityResult(page)
-        pdfBuffer = await generatePdf(page)
-      } else {
-        await goto(page, { ...opts, url, waitUntil, waitUntilAuto })
-        async function waitUntilAuto (page) {
-          await waitForDomStabilityResult(page)
-          const timeout = goto.timeouts.action(opts.timeout)
-          let isWhite = false
-          let retry = -1
-
-          const timePdf = timeSpan()
-
-          do {
-            ++retry
-            const screenshotTime = timeSpan()
-            const screenshot = await captureWithNavigationRetry(
-              () =>
-                page.screenshot({
-                  ...opts,
-                  optimizeForSpeed: true,
-                  type: 'jpeg',
-                  quality: 30
-                }),
-              { page, goto, timeout }
-            )
-            isWhite = await isWhiteScreenshot(screenshot)
-            if (isWhite) await goto.waitUntilAuto(page, { timeout: opts.timeout })
-            debug('retry', { waitUntil, isWhite, retry, duration: screenshotTime() })
-          } while (isWhite && timePdf() < timeout)
-
-          debug({ waitUntil, isWhite, timeout, duration: require('pretty-ms')(timePdf()) })
-        }
-        pdfBuffer = await generatePdf(page)
+  const pdf =
+    page =>
+      async (url, opts = {}) => {
+        await prepare(page, url, opts)
+        return render(page, opts)
       }
 
-      return pdfBuffer
-    }
-  }
+  pdf.prepare = prepare
+  pdf.render = render
+  return pdf
 }
+
+module.exports.DEFAULT_OPTS = PDF_DEFAULT_OPTS