@heal-dev/heal-playwright-tracer 1.0.0 → 1.0.8

package/dist/application/playwright-fixture/wire-all-pages.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wireAllPages = wireAllPages;
+exports.wireInitialPage = wireInitialPage;
+/** Returns a `restore()` thunk that undoes all patches. */
+function wireAllPages(sessions, opts) {
+    const { browser, apiRequest } = opts;
+    // (1) Wire every existing BrowserContext.
+    for (const ctx of browser.contexts()) {
+        for (const session of sessions)
+            session.attachToContext(ctx);
+    }
+    // (2) Patch newly-created contexts. We hold references to the
+    // ORIGINAL methods (no `.bind`) so `restore()` returns the exact
+    // same function reference user code may have captured before
+    // wiring. Inside our wrapper we use `.call(browser, …)` to keep
+    // `this` correctly bound on invocation.
+    const originalNewContext = browser.newContext;
+    const originalNewPage = browser.newPage;
+    browser.newContext = async (...args) => {
+        const ctx = await originalNewContext.call(browser, ...args);
+        for (const session of sessions)
+            session.attachToContext(ctx);
+        return ctx;
+    };
+    browser.newPage = async (...args) => {
+        const page = await originalNewPage.call(browser, ...args);
+        const ctx = page.context();
+        for (const session of sessions)
+            session.attachToContext(ctx);
+        return page;
+    };
+    // (3) Patch the global APIRequest factory if we were handed one
+    // and any session implements `attachToApiRequestContext`.
+    let originalApiNewContext;
+    if (apiRequest && sessions.some((s) => s.attachToApiRequestContext)) {
+        originalApiNewContext = apiRequest.newContext;
+        apiRequest.newContext = async (...args) => {
+            const api = await originalApiNewContext.call(apiRequest, ...args);
+            for (const session of sessions) {
+                session.attachToApiRequestContext?.(api);
+            }
+            return api;
+        };
+    }
+    return function restore() {
+        // Always restore. If user code re-patched our wrapper in the
+        // meantime, theirs gets reverted too — they own the conflict.
+        browser.newContext = originalNewContext;
+        browser.newPage = originalNewPage;
+        if (apiRequest && originalApiNewContext) {
+            apiRequest.newContext = originalApiNewContext;
+        }
+    };
+}
+/**
+ * Wire a single page (and its context) eagerly. Used by the fixture
+ * for the test's initial `page` so the first request fired by the
+ * test body is captured even if it races with the `attachToContext`
+ * call for a sibling context.
+ */
+function wireInitialPage(sessions, page) {
+    const ctx = page.context();
+    for (const session of sessions)
+        session.attachToContext(ctx);
+}

package/dist/application/trace-event-recorder-runtime/index.d.ts

@@ -12,4 +12,9 @@ export declare const pushStep: (name: string) => void;
 export declare const popStep: () => void;
 export declare const setCurrentStatementScreenshot: (filename: string) => void;
 export declare const setExporter: (newExporter: TraceEventConsumer) => void;
+export declare const getCurrentStatementSeq: () => number | undefined;
+export declare const getCurrentStepPath: () => string[] | undefined;
+export declare const getStartedAt: () => number;
+/** The recorder's monotonic clock — sidecar adapters use it to compute `t = now() - startedAt`. */
+export declare const clock: import("../../domain/trace-event-recorder/service").Clock;
 export { SCHEMA_VERSION };

package/dist/application/trace-event-recorder-runtime/index.js

@@ -5,7 +5,7 @@
  * Please see the LICENSE file at the root of this repository
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SCHEMA_VERSION = exports.setExporter = exports.setCurrentStatementScreenshot = exports.popStep = exports.pushStep = exports.setPage = exports.setContext = exports.reset = void 0;
+exports.SCHEMA_VERSION = exports.clock = exports.getStartedAt = exports.getCurrentStepPath = exports.getCurrentStatementSeq = exports.setExporter = exports.setCurrentStatementScreenshot = exports.popStep = exports.pushStep = exports.setPage = exports.setContext = exports.reset = void 0;
 // Composition root for the process-wide trace-event-recorder singleton.
 //
 // `domain/.../factory.ts` exports the `TraceEventRecorder` class —
@@ -66,3 +66,13 @@ exports.pushStep = traceEventRecorder.pushStep;
 exports.popStep = traceEventRecorder.popStep;
 exports.setCurrentStatementScreenshot = traceEventRecorder.setCurrentStatementScreenshot;
 exports.setExporter = traceEventRecorder.setExporter;
+// Read accessors for sidecar adapters (network, console). These
+// expose just enough of the recorder's runtime state for the
+// adapters to correlate an out-of-band Playwright event with the
+// statement that triggered it, without giving them a reference to
+// the recorder itself.
+exports.getCurrentStatementSeq = traceEventRecorder.getCurrentStatementSeq;
+exports.getCurrentStepPath = traceEventRecorder.getCurrentStepPath;
+exports.getStartedAt = traceEventRecorder.getStartedAt;
+/** The recorder's monotonic clock — sidecar adapters use it to compute `t = now() - startedAt`. */
+exports.clock = traceEventRecorder.clock;

package/dist/bin/heal-tracer.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+export {};

package/dist/bin/heal-tracer.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// Entry point wired in package.json `bin`. Kept minimal so the Commander
+// adapter remains test-driven and import-only.
+const commander_cli_adapter_1 = require("../application/commander-cli-adapter/commander-cli-adapter");
+const adapter = new commander_cli_adapter_1.CommanderCliAdapter();
+adapter.parse().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+});

package/dist/domain/code-hook-injector/service/statement-analysis/async-enclosing-function-detector.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type * as BabelTypes from '@babel/types';
+import type { NodePath } from '@babel/traverse';
+type Types = typeof BabelTypes;
+export type AsyncEnclosingFunctionDetector = (nodePath: NodePath) => boolean;
+export declare function createAsyncEnclosingFunctionDetector(_t: Types): AsyncEnclosingFunctionDetector;
+export {};

package/dist/domain/code-hook-injector/service/statement-analysis/async-enclosing-function-detector.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAsyncEnclosingFunctionDetector = createAsyncEnclosingFunctionDetector;
+function createAsyncEnclosingFunctionDetector(_t) {
+    return function isAsyncEnclosing(nodePath) {
+        let p = nodePath.parentPath;
+        while (p) {
+            if (p.isFunction()) {
+                const fn = p.node;
+                return fn.async === true;
+            }
+            p = p.parentPath;
+        }
+        return false;
+    };
+}

package/dist/domain/code-hook-injector/service/trace-hook/preprocess-call.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type * as BabelTypes from '@babel/types';
+type Types = typeof BabelTypes;
+export type PreprocessCallBuilder = (globalName: string, meta: BabelTypes.Expression) => BabelTypes.ExpressionStatement;
+export declare function createPreprocessCallBuilder(t: Types): PreprocessCallBuilder;
+export {};

package/dist/domain/code-hook-injector/service/trace-hook/preprocess-call.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPreprocessCallBuilder = createPreprocessCallBuilder;
+function createPreprocessCallBuilder(t) {
+    return function buildPreprocessCall(globalName, meta) {
+        const callee = t.memberExpression(t.identifier('globalThis'), t.identifier(globalName));
+        const call = t.optionalCallExpression(callee, [meta], /* optional */ true);
+        const stmt = t.expressionStatement(t.awaitExpression(call));
+        stmt._traced = true;
+        return stmt;
+    };
+}

package/dist/domain/persistence/execution-history-schema.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { StatementError } from '../trace-event-recorder/model/statement-trace-schema';
+import type { TestStatus } from './test-status';
+/** Record kind — discriminator for executions.ndjson lines. */
+export declare const EXECUTION_RECORD_KIND: "execution";
+/**
+ * One line in `executions.ndjson`. Compact per-run summary; full
+ * per-test detail lives in `execution.json` next to its tests.
+ */
+export interface ExecutionRecord {
+    kind: typeof EXECUTION_RECORD_KIND;
+    executionId: string;
+    /**
+     * Whether the executionId came from `HEAL_EXECUTION_ID` (multi-shard
+     * CI shares one id) or was generated locally per-process. Readers
+     * use this to decide whether two records with the same id can
+     * legitimately exist (yes when source='env').
+     */
+    source: 'env' | 'generated';
+    startedAt: number;
+    endedAt: number;
+    durationMs: number;
+    git?: {
+        sha?: string;
+        branch?: string;
+        dirty?: boolean;
+    };
+    playwrightVersion?: string;
+    totals: ExecutionTotals;
+}
+export interface ExecutionTotals {
+    tests: number;
+    passed: number;
+    failed: number;
+    timedOut: number;
+    skipped: number;
+    interrupted: number;
+}
+/**
+ * Per-execution manifest written to
+ * `<heal-traces>/<executionId>/execution.json`. Lets the viewer
+ * build an execution-level page without parsing every NDJSON.
+ */
+export interface ExecutionManifest {
+    executionId: string;
+    source: 'env' | 'generated';
+    startedAt: number;
+    endedAt: number;
+    durationMs: number;
+    git?: {
+        sha?: string;
+        branch?: string;
+        dirty?: boolean;
+    };
+    playwrightVersion?: string;
+    totals: ExecutionTotals;
+    tests: ExecutionTestEntry[];
+}
+export interface ExecutionTestEntry {
+    playwrightTestId: string;
+    title: string;
+    titlePath: string[];
+    file: string;
+    project: string;
+    /**
+     * One entry per Playwright retry, ordered by `attempt` ascending.
+     * Always non-empty — a test that never ran has no entry at all.
+     */
+    attempts: AttemptEntry[];
+}
+/**
+ * Per-(test, attempt) execution slice. `failingStatement` and
+ * `error` are only set when the attempt did not pass:
+ *
+ *   - Both present: the in-test failure was located to a specific
+ *     `statement` whose `status === 'threw'`.
+ *   - Only `error` present: the worker crashed before any statement
+ *     threw (rescued path — error is synthesized by the reporter).
+ *   - Neither present: the attempt passed, was skipped, or no
+ *     statement-level error was found on disk.
+ */
+export interface AttemptEntry {
+    /** 1-indexed attempt number = Playwright's `result.retry + 1`. */
+    attempt: number;
+    status: TestStatus;
+    startedAt: number;
+    durationMs: number;
+    failingStatement?: FailingStatement;
+    error?: StatementError;
+}
+/**
+ * Minimal locator for the statement that threw. Mirrors a subset of
+ * `Statement` (statement-trace-schema) — just enough for the viewer
+ * to deep-link and render a one-line preview without re-reading
+ * `heal-traces.ndjson`.
+ */
+export interface FailingStatement {
+    /** Contiguous per-test execution-order index from `Statement.index`. */
+    index: number;
+    file: string;
+    line: number;
+    endLine: number;
+    /** Truncated source snippet (already shortened by the tracer). */
+    source: string;
+    scope: string;
+    step: string | null;
+    stepPath: string[] | null;
+}

package/dist/domain/persistence/execution-history-schema.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXECUTION_RECORD_KIND = void 0;
+/** Record kind — discriminator for executions.ndjson lines. */
+exports.EXECUTION_RECORD_KIND = 'execution';

package/dist/domain/persistence/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+export { EXECUTION_RECORD_KIND, type ExecutionRecord, type ExecutionTotals, type ExecutionManifest, type ExecutionTestEntry, type AttemptEntry, type FailingStatement, } from './execution-history-schema';
+export type { TestStatus } from './test-status';

package/dist/domain/persistence/index.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXECUTION_RECORD_KIND = void 0;
+var execution_history_schema_1 = require("./execution-history-schema");
+Object.defineProperty(exports, "EXECUTION_RECORD_KIND", { enumerable: true, get: function () { return execution_history_schema_1.EXECUTION_RECORD_KIND; } });

package/dist/domain/persistence/test-status.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+export type TestStatus = 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted' | 'unknown';

package/dist/domain/persistence/test-status.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/trace-event-recorder/model/console-trace-schema.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+export type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug' | 'trace' | 'pageerror';
+export interface ConsoleLocation {
+    url?: string;
+    line?: number;
+    col?: number;
+}
+export interface ConsoleRecord {
+    kind: 'console';
+    /** Milliseconds since the recorder's `startedAt` for this test. */
+    t: number;
+    /** Top-of-enter-stack `seq` at emit time, or absent if the event fired outside any instrumented statement. */
+    statementSeq?: number;
+    /** Full chain of enclosing `test.step(...)` titles, snapshot at emit time. */
+    stepPath?: string[];
+    level: ConsoleLevel;
+    /** `ConsoleMessage.text()` for `console.*`, `Error.message` for `pageerror`. */
+    text: string;
+    /**
+     * Best-effort `ConsoleMessage.args().jsonValue()` for `console.*`
+     * (each handle resolved with a small per-arg timeout, then capped
+     * by the configured `maxArgBytes` / `maxArgsPerEvent`). Absent for
+     * `pageerror` and when arg resolution timed out.
+     */
+    args?: unknown[];
+    /** Stack from `Error` objects passed to `pageerror`. Absent for `console.*`. */
+    stack?: string;
+    /** Source location reported by `ConsoleMessage.location()`. */
+    location?: ConsoleLocation;
+    pageUrl?: string;
+    frameUrl?: string;
+}

package/dist/domain/trace-event-recorder/model/console-trace-schema.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/trace-event-recorder/model/global-names.d.ts

@@ -6,3 +6,4 @@
 export declare const HEAL_ENTER = "__heal_enter";
 export declare const HEAL_OK = "__heal_ok";
 export declare const HEAL_THROW = "__heal_throw";
+export declare const HEAL_PREPROCESS = "__heal_preprocess";

package/dist/domain/trace-event-recorder/model/global-names.js

@@ -5,7 +5,7 @@
  * Please see the LICENSE file at the root of this repository
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HEAL_THROW = exports.HEAL_OK = exports.HEAL_ENTER = void 0;
+exports.HEAL_PREPROCESS = exports.HEAL_THROW = exports.HEAL_OK = exports.HEAL_ENTER = void 0;
 // Names of the global functions the Babel plugin injects into
 // instrumented source and the recorder entrypoint installs on
 // `globalThis`. Both sides import from here so the contract lives in
@@ -18,3 +18,11 @@ exports.HEAL_THROW = exports.HEAL_OK = exports.HEAL_ENTER = void 0;
 exports.HEAL_ENTER = '__heal_enter';
 exports.HEAL_OK = '__heal_ok';
 exports.HEAL_THROW = '__heal_throw';
+// User-extensible per-statement async hook. The Babel plugin emits
+// `await globalThis.__heal_preprocess?.(meta)` inside the try body
+// before the user's statement when the enclosing function is async.
+// The fixture installs the global at test start by composing every
+// `preProcessor` registered through `configureTracer({...})`. Stays
+// `undefined` when no preprocessors are configured, so the optional
+// call short-circuits to a no-op.
+exports.HEAL_PREPROCESS = '__heal_preprocess';

package/dist/domain/trace-event-recorder/model/network-trace-schema.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+export interface NetworkTiming {
+    /** Ms since `request.timing().startTime`, mirroring Playwright's `RequestTiming` shape. */
+    startTime?: number;
+    domainLookupStart?: number;
+    domainLookupEnd?: number;
+    connectStart?: number;
+    secureConnectionStart?: number;
+    connectEnd?: number;
+    requestStart?: number;
+    responseStart?: number;
+    responseEnd?: number;
+}
+export interface NetworkSecurityDetails {
+    protocol?: string;
+    subjectName?: string;
+    issuer?: string;
+    /** Unix timestamp in seconds. */
+    validFrom?: number;
+    validTo?: number;
+}
+export interface NetworkServerAddr {
+    ipAddress?: string;
+    port?: number;
+}
+export interface NetworkBodyPreview {
+    /** Total body size when known (from Content-Length or buffer length). */
+    bytes?: number;
+    /** True when `preview` is shorter than `bytes` because the cap was hit. */
+    truncated: boolean;
+    /**
+     * UTF-8 preview of the body. Present only for textual content
+     * types (`text/*`, `application/json`, `application/xml`,
+     * `application/x-www-form-urlencoded`, …) AND when reading
+     * succeeded within the timeout. Trimmed at a safe UTF-8 boundary
+     * to avoid mid-codepoint cuts.
+     */
+    preview?: string;
+}
+export interface NetworkFailure {
+    errorText: string;
+}
+export type NetworkSource = 'browser-context' | 'api-request-context';
+export interface NetworkRecord {
+    kind: 'network';
+    /** Ms since the recorder's `startedAt`, sampled when the request was issued. */
+    t: number;
+    statementSeq?: number;
+    stepPath?: string[];
+    /**
+     * Per-test stable id for this exchange. Synthesized by the adapter
+     * (Playwright does not expose a request id), shared with any
+     * follow-up `network-body` record so the two can be joined.
+     */
+    requestId: string;
+    /** Where the exchange came from. `'api-request-context'` is the runner-side `playwright.request` traffic. */
+    source: NetworkSource;
+    method: string;
+    url: string;
+    /**
+     * Playwright `Request.resourceType()` for browser-context traffic
+     * (`'document'|'fetch'|'xhr'|'image'|...`). Absent for
+     * api-request-context traffic, which has no equivalent.
+     */
+    resourceType?: string;
+    isNavigationRequest?: boolean;
+    /** Set when this request was reached via one or more redirects. */
+    redirectedFromId?: string;
+    status?: number;
+    statusText?: string;
+    fromServiceWorker?: boolean;
+    requestHeaders: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBody?: NetworkBodyPreview;
+    responseBody?: NetworkBodyPreview;
+    timing?: NetworkTiming;
+    serverAddr?: NetworkServerAddr;
+    securityDetails?: NetworkSecurityDetails;
+    failure?: NetworkFailure;
+    pageUrl?: string;
+    frameUrl?: string;
+    /** Total ms between request issue and response end / failure. */
+    duration?: number;
+}
+/**
+ * Optional record appended AFTER the matching `NetworkRecord` (and
+ * after `test-result` in the main file's mental timeline) when the
+ * configured body capture mode is `'on-error'` and the test failed.
+ *
+ * Carrying the body on a separate line keeps the live network stream
+ * line-by-line during the test — bodies are buffered in memory and
+ * flushed only when we decide to keep them.
+ *
+ * Joined to its parent `NetworkRecord` via `requestId`.
+ */
+export interface NetworkBodyRecord {
+    kind: 'network-body';
+    requestId: string;
+    requestBody?: NetworkBodyPreview;
+    responseBody?: NetworkBodyPreview;
+}

package/dist/domain/trace-event-recorder/model/network-trace-schema.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/trace-event-recorder/model/statement-trace-schema.d.ts

@@ -3,11 +3,11 @@
  * This file and its contents are licensed under the AGPLv3 License.
  * Please see the LICENSE file at the root of this repository
  */
-export declare const HEAL_TRACE_SCHEMA_VERSION = 1;
+export declare const HEAL_TRACE_SCHEMA_VERSION = 2;
 /**
  * One line of a `heal-traces.ndjson` file. Discriminated by `kind`.
  */
-export type HealTraceRecord = TestHeaderRecord | StatementRecord | TestResultRecord;
+export type HealTraceRecord = TestHeaderRecord | StatementRecord | TestResultRecord | TestAttachmentsRecord;
 export interface TestHeaderRecord {
     kind: 'test-header';
     schemaVersion: typeof HEAL_TRACE_SCHEMA_VERSION;
@@ -62,6 +62,15 @@ export interface TestContext {
      * line numbers required.
      */
     testCaseId?: number;
+    /**
+     * Per-process execution id. Sourced from `HEAL_EXECUTION_ID` when
+     * set (so multi-shard CI shares one id), else a per-process
+     * `randomUUID()`. Used to scope on-disk artefacts under
+     * `<rootDir>/heal-traces/<executionId>/...` and to group
+     * historical runs in the local viewer. Optional for backwards
+     * compatibility with traces produced before this field existed.
+     */
+    executionId?: string;
 }
 export interface TestEnv {
     nodeVersion?: string;
@@ -85,6 +94,17 @@ export interface StatementRecord {
 export interface Statement {
     /** Execution-order sequence number, identical to the raw enter event's seq. */
     seq: number;
+    /**
+     * 0-based, contiguous, per-test execution-order index. Increments
+     * by 1 every time a new statement is entered (roots and nested
+     * children alike), so the first statement to run in a test has
+     * `index: 0`, the second `index: 1`, and so on. Unlike `seq`,
+     * which is bumped by every raw event (enter/ok/throw/meta) and
+     * therefore has gaps, `index` lets consumers reason about "the
+     * Nth statement that ran" without tracking event-stream
+     * arithmetic.
+     */
+    index: number;
     file: string;
     line: number;
     endLine: number;
@@ -145,6 +165,52 @@ export interface TestResultRecord {
     duration: number;
     stdout?: string[];
     stderr?: string[];
+    /**
+     * Present only when this record was synthesized by the optional
+     * `heal-reporter` after a worker crash (OOM, SIGKILL, segfault,
+     * `process.exit()`). Carries the classified crash cause. The
+     * fixture-written `test-result` never sets this — so presence of
+     * the field is itself the signal that the test did not reach
+     * normal teardown.
+     */
+    error?: StatementError;
+}
+/**
+ * Optional record appended AFTER `test-result` by the
+ * `HealTracerReporter` (Playwright Reporter API). Carries the list
+ * of files Playwright produced for the test — `trace.zip`, video,
+ * Playwright-taken failure screenshots, and any user attachments
+ * pushed via `testInfo.attach()`.
+ *
+ * Written from the reporter (not the fixture) because Playwright
+ * populates `testInfo.attachments` AFTER our `_traceAuto` fixture's
+ * teardown — the reporter's `onTestEnd` is the first hook where
+ * `result.attachments` is final.
+ *
+ * Absent when the reporter is not registered. Absence is not an
+ * error — the trace is still complete; downstream tools should
+ * treat the attachment list as empty.
+ */
+export interface TestAttachmentsRecord {
+    kind: 'test-attachments';
+    attachments: TestAttachment[];
+}
+export interface TestAttachment {
+    /**
+     * Playwright's attachment name. Common values: `'trace'` (for
+     * trace.zip), `'video'`, `'screenshot'`. User attachments use the
+     * label passed to `testInfo.attach(name, …)`.
+     */
+    name: string;
+    /**
+     * Path to the attachment file, RELATIVE to the test's outputDir
+     * (the parent of `heal-data/`). Forward slashes on every platform.
+     * Attachments outside the outputDir (rare; users could attach an
+     * arbitrary path via `testInfo.attach({ path })`) are dropped.
+     */
+    path: string;
+    /** MIME type (e.g. `'application/zip'`, `'image/png'`, `'video/webm'`). */
+    contentType: string;
 }
 /**
  * Normalized error attached to a statement whose status is `threw`.

package/dist/domain/trace-event-recorder/model/statement-trace-schema.js

@@ -30,4 +30,4 @@ exports.HEAL_TRACE_SCHEMA_VERSION = void 0;
 // raw recorder event stream (enter/ok/throw/meta). Consumers (the
 // Heal autopilot agent, humans debugging a failing test) should
 // import these types to stay in sync with the file format.
-exports.HEAL_TRACE_SCHEMA_VERSION = 1;
+exports.HEAL_TRACE_SCHEMA_VERSION = 2;

package/dist/domain/trace-event-recorder/model/trace-schema.d.ts

@@ -42,6 +42,7 @@ export interface MetaEvent extends TraceEventBase {
     retry?: number;
     attempt?: number;
     testCaseId?: number;
+    executionId?: string;
     [key: string]: unknown;
 }
 /**