@d-zero/puppeteer-scroll 3.1.18-alpha.2 → 4.0.0

package/README.md

@@ -21,3 +21,72 @@ await page.goto('https://example.com');
 
 await scrollAllOver(page);
 ```
+
+## API
+
+### `scrollAllOver(page, options?)`
+
+ページを上から下までスクロールします。`body.scrollHeight`に到達するか、スクロールが進行しない状態（スクロールジャック等）が3イテレーション続いた時点で終了します。
+
+#### オプション
+
+| オプション | 型                                         | デフォルト                                  | 説明                                                                                                                            |
+| ---------- | ------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `interval` | `number \| DelayOptions`                   | `{ random: { min: 200, max: 500 } }`        | 各スクロール間のミリ秒。固定値またはランダム範囲（`{ random: ... }`）を指定可能。                                               |
+| `distance` | `number \| DelayOptions`                   | 未指定時は`clientHeight × random(0.5, 1.0)` | 1ステップで進むピクセル数。固定値またはランダム範囲を指定可能。未指定時はビューポート高さの50〜100%の範囲でステップごとに変動。 |
+| `logger`   | `(scrollY, scrollHeight, message) => void` | なし                                        | スクロール進捗のログ用コールバック。                                                                                            |
+
+`DelayOptions`の型定義は[`@d-zero/shared/delay`](../shared/src/delay.md)を参照。
+
+#### デフォルト挙動
+
+オプションを渡さない場合、人間のスクロールに近い揺らぎを付けるため、`interval`と`distance`の両方がランダム化されます:
+
+- **`interval`**: 200〜500ms の範囲で毎ループ均一分布からサンプリング
+- **`distance`**: ビューポート高さの 50〜100% を毎ループブラウザ側`Math.random()`でサンプリング（`clientHeight`に比例するためモバイル・デスクトップを問わず安全）
+
+決定論的な挙動が必要な場合（テスト、レコーディング、比較など）は、必ず`interval`と`distance`を明示的に指定してください:
+
+```ts
+// 完全固定（ランダム要素なし）。distance はピクセル値を直接指定する
+await scrollAllOver(page, {
+	interval: 300,
+	distance: 800,
+});
+```
+
+> **メモ**: `distance`に`0`以下の値を渡しても内部で最小`1`px に丸められます（スクロールジャック誤検出の防止）。`distance`はピクセル値であり、ビューポート比率では指定できません。
+
+#### 使用例
+
+```ts
+import { scrollAllOver } from '@d-zero/puppeteer-scroll';
+
+// すべてデフォルト（ランダム挙動）
+await scrollAllOver(page);
+
+// interval だけ固定
+await scrollAllOver(page, { interval: 300 });
+
+// interval と distance の両方をランダム化（distance はピクセル値）
+await scrollAllOver(page, {
+	interval: { random: { min: 200, max: 800 } },
+	distance: { random: { min: 300, max: 900 } },
+});
+
+// 進捗ログ
+await scrollAllOver(page, {
+	logger: (scrollY, scrollHeight, message) => {
+		console.log(`${message}: ${scrollY}/${scrollHeight}`);
+	},
+});
+```
+
+### スクロールジャック検出
+
+`scrollBy`が呼ばれても`scrollY`が変化しない状態（fullpage.jsなどスクロールジャック系のライブラリが原因）を検出した場合、3イテレーション連続で進行がない時点で自動的に終了します。終了時には`logger`に`'Scroll stuck, bailing out'`が通知されます。
+
+## 関連パッケージ
+
+- [`@d-zero/puppeteer-page-scan`](../puppeteer-page-scan/README.md) — `scrollAllOver`を内包し、`scrollInterval` / `scrollDistance`オプション経由で挙動をカスタマイズ可能
+- [`@d-zero/shared/delay`](../shared/src/delay.md) — `DelayOptions`型と確率分布のサポート

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-alpha.2",
+	"version": "4.0.0",
 	"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-alpha.2"
+		"@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": "74b262438ed5e263d89a066029adfadf1ec27e0b"
+	"gitHead": "2d24e08c0cb516b7ea9d07a4301eb991193cca11"
 }