@andrii_kremlovskyi/playwright-traces-reader 1.0.0

package/README.md

@@ -0,0 +1,164 @@
+# playwright-traces-reader
+
+Parse [Playwright](https://playwright.dev) trace files into structured data — useful for AI agents, custom reporters, and post-run analysis tooling.
+
+## Features
+
+- Extract test steps with timings and errors
+- Extract failed steps with full error messages
+- Extract API and browser network traffic (with resolved request/response bodies)
+- Save screenshots from screencasts
+- Extract full DOM snapshots (before / during / after each action) with back-reference resolution
+- Support for multi-test reports (many SHA1 trace entries in one `data/` directory)
+- GitHub Copilot skill scaffold via `init-skills` CLI command
+
+## Installation
+
+```bash
+npm install @kremlovskyi/playwright-traces-reader
+```
+
+## Quick Start
+
+```typescript
+import {
+  prepareTraceDir,
+  getFailedTests,
+  getNetworkTraffic,
+  getTestSteps,
+  extractScreenshots,
+  getDomSnapshots,
+} from '@kremlovskyi/playwright-traces-reader';
+
+// Point at a single extracted trace directory (or a .zip)
+const ctx = await prepareTraceDir('/path/to/playwright-report/data/<sha1>');
+
+const failures = await getFailedTests(ctx);
+const traffic  = await getNetworkTraffic(ctx);
+const steps    = await getTestSteps(ctx);
+```
+
+### Multi-test reports
+
+A Playwright HTML report stores one trace entry per test inside `playwright-report/data/`. Use `listTraces()` to iterate all of them:
+
+```typescript
+import { listTraces, getFailedTests } from '@kremlovskyi/playwright-traces-reader';
+
+const traces = await listTraces('/path/to/playwright-report/data');
+
+for (const ctx of traces) {
+  const failures = await getFailedTests(ctx);
+  // ... process per-test results
+}
+```
+
+Both extracted directories and `.zip` archives are handled automatically. Non-trace files (`.md`, `.png`, etc.) are ignored.
+
+## API
+
+### `listTraces(reportDataDir)`
+
+Discovers all trace contexts inside a `data/` directory. Returns `TraceContext[]`.
+
+### `prepareTraceDir(tracePath)`
+
+Takes a single path (extracted directory or `.zip`) and returns a `TraceContext`.
+
+### `getTestSteps(ctx)`
+
+Returns the full step tree from `test.trace` as `TestStep[]`. Each step has:
+
+| Field | Type | Description |
+|---|---|---|
+| `callId` | `string` | Unique step identifier |
+| `title` | `string` | Human-readable step name |
+| `method` | `string \| undefined` | API method if applicable |
+| `startTime` | `number` | Unix ms timestamp |
+| `endTime` | `number \| null` | Unix ms timestamp |
+| `durationMs` | `number \| null` | Wall-clock duration |
+| `error` | `TraceError \| null` | Error details if the step failed |
+| `children` | `TestStep[]` | Nested child steps |
+
+### `getFailedTests(ctx)`
+
+Walks the step tree and returns a flat `FailedStep[]` for every step that has an `error`. Useful as a quick failure summary.
+
+### `getNetworkTraffic(ctx)`
+
+Returns `NetworkEntry[]` from all `*.network` trace files. Each entry includes:
+
+| Field | Type | Description |
+|---|---|---|
+| `url` | `string` | Request URL |
+| `method` | `string` | HTTP method |
+| `status` | `number` | HTTP response status |
+| `source` | `'api' \| 'browser'` | `'api'` = Playwright `APIRequestContext`; `'browser'` = XHR / navigation |
+| `requestBody` | `string \| null` | Resolved request body |
+| `responseBody` | `string \| null` | Resolved response body (binary → `[binary: ...]` placeholder) |
+| `contentType` | `string \| null` | Response content-type |
+| `pageref` | `string \| undefined` | Browser page ID (browser traffic only) |
+
+### `extractScreenshots(ctx, outDir)`
+
+Writes screencast frames from all `[N]-trace.trace` files to `outDir` as numbered `.jpeg` files. Returns `Screenshot[]` with `savedPath`, `timestamp`, `pageId`, `width`, and `height`.
+
+### `getDomSnapshots(ctx)`
+
+Returns `ActionDomSnapshots[]` — one entry per browser action that has DOM snapshots. Each entry groups three phases:
+
+| Field | Type | Description |
+|---|---|---|
+| `callId` | `string` | Action identifier |
+| `before` | `DomSnapshot \| null` | DOM before the action |
+| `action` | `DomSnapshot \| null` | DOM during the action (mid-interaction) |
+| `after` | `DomSnapshot \| null` | DOM after the action completed |
+
+Each `DomSnapshot` contains:
+
+| Field | Type | Description |
+|---|---|---|
+| `html` | `string` | Full serialized HTML (back-references resolved, `<script>` stripped) |
+| `phase` | `'before' \| 'action' \| 'after'` | Snapshot phase |
+| `frameUrl` | `string` | URL of the frame at snapshot time |
+| `targetElement` | `string \| null` | `callId` of the action that targeted an element, or `null` |
+| `viewport` | `{ width: number; height: number }` | Viewport dimensions |
+| `timestamp` | `number` | Unix ms timestamp |
+
+### `getResourceBuffer(ctx, sha1)`
+
+Low-level helper. Resolves a SHA1 filename to a raw `Buffer` from `resources/`. Returns `null` if not found.
+
+### `readNdjson<T>(filePath)`
+
+Low-level async generator that streams and parses an NDJSON file line by line. Silently skips malformed lines.
+
+## GitHub Copilot Skill
+
+Install a ready-made GitHub Copilot skill scaffold into your project:
+
+```bash
+npx @kremlovskyi/playwright-traces-reader init-skills
+# or into a custom target directory:
+npx @kremlovskyi/playwright-traces-reader init-skills ./my-project
+```
+
+This copies a `SKILL.md` template to `.github/skills/analyze-playwright-traces/SKILL.md` with code examples for all extractor functions. Once in place, GitHub Copilot will use the skill automatically when answering questions about your Playwright test runs.
+
+## Trace Format
+
+Playwright HTML reports store traces in `playwright-report/data/<sha1>/`:
+
+```
+<sha1>/
+├── test.trace          ← step tree (getTestSteps / getFailedTests)
+├── 0-trace.trace       ← browser actions, screenshots, DOM snapshots
+├── 0-trace.network     ← network HAR entries
+└── resources/          ← binary blobs (bodies, images) addressed by SHA1
+```
+
+All trace files use **Newline-Delimited JSON (NDJSON)**.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const [, , command, ...args] = process.argv;
+async function initSkills(targetDir) {
+    const skillDir = path.join(targetDir, '.github', 'skills', 'analyze-playwright-traces');
+    await fs.promises.mkdir(skillDir, { recursive: true });
+    // Copy the template SKILL.md from this package
+    const templatePath = path.resolve(__dirname, '..', 'templates', 'skills', 'analyze-playwright-traces', 'SKILL.md');
+    const destPath = path.join(skillDir, 'SKILL.md');
+    if (!fs.existsSync(templatePath)) {
+        console.error(`Template not found at ${templatePath}`);
+        process.exit(1);
+    }
+    await fs.promises.copyFile(templatePath, destPath);
+    console.log(`✔ Skill scaffolded at ${destPath}`);
+}
+async function main() {
+    if (command === 'init-skills') {
+        const targetDir = args[0] ?? process.cwd();
+        await initSkills(targetDir);
+        return;
+    }
+    console.log(`
+playwright-traces-reader — CLI for parsing Playwright trace files
+
+Usage:
+  npx playwright-traces-reader init-skills [targetDir]
+    Scaffolds the GitHub Copilot skill template into <targetDir>/.github/skills/analyze-playwright-traces/SKILL.md
+    Defaults targetDir to the current working directory.
+`);
+}
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,uCAAyB;AACzB,2CAA6B;AAE7B,MAAM,CAAC,EAAE,AAAD,EAAG,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;AAE5C,KAAK,UAAU,UAAU,CAAC,SAAiB;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,2BAA2B,CAAC,CAAC;IACxF,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvD,+CAA+C;IAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,2BAA2B,EAAE,UAAU,CAAC,CAAC;IACnH,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAEjD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,OAAO,CAAC,KAAK,CAAC,yBAAyB,YAAY,EAAE,CAAC,CAAC;QACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACnD,OAAO,CAAC,GAAG,CAAC,yBAAyB,QAAQ,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAC3C,MAAM,UAAU,CAAC,SAAS,CAAC,CAAC;QAC5B,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC;;;;;;;CAOb,CAAC,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/extractors.d.ts

@@ -0,0 +1,131 @@
+import { type TraceContext } from './parseTrace';
+export interface TestStep {
+    callId: string;
+    parentId: string | null;
+    title: string;
+    method: string;
+    startTime: number;
+    endTime: number | null;
+    durationMs: number | null;
+    error: TraceError | null;
+    children: TestStep[];
+}
+export interface TraceError {
+    name: string;
+    message: string;
+    stack?: string;
+}
+export interface FailedStep {
+    callId: string;
+    title: string;
+    error: TraceError;
+    durationMs: number | null;
+}
+export interface NetworkEntry {
+    source: 'browser' | 'api';
+    method: string;
+    url: string;
+    status: number;
+    statusText: string;
+    requestHeaders: Array<{
+        name: string;
+        value: string;
+    }>;
+    responseHeaders: Array<{
+        name: string;
+        value: string;
+    }>;
+    requestBody: string | null;
+    responseBody: string | null;
+    mimeType: string;
+    startedDateTime: string;
+    durationMs: number;
+}
+export interface Screenshot {
+    sha1: string;
+    timestamp: number;
+    pageId: string;
+    width: number;
+    height: number;
+    savedPath: string;
+}
+/**
+ * Reconstructs the test step tree from a test.trace file.
+ * Returns top-level steps (roots), each with nested children.
+ */
+export declare function getTestSteps(traceContext: TraceContext): Promise<TestStep[]>;
+/**
+ * Scans test.trace for steps that have errors.
+ * Returns a flat list of all steps (at any nesting level) that failed,
+ * with the error details and duration.
+ */
+export declare function getFailedTests(traceContext: TraceContext): Promise<FailedStep[]>;
+/**
+ * Reads all *.network files in the trace directory and returns structured
+ * network entries. Each entry is tagged as 'browser' (has pageref) or
+ * 'api' (has _apiRequest, no pageref). Response and request bodies are
+ * resolved from the resources/ directory when a _sha1 reference exists.
+ */
+export declare function getNetworkTraffic(traceContext: TraceContext): Promise<NetworkEntry[]>;
+/**
+ * Finds all screencast-frame entries across all *-trace.trace files,
+ * copies the referenced JPEG/PNG blobs from resources/ into outDir as
+ * numbered files, and returns metadata including the saved file path.
+ */
+export declare function extractScreenshots(traceContext: TraceContext, outDir: string): Promise<Screenshot[]>;
+/**
+ * A single serialized DOM snapshot for one phase of one action.
+ *
+ * `phase`:
+ *   - `"before"` — DOM state before the action started (default recorded point)
+ *   - `"action"` — DOM state during the action (corresponds to Trace Viewer's "Action" tab)
+ *   - `"after"`  — DOM state after the action completed
+ *
+ * `html` is the snapshot serialized to an HTML string. Back-references inside
+ * Playwright's compact snapshot format (`[[offset, nodeIdx]]`) are resolved using
+ * the per-frame snapshot history: `offset` is how many snapshots to go back (from
+ * the current snapshot's index) within this frame's history, and `nodeIdx` is the
+ * index in the post-order DFS traversal of that historical snapshot.
+ *
+ * `targetElement` is the value of the `__playwright_target__` attribute on
+ * the interacted element (the `callId` of the action that targeted it), if any.
+ */
+export interface DomSnapshot {
+    callId: string;
+    phase: 'before' | 'action' | 'after';
+    snapshotName: string;
+    frameId: string;
+    frameUrl: string;
+    pageId: string;
+    timestamp: number;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    html: string;
+    targetElement: string | null;
+}
+/**
+ * A complete set of DOM snapshots for a single browser action, grouping
+ * the before/action/after phases together.
+ */
+export interface ActionDomSnapshots {
+    callId: string;
+    before: DomSnapshot | null;
+    action: DomSnapshot | null;
+    after: DomSnapshot | null;
+}
+/**
+ * Extracts DOM snapshots from all browser context trace files (`[N]-trace.trace`
+ * where the context is a browser context, i.e. has frame-snapshot entries).
+ *
+ * Returns one `ActionDomSnapshots` per unique `callId` found, with all three
+ * phases (`before`, `action`, `after`) populated when available.
+ *
+ * Back-references in Playwright's compact snapshot format are resolved using
+ * the per-frame snapshot history: `[[offset, nodeIdx]]` means "go back `offset`
+ * snapshots in this frame's history, find the `nodeIdx`-th node in post-order
+ * DFS of that snapshot".
+ */
+export declare function getDomSnapshots(traceContext: TraceContext): Promise<ActionDomSnapshots[]>;
+//# sourceMappingURL=extractors.d.ts.map

package/dist/extractors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractors.d.ts","sourceRoot":"","sources":["../src/extractors.ts"],"names":[],"mappings":"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"}

package/dist/extractors.js

@@ -0,0 +1,429 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTestSteps = getTestSteps;
+exports.getFailedTests = getFailedTests;
+exports.getNetworkTraffic = getNetworkTraffic;
+exports.extractScreenshots = extractScreenshots;
+exports.getDomSnapshots = getDomSnapshots;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const parseTrace_1 = require("./parseTrace");
+// ---------- getTestSteps ----------
+/**
+ * Reconstructs the test step tree from a test.trace file.
+ * Returns top-level steps (roots), each with nested children.
+ */
+async function getTestSteps(traceContext) {
+    const testTracePath = path.join(traceContext.traceDir, 'test.trace');
+    const stepMap = new Map();
+    const roots = [];
+    for await (const event of (0, parseTrace_1.readNdjson)(testTracePath)) {
+        if (event.type === 'before') {
+            const step = {
+                callId: event.callId,
+                parentId: event.parentId ?? null,
+                title: event.title,
+                method: event.method,
+                startTime: event.startTime,
+                endTime: null,
+                durationMs: null,
+                error: null,
+                children: [],
+            };
+            stepMap.set(event.callId, step);
+            if (event.parentId) {
+                const parent = stepMap.get(event.parentId);
+                if (parent) {
+                    parent.children.push(step);
+                }
+                else {
+                    roots.push(step);
+                }
+            }
+            else {
+                roots.push(step);
+            }
+        }
+        else if (event.type === 'after') {
+            const step = stepMap.get(event.callId);
+            if (step) {
+                step.endTime = event.endTime;
+                step.durationMs = event.endTime - step.startTime;
+                if (event.error) {
+                    step.error = event.error;
+                }
+            }
+        }
+    }
+    return roots;
+}
+// ---------- getFailedTests ----------
+/**
+ * Scans test.trace for steps that have errors.
+ * Returns a flat list of all steps (at any nesting level) that failed,
+ * with the error details and duration.
+ */
+async function getFailedTests(traceContext) {
+    const roots = await getTestSteps(traceContext);
+    const failed = [];
+    function collect(steps) {
+        for (const step of steps) {
+            if (step.error) {
+                failed.push({
+                    callId: step.callId,
+                    title: step.title,
+                    error: step.error,
+                    durationMs: step.durationMs,
+                });
+            }
+            collect(step.children);
+        }
+    }
+    collect(roots);
+    return failed;
+}
+// ---------- getNetworkTraffic ----------
+/**
+ * Reads all *.network files in the trace directory and returns structured
+ * network entries. Each entry is tagged as 'browser' (has pageref) or
+ * 'api' (has _apiRequest, no pageref). Response and request bodies are
+ * resolved from the resources/ directory when a _sha1 reference exists.
+ */
+async function getNetworkTraffic(traceContext) {
+    const entries = [];
+    const files = await fs.promises.readdir(traceContext.traceDir);
+    const networkFiles = files.filter(f => f.endsWith('.network')).sort();
+    for (const networkFile of networkFiles) {
+        const filePath = path.join(traceContext.traceDir, networkFile);
+        for await (const event of (0, parseTrace_1.readNdjson)(filePath)) {
+            if (event.type !== 'resource-snapshot')
+                continue;
+            const snap = event.snapshot;
+            const isBrowser = Boolean(snap.pageref);
+            const source = isBrowser ? 'browser' : 'api';
+            // Resolve request body
+            let requestBody = null;
+            const postData = snap.request.postData;
+            if (postData) {
+                if (postData.text) {
+                    requestBody = postData.text;
+                }
+                else if (postData._sha1) {
+                    const sha1 = postData._sha1.replace(/\.bin$/, '');
+                    const buf = await (0, parseTrace_1.getResourceBuffer)(traceContext, postData._sha1) ??
+                        await (0, parseTrace_1.getResourceBuffer)(traceContext, sha1);
+                    if (buf)
+                        requestBody = buf.toString('utf8');
+                }
+            }
+            // Resolve response body
+            let responseBody = null;
+            const content = snap.response.content;
+            if (content._sha1) {
+                const buf = await (0, parseTrace_1.getResourceBuffer)(traceContext, content._sha1);
+                if (buf) {
+                    if (content.mimeType.includes('json') || content.mimeType.includes('text')) {
+                        responseBody = buf.toString('utf8');
+                    }
+                    else {
+                        responseBody = `[binary: ${content.mimeType}, ${buf.length} bytes]`;
+                    }
+                }
+            }
+            else if (content.text) {
+                responseBody = content.text;
+            }
+            entries.push({
+                source,
+                method: snap.request.method,
+                url: snap.request.url,
+                status: snap.response.status,
+                statusText: snap.response.statusText,
+                requestHeaders: snap.request.headers,
+                responseHeaders: snap.response.headers,
+                requestBody,
+                responseBody,
+                mimeType: content.mimeType,
+                startedDateTime: snap.startedDateTime,
+                durationMs: snap.time,
+            });
+        }
+    }
+    return entries;
+}
+// ---------- extractScreenshots ----------
+/**
+ * Finds all screencast-frame entries across all *-trace.trace files,
+ * copies the referenced JPEG/PNG blobs from resources/ into outDir as
+ * numbered files, and returns metadata including the saved file path.
+ */
+async function extractScreenshots(traceContext, outDir) {
+    const screenshots = [];
+    await fs.promises.mkdir(outDir, { recursive: true });
+    const files = await fs.promises.readdir(traceContext.traceDir);
+    const traceFiles = files.filter(f => f.endsWith('.trace') && f !== 'test.trace').sort();
+    let index = 0;
+    for (const traceFile of traceFiles) {
+        const filePath = path.join(traceContext.traceDir, traceFile);
+        for await (const event of (0, parseTrace_1.readNdjson)(filePath)) {
+            if (event.type !== 'screencast-frame')
+                continue;
+            const buf = await (0, parseTrace_1.getResourceBuffer)(traceContext, event.sha1);
+            if (!buf)
+                continue;
+            const ext = event.sha1.endsWith('.jpeg') ? 'jpeg' : 'png';
+            const outFileName = `screenshot-${String(index).padStart(4, '0')}.${ext}`;
+            const savedPath = path.join(outDir, outFileName);
+            await fs.promises.writeFile(savedPath, buf);
+            screenshots.push({
+                sha1: event.sha1,
+                timestamp: event.timestamp,
+                pageId: event.pageId,
+                width: event.width,
+                height: event.height,
+                savedPath,
+            });
+            index++;
+        }
+    }
+    return screenshots;
+}
+/**
+ * Builds the post-order DFS node list for a snapshot tree (mirroring
+ * Playwright's `snapshotNodes()` in snapshotRenderer.ts). Only "real"
+ * element/text nodes are added — subtree refs are not in the list.
+ * This list is used for back-reference resolution.
+ *
+ * Results are memoized in `cache` (keyed by the html object reference) to avoid
+ * recomputing the same large trees when many back-references point to the same
+ * historical snapshot.
+ */
+function buildSnapshotNodeList(html, cache) {
+    const cached = cache.get(html);
+    if (cached)
+        return cached;
+    const nodes = [];
+    function visit(n) {
+        if (typeof n === 'string') {
+            nodes.push(n);
+            return;
+        }
+        if (!Array.isArray(n))
+            return;
+        // Subtree ref: [[offset, idx]] — skip (not a real node)
+        if (Array.isArray(n[0]))
+            return;
+        // Element: [tagName, attrs, ...children] — recurse children first (post-order)
+        const [, , ...children] = n;
+        for (const child of children)
+            visit(child);
+        nodes.push(n);
+    }
+    visit(html);
+    cache.set(html, nodes);
+    return nodes;
+}
+const VOID_TAGS = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'keygen', 'link', 'menuitem', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+/**
+ * Resolves a snapshot node tree into an HTML string.
+ *
+ * `snapshotIndex` is the 0-based index of the current snapshot in `frameHistory`.
+ * `frameHistory` is the ordered list of all raw snapshot HTMLs seen so far for
+ * this frame (current snapshot is already appended before this call).
+ * `dfsCache` is a memoization cache shared across the entire trace-file pass to
+ * avoid rebuilding the same DFS node lists repeatedly.
+ *
+ * Back-references `[[offset, nodeIdx]]` are resolved as:
+ *   refIndex = snapshotIndex - offset
+ *   node     = snapshotNodes(frameHistory[refIndex])[nodeIdx]
+ */
+function resolveSnapshotNode(node, snapshotIndex, frameHistory, dfsCache) {
+    if (typeof node === 'string') {
+        return escapeHtml(node);
+    }
+    if (!Array.isArray(node))
+        return '';
+    // Subtree reference: [[offset, nodeIdx]]
+    if (Array.isArray(node[0]) &&
+        node[0].length === 2 &&
+        typeof node[0][0] === 'number' &&
+        typeof node[0][1] === 'number') {
+        const [offset, nodeIdx] = node[0];
+        const refIndex = snapshotIndex - offset;
+        if (refIndex >= 0 && refIndex < frameHistory.length) {
+            const refHtml = frameHistory[refIndex];
+            const nodes = buildSnapshotNodeList(refHtml, dfsCache);
+            if (nodeIdx >= 0 && nodeIdx < nodes.length) {
+                return resolveSnapshotNode(nodes[nodeIdx], refIndex, frameHistory, dfsCache);
+            }
+        }
+        return `<!-- ref: [${offset}, ${nodeIdx}] unresolved -->`;
+    }
+    // Element node: [tagName, attrs, ...children]
+    const [tagName, attrs, ...children] = node;
+    if (typeof tagName !== 'string')
+        return '';
+    const tag = tagName.toLowerCase();
+    if (tag === 'script')
+        return ''; // not useful for AI analysis
+    const attrStr = attrs && typeof attrs === 'object' && !Array.isArray(attrs)
+        ? Object.entries(attrs)
+            .filter(([k]) => !k.startsWith('__playwright'))
+            .map(([k, v]) => ` ${k}="${escapeAttr(String(v))}"`)
+            .join('')
+        : '';
+    if (VOID_TAGS.has(tag)) {
+        return `<${tag}${attrStr}>`;
+    }
+    const inner = children.map(c => resolveSnapshotNode(c, snapshotIndex, frameHistory, dfsCache)).join('');
+    return `<${tag}${attrStr}>${inner}</${tag}>`;
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function escapeAttr(s) {
+    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+}
+/**
+ * Extracts DOM snapshots from all browser context trace files (`[N]-trace.trace`
+ * where the context is a browser context, i.e. has frame-snapshot entries).
+ *
+ * Returns one `ActionDomSnapshots` per unique `callId` found, with all three
+ * phases (`before`, `action`, `after`) populated when available.
+ *
+ * Back-references in Playwright's compact snapshot format are resolved using
+ * the per-frame snapshot history: `[[offset, nodeIdx]]` means "go back `offset`
+ * snapshots in this frame's history, find the `nodeIdx`-th node in post-order
+ * DFS of that snapshot".
+ */
+async function getDomSnapshots(traceContext) {
+    const files = await fs.promises.readdir(traceContext.traceDir);
+    const traceFiles = files.filter(f => f.endsWith('.trace') && f !== 'test.trace').sort();
+    // Per-frame snapshot history: frameId → ordered list of raw html nodes
+    const frameHistory = new Map();
+    // Memoization cache for buildSnapshotNodeList — keyed by html object reference
+    const dfsCache = new Map();
+    // Collect resolved snapshots keyed by callId → phase
+    const rawByCallId = new Map();
+    for (const traceFile of traceFiles) {
+        const filePath = path.join(traceContext.traceDir, traceFile);
+        for await (const event of (0, parseTrace_1.readNdjson)(filePath)) {
+            if (event.type !== 'frame-snapshot')
+                continue;
+            const snap = event.snapshot;
+            const { snapshotName, callId, frameId, frameUrl, pageId, viewport, timestamp, html } = snap;
+            // Determine phase from snapshotName prefix
+            let phase;
+            if (snapshotName.startsWith('before@')) {
+                phase = 'before';
+            }
+            else if (snapshotName.startsWith('after@')) {
+                phase = 'after';
+            }
+            else if (snapshotName.startsWith('input@')) {
+                phase = 'action';
+            }
+            else {
+                continue; // unknown phase, skip
+            }
+            // Append to per-frame history BEFORE resolving (so refs can point back to it)
+            if (!frameHistory.has(frameId))
+                frameHistory.set(frameId, []);
+            const history = frameHistory.get(frameId);
+            history.push(html);
+            const snapshotIndex = history.length - 1;
+            // Resolve the full html to a string using the correct ref algorithm
+            const resolvedHtml = resolveSnapshotNode(html, snapshotIndex, history, dfsCache);
+            // Extract the __playwright_target__ attribute to identify the targeted element
+            const targetElement = findPlaywrightTarget(html);
+            const domSnapshot = {
+                callId,
+                phase,
+                snapshotName,
+                frameId,
+                frameUrl,
+                pageId,
+                timestamp,
+                viewport,
+                html: resolvedHtml,
+                targetElement,
+            };
+            if (!rawByCallId.has(callId))
+                rawByCallId.set(callId, new Map());
+            rawByCallId.get(callId).set(phase, domSnapshot);
+        }
+    }
+    // Assemble into ActionDomSnapshots
+    const result = [];
+    for (const [callId, phases] of rawByCallId) {
+        result.push({
+            callId,
+            before: phases.get('before') ?? null,
+            action: phases.get('action') ?? null,
+            after: phases.get('after') ?? null,
+        });
+    }
+    result.sort((a, b) => {
+        const ta = (a.before ?? a.action ?? a.after)?.timestamp ?? 0;
+        const tb = (b.before ?? b.action ?? b.after)?.timestamp ?? 0;
+        return ta - tb;
+    });
+    return result;
+}
+/** Recursively searches the snapshot tree for a node with __playwright_target__ */
+function findPlaywrightTarget(node) {
+    if (!Array.isArray(node) || node.length < 2)
+        return null;
+    const attrs = node[1];
+    if (attrs && typeof attrs === 'object' && !Array.isArray(attrs)) {
+        const target = attrs['__playwright_target__'];
+        if (target)
+            return target;
+    }
+    for (let i = 2; i < node.length; i++) {
+        const child = node[i];
+        if (Array.isArray(child)) {
+            const found = findPlaywrightTarget(child);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=extractors.js.map

package/dist/extractors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractors.js","sourceRoot":"","sources":["../src/extractors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { prepareTraceDir, readNdjson, getResourceBuffer, listTraces } from './parseTrace';
+export type { TraceContext } from './parseTrace';
+export { getTestSteps, getFailedTests, getNetworkTraffic, extractScreenshots, getDomSnapshots, } from './extractors';
+export type { TestStep, TraceError, FailedStep, NetworkEntry, Screenshot, DomSnapshot, ActionDomSnapshots, } from './extractors';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1F,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EACL,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAChB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,QAAQ,EACR,UAAU,EACV,UAAU,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACX,kBAAkB,GACnB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDomSnapshots = exports.extractScreenshots = exports.getNetworkTraffic = exports.getFailedTests = exports.getTestSteps = exports.listTraces = exports.getResourceBuffer = exports.readNdjson = exports.prepareTraceDir = void 0;
+var parseTrace_1 = require("./parseTrace");
+Object.defineProperty(exports, "prepareTraceDir", { enumerable: true, get: function () { return parseTrace_1.prepareTraceDir; } });
+Object.defineProperty(exports, "readNdjson", { enumerable: true, get: function () { return parseTrace_1.readNdjson; } });
+Object.defineProperty(exports, "getResourceBuffer", { enumerable: true, get: function () { return parseTrace_1.getResourceBuffer; } });
+Object.defineProperty(exports, "listTraces", { enumerable: true, get: function () { return parseTrace_1.listTraces; } });
+var extractors_1 = require("./extractors");
+Object.defineProperty(exports, "getTestSteps", { enumerable: true, get: function () { return extractors_1.getTestSteps; } });
+Object.defineProperty(exports, "getFailedTests", { enumerable: true, get: function () { return extractors_1.getFailedTests; } });
+Object.defineProperty(exports, "getNetworkTraffic", { enumerable: true, get: function () { return extractors_1.getNetworkTraffic; } });
+Object.defineProperty(exports, "extractScreenshots", { enumerable: true, get: function () { return extractors_1.extractScreenshots; } });
+Object.defineProperty(exports, "getDomSnapshots", { enumerable: true, get: function () { return extractors_1.getDomSnapshots; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,2CAA0F;AAAjF,6GAAA,eAAe,OAAA;AAAE,wGAAA,UAAU,OAAA;AAAE,+GAAA,iBAAiB,OAAA;AAAE,wGAAA,UAAU,OAAA;AAGnE,2CAMsB;AALpB,0GAAA,YAAY,OAAA;AACZ,4GAAA,cAAc,OAAA;AACd,+GAAA,iBAAiB,OAAA;AACjB,gHAAA,kBAAkB,OAAA;AAClB,6GAAA,eAAe,OAAA"}

package/dist/parseTrace.d.ts

@@ -0,0 +1,30 @@
+export interface TraceContext {
+    traceDir: string;
+}
+/**
+ * Ensures the trace is available as a directory.
+ * If a .zip file is provided, it extracts it to a temporary directory.
+ */
+export declare function prepareTraceDir(tracePath: string): Promise<TraceContext>;
+/**
+ * Reads a Newline Delimited JSON (NDJSON) file line by line and yields parsed objects.
+ */
+export declare function readNdjson<T = any>(filePath: string): AsyncGenerator<T>;
+/**
+ * Returns raw file buffer from the resources/ directory of a trace
+ */
+export declare function getResourceBuffer(traceContext: TraceContext, sha1: string): Promise<Buffer | null>;
+/**
+ * Discovers all individual test traces inside a Playwright report data directory.
+ *
+ * A report's `data/` directory can contain many SHA1-named entries — one per test
+ * execution. Each entry is either a directory or a `.zip` archive. Non-trace files
+ * (`.md`, `.png`, `.json`, etc.) are ignored.
+ *
+ * Returns a `TraceContext` for every trace found, with `.zip` archives extracted
+ * in-place (same directory, no suffix).
+ *
+ * @param reportDataDir  Path to the `playwright-report/data/` directory.
+ */
+export declare function listTraces(reportDataDir: string): Promise<TraceContext[]>;
+//# sourceMappingURL=parseTrace.d.ts.map

package/dist/parseTrace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseTrace.d.ts","sourceRoot":"","sources":["../src/parseTrace.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAgB9E;AAED;;GAEG;AACH,wBAAuB,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAmB9E;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMxG;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA6B/E"}

package/dist/parseTrace.js

@@ -0,0 +1,137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareTraceDir = prepareTraceDir;
+exports.readNdjson = readNdjson;
+exports.getResourceBuffer = getResourceBuffer;
+exports.listTraces = listTraces;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const adm_zip_1 = __importDefault(require("adm-zip"));
+/**
+ * Ensures the trace is available as a directory.
+ * If a .zip file is provided, it extracts it to a temporary directory.
+ */
+async function prepareTraceDir(tracePath) {
+    const stat = await fs.promises.stat(tracePath);
+    if (stat.isDirectory()) {
+        return { traceDir: tracePath };
+    }
+    if (tracePath.endsWith('.zip')) {
+        const outDir = tracePath.replace(/\.zip$/, '');
+        if (!fs.existsSync(outDir)) {
+            const zip = new adm_zip_1.default(tracePath);
+            zip.extractAllTo(outDir, true);
+        }
+        return { traceDir: outDir };
+    }
+    throw new Error(`Invalid trace path: ${tracePath}. Must be a directory or .zip file.`);
+}
+/**
+ * Reads a Newline Delimited JSON (NDJSON) file line by line and yields parsed objects.
+ */
+async function* readNdjson(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return;
+    }
+    const fileStream = fs.createReadStream(filePath);
+    const rl = readline.createInterface({
+        input: fileStream,
+        crlfDelay: Infinity
+    });
+    for await (const line of rl) {
+        if (line.trim()) {
+            try {
+                yield JSON.parse(line);
+            }
+            catch (e) {
+                // Ignore malformed lines
+            }
+        }
+    }
+}
+/**
+ * Returns raw file buffer from the resources/ directory of a trace
+ */
+async function getResourceBuffer(traceContext, sha1) {
+    const resourcePath = path.join(traceContext.traceDir, 'resources', sha1);
+    if (fs.existsSync(resourcePath)) {
+        return fs.promises.readFile(resourcePath);
+    }
+    return null;
+}
+/**
+ * Discovers all individual test traces inside a Playwright report data directory.
+ *
+ * A report's `data/` directory can contain many SHA1-named entries — one per test
+ * execution. Each entry is either a directory or a `.zip` archive. Non-trace files
+ * (`.md`, `.png`, `.json`, etc.) are ignored.
+ *
+ * Returns a `TraceContext` for every trace found, with `.zip` archives extracted
+ * in-place (same directory, no suffix).
+ *
+ * @param reportDataDir  Path to the `playwright-report/data/` directory.
+ */
+async function listTraces(reportDataDir) {
+    const entries = await fs.promises.readdir(reportDataDir, { withFileTypes: true });
+    const tracePaths = [];
+    for (const entry of entries) {
+        const fullPath = path.join(reportDataDir, entry.name);
+        // Resolve symlinks so we can reliably check if it's a directory
+        const isDir = entry.isDirectory() ||
+            (entry.isSymbolicLink() && (await fs.promises.stat(fullPath)).isDirectory());
+        if (isDir) {
+            // A directory is a trace if it contains a test.trace file
+            const testTracePath = path.join(fullPath, 'test.trace');
+            if (fs.existsSync(testTracePath)) {
+                tracePaths.push(fullPath);
+            }
+        }
+        else if (entry.isFile() && entry.name.endsWith('.zip')) {
+            const extractedDir = fullPath.replace(/\.zip$/, '');
+            // Only include if the extracted form is not already represented as a directory entry
+            if (!fs.existsSync(extractedDir)) {
+                tracePaths.push(fullPath);
+            }
+            // If the directory already exists (previously extracted), it was already added above
+        }
+    }
+    return Promise.all(tracePaths.map(p => prepareTraceDir(p)));
+}
+//# sourceMappingURL=parseTrace.js.map

package/dist/parseTrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseTrace.js","sourceRoot":"","sources":["../src/parseTrace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@andrii_kremlovskyi/playwright-traces-reader",
+  "version": "1.0.0",
+  "description": "Parse Playwright trace files into structured data for AI agents and tooling",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "playwright-traces-reader": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "templates/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest"
+  },
+  "keywords": [
+    "playwright",
+    "traces",
+    "github-copilot",
+    "llm",
+    "skills"
+  ],
+  "author": "Andrii Kremlovskyi",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.8",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.5.0",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.6",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.16"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/tests/**/*.test.ts"
+    ],
+    "transform": {
+      "^.+\\.tsx?$": [
+        "ts-jest",
+        {
+          "tsconfig": {
+            "module": "commonjs",
+            "moduleResolution": "node",
+            "esModuleInterop": true,
+            "types": [
+              "node",
+              "jest"
+            ]
+          }
+        }
+      ]
+    }
+  }
+}

package/templates/skills/analyze-playwright-traces/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: analyze-playwright-traces
+description: Analyze Playwright test traces to find test failures, extract network request/response payloads, identify slow steps, locate UI screenshots, and inspect DOM state before/during/after each browser action.
+---
+
+# Analyze Playwright Traces
+
+Use this skill when the user asks about test failures, API payloads in tests, slow steps, or UI screenshots from Playwright test runs.
+
+## Prerequisites
+
+This skill requires the `@kremlovskyi/playwright-traces-reader` npm package in the project:
+```bash
+npm install @kremlovskyi/playwright-traces-reader
+```
+
+And a built trace directory under `playwright-report/data/<sha1>/` (or a `.zip` of the same).
+
+## How to Use
+
+### 1. Find failed tests and error details
+
+```typescript
+import { prepareTraceDir, getFailedTests } from 'playwright-traces-reader';
+
+const ctx = await prepareTraceDir('/path/to/playwright-report/data/<sha1>');
+const failures = await getFailedTests(ctx);
+
+for (const f of failures) {
+  console.log(`FAILED: ${f.title}`);
+  console.log(`Error: ${f.error.message}`);
+  console.log(`Duration: ${f.durationMs}ms`);
+}
+```
+
+### 2. Find slow steps
+
+```typescript
+import { prepareTraceDir, getTestSteps } from 'playwright-traces-reader';
+
+const ctx = await prepareTraceDir('/path/to/trace-dir');
+const steps = await getTestSteps(ctx);
+
+function flatten(steps: TestStep[], out: TestStep[] = []): TestStep[] {
+  for (const s of steps) { out.push(s); flatten(s.children, out); }
+  return out;
+}
+
+const allSteps = flatten(steps);
+const sorted = allSteps
+  .filter(s => s.durationMs !== null)
+  .sort((a, b) => (b.durationMs ?? 0) - (a.durationMs ?? 0));
+
+console.log('Top 5 slowest steps:');
+sorted.slice(0, 5).forEach(s => console.log(`  ${s.durationMs}ms — ${s.title}`));
+```
+
+### 3. Extract API request/response bodies
+
+```typescript
+import { prepareTraceDir, getNetworkTraffic } from 'playwright-traces-reader';
+
+const ctx = await prepareTraceDir('/path/to/trace-dir');
+const traffic = await getNetworkTraffic(ctx);
+
+// Filter only API (Node.js APIRequestContext) calls
+const apiCalls = traffic.filter(e => e.source === 'api');
+for (const call of apiCalls) {
+  console.log(`${call.method} ${call.url} → ${call.status}`);
+  if (call.responseBody) console.log('Response:', call.responseBody.slice(0, 500));
+}
+```
+
+### 4. Extract screenshots for visual inspection
+
+```typescript
+import { prepareTraceDir, extractScreenshots } from 'playwright-traces-reader';
+import * as os from 'os';
+
+const ctx = await prepareTraceDir('/path/to/trace-dir');
+const screenshots = await extractScreenshots(ctx, `${os.tmpdir()}/pw-screenshots`);
+
+for (const s of screenshots) {
+  console.log(`Screenshot at ${s.timestamp}ms: ${s.savedPath}`);
+}
+// Pass savedPath to your image viewer or AI model for visual inspection
+```
+
+### 5. Inspect DOM state before/during/after each action
+
+```typescript
+import { prepareTraceDir, getDomSnapshots } from 'playwright-traces-reader';
+
+const ctx = await prepareTraceDir('/path/to/trace-dir');
+const snapshots = await getDomSnapshots(ctx);
+
+for (const action of snapshots) {
+  // action.before — DOM before the action
+  // action.action — DOM during the action (mid-interaction state)
+  // action.after  — DOM after the action
+  const snap = action.after ?? action.before;
+  if (!snap) continue;
+
+  console.log(`callId: ${action.callId} | url: ${snap.frameUrl}`);
+  if (snap.targetElement) {
+    console.log(`  targeted element (callId attr): ${snap.targetElement}`);
+  }
+  console.log(`  DOM snippet: ${snap.html.slice(0, 300)}`);
+}
+
+// Find the DOM snapshot for a specific action by its callId
+const target = snapshots.find(s => s.callId === 'call@42');
+if (target?.after) {
+  console.log('DOM after action 42:', target.after.html);
+}
+```
+
+Each `DomSnapshot` includes:
+- `html` — full serialized HTML string (back-references resolved, `<script>` tags stripped)
+- `phase` — `"before"` | `"action"` | `"after"`
+- `frameUrl` — URL of the page frame at snapshot time
+- `targetElement` — `callId` of the action that targeted an element (from `__playwright_target__` attr), or `null`
+- `viewport` — `{ width, height }` at snapshot time
+
+## Locating Trace Directories
+
+A Playwright report's `data/` directory holds **one SHA1 entry per test**. A test suite run with multiple tests will have multiple entries. Use `listTraces()` to iterate all of them:
+
+```typescript
+import { listTraces, getFailedTests } from 'playwright-traces-reader';
+
+// Works for 1 test or many — automatically discovers all SHA1 trace entries
+const traces = await listTraces('/path/to/playwright-report/data');
+
+for (const ctx of traces) {
+  const failures = await getFailedTests(ctx);
+  // ... process results per test
+}
+```
+
+Each entry is either a directory (already extracted) or a `.zip` (auto-extracted). Non-trace files in `data/` (`.md`, `.png`, etc.) are ignored automatically.
+
+## Low-Level Utilities
+
+### `prepareTraceDir(tracePath)`
+
+Takes a single path (directory or `.zip`) and returns a `TraceContext`. Use this when you have a specific trace path rather than a whole `data/` directory.
+
+```typescript
+import { prepareTraceDir } from '@kremlovskyi/playwright-traces-reader';
+
+const ctx = await prepareTraceDir('/path/to/playwright-report/data/<sha1>');
+// or a zip:
+const ctx = await prepareTraceDir('/path/to/playwright-report/data/<sha1>.zip');
+```
+
+### `getResourceBuffer(ctx, sha1)`
+
+Resolves a SHA1 filename to its raw `Buffer` from the trace's `resources/` directory. Returns `null` if the blob is not found. Useful when you need the raw bytes of a request/response body or a screenshot blob.
+
+```typescript
+import { prepareTraceDir, getResourceBuffer } from '@kremlovskyi/playwright-traces-reader';
+
+const ctx = await prepareTraceDir('/path/to/trace-dir');
+const buf = await getResourceBuffer(ctx, 'a1b2c3d4...');
+if (buf) {
+  // e.g. write to disk, pass to an image model, etc.
+  console.log(`blob size: ${buf.byteLength} bytes`);
+}
+```
+
+### `readNdjson<T>(filePath)`
+
+Async generator that streams and parses an NDJSON file line by line. Silently skips malformed lines. Useful for reading raw trace events when the built-in extractors don't cover your use case.
+
+```typescript
+import { prepareTraceDir, readNdjson } from '@kremlovskyi/playwright-traces-reader';
+import * as path from 'path';
+
+const ctx = await prepareTraceDir('/path/to/trace-dir');
+const traceFile = path.join(ctx.traceDir, '0-trace.trace');
+
+for await (const event of readNdjson<{ type: string }>(traceFile)) {
+  if (event.type === 'screencast-frame') {
+    console.log('screencast frame:', event);
+  }
+}
+```
+
+
+
+- **Failures**: Start with `getFailedTests()` to see the error message and which step failed. The `error.message` contains the full diff for assertion failures.
+- **Network issues**: Use `getNetworkTraffic()` filtering by `source === 'api'` to see all HTTP calls made by the test. Check `status >= 400` for HTTP errors.
+- **Slow tests**: Use `getTestSteps()` and sort by `durationMs` to find bottlenecks.
+- **Visual state**: Use `extractScreenshots()` and look at the last screenshot before a failure to understand the UI state at the time of failure.
+- **DOM inspection**: Use `getDomSnapshots()` to get the full HTML page state at each action. The `after` snapshot is the most useful for debugging — it shows exactly what the page looked like after Playwright performed an action. Combine with `targetElement` to identify which element Playwright interacted with.