@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/observe/parseAppApiUrl.js

@@ -0,0 +1,37 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// The request or endpoint an app API URL calls: /api/request/<pageId>/<requestId>
+// or /api/endpoints/<endpointId>, after the base path. Null for any other URL.
+function parseAppApiUrl({ url, basePath = '' }) {
+  const { pathname } = new URL(url);
+  const requestPrefix = `${basePath}/api/request/`;
+  const endpointPrefix = `${basePath}/api/endpoints/`;
+  if (pathname.startsWith(requestPrefix)) {
+    const segments = pathname.slice(requestPrefix.length).split('/');
+    return {
+      requestId: segments[segments.length - 1],
+      pageId: segments.slice(0, -1).join('/'),
+      endpointId: null,
+    };
+  }
+  if (pathname.startsWith(endpointPrefix)) {
+    return { requestId: null, pageId: null, endpointId: pathname.slice(endpointPrefix.length) };
+  }
+  return null;
+}
+
+export default parseAppApiUrl;

package/lib/docs/observe/readStepObserver.js

@@ -0,0 +1,42 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// Serialized into the journey's page by page.evaluate, so this function must be
+// pure: it may reference nothing but `window`, `document` and its argument.
+//
+// Closes the step's window opened by installStepObserver and reads it: the
+// trace emits, and how many mutated nodes are still in the document. A
+// transient effect's nodes never count: antd's click wave inserts a holder
+// with a wave node into every Button it clicks and removes it only when its
+// motion ends, which a headless page may not reach within the step. Returns
+// null when the document that opened the window is gone (a full page load).
+function readStepObserver({ transientSelector }) {
+  const observer = window.__lowdefyStepObserver;
+  if (!observer || !observer.open) return null;
+  observer.open = false;
+  function isTransient(node) {
+    if (node.nodeType !== 1) {
+      return node.parentElement !== null && node.parentElement.closest(transientSelector) !== null;
+    }
+    if (node.closest(transientSelector) !== null) return true;
+    const children = [...node.children];
+    return children.length > 0 && children.every((child) => child.matches(transientSelector));
+  }
+  const counted = new Set(observer.nodes.filter((node) => node.isConnected && !isTransient(node)));
+  return { emits: observer.emits, mutationCount: counted.size };
+}
+
+export default readStepObserver;

package/lib/docs/observe/relativeSource.js

@@ -0,0 +1,29 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import path from 'node:path';
+import { type } from '@lowdefy/helpers';
+
+// A config source location ("<file>:<line>") relative to the config
+// directory, with forward slashes, so findings read and key the same on every
+// machine and worktree: "pages/ticket.yaml:88".
+function relativeSource({ source, configDirectory }) {
+  if (type.isNone(source)) return null;
+  if (!path.isAbsolute(source) || type.isNone(configDirectory)) return source;
+  return path.relative(configDirectory, source).split(path.sep).join('/');
+}
+
+export default relativeSource;

package/lib/docs/observe/resolveConfigKeySource.js

@@ -0,0 +1,33 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { loadAndResolveErrorLocation } from '@lowdefy/errors';
+
+import readMergedMaps from '../../server/readMergedMaps.js';
+
+// The config file and line a config key comes from ("pages/home.yaml:88"),
+// through the dev server's key and ref maps (JIT page builds included), or
+// null when it cannot be located.
+async function resolveConfigKeySource({ buildDirectory, configDirectory, configKey }) {
+  const location = await loadAndResolveErrorLocation({
+    error: { configKey },
+    configDirectory,
+    readMaps: () => readMergedMaps({ buildDirectory }),
+  });
+  return location?.source ?? null;
+}
+
+export default resolveConfigKeySource;

package/lib/docs/observe/takeJourneyEvents.js

@@ -0,0 +1,36 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+function take(list, { since, until }) {
+  const taken = list.filter((event) => event.time >= since && event.time <= until);
+  const kept = list.filter((event) => event.time > until);
+  list.splice(0, list.length, ...kept);
+  return taken;
+}
+
+// Removes and returns the page errors, app requests and app responses a
+// journey's contexts buffered in [since, until] (milliseconds), dropping older
+// ones: what one step's window produced.
+function takeJourneyEvents({ events, since, until }) {
+  return {
+    pageErrors: take(events.pageErrors, { since, until }),
+    requests: take(events.requests, { since, until }),
+    responses: take(events.responses, { since, until }),
+    abortedRequests: take(events.abortedRequests, { since, until }),
+  };
+}
+
+export default takeJourneyEvents;

package/lib/docs/observe/toAppErrorFailure.js

@@ -0,0 +1,61 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+import { getStepKey } from '@lowdefy/node-utils';
+
+function describeWhere({ phase, index, step }) {
+  if (phase === 'open') {
+    return 'Opening the page';
+  }
+  return `Step ${index} (${getStepKey(step)})`;
+}
+
+// The journey failure for the app errors a window held: the step that caused
+// them (or phase 'open' for the page open, in place of index and step), each
+// error with its kind, message, config source and finding key.
+// When the step also failed on its own, the app error leads the message, since
+// it is usually the cause, and the step's own message follows (and is kept
+// apart as stepMessage).
+function toAppErrorFailure({ findings, phase, index, step, stepFailure }) {
+  const errors = findings.map(({ kind, message, source, configKey, key }) => ({
+    kind,
+    message,
+    source,
+    configKey,
+    key,
+  }));
+  const actual = errors.map((error) => `${error.kind}: ${error.message}`);
+  const count = errors.length === 1 ? 'an app error' : `${errors.length} app errors`;
+  const message = `${describeWhere({ phase, index, step })} caused ${count}: ${actual.join('; ')}`;
+  const failure = {
+    kind: 'app-error',
+    message,
+    expected: 'no app error',
+    actual,
+    errors,
+  };
+  if (!type.isUndefined(stepFailure)) {
+    failure.message = `${message}. The step also failed: ${stepFailure.message}`;
+    failure.stepMessage = stepFailure.message;
+  }
+  if (phase === 'open') {
+    return { phase: 'open', ...failure };
+  }
+  return { index, step, ...failure };
+}
+
+export default toAppErrorFailure;

package/lib/docs/observe/usesSearchStage.js

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { type } from '@lowdefy/helpers';
+
+const SEARCH_STAGES = ['"$search"', '"$vectorSearch"'];
+
+function readArtifactText({ buildDirectory, name }) {
+  const filePath = path.join(buildDirectory, name);
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+}
+
+// Whether a server error entry came from a request or endpoint whose built
+// artifact uses an Atlas Search stage ($search, $vectorSearch), which a data
+// set's memory store cannot run: the journey environment's limit, not the app's
+// fault.
+function usesSearchStage({ buildDirectory, entry }) {
+  let text = '';
+  if (!type.isNone(entry.requestId) && !type.isNone(entry.pageId)) {
+    text = readArtifactText({
+      buildDirectory,
+      name: path.join('pages', entry.pageId, 'requests', `${entry.requestId}.json`),
+    });
+  } else if (!type.isNone(entry.endpointId)) {
+    text = readArtifactText({ buildDirectory, name: path.join('api', `${entry.endpointId}.json`) });
+  }
+  return SEARCH_STAGES.some((stage) => text.includes(stage));
+}
+
+export default usesSearchStage;

package/lib/docs/observe/waitForClientErrorReports.js

@@ -0,0 +1,31 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+const POLL_MS = 25;
+
+// Waits, up to timeoutMs, until no client error report the journey's pages sent
+// is still in flight, so an error the step caused lands in the run's error buffer
+// before the step's window closes. A short grace first lets a report the
+// page is about to send start.
+async function waitForClientErrorReports({ events, graceMs = 100, timeoutMs = 2000 }) {
+  await new Promise((resolve) => setTimeout(resolve, graceMs));
+  const deadline = Date.now() + timeoutMs;
+  while (events.pendingClientErrors.size > 0 && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+  }
+}
+
+export default waitForClientErrorReports;

package/lib/docs/observe/watchJourneyContext.js

@@ -0,0 +1,75 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import isAppApiUrl from './isAppApiUrl.js';
+
+// Buffers, with timestamps, what a journey's browser context does that the
+// invariants read over a step's window: uncaught page errors, and the
+// requests to and responses from the app's request and endpoint API routes.
+// Hooked in before the context's first request, so the first page load is
+// watched too. Client error reports still in flight are counted, so a step's
+// window waits for them before it closes.
+const ABORTED_ERROR_TEXT = /ERR_ABORTED|NS_BINDING_ABORTED|cancelled/i;
+
+function watchJourneyContext({ context, events, origin, basePath }) {
+  const clientErrorPath = `${basePath}/api/client-error`;
+  function isClientErrorPost(request) {
+    try {
+      const url = new URL(request.url());
+      return url.origin === origin && url.pathname === clientErrorPath;
+    } catch {
+      return false;
+    }
+  }
+  function settleClientErrorPost(request) {
+    if (isClientErrorPost(request)) events.pendingClientErrors.delete(request);
+  }
+  context.on('requestfinished', settleClientErrorPost);
+  context.on('requestfailed', (request) => {
+    settleClientErrorPost(request);
+    // A request the browser cancelled, which is what leaving a page does to the
+    // page's requests in flight. An invariant reads it to tell that a fetch
+    // failure came from the runner's own navigation.
+    if (ABORTED_ERROR_TEXT.test(request.failure()?.errorText ?? '')) {
+      events.abortedRequests.push({ time: Date.now(), url: request.url() });
+    }
+  });
+  context.on('weberror', (webError) => {
+    const error = webError.error();
+    events.pageErrors.push({
+      time: Date.now(),
+      name: error?.name ?? 'Error',
+      message: error?.message ?? String(error),
+      stack: error?.stack ?? null,
+    });
+  });
+  context.on('request', (request) => {
+    if (isClientErrorPost(request)) events.pendingClientErrors.add(request);
+    if (!isAppApiUrl({ url: request.url(), origin, basePath })) return;
+    events.requests.push({ time: Date.now(), url: request.url(), method: request.method() });
+  });
+  context.on('response', (response) => {
+    if (!isAppApiUrl({ url: response.url(), origin, basePath })) return;
+    events.responses.push({
+      time: Date.now(),
+      url: response.url(),
+      method: response.request().method(),
+      status: response.status(),
+    });
+  });
+}
+
+export default watchJourneyContext;

package/lib/docs/observe/withAppErrors.js

@@ -0,0 +1,31 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import toAppErrorFailure from './toAppErrorFailure.js';
+
+// The step's failure once the app errors its window held are counted. App
+// errors fail the step, leading any failure of the step's own. A step that
+// left the journey's origin keeps that failure, since what it saw afterwards
+// is not what the app does, and carries the app errors beside it.
+function withAppErrors({ failure, leftOrigin, findings, index, step }) {
+  const appFailure = toAppErrorFailure({ findings, index, step, stepFailure: failure });
+  if (leftOrigin) {
+    return { ...failure, errors: appFailure.errors };
+  }
+  return appFailure;
+}
+
+export default withAppErrors;

package/lib/docs/observe/withAppErrors.test.mjs

@@ -0,0 +1,101 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import withAppErrors from './withAppErrors.js';
+
+const findings = [
+  {
+    kind: 'server-error',
+    severity: 'error',
+    message: 'Unrecognized pipeline stage',
+    pageId: 'orders',
+    source: 'pages/orders.yaml:12',
+    configKey: null,
+    key: 'server-error|orders|pages/orders.yaml:12',
+  },
+  {
+    kind: 'client-error',
+    severity: 'error',
+    message: 'Boom',
+    pageId: 'orders',
+    source: null,
+    configKey: null,
+    key: 'client-error|orders|message:abcd1234',
+  },
+];
+
+test('withAppErrors fails a step that passed with the app errors its window held', () => {
+  expect(withAppErrors({ findings, index: 2, step: { click: 'save' } })).toEqual({
+    index: 2,
+    step: { click: 'save' },
+    kind: 'app-error',
+    message:
+      'Step 2 (click) caused 2 app errors: server-error: Unrecognized pipeline stage; client-error: Boom',
+    expected: 'no app error',
+    actual: ['server-error: Unrecognized pipeline stage', 'client-error: Boom'],
+    errors: [
+      {
+        kind: 'server-error',
+        message: 'Unrecognized pipeline stage',
+        source: 'pages/orders.yaml:12',
+        configKey: null,
+        key: 'server-error|orders|pages/orders.yaml:12',
+      },
+      {
+        kind: 'client-error',
+        message: 'Boom',
+        source: null,
+        configKey: null,
+        key: 'client-error|orders|message:abcd1234',
+      },
+    ],
+  });
+});
+
+test('withAppErrors leads with the app error when the step also failed on its own', () => {
+  const failure = withAppErrors({
+    failure: { index: 0, step: { click: 'save' }, message: 'Expected text "Saved".' },
+    findings: [findings[0]],
+    index: 0,
+    step: { click: 'save' },
+  });
+  expect(failure.kind).toBe('app-error');
+  expect(failure.stepMessage).toBe('Expected text "Saved".');
+  expect(failure.message).toBe(
+    'Step 0 (click) caused an app error: server-error: Unrecognized pipeline stage. The step also failed: Expected text "Saved".'
+  );
+});
+
+test('withAppErrors keeps a left-origin failure and adds the app errors beside it', () => {
+  const leftOrigin = {
+    index: 1,
+    step: { as: 'outsider' },
+    expected: 'every request to stay on http://localhost:3227',
+    actual: 'http://127.0.0.1:3227/api/root',
+    message: 'Journey left its origin.',
+  };
+  const failure = withAppErrors({
+    failure: leftOrigin,
+    leftOrigin: true,
+    findings: [findings[0]],
+    index: 1,
+    step: { as: 'outsider' },
+  });
+  expect(failure).toEqual({
+    ...leftOrigin,
+    errors: [expect.objectContaining({ kind: 'server-error' })],
+  });
+});

package/lib/docs/openJourney.js

@@ -0,0 +1,94 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import createJourneyActors from './createJourneyActors.js';
+
+// The actor a journey starts as; `as` steps switch to others by name.
+const MAIN_ACTOR = 'main';
+
+// Opens a journey's first page as its main actor and returns the journey the
+// steps run against, with the main actor's page. `timeout` bounds each page
+// open, raised to `stepTimeout` when that is longer, so one journey setting
+// raises every such wait. Closes every actor it opened when the open fails.
+async function openJourney({
+  browser,
+  origin,
+  basePath,
+  pageId,
+  path,
+  pathParams,
+  user,
+  urlQuery,
+  width,
+  height,
+  colorScheme,
+  timeout,
+  stepTimeout,
+  dataCookie,
+  mutantCookie,
+  users,
+  recording,
+  onContext,
+}) {
+  const openTimeout = Math.max(timeout, stepTimeout);
+  // Taken before any page opens: mail the journey causes arrives after it,
+  // including mail the first page's onInit sends.
+  const startedAt = Date.now();
+  const actors = createJourneyActors({
+    browser,
+    origin,
+    basePath,
+    pageId,
+    path,
+    pathParams,
+    user,
+    urlQuery,
+    width,
+    height,
+    colorScheme,
+    timeout: openTimeout,
+    dataCookie,
+    mutantCookie,
+    users,
+    mainActor: MAIN_ACTOR,
+    recording,
+    onContext,
+  });
+  try {
+    const main = await actors.switchTo(MAIN_ACTOR);
+    const journey = {
+      actors,
+      origin,
+      configDirectory: process.env.LOWDEFY_DIRECTORY_CONFIG ?? process.cwd(),
+      startedAt,
+      openTimeout,
+      stepTimeout,
+      // The page the journey opened, whose blocks a step may name after the
+      // app sent the person elsewhere (see checkStepReferences).
+      pageId,
+      mainActor: MAIN_ACTOR,
+      // The data set's users on a data set run (undefined otherwise), which
+      // the `as` names are checked against (see checkStepReferences).
+      dataSetUsers: users,
+    };
+    return { journey, main };
+  } catch (error) {
+    await actors.closeAll();
+    throw error;
+  }
+}
+
+export default openJourney;

package/lib/docs/openJourneyEmail.js

@@ -0,0 +1,41 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import waitForJourneyEmail from './waitForJourneyEmail.js';
+
+function escapeHtml(text) {
+  return text.replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`);
+}
+
+// Opens the newest email to `to` (subject containing `subject`) received since
+// the journey started - waiting for one when none has arrived - in the actor's
+// tab, where `click` follows its links by their text and `expect.visible`
+// checks its content.
+async function openJourneyEmail({ page, params, since, configDirectory, timeout }) {
+  const message = await waitForJourneyEmail({ page, params, since, configDirectory, timeout });
+  const html = message.html ?? `<pre>${escapeHtml(message.text ?? '')}</pre>`;
+  await page.goto(`data:text/html;charset=utf-8;base64,${Buffer.from(html).toString('base64')}`, {
+    waitUntil: 'load',
+    timeout,
+  });
+  // Email buttons open in a new tab; a journey drives one tab per actor, so a
+  // link opens where the email is, the way the step after it expects.
+  await page.evaluate(() => {
+    document.querySelectorAll('a[target]').forEach((link) => link.removeAttribute('target'));
+  });
+}
+
+export default openJourneyEmail;