e2e 0.17.0 → 0.18.0

package/dist/config/tsconfig.js

@@ -0,0 +1,115 @@
+/**
+ * What the loader reads about the project besides the modules themselves:
+ * the tsconfig.json that governs a file (the nearest one above it, the way
+ * `tsc` finds it, with `extends` applied, or the project it references that
+ * includes the file) and which candidate files exist.
+ *
+ * Both are kept with the module graph that read them, the way the graph's
+ * modules are: a fresh graph (a config loaded with `graph: true`, which
+ * carries `e2e-graph` on every project file) reads its tsconfig.json and
+ * file lookups once, as they are when it loads. Every other load in the
+ * process shares one view, whose tsconfig.json is read once (collecting
+ * fifty test files reads the `extends` chain once) and whose file lookups
+ * ask the disk each time, as Node.js's own resolution does, so a test file
+ * imported again sees files added or removed since.
+ */
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { createFilesMatcher, createPathsMatcher, findTsconfig, parseTsconfig } from 'get-tsconfig';
+/** Carries the tsconfig.json files the runner warned about to its workers, so each file is reported once per run. */
+export const WARNED_TSCONFIGS_ENV = 'E2E_WARNED_TSCONFIGS';
+/** The tsconfig.json files a warning was printed for: in this process, or in the runner that spawned it. */
+const warned = new Set((process.env[WARNED_TSCONFIGS_ENV] ?? '').split(path.delimiter).filter((file) => file !== ''));
+/** The tsconfig.json files warned about so far, as the value of `WARNED_TSCONFIGS_ENV` for a worker. */
+export function warnedTsconfigs() {
+    return [...warned].join(path.delimiter);
+}
+/** The tsconfig.json a project reference names: the file, or `tsconfig.json` in the directory. */
+function referencedTsconfig(owner, reference) {
+    const target = path.resolve(path.dirname(owner), reference);
+    return target.endsWith('.json') ? target : path.join(target, 'tsconfig.json');
+}
+/** The project as one module graph sees it. */
+export class ProjectView {
+    /** The nearest tsconfig.json of each directory looked up so far; undefined where none is above it. */
+    nearest = new Map();
+    /** Each tsconfig.json read so far; undefined for one that could not be read. */
+    read = new Map();
+    /** get-tsconfig's own cache of the files it read. */
+    reads = new Map();
+    /** File lookups answered so far, for a graph's view; undefined where the disk is asked each time. */
+    files;
+    constructor(memoizeFiles) {
+        this.files = memoizeFiles ? new Map() : undefined;
+    }
+    /**
+     * The tsconfig that governs `file`, or undefined when no readable
+     * tsconfig.json is above it. A solution-style tsconfig.json (`files: []`
+     * and `references`, as Vite writes) hands a file to the referenced
+     * tsconfig that includes it, the way TypeScript's editor support does.
+     */
+    tsconfigFor(file) {
+        const directory = path.dirname(file);
+        if (!this.nearest.has(directory))
+            this.nearest.set(directory, findTsconfig(directory, 'tsconfig.json', this.reads));
+        const nearest = this.nearest.get(directory);
+        const root = nearest === undefined ? undefined : this.readTsconfig(nearest);
+        if (root === undefined || root.references.length === 0 || root.includes(file) !== undefined)
+            return root?.tsconfig;
+        for (const reference of root.references) {
+            const referenced = this.readTsconfig(reference);
+            if (referenced !== undefined && referenced.includes(file) !== undefined)
+                return referenced.tsconfig;
+        }
+        return root.tsconfig;
+    }
+    /**
+     * `tsconfigPath` read with its `extends` chain, or undefined when it
+     * cannot be, with a warning: an `extends` naming a package that is not
+     * installed (`@tsconfig/node22`) should not stop a run, so TypeScript
+     * compiles with default settings and no `paths` instead.
+     */
+    readTsconfig(tsconfigPath) {
+        if (this.read.has(tsconfigPath))
+            return this.read.get(tsconfigPath);
+        let read;
+        try {
+            const result = { path: tsconfigPath, config: parseTsconfig(tsconfigPath, this.reads) };
+            read = {
+                tsconfig: { compilerOptions: result.config.compilerOptions ?? {}, paths: createPathsMatcher(result) },
+                includes: createFilesMatcher(result),
+                references: (result.config.references ?? []).map((reference) => referencedTsconfig(tsconfigPath, reference.path)),
+            };
+        }
+        catch (cause) {
+            if (!warned.has(tsconfigPath)) {
+                warned.add(tsconfigPath);
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                process.emitWarning(`e2e ignores ${tsconfigPath}, which it cannot read (${reason}): TypeScript compiles with default settings and no paths`);
+            }
+        }
+        this.read.set(tsconfigPath, read);
+        return read;
+    }
+    /** Whether `file` is a regular file. */
+    isFile(file) {
+        let known = this.files?.get(file);
+        if (known === undefined) {
+            known = statSync(file, { throwIfNoEntry: false })?.isFile() === true;
+            this.files?.set(file, known);
+        }
+        return known;
+    }
+}
+/** One view per graph key; the empty key is every load outside a fresh graph. */
+const views = new Map();
+/** The view of the module graph `graph` names (the `e2e-graph` value of a URL), or the shared one for null. */
+export function projectView(graph) {
+    const key = graph ?? '';
+    let view = views.get(key);
+    if (view === undefined) {
+        view = new ProjectView(graph !== null);
+        views.set(key, view);
+    }
+    return view;
+}

package/dist/config/typescript.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Compiles a TypeScript or JSX file to JavaScript this Node.js runs, with
+ * oxc. The output carries an inline source map, so stack traces, a test's
+ * location, and failure code frames point at the source. Syntax the running
+ * Node.js lacks (`using`, for one) is lowered for it, with helpers from e2e's
+ * own copy of `@oxc-project/runtime`, which the project need not install.
+ * The caller passes the compiler options that change what runs: JSX, legacy
+ * decorators, class field semantics, and import elision.
+ */
+import { type CompiledExtension } from './compiled-files.ts';
+import type { CompilerOptions } from './tsconfig.ts';
+/**
+ * `source`, the content of `file` as the next loader handed it over,
+ * compiled to JavaScript for its kind with `compilerOptions`, with an
+ * inline source map. When an earlier loader already compiled the file and
+ * left its own inline map, the two are composed, so positions still lead to
+ * the file on disk.
+ */
+export declare function compileTypeScript(file: string, source: string, kind: CompiledExtension, compilerOptions: CompilerOptions): string;

package/dist/config/typescript.js

@@ -0,0 +1,253 @@
+/**
+ * Compiles a TypeScript or JSX file to JavaScript this Node.js runs, with
+ * oxc. The output carries an inline source map, so stack traces, a test's
+ * location, and failure code frames point at the source. Syntax the running
+ * Node.js lacks (`using`, for one) is lowered for it, with helpers from e2e's
+ * own copy of `@oxc-project/runtime`, which the project need not install.
+ * The caller passes the compiler options that change what runs: JSX, legacy
+ * decorators, class field semantics, and import elision.
+ */
+import remapping, {} from '@jridgewell/remapping';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { InfrastructureError } from '../internal/errors.js';
+import { HOOKED_REQUIRE_KEY } from './compiled-files.js';
+const ownRequire = createRequire(import.meta.url);
+/** oxc's transformer and parser, loaded on first use. */
+let compiler;
+/**
+ * oxc, loaded when the first file compiles rather than when e2e loads, so
+ * a command that compiles nothing (`--version`, `--help`) still runs
+ * without oxc's native binding. npm leaves that binding out with
+ * `--omit=optional`, and from a lockfile written on another platform
+ * (npm/cli#4828); the error names it and the way back.
+ */
+function oxc() {
+    if (compiler !== undefined)
+        return compiler;
+    try {
+        compiler = { transform: ownRequire('oxc-transform'), parser: ownRequire('oxc-parser') };
+    }
+    catch (cause) {
+        const reason = (cause instanceof Error ? cause.message : String(cause)).split('\n')[0];
+        // napi-rs's loader says so when no platform package is installed.
+        const missingBinding = /Cannot find native binding/.test(String(cause?.message));
+        const platform = `${process.platform}-${process.arch}`;
+        const fix = missingBinding
+            ? `its native bindings for ${platform} (@oxc-transform/binding-${platform}* and @oxc-parser/binding-${platform}*) are not installed. npm skips it with --omit=optional, or when package-lock.json was written on another platform (npm/cli#4828): install again without --omit=optional, or delete package-lock.json and node_modules and run npm install`
+            : `it could not be loaded (${reason})`;
+        throw new InfrastructureError('TYPESCRIPT_COMPILER_UNAVAILABLE', `e2e compiles TypeScript with oxc, and ${fix}`, { cause });
+    }
+    return compiler;
+}
+/** The first ECMAScript edition that defines class fields rather than assigning them. */
+const DEFINED_FIELDS_SINCE = 2022;
+/** JSX as the tsconfig asks for it; classic `React.createElement` when it names no automatic runtime. */
+function jsxOptions(options) {
+    if (options.jsx === 'react-jsx' || options.jsx === 'react-jsxdev') {
+        return { runtime: 'automatic', importSource: options.jsxImportSource ?? 'react', development: options.jsx === 'react-jsxdev' };
+    }
+    return {
+        runtime: 'classic',
+        pragma: options.jsxFactory ?? 'React.createElement',
+        pragmaFrag: options.jsxFragmentFactory ?? 'React.Fragment',
+    };
+}
+/**
+ * The ECMAScript year a tsconfig `target` names, or undefined for `ESNext`
+ * and an unset target. `ES6` is 2015; `ES3` and `ES5` count as 2009, the
+ * year of ES5.
+ */
+function targetYear(target) {
+    const edition = /^es(\d+)$/i.exec(target ?? '')?.[1];
+    if (edition === undefined)
+        return undefined;
+    const number = Number(edition);
+    if (number === 6)
+        return 2015;
+    return number < 2015 ? 2009 : number;
+}
+/**
+ * `useDefineForClassFields` as TypeScript reads it: explicit, or false for a
+ * target below ES2022. An unset target keeps define semantics, as esbuild did.
+ */
+function definesClassFields(options) {
+    if (options.useDefineForClassFields !== undefined)
+        return options.useDefineForClassFields;
+    const year = targetYear(options.target);
+    return year === undefined || year >= DEFINED_FIELDS_SINCE;
+}
+/** The oxc options a tsconfig's compiler options call for. */
+function transformOptions(options) {
+    const assignsFields = !definesClassFields(options);
+    return {
+        jsx: jsxOptions(options),
+        typescript: {
+            onlyRemoveTypeImports: options.verbatimModuleSyntax === true,
+            removeClassFieldsWithoutInitializer: assignsFields,
+        },
+        assumptions: { setPublicClassFields: assignsFields },
+        ...(options.experimentalDecorators === true
+            ? { decorator: { legacy: true, emitDecoratorMetadata: options.emitDecoratorMetadata === true } }
+            : {}),
+    };
+}
+/** `file:line:column: message` for one oxc-transform error; it counts UTF-8 bytes, an editor counts characters. */
+function describeError(file, source, error) {
+    const start = error.labels[0]?.start;
+    if (start === undefined)
+        return `${file}: ${error.message}`;
+    return `${file}:${position(source.subarray(0, start).toString('utf8'))}: ${error.message}`;
+}
+/** `line:column` just past `text`, both counted from 1. */
+function position(text) {
+    const lines = text.split('\n');
+    return `${lines.length}:${lines.at(-1).length + 1}`;
+}
+/**
+ * Syntax oxc 0.152 passes through unchanged that Node.js cannot run, found
+ * before compiling so the error names the line and the fix instead of a
+ * bare `SyntaxError` from Node.js with no location. Each check only parses
+ * a file whose text could hold the construct.
+ */
+function rejectUnsupportedSyntax(file, source, kind, options) {
+    const legacyDecorators = options.experimentalDecorators === true;
+    const commonJs = kind.format === 'commonjs';
+    // A decorator's `@` starts a line or follows whitespace or punctuation, which rules out a package import ('@scope/pkg').
+    const mayHold = (commonJs && /\b(?:import|export)\b/.test(source)) || /\baccessor\b/.test(source) || (!legacyDecorators && /(?:^|[\s(,;{}])@[A-Za-z_$]/m.test(source));
+    if (!mayHold)
+        return;
+    const parsed = oxc().parser.parseSync(file, source, { lang: kind.lang, sourceType: kind.format });
+    const problems = [];
+    if (commonJs) {
+        for (const declaration of parsed.module.staticImports) {
+            if (declaration.entries.length === 0 || declaration.entries.some((entry) => !entry.isType)) {
+                problems.push({ start: declaration.start, message: 'a .cts file is CommonJS, and e2e does not turn an import declaration into require(): write `import name = require(...)`, or `import type` for types' });
+            }
+        }
+        for (const declaration of parsed.module.staticExports) {
+            // `export interface`, `export type`, and `export declare` emit nothing, as tsc allows in .cts.
+            if (declaration.entries.every((entry) => entry.isType))
+                continue;
+            problems.push({ start: declaration.start, message: 'a .cts file is CommonJS, and e2e does not turn an export declaration into module.exports: write `export = ...`' });
+        }
+    }
+    const { Visitor } = oxc().parser;
+    new Visitor({
+        AccessorProperty(node) {
+            problems.push({ start: node.start, message: '`accessor` class fields (auto-accessors) are not supported: oxc, which compiles e2e\'s TypeScript, does not lower them yet; write a getter and setter over a private field' });
+        },
+        Decorator(node) {
+            if (!legacyDecorators) {
+                problems.push({ start: node.start, message: 'decorators need `"experimentalDecorators": true` in tsconfig.json: e2e compiles TypeScript\'s legacy decorators, and Node.js does not run standard decorators yet' });
+            }
+        },
+    }).visit(parsed.program);
+    if (problems.length > 0) {
+        throw new SyntaxError(problems.map(({ start, message }) => `${file}:${position(source.slice(0, start))}: ${message}`).join('\n'));
+    }
+}
+/**
+ * A `require` that runs resolve hooks, for compiled CommonJS. The `require`
+ * Node.js hands a CommonJS module an ES module imported skips them: before
+ * nodejs/node#62920 (24.18.0, 26.2.0; not in Node.js 22), and on every
+ * version once a `module.register` loader is in the chain too (Yarn PnP,
+ * tsx through NODE_OPTIONS). Without it, `require('./helper')` from such a
+ * module misses `helper.ts`, a tsconfig alias, and the helpers compiled code
+ * requires from e2e's install. The loader puts the function on `globalThis`
+ * when it registers (`esm-hooks.ts`): the `require` such a module starts
+ * with cannot load another ES module, e2e's included.
+ */
+const HOOKED_REQUIRE = `require = globalThis[Symbol.for(${JSON.stringify(HOOKED_REQUIRE_KEY)})](__filename);`;
+/**
+ * Compiled CommonJS as Node.js can run it, read from oxc's own parse of
+ * the output:
+ * - Oxc keeps a file whose only imports were type-only a module by printing
+ *   `export {};`, even for CommonJS, where that statement is a syntax error
+ *   and TypeScript emits nothing. It is an oxc bug, not yet reported
+ *   upstream (oxc 0.152.0, `crates/oxc_transformer/src/typescript/
+ *   annotations.rs`, the `no_modules_remaining && some_modules_deleted`
+ *   branch). The statement is blanked out, so nothing after it moves.
+ * - `HOOKED_REQUIRE` follows the last directive on
+ *   its line, so the prologue stays first and no mapped position moves; with
+ *   no directive it takes a line of its own at the top (after a hashbang),
+ *   and the source map gains an unmapped line there.
+ */
+function runnableCommonJs(file, code, mappings) {
+    const { program } = oxc().parser.parseSync(file, code, { lang: 'js', sourceType: 'commonjs' });
+    let runnable = code;
+    for (const statement of program.body) {
+        if (statement.type === 'ExportNamedDeclaration' && statement.declaration === null && statement.source === null && statement.specifiers.length === 0) {
+            runnable = `${runnable.slice(0, statement.start)}${' '.repeat(statement.end - statement.start)}${runnable.slice(statement.end)}`;
+        }
+    }
+    const directives = program.body.filter((statement) => statement.type === 'ExpressionStatement' && typeof statement.directive === 'string');
+    const last = directives.at(-1);
+    if (last !== undefined)
+        return { code: `${runnable.slice(0, last.end)} ${HOOKED_REQUIRE}${runnable.slice(last.end)}`, mappings };
+    const line = program.hashbang === null ? 0 : 1;
+    const lines = runnable.split('\n');
+    lines.splice(line, 0, HOOKED_REQUIRE);
+    const mappedLines = mappings.split(';');
+    mappedLines.splice(line, 0, '');
+    return { code: lines.join('\n'), mappings: mappedLines.join(';') };
+}
+/** Each helper's file in e2e's copy of `@oxc-project/runtime`, resolved once. */
+const helperFiles = new Map();
+/**
+ * The compiled code with each runtime helper it imports or requires taken
+ * from e2e's own copy: by URL for `import`, by path for `require`. Oxc 0.152
+ * has no option to name the helper source, so the import and require
+ * specifiers it printed (`helpersUsed`) are rewritten; a redirect of the
+ * package name in the resolver would also catch a project's own
+ * `@oxc-project/runtime` imports.
+ */
+function withOwnHelpers(code, helpers, format) {
+    let rewritten = code;
+    for (const specifier of new Set(Object.values(helpers))) {
+        let file = helperFiles.get(specifier);
+        if (file === undefined) {
+            file = ownRequire.resolve(specifier);
+            helperFiles.set(specifier, file);
+        }
+        const written = JSON.stringify(specifier);
+        rewritten =
+            format === 'module'
+                ? rewritten.replaceAll(` from ${written};`, ` from ${JSON.stringify(pathToFileURL(file).href)};`)
+                : rewritten.replaceAll(`require(${written})`, `require(${JSON.stringify(file)})`);
+    }
+    return rewritten;
+}
+/** An inline source map at the end of `source`, as another loader earlier in the chain leaves one. */
+const INLINE_MAP = /\n\/\/# sourceMappingURL=data:application\/json(?:;charset=utf-8)?;base64,([A-Za-z0-9+/=]+)\s*$/;
+/**
+ * `source`, the content of `file` as the next loader handed it over,
+ * compiled to JavaScript for its kind with `compilerOptions`, with an
+ * inline source map. When an earlier loader already compiled the file and
+ * left its own inline map, the two are composed, so positions still lead to
+ * the file on disk.
+ */
+export function compileTypeScript(file, source, kind, compilerOptions) {
+    rejectUnsupportedSyntax(file, source, kind, compilerOptions);
+    const result = oxc().transform.transformSync(file, source, {
+        ...transformOptions(compilerOptions),
+        lang: kind.lang,
+        sourceType: kind.format,
+        target: `node${process.versions.node}`,
+        sourcemap: true,
+    });
+    const errors = result.errors.filter((error) => error.severity === 'Error');
+    if (errors.length > 0) {
+        const bytes = Buffer.from(source, 'utf8');
+        throw new SyntaxError(errors.map((error) => describeError(file, bytes, error)).join('\n'));
+    }
+    let code = withOwnHelpers(result.code, result.helpersUsed, kind.format);
+    let mappings = result.map?.mappings ?? '';
+    if (kind.format === 'commonjs')
+        ({ code, mappings } = runnableCommonJs(file, code, mappings));
+    // Absolute, so a frame names the file without the loader's query, whatever characters its name holds.
+    const own = { version: 3, mappings, names: result.map?.names ?? [], sources: [pathToFileURL(file).href] };
+    const incoming = INLINE_MAP.exec(source)?.[1];
+    const map = incoming === undefined ? own : remapping([own, JSON.parse(Buffer.from(incoming, 'base64').toString('utf8'))], () => null);
+    return `${code}\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(map)).toString('base64')}\n`;
+}

package/dist/engine/contract.d.ts

@@ -297,6 +297,7 @@ export type PointerAction = {
 } | {
     readonly kind: 'swipeTo';
     readonly target: ViewportPoint;
+    readonly durationMs?: number;
 };
 /** Every pointer action kind; what an engine declares in `pointerActions`. */
 export type PointerActionKind = PointerAction['kind'];

package/dist/engine/index.d.ts

@@ -362,6 +362,8 @@ export interface EnginePrepareInfo {
      * fail every test behind it.
      */
     readonly signal: AbortSignal;
+    /** Whether the run asked for a visible surface (`--headed`), as `EngineInitInfo` declares it. */
+    readonly headed: boolean;
     /**
      * Reports one line of progress. The runner streams it as a `notice` run
      * event, so it reaches the reporter and every host sink instead of being

package/dist/engine/session.js

@@ -11,7 +11,7 @@
  * a non-retryable `ENGINE_FAILURE`, so a crashed engine is an infrastructure
  * failure everywhere and never a retry-eligible test failure.
  */
-import { asEngineError, ConfigurationError, E2EError, errorMessage, isForeignE2EError, TestError, } from '../internal/errors.js';
+import { asEngineError, ConfigurationError, errorMessage, isE2EError, TestError, } from '../internal/errors.js';
 import { requireKey } from '../internal/keys.js';
 import { EngineError, } from './surface.js';
 /** Located refs are pruned oldest-first past this bound so the map cannot grow unboundedly. */
@@ -45,7 +45,7 @@ function countSecure(node) {
  * engine failing outside its contract, reported as infrastructure.
  */
 function normalize(cause, label) {
-    if (cause instanceof E2EError || isForeignE2EError(cause) || asEngineError(cause) !== undefined) {
+    if (isE2EError(cause) || asEngineError(cause) !== undefined) {
         throw cause;
     }
     throw new EngineError('ENGINE_FAILURE', `${label} failed: ${errorMessage(cause)}`, {

package/dist/expect/async.js

@@ -106,7 +106,7 @@ class AsyncExpectationImpl {
                         return undefined;
                     return spec.predicate(sample);
                 },
-                onTimeout: () => {
+                onTimeout: (cause) => {
                     const expected = `${this.negated ? 'not ' : ''}${spec.describeExpected}`;
                     const observed = spec.observed(lastSample);
                     return new TestError('ASSERTION_FAILED', [
@@ -117,6 +117,7 @@ class AsyncExpectationImpl {
                     ].join('\n'), {
                         // The same facts, one per field, for a reporter that lays them out.
                         details: { locator: this.label, expected, observed, matches: lastSample.count },
+                        ...(cause === undefined ? {} : { cause }),
                     });
                 },
             });

package/dist/expect/poll.js

@@ -1,5 +1,5 @@
 /** expect.poll: re-reads a value until a synchronous matcher passes. */
-import { ConfigurationError, E2EError, TestError } from '../internal/errors.js';
+import { ConfigurationError, E2EError, isE2EError, TestError } from '../internal/errors.js';
 import { Deadline, POLL_INTERVAL_MS, sleep, withAbort, withTimeout } from '../internal/time.js';
 import { currentAttempt } from './attempt.js';
 import { currentPollScope } from './poll-scope.js';
@@ -39,7 +39,7 @@ function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function isNotYet(error) {
-    return error instanceof E2EError && error.code === 'ASSERTION_FAILED';
+    return isE2EError(error) && error.code === 'ASSERTION_FAILED';
 }
 function cancelled() {
     return new E2EError('infrastructure', 'CANCELLED', 'operation cancelled');

package/dist/internal/errors.d.ts

@@ -3,6 +3,8 @@ import { type SourceLocation } from './source.ts';
 import { type EngineErrorCode } from '../engine/contract.ts';
 /** Message of an arbitrary thrown value, for diagnostics that must not throw. */
 export declare function errorMessage(cause: unknown): string;
+/** Installs the process-wide redactor `serializeError` uses when none is given; `undefined` clears it. */
+export declare function setErrorRedactor(redact: ((text: string) => string) | undefined): void;
 /**
  * The message of a thrown value led by its code when it is an e2e error, as
  * the CLI prints one: `POLICY_DENIED: forbidden URL scheme: file:`. Any
@@ -107,8 +109,13 @@ export declare class E2EError extends Error {
     readonly [E2E_ERROR_MARKER] = true;
     constructor(category: ErrorCategory, code: string, message: string, options?: E2EErrorOptions);
 }
-/** Detects an E2EError created by another copy of this module. */
-export declare function isForeignE2EError(value: unknown): value is Error & {
+/**
+ * True for an E2EError from this module copy or another. An engine imported by
+ * a config file loads its own copy of the runner, so its errors fail
+ * `instanceof E2EError` and every subclass check; test for runner errors with
+ * this, and read the subclass off `category` and `code`.
+ */
+export declare function isE2EError(value: unknown): value is Error & {
     category: ErrorCategory;
     code: string;
     retryable: boolean;
@@ -159,7 +166,7 @@ export declare function serializeError(error: E2EError, extras?: {
     /**
      * Replaces secret values in the message, the details, and the stack: an
      * assertion that observed a secret on screen, or a message that quoted
-     * one, must not carry it into the report. Identity when omitted.
+     * one, must not carry it into the report. Defaults to `setErrorRedactor`'s.
      */
     redact?: ((text: string) => string) | undefined;
 }): SerializedError;

package/dist/internal/errors.js

@@ -1,18 +1,28 @@
 /** Runner-owned error taxonomy and exit-code mapping. */
 import { stripVTControlCharacters } from 'node:util';
+import { realmSlot } from './realm-slot.js';
 import { sourceLocation } from './source.js';
 import { ENGINE_ERROR_CODES, EngineError, RETRYABLE_ENGINE_ERROR_CODES, } from '../engine/contract.js';
 /** Message of an arbitrary thrown value, for diagnostics that must not throw. */
 export function errorMessage(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }
+/** The redactor `serializeError` falls back to, on `globalThis` so a project's copy of e2e shares it. */
+const redactorSlot = realmSlot('e2e.error-redactor.v1');
+/** Installs the process-wide redactor `serializeError` uses when none is given; `undefined` clears it. */
+export function setErrorRedactor(redact) {
+    if (redact === undefined)
+        redactorSlot.delete(globalThis);
+    else
+        redactorSlot.set(globalThis, redact);
+}
 /**
  * The message of a thrown value led by its code when it is an e2e error, as
  * the CLI prints one: `POLICY_DENIED: forbidden URL scheme: file:`. Any
  * other value is its message alone.
  */
 export function codedMessage(cause) {
-    const code = cause instanceof E2EError || isForeignE2EError(cause) ? `${cause.code}: ` : '';
+    const code = isE2EError(cause) ? `${cause.code}: ` : '';
     return `${code}${errorMessage(cause)}`;
 }
 /**
@@ -129,8 +139,13 @@ const CATEGORIES = new Set([
     'internal',
     'interrupted',
 ]);
-/** Detects an E2EError created by another copy of this module. */
-export function isForeignE2EError(value) {
+/**
+ * True for an E2EError from this module copy or another. An engine imported by
+ * a config file loads its own copy of the runner, so its errors fail
+ * `instanceof E2EError` and every subclass check; test for runner errors with
+ * this, and read the subclass off `category` and `code`.
+ */
+export function isE2EError(value) {
     return (value instanceof Error &&
         value[E2E_ERROR_MARKER] === true &&
         CATEGORIES.has(value.category) &&
@@ -197,8 +212,8 @@ export function combineExitCodes(codes) {
  * non-retryable infrastructure ENGINE_FAILURE.
  */
 export function translateEngineError(cause, suffix = '') {
-    if (cause instanceof E2EError)
-        return cause;
+    if (isE2EError(cause))
+        return classifyError(cause);
     const engineError = asEngineError(cause);
     if (engineError !== undefined) {
         switch (engineError.code) {
@@ -235,7 +250,7 @@ export function translateEngineError(cause, suffix = '') {
  * `Error` from an installer - is infrastructure.
  */
 export function translateProvisioningError(cause, suffix = '') {
-    if (cause instanceof E2EError || isForeignE2EError(cause))
+    if (isE2EError(cause))
         return classifyError(cause);
     if (asEngineError(cause)?.code === 'CANCELLED')
         return translateEngineError(cause);
@@ -245,7 +260,7 @@ export function translateProvisioningError(cause, suffix = '') {
 export function classifyError(value) {
     if (value instanceof E2EError)
         return value;
-    if (isForeignE2EError(value)) {
+    if (isE2EError(value)) {
         const details = value.details;
         return new E2EError(value.category, value.code, value.message, {
             retryable: value.retryable,
@@ -264,7 +279,7 @@ export function classifyError(value) {
 const MAX_MESSAGE_BYTES = 8192;
 /** Serializes an error into the bounded report-1 error shape. */
 export function serializeError(error, extras = {}) {
-    const redact = extras.redact ?? ((text) => text);
+    const redact = extras.redact ?? redactorSlot.get(globalThis) ?? ((text) => text);
     const serialized = {
         category: error.category,
         code: error.code,

package/dist/internal/node-version.d.ts

@@ -1,9 +1,18 @@
 /**
- * The Node.js floor, checked before the CLI loads anything else. Package
- * managers only warn about `engines`, so an unsupported runtime would
- * otherwise surface as an unrelated TypeError deep inside a run.
+ * The Node.js releases e2e runs on, as a set of release ranges. The CLI checks the floor before it loads
+ * anything else: package managers only warn about `engines`, so an
+ * unsupported runtime would otherwise surface as an unrelated TypeError deep
+ * inside a run.
  */
-/** Mirrors `engines.node` in package.json; a unit test keeps the two in step. */
-export declare const MINIMUM_NODE_VERSION = "22.12.0";
-/** Explains an unsupported runtime, or undefined when `current` meets the floor. */
-export declare function unsupportedNodeMessage(current: string, minimum?: string): string | undefined;
+/** `engines.node` in package.json; a unit test keeps the two in step. */
+export declare const SUPPORTED_NODE_RANGE: string;
+/**
+ * Explains a runtime e2e cannot run on, or undefined for one it can: a
+ * Node.js outside `SUPPORTED_NODE_RANGE`, or a runtime that reports a
+ * supported Node.js version without Node.js's `module.registerHooks` (Bun),
+ * which e2e's TypeScript loader runs on, or Deno.
+ */
+export declare function unsupportedRuntimeMessage(versions?: Pick<NodeJS.ProcessVersions, 'node'> & {
+    readonly bun?: string;
+    readonly deno?: string;
+}, hasRegisterHooks?: boolean): string | undefined;