@mtharrison/pkg-profiler 1.1.0 → 2.0.0

package/dist/index.cjs

@@ -1,9 +1,139 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-let node_inspector_promises = require("node:inspector/promises");
-let node_url = require("node:url");
 let node_fs = require("node:fs");
+let node_inspector = require("node:inspector");
 let node_path = require("node:path");
+let node_async_hooks = require("node:async_hooks");
+let node_url = require("node:url");
 
+//#region src/async-tracker.ts
+/**
+* Opt-in async I/O wait time tracker using node:async_hooks.
+*
+* Tracks the time between async resource init (when the I/O op is started)
+* and the first before callback (when the callback fires), attributing
+* that wait time to the package/file/function that initiated the operation.
+*/
+/** Async resource types worth tracking — I/O and timers, not promises. */
+const TRACKED_TYPES = new Set([
+	"TCPCONNECTWRAP",
+	"TCPWRAP",
+	"PIPEWRAP",
+	"PIPECONNECTWRAP",
+	"TLSWRAP",
+	"FSREQCALLBACK",
+	"FSREQPROMISE",
+	"GETADDRINFOREQWRAP",
+	"GETNAMEINFOREQWRAP",
+	"HTTPCLIENTREQUEST",
+	"HTTPINCOMINGMESSAGE",
+	"SHUTDOWNWRAP",
+	"WRITEWRAP",
+	"ZLIB",
+	"Timeout"
+]);
+/**
+* Parse a single line from an Error().stack trace into file path and function id.
+* Returns null for lines that don't match V8's stack frame format or are node internals.
+*
+* Handles these V8 formats:
+*   "    at functionName (/absolute/path:line:col)"
+*   "    at /absolute/path:line:col"
+*   "    at Object.functionName (/absolute/path:line:col)"
+*/
+function parseStackLine(line) {
+	const match = line.match(/^\s+at\s+(?:(.+?)\s+\()?(.+?):(\d+):\d+\)?$/);
+	if (!match) return null;
+	const rawFn = match[1] ?? "";
+	const filePath = match[2];
+	const lineNum = match[3];
+	if (filePath.startsWith("node:") || filePath.startsWith("<")) return null;
+	const fnParts = rawFn.split(".");
+	return {
+		filePath,
+		functionId: `${fnParts[fnParts.length - 1] || "<anonymous>"}:${lineNum}`
+	};
+}
+var AsyncTracker = class {
+	resolver;
+	store;
+	thresholdUs;
+	hook = null;
+	pending = /* @__PURE__ */ new Map();
+	/**
+	* @param resolver - PackageResolver for mapping file paths to packages
+	* @param store - SampleStore to record async wait times into
+	* @param thresholdUs - Minimum wait duration in microseconds to record (default 1000 = 1ms)
+	*/
+	constructor(resolver, store, thresholdUs = 1e3) {
+		this.resolver = resolver;
+		this.store = store;
+		this.thresholdUs = thresholdUs;
+	}
+	enable() {
+		if (this.hook) return;
+		this.hook = (0, node_async_hooks.createHook)({
+			init: (asyncId, type) => {
+				if (!TRACKED_TYPES.has(type)) return;
+				const holder = {};
+				const origLimit = Error.stackTraceLimit;
+				Error.stackTraceLimit = 8;
+				Error.captureStackTrace(holder);
+				Error.stackTraceLimit = origLimit;
+				const stack = holder.stack;
+				if (!stack) return;
+				const lines = stack.split("\n");
+				let parsed = null;
+				for (let i = 1; i < lines.length; i++) {
+					const result = parseStackLine(lines[i]);
+					if (result) {
+						if (result.filePath.includes("async-tracker")) continue;
+						parsed = result;
+						break;
+					}
+				}
+				if (!parsed) return;
+				const { packageName, relativePath } = this.resolver.resolve(parsed.filePath);
+				this.pending.set(asyncId, {
+					startHrtime: process.hrtime(),
+					pkg: packageName,
+					file: relativePath,
+					fn: parsed.functionId
+				});
+			},
+			before: (asyncId) => {
+				const op = this.pending.get(asyncId);
+				if (!op) return;
+				const elapsed = process.hrtime(op.startHrtime);
+				const durationUs = elapsed[0] * 1e6 + Math.round(elapsed[1] / 1e3);
+				if (durationUs >= this.thresholdUs) this.store.record(op.pkg, op.file, op.fn, durationUs);
+				this.pending.delete(asyncId);
+			},
+			destroy: (asyncId) => {
+				this.pending.delete(asyncId);
+			}
+		});
+		this.hook.enable();
+	}
+	disable() {
+		if (!this.hook) return;
+		this.hook.disable();
+		const now = process.hrtime();
+		for (const [, op] of this.pending) {
+			let secs = now[0] - op.startHrtime[0];
+			let nanos = now[1] - op.startHrtime[1];
+			if (nanos < 0) {
+				secs -= 1;
+				nanos += 1e9;
+			}
+			const durationUs = secs * 1e6 + Math.round(nanos / 1e3);
+			if (durationUs >= this.thresholdUs) this.store.record(op.pkg, op.file, op.fn, durationUs);
+		}
+		this.pending.clear();
+		this.hook = null;
+	}
+};
+
+//#endregion
 //#region src/frame-parser.ts
 /**
 * Classify a V8 CPU profiler call frame and convert its URL to a filesystem path.
@@ -12,6 +142,9 @@ let node_path = require("node:path");
 * It determines the frame kind (user code, internal, eval, wasm) and for user
 * frames converts the URL to a filesystem path and builds a human-readable
 * function identifier.
+*
+* @param frame - Raw call frame from the V8 CPU profiler.
+* @returns A classified frame: `'user'` with file path and function id, or a non-user kind.
 */
 function parseFrame(frame) {
 	const { url, functionName, lineNumber } = frame;
@@ -97,97 +230,6 @@ var PackageResolver = class {
 	}
 };
 
-//#endregion
-//#region src/reporter/aggregate.ts
-const THRESHOLD_PCT = .05;
-/**
-* Aggregate SampleStore data into a ReportData structure.
-*
-* @param store - SampleStore with accumulated microseconds and sample counts
-* @param projectName - Name of the first-party project (for isFirstParty flag)
-* @returns ReportData with packages sorted desc by time, thresholded at 5%
-*/
-function aggregate(store, projectName) {
-	let totalTimeUs = 0;
-	for (const fileMap of store.packages.values()) for (const funcMap of fileMap.values()) for (const us of funcMap.values()) totalTimeUs += us;
-	if (totalTimeUs === 0) return {
-		timestamp: (/* @__PURE__ */ new Date()).toLocaleString(),
-		totalTimeUs: 0,
-		packages: [],
-		otherCount: 0,
-		projectName
-	};
-	const threshold = totalTimeUs * THRESHOLD_PCT;
-	const packages = [];
-	let topLevelOtherCount = 0;
-	for (const [packageName, fileMap] of store.packages) {
-		let packageTimeUs = 0;
-		for (const funcMap of fileMap.values()) for (const us of funcMap.values()) packageTimeUs += us;
-		if (packageTimeUs < threshold) {
-			topLevelOtherCount++;
-			continue;
-		}
-		let packageSampleCount = 0;
-		const countFileMap = store.sampleCountsByPackage.get(packageName);
-		if (countFileMap) for (const countFuncMap of countFileMap.values()) for (const count of countFuncMap.values()) packageSampleCount += count;
-		const files = [];
-		let fileOtherCount = 0;
-		for (const [fileName, funcMap] of fileMap) {
-			let fileTimeUs = 0;
-			for (const us of funcMap.values()) fileTimeUs += us;
-			if (fileTimeUs < threshold) {
-				fileOtherCount++;
-				continue;
-			}
-			let fileSampleCount = 0;
-			const countFuncMap = countFileMap?.get(fileName);
-			if (countFuncMap) for (const count of countFuncMap.values()) fileSampleCount += count;
-			const functions = [];
-			let funcOtherCount = 0;
-			for (const [funcName, funcTimeUs] of funcMap) {
-				if (funcTimeUs < threshold) {
-					funcOtherCount++;
-					continue;
-				}
-				const funcSampleCount = countFuncMap?.get(funcName) ?? 0;
-				functions.push({
-					name: funcName,
-					timeUs: funcTimeUs,
-					pct: funcTimeUs / totalTimeUs * 100,
-					sampleCount: funcSampleCount
-				});
-			}
-			functions.sort((a, b) => b.timeUs - a.timeUs);
-			files.push({
-				name: fileName,
-				timeUs: fileTimeUs,
-				pct: fileTimeUs / totalTimeUs * 100,
-				sampleCount: fileSampleCount,
-				functions,
-				otherCount: funcOtherCount
-			});
-		}
-		files.sort((a, b) => b.timeUs - a.timeUs);
-		packages.push({
-			name: packageName,
-			timeUs: packageTimeUs,
-			pct: packageTimeUs / totalTimeUs * 100,
-			isFirstParty: packageName === projectName,
-			sampleCount: packageSampleCount,
-			files,
-			otherCount: fileOtherCount
-		});
-	}
-	packages.sort((a, b) => b.timeUs - a.timeUs);
-	return {
-		timestamp: (/* @__PURE__ */ new Date()).toLocaleString(),
-		totalTimeUs,
-		packages,
-		otherCount: topLevelOtherCount,
-		projectName
-	};
-}
-
 //#endregion
 //#region src/reporter/format.ts
 /**
@@ -201,6 +243,9 @@ function aggregate(store, projectName) {
 * - < 1s:  shows rounded milliseconds (e.g. "432ms")
 * - Sub-millisecond values round up to 1ms (never shows "0ms" for nonzero input)
 * - Zero returns "0ms"
+*
+* @param us - Time value in microseconds.
+* @returns Human-readable time string.
 */
 function formatTime(us) {
 	if (us === 0) return "0ms";
@@ -212,6 +257,10 @@ function formatTime(us) {
 /**
 * Convert microseconds to percentage of total with one decimal place.
 * Returns "0.0%" when totalUs is zero (avoids division by zero).
+*
+* @param us - Time value in microseconds.
+* @param totalUs - Total time in microseconds (denominator).
+* @returns Percentage string like `"12.3%"`.
 */
 function formatPct(us, totalUs) {
 	if (totalUs === 0) return "0.0%";
@@ -221,6 +270,9 @@ function formatPct(us, totalUs) {
 * Escape HTML-special characters to prevent broken markup.
 * Handles: & < > " '
 * Ampersand is replaced first to avoid double-escaping.
+*
+* @param str - Raw string to escape.
+* @returns HTML-safe string.
 */
 function escapeHtml(str) {
 	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -241,6 +293,7 @@ function generateCss() {
       --bar-track: #e8eaed;
       --bar-fill: #5b8def;
       --bar-fill-fp: #3b6cf5;
+      --bar-fill-async: #f5943b;
       --other-text: #a0a4b8;
       --table-header-bg: #f4f5f7;
       --shadow: 0 1px 3px rgba(0,0,0,0.06);
@@ -280,6 +333,59 @@ function generateCss() {
       margin-top: 2rem;
     }
 
+    /* Threshold slider */
+    .threshold-control {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      margin-bottom: 1rem;
+      font-size: 0.85rem;
+    }
+
+    .threshold-control label {
+      font-weight: 600;
+      color: var(--muted);
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      font-size: 0.8rem;
+    }
+
+    .threshold-control input[type="range"] {
+      flex: 1;
+      max-width: 240px;
+      height: 8px;
+      appearance: none;
+      -webkit-appearance: none;
+      background: var(--bar-track);
+      border-radius: 4px;
+      outline: none;
+    }
+
+    .threshold-control input[type="range"]::-webkit-slider-thumb {
+      appearance: none;
+      -webkit-appearance: none;
+      width: 16px;
+      height: 16px;
+      border-radius: 50%;
+      background: var(--bar-fill);
+      cursor: pointer;
+    }
+
+    .threshold-control input[type="range"]::-moz-range-thumb {
+      width: 16px;
+      height: 16px;
+      border-radius: 50%;
+      background: var(--bar-fill);
+      cursor: pointer;
+      border: none;
+    }
+
+    .threshold-control span {
+      font-family: var(--font-mono);
+      font-size: 0.85rem;
+      min-width: 3.5em;
+    }
+
     /* Summary table */
     table {
       width: 100%;
@@ -318,6 +424,7 @@ function generateCss() {
 
     td.pkg-name { font-family: var(--font-mono); font-size: 0.85rem; }
     td.numeric { text-align: right; font-family: var(--font-mono); font-size: 0.85rem; }
+    td.async-col { color: var(--bar-fill-async); }
 
     .bar-cell {
       width: 30%;
@@ -431,6 +538,13 @@ function generateCss() {
       flex-shrink: 0;
     }
 
+    .tree-async {
+      font-family: var(--font-mono);
+      font-size: 0.8rem;
+      color: var(--bar-fill-async);
+      flex-shrink: 0;
+    }
+
     /* Level indentation */
     .level-0 > summary { padding-left: 0.75rem; }
     .level-1 > summary { padding-left: 2rem; }
@@ -458,7 +572,226 @@ function generateCss() {
     }
   `;
 }
-function renderSummaryTable(packages, otherCount, totalTimeUs) {
+function generateJs() {
+	return `
+(function() {
+  var DATA = window.__REPORT_DATA__;
+  if (!DATA) return;
+  var HAS_ASYNC = !!(DATA.totalAsyncTimeUs && DATA.totalAsyncTimeUs > 0);
+
+  function formatTime(us) {
+    if (us === 0) return '0ms';
+    var ms = us / 1000;
+    if (ms >= 1000) return (ms / 1000).toFixed(2) + 's';
+    var rounded = Math.round(ms);
+    return (rounded < 1 ? 1 : rounded) + 'ms';
+  }
+
+  function formatPct(us, totalUs) {
+    if (totalUs === 0) return '0.0%';
+    return ((us / totalUs) * 100).toFixed(1) + '%';
+  }
+
+  function escapeHtml(str) {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
+  function applyThreshold(data, pct) {
+    var threshold = data.totalTimeUs * (pct / 100);
+    var filtered = [];
+    var otherCount = 0;
+
+    for (var i = 0; i < data.packages.length; i++) {
+      var pkg = data.packages[i];
+      if (pkg.timeUs < threshold) {
+        otherCount++;
+        continue;
+      }
+
+      var files = [];
+      var fileOtherCount = 0;
+
+      for (var j = 0; j < pkg.files.length; j++) {
+        var file = pkg.files[j];
+        if (file.timeUs < threshold) {
+          fileOtherCount++;
+          continue;
+        }
+
+        var functions = [];
+        var funcOtherCount = 0;
+
+        for (var k = 0; k < file.functions.length; k++) {
+          var fn = file.functions[k];
+          if (fn.timeUs < threshold) {
+            funcOtherCount++;
+            continue;
+          }
+          functions.push(fn);
+        }
+
+        files.push({
+          name: file.name,
+          timeUs: file.timeUs,
+          pct: file.pct,
+          sampleCount: file.sampleCount,
+          asyncTimeUs: file.asyncTimeUs,
+          asyncPct: file.asyncPct,
+          asyncOpCount: file.asyncOpCount,
+          functions: functions,
+          otherCount: funcOtherCount
+        });
+      }
+
+      filtered.push({
+        name: pkg.name,
+        timeUs: pkg.timeUs,
+        pct: pkg.pct,
+        isFirstParty: pkg.isFirstParty,
+        sampleCount: pkg.sampleCount,
+        asyncTimeUs: pkg.asyncTimeUs,
+        asyncPct: pkg.asyncPct,
+        asyncOpCount: pkg.asyncOpCount,
+        files: files,
+        otherCount: fileOtherCount
+      });
+    }
+
+    return { packages: filtered, otherCount: otherCount };
+  }
+
+  function renderTable(packages, otherCount, totalTimeUs) {
+    var rows = '';
+    for (var i = 0; i < packages.length; i++) {
+      var pkg = packages[i];
+      var cls = pkg.isFirstParty ? 'first-party' : 'dependency';
+      var pctVal = totalTimeUs > 0 ? (pkg.timeUs / totalTimeUs) * 100 : 0;
+      rows += '<tr class="' + cls + '">' +
+        '<td class="pkg-name">' + escapeHtml(pkg.name) + '</td>' +
+        '<td class="numeric">' + escapeHtml(formatTime(pkg.timeUs)) + '</td>' +
+        '<td class="bar-cell"><div class="bar-container">' +
+          '<div class="bar-track"><div class="bar-fill" style="width:' + pctVal.toFixed(1) + '%"></div></div>' +
+          '<span class="bar-pct">' + escapeHtml(formatPct(pkg.timeUs, totalTimeUs)) + '</span>' +
+        '</div></td>' +
+        '<td class="numeric">' + pkg.sampleCount + '</td>';
+      if (HAS_ASYNC) {
+        rows += '<td class="numeric async-col">' + escapeHtml(formatTime(pkg.asyncTimeUs || 0)) + '</td>' +
+          '<td class="numeric async-col">' + (pkg.asyncOpCount || 0) + '</td>';
+      }
+      rows += '</tr>';
+    }
+
+    if (otherCount > 0) {
+      rows += '<tr class="other-row">' +
+        '<td class="pkg-name">Other (' + otherCount + ' items)</td>' +
+        '<td class="numeric"></td>' +
+        '<td class="bar-cell"></td>' +
+        '<td class="numeric"></td>';
+      if (HAS_ASYNC) {
+        rows += '<td class="numeric"></td><td class="numeric"></td>';
+      }
+      rows += '</tr>';
+    }
+
+    var headers = '<th>Package</th><th>Wall Time</th><th>% of Total</th><th>Samples</th>';
+    if (HAS_ASYNC) {
+      headers += '<th>Async Wait</th><th>Async Ops</th>';
+    }
+
+    return '<table><thead><tr>' + headers + '</tr></thead><tbody>' + rows + '</tbody></table>';
+  }
+
+  function asyncStats(entry) {
+    if (!HAS_ASYNC) return '';
+    var at = entry.asyncTimeUs || 0;
+    var ac = entry.asyncOpCount || 0;
+    if (at === 0 && ac === 0) return '';
+    return ' <span class="tree-async">| ' + escapeHtml(formatTime(at)) + ' async &middot; ' + ac + ' ops</span>';
+  }
+
+  function renderTree(packages, otherCount, totalTimeUs) {
+    var html = '<div class="tree">';
+
+    for (var i = 0; i < packages.length; i++) {
+      var pkg = packages[i];
+      var fpCls = pkg.isFirstParty ? ' fp-pkg' : '';
+      html += '<details class="level-0' + fpCls + '"><summary>';
+      html += '<span class="tree-label pkg">pkg</span>';
+      html += '<span class="tree-name">' + escapeHtml(pkg.name) + '</span>';
+      html += '<span class="tree-stats">' + escapeHtml(formatTime(pkg.timeUs)) + ' &middot; ' + escapeHtml(formatPct(pkg.timeUs, totalTimeUs)) + ' &middot; ' + pkg.sampleCount + ' samples</span>';
+      html += asyncStats(pkg);
+      html += '</summary>';
+
+      for (var j = 0; j < pkg.files.length; j++) {
+        var file = pkg.files[j];
+        html += '<details class="level-1"><summary>';
+        html += '<span class="tree-label file">file</span>';
+        html += '<span class="tree-name">' + escapeHtml(file.name) + '</span>';
+        html += '<span class="tree-stats">' + escapeHtml(formatTime(file.timeUs)) + ' &middot; ' + escapeHtml(formatPct(file.timeUs, totalTimeUs)) + ' &middot; ' + file.sampleCount + ' samples</span>';
+        html += asyncStats(file);
+        html += '</summary>';
+
+        for (var k = 0; k < file.functions.length; k++) {
+          var fn = file.functions[k];
+          html += '<div class="level-2">';
+          html += '<span class="tree-label fn">fn</span> ';
+          html += '<span class="tree-name">' + escapeHtml(fn.name) + '</span>';
+          html += ' <span class="tree-stats">' + escapeHtml(formatTime(fn.timeUs)) + ' &middot; ' + escapeHtml(formatPct(fn.timeUs, totalTimeUs)) + ' &middot; ' + fn.sampleCount + ' samples</span>';
+          html += asyncStats(fn);
+          html += '</div>';
+        }
+
+        if (file.otherCount > 0) {
+          html += '<div class="other-item indent-2">Other (' + file.otherCount + ' items)</div>';
+        }
+
+        html += '</details>';
+      }
+
+      if (pkg.otherCount > 0) {
+        html += '<div class="other-item indent-1">Other (' + pkg.otherCount + ' items)</div>';
+      }
+
+      html += '</details>';
+    }
+
+    if (otherCount > 0) {
+      html += '<div class="other-item">Other (' + otherCount + ' packages)</div>';
+    }
+
+    html += '</div>';
+    return html;
+  }
+
+  function update(pct) {
+    var result = applyThreshold(DATA, pct);
+    var summaryEl = document.getElementById('summary-container');
+    var treeEl = document.getElementById('tree-container');
+    if (summaryEl) summaryEl.innerHTML = renderTable(result.packages, result.otherCount, DATA.totalTimeUs);
+    if (treeEl) treeEl.innerHTML = renderTree(result.packages, result.otherCount, DATA.totalTimeUs);
+  }
+
+  document.addEventListener('DOMContentLoaded', function() {
+    update(5);
+    var slider = document.getElementById('threshold-slider');
+    var label = document.getElementById('threshold-value');
+    if (slider) {
+      slider.addEventListener('input', function() {
+        var val = parseFloat(slider.value);
+        if (label) label.textContent = val.toFixed(1) + '%';
+        update(val);
+      });
+    }
+  });
+})();
+`;
+}
+function renderSummaryTable(packages, otherCount, totalTimeUs, hasAsync) {
 	let rows = "";
 	for (const pkg of packages) {
 		const cls = pkg.isFirstParty ? "first-party" : "dependency";
@@ -473,7 +806,9 @@ function renderSummaryTable(packages, otherCount, totalTimeUs) {
             <span class="bar-pct">${escapeHtml(formatPct(pkg.timeUs, totalTimeUs))}</span>
           </div>
         </td>
-        <td class="numeric">${pkg.sampleCount}</td>
+        <td class="numeric">${pkg.sampleCount}</td>${hasAsync ? `
+        <td class="numeric async-col">${escapeHtml(formatTime(pkg.asyncTimeUs ?? 0))}</td>
+        <td class="numeric async-col">${pkg.asyncOpCount ?? 0}</td>` : ""}
       </tr>`;
 	}
 	if (otherCount > 0) rows += `
@@ -481,7 +816,9 @@ function renderSummaryTable(packages, otherCount, totalTimeUs) {
         <td class="pkg-name">Other (${otherCount} items)</td>
         <td class="numeric"></td>
         <td class="bar-cell"></td>
+        <td class="numeric"></td>${hasAsync ? `
         <td class="numeric"></td>
+        <td class="numeric"></td>` : ""}
       </tr>`;
 	return `
     <table>
@@ -490,14 +827,22 @@ function renderSummaryTable(packages, otherCount, totalTimeUs) {
           <th>Package</th>
           <th>Wall Time</th>
           <th>% of Total</th>
-          <th>Samples</th>
+          <th>Samples</th>${hasAsync ? `
+          <th>Async Wait</th>
+          <th>Async Ops</th>` : ""}
         </tr>
       </thead>
       <tbody>${rows}
       </tbody>
     </table>`;
 }
-function renderTree(packages, otherCount, totalTimeUs) {
+function formatAsyncStats(entry) {
+	const at = entry.asyncTimeUs ?? 0;
+	const ac = entry.asyncOpCount ?? 0;
+	if (at === 0 && ac === 0) return "";
+	return ` <span class="tree-async">| ${escapeHtml(formatTime(at))} async &middot; ${ac} ops</span>`;
+}
+function renderTree(packages, otherCount, totalTimeUs, hasAsync) {
 	let html = "<div class=\"tree\">";
 	for (const pkg of packages) {
 		const fpCls = pkg.isFirstParty ? " fp-pkg" : "";
@@ -506,6 +851,7 @@ function renderTree(packages, otherCount, totalTimeUs) {
 		html += `<span class="tree-label pkg">pkg</span>`;
 		html += `<span class="tree-name">${escapeHtml(pkg.name)}</span>`;
 		html += `<span class="tree-stats">${escapeHtml(formatTime(pkg.timeUs))} &middot; ${escapeHtml(formatPct(pkg.timeUs, totalTimeUs))} &middot; ${pkg.sampleCount} samples</span>`;
+		if (hasAsync) html += formatAsyncStats(pkg);
 		html += `</summary>`;
 		for (const file of pkg.files) {
 			html += `<details class="level-1">`;
@@ -513,12 +859,14 @@ function renderTree(packages, otherCount, totalTimeUs) {
 			html += `<span class="tree-label file">file</span>`;
 			html += `<span class="tree-name">${escapeHtml(file.name)}</span>`;
 			html += `<span class="tree-stats">${escapeHtml(formatTime(file.timeUs))} &middot; ${escapeHtml(formatPct(file.timeUs, totalTimeUs))} &middot; ${file.sampleCount} samples</span>`;
+			if (hasAsync) html += formatAsyncStats(file);
 			html += `</summary>`;
 			for (const fn of file.functions) {
 				html += `<div class="level-2">`;
 				html += `<span class="tree-label fn">fn</span> `;
 				html += `<span class="tree-name">${escapeHtml(fn.name)}</span>`;
 				html += ` <span class="tree-stats">${escapeHtml(formatTime(fn.timeUs))} &middot; ${escapeHtml(formatPct(fn.timeUs, totalTimeUs))} &middot; ${fn.sampleCount} samples</span>`;
+				if (hasAsync) html += formatAsyncStats(fn);
 				html += `</div>`;
 			}
 			if (file.otherCount > 0) html += `<div class="other-item indent-2">Other (${file.otherCount} items)</div>`;
@@ -533,12 +881,19 @@ function renderTree(packages, otherCount, totalTimeUs) {
 }
 /**
 * Render a complete self-contained HTML report from aggregated profiling data.
+*
+* @param data - Aggregated report data (packages, timing, project name).
+* @returns A full HTML document string with inline CSS/JS and no external dependencies.
 */
 function renderHtml(data) {
-	const summaryTable = renderSummaryTable(data.packages, data.otherCount, data.totalTimeUs);
-	const tree = renderTree(data.packages, data.otherCount, data.totalTimeUs);
+	const hasAsync = !!(data.totalAsyncTimeUs && data.totalAsyncTimeUs > 0);
+	const summaryTable = renderSummaryTable(data.packages, data.otherCount, data.totalTimeUs, hasAsync);
+	const tree = renderTree(data.packages, data.otherCount, data.totalTimeUs, hasAsync);
 	const totalFormatted = escapeHtml(formatTime(data.totalTimeUs));
 	const titleName = escapeHtml(data.projectName);
+	let metaLine = `Generated ${escapeHtml(data.timestamp)} &middot; Total wall time: ${totalFormatted}`;
+	if (hasAsync) metaLine += ` &middot; Total async wait: ${escapeHtml(formatTime(data.totalAsyncTimeUs))}`;
+	const safeJson = JSON.stringify(data).replace(/</g, "\\u003c");
 	return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -550,46 +905,213 @@ function renderHtml(data) {
 </head>
 <body>
   <h1>${titleName}</h1>
-  <div class="meta">Generated ${escapeHtml(data.timestamp)} &middot; Total wall time: ${totalFormatted}</div>
+  <div class="meta">${metaLine}</div>
 
   <h2>Summary</h2>
-  ${summaryTable}
+  <div class="threshold-control">
+    <label>Threshold</label>
+    <input type="range" id="threshold-slider" min="0" max="20" step="0.5" value="5">
+    <span id="threshold-value">5.0%</span>
+  </div>
+  <div id="summary-container">${summaryTable}</div>
 
   <h2>Details</h2>
-  ${tree}
+  <div id="tree-container">${tree}</div>
+
+  <script>var __REPORT_DATA__ = ${safeJson};<\/script>
+  <script>${generateJs()}<\/script>
 </body>
 </html>`;
 }
 
 //#endregion
-//#region src/reporter.ts
+//#region src/pkg-profile.ts
 /**
-* Reporter orchestrator.
+* Immutable profiling result returned by `stop()` and `profile()`.
 *
-* Aggregates SampleStore data, renders HTML, writes file to cwd,
-* and returns the file path.
+* Contains aggregated per-package timing data and a convenience method
+* to write a self-contained HTML report to disk.
 */
-function generateFilename() {
+function generateFilename(timestamp) {
 	const now = /* @__PURE__ */ new Date();
 	const pad = (n) => String(n).padStart(2, "0");
 	return `where-you-at-${`${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`}-${`${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`}.html`;
 }
-function readProjectName(cwd) {
-	try {
-		const raw = (0, node_fs.readFileSync)((0, node_path.join)(cwd, "package.json"), "utf-8");
-		return JSON.parse(raw).name ?? "app";
-	} catch {
-		return "app";
+var PkgProfile = class {
+	/** When the profile was captured */
+	timestamp;
+	/** Total sampled wall time in microseconds */
+	totalTimeUs;
+	/** Package breakdown sorted by time descending (all packages, no threshold applied) */
+	packages;
+	/** Always 0 — threshold filtering is now applied client-side in the HTML report */
+	otherCount;
+	/** Project name (from package.json) */
+	projectName;
+	/** Total async wait time in microseconds (undefined when async tracking not enabled) */
+	totalAsyncTimeUs;
+	/** @internal */
+	constructor(data) {
+		this.timestamp = data.timestamp;
+		this.totalTimeUs = data.totalTimeUs;
+		this.packages = data.packages;
+		this.otherCount = data.otherCount;
+		this.projectName = data.projectName;
+		this.totalAsyncTimeUs = data.totalAsyncTimeUs;
+	}
+	/**
+	* Write a self-contained HTML report to disk.
+	*
+	* @param path - Output file path. Defaults to `./where-you-at-{timestamp}.html` in cwd.
+	* @returns Absolute path to the written file.
+	*/
+	writeHtml(path) {
+		const html = renderHtml({
+			timestamp: this.timestamp,
+			totalTimeUs: this.totalTimeUs,
+			packages: this.packages,
+			otherCount: this.otherCount,
+			projectName: this.projectName,
+			totalAsyncTimeUs: this.totalAsyncTimeUs
+		});
+		let filepath;
+		if (path) filepath = (0, node_path.resolve)(path);
+		else {
+			const filename = generateFilename(this.timestamp);
+			filepath = (0, node_path.join)(process.cwd(), filename);
+		}
+		(0, node_fs.writeFileSync)(filepath, html, "utf-8");
+		return filepath;
 	}
+};
+
+//#endregion
+//#region src/reporter/aggregate.ts
+/**
+* Sum all microseconds in a SampleStore.
+*/
+function sumStore(store) {
+	let total = 0;
+	for (const fileMap of store.packages.values()) for (const funcMap of fileMap.values()) for (const us of funcMap.values()) total += us;
+	return total;
 }
-function generateReport(store, cwd) {
-	const resolvedCwd = cwd ?? process.cwd();
-	const html = renderHtml(aggregate(store, readProjectName(resolvedCwd)));
-	const filename = generateFilename();
-	const filepath = (0, node_path.join)(resolvedCwd, filename);
-	(0, node_fs.writeFileSync)(filepath, html, "utf-8");
-	console.log(`Report written to ./${filename}`);
-	return filepath;
+/**
+* Aggregate SampleStore data into a ReportData structure.
+*
+* @param store - SampleStore with accumulated microseconds and sample counts
+* @param projectName - Name of the first-party project (for isFirstParty flag)
+* @param asyncStore - Optional SampleStore with async wait time data
+* @returns ReportData with all packages sorted desc by time, no threshold applied
+*/
+function aggregate(store, projectName, asyncStore) {
+	const totalTimeUs = sumStore(store);
+	const totalAsyncTimeUs = asyncStore ? sumStore(asyncStore) : 0;
+	if (totalTimeUs === 0 && totalAsyncTimeUs === 0) return {
+		timestamp: (/* @__PURE__ */ new Date()).toLocaleString(),
+		totalTimeUs: 0,
+		packages: [],
+		otherCount: 0,
+		projectName
+	};
+	const allPackageNames = /* @__PURE__ */ new Set();
+	for (const name of store.packages.keys()) allPackageNames.add(name);
+	if (asyncStore) for (const name of asyncStore.packages.keys()) allPackageNames.add(name);
+	const packages = [];
+	for (const packageName of allPackageNames) {
+		const fileMap = store.packages.get(packageName);
+		let packageTimeUs = 0;
+		if (fileMap) for (const funcMap of fileMap.values()) for (const us of funcMap.values()) packageTimeUs += us;
+		let packageSampleCount = 0;
+		const countFileMap = store.sampleCountsByPackage.get(packageName);
+		if (countFileMap) for (const countFuncMap of countFileMap.values()) for (const count of countFuncMap.values()) packageSampleCount += count;
+		let packageAsyncTimeUs = 0;
+		let packageAsyncOpCount = 0;
+		const asyncFileMap = asyncStore?.packages.get(packageName);
+		const asyncCountFileMap = asyncStore?.sampleCountsByPackage.get(packageName);
+		if (asyncFileMap) for (const funcMap of asyncFileMap.values()) for (const us of funcMap.values()) packageAsyncTimeUs += us;
+		if (asyncCountFileMap) for (const countFuncMap of asyncCountFileMap.values()) for (const count of countFuncMap.values()) packageAsyncOpCount += count;
+		const allFileNames = /* @__PURE__ */ new Set();
+		if (fileMap) for (const name of fileMap.keys()) allFileNames.add(name);
+		if (asyncFileMap) for (const name of asyncFileMap.keys()) allFileNames.add(name);
+		const files = [];
+		for (const fileName of allFileNames) {
+			const funcMap = fileMap?.get(fileName);
+			let fileTimeUs = 0;
+			if (funcMap) for (const us of funcMap.values()) fileTimeUs += us;
+			let fileSampleCount = 0;
+			const countFuncMap = countFileMap?.get(fileName);
+			if (countFuncMap) for (const count of countFuncMap.values()) fileSampleCount += count;
+			let fileAsyncTimeUs = 0;
+			let fileAsyncOpCount = 0;
+			const asyncFuncMap = asyncFileMap?.get(fileName);
+			const asyncCountFuncMap = asyncCountFileMap?.get(fileName);
+			if (asyncFuncMap) for (const us of asyncFuncMap.values()) fileAsyncTimeUs += us;
+			if (asyncCountFuncMap) for (const count of asyncCountFuncMap.values()) fileAsyncOpCount += count;
+			const allFuncNames = /* @__PURE__ */ new Set();
+			if (funcMap) for (const name of funcMap.keys()) allFuncNames.add(name);
+			if (asyncFuncMap) for (const name of asyncFuncMap.keys()) allFuncNames.add(name);
+			const functions = [];
+			for (const funcName of allFuncNames) {
+				const funcTimeUs = funcMap?.get(funcName) ?? 0;
+				const funcSampleCount = countFuncMap?.get(funcName) ?? 0;
+				const funcAsyncTimeUs = asyncFuncMap?.get(funcName) ?? 0;
+				const funcAsyncOpCount = asyncCountFuncMap?.get(funcName) ?? 0;
+				const entry = {
+					name: funcName,
+					timeUs: funcTimeUs,
+					pct: totalTimeUs > 0 ? funcTimeUs / totalTimeUs * 100 : 0,
+					sampleCount: funcSampleCount
+				};
+				if (totalAsyncTimeUs > 0) {
+					entry.asyncTimeUs = funcAsyncTimeUs;
+					entry.asyncPct = funcAsyncTimeUs / totalAsyncTimeUs * 100;
+					entry.asyncOpCount = funcAsyncOpCount;
+				}
+				functions.push(entry);
+			}
+			functions.sort((a, b) => b.timeUs - a.timeUs);
+			const fileEntry = {
+				name: fileName,
+				timeUs: fileTimeUs,
+				pct: totalTimeUs > 0 ? fileTimeUs / totalTimeUs * 100 : 0,
+				sampleCount: fileSampleCount,
+				functions,
+				otherCount: 0
+			};
+			if (totalAsyncTimeUs > 0) {
+				fileEntry.asyncTimeUs = fileAsyncTimeUs;
+				fileEntry.asyncPct = fileAsyncTimeUs / totalAsyncTimeUs * 100;
+				fileEntry.asyncOpCount = fileAsyncOpCount;
+			}
+			files.push(fileEntry);
+		}
+		files.sort((a, b) => b.timeUs - a.timeUs);
+		const pkgEntry = {
+			name: packageName,
+			timeUs: packageTimeUs,
+			pct: totalTimeUs > 0 ? packageTimeUs / totalTimeUs * 100 : 0,
+			isFirstParty: packageName === projectName,
+			sampleCount: packageSampleCount,
+			files,
+			otherCount: 0
+		};
+		if (totalAsyncTimeUs > 0) {
+			pkgEntry.asyncTimeUs = packageAsyncTimeUs;
+			pkgEntry.asyncPct = packageAsyncTimeUs / totalAsyncTimeUs * 100;
+			pkgEntry.asyncOpCount = packageAsyncOpCount;
+		}
+		packages.push(pkgEntry);
+	}
+	packages.sort((a, b) => b.timeUs - a.timeUs);
+	const result = {
+		timestamp: (/* @__PURE__ */ new Date()).toLocaleString(),
+		totalTimeUs,
+		packages,
+		otherCount: 0,
+		projectName
+	};
+	if (totalAsyncTimeUs > 0) result.totalAsyncTimeUs = totalAsyncTimeUs;
+	return result;
 }
 
 //#endregion
@@ -673,55 +1195,151 @@ var SampleStore = class {
 let session = null;
 let profiling = false;
 const store = new SampleStore();
+const asyncStore = new SampleStore();
 const resolver = new PackageResolver(process.cwd());
+let asyncTracker = null;
+/**
+* Promisify session.post for the normal async API path.
+*/
+function postAsync(method, params) {
+	return new Promise((resolve, reject) => {
+		const cb = (err, result) => {
+			if (err) reject(err);
+			else resolve(result);
+		};
+		if (params !== void 0) session.post(method, params, cb);
+		else session.post(method, cb);
+	});
+}
+/**
+* Synchronous session.post — works because the V8 inspector executes
+* callbacks synchronously for in-process sessions.
+*/
+function postSync(method) {
+	let result;
+	let error = null;
+	const cb = (err, params) => {
+		error = err;
+		result = params;
+	};
+	session.post(method, cb);
+	if (error) throw error;
+	return result;
+}
+function readProjectName(cwd) {
+	try {
+		const raw = (0, node_fs.readFileSync)((0, node_path.join)(cwd, "package.json"), "utf-8");
+		return JSON.parse(raw).name ?? "app";
+	} catch {
+		return "app";
+	}
+}
+function buildEmptyProfile() {
+	const projectName = readProjectName(process.cwd());
+	return new PkgProfile({
+		timestamp: (/* @__PURE__ */ new Date()).toLocaleString(),
+		totalTimeUs: 0,
+		packages: [],
+		otherCount: 0,
+		projectName
+	});
+}
+/**
+* Shared logic for stopping the profiler and building a PkgProfile.
+* Synchronous — safe to call from process `exit` handlers.
+*/
+function stopSync() {
+	if (!profiling || !session) return buildEmptyProfile();
+	const { profile } = postSync("Profiler.stop");
+	postSync("Profiler.disable");
+	profiling = false;
+	if (asyncTracker) {
+		asyncTracker.disable();
+		asyncTracker = null;
+	}
+	processProfile(profile);
+	const data = aggregate(store, readProjectName(process.cwd()), asyncStore.packages.size > 0 ? asyncStore : void 0);
+	store.clear();
+	asyncStore.clear();
+	return new PkgProfile(data);
+}
 /**
 * Start the V8 CPU profiler. If already profiling, this is a safe no-op.
+*
+* @param options - Optional configuration.
+* @param options.interval - Sampling interval in microseconds passed to V8 (defaults to 1000µs). Lower values = higher fidelity but more overhead.
+* @returns Resolves when the profiler is successfully started
 */
-async function track(options) {
+async function start(options) {
 	if (profiling) return;
 	if (session === null) {
-		session = new node_inspector_promises.Session();
+		session = new node_inspector.Session();
 		session.connect();
 	}
-	await session.post("Profiler.enable");
-	if (options?.interval !== void 0) await session.post("Profiler.setSamplingInterval", { interval: options.interval });
-	await session.post("Profiler.start");
+	await postAsync("Profiler.enable");
+	if (options?.interval !== void 0) await postAsync("Profiler.setSamplingInterval", { interval: options.interval });
+	await postAsync("Profiler.start");
 	profiling = true;
+	if (options?.trackAsync) {
+		asyncTracker = new AsyncTracker(resolver, asyncStore);
+		asyncTracker.enable();
+	}
+}
+/**
+* Stop the profiler, process collected samples, and return a PkgProfile
+* containing the aggregated data. Resets the store afterward.
+*
+* @returns A PkgProfile with the profiling results, or a PkgProfile with empty data if no samples were collected.
+*/
+async function stop() {
+	return stopSync();
 }
 /**
 * Stop the profiler (if running) and reset all accumulated sample data.
 */
 async function clear() {
 	if (profiling && session) {
-		await session.post("Profiler.stop");
-		await session.post("Profiler.disable");
+		postSync("Profiler.stop");
+		postSync("Profiler.disable");
 		profiling = false;
 	}
 	store.clear();
+	if (asyncTracker) {
+		asyncTracker.disable();
+		asyncTracker = null;
+	}
+	asyncStore.clear();
 }
-/**
-* Stop the profiler, process collected samples through the data pipeline
-* (parseFrame -> PackageResolver -> SampleStore), generate an HTML report,
-* and return the file path. Resets the store after reporting (clean slate
-* for next cycle).
-*
-* Returns the absolute path to the generated HTML file, or empty string
-* if no samples were collected.
-*/
-async function report() {
-	if (!profiling || !session) {
-		console.log("no samples collected");
-		return "";
+async function profile(fnOrOptions) {
+	if (typeof fnOrOptions === "function") {
+		await start();
+		try {
+			await fnOrOptions();
+		} finally {
+			return stop();
+		}
 	}
-	const { profile } = await session.post("Profiler.stop");
-	await session.post("Profiler.disable");
-	profiling = false;
-	processProfile(profile);
-	let filepath = "";
-	if (store.packages.size > 0) filepath = generateReport(store);
-	else console.log("no samples collected");
-	store.clear();
-	return filepath;
+	const { onExit, ...startOpts } = fnOrOptions;
+	await start(startOpts);
+	let handled = false;
+	const handler = (signal) => {
+		if (handled) return;
+		handled = true;
+		process.removeListener("SIGINT", onSignal);
+		process.removeListener("SIGTERM", onSignal);
+		process.removeListener("exit", onProcessExit);
+		onExit(stopSync());
+		if (signal) process.kill(process.pid, signal);
+	};
+	const onSignal = (signal) => {
+		handler(signal);
+	};
+	const onProcessExit = () => {
+		handler();
+	};
+	process.once("SIGINT", onSignal);
+	process.once("SIGTERM", onSignal);
+	process.once("exit", onProcessExit);
 }
 /**
 * Process a V8 CPUProfile: walk each sample, parse the frame, resolve
@@ -749,7 +1367,11 @@ function processProfile(profile) {
 }
 
 //#endregion
+exports.PkgProfile = PkgProfile;
 exports.clear = clear;
-exports.report = report;
-exports.track = track;
+exports.profile = profile;
+exports.report = stop;
+exports.start = start;
+exports.stop = stop;
+exports.track = start;
 //# sourceMappingURL=index.cjs.map