@applitools/eyes-storybook 3.65.8 → 3.67.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # Changelog
 
+## [3.67.0](https://github.com/Applitools-Dev/sdk/compare/js/eyes-storybook@3.66.0...js/eyes-storybook@3.67.0) (2026-06-28)
+
+
+### Features
+
+* per-phase timing in the summary event | AD-14515 ([#3942](https://github.com/Applitools-Dev/sdk/issues/3942)) ([3704a6d](https://github.com/Applitools-Dev/sdk/commit/3704a6d60f07e4338f3d0c5fa1589baf89b45080))
+
+
+### Dependencies
+
+* @applitools/utils bumped to 1.15.1
+  #### Bug Fixes
+
+  * updated extract git fallback logic | FLD-4492 ([#3831](https://github.com/Applitools-Dev/sdk/issues/3831)) ([0d98f3c](https://github.com/Applitools-Dev/sdk/commit/0d98f3cdf828eff756ffbfc5d4cdff7b19a20557))
+* @applitools/logger bumped to 2.3.0
+  #### Features
+
+  * stream SDK logs to Azure Blob per server flag | AD-13401 ([#3849](https://github.com/Applitools-Dev/sdk/issues/3849)) ([7f9dfec](https://github.com/Applitools-Dev/sdk/commit/7f9dfecd874aefc33104db015451a22eee500324))
+
+
+
+* @applitools/core-base bumped to 1.36.0
+  #### Features
+
+  * stream SDK logs to Azure Blob per server flag | AD-13401 ([#3849](https://github.com/Applitools-Dev/sdk/issues/3849)) ([7f9dfec](https://github.com/Applitools-Dev/sdk/commit/7f9dfecd874aefc33104db015451a22eee500324))
+
+
+
+* @applitools/dom-snapshot bumped to 4.17.5
+
+* @applitools/socket bumped to 1.3.15
+
+* @applitools/req bumped to 1.11.2
+
+* @applitools/image bumped to 1.2.13
+
+* @applitools/dom-capture bumped to 11.8.3
+
+* @applitools/driver bumped to 1.26.5
+
+* @applitools/spec-driver-webdriver bumped to 1.6.5
+
+* @applitools/spec-driver-selenium bumped to 1.8.5
+
+* @applitools/spec-driver-playwright bumped to 1.9.5
+
+* @applitools/spec-driver-puppeteer bumped to 1.8.5
+
+* @applitools/screenshoter bumped to 3.12.24
+
+* @applitools/nml-client bumped to 1.11.34
+
+* @applitools/tunnel-client bumped to 1.12.2
+
+* @applitools/ufg-client bumped to 1.22.5
+
+* @applitools/ec-client bumped to 1.12.36
+
+* @applitools/core bumped to 4.66.0
+  #### Features
+
+  * stream SDK logs to Azure Blob per server flag | AD-13401 ([#3849](https://github.com/Applitools-Dev/sdk/issues/3849)) ([7f9dfec](https://github.com/Applitools-Dev/sdk/commit/7f9dfecd874aefc33104db015451a22eee500324))
+
+
+  #### Bug Fixes
+
+  * updated extract git fallback logic | FLD-4492 ([#3831](https://github.com/Applitools-Dev/sdk/issues/3831)) ([0d98f3c](https://github.com/Applitools-Dev/sdk/commit/0d98f3cdf828eff756ffbfc5d4cdff7b19a20557))
+
+
+
+* @applitools/eyes bumped to 1.43.5
+
+* @applitools/test-server bumped to 1.4.6
+
+
+## [3.66.0](https://github.com/Applitools-Dev/sdk/compare/js/eyes-storybook@3.65.8...js/eyes-storybook@3.66.0) (2026-06-18)
+
+
+### Features
+
+* one-time per-execution summary logEvent in storybook | AD-14305 ([#3911](https://github.com/Applitools-Dev/sdk/issues/3911)) ([59e3a5d](https://github.com/Applitools-Dev/sdk/commit/59e3a5dccf74aa1ac1158024316bd305e3515afa))
+
+
+### Dependencies
+
+* @applitools/utils bumped to 1.15.0
+  #### Features
+
+  * one-time per-execution summary logEvent in storybook | AD-14305 ([#3911](https://github.com/Applitools-Dev/sdk/issues/3911)) ([59e3a5d](https://github.com/Applitools-Dev/sdk/commit/59e3a5dccf74aa1ac1158024316bd305e3515afa))
+* @applitools/req bumped to 1.11.1
+  #### Bug Fixes
+
+  * bundle node-fetch into dist to drop node-domexception dep warning | FLD-4197 ([#3899](https://github.com/Applitools-Dev/sdk/issues/3899)) ([9c3dc52](https://github.com/Applitools-Dev/sdk/commit/9c3dc52866a4a665f1578c39ff43cd0ee5f63492))
+
+
+
+* @applitools/logger bumped to 2.2.13
+
+* @applitools/dom-snapshot bumped to 4.17.4
+
+* @applitools/socket bumped to 1.3.14
+
+* @applitools/image bumped to 1.2.12
+
+* @applitools/dom-capture bumped to 11.8.2
+
+* @applitools/driver bumped to 1.26.4
+
+* @applitools/spec-driver-webdriver bumped to 1.6.4
+
+* @applitools/spec-driver-selenium bumped to 1.8.4
+
+* @applitools/spec-driver-playwright bumped to 1.9.4
+
+* @applitools/spec-driver-puppeteer bumped to 1.8.4
+
+* @applitools/screenshoter bumped to 3.12.23
+
+* @applitools/nml-client bumped to 1.11.33
+
+* @applitools/tunnel-client bumped to 1.12.1
+
+* @applitools/ufg-client bumped to 1.22.4
+
+* @applitools/core-base bumped to 1.35.3
+
+* @applitools/ec-client bumped to 1.12.35
+
+* @applitools/core bumped to 4.65.2
+
+* @applitools/eyes bumped to 1.43.4
+
+* @applitools/test-server bumped to 1.4.5
+
+
 ## [3.65.8](https://github.com/Applitools-Dev/sdk/compare/js/eyes-storybook@3.65.7...js/eyes-storybook@3.65.8) (2026-06-15)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/eyes-storybook",
-  "version": "3.65.8",
+  "version": "3.67.0",
   "description": "",
   "keywords": [
     "applitools",
@@ -36,6 +36,7 @@
     "test:it": "run --top-level mocha 'test/it/*.test.js'",
     "test:versions": "yarn build && yarn test:e2e:versions && yarn lint",
     "test:e2e": "MOCHA_GROUP=e2e run --top-level mocha 'test/e2e/*.e2e.test.js' --require ./test/mocha-global-setup.js",
+    "test:performance-logs": "MOCHA_GROUP=performance_logs run --top-level mocha 'test/e2e/execution-summary-event.e2e.test.js' --require ./test/mocha-global-setup.js --exit",
     "test:e2e:versions": "MOCHA_GROUP=e2e_versions run --top-level mocha test/versions/*.e2e.versions.test.js",
     "test:sanity": "run --top-level mocha 'test/sanity/*.test.js'",
     "test:heavy": "node bin/eyes-storybook.js -f test/fixtures/heavyStorybook/applitools.config.js",
@@ -59,15 +60,15 @@
     "up:framework": "cd test/fixtures/storybook-versions/${APPLITOOLS_FRAMEWORK_VERSION} && npm ci"
   },
   "dependencies": {
-    "@applitools/core": "4.65.1",
-    "@applitools/driver": "1.26.3",
-    "@applitools/eyes": "1.43.3",
+    "@applitools/core": "4.66.0",
+    "@applitools/driver": "1.26.5",
+    "@applitools/eyes": "1.43.5",
     "@applitools/functional-commons": "1.6.0",
-    "@applitools/logger": "2.2.12",
+    "@applitools/logger": "2.3.0",
     "@applitools/monitoring-commons": "1.0.19",
-    "@applitools/spec-driver-puppeteer": "1.8.3",
-    "@applitools/ufg-client": "1.22.3",
-    "@applitools/utils": "1.14.5",
+    "@applitools/spec-driver-puppeteer": "1.8.5",
+    "@applitools/ufg-client": "1.22.5",
+    "@applitools/utils": "1.15.1",
     "@inquirer/prompts": "7.0.1",
     "boxen": "4.2.0",
     "chalk": "3.0.0",
@@ -83,7 +84,7 @@
   "devDependencies": {
     "@applitools/bongo": "^5.10.0",
     "@applitools/snaptdout": "^1.1.1",
-    "@applitools/test-server": "^1.4.4",
+    "@applitools/test-server": "^1.4.6",
     "@applitools/test-utils": "^1.5.17",
     "@storybook/addon-interactions": "^6.4.18",
     "@storybook/react": "^6.5.16",
@@ -117,6 +118,7 @@
       "core-js": false,
       "puppeteer": true,
       "@storybook/react>core-js": false,
+      "@storybook/react>@storybook/core-common>webpack>watchpack>watchpack-chokidar2>chokidar>fsevents": false,
       "@applitools/ufg-client>@applitools/image>sharp": false,
       "puppeteer>puppeteer-core>ws>bufferutil": false,
       "puppeteer>puppeteer-core>ws>utf-8-validate": false

package/src/buildExecutionSummaryEvent.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// Credentials/connection details that must never be sent to Coralogix. Everything else in
+// the config (puppeteerOptions, hooks, flags, ...) is reported as-is.
+const SETTINGS_DENY_LIST = ['apiKey', 'proxy', 'eyesServerUrl', 'serverUrl', 'accessKey'];
+
+function pickSettings(config = {}) {
+  const flags = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (!SETTINGS_DENY_LIST.includes(key)) flags[key] = value;
+  }
+  return flags;
+}
+
+/**
+ * Assemble the one-time per-execution summary event payload. Pure function — all
+ * inputs are plain data; never throws on missing fields (best-effort observability).
+ */
+function buildExecutionSummaryEvent({
+  status, // 'finished' | 'failed' | 'aborted'
+  config = {},
+  environment = {},
+  account = {},
+  concurrentTabs,
+  counts = {},
+  summary, // TestResultSummary | undefined
+  metrics = {}, // runMetrics.summarize()
+  totalRunMs,
+  renderStoriesMs,
+}) {
+  // keep the scalar counts (passed/failed/unresolved/...); drop the large per-test `results` array
+  let tests;
+  if (summary) {
+    tests = {...summary};
+    delete tests.results;
+  }
+
+  return {
+    type: 'eyesStorybookExecutionFinished',
+    status,
+    sdkVersion: environment.sdk?.currentVersion,
+    addonVersion: environment.sdk?.addonVersion,
+    storybookVersion: config.sbVersion || environment.versions?.storybook,
+    framework: environment.sdk?.framework,
+    counts: {
+      totalStories: counts.totalStories,
+      afterFilter: counts.afterFilter,
+      afterVariations: counts.afterVariations,
+      normal: counts.normal,
+      fakeIE: counts.fakeIE,
+      tests,
+    },
+    timing: {
+      totalRunMs,
+      renderStoriesMs,
+      perStoryTotalMs: metrics.timing?.perStoryTotalMs,
+      snapshotMs: metrics.timing?.snapshotMs,
+      openMs: metrics.timing?.openMs,
+      checkAndCloseMs: metrics.timing?.checkAndCloseMs,
+    },
+    memory: metrics.memory,
+    tabs: {
+      concurrentTabs,
+      crashed: metrics.tabs?.tabsCrashed,
+      replaced: metrics.tabs?.tabsReplaced,
+    },
+    settings: {
+      componentConcurrency: account.serverConcurrency?.componentConcurrency,
+      concurrentTabs,
+      flags: pickSettings(config),
+    },
+  };
+}
+
+module.exports = {buildExecutionSummaryEvent, pickSettings, SETTINGS_DENY_LIST};

package/src/eyesStorybook.js

@@ -26,6 +26,8 @@ const {makeCore} = require('@applitools/core');
 const makeGetStoriesWithConfig = require('./getStoriesWithConfig');
 const {makeNetworkUtils} = require('./utils/pageNetworkUtils');
 const {readStoriesTimeout: defaultReadStoriesTimeout} = require('./defaultConfig');
+const {makeRunMetrics} = require('./runMetrics');
+const {buildExecutionSummaryEvent} = require('./buildExecutionSummaryEvent');
 
 async function eyesStorybook({
   config,
@@ -43,6 +45,11 @@ async function eyesStorybook({
   let transitioning = false;
   logger.log('eyesStorybook started');
 
+  const runStart = Date.now();
+  // Run-scope counts, populated during the pipeline and read by the summary event
+  // even if the run later fails partway through (best-effort observability).
+  const counts = {};
+
   const CONCURRENT_TABS = isNaN(Number(process.env.APPLITOOLS_CONCURRENT_TABS))
     ? 3
     : Number(process.env.APPLITOOLS_CONCURRENT_TABS);
@@ -64,6 +71,11 @@ async function eyesStorybook({
   const browser = await puppeteer.launch(config.puppeteerOptions);
   logger.log('browser launched');
 
+  // Best-effort per-execution metrics (memory / timing / tab reliability). The
+  // sampler is unref'd and every sample is guarded — it can never keep the
+  // process alive or affect the run.
+  const metrics = makeRunMetrics({browser, logger});
+
   const environment = extractEnvironment(addonVersion);
   const core = await makeCore({spec, agentId: config.agentId, environment, logger});
   const manager = await core.makeManager({
@@ -87,6 +99,11 @@ async function eyesStorybook({
       throw error;
     });
 
+  // Start the best-effort metrics sampler only once getAccountInfo has succeeded —
+  // its .catch closes the browser and rethrows without reaching the `finally` that
+  // would otherwise stop the sampler.
+  metrics.start();
+
   const getStoriesWithConfig = makeGetStoriesWithConfig({config});
 
   const initPage = makeInitPage({
@@ -96,8 +113,72 @@ async function eyesStorybook({
     logger,
     getTransitiongIntoIE,
     getRenderIE,
+    onTabCrashed: metrics.incrementTabsCrashed,
+  });
+  const pagePool = createPagePool({
+    initPage,
+    logger,
+    onPageReplaced: metrics.incrementTabsReplaced,
   });
-  const pagePool = createPagePool({initPage, logger});
+
+  let summaryEmitted = false;
+  let runStatus = 'finished';
+  let resultSummary;
+
+  // Emit the one-time per-execution summary event (-> Coralogix). Best-effort and
+  // idempotent: awaited so the batched logEvent actually flushes + sends before we
+  // exit, guarded so we never double-send, and fully swallowed on failure so it can
+  // never affect the run's outcome.
+  async function emitExecutionSummary(status, summary) {
+    if (summaryEmitted) return;
+    summaryEmitted = true;
+    try {
+      await metrics.stop(); // final sample while the browser is still alive
+      const event = buildExecutionSummaryEvent({
+        status,
+        config,
+        environment,
+        account,
+        concurrentTabs: CONCURRENT_TABS,
+        counts,
+        summary,
+        metrics: metrics.summarize(),
+        totalRunMs: Date.now() - runStart,
+        renderStoriesMs: performance['renderStories'],
+      });
+      logger.log('eyesStorybook sending execution summary event', event);
+      await core.logEvent({
+        settings: {
+          eyesServerUrl: config.eyesServerUrl,
+          apiKey: config.apiKey,
+          agentId: config.agentId,
+          proxy: config.proxy,
+          useDnsCache: config.useDnsCache,
+          level: 'Notice',
+          event,
+        },
+        logger,
+      });
+    } catch (err) {
+      logger.log('failed to emit execution summary event:', err && err.message);
+    }
+  }
+
+  // process 'exit' is synchronous-only and cannot perform the async, batched HTTP
+  // send — so cover hard terminations with signal handlers (which CAN run async).
+  // Registered now and removed in `finally` so we never leak a listener.
+  const makeSignalHandler = signalName => async () => {
+    logger.log(`eyesStorybook received ${signalName}, emitting summary before exit`);
+    await emitExecutionSummary('aborted', resultSummary);
+    process.exit(1);
+  };
+  const signalHandlers = {
+    SIGINT: makeSignalHandler('SIGINT'),
+    SIGTERM: makeSignalHandler('SIGTERM'),
+  };
+  for (const [signalName, handler] of Object.entries(signalHandlers)) {
+    process.once(signalName, handler);
+  }
 
   try {
     const {stories, page} = await getStoriesWithSpinner();
@@ -121,6 +202,8 @@ async function eyesStorybook({
     });
 
     const filteredStories = filterStories({stories, config});
+    counts.totalStories = stories.length;
+    counts.afterFilter = filteredStories.length;
 
     // Log filtering and sharding results
     logger.log(`${stories.length} total stories found`);
@@ -141,10 +224,14 @@ async function eyesStorybook({
       `there are ${storiesIncludingVariations.length} stories after filtering and adding variations `,
     );
 
+    counts.afterVariations = storiesIncludingVariations.length;
+
     const storiesByBrowserWithConfig = getStoriesWithConfig({
       stories: storiesIncludingVariations,
       logger,
     });
+    counts.normal = storiesByBrowserWithConfig.stories.length;
+    counts.fakeIE = storiesByBrowserWithConfig.storiesWithIE.length;
 
     logger.log(
       `starting to run ${storiesByBrowserWithConfig.stories.length} normal stories ("non fake IE") and ${storiesByBrowserWithConfig.storiesWithIE.length} "fake IE stories"`,
@@ -166,6 +253,8 @@ async function eyesStorybook({
       appName: config.appName,
       serverSettings: account.eyesServer,
       signal,
+      recordOpenTime: metrics.recordOpenTime,
+      recordCheckAndCloseTime: metrics.recordCheckAndCloseTime,
     });
 
     const renderStories = makeRenderStories({
@@ -178,6 +267,8 @@ async function eyesStorybook({
       pagePool,
       eventEmitter,
       signal,
+      recordStoryTime: metrics.recordStoryTime,
+      recordSnapshotTime: metrics.recordSnapshotTime,
     });
 
     logger.log('finished creating functions');
@@ -196,6 +287,7 @@ async function eyesStorybook({
       }),
     );
     if (signal.aborted) {
+      runStatus = 'aborted';
       if (error) {
         const msg = refineErrorMessage({prefix: 'Error in executeRenders:', error});
         logger.log('Error in executeRenders:', error);
@@ -211,17 +303,27 @@ async function eyesStorybook({
     if (errorInGetResults) {
       logger.log('failed to get results', errorInGetResults);
     }
+    resultSummary = testResultsSummary;
 
     if (error) {
+      runStatus = 'failed';
       const msg = refineErrorMessage({prefix: 'Error in executeRenders:', error});
       logger.log('Error in executeRenders:', error);
       throw new Error(msg);
     } else {
       return {summary: testResultsSummary, results};
     }
+  } catch (err) {
+    if (runStatus === 'finished') runStatus = 'failed';
+    throw err;
   } finally {
     logger.log('total time: ', performance['renderStories']);
     logger.log('perf results', performance);
+    // emit BEFORE closing the browser so the final memory sample is still valid
+    await emitExecutionSummary(runStatus, resultSummary);
+    for (const [signalName, handler] of Object.entries(signalHandlers)) {
+      process.removeListener(signalName, handler);
+    }
     pagePool.isClosed = true;
     await browser.close();
   }

package/src/initPage.js

@@ -4,7 +4,15 @@ const fakeIE = require('./fakeIE');
 const {makeNetworkUtils} = require('./utils/pageNetworkUtils');
 const utils = require('@applitools/utils');
 
-function makeInitPage({iframeUrl, config, browser, logger, getTransitiongIntoIE, getRenderIE}) {
+function makeInitPage({
+  iframeUrl,
+  config,
+  browser,
+  logger,
+  getTransitiongIntoIE,
+  getRenderIE,
+  onTabCrashed = () => {},
+}) {
   const networkUtils = makeNetworkUtils({logger});
   return async function initPage({pageId, pagePool}) {
     logger.log('initializing puppeteer page number ', pageId);
@@ -60,6 +68,7 @@ function makeInitPage({iframeUrl, config, browser, logger, getTransitiongIntoIE,
 
     page.on('error', async err => {
       logger.log(`Puppeteer error for page ${pageId}:`, err);
+      onTabCrashed(); // best-effort metric; the 'error' event is Chromium "Page crashed!"
       await pagePool.removeAndAddPage(pageId);
     });
 

package/src/pagePool.js

@@ -1,6 +1,6 @@
 'use strict';
 
-function createPagePool({initPage, logger, freePageTimeout = 300_000}) {
+function createPagePool({initPage, logger, freePageTimeout = 300_000, onPageReplaced = () => {}}) {
   let counter = 0;
   const fullPageObjs = [];
   logger.log(`[page pool] created`);
@@ -43,6 +43,7 @@ function createPagePool({initPage, logger, freePageTimeout = 300_000}) {
   return pagePool;
 
   async function removeAndAddPage(pageId) {
+    onPageReplaced(); // best-effort metric: a pooled tab was torn down and replaced
     pagePool.removePage(pageId);
     const {pageId: newPageId} = await pagePool.createPage();
     pagePool.addToPool(newPageId);

package/src/renderStories.js

@@ -17,6 +17,8 @@ function makeRenderStories({
   maxPageTTL = 60000,
   eventEmitter = new EventEmitter(),
   signal = new AbortController().signal,
+  recordStoryTime = () => {},
+  recordSnapshotTime = () => {},
 }) {
   const sparePages = {
     queue: [],
@@ -142,7 +144,11 @@ function makeRenderStories({
         const story = stories[currIndex++];
         const storyUrl = getStoryUrl(story, storybookUrl);
         const title = getStoryBaselineName(story);
+        // measure the FULL per-story chain (snapshot + open + checkAndClose),
+        // unlike performance[baselineName] which covers only open + checkAndClose.
+        const storyStart = Date.now();
         try {
+          const snapshotStart = Date.now();
           let [error, storyData] = await presult(
             getStoryData({
               story,
@@ -151,6 +157,7 @@ function makeRenderStories({
               pageId,
             }),
           );
+          recordSnapshotTime(Date.now() - snapshotStart);
 
           if (
             error &&
@@ -202,6 +209,8 @@ function makeRenderStories({
         } catch (ex) {
           logger.log(`[page ${pageId}] error while processing story "${title}". ${ex}`);
           return onDoneStory(ex, story);
+        } finally {
+          recordStoryTime(Date.now() - storyStart);
         }
       }
     }

package/src/renderStory.js

@@ -14,6 +14,8 @@ function makeRenderStory({
   serverSettings,
   concurrency,
   signal = new AbortController().signal,
+  recordOpenTime = () => {},
+  recordCheckAndCloseTime = () => {},
 }) {
   const throttle = throat(storyDataGap);
   return function renderStory({story, snapshots, url}) {
@@ -26,7 +28,9 @@ function makeRenderStory({
     const checkParams = storyToCheckSettings({story, url});
 
     return timeItAsync(baselineName, async () => {
+      const openStart = Date.now();
       const eyes = await openEyes({settings: openParams});
+      recordOpenTime(Date.now() - openStart);
       return new Promise(async (resolve, reject) => {
         if (signal.aborted) {
           return await abortStory();
@@ -36,11 +40,13 @@ function makeRenderStory({
         throttle(async () => {
           try {
             if (snapshots) {
+              const checkStart = Date.now();
               await eyes.checkAndClose({
                 target: snapshots,
                 settings: checkParams,
               });
               const results = await eyes.getResults();
+              recordCheckAndCloseTime(Date.now() - checkStart);
               resolve(results);
             } else {
               await eyes.abort({settings: {environments: checkParams.environments}});

package/src/runMetrics.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const utils = require('@applitools/utils');
+
+// Collects per-execution metrics for the one-time summary logEvent (-> Coralogix).
+//
+// Everything here is ADDITIVE observability and best-effort: a failure to sample
+// any metric is swallowed (logged at debug) and the run is unaffected. The memory
+// sampler runs on an interval that is `.unref()`'d so it can NEVER keep the
+// process alive past the end of a run.
+
+const SAMPLE_INTERVAL_MS = 2000;
+
+function makeStats() {
+  const samples = [];
+  return {
+    add(n) {
+      if (typeof n === 'number' && Number.isFinite(n)) samples.push(n);
+    },
+    summary() {
+      if (samples.length === 0) return null;
+      const sorted = [...samples].sort((a, b) => a - b);
+      const n = sorted.length;
+      const sum = sorted.reduce((a, b) => a + b, 0);
+      const mid = Math.floor(n / 2);
+      return {
+        min: sorted[0],
+        max: sorted[n - 1],
+        avg: Math.round(sum / n),
+        median: n % 2 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2),
+        p95: sorted[Math.ceil(n * 0.95) - 1],
+        samples: n,
+      };
+    },
+  };
+}
+
+/**
+ * @param {object} options
+ * @param {import('puppeteer').Browser} [options.browser]
+ * @param {{log: Function}} options.logger
+ */
+function makeRunMetrics({browser, logger} = {}) {
+  const nodeRss = makeStats();
+  const nodeHeapUsed = makeStats();
+  const browserTreeRss = makeStats();
+  const perStoryTotalMs = makeStats();
+  const snapshotMs = makeStats();
+  const openMs = makeStats();
+  const checkAndCloseMs = makeStats();
+  const counters = {tabsCrashed: 0, tabsReplaced: 0};
+
+  let timer;
+  let sampling = false;
+  let browserPid;
+  let started = false;
+
+  function start() {
+    if (started) return;
+    started = true;
+    try {
+      browserPid = browser?.process?.()?.pid;
+    } catch (err) {
+      logger?.log(`[metrics] could not resolve browser pid: ${err?.message}`);
+    }
+    // immediate first sample, then on interval
+    void sampleOnce();
+    timer = setInterval(() => void sampleOnce(), SAMPLE_INTERVAL_MS);
+    // never let the metrics sampler keep the process alive
+    timer.unref?.();
+  }
+
+  async function sampleOnce() {
+    // node memory — synchronous, always cheap, always safe
+    try {
+      const mem = process.memoryUsage();
+      nodeRss.add(mem.rss);
+      nodeHeapUsed.add(mem.heapUsed);
+    } catch (err) {
+      logger?.log(`[metrics] node memory sample failed: ${err?.message}`);
+    }
+    // browser process-tree memory — async, may be unavailable; skip if a previous
+    // browser sample is still in flight to avoid pile-up on slow platforms.
+    if (sampling || !browserPid) return;
+    sampling = true;
+    try {
+      const bytes = await utils.process.sampleProcessTreeMemory(browserPid, {logger});
+      if (typeof bytes === 'number') browserTreeRss.add(bytes);
+    } catch (err) {
+      logger?.log(`[metrics] browser memory sample failed: ${err?.message}`);
+    } finally {
+      sampling = false;
+    }
+  }
+
+  function recordStoryTime(ms) {
+    perStoryTotalMs.add(ms);
+  }
+
+  function recordSnapshotTime(ms) {
+    snapshotMs.add(ms);
+  }
+
+  function recordOpenTime(ms) {
+    openMs.add(ms);
+  }
+
+  function recordCheckAndCloseTime(ms) {
+    checkAndCloseMs.add(ms);
+  }
+
+  function incrementTabsCrashed() {
+    counters.tabsCrashed += 1;
+  }
+
+  function incrementTabsReplaced() {
+    counters.tabsReplaced += 1;
+  }
+
+  // Stop sampling and take one final sample. Idempotent.
+  async function stop() {
+    if (timer) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+    await sampleOnce();
+  }
+
+  function summarize() {
+    return {
+      memory: {
+        nodeRssBytes: nodeRss.summary(),
+        nodeHeapUsedBytes: nodeHeapUsed.summary(),
+        browserTreeRssBytes: browserTreeRss.summary(),
+      },
+      timing: {
+        perStoryTotalMs: perStoryTotalMs.summary(),
+        snapshotMs: snapshotMs.summary(),
+        openMs: openMs.summary(),
+        checkAndCloseMs: checkAndCloseMs.summary(),
+      },
+      tabs: {...counters},
+    };
+  }
+
+  return {
+    start,
+    stop,
+    recordStoryTime,
+    recordSnapshotTime,
+    recordOpenTime,
+    recordCheckAndCloseTime,
+    incrementTabsCrashed,
+    incrementTabsReplaced,
+    summarize,
+  };
+}
+
+module.exports = {makeRunMetrics, makeStats};