diff --git a/bin/mcp-server.js b/bin/mcp-server.js
index fba958125..0b3c5458f 100644
--- a/bin/mcp-server.js
+++ b/bin/mcp-server.js
@@ -4,15 +4,22 @@ 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,
+  pickActingHelper,
+  traceDirFor,
+  snapshotDirFor,
+  artifactsToFileUrls,
+  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 crypto from 'crypto'
 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)
@@ -224,15 +231,8 @@ async function resolveTestToFile({ cli, root, configPath, test }) {
   return fsFound ? normalizePath(fsFound) : null
 }
 
-function clearString(str) {
-  return str.replace(/[^a-zA-Z0-9]/g, '_')
-}
-
-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 outputBaseDir() {
+  return global.output_dir || resolvePath(process.cwd(), 'output')
 }
 
 async function initCodecept(configPath) {
@@ -337,6 +337,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 +427,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: pathToFileURL(traceFile).href,
+              artifacts: artifactsToFileUrls(captured, dir),
+            }, null, 2),
+          }],
+        }
+      }
+
       case 'run_code': {
         const { code, timeout = 60000, config: configPath, saveArtifacts = true } = args
         await initCodecept(configPath)
@@ -423,67 +467,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 = pathToFileURL(traceFile).href
+
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
       }
 
@@ -549,27 +618,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 = pathToFileURL(t.artifacts.aiTrace).href
+              }
+              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 {
+                  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 = pathToFileURL(tracePath).href
+                  }
+                } 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 e24f8db49..bfd36f126 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,7 +8,7 @@ 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'
+import { captureSnapshot, pickActingHelper, traceDirFor, artifactLinks } from '../utils/trace.js'
 import {
   parsePluginArgs,
   resolveTrigger,
@@ -18,8 +16,6 @@ import {
   matchUrl,
 } from '../utils/pluginParser.js'
 
-const supportedHelpers = Container.STANDARD_ACTING_HELPERS
-
 const defaultConfig = {
   on: 'step',
   deleteSuccessful: false,
@@ -73,20 +69,13 @@ const defaultConfig = {
  * @param {*} config
  */
 export default function (config = {}) {
-  const helpers = Container.helpers()
-  let helper
-
   const cliArgs = parsePluginArgs(config._args)
   const trigger = resolveTrigger(cliArgs, config, { on: defaultConfig.on }, { name: 'aiTrace' })
   if (!trigger) return
 
   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.')
@@ -126,13 +115,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)
@@ -320,6 +303,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
@@ -327,6 +311,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 {
@@ -335,58 +320,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}`)
@@ -449,22 +407,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..3490f28f1 100644
--- a/lib/plugin/pageInfo.js
+++ b/lib/plugin/pageInfo.js
@@ -1,14 +1,15 @@
 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, pickActingHelper } from '../utils/trace.js'
 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'],
@@ -37,57 +38,58 @@ 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 () => {
-      try {
-        const url = await helper.grabCurrentUrl()
-        pageState.url = url
-      } catch (err) {
-        // not really needed
-      }
-    })
-    recorder.add('HTML snapshot failed test', async () => {
+    recorder.add('pageInfo capture', 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
+          // 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 {}
+          }
         }
-      } 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 +129,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/trace.js b/lib/utils/trace.js
new file mode 100644
index 000000000..af6f5863b
--- /dev/null
+++ b/lib/utils/trace.js
@@ -0,0 +1,240 @@
+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'
+
+// ---------------------------------------------------------------------------
+// Helper / directory naming
+// ---------------------------------------------------------------------------
+
+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}`)
+}
+
+// ---------------------------------------------------------------------------
+// Artifact link rendering (trace.md)
+// ---------------------------------------------------------------------------
+
+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 pathToFileURL(path.join(dir, basename)).href
+}
+
+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
+  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
+}
+
+// ---------------------------------------------------------------------------
+// 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
+      // 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 {}
+  }
+
+  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/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/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>')
+    })
+  })
 })
diff --git a/test/unit/utils/trace_test.js b/test/unit/utils/trace_test.js
new file mode 100644
index 000000000..573695f6f
--- /dev/null
+++ b/test/unit/utils/trace_test.js
@@ -0,0 +1,433 @@
+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')
+    })
+
+    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', () => {
+    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('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',
+        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')
+    })
+  })
+})