@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/tabChannel.test.mjs

@@ -16,8 +16,15 @@
 
 import { jest } from '@jest/globals';
 
-const { listTabs, registerTab, requestFromTab, resolveTabRequest, unregisterTab, updateTabPage } =
-  await import('./tabChannel.js');
+const {
+  findPageInstance,
+  listTabs,
+  registerTab,
+  requestFromTab,
+  resolveTabRequest,
+  unregisterTab,
+  updateTabPage,
+} = await import('./tabChannel.js');
 
 // tabChannel keeps its registries at module scope, so clear connected tabs
 // between tests to keep them independent.
@@ -25,43 +32,139 @@ afterEach(() => {
   listTabs().forEach((tab) => unregisterTab({ id: tab.id }));
 });
 
-test('registerTab adds a tab visible via listTabs', () => {
-  registerTab({ id: 'tab-1', pageId: 'home', send: jest.fn() });
+function ticket({ space = 's', ticketId }) {
+  return {
+    pageId: 'ticket',
+    pathParams: { space, ticket_id: ticketId },
+    instanceKey: `page:ticket#tickets/${space}/${ticketId}`,
+  };
+}
+
+function connectTab({ id, pageId, send = jest.fn(), ...origin }) {
+  registerTab({ id, send, ...origin });
+  if (pageId) {
+    updateTabPage({ id, pageId, pathParams: {}, instanceKey: `page:${pageId}` });
+  }
+  return send;
+}
+
+test('registerTab adds a tab visible via listTabs, on no page until its first page renders', () => {
+  registerTab({ id: 'tab-1', send: jest.fn() });
   const tabs = listTabs();
   expect(tabs).toHaveLength(1);
-  expect(tabs[0]).toMatchObject({ id: 'tab-1', pageId: 'home' });
+  expect(tabs[0]).toMatchObject({ id: 'tab-1', pageId: null, pathParams: null, instanceKey: null });
   expect(tabs[0].connectedAt).toBeInstanceOf(Date);
 });
 
 test('registerTab throws when id is missing', () => {
-  expect(() => registerTab({ pageId: 'home', send: jest.fn() })).toThrow('registerTab requires');
+  expect(() => registerTab({ send: jest.fn() })).toThrow('registerTab requires');
 });
 
 test('registerTab throws when send is not a function', () => {
-  expect(() => registerTab({ id: 'tab-1', pageId: 'home' })).toThrow(
-    'registerTab requires a "send" function'
-  );
+  expect(() => registerTab({ id: 'tab-1' })).toThrow('registerTab requires a "send" function');
 });
 
 test('unregisterTab removes a tab from the registry', () => {
-  registerTab({ id: 'tab-1', pageId: 'home', send: jest.fn() });
+  connectTab({ id: 'tab-1', pageId: 'home' });
   unregisterTab({ id: 'tab-1' });
   expect(listTabs()).toHaveLength(0);
 });
 
-test('updateTabPage changes the pageId of a registered tab', () => {
-  registerTab({ id: 'tab-1', pageId: 'home', send: jest.fn() });
-  updateTabPage({ id: 'tab-1', pageId: 'about' });
-  expect(listTabs()[0].pageId).toEqual('about');
+test('updateTabPage records the page instance a tab shows', () => {
+  connectTab({ id: 'tab-1', pageId: 'home' });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '2' }) });
+  expect(listTabs()[0]).toMatchObject({
+    id: 'tab-1',
+    pageId: 'ticket',
+    pathParams: { space: 's', ticket_id: '2' },
+    instanceKey: 'page:ticket#tickets/s/2',
+  });
 });
 
 test('updateTabPage on an unknown tab id does not throw', () => {
-  expect(() => updateTabPage({ id: 'missing', pageId: 'about' })).not.toThrow();
+  expect(() =>
+    updateTabPage({ id: 'missing', pageId: 'about', instanceKey: 'page:about' })
+  ).not.toThrow();
+});
+
+test('updateTabPage throws when the instance key is missing', () => {
+  registerTab({ id: 'tab-1', send: jest.fn() });
+  expect(() => updateTabPage({ id: 'tab-1', pageId: 'about' })).toThrow(
+    'updateTabPage requires "pageId" and "instanceKey" strings'
+  );
+});
+
+test('findPageInstance reads the instance on screen when the tab is on the page', () => {
+  registerTab({ id: 'tab-1', send: jest.fn() });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '1' }) });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '2' }) });
+  const { tab, ...instance } = findPageInstance({ pageId: 'ticket' });
+  expect(tab.id).toEqual('tab-1');
+  expect(instance).toEqual(ticket({ ticketId: '2' }));
+});
+
+test('findPageInstance reads the most recently rendered instance when no tab is on the page', () => {
+  registerTab({ id: 'tab-1', send: jest.fn() });
+  registerTab({ id: 'tab-2', send: jest.fn() });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '1' }) });
+  updateTabPage({ id: 'tab-2', ...ticket({ ticketId: '2' }) });
+  updateTabPage({ id: 'tab-1', pageId: 'home', instanceKey: 'page:home' });
+  updateTabPage({ id: 'tab-2', pageId: 'home', instanceKey: 'page:home' });
+  const { tab, ...instance } = findPageInstance({ pageId: 'ticket' });
+  expect(tab.id).toEqual('tab-2');
+  expect(instance).toEqual(ticket({ ticketId: '2' }));
+});
+
+test('findPageInstance prefers a tab showing the page over a later render elsewhere', () => {
+  registerTab({ id: 'tab-1', send: jest.fn() });
+  registerTab({ id: 'tab-2', send: jest.fn() });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '1' }) });
+  updateTabPage({ id: 'tab-2', ...ticket({ ticketId: '2' }) });
+  updateTabPage({ id: 'tab-2', pageId: 'home', instanceKey: 'page:home' });
+  const { tab, ...instance } = findPageInstance({ pageId: 'ticket' });
+  expect(tab.id).toEqual('tab-1');
+  expect(instance).toEqual(ticket({ ticketId: '1' }));
+});
+
+test('findPageInstance with pathParams reads that instance, comparing values as strings', () => {
+  registerTab({ id: 'tab-1', send: jest.fn() });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '1' }) });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '2' }) });
+  const { tab, ...instance } = findPageInstance({
+    pageId: 'ticket',
+    pathParams: { space: 's', ticket_id: 1 },
+  });
+  expect(tab.id).toEqual('tab-1');
+  expect(instance).toEqual(ticket({ ticketId: '1' }));
+});
+
+test('findPageInstance returns undefined for values no tab has rendered', () => {
+  registerTab({ id: 'tab-1', send: jest.fn() });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '1' }) });
+  expect(
+    findPageInstance({ pageId: 'ticket', pathParams: { space: 's', ticket_id: '3' } })
+  ).toBeUndefined();
+  expect(findPageInstance({ pageId: 'ticket', pathParams: { space: 's' } })).toBeUndefined();
+});
+
+test('findPageInstance without a pageId reads the most recently connected tab on screen', () => {
+  connectTab({ id: 'tab-1', pageId: 'home' });
+  connectTab({ id: 'tab-2', pageId: 'about' });
+  registerTab({ id: 'tab-3', send: jest.fn() });
+  const { tab, ...instance } = findPageInstance();
+  expect(tab.id).toEqual('tab-2');
+  expect(instance).toEqual({ pageId: 'about', pathParams: {}, instanceKey: 'page:about' });
+});
+
+test('findPageInstance forgets the instances of a tab that disconnected', () => {
+  registerTab({ id: 'tab-1', send: jest.fn() });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '1' }) });
+  unregisterTab({ id: 'tab-1' });
+  expect(findPageInstance({ pageId: 'ticket' })).toBeUndefined();
 });
 
 test('requestFromTab sends the event to the matching tab and resolves via resolveTabRequest', async () => {
-  const send = jest.fn();
-  registerTab({ id: 'tab-1', pageId: 'home', send });
+  const send = connectTab({ id: 'tab-1', pageId: 'home' });
   const promise = requestFromTab({ pageId: 'home', event: 'inspect-request' });
 
   expect(send).toHaveBeenCalledTimes(1);
@@ -74,11 +177,28 @@ test('requestFromTab sends the event to the matching tab and resolves via resolv
   await expect(promise).resolves.toEqual('snapshot');
 });
 
-test('requestFromTab targets the tab registered for the given pageId', async () => {
-  const sendHome = jest.fn();
-  const sendAbout = jest.fn();
-  registerTab({ id: 'tab-home', pageId: 'home', send: sendHome });
-  registerTab({ id: 'tab-about', pageId: 'about', send: sendAbout });
+test('requestFromTab names the instance to read in the event it sends', async () => {
+  const send = jest.fn();
+  registerTab({ id: 'tab-1', send });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '1' }) });
+  updateTabPage({ id: 'tab-1', ...ticket({ ticketId: '2' }) });
+  requestFromTab({
+    pageId: 'ticket',
+    pathParams: { space: 's', ticket_id: '1' },
+    event: 'eval-request',
+    payload: { expression: { _state: 'a' } },
+    timeout: 10,
+  });
+  expect(send.mock.calls[0][1]).toEqual({
+    requestId: expect.any(String),
+    ...ticket({ ticketId: '1' }),
+    expression: { _state: 'a' },
+  });
+});
+
+test('requestFromTab targets the tab on the given pageId', async () => {
+  const sendHome = connectTab({ id: 'tab-home', pageId: 'home' });
+  const sendAbout = connectTab({ id: 'tab-about', pageId: 'about' });
 
   const promise = requestFromTab({ pageId: 'about', event: 'eval-request' });
   expect(sendAbout).toHaveBeenCalledTimes(1);
@@ -90,9 +210,8 @@ test('requestFromTab targets the tab registered for the given pageId', async ()
 });
 
 test('requestFromTab picks the most recently registered tab when pageId is omitted', async () => {
-  registerTab({ id: 'tab-1', pageId: 'home', send: jest.fn() });
-  const sendLatest = jest.fn();
-  registerTab({ id: 'tab-2', pageId: 'about', send: sendLatest });
+  connectTab({ id: 'tab-1', pageId: 'home' });
+  const sendLatest = connectTab({ id: 'tab-2', pageId: 'about' });
 
   const promise = requestFromTab({ event: 'inspect-request' });
   expect(sendLatest).toHaveBeenCalledTimes(1);
@@ -103,13 +222,25 @@ test('requestFromTab picks the most recently registered tab when pageId is omitt
 });
 
 test('requestFromTab resolves with an error when no tab matches the pageId', async () => {
-  registerTab({ id: 'tab-1', pageId: 'home', send: jest.fn() });
+  connectTab({ id: 'tab-1', pageId: 'home' });
   const response = await requestFromTab({ pageId: 'missing-page', event: 'inspect-request' });
   expect(response.error).toContain('No browser tab connected');
 });
 
+test('requestFromTab names the pathParams in its error when no tab has that instance', async () => {
+  connectTab({ id: 'tab-1', pageId: 'home' });
+  const response = await requestFromTab({
+    pageId: 'ticket',
+    pathParams: { space: 's', ticket_id: '1' },
+    event: 'inspect-request',
+  });
+  expect(response.error).toEqual(
+    'No browser tab connected on page "ticket" with pathParams {"space":"s","ticket_id":"1"}. Ask the developer to open the page, or use source: "headless".'
+  );
+});
+
 test('requestFromTab resolves with a timeout error when no response arrives in time', async () => {
-  registerTab({ id: 'tab-1', pageId: 'home', send: jest.fn() });
+  connectTab({ id: 'tab-1', pageId: 'home' });
   const response = await requestFromTab({ pageId: 'home', event: 'inspect-request', timeout: 10 });
   expect(response.error).toContain('Timed out');
 });
@@ -119,8 +250,7 @@ test('resolveTabRequest returns false for an unknown requestId', () => {
 });
 
 test('resolveTabRequest returns false when called again for an already-settled requestId', async () => {
-  const send = jest.fn();
-  registerTab({ id: 'tab-1', pageId: 'home', send });
+  const send = connectTab({ id: 'tab-1', pageId: 'home' });
   const promise = requestFromTab({ pageId: 'home', event: 'inspect-request' });
   const requestId = send.mock.calls[0][1].requestId;
 
@@ -128,3 +258,31 @@ test('resolveTabRequest returns false when called again for an already-settled r
   await promise;
   expect(resolveTabRequest({ requestId, result: 'second' })).toBe(false);
 });
+
+test('requestFromTab skips an automated journey tab for the developer tab on the same page', async () => {
+  const developerSend = connectTab({ id: 'developer', pageId: 'tickets' });
+  const walkSend = connectTab({
+    id: 'walk',
+    pageId: 'tickets',
+    source: 'journey',
+    automated: true,
+  });
+  const promise = requestFromTab({ pageId: 'tickets', event: 'inspect-request', timeout: 50 });
+  expect(developerSend).toHaveBeenCalledTimes(1);
+  expect(walkSend).not.toHaveBeenCalled();
+  const [, { requestId }] = developerSend.mock.calls[0];
+  resolveTabRequest({ requestId, result: { state: {} } });
+  await expect(promise).resolves.toEqual({ state: {} });
+  expect(listTabs().map(({ id, source, automated }) => ({ id, source, automated }))).toEqual([
+    { id: 'developer', source: 'dev', automated: false },
+    { id: 'walk', source: 'journey', automated: true },
+  ]);
+});
+
+test('requestFromTab finds no tab when only an automated tab is on the page', async () => {
+  connectTab({ id: 'walk', pageId: 'tickets', source: 'journey', automated: true });
+  await expect(requestFromTab({ pageId: 'tickets', event: 'inspect-request' })).resolves.toEqual({
+    error:
+      'No browser tab connected on page "tickets". Ask the developer to open the page, or use source: "headless".',
+  });
+});

package/lib/docs/unsettledPageNote.js

@@ -0,0 +1,24 @@
+/*
+  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 note every headless tool attaches alongside `ready: false`, so an agent
+// reading the result knows it is looking at a page mid-flight rather than the
+// page's settled truth.
+function unsettledPageNote({ timeout }) {
+  return `Page did not settle within ${timeout}ms — onMountAsync, a request or a subscription is still running. The result below is a snapshot of an unsettled page.`;
+}
+
+export default unsettledPageNote;

package/lib/docs/validateJourneyMail.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.
+*/
+
+import { type } from '@lowdefy/helpers';
+import { getStepKey } from '@lowdefy/node-utils';
+
+function readsMail(step) {
+  const key = getStepKey(step);
+  return key === 'email' || (key === 'fill' && !type.isUndefined(step.fill.fromEmail));
+}
+
+// Steps that read email need the dev server's mail sink. Without it they would
+// each wait out their timeout for mail that can never arrive, so the journey is
+// refused up front. Returns an error message, or undefined.
+function validateJourneyMail({ steps }) {
+  const capturesMail = process.env.LOWDEFY_SERVER_DEV_MAIL_SINK === 'true';
+  if (steps.some(readsMail) && !capturesMail) {
+    return 'The steps read email (an "email" step or a "fill" with "fromEmail"), but this dev server captures no mail. Start (or restart) it with LOWDEFY_DEV_SMTP_PORT set to a free port, and point the app\'s SMTP connection at 127.0.0.1 on that port.';
+  }
+  return undefined;
+}
+
+export default validateJourneyMail;

package/lib/docs/validateJourneyTimeout.js

@@ -0,0 +1,38 @@
+/*
+  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';
+
+// A step that needs longer than a minute is a hung page, and a failing journey
+// should report in minutes, not hours.
+const MAX_JOURNEY_TIMEOUT = 60000;
+
+// The journey's `timeout`: how long each step may wait, in milliseconds.
+// Returns an error message, or undefined when it is omitted or well-formed.
+function validateJourneyTimeout({ timeout }) {
+  if (type.isUndefined(timeout)) {
+    return undefined;
+  }
+  if (!type.isInt(timeout) || timeout < 1 || timeout > MAX_JOURNEY_TIMEOUT) {
+    return `The journey "timeout" must be a whole number of milliseconds from 1 to ${MAX_JOURNEY_TIMEOUT}. Received ${JSON.stringify(
+      timeout
+    )}.`;
+  }
+  return undefined;
+}
+
+export { MAX_JOURNEY_TIMEOUT };
+export default validateJourneyTimeout;

package/lib/docs/validateJourneyTimeout.test.mjs

@@ -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 validateJourneyTimeout from './validateJourneyTimeout.js';
+
+test.each([undefined, 1, 5000, 60000])('validateJourneyTimeout accepts %j', (timeout) => {
+  expect(validateJourneyTimeout({ timeout })).toBeUndefined();
+});
+
+test.each([0, -1, 60001, 1500.5, '5000', null])('validateJourneyTimeout rejects %j', (timeout) => {
+  expect(validateJourneyTimeout({ timeout })).toEqual(
+    `The journey "timeout" must be a whole number of milliseconds from 1 to 60000. Received ${JSON.stringify(
+      timeout
+    )}.`
+  );
+});

package/lib/docs/validateRecordingParam.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.
+*/
+
+import { isTraceId, type } from '@lowdefy/helpers';
+
+// The journey route's optional `recording` param, { run, journey }: the test
+// run (a trace id) this journey records into, and the journey's name in it.
+// Returns an error message, or undefined when the param is absent or valid.
+function validateRecordingParam(recording) {
+  if (type.isNone(recording)) return undefined;
+  if (!type.isObject(recording)) {
+    return `The "recording" param must be an object { run, journey }. Received ${JSON.stringify(
+      recording
+    )}.`;
+  }
+  if (!isTraceId(recording.run)) {
+    return `The "recording.run" param must be a trace id like "20261003T151200Z-p0d4rm". Received ${JSON.stringify(
+      recording.run
+    )}.`;
+  }
+  if (!type.isNone(recording.journey) && !type.isString(recording.journey)) {
+    return `The "recording.journey" param must be a string or null. Received ${JSON.stringify(
+      recording.journey
+    )}.`;
+  }
+  return undefined;
+}
+
+export default validateRecordingParam;

package/lib/docs/validateStateSelection.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 { type } from '@lowdefy/helpers';
+
+// A journey's `state` option: true, false, or an array of state paths.
+// Returns an error message, or undefined when it is valid or not given.
+function validateStateSelection({ state }) {
+  if (type.isUndefined(state) || type.isBoolean(state)) {
+    return undefined;
+  }
+  if (type.isArray(state) && state.every((path) => type.isString(path) && path !== '')) {
+    return undefined;
+  }
+  return `The "state" option must be true, false or an array of state paths such as ["form.name"]. Received ${JSON.stringify(
+    state
+  )}.`;
+}
+
+export default validateStateSelection;

package/lib/docs/validateStateSelection.test.mjs

@@ -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 validateStateSelection from './validateStateSelection.js';
+
+test.each([undefined, true, false, [], ['form.name', 'rows']])(
+  'validateStateSelection accepts %j',
+  (state) => {
+    expect(validateStateSelection({ state })).toBeUndefined();
+  }
+);
+
+test.each(['all', null, 1, [''], ['a', 2], { path: 'a' }])(
+  'validateStateSelection rejects %j',
+  (state) => {
+    expect(validateStateSelection({ state })).toMatch(
+      /^The "state" option must be true, false or an array of state paths/
+    );
+  }
+);

package/lib/docs/validateViewport.js

@@ -0,0 +1,51 @@
+/*
+  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';
+
+const COLOR_SCHEMES = ['light', 'dark'];
+
+// Wide enough for a 4K screen. Chromium renders far larger viewports only
+// slowly, and fails some of them after tying up the browser for many seconds;
+// a full-page screenshot, not a tall viewport, is the way to see a long page.
+const MAX_VIEWPORT_SIZE = 4096;
+
+function isViewportSize(value) {
+  return type.isInt(value) && value > 0 && value <= MAX_VIEWPORT_SIZE;
+}
+
+// Checks the viewport a headless page is opened with: width and height in CSS
+// pixels, and the colour scheme the page's `prefers-color-scheme` reports.
+// Returns an error message, or undefined when every given option is valid.
+function validateViewport({ width, height, colorScheme }) {
+  if (!type.isUndefined(width) && !isViewportSize(width)) {
+    return `Viewport width must be a positive integer of at most ${MAX_VIEWPORT_SIZE} (CSS pixels). Received ${JSON.stringify(
+      width
+    )}.`;
+  }
+  if (!type.isUndefined(height) && !isViewportSize(height)) {
+    return `Viewport height must be a positive integer of at most ${MAX_VIEWPORT_SIZE} (CSS pixels). Received ${JSON.stringify(
+      height
+    )}.`;
+  }
+  if (!type.isUndefined(colorScheme) && !COLOR_SCHEMES.includes(colorScheme)) {
+    return `Color scheme must be "light" or "dark". Received ${JSON.stringify(colorScheme)}.`;
+  }
+  return undefined;
+}
+
+export { COLOR_SCHEMES, MAX_VIEWPORT_SIZE };
+export default validateViewport;

package/lib/docs/validateViewport.test.mjs

@@ -0,0 +1,54 @@
+/*
+  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 validateViewport from './validateViewport.js';
+
+test('validateViewport accepts no options and every valid option', () => {
+  expect(validateViewport({})).toBeUndefined();
+  expect(validateViewport({ width: 390, height: 844, colorScheme: 'dark' })).toBeUndefined();
+  expect(validateViewport({ colorScheme: 'light' })).toBeUndefined();
+  expect(validateViewport({ width: 4096, height: 4096 })).toBeUndefined();
+});
+
+test.each([
+  [
+    { width: 0 },
+    'Viewport width must be a positive integer of at most 4096 (CSS pixels). Received 0.',
+  ],
+  [
+    { width: 390.5 },
+    'Viewport width must be a positive integer of at most 4096 (CSS pixels). Received 390.5.',
+  ],
+  [
+    { height: -1 },
+    'Viewport height must be a positive integer of at most 4096 (CSS pixels). Received -1.',
+  ],
+  [
+    { height: '800' },
+    'Viewport height must be a positive integer of at most 4096 (CSS pixels). Received "800".',
+  ],
+  [
+    { width: 40000 },
+    'Viewport width must be a positive integer of at most 4096 (CSS pixels). Received 40000.',
+  ],
+  [
+    { height: 4097 },
+    'Viewport height must be a positive integer of at most 4096 (CSS pixels). Received 4097.',
+  ],
+  [{ colorScheme: 'dim' }, 'Color scheme must be "light" or "dark". Received "dim".'],
+])('validateViewport rejects %j', (options, message) => {
+  expect(validateViewport(options)).toEqual(message);
+});