@percy/core 1.31.13 → 1.31.14-beta.1

package/dist/discovery.js

@@ -2,6 +2,7 @@ import logger from '@percy/logger';
 import Queue from './queue.js';
 import Page from './page.js';
 import { normalizeURL, hostnameMatches, createResource, createRootResource, createPercyCSSResource, createLogResource, yieldAll, snapshotLogName, waitForTimeout, withRetries, waitForSelectorInsideBrowser, isGzipped, maybeScrollToBottom } from './utils.js';
+import { ByteLRU, entrySize, DiskSpillStore, createSpillDir } from './cache/byte-lru.js';
 import { sha256hash } from '@percy/client/utils';
 import Pako from 'pako';
 
@@ -223,10 +224,8 @@ function processSnapshotResources({
   resources = resources.flat();
 
   // include associated snapshot logs matched by meta information
-  resources.push(createLogResource(logger.query(log => {
-    var _log$meta$snapshot, _log$meta$snapshot2;
-    return ((_log$meta$snapshot = log.meta.snapshot) === null || _log$meta$snapshot === void 0 ? void 0 : _log$meta$snapshot.testCase) === snapshot.meta.snapshot.testCase && ((_log$meta$snapshot2 = log.meta.snapshot) === null || _log$meta$snapshot2 === void 0 ? void 0 : _log$meta$snapshot2.name) === snapshot.meta.snapshot.name;
-  })));
+  resources.push(createLogResource(logger.snapshotLogs(snapshot.meta.snapshot)));
+  logger.evictSnapshot(snapshot.meta.snapshot);
   if (process.env.PERCY_GZIP) {
     for (let index = 0; index < resources.length; index++) {
       const alreadyZipped = isGzipped(resources[index].content);
@@ -434,9 +433,74 @@ export async function* discoverSnapshotResources(queue, options, callback) {
     return all;
   }, []));
 }
-
-// Used to cache resources across core instances
 export const RESOURCE_CACHE_KEY = Symbol('resource-cache');
+export const CACHE_STATS_KEY = Symbol('resource-cache-stats');
+export const DISK_SPILL_KEY = Symbol('resource-cache-disk-spill');
+const BYTES_PER_MB = 1_000_000;
+// MAX_RESOURCE_SIZE in network.js is 25MB; caps below that would skip every
+// resource, so we clamp. MIN_REASONABLE_CAP_MB warns on near-useless caps.
+const MAX_RESOURCE_SIZE_MB = 25;
+const MIN_REASONABLE_CAP_MB = 50;
+const DEFAULT_WARN_THRESHOLD_BYTES = 500 * BYTES_PER_MB;
+function makeCacheStats() {
+  return {
+    effectiveMaxCacheRamMB: null,
+    oversizeSkipped: 0,
+    firstEvictionEventFired: false,
+    warningFired: false,
+    unsetModeBytes: 0
+  };
+}
+function readWarnThresholdBytes() {
+  const raw = Number(process.env.PERCY_CACHE_WARN_THRESHOLD_BYTES);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_WARN_THRESHOLD_BYTES;
+}
+
+// Cache lookup shared by the network intercept path. RAM miss falls through
+// to the disk tier; read failures return undefined so the browser refetches.
+// Also resolves the array-valued root-resource shape used for multi-width
+// DOM snapshots, regardless of which tier returned it.
+//
+// Disk hits are promoted back to RAM so a hot URL that was evicted once does
+// not pay the readFileSync cost on every subsequent access — the typical
+// two-tier-cache promotion pattern. ByteLRU's own eviction will then re-spill
+// the actual coldest entry if needed. DISK_SPILL_KEY is only set when the
+// ByteLRU tier is active (see createDiscoveryQueue 'start' handler), so the
+// cache here is guaranteed to be a ByteLRU when we enter this branch.
+export function lookupCacheResource(percy, snapshotResources, cache, url, width) {
+  let resource = snapshotResources.get(url) || cache.get(url);
+  const disk = percy[DISK_SPILL_KEY];
+  if (!resource && disk) {
+    resource = disk.get(url);
+    if (resource) {
+      percy.log.debug(`cache disk-hit: ${url} (disk=${disk.size}/` + `${Math.round(disk.bytes / BYTES_PER_MB)}MB)`);
+      // Promote back to RAM and drop the disk copy. cache.set may itself
+      // evict the LRU entry (which spills back to disk) — that's the
+      // intended LRU dance, not a bug.
+      cache.set(url, resource, entrySize(resource));
+      disk.delete(url);
+    }
+  }
+  if (resource && Array.isArray(resource) && resource[0].root) {
+    const rootResource = resource.find(r => {
+      var _r$widths;
+      return (_r$widths = r.widths) === null || _r$widths === void 0 ? void 0 : _r$widths.includes(width);
+    });
+    resource = rootResource || resource[0];
+  }
+  return resource;
+}
+
+// Fire-and-forget wrapper around the shared telemetry egress on Percy.
+// onEvict callbacks are sync; the microtask hop keeps even sendCacheTelemetry's
+// pre-await synchronous work (header construction, payload serialization) off
+// the eviction-loop hot path.
+function fireCacheEventSafe(percy, message, extra) {
+  // sendCacheTelemetry already swallows pager errors. The trailing .catch is
+  // belt-and-suspenders against Node 14's unhandled-rejection-as-fatal mode
+  // if the catch arm itself ever throws (e.g. log.debug stub explodes).
+  Promise.resolve().then(() => percy.sendCacheTelemetry(message, extra)).catch(() => {});
+}
 
 // Creates an asset discovery queue that uses the percy browser instance to create a page for each
 // snapshot which is used to intercept and capture snapshot resource requests.
@@ -446,21 +510,84 @@ export function createDiscoveryQueue(percy) {
   } = percy.config.discovery;
   let queue = new Queue('discovery');
   let cache;
+  let capBytes = null;
+  // Read once: saveResource consults this on every call.
+  const warnThreshold = readWarnThresholdBytes();
   return queue.set({
     concurrency
-  })
-  // on start, launch the browser and run the queue
-  .handle('start', async () => {
-    cache = percy[RESOURCE_CACHE_KEY] = new Map();
-
-    // If browser.launch() fails it will get captured in
-    // *percy.start()
+  }).handle('start', async () => {
+    const configuredMaxCacheRamMB = percy.config.discovery.maxCacheRam;
+    let effectiveMaxCacheRamMB = configuredMaxCacheRamMB;
+
+    // User's config is not mutated; the post-clamp value lives on stats.
+    if (configuredMaxCacheRamMB != null) {
+      if (configuredMaxCacheRamMB < MAX_RESOURCE_SIZE_MB) {
+        percy.log.warn(`--max-cache-ram=${configuredMaxCacheRamMB}MB is below the ${MAX_RESOURCE_SIZE_MB}MB minimum ` + '(individual resources up to 25MB would otherwise be dropped). ' + `Continuing with the minimum: ${MAX_RESOURCE_SIZE_MB}MB.`);
+        effectiveMaxCacheRamMB = MAX_RESOURCE_SIZE_MB;
+      } else if (configuredMaxCacheRamMB < MIN_REASONABLE_CAP_MB) {
+        percy.log.warn(`--max-cache-ram=${configuredMaxCacheRamMB}MB is very small; ` + 'most resources will not fit and hit rate will be near zero.');
+      }
+      if (percy.config.discovery.disableCache) {
+        percy.log.info('--max-cache-ram is ignored because --disable-cache is set.');
+      }
+      capBytes = effectiveMaxCacheRamMB * BYTES_PER_MB;
+    }
+    if (warnThreshold !== DEFAULT_WARN_THRESHOLD_BYTES) {
+      percy.log.debug(`PERCY_CACHE_WARN_THRESHOLD_BYTES override active: ${warnThreshold} bytes ` + `(default ${DEFAULT_WARN_THRESHOLD_BYTES}).`);
+    }
+    percy[CACHE_STATS_KEY] = makeCacheStats();
+    percy[CACHE_STATS_KEY].effectiveMaxCacheRamMB = capBytes != null ? effectiveMaxCacheRamMB : null;
+    if (capBytes != null) {
+      // Overflow tier: RAM evictions spill here. diskStore.set returns
+      // false on any I/O failure → caller falls back to drop automatically.
+      const diskStore = new DiskSpillStore(createSpillDir(), {
+        log: percy.log
+      });
+      percy[DISK_SPILL_KEY] = diskStore;
+      cache = percy[RESOURCE_CACHE_KEY] = new ByteLRU(capBytes, {
+        onEvict: (key, reason, value) => {
+          if (reason === 'too-big') {
+            percy[CACHE_STATS_KEY].oversizeSkipped++;
+            percy.log.debug(`cache skip (oversize): ${key}`);
+            return;
+          }
+          const spilled = diskStore.set(key, value);
+          percy.log.debug(`cache ${spilled ? 'spill' : 'evict'}: ${key} ` + `(cache ${Math.round(cache.calculatedSize / BYTES_PER_MB)}` + `/${effectiveMaxCacheRamMB}MB, entries=${cache.size}, ` + `disk=${diskStore.size}/${Math.round(diskStore.bytes / BYTES_PER_MB)}MB)`);
+          const stats = percy[CACHE_STATS_KEY];
+          if (stats && !stats.firstEvictionEventFired) {
+            stats.firstEvictionEventFired = true;
+            percy.log.info('Cache eviction active — cap reached, oldest entries spilling to disk.');
+            fireCacheEventSafe(percy, 'cache_eviction_started', {
+              cache_budget_ram_mb: effectiveMaxCacheRamMB,
+              cache_peak_bytes_seen: cache.stats.peakBytes,
+              eviction_count: cache.stats.evictions,
+              disk_spill_enabled: diskStore.ready
+            });
+          }
+        }
+      });
+    } else {
+      cache = percy[RESOURCE_CACHE_KEY] = new Map();
+    }
     await percy.browser.launch();
     queue.run();
-  })
-  // on end, close the browser
-  .handle('end', async () => {
-    await percy.browser.close();
+  }).handle('end', async () => {
+    // Disk-spill cleanup must run even if browser.close() throws — otherwise
+    // the per-run temp dir under os.tmpdir() leaks. CACHE_STATS_KEY is set
+    // alongside DISK_SPILL_KEY in 'start', so the snapshot is always safe.
+    try {
+      await percy.browser.close();
+    } finally {
+      const diskStore = percy[DISK_SPILL_KEY];
+      if (diskStore) {
+        percy[CACHE_STATS_KEY].finalDiskStats = {
+          ...diskStore.stats,
+          ready: diskStore.ready
+        };
+        diskStore.destroy();
+        delete percy[DISK_SPILL_KEY];
+      }
+    }
   })
   // snapshots are unique by name and testCase; when deferred also by widths
   .handle('find', ({
@@ -509,18 +636,9 @@ export function createDiscoveryQueue(percy) {
             disableCache: snapshot.discovery.disableCache,
             allowedHostnames: snapshot.discovery.allowedHostnames,
             disallowedHostnames: snapshot.discovery.disallowedHostnames,
-            getResource: (u, width = null) => {
-              let resource = snapshot.resources.get(u) || cache.get(u);
-              if (resource && Array.isArray(resource) && resource[0].root) {
-                const rootResource = resource.find(r => {
-                  var _r$widths;
-                  return (_r$widths = r.widths) === null || _r$widths === void 0 ? void 0 : _r$widths.includes(width);
-                });
-                resource = rootResource || resource[0];
-              }
-              return resource;
-            },
+            getResource: (u, width = null) => lookupCacheResource(percy, snapshot.resources, cache, u, width),
             saveResource: r => {
+              var _percy$DISK_SPILL_KEY;
               const limitResources = process.env.LIMIT_SNAPSHOT_RESOURCES || false;
               const MAX_RESOURCES = Number(process.env.MAX_SNAPSHOT_RESOURCES) || 749;
               if (limitResources && snapshot.resources.size >= MAX_RESOURCES) {
@@ -528,8 +646,31 @@ export function createDiscoveryQueue(percy) {
                 return;
               }
               snapshot.resources.set(r.url, r);
-              if (!snapshot.discovery.disableCache) {
+              if (snapshot.discovery.disableCache) return;
+
+              // Fresh write supersedes any prior spill — prevents races
+              // where getResource could serve a stale disk copy.
+              if ((_percy$DISK_SPILL_KEY = percy[DISK_SPILL_KEY]) !== null && _percy$DISK_SPILL_KEY !== void 0 && _percy$DISK_SPILL_KEY.has(r.url)) {
+                percy[DISK_SPILL_KEY].delete(r.url);
+              }
+              if (capBytes != null) {
+                // ByteLRU fires onEvict('too-big') for oversize entries;
+                // the oversize_skipped stat + debug log live there.
+                cache.set(r.url, r, entrySize(r));
+              } else {
+                // Subtract the prior entry's footprint before overwriting so
+                // the byte counter tracks current cache contents rather than
+                // cumulative writes. Without this, the same shared CSS saved
+                // across N snapshots would inflate unsetModeBytes by N×.
+                const stats = percy[CACHE_STATS_KEY];
+                const prior = cache.get(r.url);
+                if (prior) stats.unsetModeBytes -= entrySize(prior);
                 cache.set(r.url, r);
+                stats.unsetModeBytes += entrySize(r);
+                if (!stats.warningFired && stats.unsetModeBytes >= warnThreshold) {
+                  stats.warningFired = true;
+                  percy.log.warn(`Percy cache is using ${(stats.unsetModeBytes / BYTES_PER_MB).toFixed(1)}MB. ` + 'If your CI is memory-constrained, set --max-cache-ram. ' + 'See https://www.browserstack.com/docs/percy/cli/managing-cache-memory');
+                }
               }
             }
           }

package/dist/lock.js

@@ -0,0 +1,215 @@
+// Per-port lock file for Percy agent processes.
+//
+// Why: a stale ~/.percy directory after a crash currently surfaces as a
+// late, opaque EADDRINUSE on the next `percy start`. The lock file lets
+// us short-circuit at command entry with a clear, actionable refusal
+// message and lets us auto-reclaim a stale lock whose recorded pid is
+// dead.
+//
+// Cross-platform note: `fs.renameSync` over an existing target is
+// unreliable on Node 14 Windows (Percy's Windows CI is pinned to
+// node-version: 14, see .github/workflows/windows.yml). We therefore
+// reclaim via unlink + retry-`wx` rather than rename-based reclaim.
+
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+// Use a default import so tests can `spyOn(os, 'homedir')` to redirect
+// the lock dir into a tmpdir without touching the user's $HOME.
+// (Babel's namespace import is frozen and not spy-able.)
+import os from 'os';
+const LOCK_DIR_MODE = 0o700;
+const LOCK_FILE_MODE = 0o600;
+export class LockHeldError extends Error {
+  constructor(meta, lockPath) {
+    super(`Percy is already running on port ${meta.port} ` + `(pid ${meta.pid}, started ${meta.startedAt}).\n` + `If you believe this is stale, remove ${lockPath} and try again.`);
+    this.name = 'LockHeldError';
+    this.meta = meta;
+    this.lockPath = lockPath;
+  }
+}
+
+// Lockfile-name pattern: literal "agent-" prefix, decimal-digit-only
+// port (validated to be in the TCP range 0-65535), literal ".lock"
+// suffix. Built without any user-controlled string concatenation so
+// semgrep's path-traversal taint analysis is satisfied.
+const LOCK_DIR_NAME = '.percy';
+const LOCK_FILE_PREFIX = 'agent-';
+const LOCK_FILE_SUFFIX = '.lock';
+export function lockPathFor(port) {
+  // Validate that `port` is a TCP port (positive 16-bit integer). This
+  // guarantees the resulting filename only contains digits + literal
+  // characters from LOCK_FILE_PREFIX/LOCK_FILE_SUFFIX — no '/' or
+  // '..' can appear, eliminating any path-traversal risk.
+  let n = Number(port);
+  /* istanbul ignore if: invalid ports are filtered upstream by the
+     CLI flag parser and the Percy() constructor's default; this
+     guard is defensive against pathological direct callers. Port 0
+     is also rejected — it means "OS picks an ephemeral port", and a
+     lockfile keyed by 0 would not correspond to the actual bound
+     port (two callers requesting port 0 would contend on agent-0.lock
+     even though the OS hands them different ports). */
+  if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+    throw new TypeError(`Invalid port for lockfile: ${JSON.stringify(port)}`);
+  }
+  // The validated integer `n` plus the literal prefix/suffix yields a
+  // string of [prefix][digits][suffix] — no `/` or `..` is reachable.
+  // (semgrep's path-traversal rule is suppressed file-level via
+  // .semgrepignore because its taint analysis does not follow the
+  // Number.isInteger validation above.)
+  let filename = LOCK_FILE_PREFIX.concat(String(n), LOCK_FILE_SUFFIX);
+  return join(os.homedir(), LOCK_DIR_NAME, filename);
+}
+
+// `process.kill(pid, 0)` returns truthy for living processes, throws
+// ESRCH if the pid is gone, and throws EPERM if the pid exists but
+// belongs to another user (treat as alive — we cannot reclaim it).
+function livenessCheck(pid) {
+  try {
+    process.kill(pid, 0);
+    return 'alive';
+  } catch (err) {
+    /* istanbul ignore else: ESRCH is the only "dead" signal we
+       reclaim on. Every other code (EPERM = exists-but-foreign,
+       ENOSYS / EINVAL = exotic platform) means we cannot safely
+       claim the lock and must treat it as "alive". The else branch
+       collapses these cases — it's exercised by the EPERM test in
+       lock.test.js but not all error codes are individually
+       reproducible under nyc. */
+    if (err.code === 'ESRCH') return 'dead';
+    return 'alive';
+  }
+}
+
+// Acquire a per-port lock. On success, returns a handle whose `path`
+// the caller must eventually pass to `releaseLockSync`. Throws
+// `LockHeldError` if another live process holds the lock. Returns
+// `null` (no lock acquired) when `port === 0` — the lockfile is
+// keyed by the requested port, but port 0 means "OS picks an
+// ephemeral port", so the lockfile name wouldn't match the actual
+// bound port. Callers should treat a null handle as "no lock to
+// release" and the lockfile mechanism is effectively skipped for
+// ephemeral-port instances (e.g., parallel test fixtures).
+export function acquireLock({
+  port
+}) {
+  if (Number(port) === 0) return null;
+  const dir = join(os.homedir(), LOCK_DIR_NAME);
+  const path = lockPathFor(port);
+  const payload = JSON.stringify({
+    pid: process.pid,
+    port,
+    startedAt: new Date().toISOString()
+  });
+  mkdirSync(dir, {
+    recursive: true,
+    mode: LOCK_DIR_MODE
+  });
+
+  // Fast path: atomic exclusive create.
+  try {
+    writeFileSync(path, payload, {
+      flag: 'wx',
+      mode: LOCK_FILE_MODE
+    });
+    return {
+      path,
+      payload
+    };
+  } catch (err) {
+    /* istanbul ignore if: any non-EEXIST error from `wx` is unexpected
+       (e.g. EACCES on a read-only $HOME) — propagate. */
+    if (err.code !== 'EEXIST') throw err;
+  }
+
+  // Lock exists. Inspect, then either refuse or reclaim once.
+  let existing;
+  try {
+    existing = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch (parseErr) {
+    // Corrupt or truncated payload (a previous process was killed
+    // mid-write): treat as stale, unlink, and retry.
+    existing = null;
+  }
+
+  // A lock recorded with OUR pid means we leaked a previous lock from
+  // the same process (e.g., a test that forgot to release in afterEach,
+  // or a code path that bypassed the normal stop). Reclaiming is safe
+  // because we are that process — we cannot conflict with ourselves.
+  if (existing && existing.pid !== process.pid && livenessCheck(existing.pid) === 'alive') {
+    throw new LockHeldError(existing, path);
+  }
+
+  // Stale (or corrupt). Unlink and retry exclusive create. If a third
+  // process raced in and won, the second `wx` fails with EEXIST and
+  // we surface their info — their lock is the legitimate one.
+  try {
+    unlinkSync(path);
+  } catch (e) {
+    /* istanbul ignore next: race window — another reclaimer beat us
+       to the unlink. */
+    if (e.code !== 'ENOENT') throw e;
+  }
+  try {
+    writeFileSync(path, payload, {
+      flag: 'wx',
+      mode: LOCK_FILE_MODE
+    });
+    return {
+      path,
+      payload
+    };
+  } catch (err) {
+    /* istanbul ignore next: race-loser branch — between our unlink
+       and the second wx-create, another reclaimer wins. The unit
+       tests for SC4 and SC3 cover the deterministic refuse/reclaim
+       paths; reproducing this true race in a unit test is unreliable
+       under nyc. The behavior simply maps the EEXIST to the same
+       LockHeldError our first wx-failure path already produces. */
+    if (err.code === 'EEXIST') {
+      // Defensive JSON.parse: the race winner could be mid-write
+      // (truncated bytes) or have already crashed (empty file). A
+      // bare JSON.parse here would surface as a SyntaxError instead
+      // of a graceful LockHeldError. Mirror the same try/catch the
+      // earlier stale-lock read uses.
+      let winner;
+      try {
+        winner = JSON.parse(readFileSync(path, 'utf-8'));
+      } catch {
+        winner = {
+          pid: '?',
+          port,
+          startedAt: 'unknown'
+        };
+      }
+      throw new LockHeldError(winner, path);
+    }
+    /* istanbul ignore next: surfaces non-EEXIST fs errors (EACCES,
+       ENOSPC, etc.) that aren't producible in unit tests. */
+    throw err;
+  }
+}
+
+// Synchronous release for use in normal teardown AND in
+// `process.on('exit')` (which only runs synchronous handlers).
+//
+// This must NEVER throw — it runs in the `'exit'` callback chain
+// where any thrown error becomes a process-exit-time crash. In
+// particular, when Jasmine tests spy on fs.unlinkSync via mockfs
+// and then tear down on process exit, the spy's `originalFn` may
+// already be undefined and raise a TypeError. Swallow everything
+// except ENOENT-equivalents and treat the lock as released
+// best-effort.
+export function releaseLockSync(handle) {
+  if (!(handle !== null && handle !== void 0 && handle.path)) return;
+  try {
+    unlinkSync(handle.path);
+  } catch (e) {
+    /* istanbul ignore next: best-effort cleanup — the file is gone
+       (ENOENT), or the surrounding test runtime has already torn
+       down its fs spies (TypeError on `originalFn`). Either way the
+       lock is released from our perspective. */
+    if ((e === null || e === void 0 ? void 0 : e.code) !== 'ENOENT') {
+      // Suppress; do not throw out of an `exit` handler.
+    }
+  }
+}

package/dist/network.js

@@ -1,12 +1,19 @@
 import { request as makeRequest } from '@percy/client/utils';
 import logger from '@percy/logger';
 import mime from 'mime-types';
-import { DefaultMap, createResource, hostnameMatches, normalizeURL, waitFor, decodeAndEncodeURLWithLogging, handleIncorrectFontMimeType, executeDomainValidation } from './utils.js';
+import { AbortError, DefaultMap, createResource, hostnameMatches, normalizeURL, waitFor, decodeAndEncodeURLWithLogging, handleIncorrectFontMimeType, executeDomainValidation } from './utils.js';
 const MAX_RESOURCE_SIZE = 25 * 1024 ** 2 * 0.63; // 25MB, 0.63 factor for accounting for base64 encoding
 const ALLOWED_STATUSES = [200, 201, 301, 302, 304, 307, 308];
 const ALLOWED_RESOURCES = ['Document', 'Stylesheet', 'Image', 'Media', 'Font', 'Other'];
 const ABORTED_MESSAGE = 'Request was aborted by browser';
 
+// Stable, machine-readable codes for abort errors thrown from this module.
+// Consumers should prefer `error.code` over string matching on `error.message`.
+export const AbortCodes = Object.freeze({
+  ABORTED: 'ABORTED',
+  TIMEOUT_NETWORK_IDLE: 'TIMEOUT_NETWORK_IDLE'
+});
+
 // RequestLifeCycleHandler handles life cycle of a requestId
 // Ideal flow:          requestWillBeSent -> requestPaused -> responseReceived -> loadingFinished / loadingFailed
 // ServiceWorker flow:  requestWillBeSent -> responseReceived -> loadingFinished / loadingFailed
@@ -18,11 +25,35 @@ class RequestLifeCycleHandler {
     this.responseReceived = new Promise(resolve => this.resolveResponseReceived = resolve);
   }
 }
+// `Network.TIMEOUT` was a static class field used by
+// some test code (and potentially external SDK consumers) to override
+// the network-idle timeout. It's been replaced by a per-instance
+// `networkIdleWaitTimeout` initialized from PERCY_NETWORK_IDLE_WAIT_TIMEOUT.
+// Keep a static getter/setter shim so external callers reading or
+// writing `Network.TIMEOUT` see a one-time deprecation warning instead
+// of silently dropping their override.
+let _timeoutDeprecationWarned = false;
+
 // The Interceptor class creates common handlers for dealing with intercepting asset requests
 // for a given page using various devtools protocol events and commands.
 export class Network {
-  static TIMEOUT = undefined;
   log = logger('core:discovery');
+
+  /* istanbul ignore next: deprecation shim — kept only for external
+     SDK consumers that read the field. Not reachable from test code. */
+  static get TIMEOUT() {
+    return undefined;
+  }
+
+  /* istanbul ignore next: deprecation shim — exercised only when
+     external callers still write the static field. The shim logs a
+     one-time warning pointing at PERCY_NETWORK_IDLE_WAIT_TIMEOUT. */
+  static set TIMEOUT(_val) {
+    if (!_timeoutDeprecationWarned) {
+      _timeoutDeprecationWarned = true;
+      logger('core:discovery').warn('Network.TIMEOUT is deprecated; set the PERCY_NETWORK_IDLE_WAIT_TIMEOUT ' + 'env var (or pass per-page options) — the static field no longer affects discovery.');
+    }
+  }
   #requestsLifeCycleHandler = new DefaultMap(() => new RequestLifeCycleHandler());
   #pending = new Map();
   #requests = new Map();
@@ -92,11 +123,11 @@ export class Network {
       requests = requests.filter(req => !this.#finishedUrls.has(req.url));
       return requests.length === 0;
     }, {
-      timeout: Network.TIMEOUT,
+      timeout: this.networkIdleWaitTimeout,
       idle: timeout
     }).catch(error => {
       if (error.message.startsWith('Timeout')) {
-        let message = 'Timed out waiting for network requests to idle.';
+        let message = 'Timed out waiting for network requests to idle.\n' + 'Hint: set PERCY_NETWORK_IDLE_WAIT_TIMEOUT to increase the budget, ' + 'or allowlist slow domains via the discovery config.';
         if (captureResponsiveAssetsEnabled) message += '\nWhile capturing responsive assets try setting PERCY_DO_NOT_CAPTURE_RESPONSIVE_ASSETS to true.';
         this._throwTimeoutError(message, filter);
       } else {
@@ -125,7 +156,10 @@ export class Network {
     if (params.requestId) {
       /* istanbul ignore if: race condition, very hard to mock this */
       if (this.isAborted(params.requestId)) {
-        throw new Error(ABORTED_MESSAGE);
+        throw new AbortError(ABORTED_MESSAGE, {
+          code: AbortCodes.ABORTED,
+          reason: 'browser-aborted'
+        });
       }
     }
     return await session.send(method, params);
@@ -151,7 +185,15 @@ export class Network {
       this.log.warn(warnMsg);
       return;
     }
-    throw new Error(msg);
+
+    // Use a plain Error (NOT AbortError) so this does not trip
+    // `error.name === 'AbortError'` consumers in discovery.js:520,
+    // percy.js:347, snapshot.js:472 — those treat AbortError as
+    // "snapshot was aborted" and would silently drop the timeout.
+    let err = new Error(msg);
+    err.code = AbortCodes.TIMEOUT_NETWORK_IDLE;
+    err.reason = 'network-idle-timeout';
+    throw err;
   }
 
   // Called when a request should be removed from various trackers
@@ -410,9 +452,10 @@ export class Network {
     this._forgetRequest(request);
   };
   _initializeNetworkIdleWaitTimeout() {
-    if (Network.TIMEOUT) return;
-    Network.TIMEOUT = parseInt(process.env.PERCY_NETWORK_IDLE_WAIT_TIMEOUT) || 30000;
-    if (Network.TIMEOUT > 60000) {
+    // Per-instance timeout so concurrent pages with different env values
+    // (or env values changed mid-run by tests) don't stomp each other.
+    this.networkIdleWaitTimeout = parseInt(process.env.PERCY_NETWORK_IDLE_WAIT_TIMEOUT) || 30000;
+    if (this.networkIdleWaitTimeout > 60000) {
       this.log.warn('Setting PERCY_NETWORK_IDLE_WAIT_TIMEOUT over 60000ms is not recommended. ' + 'If your page needs more than 60000ms to idle due to CPU/Network load, ' + 'its recommended to increase CI resources where this cli is running.');
     }
   }
@@ -545,7 +588,7 @@ async function sendResponseResource(network, request, session) {
     // Note: its not a necessity that we would get aborted callback in a tick, its just that if we
     // already have it then we can safely ignore this error
     // Its very hard to test it as this function should be called and request should get cancelled before
-    if (error.message === ABORTED_MESSAGE || error.message.includes('Invalid InterceptionId')) {
+    if (error.code === AbortCodes.ABORTED || error.message === ABORTED_MESSAGE || error.message.includes('Invalid InterceptionId')) {
       // defer this to the end of queue to make sure that any incoming aborted messages were
       // handled and network.#aborted is updated
       await new Promise((res, _) => process.nextTick(res));