zeitzeuge 0.5.1 → 0.6.0

package/dist/analysis/agent.d.ts

@@ -1,17 +1,30 @@
 import { type BackendProtocol } from 'deepagents';
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { Ora } from 'ora';
-import type { Finding } from '../types.js';
+import type { Finding, HeapSummary, TraceResult } from '../types.js';
+import type { PerformanceMetrics } from '../vitest/metrics.js';
+/** Context for building a dynamic page-load user message. */
+export interface PageLoadContext {
+    url: string;
+    heapSummary: HeapSummary;
+    traceResult: TraceResult;
+}
 /**
  * Analyze performance data using a Deep Agent that explores
  * the workspace containing heap + trace data + source files.
  */
-export declare function analyze(model: BaseChatModel, backend: BackendProtocol, spinner: Ora): Promise<Finding[]>;
+export declare function analyze(model: BaseChatModel, backend: BackendProtocol, spinner: Ora, context?: PageLoadContext): Promise<Finding[]>;
+/** Context for building a dynamic Vitest user message. */
+export interface VitestAnalysisContext {
+    metrics: PerformanceMetrics;
+    hasHeapProfiles: boolean;
+    hasListenerTracking: boolean;
+}
 /**
  * Analyze Vitest test performance data using a Deep Agent that explores
  * the workspace containing CPU profiles + test timing + source files.
  */
-export declare function analyzeTestPerformance(model: BaseChatModel, backend: BackendProtocol, spinner: Ora): Promise<Finding[]>;
+export declare function analyzeTestPerformance(model: BaseChatModel, backend: BackendProtocol, spinner: Ora, context?: VitestAnalysisContext): Promise<Finding[]>;
 /**
  * Format bytes into a human-readable string.
  * Kept for backwards compatibility with existing imports.

package/dist/analysis/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/analysis/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAM/B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAwC3C;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,GAAG,GACX,OAAO,CAAC,OAAO,EAAE,CAAC,CAoCpB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,GAAG,GACX,OAAO,CAAC,OAAO,EAAE,CAAC,CAwCpB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjD"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/analysis/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAM/B,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAwC/D,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,WAAW,CAAC;CAC1B;AA6DD;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,GAAG,EACZ,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,OAAO,EAAE,CAAC,CAwBpB;AAED,0DAA0D;AAC1D,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAkDD;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,GAAG,EACZ,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,OAAO,EAAE,CAAC,CAwBpB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjD"}

package/dist/analysis/prompts.d.ts

@@ -1,2 +1,2 @@
-export declare const SYSTEM_PROMPT = "You are an expert web performance engineer. You have access to a virtual filesystem workspace containing captured data from a real page load: heap snapshot, network trace, and Chrome runtime trace.\n\n## Workspace structure\n\n- /heap/summary.json \u2014 Parsed V8 heap snapshot: largest objects, type stats, constructor stats, detached DOM nodes, closure stats\n- /trace/summary.json \u2014 Page load metrics: timing, long tasks, render-blocking resources, resource breakdown\n- /trace/network-waterfall.json \u2014 Every network request with timing, size, priority, render-blocking status\n- /trace/asset-manifest.json \u2014 Index of all assets with paths to stored files\n- /trace/runtime/summary.json \u2014 Runtime trace overview: frame breakdown (scripting/layout/paint/GC), blocking function count, listener imbalances, GC stats\n- /trace/runtime/blocking-functions.json \u2014 Functions that blocked the main thread > 50ms, with script URL, line number, call stack, and duration\n- /trace/runtime/event-listeners.json \u2014 Event listener add/remove counts per event type, with source locations\n- /trace/runtime/frame-breakdown.json \u2014 Time spent in scripting vs layout vs paint vs GC\n- /trace/runtime/raw-events.json \u2014 Full Chrome trace events (large file \u2014 read to investigate specific function calls, layouts, GC, and event dispatches)\n- /scripts/*.js \u2014 Actual JavaScript source files captured during page load\n- /styles/*.css \u2014 Actual CSS source files\n- /html/document.html \u2014 The HTML document\n\n## Your workflow\n\n1. Read /heap/summary.json, /trace/summary.json, AND /trace/runtime/summary.json first for the big picture\n2. Identify the highest-impact issues from all datasets\n3. For each issue, dive into the relevant source files to understand the root cause\n4. Provide specific, code-level fixes\n\n## What to look for\n\n### Memory issues (from heap data)\n- Memory leaks: unbounded arrays, maps, caches that grow without bound\n- Detached DOM nodes: DOM elements removed from the document but still referenced\n- Large retained objects: single objects or trees retaining disproportionate memory\n- Closure leaks: closures capturing variables they no longer need\n\n### Page-load issues (from trace + source code)\n- Render-blocking scripts: <script> in <head> without async/defer \u2014 read the script to judge if it must be synchronous\n- Render-blocking CSS: large stylesheets blocking first paint\n- Long tasks (> 50ms): identify the function/module causing the block by reading the source\n- Large bundles: scripts > 100KB \u2014 search for unused imports or code that could be lazy-loaded\n- Sequential waterfalls: resources chained sequentially that could load in parallel\n\n### Runtime issues (from Chrome trace)\n- Frame-blocking functions: read /trace/runtime/blocking-functions.json first, then inspect the actual script source at the reported line number to understand what the function does and how to optimize it\n- Event listener leaks: check /trace/runtime/event-listeners.json for event types where addCount >> removeCount, then grep the scripts for those addEventListener calls\n- GC pressure: high GC pause counts or duration suggest excessive short-lived object creation \u2014 look for hot loops creating objects\n- Layout thrashing: forced synchronous layouts caused by reading layout properties (offsetHeight, getBoundingClientRect) after DOM writes\n\n## Output guidelines\n\n- Report 3\u20137 findings, ordered by impact (mix of memory, page-load, and runtime if all have issues)\n- Be specific \u2014 name actual files, functions, object constructors, and retention paths\n- Provide concrete code fixes, not generic advice\n- If heap, trace, and runtime all look healthy, say so \u2014 don't manufacture issues";
+export declare const SYSTEM_PROMPT = "You are an expert web performance engineer. You have access to a virtual filesystem workspace containing captured data from a real page load: heap snapshot, network trace, and Chrome runtime trace.\n\n## Workspace structure\n\n- /heap/summary.json \u2014 Parsed V8 heap snapshot: largest objects, type stats, constructor stats, detached DOM nodes, closure stats\n- /trace/summary.json \u2014 Page load metrics: timing, long tasks, render-blocking resources, resource breakdown\n- /trace/network-waterfall.json \u2014 Every network request with timing, size, priority, render-blocking status\n- /trace/asset-manifest.json \u2014 Index of all assets with paths to stored files\n- /trace/runtime/summary.json \u2014 Runtime trace overview: frame breakdown (scripting/layout/paint/GC), blocking function count, listener imbalances, GC stats\n- /trace/runtime/blocking-functions.json \u2014 Functions that blocked the main thread > 50ms, with script URL, line number, call stack, and duration\n- /trace/runtime/event-listeners.json \u2014 Event listener add/remove counts per event type, with source locations\n- /trace/runtime/frame-breakdown.json \u2014 Time spent in scripting vs layout vs paint vs GC\n- /trace/runtime/raw-events.json \u2014 Full Chrome trace events (large file \u2014 read to investigate specific function calls, layouts, GC, and event dispatches)\n- /scripts/*.js \u2014 Actual JavaScript source files captured during page load\n- /styles/*.css \u2014 Actual CSS source files\n- /html/document.html \u2014 The HTML document\n\n## Your workflow\n\n1. Read /heap/summary.json, /trace/summary.json, AND /trace/runtime/summary.json first for the big picture\n2. Identify the highest-impact issues from all datasets\n3. For each issue, dive into the relevant source files to understand the root cause\n4. Provide specific, code-level fixes\n\n## What to look for\n\n### Memory issues (from heap data)\n- Memory leaks: unbounded arrays, maps, caches that grow without bound\n- Detached DOM nodes: DOM elements removed from the document but still referenced\n- Large retained objects: single objects or trees retaining disproportionate memory\n- Closure leaks: closures capturing variables they no longer need\n\n### Page-load issues (from trace + source code)\n- Render-blocking scripts: <script> in <head> without async/defer \u2014 read the script to judge if it must be synchronous\n- Render-blocking CSS: large stylesheets blocking first paint\n- Long tasks (> 50ms): identify the function/module causing the block by reading the source\n- Large bundles: scripts > 100KB \u2014 search for unused imports or code that could be lazy-loaded\n- Sequential waterfalls: resources chained sequentially that could load in parallel\n\n### Runtime issues (from Chrome trace)\n- Frame-blocking functions: read /trace/runtime/blocking-functions.json first, then inspect the actual script source at the reported line number to understand what the function does and how to optimize it\n- Event listener leaks: check /trace/runtime/event-listeners.json for event types where addCount >> removeCount, then grep the scripts for those addEventListener calls\n- GC pressure: high GC pause counts or duration suggest excessive short-lived object creation \u2014 look for hot loops creating objects\n- Layout thrashing: forced synchronous layouts caused by reading layout properties (offsetHeight, getBoundingClientRect) after DOM writes\n\n## Severity classification\n\nAssign severity based on measured impact \u2014 do NOT guess:\n\n- **critical** \u2014 A blocking function >500ms, retained heap object >5MB,\n  render-blocking resource >200KB, listener addCount > 10\u00D7 removeCount,\n  or GC pauses totalling >500ms\n- **warning** \u2014 A blocking function 100\u2013500ms, retained heap object 1\u20135MB,\n  render-blocking resource 50\u2013200KB, listener addCount > 2\u00D7 removeCount,\n  or GC pauses totalling 100\u2013500ms\n- **info** \u2014 Blocking function 50\u2013100ms, retained object <1MB, minor\n  optimisation opportunities, or observations about dependency usage\n\nAlways base severity on the actual numbers from the captured data \u2014 never inflate.\n\n## Verification rules\n\nThese rules are mandatory for every finding:\n\n1. **ALWAYS read the source file** in /scripts/, /styles/, or /html/ and\n   verify the code BEFORE suggesting a fix. Never suggest a fix for code\n   you have not read.\n2. **Never guess at line numbers** \u2014 confirm by reading the file. If the\n   trace reports a line number but the source doesn't match, say so.\n3. Each `suggestedFix` MUST reference the actual current code and describe\n   what to change. Include a before/after snippet from the real source.\n4. If the heap summary, trace summary, and runtime summary all show healthy\n   numbers, state that the page is well-optimised \u2014 do NOT manufacture\n   findings.\n5. Never report a finding based solely on a URL or resource name \u2014 always\n   read the actual content to confirm the issue.\n\n## Cross-referencing data\n\n- When a script appears in BOTH /trace/runtime/blocking-functions.json (CPU)\n  AND /heap/summary.json (memory), mention both dimensions in the finding.\n- Check /trace/runtime/event-listeners.json for listener imbalances and\n  cross-reference with the actual addEventListener calls in /scripts/.\n- Use /trace/network-waterfall.json to identify sequential chains, then read\n  the initiating script to confirm the dependency.\n- When GC pauses are significant, cross-reference with heap data to identify\n  which constructors or allocation patterns are responsible.\n\n## Estimating impactMs\n\nEvery finding should include an `impactMs` estimate when possible:\n\n- For render-blocking resources: impactMs \u2248 the resource's load duration\n  (from the network waterfall) that could be deferred.\n- For blocking functions: impactMs \u2248 the function's duration minus 50ms\n  (the long-task threshold).\n- For memory issues: impactMs may not apply \u2014 use `retainedSize` instead.\n- If you cannot reasonably estimate the savings, omit impactMs rather than\n  guessing.\n\n## Output guidelines\n\n- Report 3\u20137 findings, ordered by impact (mix of memory, page-load, and runtime if all have issues)\n- Be specific \u2014 name actual files, functions, object constructors, and retention paths\n- Provide concrete code fixes, not generic advice\n- If heap, trace, and runtime all look healthy, say so \u2014 don't manufacture issues\n\n## Structured output fields\n\nFor each finding, fill in as many fields as applicable:\n\n- `sourceFile` \u2014 the workspace path (e.g. /scripts/app.js) or resource URL\n  where the issue occurs. Always set this when you can identify the file.\n- `lineNumber` \u2014 the 1-based line number in the source file. Only set after\n  verifying by reading the file.\n- `confidence` \u2014 `high` if you read the source and confirmed the issue,\n  `medium` if the profiling data strongly suggests it but you couldn't fully\n  verify, `low` if inferred from patterns.\n- `estimatedSavingsMs` \u2014 your estimate of time saved if the fix is applied.\n- `beforeCode` \u2014 a snippet of the CURRENT problematic code, copied from the\n  source file you read. Keep it focused (5\u201315 lines).\n- `afterCode` \u2014 the IMPROVED code snippet showing the fix. Must be a drop-in\n  replacement for `beforeCode`.\n- `impactMs` \u2014 the current measured cost (e.g. blocking function duration,\n  resource load time).";
 //# sourceMappingURL=prompts.d.ts.map

package/dist/analysis/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/analysis/prompts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,ytHAkDwD,CAAC"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/analysis/prompts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,i1OA4HH,CAAC"}

package/dist/cli.js

@@ -59,12 +59,86 @@ var SYSTEM_PROMPT = `You are an expert web performance engineer. You have access
 - GC pressure: high GC pause counts or duration suggest excessive short-lived object creation — look for hot loops creating objects
 - Layout thrashing: forced synchronous layouts caused by reading layout properties (offsetHeight, getBoundingClientRect) after DOM writes
 
+## Severity classification
+
+Assign severity based on measured impact — do NOT guess:
+
+- **critical** — A blocking function >500ms, retained heap object >5MB,
+  render-blocking resource >200KB, listener addCount > 10× removeCount,
+  or GC pauses totalling >500ms
+- **warning** — A blocking function 100–500ms, retained heap object 1–5MB,
+  render-blocking resource 50–200KB, listener addCount > 2× removeCount,
+  or GC pauses totalling 100–500ms
+- **info** — Blocking function 50–100ms, retained object <1MB, minor
+  optimisation opportunities, or observations about dependency usage
+
+Always base severity on the actual numbers from the captured data — never inflate.
+
+## Verification rules
+
+These rules are mandatory for every finding:
+
+1. **ALWAYS read the source file** in /scripts/, /styles/, or /html/ and
+   verify the code BEFORE suggesting a fix. Never suggest a fix for code
+   you have not read.
+2. **Never guess at line numbers** — confirm by reading the file. If the
+   trace reports a line number but the source doesn't match, say so.
+3. Each \`suggestedFix\` MUST reference the actual current code and describe
+   what to change. Include a before/after snippet from the real source.
+4. If the heap summary, trace summary, and runtime summary all show healthy
+   numbers, state that the page is well-optimised — do NOT manufacture
+   findings.
+5. Never report a finding based solely on a URL or resource name — always
+   read the actual content to confirm the issue.
+
+## Cross-referencing data
+
+- When a script appears in BOTH /trace/runtime/blocking-functions.json (CPU)
+  AND /heap/summary.json (memory), mention both dimensions in the finding.
+- Check /trace/runtime/event-listeners.json for listener imbalances and
+  cross-reference with the actual addEventListener calls in /scripts/.
+- Use /trace/network-waterfall.json to identify sequential chains, then read
+  the initiating script to confirm the dependency.
+- When GC pauses are significant, cross-reference with heap data to identify
+  which constructors or allocation patterns are responsible.
+
+## Estimating impactMs
+
+Every finding should include an \`impactMs\` estimate when possible:
+
+- For render-blocking resources: impactMs ≈ the resource's load duration
+  (from the network waterfall) that could be deferred.
+- For blocking functions: impactMs ≈ the function's duration minus 50ms
+  (the long-task threshold).
+- For memory issues: impactMs may not apply — use \`retainedSize\` instead.
+- If you cannot reasonably estimate the savings, omit impactMs rather than
+  guessing.
+
 ## Output guidelines
 
 - Report 3–7 findings, ordered by impact (mix of memory, page-load, and runtime if all have issues)
 - Be specific — name actual files, functions, object constructors, and retention paths
 - Provide concrete code fixes, not generic advice
-- If heap, trace, and runtime all look healthy, say so — don't manufacture issues`;
+- If heap, trace, and runtime all look healthy, say so — don't manufacture issues
+
+## Structured output fields
+
+For each finding, fill in as many fields as applicable:
+
+- \`sourceFile\` — the workspace path (e.g. /scripts/app.js) or resource URL
+  where the issue occurs. Always set this when you can identify the file.
+- \`lineNumber\` — the 1-based line number in the source file. Only set after
+  verifying by reading the file.
+- \`confidence\` — \`high\` if you read the source and confirmed the issue,
+  \`medium\` if the profiling data strongly suggests it but you couldn't fully
+  verify, \`low\` if inferred from patterns.
+- \`estimatedSavingsMs\` — your estimate of time saved if the fix is applied.
+- \`beforeCode\` — a snippet of the CURRENT problematic code, copied from the
+  source file you read. Keep it focused (5–15 lines).
+- \`afterCode\` — the IMPROVED code snippet showing the fix. Must be a drop-in
+  replacement for \`beforeCode\`.
+- \`impactMs\` — the current measured cost (e.g. blocking function duration,
+  resource load time).`;
 
 // src/vitest/prompts.ts
 var VITEST_SYSTEM_PROMPT = `You are an expert in JavaScript/TypeScript performance optimization.
@@ -105,7 +179,9 @@ Every hot function and script in the workspace has a \`sourceCategory\` field:
 - /heap-profiles/index.json — (optional) Manifest mapping test files to heap profiles
 - /heap-profiles/<file>.json — (optional) Heap profile summary: allocation hotspots,
   per-script allocated bytes (with sourceCategory)
-- /hot-functions/application.json — **START HERE**: Hot functions from application code only
+- /hot-functions/application.json — **START HERE**: Hot functions from application code only.
+  Each entry includes a \`sourceSnippet\` (lines around the hot line) and \`workspacePath\`
+  (path to the full source file in the workspace) when source code is available.
 - /hot-functions/dependencies.json — Hot functions from third-party dependencies
 - /hot-functions/global.json — All hot functions across all categories
 - /scripts/application.json — Per-script time breakdown for application code
@@ -113,8 +189,11 @@ Every hot function and script in the workspace has a \`sourceCategory\` field:
 - /listener-tracking.json — (optional) Event listener tracking data captured from
   worker processes. Contains per-event-type add/remove counts for EventTarget and
   EventEmitter, plus exceedances where listener counts exceeded maxListeners.
-- /tests/*.ts — Test source files
-- /src/*.ts — Application and dependency source files referenced by hot functions
+- /src/index.json — Mapping of source files to their hot functions (quick overview
+  of which files matter and what bottlenecks they contain)
+- /tests/<relative-path> — Test source files (directory structure preserved)
+- /src/<relative-path> — Application and dependency source files referenced by
+  hot functions (directory structure preserved from the project root)
 
 ## Your workflow
 
@@ -159,6 +238,9 @@ Every hot function and script in the workspace has a \`sourceCategory\` field:
 - When allocation hotspots match CPU hotspots, prioritize fixes there first
 
 ### Call chain analysis
+- Each hot function includes a \`callerChain\` field — the chain of callers
+  from the hot function up toward the entry point. Use this to understand
+  WHY a function is hot and which application-level call triggers it.
 - Trace expensive call trees to find which APPLICATION function triggers them
 - Follow the call tree from application entry points down to the hot leaf functions
 - Identify which application-level design decisions lead to the bottleneck
@@ -208,6 +290,63 @@ Each finding MUST use one of these exact category values:
 Prefer more specific categories (algorithm, serialization, allocation, event-handling)
 over generic ones (hot-function, other) when the root cause is clear.
 
+## Severity classification
+
+Assign severity based on measured impact — do NOT guess:
+
+- **critical** — A single function consuming >15% self-time, listener exceedances
+  (count exceeding maxListeners), or GC overhead >10% of total profile duration
+- **warning** — A function consuming 5–15% self-time, listener add/remove imbalance
+  where addCount > 2× removeCount, or GC overhead between 5–10%
+- **info** — A function consuming <5% self-time, minor inefficiencies,
+  dependency observations, or small optimisation opportunities
+
+Always base severity on the actual numbers from the profiling data — never inflate.
+
+## Verification rules
+
+These rules are mandatory for every finding:
+
+1. **ALWAYS read the source file** in /src/ or /tests/ and verify the code
+   BEFORE suggesting a fix. Never suggest a fix for code you have not read.
+2. **Never guess at line numbers** — confirm by reading the file. If the profile
+   reports line 42 but the source at line 42 doesn't match, say so.
+3. Each \`suggestedFix\` MUST reference the actual current code and describe
+   what to change. Include a before/after snippet from the real source.
+4. If /hot-functions/application.json is empty or every function is <1%
+   self-time, state that the application code is efficient — do NOT
+   manufacture findings.
+5. Never report a finding based solely on a function name — always read the
+   implementation to confirm the issue exists.
+
+## Cross-referencing data
+
+- When a function appears in BOTH /hot-functions/ (CPU hotspot) AND
+  /heap-profiles/ (allocation hotspot), prioritise it and mention both
+  dimensions in the finding.
+- Cross-reference /hot-functions/ data with /heap-profiles/ when both are
+  present to find functions that are expensive in both CPU and memory.
+- Check whether hot dependency calls originate from application code by
+  tracing the call tree in /profiles/.
+- When /listener-tracking.json is present, cross-reference exceedance stack
+  traces with the source code in /src/ to pinpoint the registration site.
+- /metrics/current.json contains pre-computed aggregate metrics (suite totals,
+  CPU category breakdown, top hot functions). Use it for the big-picture
+  numbers when sizing impact.
+
+## Estimating impactMs
+
+Every finding should include an \`impactMs\` estimate when possible:
+
+- Use the hot function's \`selfTime\` as the baseline cost.
+- Estimate what fraction of that cost the fix would eliminate
+  (e.g. an O(n²) → O(n) fix on data of size 1000 might eliminate ~99%).
+- impactMs = selfTime × estimated fraction eliminated.
+- Example: a function with selfTime 200ms in a 1000ms run, where an
+  algorithm fix would remove ~80% of the work → impactMs ≈ 160.
+- If you cannot reasonably estimate the savings, omit impactMs rather than
+  guessing.
+
 ## Output guidelines
 
 - Report 3–7 findings, ordered by impact ON THE APPLICATION CODE
@@ -218,7 +357,28 @@ over generic ones (hot-function, other) when the root cause is clear.
 - When reporting a dependency bottleneck, explain what application code is
   calling it and how the developer can reduce that cost
 - If the application code is already efficient, say so — don't force findings
-  about test infrastructure just to fill the report`;
+  about test infrastructure just to fill the report
+
+## Structured output fields
+
+For each finding, fill in as many fields as applicable:
+
+- \`sourceFile\` — the workspace path (e.g. /src/utils/parser.ts) or original
+  file path where the issue occurs. Always set this when you can identify
+  the file.
+- \`lineNumber\` — the 1-based line number in the source file. Only set after
+  verifying by reading the file.
+- \`confidence\` — \`high\` if you read the source and confirmed the issue,
+  \`medium\` if the profiling data strongly suggests it but you couldn't fully
+  verify, \`low\` if inferred from patterns.
+- \`estimatedSavingsMs\` — your estimate of time saved if the fix is applied.
+- \`beforeCode\` — a snippet of the CURRENT problematic code, copied from the
+  source file you read. Keep it focused (5–15 lines).
+- \`afterCode\` — the IMPROVED code snippet showing the fix. Must be a drop-in
+  replacement for \`beforeCode\`.
+- \`affectedTests\` — list of test names that exercise this code path and would
+  benefit from the fix.
+- \`impactMs\` — the current measured cost (e.g. selfTime of the hot function).`;
 
 // src/schema.ts
 import { z } from "zod";
@@ -256,11 +416,18 @@ var init_schema = __esm(() => {
     category: z.string().describe(`Category of the performance issue. Use one of: ${ALL_CATEGORIES.join(", ")}`),
     resourceUrl: z.string().optional().describe("URL of the resource involved"),
     workspacePath: z.string().optional().describe("Path in the VFS workspace"),
-    impactMs: z.number().optional().describe("Impact on page load time in ms"),
+    impactMs: z.number().optional().describe("Estimated current cost in ms (e.g. selfTime of the hot function)"),
+    estimatedSavingsMs: z.number().optional().describe("Estimated time savings in ms if the fix is applied. Computed as impactMs × fraction eliminated by the fix."),
+    confidence: z.enum(["high", "medium", "low"]).optional().describe("How confident you are in this finding. high = verified in source code, medium = strong signal but partial verification, low = inferred from data patterns"),
     retainedSize: z.number().optional().describe("Retained heap size in bytes"),
     retainerPath: z.array(z.string()).optional().describe("Object retention path in the heap"),
+    sourceFile: z.string().optional().describe("Primary source file where the issue occurs (workspace path or original path)"),
+    lineNumber: z.number().optional().describe("Line number in the source file where the issue occurs (1-based)"),
     suggestedFix: z.string().describe("Code snippet or guidance to fix the issue"),
+    beforeCode: z.string().optional().describe("The current problematic code snippet from the source file"),
+    afterCode: z.string().optional().describe("The improved code snippet that fixes the issue"),
     testFile: z.string().optional().describe("Test file path (for test performance findings)"),
+    affectedTests: z.array(z.string()).optional().describe("Test names that would benefit from this fix (for test performance findings)"),
     hotFunction: z.object({
       name: z.string(),
       scriptUrl: z.string(),
@@ -362,32 +529,46 @@ async function invokeWithTodoStreaming(agent, userMessage, spinner) {
   }
   return lastValues;
 }
-async function analyze(model, backend, spinner) {
+function buildPageLoadUserMessage(ctx) {
+  const { url, heapSummary, traceResult } = ctx;
+  const m = traceResult.metrics;
+  const reqCount = traceResult.networkRequests.length;
+  const renderBlocking = traceResult.networkRequests.filter((r) => r.isRenderBlocking).length;
+  const totalTransfer = traceResult.networkRequests.reduce((s, r) => s + r.encodedSize, 0);
+  const hasRuntime = !!traceResult.runtimeTrace;
+  const lines = [
+    "Analyze the frontend performance data in this workspace.",
+    "",
+    `URL: ${url}`,
+    `Page load: ${Math.round(m.loadComplete)}ms | FCP: ${Math.round(m.firstContentfulPaint)}ms | LCP: ${Math.round(m.largestContentfulPaint)}ms | TBT: ${Math.round(m.totalBlockingTime)}ms`,
+    `Heap: ${formatBytes(heapSummary.metadata.totalSize)} total, ${heapSummary.metadata.nodeCount.toLocaleString()} nodes, ${heapSummary.detachedNodes.count} detached DOM nodes`,
+    `Network: ${reqCount} requests, ${formatBytes(totalTransfer)} transferred, ${renderBlocking} render-blocking`,
+    `Long tasks: ${m.longTasks.length}`
+  ];
+  if (hasRuntime) {
+    const rt = traceResult.runtimeTrace;
+    lines.push(`Runtime trace: ${rt.blockingFunctions.length} blocking functions, ${rt.gcEvents.length} GC events (${Math.round(rt.gcEvents.reduce((s, e) => s + e.duration, 0))}ms total)`);
+  }
+  lines.push("", "Available data:", "- /heap/summary.json — parsed heap snapshot", "- /trace/summary.json — page load metrics", "- /trace/network-waterfall.json — request timing and sizes", "- /trace/asset-manifest.json — index of stored assets");
+  if (hasRuntime) {
+    lines.push("- /trace/runtime/summary.json — runtime trace overview", "- /trace/runtime/blocking-functions.json — main thread blocking functions", "- /trace/runtime/event-listeners.json — listener add/remove counts", "- /trace/runtime/frame-breakdown.json — scripting vs layout vs paint vs GC", "- /trace/runtime/raw-events.json — full Chrome trace events");
+  }
+  lines.push("- /scripts/ — JavaScript source files", "- /styles/ — CSS source files", "- /html/document.html — page markup", "", "Explore the workspace, read source files to verify root causes, and provide code-level fixes.");
+  return lines.join(`
+`);
+}
+async function analyze(model, backend, spinner, context) {
   const agent = createDeepAgent({
     model,
     systemPrompt: SYSTEM_PROMPT,
     backend,
     responseFormat: providerStrategy(FindingsSchema)
   });
-  const userMessage = [
+  const userMessage = context ? buildPageLoadUserMessage(context) : [
     "Analyze the frontend performance data in this workspace.",
     "",
-    "The workspace contains heap snapshot data, page-load trace data, and Chrome runtime trace data.",
-    "",
     "Start by reading /heap/summary.json, /trace/summary.json, and /trace/runtime/summary.json",
-    "to understand the overall picture. Then explore:",
-    "",
-    "- /trace/network-waterfall.json for request timing",
-    "- /trace/runtime/blocking-functions.json for function-level main thread blocking",
-    "- /trace/runtime/event-listeners.json for listener add/remove imbalances",
-    "- /trace/runtime/frame-breakdown.json for frame breakdown (scripting vs layout vs paint vs GC)",
-    "- /scripts/ for the actual JavaScript source code",
-    "- /styles/ for CSS source",
-    "- /html/document.html for the page markup",
-    "",
-    "Look for memory issues (from the heap data), page-load issues (from the network trace),",
-    "and runtime issues (from the Chrome trace — blocking functions, listener leaks, GC pressure).",
-    "When you find a problem, read the actual source file to provide a specific, code-level fix."
+    "to understand the overall picture, then explore source files to verify root causes."
   ].join(`
 `);
   const result = await invokeWithTodoStreaming(agent, userMessage, spinner);
@@ -397,36 +578,44 @@ async function analyze(model, backend, spinner) {
   }
   return findings;
 }
-async function analyzeTestPerformance(model, backend, spinner) {
+function buildVitestUserMessage(ctx) {
+  const { metrics, hasHeapProfiles, hasListenerTracking } = ctx;
+  const lines = [
+    "Analyze the performance of the APPLICATION CODE being tested in this Vitest workspace.",
+    "",
+    `Test suite: ${metrics.suite.totalTests} tests, total duration ${metrics.suite.totalDuration}ms`,
+    `CPU breakdown: application ${metrics.cpu.applicationPercent}%, dependencies ${metrics.cpu.dependencyPercent}%, GC ${metrics.cpu.gcPercentage}%, idle ${metrics.cpu.idlePercentage}%`,
+    `Slowest file: ${metrics.suite.slowestFile} (${metrics.suite.slowestFileDuration}ms)`,
+    `Slowest test: ${metrics.suite.slowestTestName} (${metrics.suite.slowestTestDuration}ms)`,
+    "",
+    "Available data:",
+    "- /hot-functions/application.json — application-level CPU hotspots",
+    "- /scripts/application.json — per-file CPU time for application code",
+    "- /hot-functions/dependencies.json — dependency CPU hotspots",
+    "- /scripts/dependencies.json — per-file CPU time for dependencies"
+  ];
+  if (hasListenerTracking) {
+    lines.push("- /listener-tracking.json — event listener add/remove patterns and exceedances");
+  }
+  if (hasHeapProfiles) {
+    lines.push("- /heap-profiles/index.json — heap profile manifest", "- /heap-profiles/<file>.json — per-file allocation hotspots");
+  }
+  lines.push("- /summary.json — overall test run summary", "- /timing/overview.json — per-file test durations", "- /timing/slow-tests.json — tests exceeding the slow threshold", "- /profiles/ — full CPU profile summaries with call trees", "- /metrics/current.json — pre-computed aggregate metrics", "- /src/ and /tests/ — source files", "", "Focus findings on the APPLICATION code — what can the developer change in their own", "codebase to improve performance? Read source files to verify root causes before suggesting fixes.");
+  return lines.join(`
+`);
+}
+async function analyzeTestPerformance(model, backend, spinner, context) {
   const agent = createDeepAgent({
     model,
     systemPrompt: VITEST_SYSTEM_PROMPT,
     backend,
     responseFormat: providerStrategy(FindingsSchema)
   });
-  const userMessage = [
+  const userMessage = context ? buildVitestUserMessage(context) : [
     "Analyze the performance of the APPLICATION CODE being tested in this Vitest workspace.",
     "",
-    "Follow this order:",
-    "1. Read /hot-functions/application.json — these are the hotspots IN the user's own code",
-    "2. Read /scripts/application.json — per-file CPU time for application source files",
-    "3. Read /hot-functions/dependencies.json — expensive dependency calls",
-    "4. If present, read /heap-profiles/index.json and /heap-profiles/<file>.json for allocation hotspots",
-    "5. If present, read /listener-tracking.json — event listener add/remove patterns",
-    "   from worker processes. Look for exceedances (too many listeners on a single target)",
-    "   and add/remove imbalances (listeners registered but never cleaned up).",
-    "6. Read /summary.json and /timing/overview.json for the big picture",
-    "7. Read CPU profiles in /profiles/ for detailed call trees",
-    "8. Read source files in /src/ and /tests/ to understand root causes and propose code-level fixes",
-    "",
-    "Focus findings on the APPLICATION code — what can the developer change in their own codebase",
-    "to improve performance? Dependency bottlenecks are worth reporting if the developer can",
-    "reduce how they call the dependency or choose an alternative.",
-    "",
-    "If /listener-tracking.json is present, analyze exceedances and imbalances.",
-    "For listener exceedances (e.g. AbortSignal with 15 abort listeners when max is 10),",
-    "use the stack trace to identify the code adding listeners and suggest proper cleanup",
-    "(e.g. AbortController, removeEventListener, { once: true })."
+    "Start with /hot-functions/application.json, then explore source files to verify",
+    "root causes and provide code-level fixes."
   ].join(`
 `);
   const result = await invokeWithTodoStreaming(agent, userMessage, spinner);
@@ -1898,16 +2087,40 @@ function generateMarkdown(options) {
       sections.push(`## ${emoji} ${f.title}`);
       sections.push("");
       const context = [`**${categoryLabel}**`];
+      if (f.confidence)
+        context.push(`confidence: ${f.confidence}`);
       if (f.impactMs != null)
         context.push(`${f.impactMs.toFixed(0)}ms impact`);
+      if (f.estimatedSavingsMs != null)
+        context.push(`~${f.estimatedSavingsMs.toFixed(0)}ms savings`);
       if (f.retainedSize != null)
         context.push(`${formatBytes2(f.retainedSize)} retained`);
+      if (f.sourceFile)
+        context.push(`\`${f.sourceFile}${f.lineNumber != null ? `:${f.lineNumber}` : ""}\``);
       if (f.resourceUrl)
         context.push(`\`${f.resourceUrl}\``);
       sections.push(context.join(" · "));
       sections.push("");
       sections.push(f.description);
       sections.push("");
+      if (f.beforeCode || f.afterCode) {
+        if (f.beforeCode) {
+          sections.push(`### Before`);
+          sections.push("");
+          sections.push("```js");
+          sections.push(f.beforeCode);
+          sections.push("```");
+          sections.push("");
+        }
+        if (f.afterCode) {
+          sections.push(`### After`);
+          sections.push("");
+          sections.push("```js");
+          sections.push(f.afterCode);
+          sections.push("```");
+          sections.push("");
+        }
+      }
       if (f.suggestedFix) {
         sections.push(`### How to fix`);
         sections.push("");
@@ -2043,19 +2256,47 @@ function generateTestMarkdown(options) {
       sections.push(`## ${emoji} ${f.title}`);
       sections.push("");
       const context = [`**${categoryLabel}**`];
+      if (f.confidence)
+        context.push(`confidence: ${f.confidence}`);
       if (f.impactMs != null)
         context.push(`${f.impactMs.toFixed(0)}ms impact`);
+      if (f.estimatedSavingsMs != null)
+        context.push(`~${f.estimatedSavingsMs.toFixed(0)}ms savings`);
       if (f.testFile)
         context.push(`\`${f.testFile}\``);
       if (f.hotFunction) {
         context.push(`\`${f.hotFunction.name}\` (${f.hotFunction.selfTime.toFixed(0)}ms, ${f.hotFunction.selfPercent.toFixed(1)}%)`);
       }
+      if (f.sourceFile)
+        context.push(`\`${f.sourceFile}${f.lineNumber != null ? `:${f.lineNumber}` : ""}\``);
       if (f.resourceUrl)
         context.push(`\`${f.resourceUrl}\``);
       sections.push(context.join(" · "));
       sections.push("");
+      if (f.affectedTests && f.affectedTests.length > 0) {
+        sections.push(`**Affected tests:** ${f.affectedTests.map((t) => `\`${t}\``).join(", ")}`);
+        sections.push("");
+      }
       sections.push(f.description);
       sections.push("");
+      if (f.beforeCode || f.afterCode) {
+        if (f.beforeCode) {
+          sections.push(`### Before`);
+          sections.push("");
+          sections.push("```ts");
+          sections.push(f.beforeCode);
+          sections.push("```");
+          sections.push("");
+        }
+        if (f.afterCode) {
+          sections.push(`### After`);
+          sections.push("");
+          sections.push("```ts");
+          sections.push(f.afterCode);
+          sections.push("```");
+          sections.push("");
+        }
+      }
       if (f.suggestedFix) {
         sections.push(`### How to fix`);
         sections.push("");
@@ -2207,7 +2448,11 @@ async function main() {
     const agentSpinner = createSpinner("Analyzing...");
     let findings;
     try {
-      findings = await analyze(model, workspace.backend, agentSpinner);
+      findings = await analyze(model, workspace.backend, agentSpinner, {
+        url,
+        heapSummary,
+        traceResult: captureResult.trace
+      });
       agentSpinner.succeed(`Analysis complete — ${findings.length} findings`);
     } catch (err) {
       agentSpinner.fail(`Analysis failed: ${err instanceof Error ? err.message : "Unknown error"}`);

package/dist/output/report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/output/report.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAoC/D,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAI9E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAiH/D;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAItF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAuNvE"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/output/report.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAoC/D,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAI9E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAwI/D;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAItF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAoPvE"}

package/dist/schema.d.ts

@@ -23,10 +23,21 @@ export declare const FindingSchema: z.ZodObject<{
     resourceUrl: z.ZodOptional<z.ZodString>;
     workspacePath: z.ZodOptional<z.ZodString>;
     impactMs: z.ZodOptional<z.ZodNumber>;
+    estimatedSavingsMs: z.ZodOptional<z.ZodNumber>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
     retainedSize: z.ZodOptional<z.ZodNumber>;
     retainerPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sourceFile: z.ZodOptional<z.ZodString>;
+    lineNumber: z.ZodOptional<z.ZodNumber>;
     suggestedFix: z.ZodString;
+    beforeCode: z.ZodOptional<z.ZodString>;
+    afterCode: z.ZodOptional<z.ZodString>;
     testFile: z.ZodOptional<z.ZodString>;
+    affectedTests: z.ZodOptional<z.ZodArray<z.ZodString>>;
     hotFunction: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
         scriptUrl: z.ZodString;
@@ -48,10 +59,21 @@ export declare const FindingsSchema: z.ZodObject<{
         resourceUrl: z.ZodOptional<z.ZodString>;
         workspacePath: z.ZodOptional<z.ZodString>;
         impactMs: z.ZodOptional<z.ZodNumber>;
+        estimatedSavingsMs: z.ZodOptional<z.ZodNumber>;
+        confidence: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>>;
         retainedSize: z.ZodOptional<z.ZodNumber>;
         retainerPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sourceFile: z.ZodOptional<z.ZodString>;
+        lineNumber: z.ZodOptional<z.ZodNumber>;
         suggestedFix: z.ZodString;
+        beforeCode: z.ZodOptional<z.ZodString>;
+        afterCode: z.ZodOptional<z.ZodString>;
         testFile: z.ZodOptional<z.ZodString>;
+        affectedTests: z.ZodOptional<z.ZodArray<z.ZodString>>;
         hotFunction: z.ZodOptional<z.ZodObject<{
             name: z.ZodString;
             scriptUrl: z.ZodString;

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,iaA2BjB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;iBAwBxB,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;iBAEzB,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,iaA2BjB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwDxB,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEzB,CAAC"}