@heal-dev/heal-playwright-tracer 1.0.0

package/dist/domain/code-hook-injector/service/statement-analysis/leaf-statement-classifier.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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;
+type Node = BabelTypes.Node;
+export interface LeafStatementClassifier {
+    isLeafStatement: (node: Node) => boolean;
+    kindOf: (node: Node) => string;
+    containsAwait: (node: Node) => boolean;
+}
+export declare function createLeafStatementClassifier(t: Types): LeafStatementClassifier;
+export {};

package/dist/domain/code-hook-injector/service/statement-analysis/leaf-statement-classifier.js

@@ -0,0 +1,66 @@
+"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.createLeafStatementClassifier = createLeafStatementClassifier;
+function createLeafStatementClassifier(t) {
+    const isLeafStatement = (node) => t.isExpressionStatement(node) ||
+        t.isVariableDeclaration(node) ||
+        t.isReturnStatement(node) ||
+        t.isThrowStatement(node) ||
+        t.isBreakStatement(node) ||
+        t.isContinueStatement(node) ||
+        t.isDebuggerStatement(node);
+    const kindOf = (node) => {
+        if (t.isExpressionStatement(node))
+            return 'expression';
+        if (t.isVariableDeclaration(node))
+            return 'variable';
+        if (t.isReturnStatement(node))
+            return 'return';
+        if (t.isThrowStatement(node))
+            return 'throw';
+        if (t.isBreakStatement(node))
+            return 'break';
+        if (t.isContinueStatement(node))
+            return 'continue';
+        if (t.isDebuggerStatement(node))
+            return 'debugger';
+        return node.type;
+    };
+    const containsAwait = (node) => {
+        let found = false;
+        const walk = (n) => {
+            if (!n || found || typeof n !== 'object')
+                return;
+            const asNode = n;
+            if (t.isAwaitExpression(asNode)) {
+                found = true;
+                return;
+            }
+            if (t.isFunction(asNode))
+                return;
+            for (const key of Object.keys(asNode)) {
+                if (key === 'loc' || key === 'type' || key === 'start' || key === 'end')
+                    continue;
+                const v = asNode[key];
+                if (v == null)
+                    continue;
+                if (Array.isArray(v)) {
+                    for (const item of v)
+                        if (item && item.type)
+                            walk(item);
+                }
+                else if (v.type) {
+                    walk(v);
+                }
+            }
+        };
+        walk(node);
+        return found;
+    };
+    return { isLeafStatement, kindOf, containsAwait };
+}

package/dist/domain/code-hook-injector/service/statement-analysis/non-wrappable-statement.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 NonWrappableStatementPredicate = (path: NodePath<BabelTypes.Statement>) => boolean;
+export declare function createNonWrappableStatementPredicate(t: Types, isGeneratedModuleStatement: (node: BabelTypes.Node) => boolean): NonWrappableStatementPredicate;
+export {};

package/dist/domain/code-hook-injector/service/statement-analysis/non-wrappable-statement.js

@@ -0,0 +1,20 @@
+"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.createNonWrappableStatementPredicate = createNonWrappableStatementPredicate;
+function createNonWrappableStatementPredicate(t, isGeneratedModuleStatement) {
+    return function isNonWrappableStatement(path) {
+        const node = path.node;
+        return (t.isFunctionDeclaration(node) ||
+            t.isImportDeclaration(node) ||
+            t.isExportDeclaration(node) ||
+            path.parentPath.isExportDeclaration() ||
+            t.isBlockStatement(node) ||
+            t.isEmptyStatement(node) ||
+            isGeneratedModuleStatement(node));
+    };
+}

package/dist/domain/code-hook-injector/service/trace-hook/enter-meta-literal.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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';
+import type { PluginPass } from '@babel/core';
+type Types = typeof BabelTypes;
+interface MetaHelpers {
+    kindOf: (node: BabelTypes.Node) => string;
+    containsAwait: (node: BabelTypes.Node) => boolean;
+    findScopeName: (nodePath: NodePath) => string;
+    extractSource: (code: string | undefined | null, node: BabelTypes.Node) => string;
+    extractLeadingComment: (node: BabelTypes.Node) => string | null;
+    relFile: (cwd: string, absFile: string | undefined | null) => string;
+}
+export type EnterMetaLiteralBuilder = (state: PluginPass, nodePath: NodePath, node: BabelTypes.Node, cwd: string) => BabelTypes.ObjectExpression;
+export declare function createEnterMetaLiteralBuilder(t: Types, helpers: MetaHelpers): EnterMetaLiteralBuilder;
+export {};

package/dist/domain/code-hook-injector/service/trace-hook/enter-meta-literal.js

@@ -0,0 +1,34 @@
+"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.createEnterMetaLiteralBuilder = createEnterMetaLiteralBuilder;
+function createEnterMetaLiteralBuilder(t, helpers) {
+    const { kindOf, containsAwait, findScopeName, extractSource, extractLeadingComment, relFile } = helpers;
+    return function buildEnterMetaLiteral(state, nodePath, node, cwd) {
+        const file = relFile(cwd, state.file.opts.filename);
+        const loc = node.loc;
+        const properties = [
+            t.objectProperty(t.identifier('file'), t.stringLiteral(file)),
+            t.objectProperty(t.identifier('startLine'), t.numericLiteral(loc.start.line)),
+            t.objectProperty(t.identifier('startCol'), t.numericLiteral(loc.start.column)),
+            t.objectProperty(t.identifier('endLine'), t.numericLiteral(loc.end.line)),
+            t.objectProperty(t.identifier('endCol'), t.numericLiteral(loc.end.column)),
+            t.objectProperty(t.identifier('kind'), t.stringLiteral(kindOf(node))),
+            t.objectProperty(t.identifier('scope'), t.stringLiteral(findScopeName(nodePath))),
+            t.objectProperty(t.identifier('hasAwait'), t.booleanLiteral(containsAwait(node))),
+            t.objectProperty(t.identifier('source'), t.stringLiteral(extractSource(state.file.code, node))),
+        ];
+        // Optional — only emit when the source has an attached comment
+        // so the common case stays at 9 keys and no `"leadingComment":
+        // null` leaks into the NDJSON.
+        const leadingComment = extractLeadingComment(node);
+        if (leadingComment !== null) {
+            properties.push(t.objectProperty(t.identifier('leadingComment'), t.stringLiteral(leadingComment)));
+        }
+        return t.objectExpression(properties);
+    };
+}

package/dist/domain/code-hook-injector/service/trace-hook/global-trace-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 GlobalTraceCallBuilder = (name: string, args: BabelTypes.Expression[]) => BabelTypes.ExpressionStatement;
+export declare function createGlobalTraceCallBuilder(t: Types): GlobalTraceCallBuilder;
+export {};

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

@@ -0,0 +1,16 @@
+"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.createGlobalTraceCallBuilder = createGlobalTraceCallBuilder;
+function createGlobalTraceCallBuilder(t) {
+    return function buildGlobalTraceCall(name, args) {
+        const callee = t.memberExpression(t.identifier('globalThis'), t.identifier(name));
+        const stmt = t.expressionStatement(t.optionalCallExpression(callee, args, /* optional */ true));
+        stmt._traced = true;
+        return stmt;
+    };
+}

package/dist/domain/code-hook-injector/service/trace-hook/try-finally-wrapper.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 { Scope } from '@babel/traverse';
+import type { GlobalTraceCallBuilder } from './global-trace-call';
+type Types = typeof BabelTypes;
+export interface TryFinallyWrapperBuilder {
+    buildTryFinally: (scope: Scope, tryBodyStmts: BabelTypes.Statement[], okArgs?: BabelTypes.Expression[]) => {
+        threwId: BabelTypes.Identifier;
+        tryStmt: BabelTypes.TryStatement;
+    };
+    buildThrewDecl: (threwId: BabelTypes.Identifier) => BabelTypes.VariableDeclaration;
+}
+export declare function createTryFinallyWrapperBuilder(t: Types, buildGlobalTraceCall: GlobalTraceCallBuilder): TryFinallyWrapperBuilder;
+export {};

package/dist/domain/code-hook-injector/service/trace-hook/try-finally-wrapper.js

@@ -0,0 +1,44 @@
+"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.createTryFinallyWrapperBuilder = createTryFinallyWrapperBuilder;
+const global_names_1 = require("../../../trace-event-recorder/model/global-names");
+function createTryFinallyWrapperBuilder(t, buildGlobalTraceCall) {
+    function buildTryFinally(scope, tryBodyStmts, okArgs = []) {
+        const errId = scope.generateUidIdentifier('traceErr');
+        const threwId = scope.generateUidIdentifier('traceThrew');
+        const rethrow = t.throwStatement(t.cloneNode(errId));
+        rethrow._traced = true;
+        const assignThrew = t.expressionStatement(t.assignmentExpression('=', t.cloneNode(threwId), t.booleanLiteral(true)));
+        assignThrew._traced = true;
+        const catchBlock = t.blockStatement([
+            assignThrew,
+            buildGlobalTraceCall(global_names_1.HEAL_THROW, [t.cloneNode(errId)]),
+            rethrow,
+        ]);
+        const finallyBlock = t.blockStatement([
+            t.ifStatement(t.unaryExpression('!', t.cloneNode(threwId)), t.blockStatement([buildGlobalTraceCall(global_names_1.HEAL_OK, okArgs)])),
+        ]);
+        finallyBlock.body.forEach((n) => {
+            n._traced = true;
+            const withConsequent = n;
+            if (withConsequent.consequent)
+                withConsequent.consequent._traced = true;
+        });
+        const tryStmt = t.tryStatement(t.blockStatement(tryBodyStmts), t.catchClause(errId, catchBlock), finallyBlock);
+        tryStmt._traced = true;
+        return { threwId, tryStmt };
+    }
+    function buildThrewDecl(threwId) {
+        const decl = t.variableDeclaration('let', [
+            t.variableDeclarator(threwId, t.booleanLiteral(false)),
+        ]);
+        decl._traced = true;
+        return decl;
+    }
+    return { buildTryFinally, buildThrewDecl };
+}

package/dist/domain/code-hook-injector/service/trace-hook/variable-declaration-hoister.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 interface HoistedVariableDeclaration {
+    /** Names introduced by the declaration, flattened across destructuring. */
+    bindingNames: Set<string>;
+    /** `let x, y;` — the bindings hoisted out of the try block. */
+    hoistDecl: BabelTypes.VariableDeclaration;
+    /** `x = EXPR; y = EXPR;` — one per declarator that had an initializer. */
+    assignments: BabelTypes.ExpressionStatement[];
+    /** `{ x, y }` — shorthand object literal passed to `__ok`. */
+    varsObject: BabelTypes.ObjectExpression;
+}
+export type VariableDeclarationHoister = (declaration: BabelTypes.VariableDeclaration) => HoistedVariableDeclaration;
+export declare function createVariableDeclarationHoister(t: Types): VariableDeclarationHoister;
+export {};

package/dist/domain/code-hook-injector/service/trace-hook/variable-declaration-hoister.js

@@ -0,0 +1,27 @@
+"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.createVariableDeclarationHoister = createVariableDeclarationHoister;
+function createVariableDeclarationHoister(t) {
+    return function hoistVariableDeclaration(declaration) {
+        const bindingNames = new Set();
+        for (const d of declaration.declarations) {
+            Object.keys(t.getBindingIdentifiers(d.id)).forEach((n) => bindingNames.add(n));
+        }
+        const hoistDecl = t.variableDeclaration('let', [...bindingNames].map((n) => t.variableDeclarator(t.identifier(n))));
+        hoistDecl._traced = true;
+        const assignments = declaration.declarations
+            .filter((d) => d.init != null)
+            .map((d) => {
+            const stmt = t.expressionStatement(t.assignmentExpression('=', d.id, d.init));
+            stmt._traced = true;
+            return stmt;
+        });
+        const varsObject = t.objectExpression([...bindingNames].map((n) => t.objectProperty(t.identifier(n), t.identifier(n), false, true)));
+        return { bindingNames, hoistDecl, assignments, varsObject };
+    };
+}

package/dist/domain/code-hook-injector/service/traced-file-matcher.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
+ */
+export type IncludeEntry = string | RegExp | ((filename: string) => unknown);
+export type Include = IncludeEntry | IncludeEntry[] | null | undefined;
+export type Matcher = (filename: string | undefined | null) => boolean;
+export declare const defaultInclude: IncludeEntry[];
+export declare function buildMatcher(include: Include): Matcher;

package/dist/domain/code-hook-injector/service/traced-file-matcher.js

@@ -0,0 +1,26 @@
+"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.defaultInclude = void 0;
+exports.buildMatcher = buildMatcher;
+exports.defaultInclude = [/\/tests\//];
+function buildMatcher(include) {
+    const entries = include == null ? exports.defaultInclude : Array.isArray(include) ? include : [include];
+    return (filename) => {
+        if (!filename)
+            return false;
+        for (const e of entries) {
+            if (typeof e === 'string' && filename.includes(e))
+                return true;
+            if (e instanceof RegExp && e.test(filename))
+                return true;
+            if (typeof e === 'function' && e(filename))
+                return true;
+        }
+        return false;
+    };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * 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 EnterMeta {
+    file: string;
+    startLine: number;
+    startCol: number;
+    endLine: number;
+    endCol: number;
+    kind: string;
+    scope: string;
+    hasAwait: boolean;
+    source: string;
+    /**
+     * User-written `// …` / `/* … *\/` comments attached to this
+     * statement's AST node, joined with `\n` in source order. Present
+     * only when the parser attached at least one comment; see
+     * `./statement-trace-schema.ts` `Statement.leadingComment` for the
+     * attachment caveats consumers should know about.
+     */
+    leadingComment?: string;
+}

package/dist/domain/trace-event-recorder/model/enter-meta.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

@@ -0,0 +1,8 @@
+/**
+ * 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 declare const HEAL_ENTER = "__heal_enter";
+export declare const HEAL_OK = "__heal_ok";
+export declare const HEAL_THROW = "__heal_throw";

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

@@ -0,0 +1,20 @@
+"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.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
+// one place.
+//
+// The names are deliberately prefixed with `__heal_` so anyone
+// reading the Babel-transformed test source understands at a glance
+// which library these hooks belong to. Rename them together (plugin
+// and recorder entrypoint) if the package is ever renamed.
+exports.HEAL_ENTER = '__heal_enter';
+exports.HEAL_OK = '__heal_ok';
+exports.HEAL_THROW = '__heal_throw';

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

@@ -0,0 +1,16 @@
+/**
+ * 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 SerializedError {
+    name?: string;
+    message: string;
+    stack?: string;
+    isPlaywrightError?: boolean;
+    causes?: Array<{
+        name?: string;
+        message: string;
+        stack?: string;
+    }>;
+}

package/dist/domain/trace-event-recorder/model/serialized-error.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

@@ -0,0 +1,171 @@
+/**
+ * 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 declare const HEAL_TRACE_SCHEMA_VERSION = 1;
+/**
+ * One line of a `heal-traces.ndjson` file. Discriminated by `kind`.
+ */
+export type HealTraceRecord = TestHeaderRecord | StatementRecord | TestResultRecord;
+export interface TestHeaderRecord {
+    kind: 'test-header';
+    schemaVersion: typeof HEAL_TRACE_SCHEMA_VERSION;
+    test: TestHeader;
+}
+export interface TestHeader {
+    title: string;
+    titlePath: string[];
+    file: string;
+    project: string;
+    workerIndex: number;
+    retry: number;
+    /** Wall-clock ms (Date.now()) at which the recorder was reset for this test. */
+    startedAt: number;
+    env: TestEnv;
+    context: TestContext;
+}
+/**
+ * Per-test correlation identifiers. Populated by the fixture from
+ * Playwright's `TestInfo`. The global correlation key for a test
+ * attempt is `(testId, attempt)` — two attempts of the same test
+ * share `testId` and differ in `attempt`.
+ */
+export interface TestContext {
+    /**
+     * Playwright's `testInfo.testId` — a stable hash of
+     * (file, title, project). Distinct tests always get distinct
+     * values; two attempts of the same test share this value. Also
+     * serves as the cross-worker correlation key: a retry landing in
+     * a different worker still reports the same `testId`.
+     */
+    testId: string;
+    /**
+     * 1-indexed attempt number. Equal to `testInfo.retry + 1` — the
+     * first run of a test is attempt 1, the first retry is attempt 2,
+     * and so on.
+     */
+    attempt: number;
+    /**
+     * Heal test case id sourced from the `@heal-<id>` Playwright tag
+     * on the test (e.g. `test('…', { tag: '@heal-42' }, …)`). The
+     * suffix after `@heal-` is parsed as a positive integer — it must
+     * match the `bigint` primary key on `backend.test_cases`. When
+     * present, the backend resolver links every trace event for this
+     * run to the referenced test case (after verifying the id belongs
+     * to the API key's org). When absent, events go to the unlinked
+     * bucket.
+     *
+     * Tags over annotations because they are CLI-filterable — the
+     * backend triggers a specific set of test cases with
+     * `npx playwright test -g "@heal-42|@heal-57"`, no file paths or
+     * line numbers required.
+     */
+    testCaseId?: number;
+}
+export interface TestEnv {
+    nodeVersion?: string;
+    platform?: string;
+    arch?: string;
+    hostname?: string;
+    isCI?: boolean;
+    cwd?: string;
+    gitSha?: string;
+    pid?: number;
+}
+export interface StatementRecord {
+    kind: 'statement';
+    /**
+     * Always a ROOT statement (its runtime parentSeq was null). The
+     * full subtree is nested in `statement.children`; nested calls
+     * never appear as separate records in the stream.
+     */
+    statement: Statement;
+}
+export interface Statement {
+    /** Execution-order sequence number, identical to the raw enter event's seq. */
+    seq: number;
+    file: string;
+    line: number;
+    endLine: number;
+    kind: string;
+    scope: string;
+    source: string;
+    hasAwait: boolean;
+    /**
+     * User-written source comments (`// …` or `/* … *\/`) that Babel's
+     * parser attached to this statement's AST node, joined with `\n`
+     * in source order, with a single leading/trailing space stripped
+     * from each comment value. Absent from the JSON when the node has
+     * no attached comments (the field is never `null` or `""`).
+     *
+     * Intended as a best-effort intent hint — the autopilot agent and
+     * humans debugging a failing test read this the same way they
+     * would read the comment above a step in the source file.
+     *
+     * Attachment caveat: Babel assigns a same-line trailing comment
+     * of statement N as a *leading* comment of statement N+1 when the
+     * two are separated only by whitespace. `foo(); // about foo\n
+     * bar();` therefore surfaces `about foo` on `bar()`, not `foo()`.
+     * Treat the field accordingly.
+     */
+    leadingComment?: string;
+    /** Innermost test.step title, or null if not inside one. */
+    step: string | null;
+    /** Full chain of enclosing test.step titles. */
+    stepPath: string[] | null;
+    status: 'ok' | 'threw';
+    /** Milliseconds the statement took to execute. */
+    duration: number;
+    /** Relative start time in ms (from test.startedAt). */
+    t: number;
+    pageUrl?: string;
+    /** Snapshot of bindings introduced by `const`/`let` that succeeded. */
+    vars?: Record<string, unknown>;
+    /** Present only when status === 'threw'. */
+    error?: StatementError;
+    /**
+     * Filename (relative to the test's heal-data directory) of the
+     * highlight screenshot captured by locator-screenshots while this
+     * statement was running. Present only for statements that call a
+     * patched Locator action (`click`, `fill`, `hover`, …) or a
+     * wrapped assertion.
+     */
+    screenshot?: string;
+    /**
+     * Statements executed inside this one. Sorted by execution order
+     * (`seq`). Empty for leaves.
+     */
+    children: Statement[];
+}
+export interface TestResultRecord {
+    kind: 'test-result';
+    status: 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
+    /** Total test duration in ms, as reported by Playwright's TestInfo. */
+    duration: number;
+    stdout?: string[];
+    stderr?: string[];
+}
+/**
+ * Normalized error attached to a statement whose status is `threw`.
+ * Decoupled from the runtime `SerializedError` type so consumers of
+ * `heal-traces.ndjson` can import this schema without reaching into
+ * internal modules.
+ */
+export interface StatementError {
+    name?: string;
+    message: string;
+    stack?: string;
+    /**
+     * True when the error originated from Playwright itself (timeouts,
+     * locator failures, expect mismatches) as opposed to user code.
+     */
+    isPlaywrightError?: boolean;
+    /** Walked `.cause` chain, up to 5 levels deep. */
+    causes?: StatementErrorCause[];
+}
+export interface StatementErrorCause {
+    name?: string;
+    message: string;
+    stack?: string;
+}

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

@@ -0,0 +1,33 @@
+"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.HEAL_TRACE_SCHEMA_VERSION = void 0;
+// Output schema for `heal-traces.ndjson` — the agent-facing wire
+// format written one record per line.
+//
+// The file is a stream, not a single document: each line is exactly
+// one `HealTraceRecord`. Per test the records appear in this order:
+//
+//   1. Exactly one `test-header` record (first line). Carries static
+//      per-test metadata and environment fields; the fields known
+//      only at test-end (status, duration, stdout, stderr) live on
+//      `test-result` instead.
+//   2. Zero or more `statement` records, each a ROOT statement
+//      (directly inside the test body). Nested calls live inline
+//      inside `statement.children` and never appear as standalone
+//      records. Consumers must not expect a flat stream of every
+//      executed statement.
+//   3. Exactly one `test-result` record (last line). If it is
+//      missing, the test crashed mid-run and the trace should be
+//      treated as partial.
+//
+// The projector in `../../trace-event-recorder/projectors/
+// statement-projector.ts` is what produces these records from the
+// 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;