ptywright 0.1.0 → 0.2.0

package/src/script/runner.ts

@@ -1,983 +0,0 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
-
-import { SessionManager } from "../session/session_manager";
-import { formatSnapshotView } from "../terminal/view";
-import { ensureAsciinemaPlayerAssets } from "../trace/asciinema_player_assets";
-import { generateTraceReportHtml } from "../trace/report";
-import type { TraceReportArtifacts, TraceReportResult } from "../trace/report";
-import { sleep } from "../util/sleep";
-
-import type { TextMaskRule } from "../terminal/mask";
-import { scriptSchema } from "./schema";
-import type { Script, ScriptStep } from "./schema";
-
-export type SnapshotRecord = {
-  kind: string;
-  hash: string;
-  text: string;
-};
-
-export type ScriptCustomStep<Name extends string = string, Payload = unknown> = {
-  type: "custom";
-  name: Name;
-  payload?: Payload;
-};
-
-export type ScriptRunnerContext = {
-  session: ReturnType<SessionManager["launchSession"]>;
-  stepIndex: number;
-  last: SnapshotRecord | null;
-  snapshots: Map<string, SnapshotRecord>;
-  artifactsDir: string;
-  resolveArtifactPath: (path: string) => string;
-  resolveGoldenPath: (path: string) => string;
-  updateGoldens: boolean;
-  captureSnapshot: (
-    step: Omit<Extract<ScriptStep, { type: "snapshot" }>, "type">,
-  ) => Promise<SnapshotRecord>;
-  getSnapshot: (from?: string) => SnapshotRecord;
-  writeArtifactText: (path: string, text: string) => void;
-  assertGoldenText: (path: string, text: string) => void;
-};
-
-type CustomStepHandlerImpl<Payload> = {
-  bivarianceHack(
-    ctx: ScriptRunnerContext,
-    step: ScriptCustomStep<string, Payload>,
-  ): Promise<SnapshotRecord | void> | SnapshotRecord | void;
-}["bivarianceHack"];
-
-export type CustomStepHandler<Payload = unknown> = CustomStepHandlerImpl<Payload>;
-
-type RunScriptOptions = {
-  artifactsDir?: string;
-  updateGoldens?: boolean;
-  steps?: Record<string, CustomStepHandler>;
-};
-
-export async function runScriptFile(
-  scriptPath: string,
-  options?: RunScriptOptions,
-): Promise<{ ok: true; artifactsDir: string }> {
-  const raw = await Bun.file(scriptPath).text();
-  const parsedJson = JSON.parse(raw) as unknown;
-  const baseName = basename(scriptPath, extname(scriptPath));
-  const withName =
-    parsedJson &&
-    typeof parsedJson === "object" &&
-    !Array.isArray(parsedJson) &&
-    !("name" in parsedJson)
-      ? { ...parsedJson, name: baseName }
-      : parsedJson;
-
-  return runScript(withName, options);
-}
-
-export async function runScript(
-  script: unknown,
-  options?: RunScriptOptions,
-): Promise<{ ok: true; artifactsDir: string }> {
-  const parsed = scriptSchema.parse(script) as Script;
-
-  const scriptName = parsed.name ?? "script";
-  const artifactsDir = resolveArtifactsDir(parsed, scriptName, options?.artifactsDir);
-
-  mkdirSync(artifactsDir, { recursive: true });
-
-  const sessions = new SessionManager({ snapshotRingSize: 50 });
-  const launch = parsed.launch;
-  // Resolve relative paths from the runner's working directory (not the script file).
-  const cwd = launch.cwd ? resolve(process.cwd(), launch.cwd) : process.cwd();
-
-  const session = sessions.launchSession({
-    command: launch.command,
-    args: launch.args ?? [],
-    cwd,
-    env: launch.env,
-    cols: launch.cols,
-    rows: launch.rows,
-    name: launch.name,
-  });
-
-  const snapshots = new Map<string, SnapshotRecord>();
-  let last: SnapshotRecord | null = null;
-  let currentStepIndex = -1;
-  let currentStep: ScriptStep | null = null;
-
-  const resolveGoldenPath = (path: string) =>
-    isAbsolute(path) ? path : resolve(process.cwd(), path);
-  const resolveArtifactPath = (path: string) =>
-    isAbsolute(path) ? path : resolve(artifactsDir, path);
-
-  const trace = parsed.trace ?? {};
-  const saveCast = trace.saveCast ?? true;
-  const saveReport = trace.saveReport ?? true;
-  const castPath = resolveArtifactPath(trace.castPath ?? `${scriptName}.cast`);
-  const reportPath = resolveArtifactPath(trace.reportPath ?? `${scriptName}.report.html`);
-
-  const stepHandlers = options?.steps;
-
-  // Track each step execution for full report
-  const executionSteps: {
-    index: number;
-    step: ScriptStep;
-    before: SnapshotRecord | null;
-    after: SnapshotRecord | null;
-    durationMs: number;
-    ok: boolean;
-    error?: string;
-  }[] = [];
-
-  try {
-    for (let stepIndex = 0; stepIndex < parsed.steps.length; stepIndex += 1) {
-      const step = parsed.steps[stepIndex] as ScriptStep;
-      currentStepIndex = stepIndex;
-      currentStep = step;
-
-      const stepStartedAt = Date.now();
-      // Capture state before step (reuse last if available)
-      const before = last;
-
-      try {
-        last = await runStep({
-          step,
-          stepIndex,
-          session,
-          snapshots,
-          last,
-          resolveGoldenPath,
-          resolveArtifactPath,
-          updateGoldens: options?.updateGoldens ?? envTruthy(process.env.UPDATE_GOLDENS),
-          stepHandlers,
-          artifactsDir,
-        });
-
-        // Capture snapshot after step if it didn't return a new one
-        // This ensures we have a visual history for actions, and updates 'last' for subsequent assertions
-        let after = last;
-        const stepProducedNewSnapshot = last !== before;
-
-        if (!stepProducedNewSnapshot) {
-          try {
-            // We do a lightweight view capture
-            const captured = await session.snapshotText({
-              scope: "visible",
-              trimRight: true,
-              trimBottom: true,
-              captureFrame: true,
-            });
-            // We construct a record but don't persist it as a named snapshot unless asked
-            const lines = captured.text.split("\n");
-            const view = formatSnapshotView({
-              sessionId: session.id,
-              scope: "visible",
-              hash: captured.hash,
-              lines,
-              meta: session.getMeta(),
-              lineNumbers: true,
-            });
-            after = { kind: "view", hash: captured.hash, text: view };
-            last = after; // Update last so next step sees it
-          } catch {
-            // Ignore capture errors on best effort
-          }
-        }
-
-        executionSteps.push({
-          index: stepIndex,
-          step,
-          before,
-          after,
-          durationMs: Date.now() - stepStartedAt,
-          ok: true,
-        });
-      } catch (err) {
-        // Step failed
-        executionSteps.push({
-          index: stepIndex,
-          step,
-          before,
-          after: null, // Will be captured in failure block
-          durationMs: Date.now() - stepStartedAt,
-          ok: false,
-          error: (err as Error).message,
-        });
-        throw err;
-      }
-    }
-
-    await writeTraceArtifacts({
-      session,
-      artifactsDir,
-      saveCast,
-      castPath,
-      saveReport,
-      reportPath,
-      reportScope: trace.reportScope,
-      reportMaxFrames: trace.reportMaxFrames,
-      scriptName,
-      result: { ok: true },
-      executionSteps, // Pass steps to report generator
-    });
-    writeTestDataArtifact({
-      artifactsDir,
-      scriptName,
-      ok: true,
-      executionSteps,
-      resolveArtifactPath,
-    });
-
-    sessions.closeAll();
-    return { ok: true, artifactsDir };
-  } catch (error) {
-    try {
-      writeTestDataArtifact({
-        artifactsDir,
-        scriptName,
-        ok: false,
-        error: (error as Error).message,
-        executionSteps,
-        resolveArtifactPath,
-      });
-      await writeFailureArtifacts({
-        session,
-        artifactsDir,
-        scriptName,
-        stepIndex: currentStepIndex,
-        step: currentStep,
-        last,
-        error,
-      });
-      await writeTraceArtifacts({
-        session,
-        artifactsDir,
-        saveCast,
-        castPath,
-        saveReport,
-        reportPath,
-        reportScope: trace.reportScope,
-        reportMaxFrames: trace.reportMaxFrames,
-        scriptName,
-        result: {
-          ok: false,
-          error: (error as Error).message,
-          failureStep: currentStep
-            ? { index: currentStepIndex + 1, type: formatStepLabel(currentStep) }
-            : undefined,
-        },
-        executionSteps, // Pass steps so far
-      });
-    } catch {
-      // ignore best-effort artifact writing
-    } finally {
-      sessions.closeAll();
-    }
-
-    throw error;
-  }
-}
-
-function resolveArtifactsDir(script: Script, scriptName: string, override?: string): string {
-  if (override?.trim()) return resolve(override.trim());
-  if (script.artifactsDir?.trim()) return resolve(script.artifactsDir.trim());
-  return resolve(".tmp", "runs", scriptName);
-}
-
-async function runStep(args: {
-  step: ScriptStep;
-  stepIndex: number;
-  session: ReturnType<SessionManager["launchSession"]>;
-  snapshots: Map<string, SnapshotRecord>;
-  last: SnapshotRecord | null;
-  resolveGoldenPath: (path: string) => string;
-  resolveArtifactPath: (path: string) => string;
-  updateGoldens: boolean;
-  stepHandlers?: Record<string, CustomStepHandler>;
-  artifactsDir: string;
-}): Promise<SnapshotRecord | null> {
-  const { step } = args;
-
-  try {
-    if (step.type === "sendText") {
-      args.session.sendText(step.text, { enter: step.enter });
-      return args.last;
-    }
-
-    if (step.type === "pressKey") {
-      args.session.pressKey(step.key);
-      return args.last;
-    }
-
-    if (step.type === "sendMouse") {
-      const modifiers =
-        step.shift || step.alt || step.ctrl
-          ? { shift: step.shift, alt: step.alt, ctrl: step.ctrl }
-          : undefined;
-
-      args.session.sendMouse({
-        action: step.action,
-        x: step.x,
-        y: step.y,
-        button: step.button,
-        modifiers,
-      });
-
-      return args.last;
-    }
-
-    if (step.type === "resize") {
-      args.session.resize(step.cols, step.rows);
-      return args.last;
-    }
-
-    if (step.type === "mark") {
-      args.session.mark(step.label);
-      return args.last;
-    }
-
-    if (step.type === "sleep") {
-      await sleep(step.ms);
-      return args.last;
-    }
-
-    if (step.type === "waitForText") {
-      const regex = step.regex ? new RegExp(step.regex) : undefined;
-      const result = await args.session.waitForText({
-        scope: step.scope,
-        text: step.text,
-        regex,
-        timeoutMs: step.timeoutMs ?? 10_000,
-        intervalMs: step.intervalMs ?? 100,
-      });
-      if (!result.found) {
-        throw new Error(
-          `step ${args.stepIndex + 1} waitForText not found: ${step.text ?? step.regex ?? ""}`,
-        );
-      }
-      return args.last;
-    }
-
-    if (step.type === "waitForStableScreen") {
-      const result = await args.session.waitForStableScreen({
-        timeoutMs: step.timeoutMs ?? 10_000,
-        quietMs: step.quietMs ?? 400,
-        intervalMs: step.intervalMs ?? 80,
-      });
-      if (!result.stable) {
-        throw new Error(`step ${args.stepIndex + 1} waitForStableScreen timed out`);
-      }
-      return args.last;
-    }
-
-    if (step.type === "waitForExit") {
-      const startedAt = Date.now();
-      const timeoutMs = step.timeoutMs ?? 10_000;
-      const intervalMs = step.intervalMs ?? 50;
-
-      while (Date.now() - startedAt <= timeoutMs) {
-        if (args.session.isClosed()) break;
-        await sleep(intervalMs);
-      }
-
-      const reason = args.session.getCloseReason();
-      if (!reason) {
-        throw new Error("waitForExit timed out");
-      }
-      if (reason.type !== "process_exit") {
-        throw new Error("waitForExit: session was closed by user");
-      }
-      if (step.exitCode !== undefined && reason.exitCode !== step.exitCode) {
-        throw new Error(`waitForExit: exitCode mismatch (got ${reason.exitCode})`);
-      }
-      if (step.signal !== undefined && reason.signal !== step.signal) {
-        throw new Error(`waitForExit: signal mismatch (got ${String(reason.signal ?? "")})`);
-      }
-      return args.last;
-    }
-
-    if (step.type === "expectMeta") {
-      await args.session.flush();
-      const meta = args.session.getMeta();
-
-      if (step.bufferType !== undefined && meta.bufferType !== step.bufferType) {
-        throw new Error(`expectMeta.bufferType mismatch (got ${meta.bufferType})`);
-      }
-      if (step.cols !== undefined && meta.cols !== step.cols) {
-        throw new Error(`expectMeta.cols mismatch (got ${meta.cols})`);
-      }
-      if (step.rows !== undefined && meta.rows !== step.rows) {
-        throw new Error(`expectMeta.rows mismatch (got ${meta.rows})`);
-      }
-
-      if (step.cursor) {
-        const cursorAbsY = meta.baseY + meta.cursorY;
-        const cursorViewportRow = cursorAbsY - meta.viewportY;
-        const cursorViewportCol = meta.cursorX;
-        const actual = { x: cursorViewportCol + 1, y: cursorViewportRow + 1 };
-        if (actual.x !== step.cursor.x || actual.y !== step.cursor.y) {
-          throw new Error(`expectMeta.cursor mismatch (got ${actual.x},${actual.y})`);
-        }
-      }
-
-      return args.last;
-    }
-
-    if (step.type === "snapshot") {
-      const record = await snapshotStep(args.session, step);
-      persistSnapshotRecord({
-        record,
-        saveAs: step.saveAs,
-        saveTo: step.saveTo,
-        snapshots: args.snapshots,
-        resolveArtifactPath: args.resolveArtifactPath,
-      });
-      return record;
-    }
-
-    if (step.type === "expect") {
-      const record = selectSnapshot(args.last, args.snapshots, step.from);
-      assertRecordMatches(record, step, args.stepIndex);
-      return args.last;
-    }
-
-    if (step.type === "assert") {
-      const regex = step.regex ? new RegExp(step.regex) : undefined;
-      const result = await args.session.waitForText({
-        scope: step.scope,
-        text: step.text,
-        regex,
-        timeoutMs: 0, // assert implies immediate check
-        intervalMs: 0,
-      });
-
-      if (!result.found) {
-        throw new Error(
-          `step ${args.stepIndex + 1} assert failed: ${step.description || step.text || step.regex || "pattern mismatch"}`,
-        );
-      }
-      return args.last;
-    }
-
-    if (step.type === "assertSemantic") {
-      // In this core runner, we don't have LLM access.
-      // We just log it as a passed step, or perhaps we can trigger a hook?
-      // For now, let's treat it as a "manual check required" log, but pass execution.
-      // Or if the user provided a custom handler for it?
-      // Custom handlers are for "custom" type steps.
-      // Let's print a warning if we are in a verbose mode?
-      // Actually, since this is an "assert", passing it blindly is dangerous if it's critical.
-      // However, without LLM integration here, we can't do much.
-      // If we want to support it, we could look for an environment variable or callback.
-      // For this implementation, we will treat it as a "no-op" that always passes,
-      // assuming the "recording" phase was the verification, OR the user will run this
-      // with a runner that wraps this and handles assertSemantic?
-      // But `runStep` is monolithic.
-      // Let's just log it to stdout if possible, or ignore.
-      // We'll treat it as OK to allow playback to proceed.
-      return args.last;
-    }
-
-    if (step.type === "expectGolden") {
-      const record = selectSnapshot(args.last, args.snapshots, step.from);
-      const goldenPath = args.resolveGoldenPath(step.path);
-      assertGoldenText(goldenPath, `${record.text}\n`, args.updateGoldens);
-      return args.last;
-    }
-
-    if (step.type === "custom") {
-      const handler = args.stepHandlers?.[step.name];
-      if (!handler) {
-        throw new Error(`custom handler not found: ${step.name}`);
-      }
-
-      const ctx: ScriptRunnerContext = {
-        session: args.session,
-        stepIndex: args.stepIndex,
-        last: args.last,
-        snapshots: args.snapshots,
-        artifactsDir: args.artifactsDir,
-        resolveArtifactPath: args.resolveArtifactPath,
-        resolveGoldenPath: args.resolveGoldenPath,
-        updateGoldens: args.updateGoldens,
-        captureSnapshot: async (
-          snapshotConfig: Omit<Extract<ScriptStep, { type: "snapshot" }>, "type">,
-        ) => {
-          const record = await snapshotStep(args.session, {
-            type: "snapshot",
-            ...snapshotConfig,
-          } as Extract<ScriptStep, { type: "snapshot" }>);
-
-          persistSnapshotRecord({
-            record,
-            saveAs: snapshotConfig.saveAs,
-            saveTo: snapshotConfig.saveTo,
-            snapshots: args.snapshots,
-            resolveArtifactPath: args.resolveArtifactPath,
-          });
-
-          return record;
-        },
-        getSnapshot: (from?: string) => selectSnapshot(args.last, args.snapshots, from),
-        writeArtifactText: (path: string, text: string) => {
-          const resolved = args.resolveArtifactPath(path);
-          mkdirSync(dirname(resolved), { recursive: true });
-          writeFileSync(resolved, text, "utf8");
-        },
-        assertGoldenText: (path: string, text: string) => {
-          const goldenPath = args.resolveGoldenPath(path);
-          assertGoldenText(goldenPath, text, args.updateGoldens);
-        },
-      };
-
-      const result = await handler(ctx, step as ScriptCustomStep);
-      if (!result) return args.last;
-      return result;
-    }
-
-    throw new Error(`unknown type: ${(step as ScriptStep).type}`);
-  } catch (error) {
-    throw annotateStepError(error, args.stepIndex, step);
-  }
-}
-
-function persistSnapshotRecord(args: {
-  record: SnapshotRecord;
-  saveAs?: string;
-  saveTo?: string;
-  snapshots: Map<string, SnapshotRecord>;
-  resolveArtifactPath: (path: string) => string;
-}): void {
-  const saveAs = args.saveAs?.trim();
-  if (saveAs) {
-    args.snapshots.set(saveAs, args.record);
-  }
-
-  const saveTo = args.saveTo?.trim();
-  if (!saveTo) return;
-
-  const path = args.resolveArtifactPath(saveTo);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${args.record.text}\n`, "utf8");
-}
-
-function annotateStepError(error: unknown, stepIndex: number, step: ScriptStep): Error {
-  const label =
-    step.type === "custom"
-      ? `custom(${(step as Extract<ScriptStep, { type: "custom" }>).name})`
-      : step.type;
-  const prefix = `step ${stepIndex + 1} ${label}`;
-
-  if (error instanceof Error) {
-    if (!error.message.startsWith("step ")) {
-      error.message = `${prefix}: ${error.message}`;
-    }
-    return error;
-  }
-
-  return new Error(`${prefix}: ${String(error)}`);
-}
-
-function selectSnapshot(
-  last: SnapshotRecord | null,
-  snapshots: Map<string, SnapshotRecord>,
-  from?: string,
-): SnapshotRecord {
-  const key = from?.trim() ? from.trim() : "last";
-  if (key === "last") {
-    if (!last) throw new Error("expect: no previous snapshot (from=last)");
-    return last;
-  }
-
-  const found = snapshots.get(key);
-  if (!found) {
-    throw new Error(`expect: unknown snapshot reference: ${key}`);
-  }
-  return found;
-}
-
-function assertRecordMatches(
-  record: SnapshotRecord,
-  step: Extract<ScriptStep, { type: "expect" }>,
-  stepIndex: number,
-): void {
-  if (step.equals !== undefined && record.text !== step.equals) {
-    throw new Error(`step ${stepIndex + 1} expect.equals failed`);
-  }
-
-  if (step.contains && step.contains.length > 0) {
-    for (const item of step.contains) {
-      if (!record.text.includes(item)) {
-        throw new Error(`step ${stepIndex + 1} expect.contains failed: ${JSON.stringify(item)}`);
-      }
-    }
-  }
-
-  if (step.notContains && step.notContains.length > 0) {
-    for (const item of step.notContains) {
-      if (record.text.includes(item)) {
-        throw new Error(`step ${stepIndex + 1} expect.notContains failed: ${JSON.stringify(item)}`);
-      }
-    }
-  }
-
-  if (step.regex) {
-    const regex = new RegExp(step.regex);
-    if (!regex.test(record.text)) {
-      throw new Error(`step ${stepIndex + 1} expect.regex failed: ${JSON.stringify(step.regex)}`);
-    }
-  }
-}
-
-function assertGoldenText(path: string, text: string, update: boolean): void {
-  if (update) {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, text, "utf8");
-    return;
-  }
-
-  const expected = readFileSync(path, "utf8");
-  if (text !== expected) {
-    throw new Error(`golden mismatch: ${path}`);
-  }
-}
-
-async function writeFailureArtifacts(args: {
-  session: ReturnType<SessionManager["launchSession"]>;
-  artifactsDir: string;
-  scriptName: string;
-  stepIndex: number;
-  step: ScriptStep | null;
-  last: SnapshotRecord | null;
-  error: unknown;
-}): Promise<void> {
-  const { session, artifactsDir, scriptName, stepIndex, step, last, error } = args;
-
-  const err = error instanceof Error ? error : new Error(String(error));
-  const errorText = err.stack ?? err.message;
-  writeFileSync(join(artifactsDir, "failure.error.txt"), `${errorText}\n`, "utf8");
-
-  const stepPayload = {
-    script: scriptName,
-    stepIndex: stepIndex >= 0 ? stepIndex + 1 : null,
-    step: step ?? null,
-    last: last ? { kind: last.kind, hash: last.hash } : null,
-  };
-  writeFileSync(
-    join(artifactsDir, "failure.step.json"),
-    `${JSON.stringify(stepPayload, null, 2)}\n`,
-    "utf8",
-  );
-
-  let capturedText: string | undefined = undefined;
-  let capturedHash: string | undefined = undefined;
-  try {
-    const captured = await session.snapshotText({
-      scope: "visible",
-      trimRight: true,
-      trimBottom: true,
-      captureFrame: true,
-    });
-    capturedText = captured.text;
-    capturedHash = captured.hash;
-  } catch {
-    // ignore best-effort snapshot on failure
-  }
-
-  const text = capturedText ?? last?.text;
-  const hash = capturedHash ?? last?.hash ?? "unknown";
-
-  if (text !== undefined) {
-    writeFileSync(join(artifactsDir, "failure.last.txt"), `${text}\n`, "utf8");
-
-    const view = formatSnapshotView({
-      sessionId: session.id,
-      scope: "visible",
-      hash,
-      lines: text.split("\n"),
-      meta: session.getMeta(),
-      lineNumbers: true,
-    });
-    writeFileSync(join(artifactsDir, "failure.last.view.txt"), `${view}\n`, "utf8");
-  }
-}
-
-async function snapshotStep(
-  session: ReturnType<SessionManager["launchSession"]>,
-  step: Extract<ScriptStep, { type: "snapshot" }>,
-): Promise<SnapshotRecord> {
-  if (step.kind === "grid") {
-    if (step.mask && step.mask.length > 0) {
-      throw new Error("snapshot.kind=grid does not support mask (use text/view instead)");
-    }
-    const { grid, hash } = await session.snapshotGrid({
-      trimRight: step.trimRight,
-      includeStyles: step.includeStyles,
-      captureFrame: true,
-    });
-    return { kind: step.kind, hash, text: JSON.stringify(grid, null, 2) };
-  }
-
-  if (step.kind === "ansi" || step.kind === "view_ansi") {
-    const { ansi, hash } = await session.snapshotAnsi({
-      scope: step.scope,
-      trimRight: step.trimRight,
-      trimBottom: step.trimBottom ?? true,
-      maxLines: step.maxLines,
-      tailLines: step.tailLines,
-      mask: step.mask as TextMaskRule[] | undefined,
-    });
-
-    if (step.kind === "ansi") {
-      return { kind: step.kind, hash, text: ansi };
-    }
-
-    const lines = ansi.split("\n");
-    const view = formatSnapshotView({
-      sessionId: session.id,
-      scope: step.scope ?? "visible",
-      hash,
-      lines,
-      meta: session.getMeta(),
-      lineNumbers: step.lineNumbers,
-    });
-    return { kind: step.kind, hash, text: view };
-  }
-
-  const { text, hash } = await session.snapshotText({
-    scope: step.scope,
-    trimRight: step.trimRight,
-    trimBottom: step.trimBottom ?? true,
-    maxLines: step.maxLines,
-    tailLines: step.tailLines,
-    captureFrame: true,
-    mask: step.mask as TextMaskRule[] | undefined,
-  });
-
-  if (step.kind === "text") {
-    return { kind: step.kind, hash, text };
-  }
-
-  const lines = text.split("\n");
-  const view = formatSnapshotView({
-    sessionId: session.id,
-    scope: step.scope ?? "visible",
-    hash,
-    lines,
-    meta: session.getMeta(),
-    lineNumbers: step.lineNumbers,
-  });
-  return { kind: step.kind, hash, text: view };
-}
-
-async function writeTraceArtifacts(args: {
-  session: ReturnType<SessionManager["launchSession"]>;
-  artifactsDir: string;
-  saveCast: boolean;
-  castPath: string;
-  saveReport: boolean;
-  reportPath: string;
-  reportScope?: "visible" | "buffer";
-  reportMaxFrames?: number;
-  scriptName?: string;
-  result?: TraceReportResult;
-  executionSteps?: unknown[]; // Type hack to avoid import cycle or complex type movement
-}): Promise<void> {
-  if (!args.saveCast && !args.saveReport) return;
-
-  const snapshot = await args.session.snapshotCast();
-
-  if (args.saveCast) {
-    mkdirSync(dirname(args.castPath), { recursive: true });
-    writeFileSync(args.castPath, snapshot.cast, "utf8");
-  }
-
-  if (args.saveReport) {
-    const artifactHrefs = buildReportArtifactHrefs({
-      reportPath: args.reportPath,
-      castPath: args.saveCast ? args.castPath : null,
-      artifactsDir: args.artifactsDir,
-      includeFailures: args.result?.ok === false,
-    });
-
-    const html = await generateTraceReportHtml(snapshot.cast, {
-      scope: args.reportScope,
-      maxFrames: args.reportMaxFrames,
-      scriptName: args.scriptName,
-      result: args.result,
-      artifacts: artifactHrefs,
-      steps: args.executionSteps,
-    });
-    mkdirSync(dirname(args.reportPath), { recursive: true });
-    writeFileSync(args.reportPath, html, "utf8");
-    ensureAsciinemaPlayerAssets(args.reportPath);
-  }
-}
-
-function buildReportArtifactHrefs(args: {
-  reportPath: string;
-  castPath: string | null;
-  artifactsDir: string;
-  includeFailures: boolean;
-}): TraceReportArtifacts | undefined {
-  const items: TraceReportArtifacts = {};
-
-  if (args.castPath) {
-    items.castHref = relativeHref(args.reportPath, args.castPath);
-  }
-
-  if (args.includeFailures) {
-    items.failureErrorHref = relativeHref(
-      args.reportPath,
-      join(args.artifactsDir, "failure.error.txt"),
-    );
-    items.failureStepHref = relativeHref(
-      args.reportPath,
-      join(args.artifactsDir, "failure.step.json"),
-    );
-    items.failureLastTextHref = relativeHref(
-      args.reportPath,
-      join(args.artifactsDir, "failure.last.txt"),
-    );
-    items.failureLastViewHref = relativeHref(
-      args.reportPath,
-      join(args.artifactsDir, "failure.last.view.txt"),
-    );
-  }
-
-  return Object.keys(items).length ? items : undefined;
-}
-
-function relativeHref(fromFile: string, toFile: string): string {
-  const rel = relative(dirname(fromFile), toFile);
-  const normalized = rel.replace(/\\/g, "/");
-  return normalized.startsWith(".") ? normalized : `./${normalized}`;
-}
-
-function formatStepLabel(step: ScriptStep): string {
-  return step.type === "custom"
-    ? `custom(${(step as ScriptCustomStep).name})`
-    : (step as ScriptStep).type;
-}
-
-function formatPublicStepLabel(step: ScriptStep): string {
-  const showText = envTruthy(process.env.PTYWRIGHT_REPORT_SHOW_STEP_TEXT);
-  if (step.type === "custom") return `custom(${(step as ScriptCustomStep).name})`;
-
-  if (step.type === "sendText") {
-    const enter = step.enter !== undefined ? ` enter=${String(step.enter)}` : "";
-    if (!showText) return `sendText <redacted> (len=${step.text.length}${enter})`;
-    return `sendText "${truncateInline(step.text)}"${enter ? ` (${enter.trim()})` : ""}`;
-  }
-
-  if (step.type === "pressKey") return `pressKey ${step.key}`;
-  if (step.type === "sendMouse") return `sendMouse ${step.action} (${step.x},${step.y})`;
-  if (step.type === "resize") return `resize ${step.cols}x${step.rows}`;
-  if (step.type === "mark") return step.label ? `mark ${step.label}` : "mark";
-  if (step.type === "sleep") return `sleep ${step.ms}ms`;
-
-  if (step.type === "waitForText") {
-    if (!showText)
-      return step.text ? "waitForText (text)" : step.regex ? "waitForText (regex)" : "waitForText";
-    if (step.text) return `waitFor "${truncateInline(step.text)}"`;
-    if (step.regex) return `waitFor /${truncateInline(step.regex)}/`;
-    return "waitForText";
-  }
-
-  if (step.type === "waitForStableScreen") return "waitForStableScreen";
-  if (step.type === "waitForExit") return "waitForExit";
-  if (step.type === "expectMeta") return "expectMeta";
-
-  if (step.type === "snapshot") {
-    return `snapshot ${step.kind}${step.saveAs ? ` as ${step.saveAs}` : ""}`;
-  }
-
-  if (step.type === "expect") {
-    const parts: string[] = [];
-    if (step.equals !== undefined) parts.push("equals");
-    if (step.contains?.length) parts.push(`contains(${step.contains.length})`);
-    if (step.notContains?.length) parts.push(`notContains(${step.notContains.length})`);
-    if (step.regex) parts.push("regex");
-    return parts.length ? `expect ${parts.join(",")}` : "expect";
-  }
-
-  if (step.type === "expectGolden") return `expectGolden ${step.path}`;
-
-  if (step.type === "assert") {
-    if (!showText) return step.text ? "assert (text)" : step.regex ? "assert (regex)" : "assert";
-    if (step.text) return `assert "${truncateInline(step.text)}"`;
-    if (step.regex) return `assert /${truncateInline(step.regex)}/`;
-    if (step.description) return `assert "${truncateInline(step.description)}"`;
-    return "assert";
-  }
-
-  if (step.type === "assertSemantic") return "assertSemantic";
-
-  return assertUnreachableStep(step);
-}
-
-function truncateInline(text: string, maxChars: number = 60): string {
-  const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\n/g, "\\n");
-  if (normalized.length <= maxChars) return normalized;
-  return `${normalized.slice(0, maxChars)}…(+${normalized.length - maxChars})`;
-}
-
-function assertUnreachableStep(_step: never): string {
-  return "unknown";
-}
-
-function writeTestDataArtifact(args: {
-  artifactsDir: string;
-  scriptName: string;
-  ok: boolean;
-  error?: string;
-  executionSteps: Array<{
-    index: number;
-    step: ScriptStep;
-    durationMs: number;
-    ok: boolean;
-    error?: string;
-  }>;
-  resolveArtifactPath: (path: string) => string;
-}): void {
-  try {
-    const testId = basename(args.artifactsDir);
-    const outPath = args.resolveArtifactPath("test.data.js");
-    mkdirSync(dirname(outPath), { recursive: true });
-
-    const steps = args.executionSteps.map((s) => ({
-      index: s.index + 1,
-      type: s.step.type,
-      label: formatPublicStepLabel(s.step),
-      ok: s.ok,
-      durationMs: s.durationMs,
-      error: s.ok ? null : (s.error ?? null),
-    }));
-
-    const data = {
-      version: 1,
-      testId,
-      scriptName: args.scriptName,
-      ok: args.ok,
-      error: args.ok ? null : (args.error ?? null),
-      stepCount: steps.length,
-      steps,
-      generatedAt: new Date().toISOString(),
-    };
-
-    const json = JSON.stringify(data).replaceAll("<", "\\u003c");
-    const key = JSON.stringify(testId);
-    const js =
-      `globalThis.__ptywright = globalThis.__ptywright || {};\n` +
-      `globalThis.__ptywright.tests = globalThis.__ptywright.tests || {};\n` +
-      `globalThis.__ptywright.tests[${key}] = ${json};\n`;
-    writeFileSync(outPath, js, "utf8");
-  } catch {
-    // best-effort
-  }
-}
-
-function envTruthy(value: string | undefined): boolean {
-  const v = value?.trim().toLowerCase();
-  return v === "1" || v === "true" || v === "yes" || v === "on";
-}