@d-zero/puppeteer-scroll 3.1.18 → 4.0.1

package/README.md

@@ -1,23 +1,25 @@
 # `@d-zero/puppeteer-scroll`
 
-Puppeteerでスクロールするための関数を提供します。
+`IntersectionObserver` や `loading="lazy"` を完了させるため、ページを上から下までスクロールするユーティリティ。スクロールジャック検出付き。
 
-`IntersectionObserver`や`loading="lazy"`などの機能を使っているサイトに対して表示や読み込みを完了させるために、スクロールを行います。
-
-## インストール
+## Installation
 
 ```sh
-yarn install @d-zero/puppeteer-scroll
+yarn add @d-zero/puppeteer-scroll
 ```
 
-## 使い方
+## Usage
 
 ```ts
 import { scrollAllOver } from '@d-zero/puppeteer-scroll';
 
-const browser = await puppeteer.launch();
-const page = await browser.newPage();
-await page.goto('https://example.com');
-
 await scrollAllOver(page);
 ```
+
+デフォルトは人間らしい揺らぎを付けたランダム挙動。テスト・レコーディング・VRT など**決定論的な挙動が必要な場合は `interval` と `distance` を明示指定**する:
+
+```ts
+await scrollAllOver(page, { interval: 300, distance: 800 });
+```
+
+オプション・デフォルト値・スクロールジャック検出ロジック・`distance ≤ 0` の丸めについては `src/scroll-all-over.ts` の JSDoc を参照。

package/dist/resolve-value.d.ts

@@ -0,0 +1,11 @@
+import type { DelayOptions } from '@d-zero/shared/delay';
+/**
+ * Synchronously resolves a `number | DelayOptions` to a concrete number.
+ *
+ * Why: `delay()` resolves the same shape but actually waits. For values
+ * that need to be passed into a browser `evaluate` call (e.g. scroll step
+ * distance), we need the sampled number without any time elapsing.
+ * @param value - The value to resolve.
+ * @returns A concrete number.
+ */
+export declare function resolveValue(value: number | DelayOptions): number;

package/dist/resolve-value.js

@@ -0,0 +1,20 @@
+import { sampleDistribution } from '@d-zero/shared/sample-distribution';
+/**
+ * Synchronously resolves a `number | DelayOptions` to a concrete number.
+ *
+ * Why: `delay()` resolves the same shape but actually waits. For values
+ * that need to be passed into a browser `evaluate` call (e.g. scroll step
+ * distance), we need the sampled number without any time elapsing.
+ * @param value - The value to resolve.
+ * @returns A concrete number.
+ */
+export function resolveValue(value) {
+    if (typeof value === 'number') {
+        return value;
+    }
+    const random = value.random;
+    if (typeof random === 'number') {
+        return sampleDistribution(random);
+    }
+    return sampleDistribution({ min: random.min, max: random.max }, random.distribution);
+}

package/dist/scroll-all-over.d.ts

@@ -1,7 +1,7 @@
 import type { Page } from 'puppeteer';
 import { type DelayOptions } from '@d-zero/shared/delay';
 export type Options = {
-    distance?: number;
+    distance?: number | DelayOptions;
     interval?: number | DelayOptions;
     logger?: (scrollY: number, scrollHeight: number, message: string) => void;
 };
@@ -14,8 +14,12 @@ export type Options = {
  * progress.
  * @param page - The Puppeteer page object.
  * @param options - Optional parameters for scrolling.
- * @param options.distance - The distance to scroll on each iteration (default: 100).
- * @param options.interval - The interval between each scroll iteration in milliseconds (default: 300).
+ * @param options.distance - The distance to scroll on each iteration in pixels.
+ *   Accepts a fixed number or a random range via `{ random: ... }`. When omitted,
+ *   each step uses `clientHeight × random(0.5, 1.0)` so it adapts to the viewport.
+ * @param options.interval - The interval between each scroll iteration in
+ *   milliseconds. Accepts a fixed number or a random range via `{ random: ... }`.
+ *   When omitted, defaults to a random range of 200–500 ms.
  * @param options.logger - A function that logs messages.
  */
 export declare function scrollAllOver(page: Page, options?: Options): Promise<void>;

package/dist/scroll-all-over.js

@@ -1,13 +1,27 @@
 import { delay } from '@d-zero/shared/delay';
+import { resolveValue } from './resolve-value.js';
 /**
  * Number of consecutive iterations without scroll progress before bailing out.
  *
  * Scroll-jacking libraries (e.g. fullpage.js) can block `scrollBy` while
  * `body.scrollHeight` remains larger than the viewport, causing an infinite
- * loop. Three stuck iterations (≈ 900 ms at the default interval) is enough
- * to confirm that scrolling is genuinely blocked.
+ * loop. Three stuck iterations (≈ 1.05 s at the default interval mean) is
+ * enough to confirm that scrolling is genuinely blocked.
  */
 const MAX_STUCK_ITERATIONS = 3;
+/**
+ * Default interval range (ms) used when `options.interval` is omitted.
+ * Randomized to mimic human-like reading pauses while staying close to the
+ * historical 300 ms fixed default.
+ */
+const DEFAULT_INTERVAL = { random: { min: 200, max: 500 } };
+/**
+ * Default scroll-step ratio range applied to `clientHeight` when
+ * `options.distance` is omitted. Sampled in the browser context per iteration
+ * so it adapts to the current viewport height.
+ */
+const DEFAULT_DISTANCE_RATIO_MIN = 0.5;
+const DEFAULT_DISTANCE_RATIO_MAX = 1;
 /**
  * Scrolls the page vertically until the end or a maximum height is reached.
  *
@@ -17,26 +31,37 @@ const MAX_STUCK_ITERATIONS = 3;
  * progress.
  * @param page - The Puppeteer page object.
  * @param options - Optional parameters for scrolling.
- * @param options.distance - The distance to scroll on each iteration (default: 100).
- * @param options.interval - The interval between each scroll iteration in milliseconds (default: 300).
+ * @param options.distance - The distance to scroll on each iteration in pixels.
+ *   Accepts a fixed number or a random range via `{ random: ... }`. When omitted,
+ *   each step uses `clientHeight × random(0.5, 1.0)` so it adapts to the viewport.
+ * @param options.interval - The interval between each scroll iteration in
+ *   milliseconds. Accepts a fixed number or a random range via `{ random: ... }`.
+ *   When omitted, defaults to a random range of 200–500 ms.
  * @param options.logger - A function that logs messages.
  */
 export async function scrollAllOver(page, options) {
-    const interval = options?.interval ?? 300;
+    const interval = options?.interval ?? DEFAULT_INTERVAL;
+    const distance = options?.distance;
     let currentScrollY = 0;
     let scrollHeight = await page.evaluate(() => document.body.scrollHeight);
     let prevScrollY = -1;
     let stuckCount = 0;
     while (Math.ceil(currentScrollY) < Math.ceil(scrollHeight)) {
-        [currentScrollY, scrollHeight] = await page.evaluate(() => {
-            // Move the scroll position to the bottom of the page.
-            globalThis.scrollBy(0, document.documentElement.clientHeight);
-            // Return the current scroll position.
+        // Force a minimum of 1 px so a user-supplied 0/negative distance
+        // cannot stall the loop into the stuck-detection bail out.
+        const stepDistance = distance === undefined ? null : Math.max(1, resolveValue(distance));
+        [currentScrollY, scrollHeight] = await page.evaluate((step, ratioMin, ratioMax) => {
+            // When step is null, sample a random fraction of the viewport
+            // height so each scroll feels less mechanical.
+            const actualStep = step ??
+                Math.max(1, Math.floor(document.documentElement.clientHeight *
+                    (ratioMin + Math.random() * (ratioMax - ratioMin))));
+            globalThis.scrollBy(0, actualStep);
             return [
                 Math.ceil(globalThis.scrollY + globalThis.innerHeight),
                 Math.ceil(document.body.scrollHeight),
             ];
-        });
+        }, stepDistance, DEFAULT_DISTANCE_RATIO_MIN, DEFAULT_DISTANCE_RATIO_MAX);
         options?.logger?.(currentScrollY, scrollHeight, 'Scrolling');
         if (currentScrollY === prevScrollY) {
             stuckCount++;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@d-zero/puppeteer-scroll",
-	"version": "3.1.18",
+	"version": "4.0.1",
 	"description": "Scroll function for puppeteer",
 	"author": "D-ZERO",
 	"license": "MIT",
@@ -23,7 +23,7 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
-		"@d-zero/shared": "0.21.3"
+		"@d-zero/shared": "0.22.0"
 	},
 	"devDependencies": {
 		"puppeteer": "24.37.5"
@@ -36,5 +36,5 @@
 		"url": "https://github.com/d-zero-dev/tools.git",
 		"directory": "packages/@d-zero/puppeteer-scroll"
 	},
-	"gitHead": "611614bdfcdfe3ef872efd01a1fd31ebedffdbb2"
+	"gitHead": "25b4043dcd70cf3490ddcefd76a88b22c60f7712"
 }