From b7b5a33e32c4d1a4d900c47c4d23f9f42161f599 Mon Sep 17 00:00:00 2001
From: DavertMik <davert@testomat.io>
Date: Sun, 26 Apr 2026 17:27:06 +0300
Subject: [PATCH 1/4] feat(mcp): snapshot tool, run_code return/console
 capture, storage state, HTML cleanup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a `snapshot` MCP tool that captures the current browser state without
performing any action. `run_code` now also returns the value the code
produced and captures `console.*` output (level + message + relative time)
using the existing `safeStringify` from lib/utils.js with a `truncateString`
helper, so models can use debug statements and inspect return values.

Captures cookies + localStorage via Playwright's `grabStorageState()` (with
a `grabCookie + executeScript` fallback for Puppeteer/WebDriver),
normalized to a single shape and saved as `_storage.json` alongside the
other artifacts.

Centralizes the artifact-grab + trace-record glue:
- New `lib/utils/captureSnapshot.js` is the single funnel for HTML / ARIA /
  screenshot / console / storage capture.
- New `lib/utils/trace.js` holds shared helpers (`pickActingHelper`,
  `traceDirFor`, `snapshotDirFor`, `artifactLinks`, `artifactsToFileUrls`)
  used by `aiTrace`, `pageInfo`, and the MCP server.
- aiTrace and pageInfo now go through the same funnel — pageInfo's three
  serial recorder steps collapse to one delegated capture.

HTML processing pipeline (`formatHtml` in `lib/html.js`): minify ->
cleanHtml -> beautify. `cleanHtml` (new) drops `<script>` (no src) /
`<style>` / `<noscript>`, strips trash class names (Tailwind utilities,
hashed/scoped/framework-generated), and removes inline `style=""`. Built
on `js-beautify` (already a dep) instead of a hand-rolled pretty-printer.

Browser-log normalization fixes a latent bug where `JSON.stringify` was
called on Playwright `ConsoleMessage` objects, producing files full of
empty objects. Logs are now coerced to plain `{type, text}` (or kept as
strings for WebDriver) before serialization.

`safeStringify` in lib/utils.js is extended to also coerce
Function/Error/BigInt/Symbol values — universal improvements that close
a JSON.stringify(BigInt) crash and don't regress the existing 12 mocha
serialization tests.

Tests: 72 unit tests passing (12 circular_reference + 23 html (incl. new
`#cleanHtml`, `#formatHtml`, `#isTrashClass` describes) + 13 aiTrace + 32
mcp + 1 pending). Docs updated in `docs/mcp.md` and `docs/aitrace.md`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 bin/mcp-server.js            | 238 ++++++++++++++++++++++++++---------
 docs/aitrace.md              |   8 +-
 docs/mcp.md                  | 116 +++++++++++++----
 lib/html.js                  | 103 ++++++++++++---
 lib/plugin/aiTrace.js        | 113 +++++------------
 lib/plugin/pageInfo.js       |  93 +++++++-------
 lib/utils.js                 |  25 ++++
 lib/utils/captureSnapshot.js | 130 +++++++++++++++++++
 lib/utils/trace.js           |  71 +++++++++++
 test/unit/html_test.js       |  87 ++++++++++++-
 10 files changed, 753 insertions(+), 231 deletions(-)
 create mode 100644 lib/utils/captureSnapshot.js
 create mode 100644 lib/utils/trace.js

diff --git a/bin/mcp-server.js b/bin/mcp-server.js
index fba958125..47a49a2df 100644
--- a/bin/mcp-server.js
+++ b/bin/mcp-server.js
@@ -4,12 +4,19 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import Codecept from '../lib/codecept.js'
 import container from '../lib/container.js'
 import { getParamsToString } from '../lib/parser.js'
-import { methodsOfObject } from '../lib/utils.js'
+import { methodsOfObject, safeStringify, truncateString } from '../lib/utils.js'
+import { captureSnapshot } from '../lib/utils/captureSnapshot.js'
+import {
+  pickActingHelper,
+  traceDirFor,
+  snapshotDirFor,
+  artifactLinks,
+  artifactsToFileUrls,
+} from '../lib/utils/trace.js'
 import event from '../lib/event.js'
 import { fileURLToPath } from 'url'
 import { dirname, resolve as resolvePath } from 'path'
 import path from 'path'
-import crypto from 'crypto'
 import { spawn } from 'child_process'
 import { createRequire } from 'module'
 import { existsSync, readdirSync, writeFileSync } from 'fs'
@@ -224,15 +231,32 @@ async function resolveTestToFile({ cli, root, configPath, test }) {
   return fsFound ? normalizePath(fsFound) : null
 }
 
-function clearString(str) {
-  return str.replace(/[^a-zA-Z0-9]/g, '_')
+function outputBaseDir() {
+  return global.output_dir || resolvePath(process.cwd(), 'output')
 }
 
-function getTraceDir(testTitle, testFile) {
-  const hash = crypto.createHash('sha256').update(testFile + testTitle).digest('hex').slice(0, 8)
-  const cleanTitle = clearString(testTitle).slice(0, 200)
-  const outputDir = global.output_dir || resolvePath(process.cwd(), 'output')
-  return resolvePath(outputDir, `trace_${cleanTitle}_${hash}`)
+function writeTraceMarkdown({ dir, title, file, durationMs, commands, captured, error }) {
+  let md = `file: ${file || 'mcp'}\n`
+  md += `name: ${title}\n`
+  md += `time: ${(durationMs / 1000).toFixed(2)}s\n`
+  md += `---\n\n`
+
+  if (error) md += `Error: ${error}\n\n---\n\n`
+
+  if (commands && commands.length) {
+    md += `### Commands\n`
+    for (const c of commands) md += `- ${c}\n`
+    md += `\n`
+  }
+
+  md += `### Final State\n`
+  if (captured.url) md += `  > URL: ${captured.url}\n`
+  const links = artifactLinks(captured)
+  if (links) md += links + '\n'
+
+  const traceFile = path.join(dir, 'trace.md')
+  writeFileSync(traceFile, md)
+  return traceFile
 }
 
 async function initCodecept(configPath) {
@@ -337,6 +361,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       description: 'Stop the browser session.',
       inputSchema: { type: 'object', properties: {} },
     },
+    {
+      name: 'snapshot',
+      description: 'Capture current browser state (HTML, ARIA, screenshot, console, URL) without performing any action.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          config: { type: 'string' },
+          fullPage: { type: 'boolean' },
+        },
+      },
+    },
   ],
 }))
 
@@ -416,6 +451,39 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: 'text', text: JSON.stringify({ status: 'Browser stopped successfully' }, null, 2) }] }
       }
 
+      case 'snapshot': {
+        const { config: configPath, fullPage = false } = args || {}
+        await initCodecept(configPath)
+
+        const helper = pickActingHelper(container.helpers())
+        if (!helper) throw new Error('No supported acting helper available (Playwright, Puppeteer, WebDriver).')
+
+        const dir = snapshotDirFor(outputBaseDir())
+        mkdirp.sync(dir)
+
+        const captured = await captureSnapshot(helper, { dir, prefix: 'snapshot', fullPage })
+        const traceFile = writeTraceMarkdown({
+          dir,
+          title: 'snapshot',
+          file: 'mcp',
+          durationMs: 0,
+          commands: [],
+          captured,
+        })
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              status: 'success',
+              dir,
+              traceFile: `file://${traceFile}`,
+              artifacts: artifactsToFileUrls(captured, dir),
+            }, null, 2),
+          }],
+        }
+      }
+
       case 'run_code': {
         const { code, timeout = 60000, config: configPath, saveArtifacts = true } = args
         await initCodecept(configPath)
@@ -423,67 +491,92 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const I = container.support('I')
         if (!I) throw new Error('I object not available. Make sure helpers are configured.')
 
-        const result = { status: 'unknown', output: '', error: null, artifacts: {} }
+        const result = { status: 'unknown', output: '', error: null, commands: [], artifacts: {} }
+
+        const commands = []
+        const onStepAfter = step => {
+          try { commands.push(step.toString()) } catch {}
+        }
+        event.dispatcher.on(event.step.after, onStepAfter)
+
+        const traceDir = traceDirFor(`mcp_${Date.now()}`, 'run_code', outputBaseDir())
+        mkdirp.sync(traceDir)
+        const startedAt = Date.now()
+
+        const MAX_LOG_ENTRIES = 100
+        const MAX_LOG_MSG_BYTES = 2000
+        const MAX_RETURN_BYTES = 20000
+        const consoleLogs = []
+        const consoleMethods = ['log', 'info', 'warn', 'error', 'debug']
+        const origConsoleMethods = {}
+        const captureLog = level => (...args) => {
+          if (consoleLogs.length >= MAX_LOG_ENTRIES) return
+          const message = args.map(a => {
+            if (typeof a === 'string') return a
+            return truncateString(safeStringify(a, [], 2), MAX_LOG_MSG_BYTES).value
+          }).join(' ')
+          consoleLogs.push({ level, message, t: Date.now() - startedAt })
+        }
+        for (const m of consoleMethods) {
+          origConsoleMethods[m] = console[m]
+          console[m] = captureLog(m)
+        }
 
+        let returnValue
         try {
           const asyncFn = new Function('I', `return (async () => { ${code} })()`)
-          await Promise.race([
+          returnValue = await Promise.race([
             asyncFn(I),
             new Promise((_, reject) => setTimeout(() => reject(new Error(`Timeout after ${timeout}ms`)), timeout)),
           ])
 
           result.status = 'success'
           result.output = 'Code executed successfully'
-
-          if (saveArtifacts) {
-            const helpers = container.helpers()
-            const helper = Object.values(helpers)[0]
-            if (helper) {
-              try {
-                const traceDir = getTraceDir('mcp', 'run_code')
-                mkdirp.sync(traceDir)
-
-                if (helper.grabAriaSnapshot) {
-                  const aria = await helper.grabAriaSnapshot()
-                  const ariaFile = path.join(traceDir, 'aria.txt')
-                  writeFileSync(ariaFile, aria)
-                  result.artifacts.aria = `file://${ariaFile}`
-                }
-
-                if (helper.grabCurrentUrl) {
-                  result.artifacts.url = await helper.grabCurrentUrl()
-                }
-
-                if (helper.grabBrowserLogs) {
-                  const logs = (await helper.grabBrowserLogs()) || []
-                  const logsFile = path.join(traceDir, 'console.json')
-                  writeFileSync(logsFile, JSON.stringify(logs, null, 2))
-                  result.artifacts.consoleLogs = `file://${logsFile}`
-                }
-
-                if (helper.grabSource) {
-                  const html = await helper.grabSource()
-                  const htmlFile = path.join(traceDir, 'page.html')
-                  writeFileSync(htmlFile, html)
-                  result.artifacts.html = `file://${htmlFile}`
-                }
-
-                if (helper.saveScreenshot) {
-                  const screenshotFile = path.join(traceDir, 'screenshot.png')
-                  await helper.saveScreenshot(screenshotFile)
-                  result.artifacts.screenshot = `file://${screenshotFile}`
-                }
-              } catch (e) {
-                result.output += ` (Warning: ${e.message})`
-              }
-            }
-          }
         } catch (error) {
           result.status = 'failed'
           result.error = error.message
           result.output = error.stack || error.message
+        } finally {
+          for (const m of consoleMethods) console[m] = origConsoleMethods[m]
+          try { event.dispatcher.removeListener(event.step.after, onStepAfter) } catch {}
         }
 
+        result.commands = commands
+        result.logs = consoleLogs
+        if (consoleLogs.length === MAX_LOG_ENTRIES) result.logsTruncated = true
+
+        if (returnValue !== undefined) {
+          const json = typeof returnValue === 'string' ? returnValue : safeStringify(returnValue, [], 2)
+          const stringified = truncateString(json, MAX_RETURN_BYTES)
+          result.returnValue = stringified.value
+          if (stringified.truncated) result.returnValueTruncated = true
+        }
+
+        let captured = {}
+        if (saveArtifacts) {
+          const helper = pickActingHelper(container.helpers())
+          if (helper) {
+            try {
+              captured = await captureSnapshot(helper, { dir: traceDir, prefix: 'mcp' })
+              result.artifacts = artifactsToFileUrls(captured, traceDir)
+            } catch (e) {
+              result.output += ` (Warning: ${e.message})`
+            }
+          }
+        }
+
+        const traceFile = writeTraceMarkdown({
+          dir: traceDir,
+          title: 'run_code',
+          file: 'mcp',
+          durationMs: Date.now() - startedAt,
+          commands,
+          captured,
+          error: result.error,
+        })
+        result.dir = traceDir
+        result.traceFile = `file://${traceFile}`
+
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
       }
 
@@ -549,27 +642,56 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
           const results = []
           const currentSteps = {}
+          const traceDirs = {}
           let currentTestTitle = null
           const testFile = testFiles[0]
 
           const onBefore = (t) => {
-            const traceDir = getTraceDir(t.title, t.file)
+            const traceDir = traceDirFor(t.file, t.title, outputBaseDir())
             currentTestTitle = t.title
             currentSteps[t.title] = []
+            traceDirs[t.title] = traceDir
             results.push({
               test: t.title,
               file: t.file,
-              traceFile: `file://${resolvePath(traceDir, 'trace.md')}`,
               status: 'running',
               steps: [],
             })
           }
 
-          const onAfter = (t) => {
+          const onAfter = async (t) => {
             const r = results.find(x => x.test === t.title)
             if (r) {
               r.status = t.err ? 'failed' : 'completed'
               if (t.err) r.error = t.err.message
+
+              if (t.artifacts?.aiTrace) {
+                r.traceFile = `file://${t.artifacts.aiTrace}`
+              }
+              if (t.artifacts?.har) r.har = `file://${t.artifacts.har}`
+              if (t.artifacts?.trace) r.trace = `file://${t.artifacts.trace}`
+
+              if (!t.artifacts?.aiTrace) {
+                try {
+                  const helper = pickActingHelper(container.helpers())
+                  const dir = traceDirs[t.title]
+                  if (helper && dir) {
+                    mkdirp.sync(dir)
+                    const captured = await captureSnapshot(helper, { dir, prefix: 'final' })
+                    r.artifacts = artifactsToFileUrls(captured, dir)
+                    const tracePath = writeTraceMarkdown({
+                      dir,
+                      title: t.title,
+                      file: t.file,
+                      durationMs: 0,
+                      commands: (currentSteps[t.title] || []).map(s => s.step),
+                      captured,
+                      error: r.error,
+                    })
+                    r.traceFile = `file://${tracePath}`
+                  }
+                } catch {}
+              }
             }
             currentTestTitle = null
           }
diff --git a/docs/aitrace.md b/docs/aitrace.md
index e96182d53..51761dd22 100644
--- a/docs/aitrace.md
+++ b/docs/aitrace.md
@@ -53,16 +53,18 @@ For each test, a `trace_<sha256>` directory is created with the following files:
 
 **0000_step_name_screenshot.png** - Screenshot for each step (file names include step names)
 
-**0000_step_name_page.html** - Full HTML of the page at each step
+**0000_step_name_page.html** - Full HTML of the page at each step. Processed through a `minify -> clean -> beautify` pipeline so the file is multi-line indented, free of `<script>` / `<style>` / `<noscript>` content, free of inline `style=""` attributes, and free of trash class names (Tailwind utilities, framework-generated `v-*` / `ember-*`, hashed classes, scoped `xl:hidden`-style classes). Semantic attributes (`id`, `aria-*`, `data-*`, `role`, etc.) are preserved.
 
-**0000_step_name_aria.txt** - ARIA accessibility snapshot (AI-readable structure without HTML noise)
+**0000_step_name_aria.txt** - ARIA accessibility snapshot (AI-readable structure without HTML noise; Playwright only)
 
-**0000_step_name_console.json** - Browser console logs
+**0000_step_name_console.json** - Browser console logs, normalized to plain `{ type, text }` objects (Playwright `ConsoleMessage` instances are coerced via their `.type()` / `.text()` methods so the JSON file is genuinely useful — not full of empty objects).
 
 When HAR or trace recording is enabled in your helper config, links to those files are also included.
 
 **Note:** Artifact files are named using step names for easier identification (e.g., `0000_I_see_Product_screenshot.png` instead of just `0000_screenshot.png`).
 
+**Storage state:** Cookies and `localStorage` are intentionally **not** captured per-step by `aiTrace` (they rarely change between actions, so per-step `_storage.json` files would be noise). Use the `pageInfo` plugin or the MCP `snapshot()` tool when you need a storage snapshot.
+
 ## Trace File Format
 
 The `trace.md` file contains a structured execution log with links to all artifacts:
diff --git a/docs/mcp.md b/docs/mcp.md
index 70e914e3e..d8d042bb0 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -7,11 +7,12 @@ Model Context Protocol (MCP) server for CodeceptJS enables AI agents (like Claud
 The MCP server provides AI agents with tools to:
 - List all tests in a CodeceptJS project
 - List all available CodeceptJS actions (I.* methods)
-- Run arbitrary CodeceptJS code with artifacts capture
+- Run arbitrary CodeceptJS code with artifacts capture, return value, and `console.log` capture
 - Run specific tests with detailed output
 - Run tests step by step for detailed analysis
+- Capture a point-in-time snapshot of the browser without any action
 - Start and stop browser sessions
-- Capture screenshots, ARIA snapshots, HTML, and console logs
+- Capture screenshots, ARIA snapshots, formatted HTML, browser console logs, and storage state (cookies + localStorage)
 
 ## Installation
 
@@ -145,13 +146,13 @@ List all available CodeceptJS actions (I.* methods) from enabled helpers and sup
 
 ### run_code
 
-Run arbitrary CodeceptJS code. Returns status, ARIA snapshot, URL, console logs, and HTML.
+Run arbitrary CodeceptJS code. The tool captures the value the code returns, every `I.*` step it runs, anything written to `console.log` / `console.info` / `console.warn` / `console.error` / `console.debug`, plus a final-state snapshot of the page.
 
 **Parameters:**
-- `code` (required): CodeceptJS code to execute
+- `code` (required): CodeceptJS code to execute. May `return` a value and use `console.*` for debugging.
 - `timeout` (optional): Timeout in milliseconds (default: 60000)
 - `config` (optional): Path to codecept.conf.js
-- `saveArtifacts` (optional): Save artifacts like ARIA, URL, console logs, HTML (default: true)
+- `saveArtifacts` (optional): Save final-state artifacts to disk (default: true)
 
 **Returns:**
 ```json
@@ -159,27 +160,81 @@ Run arbitrary CodeceptJS code. Returns status, ARIA snapshot, URL, console logs,
   "status": "success",
   "output": "Code executed successfully",
   "error": null,
+  "commands": [
+    "I.amOnPage(\"/\")",
+    "I.grabTextFrom(\"h1\")"
+  ],
+  "logs": [
+    { "level": "log", "message": "headline Welcome", "t": 47 }
+  ],
+  "returnValue": "{\n  \"url\": \"http://localhost:8000/\",\n  \"text\": \"Welcome\"\n}",
   "artifacts": {
-    "aria": "main -> \"Welcome\"...",
     "url": "http://localhost:8000/",
-    "consoleLogs": [],
-    "html": "<html>...</html>"
-  }
+    "html": "file:///output/trace_run_code_.../mcp_page.html",
+    "aria": "file:///output/trace_run_code_.../mcp_aria.txt",
+    "screenshot": "file:///output/trace_run_code_.../mcp_screenshot.png",
+    "console": "file:///output/trace_run_code_.../mcp_console.json",
+    "storage": "file:///output/trace_run_code_.../mcp_storage.json",
+    "cookieCount": 3,
+    "localStorageCount": 5
+  },
+  "dir": "/output/trace_run_code_...",
+  "traceFile": "file:///output/trace_run_code_.../trace.md"
 }
 ```
 
+**Notes:**
+- `returnValue` is the value the code's last `return` statement produced, JSON-stringified with circular-ref handling. Capped at 20 KB; `returnValueTruncated: true` is set if it was cut.
+- `logs` is an in-order list of console output captured during execution. Each entry has `{ level, message, t }` where `t` is ms since the code started. Capped at 100 entries × 2 KB per message; `logsTruncated: true` is set if hit. `console.*` writes do not pollute MCP stdio — they're captured in-memory only.
+- `commands` is the list of `I.*` calls observed during execution (via the recorder).
+- `artifacts.storage` is omitted when both cookies and localStorage are empty.
+
 **Example:**
 ```json
 {
   "name": "run_code",
   "arguments": {
-    "code": "await I.amOnPage('/'); await I.see('Welcome');",
-    "timeout": 30000,
-    "saveArtifacts": true
+    "code": "await I.amOnPage('/'); const t = await I.grabTextFrom('h1'); console.log('headline', t); return { url: await I.grabCurrentUrl(), text: t };",
+    "timeout": 30000
   }
 }
 ```
 
+### snapshot
+
+Capture the current state of the browser without performing any action. Useful for inspecting what's on the page right now (URL, cookies, localStorage, formatted HTML, ARIA, screenshot, browser console logs) when reasoning between actions.
+
+**Parameters:**
+- `config` (optional): Path to codecept.conf.js
+- `fullPage` (optional): Take a full-page screenshot (default: false)
+
+**Returns:**
+```json
+{
+  "status": "success",
+  "dir": "/output/snapshot_1700000000000_abcd1234",
+  "traceFile": "file:///output/snapshot_.../trace.md",
+  "artifacts": {
+    "url": "http://localhost:8000/dashboard",
+    "html": "file:///output/snapshot_.../snapshot_page.html",
+    "aria": "file:///output/snapshot_.../snapshot_aria.txt",
+    "screenshot": "file:///output/snapshot_.../snapshot_screenshot.png",
+    "console": "file:///output/snapshot_.../snapshot_console.json",
+    "storage": "file:///output/snapshot_.../snapshot_storage.json",
+    "cookieCount": 3,
+    "localStorageCount": 5
+  }
+}
+```
+
+**Example:**
+```json
+{
+  "name": "snapshot",
+  "arguments": { "fullPage": true }
+}
+```
+
 ### run_test
 
 Run a specific test by name or file path. Uses subprocess to run tests with isolation.
@@ -378,17 +433,20 @@ When using `run_step_by_step`, the server generates trace files that provide ric
 ```
 output/
 └── trace_Test_Name_abc123/
-    ├── 0000_screenshot.png     # Screenshot after step 0
-    ├── 0000_page.html         # HTML snapshot after step 0
-    ├── 0000_aria.txt          # ARIA snapshot after step 0
-    ├── 0000_console.json      # Console logs after step 0
-    ├── 0001_screenshot.png     # Screenshot after step 1
-    ├── 0001_page.html
-    ├── 0001_aria.txt
-    ├── 0001_console.json
-    └── trace.md               # AI-friendly summary
+    ├── 0000_<step>_screenshot.png   # Screenshot after step 0
+    ├── 0000_<step>_page.html        # Formatted HTML (minified -> trash classes/scripts/styles stripped -> beautified)
+    ├── 0000_<step>_aria.txt         # ARIA snapshot after step 0 (Playwright only)
+    ├── 0000_<step>_console.json     # Browser console logs (normalized to {type, text})
+    ├── 0001_<step>_screenshot.png
+    ├── 0001_<step>_page.html
+    ├── 0001_<step>_aria.txt
+    ├── 0001_<step>_console.json
+    ├── final_storage.json           # Cookies + localStorage at test end (run_step_by_step fallback)
+    └── trace.md                     # AI-friendly summary with links to all of the above
 ```
 
+For ad-hoc `run_code` and `snapshot()` runs, only a single set of artifacts is produced (`mcp_*` / `snapshot_*` prefix), since there are no per-step iterations.
+
 ### Using Trace Files with AI
 
 The `trace.md` file provides structured information perfect for AI analysis:
@@ -424,6 +482,22 @@ AI agents can use these artifacts to:
 - Debug issues using HTML snapshots
 - Identify errors from console logs
 
+## HTML Formatting
+
+Every HTML snapshot saved by the MCP server (and the aiTrace / pageInfo plugins, since they share the same `captureSnapshot` funnel in `lib/utils/captureSnapshot.js`) is processed through a three-stage pipeline before being written to disk:
+
+1. **Minify** (via `html-minifier-terser`) — strips comments, collapses whitespace, removes redundant attributes.
+2. **Clean** — drops `<style>`, `<noscript>`, and inline `<script>` (no `src`) blocks entirely; preserves `<script src="...">`; strips trash class names (Tailwind utilities `text-*`, `flex-*`, `border-*`, framework-generated `v-*`, `ember-*`, `Header__title`, hashed classes containing digits, and `xl:hidden`-style scoped classes); drops `style="..."` attributes. Semantic attributes (`id`, `aria-*`, `data-*`, `role`, `href`, `src`, `alt`, `title`, `name`) are kept.
+3. **Beautify** (via `js-beautify`) — re-indents with 2-space indentation; keeps inline elements like `<strong>` / `<a>` on the same line as their text.
+
+The result is a multi-line, low-noise HTML document that's far cheaper for an LLM to reason about than raw page source.
+
+## Storage State
+
+When a Playwright helper is configured, `captureSnapshot` calls `helper.grabStorageState()` to dump cookies + localStorage in one go. For Puppeteer / WebDriver, it falls back to `helper.grabCookie()` plus an `executeScript()` call that walks `window.localStorage`. Both paths produce the same shape (`{ cookies: [...], origins: [{ origin, localStorage: [...] }] }`) so AI agents see a consistent storage payload regardless of the helper.
+
+Storage capture is **disabled per-step in aiTrace** (cookies / localStorage rarely change between actions, so per-step files would be noise) and **enabled by default** for `run_code`, `snapshot`, `run_step_by_step` fallback, and `pageInfo`.
+
 ## Architecture
 
 ### Request Flow
diff --git a/lib/html.js b/lib/html.js
index 6edaef3f4..7184762a6 100644
--- a/lib/html.js
+++ b/lib/html.js
@@ -1,5 +1,8 @@
 import { parse, serialize } from 'parse5'
 import { minify } from 'html-minifier-terser'
+import beautify from 'js-beautify'
+
+const { html: html_beautify } = beautify
 
 async function minifyHtml(html) {
   return minify(html, {
@@ -14,6 +17,62 @@ async function minifyHtml(html) {
   })
 }
 
+const TRASH_HTML_CLASSES = /^(text-|color-|flex-|float-|v-|ember-|d-|border-)/
+
+function isTrashClass(className) {
+  if (!className) return true
+  if (/\d/.test(className)) return true
+  if (TRASH_HTML_CLASSES.test(className)) return true
+  if (/(:|__)/.test(className)) return true
+  return false
+}
+
+function filterClassValue(value) {
+  return (value || '')
+    .split(/\s+/)
+    .filter(c => c && !isTrashClass(c))
+    .join(' ')
+}
+
+const DROP_TAGS = new Set(['style', 'noscript'])
+const DROP_ATTRS = new Set(['style'])
+
+function cleanHtml(html) {
+  const document = parse(html)
+
+  function walk(node) {
+    if (!node) return false
+
+    if (DROP_TAGS.has(node.nodeName) || (node.nodeName === 'script' && !(node.attrs || []).some(a => a.name === 'src'))) {
+      const parent = node.parentNode
+      const idx = parent.childNodes.indexOf(node)
+      if (idx >= 0) parent.childNodes.splice(idx, 1)
+      return true
+    }
+
+    if (node.attrs) {
+      node.attrs = node.attrs.filter(attr => {
+        if (DROP_ATTRS.has(attr.name)) return false
+        if (attr.name === 'class') {
+          attr.value = filterClassValue(attr.value)
+          if (!attr.value) return false
+        }
+        return true
+      })
+    }
+
+    if (node.childNodes) {
+      for (let i = node.childNodes.length - 1; i >= 0; i--) {
+        walk(node.childNodes[i])
+      }
+    }
+    return false
+  }
+
+  walk(document)
+  return serialize(document)
+}
+
 const defaultHtmlOpts = {
   interactiveElements: ['a', 'input', 'button', 'select', 'textarea', 'option'],
   textElements: ['label', 'h1', 'h2'],
@@ -28,7 +87,6 @@ function removeNonInteractiveElements(html, opts = {}) {
   // Parse the HTML into a document tree
   const document = parse(html)
 
-  const trashHtmlClasses = /^(text-|color-|flex-|float-|v-|ember-|d-|border-)/
   // Array to store interactive elements
   const removeElements = ['path', 'script']
 
@@ -103,21 +161,10 @@ function removeNonInteractiveElements(html, opts = {}) {
     if (node.attrs) {
       // Filter and keep allowed attributes, accessibility attributes
       node.attrs = node.attrs.filter(attr => {
-        const { name, value } = attr
-        if (name === 'class') {
-          // Remove classes containing digits
-          attr.value = value
-            .split(' ')
-            // remove classes containing digits/
-            .filter(className => !/\d/.test(className))
-            // remove popular trash classes
-            .filter(className => !className.match(trashHtmlClasses))
-            // remove classes with : and __ in them
-            .filter(className => !className.match(/(:|__)/))
-            .join(' ')
+        if (attr.name === 'class') {
+          attr.value = filterClassValue(attr.value)
         }
-
-        return allowedAttrs.includes(name)
+        return allowedAttrs.includes(attr.name)
       })
     }
 
@@ -258,4 +305,28 @@ function simplifyHtmlElement(html, maxLength = 300) {
   return html
 }
 
-export { scanForErrorMessages, removeNonInteractiveElements, splitByChunks, minifyHtml, simplifyHtmlElement }
+async function formatHtml(html) {
+  let processed = html
+  try {
+    processed = await minifyHtml(processed)
+  } catch (e) {
+    // keep raw html if minification fails
+  }
+  try {
+    processed = cleanHtml(processed)
+  } catch (e) {
+    // keep minified html if cleaning fails
+  }
+  try {
+    return html_beautify(processed, {
+      indent_size: 2,
+      wrap_line_length: 0,
+      preserve_newlines: false,
+      end_with_newline: false,
+    })
+  } catch (e) {
+    return processed
+  }
+}
+
+export { scanForErrorMessages, removeNonInteractiveElements, splitByChunks, minifyHtml, simplifyHtmlElement, formatHtml, cleanHtml, isTrashClass }
diff --git a/lib/plugin/aiTrace.js b/lib/plugin/aiTrace.js
index f2668afbc..e61fb3943 100644
--- a/lib/plugin/aiTrace.js
+++ b/lib/plugin/aiTrace.js
@@ -1,8 +1,6 @@
-import crypto from 'crypto'
 import fs from 'fs'
 import { mkdirp } from 'mkdirp'
 import path from 'path'
-import { fileURLToPath } from 'url'
 
 import store from '../store.js'
 import Container from '../container.js'
@@ -10,9 +8,8 @@ import recorder from '../recorder.js'
 import event from '../event.js'
 import output from '../output.js'
 import { deleteDir, clearString } from '../utils.js'
-import colors from 'chalk'
-
-const supportedHelpers = Container.STANDARD_ACTING_HELPERS
+import { captureSnapshot } from '../utils/captureSnapshot.js'
+import { pickActingHelper, traceDirFor, artifactLinks } from '../utils/trace.js'
 
 const defaultConfig = {
   deleteSuccessful: false,
@@ -57,16 +54,9 @@ const defaultConfig = {
  * @param {*} config
  */
 export default function (config) {
-  const helpers = Container.helpers()
-  let helper
-
   config = Object.assign(defaultConfig, config)
 
-  for (const helperName of supportedHelpers) {
-    if (Object.keys(helpers).indexOf(helperName) > -1) {
-      helper = helpers[helperName]
-    }
-  }
+  const helper = pickActingHelper(Container.helpers())
 
   if (!helper) {
     output.warn('aiTrace plugin: No supported helper found (Playwright, Puppeteer, WebDriver). Plugin disabled.')
@@ -106,13 +96,7 @@ export default function (config) {
     } catch (err) {
       title = test.title
     }
-    const testTitle = clearString(title).slice(0, 200)
-    const uniqueHash = crypto
-      .createHash('sha256')
-      .update(test.file + test.title)
-      .digest('hex')
-      .slice(0, 8)
-    dir = path.join(reportDir, `trace_${testTitle}_${uniqueHash}`)
+    dir = traceDirFor(test.file, title, reportDir)
     mkdirp.sync(dir)
     deleteDir(dir)
     mkdirp.sync(dir)
@@ -282,6 +266,7 @@ export default function (config) {
         output.debug(`aiTrace: Browser unavailable, partial artifact capture: ${err.message}`)
       }
 
+      let preExistingScreenshot = false
       if (step.artifacts?.screenshot) {
         const screenshotPath = path.isAbsolute(step.artifacts.screenshot)
           ? step.artifacts.screenshot
@@ -289,6 +274,7 @@ export default function (config) {
         const screenshotFile = path.basename(screenshotPath)
         stepData.artifacts.screenshot = screenshotFile
         step.artifacts.screenshot = screenshotPath
+        preExistingScreenshot = true
 
         if (!fs.existsSync(screenshotPath)) {
           try {
@@ -297,58 +283,31 @@ export default function (config) {
             output.debug(`aiTrace: Could not save screenshot: ${err.message}`)
           }
         }
-      } else {
-        try {
-          const screenshotFile = `${stepPrefix}_screenshot.png`
-          const screenshotPath = path.join(dir, screenshotFile)
-          await helper.saveScreenshot(screenshotPath, config.fullPageScreenshots)
-
-          stepData.artifacts.screenshot = screenshotFile
-          step.artifacts.screenshot = screenshotPath
-        } catch (err) {
-          output.debug(`aiTrace: Could not save screenshot: ${err.message}`)
-        }
       }
 
-      // Save HTML
-      if (config.captureHTML && helper.grabSource && browserAvailable) {
-        if (!step.artifacts?.html) {
-          try {
-            const html = await helper.grabSource()
-            const htmlFile = `${stepPrefix}_page.html`
-            fs.writeFileSync(path.join(dir, htmlFile), html)
-            stepData.artifacts.html = htmlFile
-          } catch (err) {
-            output.debug(`aiTrace: Could not capture HTML: ${err.message}`)
-          }
-        } else {
-          stepData.artifacts.html = step.artifacts.html
-        }
-      }
+      const captured = await captureSnapshot(helper, {
+        dir,
+        prefix: stepPrefix,
+        fullPage: config.fullPageScreenshots,
+        captureHTML: config.captureHTML && browserAvailable,
+        captureARIA: config.captureARIA && browserAvailable,
+        captureBrowserLogs: config.captureBrowserLogs && browserAvailable,
+        captureStorage: false,
+      })
 
-      // Save ARIA snapshot
-      if (config.captureARIA && helper.grabAriaSnapshot && browserAvailable) {
-        try {
-          const aria = await helper.grabAriaSnapshot()
-          const ariaFile = `${stepPrefix}_aria.txt`
-          fs.writeFileSync(path.join(dir, ariaFile), aria)
-          stepData.artifacts.aria = ariaFile
-        } catch (err) {
-          output.debug(`aiTrace: Could not capture ARIA snapshot: ${err.message}`)
-        }
+      if (!preExistingScreenshot && captured.screenshot) {
+        stepData.artifacts.screenshot = captured.screenshot
+        step.artifacts.screenshot = path.join(dir, captured.screenshot)
       }
-
-      // Save browser logs
-      if (config.captureBrowserLogs && helper.grabBrowserLogs && browserAvailable) {
-        try {
-          const logs = await helper.grabBrowserLogs()
-          const logsFile = `${stepPrefix}_console.json`
-          fs.writeFileSync(path.join(dir, logsFile), JSON.stringify(logs || [], null, 2))
-          stepData.artifacts.console = logsFile
-          stepData.meta.consoleCount = logs ? logs.length : 0
-        } catch (err) {
-          output.debug(`aiTrace: Could not capture browser logs: ${err.message}`)
-        }
+      if (step.artifacts?.html) {
+        stepData.artifacts.html = step.artifacts.html
+      } else if (captured.html) {
+        stepData.artifacts.html = captured.html
+      }
+      if (captured.aria) stepData.artifacts.aria = captured.aria
+      if (captured.console) {
+        stepData.artifacts.console = captured.console
+        stepData.meta.consoleCount = captured.consoleCount
       }
     } catch (err) {
       output.plugin(`aiTrace: Can't save step artifacts: ${err}`)
@@ -405,22 +364,8 @@ export default function (config) {
         })
       }
 
-      if (stepData.artifacts.html) {
-        markdown += `  > [HTML](./${stepData.artifacts.html})\n`
-      }
-
-      if (stepData.artifacts.aria) {
-        markdown += `  > [ARIA Snapshot](./${stepData.artifacts.aria})\n`
-      }
-
-      if (stepData.artifacts.screenshot) {
-        markdown += `  > [Screenshot](./${stepData.artifacts.screenshot})\n`
-      }
-
-      if (stepData.artifacts.console) {
-        const count = stepData.meta.consoleCount || 0
-        markdown += `  > [Browser Logs](./${stepData.artifacts.console}) (${count} entries)\n`
-      }
+      const links = artifactLinks(stepData.artifacts, { consoleCount: stepData.meta.consoleCount })
+      if (links) markdown += links + '\n'
 
       if (config.captureHTTP) {
         if (test.artifacts && test.artifacts.har) {
diff --git a/lib/plugin/pageInfo.js b/lib/plugin/pageInfo.js
index 7106738e4..e9925fead 100644
--- a/lib/plugin/pageInfo.js
+++ b/lib/plugin/pageInfo.js
@@ -1,10 +1,11 @@
 import path from 'path'
 import fs from 'fs'
 import Container from '../container.js'
-const supportedHelpers = Container.STANDARD_ACTING_HELPERS
 import recorder from '../recorder.js'
 import event from '../event.js'
 import { scanForErrorMessages } from '../html.js'
+import { captureSnapshot } from '../utils/captureSnapshot.js'
+import { pickActingHelper } from '../utils/trace.js'
 import { output } from '../index.js'
 import store from '../store.js'
 import { humanizeString, ucfirst } from '../utils.js'
@@ -37,57 +38,52 @@ const defaultConfig = {
  *
  */
 export default function (config = {}) {
-  const helpers = Container.helpers()
-  let helper
-
   config = Object.assign(defaultConfig, config)
 
-  for (const helperName of supportedHelpers) {
-    if (Object.keys(helpers).indexOf(helperName) > -1) {
-      helper = helpers[helperName]
-    }
-  }
-
-  if (!helper) return // no helpers for screenshot
+  const helper = pickActingHelper(Container.helpers())
+  if (!helper) return
 
   event.dispatcher.on(event.test.failed, test => {
     const pageState = {}
 
-    recorder.add('URL of failed test', async () => {
+    recorder.add('pageInfo capture', async () => {
       try {
-        const url = await helper.grabCurrentUrl()
-        pageState.url = url
-      } catch (err) {
-        // not really needed
-      }
-    })
-    recorder.add('HTML snapshot failed test', async () => {
-      try {
-        const html = await helper.grabHTMLFrom('body')
-
-        if (!html) return
-
-        const errors = scanForErrorMessages(html, config.errorClasses)
-        if (errors.length) {
-          output.debug('Detected errors in HTML code')
-          errors.forEach(error => output.debug(error))
-          pageState.htmlErrors = errors
+        const prefix = `${testToFileName(test)}.pageInfo`
+        const captured = await captureSnapshot(helper, {
+          dir: store.outputDir,
+          prefix,
+          captureScreenshot: false,
+        })
+
+        if (captured.url) pageState.url = captured.url
+
+        if (captured.html) {
+          const htmlPath = path.join(store.outputDir, captured.html)
+          pageState.htmlSnapshot = htmlPath
+          try {
+            const html = fs.readFileSync(htmlPath, 'utf8')
+            const errors = scanForErrorMessages(html, config.errorClasses)
+            if (errors.length) {
+              output.debug('Detected errors in HTML code')
+              errors.forEach(error => output.debug(error))
+              pageState.htmlErrors = errors
+            }
+          } catch {}
         }
-      } catch (err) {
-        // not really needed
-      }
-    })
-
-    recorder.add('Browser logs for failed test', async () => {
-      try {
-        const logs = await helper.grabBrowserLogs()
 
-        if (!logs) return
+        if (captured.aria) {
+          pageState.ariaSnapshot = path.join(store.outputDir, captured.aria)
+        }
 
-        pageState.browserErrors = getBrowserErrors(logs, config.browserLogs)
-      } catch (err) {
-        // not really needed
-      }
+        if (captured.console) {
+          const consolePath = path.join(store.outputDir, captured.console)
+          pageState.consoleSnapshot = consolePath
+          try {
+            const logs = JSON.parse(fs.readFileSync(consolePath, 'utf8'))
+            pageState.browserErrors = getBrowserErrors(logs, config.browserLogs)
+          } catch {}
+        }
+      } catch {}
     })
 
     recorder.add('Save page info', () => {
@@ -127,15 +123,16 @@ function pageStateToMarkdown(pageState) {
 }
 
 function getBrowserErrors(logs, type = ['error']) {
-  // Playwright & WebDriver console messages
-  let errors = logs
+  // Accepts Playwright ConsoleMessage objects, normalized {type, text}, or strings
+  return logs
     .map(log => {
       if (typeof log === 'string') return log
-      if (!log.type) return null
-      return { type: log.type(), text: log.text() }
+      if (!log) return null
+      const t = typeof log.type === 'function' ? log.type() : log.type
+      const text = typeof log.text === 'function' ? log.text() : log.text
+      if (!t) return null
+      return { type: t, text }
     })
     .filter(l => l && (typeof l === 'string' || type.includes(l.type)))
     .map(l => (typeof l === 'string' ? l : l.text))
-
-  return errors
 }
diff --git a/lib/utils.js b/lib/utils.js
index e606c59cb..a04b37493 100644
--- a/lib/utils.js
+++ b/lib/utils.js
@@ -617,6 +617,12 @@ function createCircularSafeReplacer(keysToSkip = []) {
       return undefined
     }
 
+    // Coerce types that JSON.stringify can't handle natively
+    if (typeof value === 'function') return `[Function: ${value.name || 'anonymous'}]`
+    if (typeof value === 'bigint') return `${value.toString()}n`
+    if (typeof value === 'symbol') return value.toString()
+    if (value instanceof Error) return { name: value.name, message: value.message, stack: value.stack }
+
     if (value === null || typeof value !== 'object') {
       return value
     }
@@ -647,6 +653,25 @@ export const safeStringify = function (obj, keysToSkip = [], space = 0) {
   }
 }
 
+/**
+ * Truncate a string at a byte cap, returning structured info.
+ * @param {string} str
+ * @param {number} maxBytes
+ * @returns {{ value: string, truncated: boolean, fullLength: number }}
+ */
+export const truncateString = function (str, maxBytes) {
+  if (typeof str !== 'string') str = String(str)
+  if (str.length <= maxBytes) {
+    return { value: str, truncated: false, fullLength: str.length }
+  }
+  const dropped = str.length - maxBytes
+  return {
+    value: `${str.slice(0, maxBytes)}\n...[truncated ${dropped} more chars]`,
+    truncated: true,
+    fullLength: str.length,
+  }
+}
+
 export const serializeError = function (error) {
   if (error) {
     const { stack, uncaught, message, actual, expected } = error
diff --git a/lib/utils/captureSnapshot.js b/lib/utils/captureSnapshot.js
new file mode 100644
index 000000000..d1cd379cc
--- /dev/null
+++ b/lib/utils/captureSnapshot.js
@@ -0,0 +1,130 @@
+import fs from 'fs'
+import path from 'path'
+import { formatHtml } from '../html.js'
+
+function normalizeBrowserLogs(logs) {
+  return (logs || []).map(l => {
+    if (typeof l === 'string') return l
+    if (l && typeof l.type === 'function' && typeof l.text === 'function') {
+      return { type: l.type(), text: l.text() }
+    }
+    return l
+  })
+}
+
+async function captureStorageState(helper) {
+  if (typeof helper.grabStorageState === 'function') {
+    try {
+      const state = await helper.grabStorageState()
+      if (state) return state
+    } catch {}
+  }
+
+  const state = { cookies: [], origins: [] }
+
+  if (typeof helper.grabCookie === 'function') {
+    try {
+      const cookies = await helper.grabCookie()
+      if (Array.isArray(cookies)) state.cookies = cookies
+    } catch {}
+  }
+
+  if (typeof helper.executeScript === 'function') {
+    try {
+      const result = await helper.executeScript(() => {
+        const out = { origin: location.origin, items: [] }
+        for (let i = 0; i < localStorage.length; i++) {
+          const name = localStorage.key(i)
+          out.items.push({ name, value: localStorage.getItem(name) })
+        }
+        return out
+      })
+      if (result?.items?.length) {
+        state.origins.push({ origin: result.origin, localStorage: result.items })
+      }
+    } catch {}
+  }
+
+  return state
+}
+
+export async function captureSnapshot(helper, {
+  dir,
+  prefix = 'snapshot',
+  fullPage = false,
+  captureURL = true,
+  captureScreenshot = true,
+  captureHTML = true,
+  captureARIA = true,
+  captureBrowserLogs = true,
+  captureStorage = true,
+} = {}) {
+  if (!helper) return {}
+  const out = {}
+
+  if (captureURL) {
+    try {
+      if (helper.grabCurrentUrl) out.url = await helper.grabCurrentUrl()
+    } catch {}
+  }
+
+  if (captureScreenshot && helper.saveScreenshot) {
+    try {
+      const file = `${prefix}_screenshot.png`
+      await helper.saveScreenshot(path.join(dir, file), fullPage)
+      out.screenshot = file
+    } catch {}
+  }
+
+  if (captureHTML && helper.grabSource) {
+    try {
+      const html = await helper.grabSource()
+      // Universal funnel: every captured HTML snapshot flows through formatHtml
+      // (minify -> cleanHtml -> beautify). Don't add direct grabSource->writeFile
+      // paths elsewhere; route through this util so trash-class cleanup stays
+      // consistent across aiTrace, pageInfo, and MCP tools.
+      const formatted = await formatHtml(html)
+      const file = `${prefix}_page.html`
+      fs.writeFileSync(path.join(dir, file), formatted)
+      out.html = file
+    } catch {}
+  }
+
+  if (captureARIA && helper.grabAriaSnapshot) {
+    try {
+      const aria = await helper.grabAriaSnapshot()
+      const file = `${prefix}_aria.txt`
+      fs.writeFileSync(path.join(dir, file), aria)
+      out.aria = file
+    } catch {}
+  }
+
+  if (captureBrowserLogs && helper.grabBrowserLogs) {
+    try {
+      const logs = await helper.grabBrowserLogs()
+      const normalized = normalizeBrowserLogs(logs)
+      const file = `${prefix}_console.json`
+      fs.writeFileSync(path.join(dir, file), JSON.stringify(normalized, null, 2))
+      out.console = file
+      out.consoleCount = normalized.length
+    } catch {}
+  }
+
+  if (captureStorage) {
+    try {
+      const state = await captureStorageState(helper)
+      const cookieCount = state.cookies?.length || 0
+      const localStorageCount = (state.origins || [])
+        .reduce((sum, o) => sum + (o.localStorage?.length || 0), 0)
+      if (cookieCount || localStorageCount) {
+        const file = `${prefix}_storage.json`
+        fs.writeFileSync(path.join(dir, file), JSON.stringify(state, null, 2))
+        out.storage = file
+        out.cookieCount = cookieCount
+        out.localStorageCount = localStorageCount
+      }
+    } catch {}
+  }
+
+  return out
+}
diff --git a/lib/utils/trace.js b/lib/utils/trace.js
new file mode 100644
index 000000000..351f595d8
--- /dev/null
+++ b/lib/utils/trace.js
@@ -0,0 +1,71 @@
+import crypto from 'crypto'
+import path from 'path'
+import Container from '../container.js'
+import { clearString } from '../utils.js'
+
+export function pickActingHelper(helpers) {
+  for (const name of Container.STANDARD_ACTING_HELPERS) {
+    if (helpers[name]) return helpers[name]
+  }
+  return null
+}
+
+export function traceDirFor(testFile, testTitle, baseDir) {
+  const hash = crypto.createHash('sha256').update((testFile || '') + (testTitle || '')).digest('hex').slice(0, 8)
+  const cleanTitle = clearString(testTitle || '').slice(0, 200)
+  return path.resolve(baseDir, `trace_${cleanTitle}_${hash}`)
+}
+
+export function snapshotDirFor(baseDir) {
+  const hash = crypto.randomBytes(4).toString('hex')
+  return path.resolve(baseDir, `snapshot_${Date.now()}_${hash}`)
+}
+
+const ARTIFACT_LABELS = {
+  html: 'HTML',
+  aria: 'ARIA',
+  screenshot: 'Screenshot',
+  console: 'Browser Logs',
+  storage: 'Storage',
+}
+
+export function artifactLinks(artifacts, { indent = '  ', consoleCount } = {}) {
+  const lines = []
+  const order = ['html', 'aria', 'screenshot', 'console', 'storage']
+
+  for (const key of order) {
+    const file = artifacts[key]
+    if (!file) continue
+    const label = ARTIFACT_LABELS[key]
+    let line = `${indent}> [${label}](./${file})`
+    if (key === 'console') {
+      const count = consoleCount ?? artifacts.consoleCount ?? 0
+      line += ` (${count} entries)`
+    } else if (key === 'storage') {
+      const cookies = artifacts.cookieCount ?? 0
+      const ls = artifacts.localStorageCount ?? 0
+      line += ` (${cookies} cookies, ${ls} localStorage)`
+    }
+    lines.push(line)
+  }
+
+  return lines.join('\n')
+}
+
+export function fileToUrl(dir, basename) {
+  return `file://${path.join(dir, basename)}`
+}
+
+export function artifactsToFileUrls(captured, dir) {
+  const out = {}
+  if (captured.url) out.url = captured.url
+  if (captured.screenshot) out.screenshot = fileToUrl(dir, captured.screenshot)
+  if (captured.html) out.html = fileToUrl(dir, captured.html)
+  if (captured.aria) out.aria = fileToUrl(dir, captured.aria)
+  if (captured.console) out.console = fileToUrl(dir, captured.console)
+  if (captured.storage) out.storage = fileToUrl(dir, captured.storage)
+  if (typeof captured.consoleCount === 'number') out.consoleCount = captured.consoleCount
+  if (typeof captured.cookieCount === 'number') out.cookieCount = captured.cookieCount
+  if (typeof captured.localStorageCount === 'number') out.localStorageCount = captured.localStorageCount
+  return out
+}
diff --git a/test/unit/html_test.js b/test/unit/html_test.js
index 1917f7afa..1de0d444d 100644
--- a/test/unit/html_test.js
+++ b/test/unit/html_test.js
@@ -3,7 +3,7 @@ import path from 'path'
 import { expect } from 'chai'
 import { fileURLToPath } from 'url'
 import * as cheerio from 'cheerio'
-import { scanForErrorMessages, removeNonInteractiveElements, minifyHtml, splitByChunks } from '../../lib/html.js'
+import { scanForErrorMessages, removeNonInteractiveElements, minifyHtml, splitByChunks, cleanHtml, formatHtml, isTrashClass } from '../../lib/html.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -139,4 +139,89 @@ describe('HTML module', () => {
       }
     })
   })
+
+  describe('#isTrashClass', () => {
+    it('flags Tailwind/utility/framework/scoped/digit-bearing classes', () => {
+      expect(isTrashClass('text-sm')).to.be.true
+      expect(isTrashClass('flex-row')).to.be.true
+      expect(isTrashClass('color-red')).to.be.true
+      expect(isTrashClass('float-left')).to.be.true
+      expect(isTrashClass('border-2')).to.be.true
+      expect(isTrashClass('d-flex')).to.be.true
+      expect(isTrashClass('v-btn')).to.be.true
+      expect(isTrashClass('ember-view')).to.be.true
+      expect(isTrashClass('bg-gray-200')).to.be.true
+      expect(isTrashClass('xl:hidden')).to.be.true
+      expect(isTrashClass('Header__title')).to.be.true
+      expect(isTrashClass('component-3xZ9')).to.be.true
+    })
+
+    it('keeps real semantic class names', () => {
+      expect(isTrashClass('login-form')).to.be.false
+      expect(isTrashClass('primary')).to.be.false
+      expect(isTrashClass('my-real-class')).to.be.false
+      expect(isTrashClass('error')).to.be.false
+    })
+  })
+
+  describe('#cleanHtml', () => {
+    const fixture = '<html><head><style>body{color:red}</style></head>'
+      + '<body>'
+      + '<div class="text-sm flex-row Header__title bg-gray-200 my-real-class" style="color: red">'
+      + '<script>alert(1)</script>'
+      + '<span data-keep="x" id="ok" aria-label="hi">hi</span>'
+      + '</div>'
+      + '<script src="/app.js"></script>'
+      + '<noscript>fallback</noscript>'
+      + '</body></html>'
+
+    it('drops <style>, <noscript>, and inline <script> (no src)', () => {
+      const out = cleanHtml(fixture)
+      expect(out).not.to.include('<style')
+      expect(out).not.to.include('<noscript')
+      expect(out).not.to.include('alert(1)')
+    })
+
+    it('keeps <script src="...">', () => {
+      const out = cleanHtml(fixture)
+      expect(out).to.include('<script src="/app.js"></script>')
+    })
+
+    it('strips trash classes but keeps real ones', () => {
+      const out = cleanHtml(fixture)
+      expect(out).to.include('class="my-real-class"')
+      expect(out).not.to.include('text-sm')
+      expect(out).not.to.include('Header__title')
+      expect(out).not.to.include('bg-gray-200')
+    })
+
+    it('drops inline style="" and preserves data-* / id / aria-*', () => {
+      const out = cleanHtml(fixture)
+      expect(out).not.to.include('style=')
+      expect(out).to.include('data-keep="x"')
+      expect(out).to.include('id="ok"')
+      expect(out).to.include('aria-label="hi"')
+    })
+  })
+
+  describe('#formatHtml', () => {
+    it('minifies, cleans, and beautifies', async () => {
+      const fixture = '<html><head><!-- a comment --><style>body{color:red}</style></head>'
+        + '<body><div class="text-sm my-real-class" style="color: red">'
+        + '<span>hi</span></div></body></html>'
+      const out = await formatHtml(fixture)
+      // beautify: multiline output
+      expect(out.split('\n').length).to.be.greaterThan(3)
+      // comment removed by minifier
+      expect(out).not.to.include('<!--')
+      // cleanHtml: trash class and inline style gone, semantic class kept
+      expect(out).not.to.include('text-sm')
+      expect(out).not.to.include('style=')
+      expect(out).to.include('class="my-real-class"')
+      // <style> block removed entirely
+      expect(out).not.to.include('<style')
+      // structure preserved
+      expect(out).to.include('<span>hi</span>')
+    })
+  })
 })

From eaca22dfb08a8df39c7f51f657c3e829b17559fc Mon Sep 17 00:00:00 2001
From: DavertMik <davert@testomat.io>
Date: Sun, 26 Apr 2026 17:37:29 +0300
Subject: [PATCH 2/4] refactor(utils): unify captureSnapshot + trace into
 lib/utils/trace.js
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both files belonged to the same flow (capture artifacts -> render trace.md).
Splitting them across two files made the import sites awkward, so they're
now consolidated:

- `lib/utils/captureSnapshot.js` deleted; its `captureSnapshot`,
  `normalizeBrowserLogs`, and `captureStorageState` moved into
  `lib/utils/trace.js`.
- `writeTraceMarkdown` (was inlined in `bin/mcp-server.js`) moved into
  `lib/utils/trace.js` too — it's the same trace-record concern.
- All three call sites (`bin/mcp-server.js`, `lib/plugin/aiTrace.js`,
  `lib/plugin/pageInfo.js`) now import from a single module.
- Stale `writeFileSync` import dropped from `bin/mcp-server.js`.

72 unit tests still passing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 bin/mcp-server.js            |  30 +------
 lib/plugin/aiTrace.js        |   3 +-
 lib/plugin/pageInfo.js       |   3 +-
 lib/utils/captureSnapshot.js | 130 ---------------------------
 lib/utils/trace.js           | 165 +++++++++++++++++++++++++++++++++++
 5 files changed, 170 insertions(+), 161 deletions(-)
 delete mode 100644 lib/utils/captureSnapshot.js

diff --git a/bin/mcp-server.js b/bin/mcp-server.js
index 47a49a2df..331ab4aac 100644
--- a/bin/mcp-server.js
+++ b/bin/mcp-server.js
@@ -5,13 +5,13 @@ import Codecept from '../lib/codecept.js'
 import container from '../lib/container.js'
 import { getParamsToString } from '../lib/parser.js'
 import { methodsOfObject, safeStringify, truncateString } from '../lib/utils.js'
-import { captureSnapshot } from '../lib/utils/captureSnapshot.js'
 import {
+  captureSnapshot,
   pickActingHelper,
   traceDirFor,
   snapshotDirFor,
-  artifactLinks,
   artifactsToFileUrls,
+  writeTraceMarkdown,
 } from '../lib/utils/trace.js'
 import event from '../lib/event.js'
 import { fileURLToPath } from 'url'
@@ -19,7 +19,7 @@ import { dirname, resolve as resolvePath } from 'path'
 import path from 'path'
 import { spawn } from 'child_process'
 import { createRequire } from 'module'
-import { existsSync, readdirSync, writeFileSync } from 'fs'
+import { existsSync, readdirSync } from 'fs'
 import { mkdirp } from 'mkdirp'
 
 const require = createRequire(import.meta.url)
@@ -235,30 +235,6 @@ function outputBaseDir() {
   return global.output_dir || resolvePath(process.cwd(), 'output')
 }
 
-function writeTraceMarkdown({ dir, title, file, durationMs, commands, captured, error }) {
-  let md = `file: ${file || 'mcp'}\n`
-  md += `name: ${title}\n`
-  md += `time: ${(durationMs / 1000).toFixed(2)}s\n`
-  md += `---\n\n`
-
-  if (error) md += `Error: ${error}\n\n---\n\n`
-
-  if (commands && commands.length) {
-    md += `### Commands\n`
-    for (const c of commands) md += `- ${c}\n`
-    md += `\n`
-  }
-
-  md += `### Final State\n`
-  if (captured.url) md += `  > URL: ${captured.url}\n`
-  const links = artifactLinks(captured)
-  if (links) md += links + '\n'
-
-  const traceFile = path.join(dir, 'trace.md')
-  writeFileSync(traceFile, md)
-  return traceFile
-}
-
 async function initCodecept(configPath) {
   if (containerInitialized) return
 
diff --git a/lib/plugin/aiTrace.js b/lib/plugin/aiTrace.js
index e61fb3943..4ba00e5d1 100644
--- a/lib/plugin/aiTrace.js
+++ b/lib/plugin/aiTrace.js
@@ -8,8 +8,7 @@ import recorder from '../recorder.js'
 import event from '../event.js'
 import output from '../output.js'
 import { deleteDir, clearString } from '../utils.js'
-import { captureSnapshot } from '../utils/captureSnapshot.js'
-import { pickActingHelper, traceDirFor, artifactLinks } from '../utils/trace.js'
+import { captureSnapshot, pickActingHelper, traceDirFor, artifactLinks } from '../utils/trace.js'
 
 const defaultConfig = {
   deleteSuccessful: false,
diff --git a/lib/plugin/pageInfo.js b/lib/plugin/pageInfo.js
index e9925fead..e7a26001b 100644
--- a/lib/plugin/pageInfo.js
+++ b/lib/plugin/pageInfo.js
@@ -4,8 +4,7 @@ import Container from '../container.js'
 import recorder from '../recorder.js'
 import event from '../event.js'
 import { scanForErrorMessages } from '../html.js'
-import { captureSnapshot } from '../utils/captureSnapshot.js'
-import { pickActingHelper } from '../utils/trace.js'
+import { captureSnapshot, pickActingHelper } from '../utils/trace.js'
 import { output } from '../index.js'
 import store from '../store.js'
 import { humanizeString, ucfirst } from '../utils.js'
diff --git a/lib/utils/captureSnapshot.js b/lib/utils/captureSnapshot.js
deleted file mode 100644
index d1cd379cc..000000000
--- a/lib/utils/captureSnapshot.js
+++ /dev/null
@@ -1,130 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { formatHtml } from '../html.js'
-
-function normalizeBrowserLogs(logs) {
-  return (logs || []).map(l => {
-    if (typeof l === 'string') return l
-    if (l && typeof l.type === 'function' && typeof l.text === 'function') {
-      return { type: l.type(), text: l.text() }
-    }
-    return l
-  })
-}
-
-async function captureStorageState(helper) {
-  if (typeof helper.grabStorageState === 'function') {
-    try {
-      const state = await helper.grabStorageState()
-      if (state) return state
-    } catch {}
-  }
-
-  const state = { cookies: [], origins: [] }
-
-  if (typeof helper.grabCookie === 'function') {
-    try {
-      const cookies = await helper.grabCookie()
-      if (Array.isArray(cookies)) state.cookies = cookies
-    } catch {}
-  }
-
-  if (typeof helper.executeScript === 'function') {
-    try {
-      const result = await helper.executeScript(() => {
-        const out = { origin: location.origin, items: [] }
-        for (let i = 0; i < localStorage.length; i++) {
-          const name = localStorage.key(i)
-          out.items.push({ name, value: localStorage.getItem(name) })
-        }
-        return out
-      })
-      if (result?.items?.length) {
-        state.origins.push({ origin: result.origin, localStorage: result.items })
-      }
-    } catch {}
-  }
-
-  return state
-}
-
-export async function captureSnapshot(helper, {
-  dir,
-  prefix = 'snapshot',
-  fullPage = false,
-  captureURL = true,
-  captureScreenshot = true,
-  captureHTML = true,
-  captureARIA = true,
-  captureBrowserLogs = true,
-  captureStorage = true,
-} = {}) {
-  if (!helper) return {}
-  const out = {}
-
-  if (captureURL) {
-    try {
-      if (helper.grabCurrentUrl) out.url = await helper.grabCurrentUrl()
-    } catch {}
-  }
-
-  if (captureScreenshot && helper.saveScreenshot) {
-    try {
-      const file = `${prefix}_screenshot.png`
-      await helper.saveScreenshot(path.join(dir, file), fullPage)
-      out.screenshot = file
-    } catch {}
-  }
-
-  if (captureHTML && helper.grabSource) {
-    try {
-      const html = await helper.grabSource()
-      // Universal funnel: every captured HTML snapshot flows through formatHtml
-      // (minify -> cleanHtml -> beautify). Don't add direct grabSource->writeFile
-      // paths elsewhere; route through this util so trash-class cleanup stays
-      // consistent across aiTrace, pageInfo, and MCP tools.
-      const formatted = await formatHtml(html)
-      const file = `${prefix}_page.html`
-      fs.writeFileSync(path.join(dir, file), formatted)
-      out.html = file
-    } catch {}
-  }
-
-  if (captureARIA && helper.grabAriaSnapshot) {
-    try {
-      const aria = await helper.grabAriaSnapshot()
-      const file = `${prefix}_aria.txt`
-      fs.writeFileSync(path.join(dir, file), aria)
-      out.aria = file
-    } catch {}
-  }
-
-  if (captureBrowserLogs && helper.grabBrowserLogs) {
-    try {
-      const logs = await helper.grabBrowserLogs()
-      const normalized = normalizeBrowserLogs(logs)
-      const file = `${prefix}_console.json`
-      fs.writeFileSync(path.join(dir, file), JSON.stringify(normalized, null, 2))
-      out.console = file
-      out.consoleCount = normalized.length
-    } catch {}
-  }
-
-  if (captureStorage) {
-    try {
-      const state = await captureStorageState(helper)
-      const cookieCount = state.cookies?.length || 0
-      const localStorageCount = (state.origins || [])
-        .reduce((sum, o) => sum + (o.localStorage?.length || 0), 0)
-      if (cookieCount || localStorageCount) {
-        const file = `${prefix}_storage.json`
-        fs.writeFileSync(path.join(dir, file), JSON.stringify(state, null, 2))
-        out.storage = file
-        out.cookieCount = cookieCount
-        out.localStorageCount = localStorageCount
-      }
-    } catch {}
-  }
-
-  return out
-}
diff --git a/lib/utils/trace.js b/lib/utils/trace.js
index 351f595d8..cdf2c8168 100644
--- a/lib/utils/trace.js
+++ b/lib/utils/trace.js
@@ -1,7 +1,13 @@
 import crypto from 'crypto'
+import fs from 'fs'
 import path from 'path'
 import Container from '../container.js'
 import { clearString } from '../utils.js'
+import { formatHtml } from '../html.js'
+
+// ---------------------------------------------------------------------------
+// Helper / directory naming
+// ---------------------------------------------------------------------------
 
 export function pickActingHelper(helpers) {
   for (const name of Container.STANDARD_ACTING_HELPERS) {
@@ -21,6 +27,10 @@ export function snapshotDirFor(baseDir) {
   return path.resolve(baseDir, `snapshot_${Date.now()}_${hash}`)
 }
 
+// ---------------------------------------------------------------------------
+// Artifact link rendering (trace.md)
+// ---------------------------------------------------------------------------
+
 const ARTIFACT_LABELS = {
   html: 'HTML',
   aria: 'ARIA',
@@ -56,6 +66,30 @@ export function fileToUrl(dir, basename) {
   return `file://${path.join(dir, basename)}`
 }
 
+export function writeTraceMarkdown({ dir, title, file, durationMs, commands, captured, error }) {
+  let md = `file: ${file || 'mcp'}\n`
+  md += `name: ${title}\n`
+  md += `time: ${(durationMs / 1000).toFixed(2)}s\n`
+  md += `---\n\n`
+
+  if (error) md += `Error: ${error}\n\n---\n\n`
+
+  if (commands && commands.length) {
+    md += `### Commands\n`
+    for (const c of commands) md += `- ${c}\n`
+    md += `\n`
+  }
+
+  md += `### Final State\n`
+  if (captured.url) md += `  > URL: ${captured.url}\n`
+  const links = artifactLinks(captured)
+  if (links) md += links + '\n'
+
+  const traceFile = path.join(dir, 'trace.md')
+  fs.writeFileSync(traceFile, md)
+  return traceFile
+}
+
 export function artifactsToFileUrls(captured, dir) {
   const out = {}
   if (captured.url) out.url = captured.url
@@ -69,3 +103,134 @@ export function artifactsToFileUrls(captured, dir) {
   if (typeof captured.localStorageCount === 'number') out.localStorageCount = captured.localStorageCount
   return out
 }
+
+// ---------------------------------------------------------------------------
+// Snapshot capture (HTML / ARIA / screenshot / console / storage)
+// ---------------------------------------------------------------------------
+
+function normalizeBrowserLogs(logs) {
+  return (logs || []).map(l => {
+    if (typeof l === 'string') return l
+    if (l && typeof l.type === 'function' && typeof l.text === 'function') {
+      return { type: l.type(), text: l.text() }
+    }
+    return l
+  })
+}
+
+async function captureStorageState(helper) {
+  if (typeof helper.grabStorageState === 'function') {
+    try {
+      const state = await helper.grabStorageState()
+      if (state) return state
+    } catch {}
+  }
+
+  const state = { cookies: [], origins: [] }
+
+  if (typeof helper.grabCookie === 'function') {
+    try {
+      const cookies = await helper.grabCookie()
+      if (Array.isArray(cookies)) state.cookies = cookies
+    } catch {}
+  }
+
+  if (typeof helper.executeScript === 'function') {
+    try {
+      const result = await helper.executeScript(() => {
+        const out = { origin: location.origin, items: [] }
+        for (let i = 0; i < localStorage.length; i++) {
+          const name = localStorage.key(i)
+          out.items.push({ name, value: localStorage.getItem(name) })
+        }
+        return out
+      })
+      if (result?.items?.length) {
+        state.origins.push({ origin: result.origin, localStorage: result.items })
+      }
+    } catch {}
+  }
+
+  return state
+}
+
+export async function captureSnapshot(helper, {
+  dir,
+  prefix = 'snapshot',
+  fullPage = false,
+  captureURL = true,
+  captureScreenshot = true,
+  captureHTML = true,
+  captureARIA = true,
+  captureBrowserLogs = true,
+  captureStorage = true,
+} = {}) {
+  if (!helper) return {}
+  const out = {}
+
+  if (captureURL) {
+    try {
+      if (helper.grabCurrentUrl) out.url = await helper.grabCurrentUrl()
+    } catch {}
+  }
+
+  if (captureScreenshot && helper.saveScreenshot) {
+    try {
+      const file = `${prefix}_screenshot.png`
+      await helper.saveScreenshot(path.join(dir, file), fullPage)
+      out.screenshot = file
+    } catch {}
+  }
+
+  if (captureHTML && helper.grabSource) {
+    try {
+      const html = await helper.grabSource()
+      // Universal funnel: every captured HTML snapshot flows through formatHtml
+      // (minify -> cleanHtml -> beautify). Don't add direct grabSource->writeFile
+      // paths elsewhere; route through this util so trash-class cleanup stays
+      // consistent across aiTrace, pageInfo, and MCP tools.
+      const formatted = await formatHtml(html)
+      const file = `${prefix}_page.html`
+      fs.writeFileSync(path.join(dir, file), formatted)
+      out.html = file
+    } catch {}
+  }
+
+  if (captureARIA && helper.grabAriaSnapshot) {
+    try {
+      const aria = await helper.grabAriaSnapshot()
+      const file = `${prefix}_aria.txt`
+      fs.writeFileSync(path.join(dir, file), aria)
+      out.aria = file
+    } catch {}
+  }
+
+  if (captureBrowserLogs && helper.grabBrowserLogs) {
+    try {
+      const logs = await helper.grabBrowserLogs()
+      const normalized = normalizeBrowserLogs(logs)
+      const file = `${prefix}_console.json`
+      fs.writeFileSync(path.join(dir, file), JSON.stringify(normalized, null, 2))
+      out.console = file
+      out.consoleCount = normalized.length
+    } catch {}
+  }
+
+  if (captureStorage) {
+    try {
+      const state = await captureStorageState(helper)
+      const cookieCount = state.cookies?.length || 0
+      const localStorageCount = (state.origins || [])
+        .reduce((sum, o) => sum + (o.localStorage?.length || 0), 0)
+      if (cookieCount || localStorageCount) {
+        const file = `${prefix}_storage.json`
+        fs.writeFileSync(path.join(dir, file), JSON.stringify(state, null, 2))
+        out.storage = file
+        out.cookieCount = cookieCount
+        out.localStorageCount = localStorageCount
+      }
+    } catch {}
+  }
+
+  return out
+}

From 754d3ea85717533f36f12a4fd7a77bec16bb9440 Mon Sep 17 00:00:00 2001
From: DavertMik <davert@testomat.io>
Date: Sun, 26 Apr 2026 17:45:31 +0300
Subject: [PATCH 3/4] test(utils): add unit coverage for trace.js +
 safeStringify extensions + truncateString
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

49 new test cases across two files:

- `test/unit/utils/trace_test.js` (new, 37 cases) — direct coverage of
  every export from `lib/utils/trace.js`:
  - `pickActingHelper` (all 3 paths)
  - `traceDirFor` (determinism, uniqueness, sanitization, missing args)
  - `snapshotDirFor` (uniqueness, embedded timestamp)
  - `artifactLinks` (each artifact, console-count override, storage
    counts, custom indent, empty input, ordering invariant)
  - `fileToUrl` / `artifactsToFileUrls`
  - `writeTraceMarkdown` (golden output, error block, optional commands,
    default `file`)
  - `captureSnapshot` (default options, full opt-out matrix, fullPage,
    formatHtml integration, ConsoleMessage normalization, Playwright
    grabStorageState path, Puppeteer/WebDriver fallback path, empty
    storage handled, missing helper methods, error swallowing, default
    prefix)

- `test/unit/circular_reference_test.js` (extended, 12 new cases):
  - `safeStringify` Function/BigInt/Symbol/Error coercions including
    nested mixed types (BigInt was a real bug; JSON.stringify(BigInt)
    used to throw and trigger the legacy fallback path)
  - `truncateString` under / equal / over maxBytes, non-string coercion,
    empty string

Total unit suite: 121 passing (was 72).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 test/unit/circular_reference_test.js |  99 ++++++-
 test/unit/utils/trace_test.js        | 418 +++++++++++++++++++++++++++
 2 files changed, 516 insertions(+), 1 deletion(-)
 create mode 100644 test/unit/utils/trace_test.js

diff --git a/test/unit/circular_reference_test.js b/test/unit/circular_reference_test.js
index a8208f93b..795b95710 100644
--- a/test/unit/circular_reference_test.js
+++ b/test/unit/circular_reference_test.js
@@ -1,5 +1,5 @@
 import { expect } from 'chai'
-import { safeStringify } from '../../lib/utils.js'
+import { safeStringify, truncateString } from '../../lib/utils.js'
 import { createTest } from '../../lib/mocha/test.js'
 import { createSuite } from '../../lib/mocha/suite.js'
 import MochaSuite from 'mocha/lib/suite.js'
@@ -160,6 +160,103 @@ describe('Circular Reference Handling', function () {
     })
   })
 
+  describe('safeStringify type coercions', function () {
+    it('coerces functions to "[Function: name]"', function () {
+      const obj = { fn: function namedFn() {}, anon: () => {} }
+      const parsed = JSON.parse(safeStringify(obj))
+      expect(parsed.fn).to.equal('[Function: namedFn]')
+      expect(parsed.anon).to.match(/^\[Function: .*\]$/)
+    })
+
+    it('coerces BigInt values (which JSON.stringify cannot natively handle)', function () {
+      const result = safeStringify({ big: 12345678901234567890n })
+      expect(result).to.contain('12345678901234567890n')
+      // Verify the legacy fallback path is NOT triggered
+      expect(result).to.not.contain('Failed to serialize')
+    })
+
+    it('coerces Symbol to its toString()', function () {
+      const obj = { s: Symbol('marker') }
+      const parsed = JSON.parse(safeStringify(obj))
+      expect(parsed.s).to.equal('Symbol(marker)')
+    })
+
+    it('coerces Error to {name, message, stack}', function () {
+      const obj = { err: new Error('boom') }
+      const parsed = JSON.parse(safeStringify(obj))
+      expect(parsed.err).to.have.property('name', 'Error')
+      expect(parsed.err).to.have.property('message', 'boom')
+      expect(parsed.err).to.have.property('stack')
+      expect(parsed.err.stack).to.be.a('string').and.include('boom')
+    })
+
+    it('coerces an Error at the top level', function () {
+      const result = safeStringify(new TypeError('bad arg'))
+      const parsed = JSON.parse(result)
+      expect(parsed.name).to.equal('TypeError')
+      expect(parsed.message).to.equal('bad arg')
+    })
+
+    it('handles nested mixed types together', function () {
+      const obj = {
+        regular: 1,
+        fn: function n() {},
+        big: 1n,
+        sym: Symbol('s'),
+        err: new RangeError('range'),
+        nested: { again: { fn: () => {} } },
+      }
+      const parsed = JSON.parse(safeStringify(obj))
+      expect(parsed.regular).to.equal(1)
+      expect(parsed.fn).to.equal('[Function: n]')
+      expect(parsed.big).to.equal('1n')
+      expect(parsed.sym).to.equal('Symbol(s)')
+      expect(parsed.err.name).to.equal('RangeError')
+      expect(parsed.nested.again.fn).to.match(/^\[Function:/)
+    })
+
+    it('preserves indentation when space arg is provided', function () {
+      const result = safeStringify({ a: 1 }, [], 2)
+      expect(result).to.contain('\n  "a": 1')
+    })
+  })
+
+  describe('truncateString', function () {
+    it('returns input as-is when under maxBytes', function () {
+      const result = truncateString('hello', 100)
+      expect(result.value).to.equal('hello')
+      expect(result.truncated).to.be.false
+      expect(result.fullLength).to.equal(5)
+    })
+
+    it('returns input as-is when exactly equal to maxBytes', function () {
+      const result = truncateString('xxxxx', 5)
+      expect(result.truncated).to.be.false
+      expect(result.value).to.equal('xxxxx')
+    })
+
+    it('truncates and appends marker when over maxBytes', function () {
+      const result = truncateString('x'.repeat(50), 10)
+      expect(result.truncated).to.be.true
+      expect(result.fullLength).to.equal(50)
+      expect(result.value.startsWith('xxxxxxxxxx')).to.be.true
+      expect(result.value).to.contain('truncated 40 more chars')
+    })
+
+    it('coerces non-string inputs via String()', function () {
+      const result = truncateString(12345, 100)
+      expect(result.value).to.equal('12345')
+      expect(result.truncated).to.be.false
+    })
+
+    it('handles empty string', function () {
+      const result = truncateString('', 10)
+      expect(result.value).to.equal('')
+      expect(result.truncated).to.be.false
+      expect(result.fullLength).to.equal(0)
+    })
+  })
+
   describe('Integration with existing serialization', function () {
     it('should work with serializeTest function', function () {
       const test = createTest('Integration Test', () => {})
diff --git a/test/unit/utils/trace_test.js b/test/unit/utils/trace_test.js
new file mode 100644
index 000000000..4bcaecbde
--- /dev/null
+++ b/test/unit/utils/trace_test.js
@@ -0,0 +1,418 @@
+import { expect } from 'chai'
+import sinon from 'sinon'
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import {
+  pickActingHelper,
+  traceDirFor,
+  snapshotDirFor,
+  artifactLinks,
+  fileToUrl,
+  artifactsToFileUrls,
+  writeTraceMarkdown,
+  captureSnapshot,
+} from '../../../lib/utils/trace.js'
+
+function makeTmpDir(prefix = 'trace-test') {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`))
+  return dir
+}
+
+function rmDir(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }) } catch {}
+}
+
+describe('lib/utils/trace.js', () => {
+  describe('pickActingHelper', () => {
+    it('returns the first STANDARD_ACTING_HELPER present', () => {
+      const helpers = { Playwright: { id: 'pw' }, Custom: { id: 'c' } }
+      expect(pickActingHelper(helpers)).to.deep.equal({ id: 'pw' })
+    })
+
+    it('falls through to next standard helper when first is missing', () => {
+      const helpers = { WebDriver: { id: 'wd' } }
+      expect(pickActingHelper(helpers)).to.deep.equal({ id: 'wd' })
+    })
+
+    it('returns null when no standard helper is configured', () => {
+      expect(pickActingHelper({})).to.be.null
+      expect(pickActingHelper({ Custom: {} })).to.be.null
+    })
+  })
+
+  describe('traceDirFor', () => {
+    it('produces an absolute path under the base dir', () => {
+      const dir = traceDirFor('/path/to/test.js', 'My Test', '/base')
+      expect(dir.startsWith('/base/trace_')).to.be.true
+    })
+
+    it('is deterministic for the same (file, title)', () => {
+      const a = traceDirFor('/test.js', 'Same', '/base')
+      const b = traceDirFor('/test.js', 'Same', '/base')
+      expect(a).to.equal(b)
+    })
+
+    it('differs when the file or title differs', () => {
+      const a = traceDirFor('/a.js', 'T', '/base')
+      const b = traceDirFor('/b.js', 'T', '/base')
+      const c = traceDirFor('/a.js', 'U', '/base')
+      expect(a).to.not.equal(b)
+      expect(a).to.not.equal(c)
+    })
+
+    it('sanitizes characters that clearString rewrites (space, slash, angle brackets, quote)', () => {
+      const dir = traceDirFor('/t.js', 'My <Awesome> "test" / step', '/base')
+      expect(dir).to.not.include(' ')
+      expect(dir).to.not.include('"')
+      expect(dir).to.not.include('<')
+      expect(dir).to.not.include('>')
+      // forward slash inside the title gets replaced; the leading "/base/trace_" path separator remains
+      const title = dir.slice('/base/trace_'.length)
+      expect(title).to.not.include('/')
+    })
+
+    it('handles missing file/title gracefully', () => {
+      const dir = traceDirFor(undefined, undefined, '/base')
+      expect(dir.startsWith('/base/trace__')).to.be.true
+    })
+  })
+
+  describe('snapshotDirFor', () => {
+    it('produces a unique path per call', () => {
+      const a = snapshotDirFor('/base')
+      const b = snapshotDirFor('/base')
+      expect(a).to.not.equal(b)
+      expect(a.startsWith('/base/snapshot_')).to.be.true
+    })
+
+    it('embeds a timestamp', () => {
+      const dir = snapshotDirFor('/base')
+      const stamp = parseInt(dir.match(/snapshot_(\d+)_/)[1], 10)
+      expect(stamp).to.be.closeTo(Date.now(), 5_000)
+    })
+  })
+
+  describe('artifactLinks', () => {
+    it('renders only present artifacts in fixed order', () => {
+      const out = artifactLinks({
+        screenshot: 's.png',
+        html: 'p.html',
+      })
+      const lines = out.split('\n')
+      expect(lines).to.have.length(2)
+      expect(lines[0]).to.equal('  > [HTML](./p.html)')
+      expect(lines[1]).to.equal('  > [Screenshot](./s.png)')
+    })
+
+    it('appends entry count for console artifact', () => {
+      const out = artifactLinks({ console: 'c.json', consoleCount: 7 })
+      expect(out).to.equal('  > [Browser Logs](./c.json) (7 entries)')
+    })
+
+    it('uses explicit consoleCount override over artifacts.consoleCount', () => {
+      const out = artifactLinks({ console: 'c.json', consoleCount: 1 }, { consoleCount: 99 })
+      expect(out).to.include('(99 entries)')
+    })
+
+    it('appends cookie + localStorage counts for storage artifact', () => {
+      const out = artifactLinks({
+        storage: 'st.json',
+        cookieCount: 3,
+        localStorageCount: 5,
+      })
+      expect(out).to.equal('  > [Storage](./st.json) (3 cookies, 5 localStorage)')
+    })
+
+    it('renders zero counts when storage exists but counts are missing', () => {
+      const out = artifactLinks({ storage: 's.json' })
+      expect(out).to.include('(0 cookies, 0 localStorage)')
+    })
+
+    it('respects custom indent', () => {
+      const out = artifactLinks({ html: 'p.html' }, { indent: '' })
+      expect(out).to.equal('> [HTML](./p.html)')
+    })
+
+    it('returns empty string when nothing renderable is present', () => {
+      expect(artifactLinks({})).to.equal('')
+      expect(artifactLinks({ url: 'http://x' })).to.equal('')
+    })
+
+    it('renders all five artifact types in the correct order', () => {
+      const out = artifactLinks({
+        screenshot: 's.png',
+        console: 'c.json',
+        consoleCount: 2,
+        html: 'p.html',
+        aria: 'a.txt',
+        storage: 'st.json',
+        cookieCount: 1,
+        localStorageCount: 4,
+      })
+      const lines = out.split('\n')
+      expect(lines.map(l => l.match(/\[([^\]]+)\]/)[1])).to.deep.equal([
+        'HTML', 'ARIA', 'Screenshot', 'Browser Logs', 'Storage',
+      ])
+    })
+  })
+
+  describe('fileToUrl', () => {
+    it('joins dir + basename and prefixes with file://', () => {
+      expect(fileToUrl('/output/run', 'p.html')).to.equal('file:///output/run/p.html')
+    })
+  })
+
+  describe('artifactsToFileUrls', () => {
+    it('rewrites every basename to a file:// URL under the dir', () => {
+      const out = artifactsToFileUrls({
+        url: 'http://example.com',
+        screenshot: 's.png',
+        html: 'p.html',
+        aria: 'a.txt',
+        console: 'c.json',
+        storage: 'st.json',
+        consoleCount: 3,
+        cookieCount: 1,
+        localStorageCount: 2,
+      }, '/dir')
+
+      expect(out.url).to.equal('http://example.com')
+      expect(out.screenshot).to.equal('file:///dir/s.png')
+      expect(out.html).to.equal('file:///dir/p.html')
+      expect(out.aria).to.equal('file:///dir/a.txt')
+      expect(out.console).to.equal('file:///dir/c.json')
+      expect(out.storage).to.equal('file:///dir/st.json')
+      expect(out.consoleCount).to.equal(3)
+      expect(out.cookieCount).to.equal(1)
+      expect(out.localStorageCount).to.equal(2)
+    })
+
+    it('omits absent artifacts', () => {
+      const out = artifactsToFileUrls({ url: 'http://x', html: 'p.html' }, '/d')
+      expect(out).to.have.keys(['url', 'html'])
+    })
+  })
+
+  describe('writeTraceMarkdown', () => {
+    let dir
+
+    beforeEach(() => { dir = makeTmpDir('trace-md') })
+    afterEach(() => rmDir(dir))
+
+    it('writes trace.md with header, commands, and final state links', () => {
+      const file = writeTraceMarkdown({
+        dir,
+        title: 'run_code',
+        file: 'mcp',
+        durationMs: 2500,
+        commands: ['I.amOnPage("/")', 'I.click("a")'],
+        captured: {
+          url: 'https://example.com/',
+          html: 'p.html',
+          aria: 'a.txt',
+          screenshot: 's.png',
+          console: 'c.json',
+          consoleCount: 1,
+        },
+      })
+      expect(file).to.equal(path.join(dir, 'trace.md'))
+      const md = fs.readFileSync(file, 'utf8')
+      expect(md).to.include('file: mcp\n')
+      expect(md).to.include('name: run_code\n')
+      expect(md).to.include('time: 2.50s\n')
+      expect(md).to.include('### Commands\n- I.amOnPage("/")\n- I.click("a")')
+      expect(md).to.include('### Final State')
+      expect(md).to.include('  > URL: https://example.com/')
+      expect(md).to.include('  > [HTML](./p.html)')
+      expect(md).to.include('  > [Browser Logs](./c.json) (1 entries)')
+    })
+
+    it('emits an Error block when error is provided', () => {
+      writeTraceMarkdown({
+        dir, title: 't', file: 'f', durationMs: 0, commands: [], captured: {},
+        error: 'boom',
+      })
+      const md = fs.readFileSync(path.join(dir, 'trace.md'), 'utf8')
+      expect(md).to.include('Error: boom')
+    })
+
+    it('omits Commands section when commands is empty', () => {
+      writeTraceMarkdown({
+        dir, title: 't', file: 'f', durationMs: 0, commands: [], captured: { url: 'http://x' },
+      })
+      const md = fs.readFileSync(path.join(dir, 'trace.md'), 'utf8')
+      expect(md).to.not.include('### Commands')
+    })
+
+    it('defaults file to "mcp" when not provided', () => {
+      writeTraceMarkdown({ dir, title: 't', durationMs: 0, commands: [], captured: {} })
+      const md = fs.readFileSync(path.join(dir, 'trace.md'), 'utf8')
+      expect(md).to.include('file: mcp\n')
+    })
+  })
+
+  describe('captureSnapshot', () => {
+    let dir
+
+    beforeEach(() => { dir = makeTmpDir('cap') })
+    afterEach(() => rmDir(dir))
+
+    function fullHelper(overrides = {}) {
+      return {
+        grabCurrentUrl: sinon.stub().resolves('https://example.com/'),
+        saveScreenshot: sinon.stub().callsFake(async file => fs.writeFileSync(file, 'fake-png')),
+        grabSource: sinon.stub().resolves('<html><body><div>hi</div></body></html>'),
+        grabAriaSnapshot: sinon.stub().resolves('main\n  - text "hi"'),
+        grabBrowserLogs: sinon.stub().resolves(['log line']),
+        grabStorageState: sinon.stub().resolves({
+          cookies: [{ name: 'sid', value: 'abc' }],
+          origins: [{ origin: 'https://example.com', localStorage: [{ name: 'k', value: 'v' }] }],
+        }),
+        ...overrides,
+      }
+    }
+
+    it('returns empty object when helper is null/undefined', async () => {
+      expect(await captureSnapshot(null, { dir })).to.deep.equal({})
+      expect(await captureSnapshot(undefined, { dir })).to.deep.equal({})
+    })
+
+    it('captures all artifact types with default options', async () => {
+      const helper = fullHelper()
+      const out = await captureSnapshot(helper, { dir, prefix: 'p' })
+
+      expect(out.url).to.equal('https://example.com/')
+      expect(out.screenshot).to.equal('p_screenshot.png')
+      expect(out.html).to.equal('p_page.html')
+      expect(out.aria).to.equal('p_aria.txt')
+      expect(out.console).to.equal('p_console.json')
+      expect(out.consoleCount).to.equal(1)
+      expect(out.storage).to.equal('p_storage.json')
+      expect(out.cookieCount).to.equal(1)
+      expect(out.localStorageCount).to.equal(1)
+
+      expect(fs.existsSync(path.join(dir, 'p_screenshot.png'))).to.be.true
+      expect(fs.existsSync(path.join(dir, 'p_page.html'))).to.be.true
+      expect(fs.existsSync(path.join(dir, 'p_aria.txt'))).to.be.true
+      expect(fs.existsSync(path.join(dir, 'p_console.json'))).to.be.true
+      expect(fs.existsSync(path.join(dir, 'p_storage.json'))).to.be.true
+    })
+
+    it('respects each capture* option independently', async () => {
+      const helper = fullHelper()
+      const out = await captureSnapshot(helper, {
+        dir,
+        prefix: 'q',
+        captureURL: false,
+        captureScreenshot: false,
+        captureHTML: false,
+        captureARIA: false,
+        captureBrowserLogs: false,
+        captureStorage: false,
+      })
+      expect(out).to.deep.equal({})
+      expect(helper.grabCurrentUrl.called).to.be.false
+      expect(helper.saveScreenshot.called).to.be.false
+      expect(helper.grabSource.called).to.be.false
+      expect(helper.grabAriaSnapshot.called).to.be.false
+      expect(helper.grabBrowserLogs.called).to.be.false
+      expect(helper.grabStorageState.called).to.be.false
+    })
+
+    it('passes fullPage flag to saveScreenshot', async () => {
+      const helper = fullHelper()
+      await captureSnapshot(helper, { dir, prefix: 'p', fullPage: true })
+      expect(helper.saveScreenshot.firstCall.args[1]).to.be.true
+    })
+
+    it('runs HTML through formatHtml (multi-line, trash classes stripped)', async () => {
+      const helper = fullHelper({
+        grabSource: sinon.stub().resolves('<html><head><style>x{}</style></head><body><div class="text-sm my-real-class" style="color:red">hi</div></body></html>'),
+      })
+      await captureSnapshot(helper, { dir, prefix: 'p' })
+      const html = fs.readFileSync(path.join(dir, 'p_page.html'), 'utf8')
+      expect(html).to.not.include('<style')
+      expect(html).to.not.include('text-sm')
+      expect(html).to.not.include('style=')
+      expect(html).to.include('my-real-class')
+      expect(html.split('\n').length).to.be.greaterThan(2)
+    })
+
+    it('normalizes Playwright ConsoleMessage objects to {type, text}', async () => {
+      const playwrightLog = {
+        type: () => 'error',
+        text: () => 'oops',
+      }
+      const helper = fullHelper({
+        grabBrowserLogs: sinon.stub().resolves([playwrightLog, 'plain string']),
+      })
+      await captureSnapshot(helper, { dir, prefix: 'p' })
+      const logs = JSON.parse(fs.readFileSync(path.join(dir, 'p_console.json'), 'utf8'))
+      expect(logs[0]).to.deep.equal({ type: 'error', text: 'oops' })
+      expect(logs[1]).to.equal('plain string')
+    })
+
+    it('uses Playwright grabStorageState when available', async () => {
+      const helper = fullHelper()
+      await captureSnapshot(helper, { dir, prefix: 'p' })
+      expect(helper.grabStorageState.calledOnce).to.be.true
+      const state = JSON.parse(fs.readFileSync(path.join(dir, 'p_storage.json'), 'utf8'))
+      expect(state.cookies).to.have.length(1)
+      expect(state.origins[0].localStorage).to.have.length(1)
+    })
+
+    it('falls back to grabCookie + executeScript when grabStorageState is absent', async () => {
+      const helper = {
+        grabCurrentUrl: sinon.stub().resolves('https://example.com/'),
+        grabCookie: sinon.stub().resolves([{ name: 'a', value: 'b' }]),
+        executeScript: sinon.stub().resolves({
+          origin: 'https://example.com',
+          items: [{ name: 'k', value: 'v' }],
+        }),
+      }
+      const out = await captureSnapshot(helper, { dir, prefix: 'p' })
+      expect(out.cookieCount).to.equal(1)
+      expect(out.localStorageCount).to.equal(1)
+      const state = JSON.parse(fs.readFileSync(path.join(dir, 'p_storage.json'), 'utf8'))
+      expect(state.cookies).to.deep.equal([{ name: 'a', value: 'b' }])
+      expect(state.origins[0].localStorage).to.deep.equal([{ name: 'k', value: 'v' }])
+    })
+
+    it('omits storage artifact when both cookies and localStorage are empty', async () => {
+      const helper = {
+        grabCurrentUrl: sinon.stub().resolves('about:blank'),
+        grabCookie: sinon.stub().resolves([]),
+        executeScript: sinon.stub().resolves({ origin: 'about:blank', items: [] }),
+      }
+      const out = await captureSnapshot(helper, { dir, prefix: 'p' })
+      expect(out).to.not.have.property('storage')
+      expect(fs.existsSync(path.join(dir, 'p_storage.json'))).to.be.false
+    })
+
+    it('skips capture branches when helper method is missing', async () => {
+      const helper = { grabCurrentUrl: sinon.stub().resolves('http://x') }
+      const out = await captureSnapshot(helper, { dir, prefix: 'p' })
+      expect(out).to.deep.equal({ url: 'http://x' })
+    })
+
+    it('swallows errors from individual grabs', async () => {
+      const helper = fullHelper({
+        grabCurrentUrl: sinon.stub().rejects(new Error('nope')),
+        grabSource: sinon.stub().rejects(new Error('boom')),
+      })
+      const out = await captureSnapshot(helper, { dir, prefix: 'p' })
+      expect(out).to.not.have.property('url')
+      expect(out).to.not.have.property('html')
+      // Other captures still succeed
+      expect(out.aria).to.equal('p_aria.txt')
+      expect(out.screenshot).to.equal('p_screenshot.png')
+    })
+
+    it('uses default prefix "snapshot" when not specified', async () => {
+      const helper = fullHelper()
+      const out = await captureSnapshot(helper, { dir })
+      expect(out.html).to.equal('snapshot_page.html')
+    })
+  })
+})

From 27e2479054873f9ec56b6491255a626ecd210e20 Mon Sep 17 00:00:00 2001
From: DavertMik <davert@testomat.io>
Date: Wed, 29 Apr 2026 22:58:30 +0300
Subject: [PATCH 4/4] fix(trace): use pathToFileURL for Windows-safe URLs; scan
 raw HTML in pageInfo

- Replace `file://${path}` template literals in lib/utils/trace.js
  fileToUrl() and bin/mcp-server.js with pathToFileURL().href so paths
  like `C:\foo\bar` are encoded correctly on Windows.
- captureSnapshot now also returns out.htmlRaw (pre-cleanHtml source) so
  consumers can scan classes that the trash-class filter would strip.
- pageInfo's error-class scan now reads htmlRaw, restoring detection of
  errorClasses containing digits/prefixes like `text-error` or `alert-1`.
---
 bin/mcp-server.js             | 14 +++++++-------
 lib/plugin/pageInfo.js        | 25 ++++++++++++++++---------
 lib/utils/trace.js            |  6 +++++-
 test/unit/utils/trace_test.js | 15 +++++++++++++++
 4 files changed, 43 insertions(+), 17 deletions(-)

diff --git a/bin/mcp-server.js b/bin/mcp-server.js
index 331ab4aac..0b3c5458f 100644
--- a/bin/mcp-server.js
+++ b/bin/mcp-server.js
@@ -14,7 +14,7 @@ import {
   writeTraceMarkdown,
 } from '../lib/utils/trace.js'
 import event from '../lib/event.js'
-import { fileURLToPath } from 'url'
+import { fileURLToPath, pathToFileURL } from 'url'
 import { dirname, resolve as resolvePath } from 'path'
 import path from 'path'
 import { spawn } from 'child_process'
@@ -453,7 +453,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             text: JSON.stringify({
               status: 'success',
               dir,
-              traceFile: `file://${traceFile}`,
+              traceFile: pathToFileURL(traceFile).href,
               artifacts: artifactsToFileUrls(captured, dir),
             }, null, 2),
           }],
@@ -551,7 +551,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           error: result.error,
         })
         result.dir = traceDir
-        result.traceFile = `file://${traceFile}`
+        result.traceFile = pathToFileURL(traceFile).href
 
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
       }
@@ -642,10 +642,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               if (t.err) r.error = t.err.message
 
               if (t.artifacts?.aiTrace) {
-                r.traceFile = `file://${t.artifacts.aiTrace}`
+                r.traceFile = pathToFileURL(t.artifacts.aiTrace).href
               }
-              if (t.artifacts?.har) r.har = `file://${t.artifacts.har}`
-              if (t.artifacts?.trace) r.trace = `file://${t.artifacts.trace}`
+              if (t.artifacts?.har) r.har = pathToFileURL(t.artifacts.har).href
+              if (t.artifacts?.trace) r.trace = pathToFileURL(t.artifacts.trace).href
 
               if (!t.artifacts?.aiTrace) {
                 try {
@@ -664,7 +664,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                       captured,
                       error: r.error,
                     })
-                    r.traceFile = `file://${tracePath}`
+                    r.traceFile = pathToFileURL(tracePath).href
                   }
                 } catch {}
               }
diff --git a/lib/plugin/pageInfo.js b/lib/plugin/pageInfo.js
index e7a26001b..3490f28f1 100644
--- a/lib/plugin/pageInfo.js
+++ b/lib/plugin/pageInfo.js
@@ -9,6 +9,7 @@ import { output } from '../index.js'
 import store from '../store.js'
 import { humanizeString, ucfirst } from '../utils.js'
 import { testToFileName } from '../mocha/test.js'
+
 const defaultConfig = {
   errorClasses: ['error', 'warning', 'alert', 'danger'],
   browserLogs: ['error'],
@@ -59,15 +60,21 @@ export default function (config = {}) {
         if (captured.html) {
           const htmlPath = path.join(store.outputDir, captured.html)
           pageState.htmlSnapshot = htmlPath
-          try {
-            const html = fs.readFileSync(htmlPath, 'utf8')
-            const errors = scanForErrorMessages(html, config.errorClasses)
-            if (errors.length) {
-              output.debug('Detected errors in HTML code')
-              errors.forEach(error => output.debug(error))
-              pageState.htmlErrors = errors
-            }
-          } catch {}
+          // Scan raw HTML (pre-cleanHtml) so error classes containing digits
+          // or trash-class prefixes aren't stripped before detection.
+          const htmlForScan = captured.htmlRaw || (() => {
+            try { return fs.readFileSync(htmlPath, 'utf8') } catch { return '' }
+          })()
+          if (htmlForScan) {
+            try {
+              const errors = scanForErrorMessages(htmlForScan, config.errorClasses)
+              if (errors.length) {
+                output.debug('Detected errors in HTML code')
+                errors.forEach(error => output.debug(error))
+                pageState.htmlErrors = errors
+              }
+            } catch {}
+          }
         }
 
         if (captured.aria) {
diff --git a/lib/utils/trace.js b/lib/utils/trace.js
index cdf2c8168..af6f5863b 100644
--- a/lib/utils/trace.js
+++ b/lib/utils/trace.js
@@ -1,6 +1,7 @@
 import crypto from 'crypto'
 import fs from 'fs'
 import path from 'path'
+import { pathToFileURL } from 'url'
 import Container from '../container.js'
 import { clearString } from '../utils.js'
 import { formatHtml } from '../html.js'
@@ -63,7 +64,7 @@ export function artifactLinks(artifacts, { indent = '  ', consoleCount } = {}) {
 }
 
 export function fileToUrl(dir, basename) {
-  return `file://${path.join(dir, basename)}`
+  return pathToFileURL(path.join(dir, basename)).href
 }
 
 export function writeTraceMarkdown({ dir, title, file, durationMs, commands, captured, error }) {
@@ -193,6 +194,9 @@ export async function captureSnapshot(helper, {
       const file = `${prefix}_page.html`
       fs.writeFileSync(path.join(dir, file), formatted)
       out.html = file
+      // Expose pre-cleanup HTML for consumers that need to inspect classes
+      // stripped by cleanHtml (e.g. pageInfo's error-class scan).
+      out.htmlRaw = html
     } catch {}
   }
 
diff --git a/test/unit/utils/trace_test.js b/test/unit/utils/trace_test.js
index 4bcaecbde..573695f6f 100644
--- a/test/unit/utils/trace_test.js
+++ b/test/unit/utils/trace_test.js
@@ -161,6 +161,11 @@ describe('lib/utils/trace.js', () => {
     it('joins dir + basename and prefixes with file://', () => {
       expect(fileToUrl('/output/run', 'p.html')).to.equal('file:///output/run/p.html')
     })
+
+    it('encodes spaces and special characters via pathToFileURL', () => {
+      const url = fileToUrl('/output/run dir', 'p age.html')
+      expect(url).to.equal('file:///output/run%20dir/p%20age.html')
+    })
   })
 
   describe('artifactsToFileUrls', () => {
@@ -339,6 +344,16 @@ describe('lib/utils/trace.js', () => {
       expect(html.split('\n').length).to.be.greaterThan(2)
     })
 
+    it('exposes pre-cleanup HTML in out.htmlRaw for class-scanning consumers', async () => {
+      const raw = '<html><body><div class="text-error alert-1">boom</div></body></html>'
+      const helper = fullHelper({ grabSource: sinon.stub().resolves(raw) })
+      const out = await captureSnapshot(helper, { dir, prefix: 'p' })
+      expect(out.htmlRaw).to.equal(raw)
+      const formatted = fs.readFileSync(path.join(dir, 'p_page.html'), 'utf8')
+      expect(formatted).to.not.include('text-error')
+      expect(formatted).to.not.include('alert-1')
+    })
+
     it('normalizes Playwright ConsoleMessage objects to {type, text}', async () => {
       const playwrightLog = {
         type: () => 'error',