@d-zero/beholder 4.2.2 → 5.0.0

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0](https://github.com/d-zero-dev/tools/compare/@d-zero/beholder@4.2.3...@d-zero/beholder@5.0.0) (2026-09-10)
+
+- feat(beholder)!: report per-viewport image-scan outcome in PageData ([1e69228](https://github.com/d-zero-dev/tools/commit/1e692285f1ef3e0a8a89db695d635c7a2f88ba7c))
+
+### BREAKING CHANGES
+
+- PageData.imageScan is a new required field ({ desktop,
+  mobile }: ImageScanCode | null per viewport), following the same
+  precedent as the 4.0.0 addition of mainContents/scrollHeight. Anyone
+  constructing a PageData object directly (rather than only reading
+  scrapeStart()'s result) must add this field.
+
+Scraper#fetchImages now classifies each device preset's outcome via the
+new IMAGE_SCAN_CODE vocabulary (0=ok, 1=degraded, 2=nav-unsettled,
+3=frame-lost, 4=scroll-height-exceeded, 255=unknown) instead of only
+emitting a free-text changePhase message: success records ok/degraded
+based on @d-zero/puppeteer-page-scan's new settled result, a
+scrollHeight-limit skip records scroll-height-exceeded, and a caught
+exception is classified by the new classifyImageScanError (reusing
+puppeteer-scroll's isTransientFrameError, plus "Not attached to an
+active page"/"Target closed" for reload/goto-specific failures).
+
+#fetchImages opts into @d-zero/puppeteer-page-scan's new
+continueOnDegradedNetwork so a page whose network never settles still
+yields images (flagged degraded) instead of losing that viewport
+outright.
+
+Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
+
+## [4.2.3](https://github.com/d-zero-dev/tools/compare/@d-zero/beholder@4.2.2...@d-zero/beholder@4.2.3) (2026-08-14)
+
+### Bug Fixes
+
+- **beholder:** dispose anchor ElementHandles via AsyncDisposableStack ([c47a97b](https://github.com/d-zero-dev/tools/commit/c47a97b75af919c1dec634526146f2726b1be1e6))
+
 ## [4.2.2](https://github.com/d-zero-dev/tools/compare/@d-zero/beholder@4.2.1...@d-zero/beholder@4.2.2) (2026-08-11)
 
 **Note:** Version bump only for package @d-zero/beholder

package/dist/classify-image-scan-error.d.ts

@@ -0,0 +1,20 @@
+import { type ImageScanCode } from './image-scan-code.js';
+/**
+ * Classifies an error caught in `Scraper#fetchImages`'s per-device try/catch
+ * into an {@link ImageScanCode}, so the caught-exception path and the
+ * successful-scan path (`settled` / `scrolled`) can be recorded with the
+ * same small integer vocabulary for persistence.
+ * @param error - The value caught from the per-device `beforePageScan` call.
+ * @returns {@link IMAGE_SCAN_CODE.NAV_UNSETTLED} for a `NavigationUnsettledError`,
+ * {@link IMAGE_SCAN_CODE.FRAME_LOST} for a known frame/session-loss error,
+ * otherwise {@link IMAGE_SCAN_CODE.UNKNOWN}.
+ * @example
+ * ```ts
+ * try {
+ *   await beforePageScan(page, url, opts);
+ * } catch (error) {
+ *   imageScan[key] = classifyImageScanError(error);
+ * }
+ * ```
+ */
+export declare function classifyImageScanError(error: unknown): ImageScanCode;

package/dist/classify-image-scan-error.js

@@ -0,0 +1,41 @@
+import { NavigationUnsettledError } from '@d-zero/puppeteer-page-scan';
+import { isTransientFrameError } from '@d-zero/puppeteer-scroll';
+import { IMAGE_SCAN_CODE } from './image-scan-code.js';
+/**
+ * Matches session/target-loss error messages observed in `#fetchImages`'s
+ * per-device retry that `isTransientFrameError` (`@d-zero/puppeteer-scroll`)
+ * does not already cover — specific `reload`/`goto` failures rather than
+ * `page.evaluate` failures. Deliberately does NOT match a bare `Protocol
+ * error` prefix: that wraps many unrelated CDP failures (e.g. `Protocol
+ * error (Runtime.evaluate): stack overflow`) that are not frame/session
+ * loss and should fall through to `UNKNOWN` for accurate diagnosis.
+ */
+const FRAME_LOST_PATTERN = /Not attached to an active page|Target closed/i;
+/**
+ * Classifies an error caught in `Scraper#fetchImages`'s per-device try/catch
+ * into an {@link ImageScanCode}, so the caught-exception path and the
+ * successful-scan path (`settled` / `scrolled`) can be recorded with the
+ * same small integer vocabulary for persistence.
+ * @param error - The value caught from the per-device `beforePageScan` call.
+ * @returns {@link IMAGE_SCAN_CODE.NAV_UNSETTLED} for a `NavigationUnsettledError`,
+ * {@link IMAGE_SCAN_CODE.FRAME_LOST} for a known frame/session-loss error,
+ * otherwise {@link IMAGE_SCAN_CODE.UNKNOWN}.
+ * @example
+ * ```ts
+ * try {
+ *   await beforePageScan(page, url, opts);
+ * } catch (error) {
+ *   imageScan[key] = classifyImageScanError(error);
+ * }
+ * ```
+ */
+export function classifyImageScanError(error) {
+    if (error instanceof NavigationUnsettledError) {
+        return IMAGE_SCAN_CODE.NAV_UNSETTLED;
+    }
+    if (isTransientFrameError(error) ||
+        (error instanceof Error && FRAME_LOST_PATTERN.test(error.message))) {
+        return IMAGE_SCAN_CODE.FRAME_LOST;
+    }
+    return IMAGE_SCAN_CODE.UNKNOWN;
+}

package/dist/dom-evaluation.js

@@ -257,6 +257,16 @@ export async function getAnchorList(page, options, timeout = DEFAULT_DOM_EVALUAT
         log('Got 0 anchors');
         return [];
     }
+    // `$anchors` の各 ElementHandle は CDP 側のリモートオブジェクト参照を保持する
+    // ため、解放しないとページごとにハンドルがリークする。AsyncDisposableStack に
+    // まとめて登録して解放するが、`await using` でこの関数のスコープ脱出時に
+    // 即座に解放してはいけない — タイムアウトで打ち切られた後もバックグラウンドで
+    // resolveAnchor が動き続けている間にハンドルを解放すると、実行中の CDP 呼び出しが
+    // 失敗する。解放は work() の完了（成功・失敗いずれも）を待って初めて行う。
+    const anchorHandles = new AsyncDisposableStack();
+    for (const $anchor of $anchors) {
+        anchorHandles.use($anchor);
+    }
     const collected = [];
     let axHits = 0;
     let textFallbacks = 0;
@@ -289,7 +299,13 @@ export async function getAnchorList(page, options, timeout = DEFAULT_DOM_EVALUAT
             collected.push(resolved.anchor);
         }));
     };
-    const { timeout: timedOut } = await raceWithTimeout(work, timeout);
+    const workPromise = work();
+    // work() が真に完了した時点（タイムアウトで打ち切られた場合は、その後
+    // バックグラウンドで走り続ける resolveAnchor がすべて解決した時点）で
+    // ハンドルを解放する。disposeAsync() 自体の失敗も無視してよい
+    // （ベストエフォートの後始末であり、呼び出し元への影響はない）。
+    void workPromise.finally(() => anchorHandles.disposeAsync()).catch(() => { });
+    const { timeout: timedOut } = await raceWithTimeout(() => workPromise, timeout);
     cancelled = true;
     if (timedOut) {
         log('getAnchorList timed out after %dms; returning %d anchors collected so far', timeout, collected.length);

package/dist/image-scan-code.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Numeric outcome codes for a single device-preset image scan performed by
+ * `Scraper#fetchImages`. Small integers (fit a `Uint8`) so callers that
+ * persist per-page scan results to a database column can use an integer
+ * rather than a string enum. A `null` value (not part of this const) means
+ * the device preset was never attempted — non-HTML/external/non-HTTP pages,
+ * or `captureImages: false`.
+ * @example
+ * ```ts
+ * import { IMAGE_SCAN_CODE } from '@d-zero/beholder';
+ *
+ * db.insert({ imageScanMobile: pageData.imageScan.mobile ?? null });
+ * if (pageData.imageScan.mobile === IMAGE_SCAN_CODE.SCROLL_HEIGHT_EXCEEDED) {
+ *   // mobile images were skipped because scrollHeight exceeded the limit
+ * }
+ * ```
+ */
+export declare const IMAGE_SCAN_CODE: {
+    /** `beforePageScan` reached `settled: 'idle'`; images extracted normally. */
+    readonly OK: 0;
+    /** `beforePageScan` reached `settled: 'degraded'`; images extracted, but navigation never went network-idle so the result carries lower confidence. */
+    readonly DEGRADED: 1;
+    /** Navigation never settled and the post-timeout frame/URL/readyState check also failed (`NavigationUnsettledError`). */
+    readonly NAV_UNSETTLED: 2;
+    /** The main frame or session was lost mid-scan (detached Frame, session closed, execution context destroyed, or "Not attached to an active page"). */
+    readonly FRAME_LOST: 3;
+    /** `document.body.scrollHeight` exceeded the scan's `maxScrollHeight` guard; scroll and extraction were skipped. */
+    readonly SCROLL_HEIGHT_EXCEEDED: 4;
+    /** An error occurred that does not match any of the categories above. */
+    readonly UNKNOWN: 255;
+};
+/** Numeric outcome code for one device preset's image scan. See {@link IMAGE_SCAN_CODE}. */
+export type ImageScanCode = (typeof IMAGE_SCAN_CODE)[keyof typeof IMAGE_SCAN_CODE];

package/dist/image-scan-code.js

@@ -0,0 +1,31 @@
+/**
+ * Numeric outcome codes for a single device-preset image scan performed by
+ * `Scraper#fetchImages`. Small integers (fit a `Uint8`) so callers that
+ * persist per-page scan results to a database column can use an integer
+ * rather than a string enum. A `null` value (not part of this const) means
+ * the device preset was never attempted — non-HTML/external/non-HTTP pages,
+ * or `captureImages: false`.
+ * @example
+ * ```ts
+ * import { IMAGE_SCAN_CODE } from '@d-zero/beholder';
+ *
+ * db.insert({ imageScanMobile: pageData.imageScan.mobile ?? null });
+ * if (pageData.imageScan.mobile === IMAGE_SCAN_CODE.SCROLL_HEIGHT_EXCEEDED) {
+ *   // mobile images were skipped because scrollHeight exceeded the limit
+ * }
+ * ```
+ */
+export const IMAGE_SCAN_CODE = {
+    /** `beforePageScan` reached `settled: 'idle'`; images extracted normally. */
+    OK: 0,
+    /** `beforePageScan` reached `settled: 'degraded'`; images extracted, but navigation never went network-idle so the result carries lower confidence. */
+    DEGRADED: 1,
+    /** Navigation never settled and the post-timeout frame/URL/readyState check also failed (`NavigationUnsettledError`). */
+    NAV_UNSETTLED: 2,
+    /** The main frame or session was lost mid-scan (detached Frame, session closed, execution context destroyed, or "Not attached to an active page"). */
+    FRAME_LOST: 3,
+    /** `document.body.scrollHeight` exceeded the scan's `maxScrollHeight` guard; scroll and extraction were skipped. */
+    SCROLL_HEIGHT_EXCEEDED: 4,
+    /** An error occurred that does not match any of the categories above. */
+    UNKNOWN: 255,
+};

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export { detectCompress } from '@d-zero/shared/detect-compress';
 export type { CompressType } from '@d-zero/shared/detect-compress';
 export { detectCDN } from '@d-zero/shared/detect-cdn';
 export type { CDNType } from '@d-zero/shared/detect-cdn';
+export { IMAGE_SCAN_CODE } from './image-scan-code.js';
+export type { ImageScanCode } from './image-scan-code.js';
 export type { ScrapeResult, ResourceEntry, ConsoleLogEntry, PageData } from './types.js';
 export type { ScraperOptions, ChangePhaseEvent, ScraperEventTypes } from './types.js';
-export type { Resource, AnchorData, Meta, ImageElement, SkippedPageData, NetworkLog, ScrollHeightData, MainContentsData, MainContentsMainTag, MainContentsHeading, MainContentsImage, MainContentsTable, MainContentsButton, MainContentsIframe, MainContentsVideo, MainContentsAudio, MainContentsCanvas, OpenGraphMeta, OgArticleMeta, OgBookMeta, OgProfileMeta, OgMusicMeta, OgVideoNsMeta, TwitterMeta, FbMeta, FediverseMeta, AppleMeta, MsApplicationMeta, VerificationMeta, GoogleMeta, GeoMeta, CitationMeta, RdfaMeta, MicrodataMeta, AmpMeta, LegacyMeta, MobileMeta, MicroformatsMeta, PinterestMeta, SlackMeta, LinkedInMeta, ExperimentalMeta, WikiMeta, LinkMeta, LinkEntry, JsonLdEntry, OthersBucket, ScriptEntry, IframeEntry, TagsMeta, TagDetail, TagEntry, TagSource, ViewportMeta, RobotsMeta, ReferrerMeta, FormatDetectionMeta, HttpEquivMeta, HttpEquivRefresh, RawHeadEntry, } from './types.js';
+export type { Resource, AnchorData, Meta, ImageElement, SkippedPageData, NetworkLog, ScrollHeightData, ImageScanData, MainContentsData, MainContentsMainTag, MainContentsHeading, MainContentsImage, MainContentsTable, MainContentsButton, MainContentsIframe, MainContentsVideo, MainContentsAudio, MainContentsCanvas, OpenGraphMeta, OgArticleMeta, OgBookMeta, OgProfileMeta, OgMusicMeta, OgVideoNsMeta, TwitterMeta, FbMeta, FediverseMeta, AppleMeta, MsApplicationMeta, VerificationMeta, GoogleMeta, GeoMeta, CitationMeta, RdfaMeta, MicrodataMeta, AmpMeta, LegacyMeta, MobileMeta, MicroformatsMeta, PinterestMeta, SlackMeta, LinkedInMeta, ExperimentalMeta, WikiMeta, LinkMeta, LinkEntry, JsonLdEntry, OthersBucket, ScriptEntry, IframeEntry, TagsMeta, TagDetail, TagEntry, TagSource, ViewportMeta, RobotsMeta, ReferrerMeta, FormatDetectionMeta, HttpEquivMeta, HttpEquivRefresh, RawHeadEntry, } from './types.js';

package/dist/index.js

@@ -16,3 +16,4 @@ export { extractMetaFromDocument } from './extract-meta.js';
 export { MAIN_CONTENT_FALLBACK_SELECTORS, MAIN_CONTENT_SELECTORS, } from './main-content-selectors.js';
 export { detectCompress } from '@d-zero/shared/detect-compress';
 export { detectCDN } from '@d-zero/shared/detect-cdn';
+export { IMAGE_SCAN_CODE } from './image-scan-code.js';

package/dist/scraper.js

@@ -41,9 +41,11 @@ import { detectCDN } from '@d-zero/shared/detect-cdn';
 import { detectCompress } from '@d-zero/shared/detect-compress';
 import { retry as retryable } from '@d-zero/shared/retry';
 import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
+import { classifyImageScanError } from './classify-image-scan-error.js';
 import { resourceLog, scraperLog } from './debug.js';
 import { DEFAULT_DOM_EVALUATION_TIMEOUT, getAnchorList, getImageList, getMeta, } from './dom-evaluation.js';
 import { getMainContents } from './get-main-contents.js';
+import { IMAGE_SCAN_CODE } from './image-scan-code.js';
 import { isError } from './is-error.js';
 import { isHtmlContentType } from './is-html-content-type.js';
 import { keywordCheck } from './keyword-check.js';
@@ -67,6 +69,8 @@ const rLog = resourceLog.extend(pid);
  * normal responsive sites complete well within the 20 min retry budget.
  */
 const MAX_SCROLL_HEIGHT = 1_000_000;
+/** Shared "not attempted" value for `PageData.imageScan`, reused everywhere a page is returned without an image scan (non-HTML/external/non-HTTP, or the `@retryable` fallback). */
+const EMPTY_IMAGE_SCAN = { desktop: null, mobile: null };
 let Scraper = (() => {
     let _classSuper = EventEmitter;
     let _instanceExtraInitializers = [];
@@ -103,6 +107,7 @@ let Scraper = (() => {
                     fallback: {
                         imageList: [],
                         scrollHeight: { desktop: null, mobile: null },
+                        imageScan: EMPTY_IMAGE_SCAN,
                     },
                     onWait(determinedInterval, retryCount, methodName, error) {
                         void this.emit('changePhase', {
@@ -323,6 +328,7 @@ let Scraper = (() => {
                                 html: '',
                                 mainContents: null,
                                 scrollHeight: null,
+                                imageScan: EMPTY_IMAGE_SCAN,
                                 isSkipped: false,
                             };
                         }
@@ -369,6 +375,7 @@ let Scraper = (() => {
                                 html,
                                 mainContents: null,
                                 scrollHeight: null,
+                                imageScan: EMPTY_IMAGE_SCAN,
                                 isSkipped: false,
                             };
                         }
@@ -416,6 +423,7 @@ let Scraper = (() => {
                         }, domEvaluationTimeout);
                         let imageList = [];
                         let scrollHeight = null;
+                        let imageScan = EMPTY_IMAGE_SCAN;
                         if (captureImages) {
                             void this.emit('changePhase', {
                                 pid: process.pid,
@@ -427,6 +435,7 @@ let Scraper = (() => {
                             const fetched = await this.#fetchImages(page, url.withoutHashAndAuth, isExternal, imageLoadTimeout, domEvaluationTimeout);
                             imageList = fetched.imageList;
                             scrollHeight = fetched.scrollHeight;
+                            imageScan = fetched.imageScan;
                         }
                         else {
                             scrollHeight = await measureScrollHeight(page);
@@ -447,6 +456,7 @@ let Scraper = (() => {
                             html,
                             mainContents,
                             scrollHeight,
+                            imageScan,
                             isSkipped: false,
                         };
                     }
@@ -462,6 +472,7 @@ let Scraper = (() => {
                     ];
                     const imageList = [];
                     const scrollHeight = { desktop: null, mobile: null };
+                    const imageScan = { desktop: null, mobile: null };
                     for (const { key, preset } of devices) {
                         const scrollKey = key === 'desktop-compact' ? 'desktop' : 'mobile';
                         try {
@@ -479,9 +490,15 @@ let Scraper = (() => {
                                 listener,
                                 timeout: 5000,
                                 maxScrollHeight: MAX_SCROLL_HEIGHT,
+                                // This per-device try/catch already isolates and classifies
+                                // failures (see `classifyImageScanError`), so a page whose
+                                // network never settles should degrade gracefully here
+                                // rather than losing the whole device preset's images.
+                                continueOnDegradedNetwork: true,
                             });
                             scrollHeight[scrollKey] = scanResult.scrollHeight;
                             if (!scanResult.scrolled) {
+                                imageScan[scrollKey] = IMAGE_SCAN_CODE.SCROLL_HEIGHT_EXCEEDED;
                                 void this.emit('changePhase', {
                                     pid: process.pid,
                                     name: 'retryExhausted',
@@ -512,10 +529,13 @@ let Scraper = (() => {
                             });
                             const images = await getImageList(page, preset.width, domEvaluationTimeout);
                             imageList.push(...images);
+                            imageScan[scrollKey] =
+                                scanResult.settled === 'idle' ? IMAGE_SCAN_CODE.OK : IMAGE_SCAN_CODE.DEGRADED;
                         }
                         catch (error) {
                             const errorMessage = error instanceof Error ? error.message : String(error);
                             log('Error(FETCH_IMAGES/%s): %s', key, errorMessage);
+                            imageScan[scrollKey] = classifyImageScanError(error);
                             void this.emit('changePhase', {
                                 pid: process.pid,
                                 name: 'retryExhausted',
@@ -525,7 +545,7 @@ let Scraper = (() => {
                             });
                         }
                     }
-                    return { imageList, scrollHeight };
+                    return { imageList, scrollHeight, imageScan };
                 }, "#fetchImages") }, _private_fetchImages_decorators, { kind: "method", name: "#fetchImages", static: false, private: true, access: { has: obj => #fetchImages in obj, get: obj => obj.#fetchImages }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
@@ -607,6 +627,7 @@ let Scraper = (() => {
                     html: '',
                     mainContents: null,
                     scrollHeight: null,
+                    imageScan: EMPTY_IMAGE_SCAN,
                     isSkipped: false,
                 };
                 void this.emit('changePhase', {
@@ -806,7 +827,12 @@ let Scraper = (() => {
          * WHY per-device try-catch: Some pages (e.g. those using fullpage.js or
          * scroll-jacking libraries) destroy the execution context when the viewport
          * changes and triggers a reload. Isolating each device preset allows partial
-         * results — if one viewport fails, the other can still succeed.
+         * results — if one viewport fails, the other can still succeed. The outcome
+         * of each device preset (success, degraded, or one of the failure kinds) is
+         * recorded per-preset in the returned `imageScan`, classified by
+         * {@link classifyImageScanError} — a page that never goes network-idle
+         * (analytics beacons, chat widgets, open WebSocket connections) still
+         * yields images, just flagged `IMAGE_SCAN_CODE.DEGRADED` instead of `OK`.
          *
          * WHY retryable with 20-min timeout and empty fallback: Image extraction is
          * best-effort. If all retries fail, empty images and null scroll heights are
@@ -833,7 +859,7 @@ let Scraper = (() => {
          * @param isExternal - Whether the page is external
          * @param imageLoadTimeout - Timeout (ms) for waiting images to complete loading
          * @param domEvaluationTimeout - Timeout (ms) for the in-page image extraction `page.evaluate`
-         * @returns Image elements plus desktop/mobile scroll heights from the scan path
+         * @returns Image elements, desktop/mobile scroll heights, and the per-device `imageScan` outcome codes
          */
         get #fetchImages() { return _private_fetchImages_descriptor.value; }
     };

package/dist/to-console-log-entry.js

@@ -18,6 +18,10 @@ export async function toConsoleLogEntry(msg, pageUrl) {
             return;
         }
         finally {
+            // Why not `await using`: dispose() が reject すると SuppressedError に
+            // 包まれ、本来無視したいだけの dispose 失敗が呼び出し元へ伝播してしまう。
+            // ここでは jsonValue() の結果を最優先し、dispose の失敗は握りつぶす
+            // 現状の挙動を維持する。
             await arg.dispose().catch(() => { });
         }
     }));

package/dist/types.d.ts

@@ -4,10 +4,12 @@
  * @see {@link ./dom-evaluation.ts} for DOM extraction functions (anchors, images, meta)
  * @module
  */
+export type { ImageScanCode } from './image-scan-code.js';
 export type { ExURL, ParseURLOptions } from '@d-zero/shared/parse-url';
 export type { CompressType } from '@d-zero/shared/detect-compress';
 export type { CDNType } from '@d-zero/shared/detect-cdn';
 export type { Meta, OpenGraphMeta, OgArticleMeta, OgBookMeta, OgProfileMeta, OgMusicMeta, OgVideoNsMeta, TwitterMeta, FbMeta, FediverseMeta, AppleMeta, MsApplicationMeta, VerificationMeta, GoogleMeta, GeoMeta, CitationMeta, RdfaMeta, MicrodataMeta, AmpMeta, LegacyMeta, MobileMeta, MicroformatsMeta, PinterestMeta, SlackMeta, LinkedInMeta, ExperimentalMeta, WikiMeta, LinkMeta, LinkEntry, JsonLdEntry, OthersBucket, ScriptEntry, IframeEntry, TagsMeta, TagDetail, TagEntry, TagSource, ViewportMeta, RobotsMeta, ReferrerMeta, FormatDetectionMeta, HttpEquivMeta, HttpEquivRefresh, RawHeadEntry, } from './meta/types.js';
+import type { ImageScanCode } from './image-scan-code.js';
 import type { Meta } from './meta/types.js';
 import type { CDNType } from '@d-zero/shared/detect-cdn';
 import type { CompressType } from '@d-zero/shared/detect-compress';
@@ -54,6 +56,21 @@ export type PageData = {
      * `null` when not measured (non-HTML, external, non-HTTP, or skipped).
      */
     scrollHeight: ScrollHeightData | null;
+    /**
+     * Per-device-preset outcome of the `<img>` element scan performed by
+     * `Scraper#fetchImages`, keyed the same way as {@link ScrollHeightData}.
+     * A field is `null` when that device preset's image scan was never
+     * attempted (non-HTML, external, non-HTTP page, or `captureImages: false`);
+     * otherwise it is an {@link ImageScanCode} recording why the scan
+     * succeeded, degraded, or was abandoned. See `IMAGE_SCAN_CODE`.
+     * @example
+     * ```ts
+     * if (pageData.imageScan.mobile === IMAGE_SCAN_CODE.SCROLL_HEIGHT_EXCEEDED) {
+     *   // mobile images were skipped due to an oversized scrollHeight
+     * }
+     * ```
+     */
+    imageScan: ImageScanData;
     /** Always `false` for successfully scraped pages. See {@link SkippedPageData} for skipped pages. */
     isSkipped: false;
 };
@@ -66,6 +83,16 @@ export type ScrollHeightData = {
     /** Height at `mobile-small` (width 320 @ 2x), or `null` if that preset failed. */
     mobile: number | null;
 };
+/**
+ * Per-device-preset {@link ImageScanCode} outcome of `Scraper#fetchImages`,
+ * mirroring {@link ScrollHeightData}'s desktop/mobile shape.
+ */
+export type ImageScanData = {
+    /** Outcome for `desktop-compact` (width 1280), or `null` if not attempted. */
+    desktop: ImageScanCode | null;
+    /** Outcome for `mobile-small` (width 320 @ 2x), or `null` if not attempted. */
+    mobile: ImageScanCode | null;
+};
 /**
  * Quantitative metrics for the detected main content region of a page.
  * @example

package/package.json

@@ -1,12 +1,15 @@
 {
 	"name": "@d-zero/beholder",
-	"version": "4.2.2",
+	"version": "5.0.0",
 	"description": "Page-level scraper for web crawling and auditing",
 	"author": "D-ZERO",
 	"license": "MIT",
 	"publishConfig": {
 		"access": "public"
 	},
+	"engines": {
+		"node": ">=24.11.0"
+	},
 	"type": "module",
 	"exports": {
 		".": {
@@ -20,10 +23,11 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
-		"@d-zero/puppeteer-page-scan": "4.6.8",
-		"@d-zero/shared": "0.22.5",
+		"@d-zero/puppeteer-page-scan": "4.7.0",
+		"@d-zero/puppeteer-scroll": "4.0.12",
+		"@d-zero/shared": "0.23.0",
 		"debug": "4.4.3",
-		"puppeteer": "25.3.0",
+		"puppeteer": "25.5.0",
 		"simple-wappalyzer": "1.1.100"
 	},
 	"devDependencies": {
@@ -36,5 +40,5 @@
 		"url": "https://github.com/d-zero-dev/tools.git",
 		"directory": "packages/@d-zero/beholder"
 	},
-	"gitHead": "b06568f6812c4f560b4d8c3a1d280cd42ec264a5"
+	"gitHead": "41dfa4dc685a038fb1ce391a305617cca7e37de3"
 }

package/src/classify-image-scan-error.spec.ts

@@ -0,0 +1,34 @@
+import { NavigationUnsettledError } from '@d-zero/puppeteer-page-scan';
+import { describe, expect, it } from 'vitest';
+
+import { classifyImageScanError } from './classify-image-scan-error.js';
+import { IMAGE_SCAN_CODE } from './image-scan-code.js';
+
+describe('classifyImageScanError', () => {
+	it('NavigationUnsettledError は NAV_UNSETTLED に分類する', () => {
+		expect(classifyImageScanError(new NavigationUnsettledError('never settled'))).toBe(
+			IMAGE_SCAN_CODE.NAV_UNSETTLED,
+		);
+	});
+
+	it.each([
+		"Attempted to use detached Frame 'XXX'.",
+		'Session closed.',
+		'Execution context was destroyed.',
+		'Protocol error (Page.reload): Not attached to an active page',
+		'Protocol error (Page.reload): Target closed',
+	])('%s は FRAME_LOST に分類する', (message) => {
+		expect(classifyImageScanError(new Error(message))).toBe(IMAGE_SCAN_CODE.FRAME_LOST);
+	});
+
+	it('分類不能な Error は UNKNOWN に分類する', () => {
+		expect(classifyImageScanError(new Error('TypeError: foo is not a function'))).toBe(
+			IMAGE_SCAN_CODE.UNKNOWN,
+		);
+	});
+
+	it('Error インスタンスでない値も UNKNOWN に分類する', () => {
+		expect(classifyImageScanError('plain string error')).toBe(IMAGE_SCAN_CODE.UNKNOWN);
+		expect(classifyImageScanError(null)).toBe(IMAGE_SCAN_CODE.UNKNOWN);
+	});
+});

package/src/classify-image-scan-error.ts

@@ -0,0 +1,46 @@
+import { NavigationUnsettledError } from '@d-zero/puppeteer-page-scan';
+import { isTransientFrameError } from '@d-zero/puppeteer-scroll';
+
+import { IMAGE_SCAN_CODE, type ImageScanCode } from './image-scan-code.js';
+
+/**
+ * Matches session/target-loss error messages observed in `#fetchImages`'s
+ * per-device retry that `isTransientFrameError` (`@d-zero/puppeteer-scroll`)
+ * does not already cover — specific `reload`/`goto` failures rather than
+ * `page.evaluate` failures. Deliberately does NOT match a bare `Protocol
+ * error` prefix: that wraps many unrelated CDP failures (e.g. `Protocol
+ * error (Runtime.evaluate): stack overflow`) that are not frame/session
+ * loss and should fall through to `UNKNOWN` for accurate diagnosis.
+ */
+const FRAME_LOST_PATTERN = /Not attached to an active page|Target closed/i;
+
+/**
+ * Classifies an error caught in `Scraper#fetchImages`'s per-device try/catch
+ * into an {@link ImageScanCode}, so the caught-exception path and the
+ * successful-scan path (`settled` / `scrolled`) can be recorded with the
+ * same small integer vocabulary for persistence.
+ * @param error - The value caught from the per-device `beforePageScan` call.
+ * @returns {@link IMAGE_SCAN_CODE.NAV_UNSETTLED} for a `NavigationUnsettledError`,
+ * {@link IMAGE_SCAN_CODE.FRAME_LOST} for a known frame/session-loss error,
+ * otherwise {@link IMAGE_SCAN_CODE.UNKNOWN}.
+ * @example
+ * ```ts
+ * try {
+ *   await beforePageScan(page, url, opts);
+ * } catch (error) {
+ *   imageScan[key] = classifyImageScanError(error);
+ * }
+ * ```
+ */
+export function classifyImageScanError(error: unknown): ImageScanCode {
+	if (error instanceof NavigationUnsettledError) {
+		return IMAGE_SCAN_CODE.NAV_UNSETTLED;
+	}
+	if (
+		isTransientFrameError(error) ||
+		(error instanceof Error && FRAME_LOST_PATTERN.test(error.message))
+	) {
+		return IMAGE_SCAN_CODE.FRAME_LOST;
+	}
+	return IMAGE_SCAN_CODE.UNKNOWN;
+}

package/src/dom-evaluation.spec.ts

@@ -213,6 +213,9 @@ function mockAnchorHandle(
 			Promise.resolve({
 				jsonValue: () => Promise.resolve(props[propName] ?? ''),
 			}),
+		// getAnchorList() が AsyncDisposableStack へ登録するため、実際の
+		// ElementHandle と同様 Symbol.asyncDispose を実装しておく必要がある
+		[Symbol.asyncDispose]: () => Promise.resolve(),
 	} as unknown as ElementHandle<Element>;
 }
 
@@ -291,6 +294,7 @@ describe('getAnchorList', () => {
 				textContent();
 				return Promise.resolve({ jsonValue: () => Promise.resolve('text fallback') });
 			},
+			[Symbol.asyncDispose]: () => Promise.resolve(),
 		} as unknown as ElementHandle<Element>;
 		const page = mockPageForAnchors({
 			anchors: [$anchor],
@@ -329,6 +333,7 @@ describe('getAnchorList', () => {
 			remoteObject: () => {
 				throw new Error('Handle is detached');
 			},
+			[Symbol.asyncDispose]: () => Promise.resolve(),
 		} as unknown as ElementHandle<Element>;
 		const $good = mockAnchorHandle('obj-1', { href: 'https://example.com/page' });
 		const page = mockPageForAnchors({
@@ -436,6 +441,7 @@ describe('getAnchorList', () => {
 		const $slow = {
 			remoteObject: () => ({ objectId: 'obj-slow' }),
 			getProperty: () => new Promise(() => {}), // never resolves
+			[Symbol.asyncDispose]: () => Promise.resolve(),
 		} as unknown as ElementHandle<Element>;
 		const page = mockPageForAnchors({
 			anchors: [$fast, $slow],
@@ -491,6 +497,41 @@ describe('getAnchorList', () => {
 
 		expect(anchors).toStrictEqual([]);
 	});
+
+	it('disposes every anchor handle after the list is collected (no CDP handle leak)', async () => {
+		const disposeA = vi.fn(async () => {});
+		const disposeB = vi.fn(async () => {});
+		const $a = {
+			remoteObject: () => ({ objectId: 'obj-a' }),
+			getProperty: () =>
+				Promise.resolve({ jsonValue: () => Promise.resolve('https://example.com/a') }),
+			[Symbol.asyncDispose]: disposeA,
+		} as unknown as ElementHandle<Element>;
+		const $b = {
+			remoteObject: () => ({ objectId: 'obj-b' }),
+			getProperty: () =>
+				Promise.resolve({ jsonValue: () => Promise.resolve('https://example.com/b') }),
+			[Symbol.asyncDispose]: disposeB,
+		} as unknown as ElementHandle<Element>;
+		const page = mockPageForAnchors({
+			anchors: [$a, $b],
+			axNodes: [
+				{ backendDOMNodeId: 1, name: { value: 'A' } },
+				{ backendDOMNodeId: 2, name: { value: 'B' } },
+			],
+			describeNodes: { 'obj-a': 1, 'obj-b': 2 },
+		});
+
+		const anchors = await getAnchorList(page);
+		expect(anchors).toHaveLength(2);
+
+		// 解放は work() 完了後に detached な .finally() で行われるため、
+		// getAnchorList の resolve と同期しない。1 tick 待ってから観測する
+		await new Promise((resolve) => setImmediate(resolve));
+
+		expect(disposeA).toHaveBeenCalledTimes(1);
+		expect(disposeB).toHaveBeenCalledTimes(1);
+	});
 });
 
 describe('DEFAULT_DOM_EVALUATION_TIMEOUT', () => {