@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/checkStepReferences.js

@@ -0,0 +1,239 @@
+/*
+  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, normaliseBlockId } from '@lowdefy/node-utils';
+
+import getPageConfig from './getPageConfig.js';
+import JourneyStepError from './JourneyStepError.js';
+import pageBlocks from './pageBlocks.js';
+import readBuildArtifact from './readBuildArtifact.js';
+import readPageArtifact from './readPageArtifact.js';
+
+const TARGET_STEPS = ['click', 'open', 'fill', 'select'];
+const TARGET_EXPECTATIONS = ['visible', 'hidden', 'text'];
+
+// Lists the known ids in a failure when there are few enough to read.
+function describeKnown({ ids, noun }) {
+  if (ids.length === 0) {
+    return `It has no ${noun}s.`;
+  }
+  if (ids.length > 20) {
+    return '';
+  }
+  return `Known ${noun}s: ${ids.join(', ')}.`;
+}
+
+function unknownReference({ message, expected, actual }) {
+  return new JourneyStepError(message, { expected, actual });
+}
+
+// The blockId a step's target names, or undefined for a target with none (a
+// page-wide `text` or `containing` target) and for steps that name no target.
+function readTargetBlockId(step) {
+  const key = getStepKey(step);
+  let target;
+  if (TARGET_STEPS.includes(key)) {
+    target = step[key];
+  } else if (key === 'expect') {
+    const expectation = getStepKey(step.expect);
+    if (TARGET_EXPECTATIONS.includes(expectation)) {
+      target = step.expect[expectation];
+    }
+  }
+  if (type.isString(target)) {
+    return target;
+  }
+  return target?.blockId;
+}
+
+// The Lowdefy page the actor's tab shows, as its id and the ids of the blocks
+// its engine holds, or null when none shows (an opened email, a page that left
+// the app) or the app is between pages (isPageReady), when the id still names
+// the page being left. The engine's ids include blocks the build cannot name: a
+// Dynamic block's content, which the server resolves when the page is fetched.
+async function readShownPage({ page }) {
+  try {
+    return await page.evaluate(() => {
+      const lowdefy = window.lowdefy;
+      if (!lowdefy?.pageId || lowdefy._devNavigating === true) return null;
+      const shownKey = lowdefy.pageInstances?.[lowdefy.pageId]?.at(-1);
+      const blocks = lowdefy.contexts?.[shownKey]?._internal?.RootSlots?.map ?? {};
+      return { pageId: lowdefy.pageId, blockIds: Object.keys(blocks) };
+    });
+  } catch {
+    return null;
+  }
+}
+
+function builtBlockIds(built) {
+  return [built.blockId, ...pageBlocks(built).map((block) => block.blockId)];
+}
+
+function hasBlock({ ids, blockId }) {
+  const normalised = normaliseBlockId(blockId);
+  return ids.some((id) => normaliseBlockId(id) === normalised);
+}
+
+// A block of the page the journey opened is not a misspelling either: the app
+// may have sent the person elsewhere (a guarded page redirecting home, a
+// refused page showing the not-found page), and the step then fails as not
+// visible, which says what happened. The opened page's own id always counts,
+// so a page the server refused (and never built) still fails that way.
+function isBlockOfJourneyPage({ blockId, journeyPageId }) {
+  if (blockId === journeyPageId) {
+    return true;
+  }
+  const built = readPageArtifact({ pageId: journeyPageId });
+  return built !== null && hasBlock({ ids: builtBlockIds(built), blockId });
+}
+
+function checkBlockId({ blockId, shownPage, journeyPageId }) {
+  const { pageId } = shownPage;
+  const known = builtBlockIds(readPageArtifact({ pageId }));
+  if (hasBlock({ ids: [...known, ...shownPage.blockIds], blockId })) {
+    return;
+  }
+  if (pageId !== journeyPageId && isBlockOfJourneyPage({ blockId, journeyPageId })) {
+    return;
+  }
+  throw unknownReference({
+    message: `Page "${pageId}" has no block "${blockId}". ${describeKnown({
+      ids: known,
+      noun: 'block',
+    })}`.trim(),
+    expected: `a block "${blockId}" on page "${pageId}"`,
+    actual: `no block "${blockId}"`,
+  });
+}
+
+// A request is counted on a page the journey may not have visited yet, so that
+// page is built first, as a visit would build it.
+async function checkRequestId({ requestId, pageId, currentPageId }) {
+  if (pageId !== currentPageId) {
+    const config = await getPageConfig({ pageId });
+    if (config === null) {
+      throw unknownReference({
+        message: `There is no page "${pageId}" to count request "${requestId}" on.`,
+        expected: `a page "${pageId}"`,
+        actual: `no page "${pageId}"`,
+      });
+    }
+  }
+  const request = readBuildArtifact({ name: `pages/${pageId}/requests/${requestId}.json` });
+  if (request !== null) {
+    return;
+  }
+  const built = readPageArtifact({ pageId });
+  const known = (built?.requests ?? []).map((item) => item.requestId);
+  throw unknownReference({
+    message: `Page "${pageId}" has no request "${requestId}". ${describeKnown({
+      ids: known,
+      noun: 'request',
+    })}`.trim(),
+    expected: `a request "${requestId}" on page "${pageId}"`,
+    actual: `no request "${requestId}"`,
+  });
+}
+
+function checkEndpointId({ endpointId }) {
+  if (readBuildArtifact({ name: `api/${endpointId}.json` }) !== null) {
+    return;
+  }
+  throw unknownReference({
+    message: `The app has no endpoint "${endpointId}".`,
+    expected: `an endpoint "${endpointId}"`,
+    actual: `no endpoint "${endpointId}"`,
+  });
+}
+
+function checkPageId({ pageId }) {
+  const registry = readBuildArtifact({ name: 'pageRegistry.json' });
+  if (Object.prototype.hasOwnProperty.call(registry, pageId)) {
+    return;
+  }
+  throw unknownReference({
+    message: `The app has no page "${pageId}". ${describeKnown({
+      ids: Object.keys(registry),
+      noun: 'page',
+    })}`.trim(),
+    expected: `a page "${pageId}"`,
+    actual: `no page "${pageId}"`,
+  });
+}
+
+// On a data set run, an `as` name opens that data set user, so a name that is
+// neither the journey's first actor nor one of its users is a misspelling.
+// Without a data set any name is a new browser as the journey's user.
+function checkActorName({ journey, name }) {
+  if (type.isUndefined(journey.dataSetUsers) || name === journey.mainActor) {
+    return;
+  }
+  if (Object.prototype.hasOwnProperty.call(journey.dataSetUsers, name)) {
+    return;
+  }
+  const users = Object.keys(journey.dataSetUsers);
+  throw unknownReference({
+    message: `"as" names "${name}", who is neither "${
+      journey.mainActor
+    }" nor a user of the data set. ${describeKnown({ ids: users, noun: 'user' })}`.trim(),
+    expected: `"${journey.mainActor}" or a data set user`,
+    actual: `no data set user "${name}"`,
+  });
+}
+
+// Checked at the start of every step, before it acts, against the current
+// build: a misspelt blockId, requestId, endpointId, goto pageId or `as` name
+// fails its step and names the unknown id, instead of passing a step that
+// asserts something is absent (expect.hidden, expect.calls with count 0) or
+// opening the not-found page. Ids are read from the actor's current page (a
+// block also from the page the journey opened); when no Lowdefy page shows, or
+// the app is between pages, block and request checks are skipped and the
+// step's own wait reports what it finds.
+async function checkStepReferences({ journey, page, step }) {
+  const key = getStepKey(step);
+  if (key === 'as') {
+    checkActorName({ journey, name: step.as });
+    return;
+  }
+  if (key === 'goto') {
+    checkPageId({ pageId: type.isString(step.goto) ? step.goto : step.goto.pageId });
+    return;
+  }
+  const calls = key === 'expect' && getStepKey(step.expect) === 'calls' ? step.expect.calls : null;
+  if (calls !== null && !type.isUndefined(calls.endpoint)) {
+    checkEndpointId({ endpointId: calls.endpoint });
+    return;
+  }
+  const blockId = readTargetBlockId(step);
+  const requestId = key === 'wait' ? step.wait.request : calls?.request;
+  if (type.isUndefined(blockId) && type.isUndefined(requestId)) {
+    return;
+  }
+  const shownPage = await readShownPage({ page });
+  const currentPageId = shownPage?.pageId ?? null;
+  if (!type.isUndefined(blockId) && shownPage !== null) {
+    checkBlockId({ blockId, shownPage, journeyPageId: journey.pageId });
+  }
+  if (!type.isUndefined(requestId)) {
+    const pageId = calls?.pageId ?? currentPageId;
+    if (pageId !== null) {
+      await checkRequestId({ requestId, pageId, currentPageId });
+    }
+  }
+}
+
+export default checkStepReferences;

package/lib/docs/checkStepReferences.test.mjs

@@ -0,0 +1,173 @@
+/*
+  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 os from 'node:os';
+import path from 'node:path';
+
+import { jest } from '@jest/globals';
+
+// getPageConfig JIT-builds a page the journey has not visited; here the
+// fixture build already holds every page it knows.
+const mockGetPageConfig = jest.fn(async ({ pageId }) =>
+  ['home', 'second'].includes(pageId) ? {} : null
+);
+jest.unstable_mockModule('./getPageConfig.js', () => ({ default: mockGetPageConfig }));
+
+const { default: checkStepReferences } = await import('./checkStepReferences.js');
+
+const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-check-step-references-'));
+const previousCwd = process.cwd();
+
+function write(name, value) {
+  const filePath = path.join(directory, 'build', name);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value));
+}
+
+beforeAll(() => {
+  write('pageRegistry.json', { home: {}, second: {} });
+  write('pages/home.json', {
+    id: 'page:home',
+    blockId: 'home',
+    pageId: 'home',
+    areas: {
+      content: {
+        blocks: [
+          { blockId: 'title' },
+          {
+            blockId: 'rows',
+            areas: { content: { blocks: [{ blockId: 'rows.$.name' }] } },
+          },
+        ],
+      },
+    },
+  });
+  write('pages/home/requests/save_item.json', { requestId: 'save_item' });
+  write('pages/second/requests/load.json', { requestId: 'load' });
+  write('api/notify.json', { endpointId: 'notify' });
+  process.chdir(directory);
+});
+
+afterAll(() => {
+  process.chdir(previousCwd);
+  fs.rmSync(directory, { recursive: true, force: true });
+});
+
+// The page's evaluate answers what readShownPage reads from window.lowdefy:
+// the shown page's id and the ids of the blocks its engine holds.
+function pageShowing(pageId, { blockIds = [] } = {}) {
+  return { evaluate: async () => ({ pageId, blockIds }) };
+}
+
+function journeyWith(overrides = {}) {
+  return { pageId: 'home', mainActor: 'main', dataSetUsers: undefined, ...overrides };
+}
+
+async function check(step, { page = pageShowing('home'), journey = journeyWith() } = {}) {
+  try {
+    await checkStepReferences({ journey, page, step });
+    return undefined;
+  } catch (error) {
+    return error;
+  }
+}
+
+test.each([
+  [{ click: 'title' }],
+  [{ fill: { blockId: 'rows.0.name', value: 'x' } }],
+  [{ expect: { hidden: { blockId: 'title', containing: 'gone' } } }],
+  [{ expect: { visible: 'home' } }],
+  [{ click: { text: 'Save' } }],
+  [{ wait: { request: 'save_item' } }],
+  [{ wait: { ms: 10 } }],
+  [{ expect: { calls: { request: 'save_item', count: 0 } } }],
+  [{ expect: { calls: { request: 'load', pageId: 'second', count: 0 } } }],
+  [{ expect: { calls: { endpoint: 'notify', count: 0 } } }],
+  [{ expect: { state: { path: 'anything', equals: null } } }],
+  [{ goto: 'second' }],
+  [{ goto: { pageId: 'second' } }],
+  [{ as: 'anyone' }],
+])('checkStepReferences passes %j', async (step) => {
+  expect(await check(step)).toBeUndefined();
+});
+
+test.each([
+  [{ expect: { hidden: 'nosuchblock' } }, 'no block "nosuchblock"'],
+  [{ click: { blockId: 'nosuchblock', text: 'Go' } }, 'no block "nosuchblock"'],
+  [{ wait: { request: 'nosuchrequest' } }, 'no request "nosuchrequest"'],
+  [{ expect: { calls: { request: 'nosuchrequest', count: 0 } } }, 'no request "nosuchrequest"'],
+  [
+    { expect: { calls: { request: 'save_item', pageId: 'second', count: 0 } } },
+    'no request "save_item"',
+  ],
+  [
+    { expect: { calls: { request: 'save_item', pageId: 'nosuchpage', count: 0 } } },
+    'no page "nosuchpage"',
+  ],
+  [{ expect: { calls: { endpoint: 'nosuchendpoint', count: 0 } } }, 'no endpoint "nosuchendpoint"'],
+  [{ goto: 'nosuchpage' }, 'no page "nosuchpage"'],
+])('checkStepReferences fails %j naming the unknown id', async (step, actual) => {
+  const error = await check(step);
+  expect(error.name).toBe('JourneyStepError');
+  expect(error.actual).toBe(actual);
+});
+
+test('checkStepReferences lists the known blocks of a small page', async () => {
+  const error = await check({ expect: { hidden: 'nosuchblock' } });
+  expect(error.message).toBe(
+    'Page "home" has no block "nosuchblock". Known blocks: home, title, rows, rows.$.name.'
+  );
+});
+
+test('checkStepReferences skips block and request checks when no Lowdefy page shows', async () => {
+  const page = { evaluate: async () => null };
+  expect(await check({ expect: { hidden: 'nosuchblock' } }, { page })).toBeUndefined();
+  expect(await check({ wait: { request: 'nosuchrequest' } }, { page })).toBeUndefined();
+});
+
+test('checkStepReferences fails an as name that is not a user of the data set', async () => {
+  const journey = journeyWith({ dataSetUsers: { member: {}, owner: {} } });
+  const error = await check({ as: 'membr' }, { journey });
+  expect(error.actual).toBe('no data set user "membr"');
+  expect(error.message).toBe(
+    '"as" names "membr", who is neither "main" nor a user of the data set. Known users: member, owner.'
+  );
+  expect(await check({ as: 'member' }, { journey })).toBeUndefined();
+  expect(await check({ as: 'main' }, { journey })).toBeUndefined();
+});
+
+test('checkStepReferences accepts a block of the page the journey opened when the app moved elsewhere', async () => {
+  const page = pageShowing('second');
+  write('pages/second.json', { id: 'page:second', blockId: 'second', pageId: 'second' });
+  expect(await check({ expect: { visible: 'title' } }, { page })).toBeUndefined();
+  expect(
+    await check(
+      { expect: { visible: 'refused' } },
+      { page, journey: journeyWith({ pageId: 'refused' }) }
+    )
+  ).toBeUndefined();
+  const error = await check({ expect: { visible: 'nosuchblock' } }, { page });
+  expect(error.message).toBe('Page "second" has no block "nosuchblock". Known blocks: second.');
+});
+
+test('checkStepReferences accepts a block the shown page holds but the build does not name', async () => {
+  // A Dynamic block's content is resolved by the server when the page is fetched.
+  const page = pageShowing('home', { blockIds: ['title', 'dynamic_content', 'dynamic_save'] });
+  expect(await check({ click: 'dynamic_save' }, { page })).toBeUndefined();
+  const error = await check({ expect: { hidden: 'nosuchblock' } }, { page });
+  expect(error.actual).toBe('no block "nosuchblock"');
+});

package/lib/docs/checkpointStore.js

@@ -139,6 +139,8 @@ function writeCheckpoint({ name, snapshot, notes, overwrite }) {
   parts.push('state.json');
   writeJsonFile(path.join(dir, 'urlQuery.json'), snapshot.urlQuery ?? '');
   parts.push('urlQuery.json');
+  writeJsonFile(path.join(dir, 'pathParams.json'), snapshot.pathParams ?? {});
+  parts.push('pathParams.json');
   writeJsonFile(path.join(dir, 'inputs.json'), snapshot.input ?? {});
   parts.push('inputs.json');
   writeJsonFile(path.join(dir, 'user.json'), snapshot.user ?? null);
@@ -177,6 +179,7 @@ function readCheckpoint({ name }) {
     checkpoint,
     state: readJsonFile(path.join(dir, 'state.json'), {}),
     urlQuery: readJsonFile(path.join(dir, 'urlQuery.json'), ''),
+    pathParams: readJsonFile(path.join(dir, 'pathParams.json'), {}),
     input: readJsonFile(path.join(dir, 'inputs.json'), {}),
     user: readJsonFile(path.join(dir, 'user.json'), null),
     global: readJsonFile(path.join(dir, 'global.json'), {}),

package/lib/docs/clientErrorStore.js

@@ -14,6 +14,11 @@
   limitations under the License.
 */
 
+import { publish } from './devEventBus.js';
+import getBuildId from './getBuildId.js';
+import isRunErrorEntry from './isRunErrorEntry.js';
+import { recordRunError } from './runErrorBuffers.js';
+
 // Module-level ring buffer of recent client-reported errors — feeds the
 // getBuildStatus feedback endpoint so agents can see browser errors without
 // tailing server logs. Deliberately in-memory only: entries are lost on
@@ -22,11 +27,23 @@ const MAX_ENTRIES = 50;
 
 const entries = [];
 
+// Each entry is stamped with the build it happened under (see getBuildId).
+// An entry a journey run caused goes to that run's own
+// buffer only (see runErrorBuffers), or is dropped when the run has ended:
+// kept out of this ring and the event bus, it never reaches build-status or
+// an agent's event stream, and a run that trips many errors cannot evict the
+// developer's own. The run reports its errors in its own result.
 function push(entry) {
-  entries.push(entry);
+  const stamped = { ...entry, buildId: getBuildId() };
+  if (isRunErrorEntry(stamped)) {
+    recordRunError({ ...stamped, store: 'client' });
+    return;
+  }
+  entries.push(stamped);
   if (entries.length > MAX_ENTRIES) {
     entries.shift();
   }
+  publish({ type: 'client_error', ...stamped });
 }
 
 function list() {

package/lib/docs/clientErrorStore.test.mjs

@@ -0,0 +1,46 @@
+/*
+  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 { jest } from '@jest/globals';
+
+const mockPublish = jest.fn();
+jest.unstable_mockModule('./devEventBus.js', () => ({
+  publish: mockPublish,
+}));
+jest.unstable_mockModule('./getBuildId.js', () => ({
+  default: () => '2026-01-01T00:00:00.000Z',
+}));
+
+const { default: clientErrorStore } = await import('./clientErrorStore.js');
+
+test('clientErrorStore push adds an entry stamped with the current build, lists it, and publishes it as a client_error event', () => {
+  const entry = { timestamp: '2026-01-01T00:00:00.000Z', name: 'OperatorError', message: 'bad' };
+  const stamped = { ...entry, buildId: '2026-01-01T00:00:00.000Z' };
+  clientErrorStore.push(entry);
+  expect(clientErrorStore.list()).toEqual([stamped]);
+  expect(mockPublish).toHaveBeenCalledWith({ type: 'client_error', ...stamped });
+});
+
+test('clientErrorStore caps at 50 entries and drops the oldest', () => {
+  for (let i = 0; i < 60; i++) {
+    clientErrorStore.push({ index: i });
+  }
+  const entries = clientErrorStore.list();
+  expect(entries.length).toEqual(50);
+  expect(entries[0].index).toEqual(10);
+  expect(entries[49].index).toEqual(59);
+  expect(mockPublish).toHaveBeenCalledTimes(60);
+});

package/lib/docs/collectExercised.js

@@ -0,0 +1,52 @@
+/*
+  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 addNestedEndpoints from './addNestedEndpoints.js';
+import addWriteFlags from './addWriteFlags.js';
+import matchExercisedPages from './matchExercisedPages.js';
+import mergeNetworkSnapshots from './mergeNetworkSnapshots.js';
+
+// What one journey run touched, across all of its actors: the network path
+// its browsers measured, the endpoints their routines reached through CallApi,
+// which requests and endpoints write, and what its pages observed: the events
+// that completed and the blocks that were ever visible.
+async function collectExercised({ snapshots, observed, readConfigFile, requestSchemas }) {
+  const network = mergeNetworkSnapshots({ snapshots });
+  const { endpoints, unfollowed } = await addNestedEndpoints({
+    endpoints: network.endpoints,
+    readConfigFile,
+  });
+  const withWrites = await addWriteFlags({
+    requests: network.requests,
+    endpoints,
+    readConfigFile,
+    requestSchemas,
+  });
+  return {
+    pages: matchExercisedPages({
+      routes: await readConfigFile('routes.json'),
+      pagePaths: network.pagePaths,
+    }),
+    appEvents: network.appEvents,
+    requests: withWrites.requests,
+    endpoints: withWrites.endpoints,
+    unfollowed,
+    events: observed.events,
+    rendered: observed.rendered,
+  };
+}
+
+export default collectExercised;

package/lib/docs/createBrowserLifecycle.js

@@ -0,0 +1,102 @@
+/*
+  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';
+
+// One shared browser per dev server child, launched on first use and closed
+// once unused for idleTimeout ms, so a server that lives for hours does not
+// hold a browser it used once. The close waits for three things: no open
+// context, no launch in flight, and no getBrowser() call for idleTimeout ms.
+// The last one covers a caller between getBrowser() and its first
+// newContext, which holds the browser without a context yet.
+function createBrowserLifecycle({ launch, idleTimeout }) {
+  // Cached as a promise so concurrent calls awaiting a launch share it.
+  let browserPromise = null;
+  let launching = 0;
+  let openContexts = 0;
+  let idleTimer = null;
+
+  function closeIfIdle() {
+    idleTimer = null;
+    if (type.isNone(browserPromise) || openContexts > 0 || launching > 0) {
+      return;
+    }
+    const closing = browserPromise;
+    browserPromise = null;
+    closing.then((browser) => browser.close()).catch(() => {});
+  }
+
+  function armIdleClose() {
+    clearTimeout(idleTimer);
+    idleTimer = setTimeout(closeIfIdle, idleTimeout);
+    // Never the reason the process stays up.
+    idleTimer.unref();
+  }
+
+  function startLaunch() {
+    launching += 1;
+    const launched = launch();
+    browserPromise = launched;
+    launched
+      .catch(() => {
+        // Forget a failed launch so the next call retries instead of
+        // replaying the rejection forever.
+        if (browserPromise === launched) {
+          browserPromise = null;
+        }
+      })
+      .finally(() => {
+        launching -= 1;
+        // A launch can outlast the idle timeout (it may wait for the shell
+        // download), so the countdown starts again once it settles.
+        armIdleClose();
+      });
+  }
+
+  async function getBrowser() {
+    armIdleClose();
+    if (type.isNone(browserPromise)) {
+      startLaunch();
+    }
+    const current = browserPromise;
+    const browser = await current;
+    if (browser.isConnected()) {
+      return browser;
+    }
+    // The browser crashed or was closed under us. Concurrent callers that
+    // all saw it share one relaunch.
+    if (browserPromise === current) {
+      startLaunch();
+    }
+    return browserPromise;
+  }
+
+  // Counts a context until it closes. Playwright emits close for every way a
+  // context ends: context.close(), browser.close() or a browser crash.
+  function trackContext(context) {
+    openContexts += 1;
+    context.on('close', () => {
+      openContexts -= 1;
+      if (openContexts === 0) {
+        armIdleClose();
+      }
+    });
+  }
+
+  return { getBrowser, trackContext };
+}
+
+export default createBrowserLifecycle;