@lowdefy/server-dev 5.6.0 → 6.0.0

package/lib/docs/runRequest.js

@@ -0,0 +1,141 @@
+/*
+  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 { callRequest } from '@lowdefy/api';
+
+import isWriteRequestsAllowed from './isWriteRequestsAllowed.js';
+import readBuildArtifact from './readBuildArtifact.js';
+
+// Cap the serialized response so a large request result can't blow out an
+// agent's context window.
+const MAX_RESPONSE_CHARS = 100_000;
+
+function getRequestType({ pageId, requestId }) {
+  // The request's `type` is stripped from build/pages/<pageId>.json by the
+  // build (packages/build/src/build/full/writeRequests.js deletes
+  // type/connectionId/properties/auth after writing the per-request file),
+  // so it must be read from the dedicated per-request artifact instead —
+  // the same file @lowdefy/api's getRequestConfig reads via readConfigFile.
+  const requestConfig = readBuildArtifact({
+    name: `pages/${pageId}/requests/${requestId}.json`,
+    deserialize: true,
+  });
+  return requestConfig?.type ?? null;
+}
+
+function truncateResponse(result) {
+  const json = JSON.stringify(result.response);
+  if (json.length <= MAX_RESPONSE_CHARS) {
+    return result;
+  }
+  return {
+    ...result,
+    response: json.slice(0, MAX_RESPONSE_CHARS),
+    truncated: true,
+    note: `Response truncated to ${MAX_RESPONSE_CHARS} characters (original serialized size: ${json.length} characters).`,
+  };
+}
+
+// Executes a page request the same way POST /api/request/<pageId>/<requestId>
+// does (src/routes/request.js), but gated for agent use: requests whose type
+// is not declared read-only (checkWrite: false in requestSchemas.json meta)
+// are refused unless the app opts in via lowdefy.yaml's
+// cli.agentTools.allowWriteRequests. Never throws — errors and refusals are
+// returned as data so an agent can reason about them.
+async function runRequest({ pageId, requestId, payload = {}, honoContext }) {
+  if (type.isUndefined(pageId) || !type.isString(pageId)) {
+    throw new Error(`run_request requires a "pageId" string. Received ${JSON.stringify(pageId)}.`);
+  }
+  if (type.isUndefined(requestId) || !type.isString(requestId)) {
+    throw new Error(
+      `run_request requires a "requestId" string. Received ${JSON.stringify(requestId)}.`
+    );
+  }
+
+  let requestType = getRequestType({ pageId, requestId });
+  if (type.isNone(requestType)) {
+    // In dev, page content (including per-request artifacts) is built JIT on
+    // first page request — trigger the same build GET /api/page/* runs so a
+    // freshly added request is found without the page ever being opened.
+    try {
+      const { default: buildPageIfNeeded } = await import('../server/jitPageBuilder.js');
+      const path = await import('node:path');
+      await buildPageIfNeeded({
+        pageId,
+        buildDirectory: path.join(process.cwd(), 'build'),
+        configDirectory: process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd(),
+      });
+      requestType = getRequestType({ pageId, requestId });
+    } catch {
+      // JIT build failure surfaces through lowdefy_build_status — fall
+      // through to the not-found refusal below.
+    }
+  }
+  if (type.isNone(requestType)) {
+    return {
+      refused: true,
+      reason:
+        `Request "${requestId}" was not found on page "${pageId}". ` +
+        `See GET /lowdefy-docs/app-map for the pages and requests that exist.`,
+    };
+  }
+
+  const requestSchemas = readBuildArtifact({ name: 'plugins/requestSchemas.json' }) ?? {};
+  const meta = requestSchemas[requestType]?.meta ?? {};
+
+  if (meta.checkWrite !== false) {
+    const allowed = await isWriteRequestsAllowed();
+    if (!allowed) {
+      return {
+        refused: true,
+        reason:
+          meta.checkWrite === true
+            ? `Request type "${requestType}" performs writes (checkWrite: true) and agent write access is disabled.`
+            : `Request type "${requestType}" has no declared read/write meta, so it is treated as a write for safety.`,
+        howToEnable: 'Set cli.agentTools.allowWriteRequests: true in lowdefy.yaml (dev only).',
+      };
+    }
+  }
+
+  // Deferred import: createLowdefyContext statically imports build/plugins/*
+  // artifacts, which only exist in a running server directory — importing it
+  // at module load would break every consumer of this module (e.g. the MCP
+  // server) in environments without a full build.
+  const { default: createLowdefyContext } = await import('../server/createLowdefyContext.js');
+  const context = await createLowdefyContext({ c: honoContext });
+  context.logger.info({ event: 'agent_run_request', pageId, requestId });
+
+  try {
+    const result = await callRequest(context, {
+      blockId: undefined,
+      pageId,
+      payload,
+      requestId,
+    });
+    return { refused: false, ...truncateResponse(result) };
+  } catch (error) {
+    return {
+      refused: false,
+      error: {
+        name: error.name,
+        message: error.message,
+      },
+    };
+  }
+}
+
+export default runRequest;

package/lib/docs/saveAnnotatedScreenshot.js

@@ -0,0 +1,43 @@
+/*
+  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';
+
+const PNG_DATA_URL_PREFIX = 'data:image/png;base64,';
+
+// Saves a tab-captured annotated screenshot (PNG data URL POSTed with the
+// feedback batch) under the config dir's .lowdefy/annotations/ — the same
+// location and naming captureAnnotatedScreenshot.js uses, so formatFeedback's
+// screenshotPath contract is identical for both capture paths. Never throws —
+// returns { path } or { error }.
+function saveAnnotatedScreenshot({ dataUrl, fileName }) {
+  if (typeof dataUrl !== 'string' || !dataUrl.startsWith(PNG_DATA_URL_PREFIX)) {
+    return { error: 'Screenshot is not a PNG data URL.' };
+  }
+  try {
+    const buffer = Buffer.from(dataUrl.slice(PNG_DATA_URL_PREFIX.length), 'base64');
+    const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+    const dir = path.join(configDirectory, '.lowdefy', 'annotations');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, fileName), buffer);
+    return { path: path.join('.lowdefy', 'annotations', fileName) };
+  } catch (error) {
+    return { error: `Failed to save annotated screenshot: ${error.message}` };
+  }
+}
+
+export default saveAnnotatedScreenshot;

package/lib/docs/scaffoldPage.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 fs from 'fs';
+import path from 'path';
+import { type } from '@lowdefy/helpers';
+
+import readBuildArtifact from './readBuildArtifact.js';
+
+const pageIdPattern = /^[a-z0-9-_]+$/i;
+
+function buildPageYaml({ pageId, title }) {
+  const titleJson = JSON.stringify(title);
+  return `id: ${pageId}
+type: PageHeaderMenu
+properties:
+  title: ${titleJson}
+blocks:
+  - id: ${pageId}_title
+    type: Title
+    properties:
+      content: ${titleJson}
+`;
+}
+
+// Scaffolds a new page config file for an AI agent to wire up — it never edits lowdefy.yaml
+// itself, since that would risk destroying the user's comments and formatting.
+function scaffoldPage({ pageId, title }) {
+  if (type.isNone(pageId) || !pageIdPattern.test(pageId)) {
+    return {
+      error: `Invalid page id ${JSON.stringify(
+        pageId
+      )}. Page ids may only contain letters, numbers, "-" and "_".`,
+    };
+  }
+
+  const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+  const pageRelativePath = path.join('pages', `${pageId}.yaml`);
+  const pageFilePath = path.join(configDirectory, pageRelativePath);
+
+  if (fs.existsSync(pageFilePath)) {
+    return { error: `"${pageRelativePath}" already exists.` };
+  }
+
+  const pageRegistry = readBuildArtifact({ name: 'pageRegistry.json' }) ?? {};
+  if (Object.keys(pageRegistry).includes(pageId)) {
+    return {
+      error: `Page id "${pageId}" is already used by another page in the build (see build/pageRegistry.json). Choose a different id.`,
+    };
+  }
+
+  const pageTitle = title ?? pageId;
+  fs.mkdirSync(path.dirname(pageFilePath), { recursive: true });
+  fs.writeFileSync(pageFilePath, buildPageYaml({ pageId, title: pageTitle }));
+
+  return {
+    created: pageRelativePath,
+    next: `Add \`- _ref: ${pageRelativePath}\` under \`pages:\` in lowdefy.yaml (or the relevant pages file), then check lowdefy_build_status.`,
+  };
+}
+
+export default scaffoldPage;

package/lib/docs/scaffoldPage.test.mjs

@@ -0,0 +1,97 @@
+/*
+  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 'fs';
+import os from 'os';
+import path from 'path';
+
+import scaffoldPage from './scaffoldPage.js';
+
+let configDirectory;
+let previousConfigDirectory;
+let previousCwd;
+
+beforeEach(() => {
+  configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-scaffold-page-test-'));
+  previousConfigDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG;
+  process.env.LOWDEFY_DIRECTORY_CONFIG = configDirectory;
+  // readBuildArtifact.js (used to check pageRegistry.json) reads from process.cwd(), which is
+  // the same directory as LOWDEFY_DIRECTORY_CONFIG in a real dev server run.
+  previousCwd = process.cwd();
+  process.chdir(configDirectory);
+});
+
+afterEach(() => {
+  process.chdir(previousCwd);
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+  if (previousConfigDirectory === undefined) {
+    delete process.env.LOWDEFY_DIRECTORY_CONFIG;
+  } else {
+    process.env.LOWDEFY_DIRECTORY_CONFIG = previousConfigDirectory;
+  }
+});
+
+test('scaffoldPage writes a canonical page file and reports the next step', () => {
+  const result = scaffoldPage({ pageId: 'reports', title: 'Reports' });
+
+  expect(result).toEqual({
+    created: path.join('pages', 'reports.yaml'),
+    next: 'Add `- _ref: pages/reports.yaml` under `pages:` in lowdefy.yaml (or the relevant pages file), then check lowdefy_build_status.',
+  });
+
+  const written = fs.readFileSync(path.join(configDirectory, 'pages', 'reports.yaml'), 'utf8');
+  expect(written).toContain('id: reports');
+  expect(written).toContain('type: PageHeaderMenu');
+  expect(written).toContain('title: "Reports"');
+  expect(written).toContain('type: Title');
+  expect(written).toContain('content: "Reports"');
+});
+
+test('scaffoldPage defaults the title to the pageId when no title is given', () => {
+  scaffoldPage({ pageId: 'dashboard' });
+
+  const written = fs.readFileSync(path.join(configDirectory, 'pages', 'dashboard.yaml'), 'utf8');
+  expect(written).toContain('title: "dashboard"');
+});
+
+test('scaffoldPage refuses an invalid page id', () => {
+  const result = scaffoldPage({ pageId: 'has a space' });
+
+  expect(result.error).toContain('Invalid page id');
+  expect(fs.existsSync(path.join(configDirectory, 'pages', 'has a space.yaml'))).toBe(false);
+});
+
+test('scaffoldPage refuses when the page file already exists', () => {
+  fs.mkdirSync(path.join(configDirectory, 'pages'), { recursive: true });
+  fs.writeFileSync(path.join(configDirectory, 'pages', 'reports.yaml'), 'id: reports\n');
+
+  const result = scaffoldPage({ pageId: 'reports' });
+
+  expect(result.error).toEqual(`"${path.join('pages', 'reports.yaml')}" already exists.`);
+});
+
+test('scaffoldPage refuses when the pageId is already used in the build registry', () => {
+  fs.mkdirSync(path.join(configDirectory, 'build'), { recursive: true });
+  fs.writeFileSync(
+    path.join(configDirectory, 'build', 'pageRegistry.json'),
+    JSON.stringify({ reports: {} })
+  );
+
+  const result = scaffoldPage({ pageId: 'reports' });
+
+  expect(result.error).toContain('Page id "reports" is already used');
+  expect(fs.existsSync(path.join(configDirectory, 'pages', 'reports.yaml'))).toBe(false);
+});

package/lib/docs/screenshotPage.js

@@ -0,0 +1,110 @@
+/*
+  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 { getBrowser, openPage, buildPageUrl } from './getBrowser.js';
+
+// A feedback annotation's elementRect/shapes are captured in the developer's
+// live tab, viewport-relative at whatever scroll position they were at
+// (batch.viewport.scrollX/scrollY) — so to recapture the same region
+// headless, this scrolls to that same offset first, then converts the
+// viewport-relative clip to document coordinates by adding the scroll
+// offset back in. Mutually exclusive with fullPage: an explicit clip always
+// wins, since it targets a specific annotated region rather than the page.
+async function resolveClip({ page, clip, scrollX, scrollY }) {
+  if (type.isNone(clip)) {
+    return undefined;
+  }
+  const hasValidPosition = type.isNumber(clip.x) && type.isNumber(clip.y);
+  const hasPositiveDims =
+    type.isNumber(clip.width) && type.isNumber(clip.height) && clip.width > 0 && clip.height > 0;
+  if (!hasValidPosition || !hasPositiveDims) {
+    // Invalid clip — fall back to a normal viewport screenshot rather than
+    // failing the whole request over a bad clip rect.
+    return undefined;
+  }
+
+  await page.evaluate(({ x, y }) => window.scrollTo(x, y), { x: scrollX, y: scrollY });
+  // Let scroll-triggered rendering (sticky headers, lazy content) settle
+  // before clipping, mirroring the load-settle wait below.
+  await page.waitForTimeout(200);
+
+  return {
+    x: clip.x + scrollX,
+    y: clip.y + scrollY,
+    width: clip.width,
+    height: clip.height,
+  };
+}
+
+// screenshotPage lets an agent visually verify a page rendered by the
+// running dev server.
+async function screenshotPage({
+  origin,
+  pageId,
+  fullPage = false,
+  clip,
+  scrollX = 0,
+  scrollY = 0,
+  user,
+  width = 1280,
+  height = 800,
+  timeout = 15000,
+}) {
+  if (type.isNone(origin) || !type.isString(origin)) {
+    return {
+      error: `screenshotPage requires an "origin" string. Received ${JSON.stringify(origin)}.`,
+    };
+  }
+  if (type.isNone(pageId) || !type.isString(pageId)) {
+    return {
+      error: `screenshotPage requires a "pageId" string. Received ${JSON.stringify(pageId)}.`,
+    };
+  }
+
+  let browser;
+  try {
+    browser = await getBrowser();
+  } catch (error) {
+    return {
+      error: `No Chromium available. Run: npx playwright install chromium (${error.message})`,
+    };
+  }
+
+  const url = buildPageUrl({ origin, pageId });
+
+  let context;
+  try {
+    const opened = await openPage({ browser, origin, pageId, user, width, height, timeout });
+    context = opened.context;
+    // Let post-load rendering (fonts, transitions, client-side state) settle.
+    await opened.page.waitForTimeout(300);
+
+    const docClip = await resolveClip({ page: opened.page, clip, scrollX, scrollY });
+    const screenshotOptions = docClip ? { type: 'png', clip: docClip } : { type: 'png', fullPage };
+    const buffer = await opened.page.screenshot(screenshotOptions);
+    return { data: buffer.toString('base64'), mimeType: 'image/png' };
+  } catch (error) {
+    return { error: `Failed to screenshot "${url}": ${error.message}` };
+  } finally {
+    if (context) {
+      await context.close();
+    }
+  }
+}
+
+export default screenshotPage;

package/lib/docs/screenshotPage.test.mjs

@@ -0,0 +1,59 @@
+/*
+  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 'fs';
+import os from 'os';
+import path from 'path';
+import { jest } from '@jest/globals';
+
+// A real screenshot needs an installed browser, which jest can't rely on, so
+// this only covers the error paths: bad input, and chromium.launch failing
+// (the "no browser installed" case). chromium.launch is mocked so the real
+// browser flow is untouched everywhere else.
+jest.unstable_mockModule('playwright-core', () => ({
+  chromium: { launch: jest.fn().mockRejectedValue(new Error("Executable doesn't exist")) },
+}));
+
+// lib/build/config.js reads build/config.json from process.cwd() at import
+// time — chdir into a fixture that has one before screenshotPage.js (which
+// imports it) is loaded. Mirrors the pattern in docs.test.mjs.
+const originalCwd = process.cwd();
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-screenshot-test-'));
+fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
+fs.writeFileSync(path.join(fixtureDir, 'build', 'config.json'), JSON.stringify({ basePath: '' }));
+process.chdir(fixtureDir);
+
+const { default: screenshotPage } = await import('./screenshotPage.js');
+
+afterAll(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(fixtureDir, { recursive: true, force: true });
+});
+
+test('screenshotPage returns an error when origin is missing', async () => {
+  const result = await screenshotPage({ pageId: 'home' });
+  expect(result.error).toMatch(/requires an "origin" string/);
+});
+
+test('screenshotPage returns an error when pageId is missing', async () => {
+  const result = await screenshotPage({ origin: 'http://localhost:3001' });
+  expect(result.error).toMatch(/requires a "pageId" string/);
+});
+
+test('screenshotPage returns an actionable error when no browser is available', async () => {
+  const result = await screenshotPage({ origin: 'http://localhost:3001', pageId: 'home' });
+  expect(result.error).toMatch(/No Chromium available. Run: npx playwright install chromium/);
+});

package/lib/docs/screenshotPageClip.test.mjs

@@ -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 { jest } from '@jest/globals';
+
+// Covers the clip/scroll success path, which screenshotPage.test.mjs cannot
+// (it deliberately fails chromium.launch to test the "no browser" error
+// path). Mocking the whole ./getBrowser.js module — not just
+// playwright-core — means lib/build/config.js (which getBrowser.js reads at
+// import time) is never touched, so no fixture chdir is needed here.
+const mockScreenshot = jest.fn(async () => Buffer.from('fake-png'));
+const mockWaitForTimeout = jest.fn(async () => {});
+const mockEvaluate = jest.fn(async () => {});
+const mockPage = {
+  screenshot: mockScreenshot,
+  waitForTimeout: mockWaitForTimeout,
+  evaluate: mockEvaluate,
+};
+const mockContext = { close: jest.fn(async () => {}) };
+const mockOpenPage = jest.fn(async () => ({
+  context: mockContext,
+  page: mockPage,
+  url: 'http://localhost:3001/home',
+}));
+const mockGetBrowser = jest.fn(async () => ({}));
+
+jest.unstable_mockModule('./getBrowser.js', () => ({
+  getBrowser: mockGetBrowser,
+  openPage: mockOpenPage,
+  buildPageUrl: jest.fn(() => 'http://localhost:3001/home'),
+}));
+
+const { default: screenshotPage } = await import('./screenshotPage.js');
+
+test('screenshotPage with a valid clip scrolls to scrollX/scrollY and converts clip to document coordinates', async () => {
+  const result = await screenshotPage({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    clip: { x: 220, y: 480, width: 96, height: 40 },
+    scrollX: 10,
+    scrollY: 340,
+  });
+
+  expect(result.error).toBeUndefined();
+  expect(mockEvaluate).toHaveBeenCalledWith(expect.any(Function), { x: 10, y: 340 });
+  expect(mockScreenshot).toHaveBeenCalledWith({
+    type: 'png',
+    clip: { x: 230, y: 820, width: 96, height: 40 },
+  });
+});
+
+test('screenshotPage without a clip takes a normal fullPage/viewport screenshot and never scrolls', async () => {
+  const result = await screenshotPage({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    fullPage: true,
+  });
+
+  expect(result.error).toBeUndefined();
+  expect(mockEvaluate).not.toHaveBeenCalled();
+  expect(mockScreenshot).toHaveBeenCalledWith({ type: 'png', fullPage: true });
+});
+
+test('screenshotPage ignores a clip with non-positive dimensions and falls back to a viewport screenshot', async () => {
+  const result = await screenshotPage({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    clip: { x: 0, y: 0, width: 0, height: 40 },
+  });
+
+  expect(result.error).toBeUndefined();
+  expect(mockEvaluate).not.toHaveBeenCalled();
+  expect(mockScreenshot).toHaveBeenCalledWith({ type: 'png', fullPage: false });
+});
+
+test('screenshotPage clip takes priority over fullPage when both are provided', async () => {
+  const result = await screenshotPage({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    fullPage: true,
+    clip: { x: 1, y: 2, width: 3, height: 4 },
+  });
+
+  expect(result.error).toBeUndefined();
+  expect(mockScreenshot).toHaveBeenCalledWith({
+    type: 'png',
+    clip: { x: 1, y: 2, width: 3, height: 4 },
+  });
+});