@lowdefy/server-dev 0.0.0-experimental-20261016121021 → 0.0.0-experimental-20261019053059

package/client/recorder/createPairingBuffer.test.mjs

@@ -18,11 +18,12 @@
 */
 
 import { jest } from '@jest/globals';
+import createPairingBuffer, { HOLD_MS } from '@lowdefy/client-core/recorder/createPairingBuffer.js';
+import createPasswordRedactor from '@lowdefy/client-core/recorder/createPasswordRedactor.js';
 // Only the validator: the package index loads undici, which needs Node globals jsdom lacks.
 import validateTraceRecord from '@lowdefy/node-utils/journeyTrace/validateTraceRecord.js';
 
-import createPairingBuffer, { HOLD_MS } from './createPairingBuffer.js';
-import createPasswordRedactor from './createPasswordRedactor.js';
+import isPasswordElement from './isPasswordElement.js';
 
 const START = Date.parse('2026-10-03T14:00:00.000Z');
 const SESSION = '20261003T140000Z-k3x9qa';
@@ -114,7 +115,7 @@ beforeEach(() => {
     getSession: () => SESSION,
     getRoles: () => ['support'],
     getBuild: () => build,
-    redactor: createPasswordRedactor(),
+    redactor: createPasswordRedactor({ isPassword: isPasswordElement }),
   });
   build = BUILD_A;
   document.body.innerHTML = `

package/client/recorder/createRecorder.js

@@ -14,12 +14,16 @@
   limitations under the License.
 */
 
-import createPairingBuffer from './createPairingBuffer.js';
-import createPasswordRedactor from './createPasswordRedactor.js';
-import createRecordBatcher from './createRecordBatcher.js';
-import createRecordingSession from './createRecordingSession.js';
+import {
+  createPairingBuffer,
+  createPasswordRedactor,
+  createRecordBatcher,
+  createRecordingSession,
+  sendRecords,
+} from '@lowdefy/client-core';
+
+import isPasswordElement from './isPasswordElement.js';
 import keyChord from './keyChord.js';
-import sendRecords from './sendRecords.js';
 
 // Dev tools draw their own UI over the app; clicks on it are not the app.
 const IGNORED_ROOTS = '[data-lowdefy-feedback]';
@@ -67,7 +71,7 @@ function createRecorder({ basePath, lowdefy, recording, window, getTrace }) {
     getSession: () => session.getId(),
     getRoles: () => lowdefy.user?.roles ?? [],
     getBuild: () => lowdefy._devBuildId ?? null,
-    redactor: createPasswordRedactor(),
+    redactor: createPasswordRedactor({ isPassword: isPasswordElement }),
   });
   let pageId = null;
   // A pageview waits here until the page it shows is on screen, because only

package/client/recorder/isPasswordElement.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 { journeyTargetSelectors } from '@lowdefy/helpers';
+
+const { blockWrapperPrefix } = journeyTargetSelectors;
+
+function isPasswordInput(element) {
+  return (
+    typeof element?.tagName === 'string' &&
+    element.tagName.toLowerCase() === 'input' &&
+    element.type === 'password'
+  );
+}
+
+// Whether an interaction's element belongs to a password block: the element,
+// or its block's `<blockId>_input` element, is an `<input type="password">`.
+// The visibility toggle turns the input into `type="text"`, so the block's own
+// input is checked too, which a click on the toggle reaches.
+function isPasswordElement(element) {
+  if (isPasswordInput(element)) return true;
+  const wrapper = element?.closest?.(`[id^="${blockWrapperPrefix}"]`);
+  if (!wrapper) return false;
+  const blockId = wrapper.id.slice(blockWrapperPrefix.length);
+  return isPasswordInput(element.ownerDocument?.getElementById(`${blockId}_input`));
+}
+
+export default isPasswordElement;

package/lib/build/mobileConfig.js

@@ -0,0 +1,26 @@
+/*
+  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.
+*/
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// {} for an app without a mobile key.
+export default JSON.parse(
+  fs.readFileSync(path.join(process.cwd(), 'build/mobile/config.json'), 'utf8')
+);

package/lib/configTree/runConfigTreeBuild.mjs

@@ -55,13 +55,14 @@ async function runConfigTreeBuild({
   await prepareScratchServer({ devDirectory, serverDirectory: directories.server });
   let result;
   try {
-    const [customTypesMap, customMessagesMap] = await Promise.all([
+    const [{ customTypesMap, customTypesMapMobile }, customMessagesMap] = await Promise.all([
       createCustomPluginTypesMap({ directories, logger }),
       createCustomPluginMessagesMap({ directories, logger }),
     ]);
     await build({
       customMessagesMap,
       customTypesMap,
+      customTypesMapMobile,
       directories,
       logger,
       refResolver,

package/lib/configTree/runConfigTreeBuild.skipPluginChecks.test.mjs

@@ -29,7 +29,7 @@ jest.unstable_mockModule('./prepareScratchServer.mjs', () => ({
   default: jest.fn().mockResolvedValue(),
 }));
 jest.unstable_mockModule('../../manager/utils/createCustomPluginTypesMap.mjs', () => ({
-  default: jest.fn().mockResolvedValue({}),
+  default: jest.fn().mockResolvedValue({ customTypesMap: {}, customTypesMapMobile: {} }),
 }));
 jest.unstable_mockModule('../../manager/utils/createCustomPluginMessagesMap.mjs', () => ({
   default: jest.fn().mockResolvedValue({}),

package/lib/docs/createDocsMcpServer.js

@@ -20,6 +20,7 @@ import { validateJourneyUser } from '@lowdefy/node-utils';
 
 import checkpointToMocks from './checkpointToMocks.js';
 import createConfigCheckpoint from './createConfigCheckpoint.js';
+import deviceAction from './device/deviceAction.js';
 import { subscribe as subscribeToDevEvents } from './devEventBus.js';
 import evalOperator from './evalOperator.js';
 import findConfig from './findConfig.js';
@@ -47,6 +48,7 @@ import runEndpoint from './runEndpoint.js';
 import runJourney from './runJourney.js';
 import runJourneyAsUsers from './runJourneyAsUsers.js';
 import selectExercised from './selectExercised.js';
+import runDeviceJourney from './device/runDeviceJourney.js';
 import runRequest from './runRequest.js';
 import snapshotState from './snapshotState.js';
 import { listStateCheckpoints } from './checkpointStore.js';
@@ -54,6 +56,7 @@ import createLogger from '../server/log/createLogger.js';
 import lowdefyConfig from '../build/config.js';
 import devToolDefinitions, { INSTRUCTIONS } from './devToolDefinitions.js';
 import scaffoldPage from './scaffoldPage.js';
+import screenshotDevice from './device/screenshotDevice.js';
 import screenshotPage from './screenshotPage.js';
 import searchDocs from './searchDocs.js';
 import searchIcons from './searchIcons.js';
@@ -82,6 +85,67 @@ function notFoundResult(message) {
   return { content: [{ type: 'text', text: message }], isError: true };
 }
 
+// A screenshot result (screenshotPage, or screenshotDevice for a phone) as MCP
+// content. The final capture shows the page where the steps (or the failing
+// step) left it; the images of `screenshot` steps follow it in step order, named
+// in the JSON. A phone's capture also says how it was taken.
+function imageResult(result) {
+  if (result.error) {
+    return notFoundResult(result.error);
+  }
+  const image = { type: 'image', data: result.data, mimeType: result.mimeType };
+  const fromDevice = !type.isUndefined(result.device);
+  if (!fromDevice && !result.failure && result.screenshots.length === 0) {
+    return { content: [image] };
+  }
+  const summary = { passed: !result.failure, failure: result.failure };
+  if (fromDevice) {
+    summary.device = result.device;
+    summary.capture = result.capture;
+    if (!type.isUndefined(result.note)) {
+      summary.note = result.note;
+    }
+  }
+  if (result.screenshots.length > 0) {
+    summary.screenshots = result.screenshots.map(({ name }) => ({ name }));
+  }
+  return {
+    content: [
+      { type: 'text', text: JSON.stringify(summary, null, 2) },
+      image,
+      ...result.screenshots.map(({ data, mimeType }) => ({ type: 'image', data, mimeType })),
+    ],
+  };
+}
+
+// A journey result's PNGs travel as image content blocks (the shape
+// lowdefy_screenshot_page returns) so an MCP client renders them; the JSON keeps
+// only their names.
+function journeyResult({ summary, screenshots }) {
+  return {
+    content: [
+      { type: 'text', text: JSON.stringify(summary, null, 2) },
+      ...screenshots.map(({ data, mimeType }) => ({ type: 'image', data, mimeType })),
+    ],
+  };
+}
+
+// The params a tool takes for the headless browser mean nothing on a phone:
+// named back to the agent rather than silently dropped.
+function deviceParamsError({ tool, params, names }) {
+  const given = names.filter((name) => !type.isNone(params[name]));
+  if (given.length === 0) {
+    return null;
+  }
+  return notFoundResult(
+    `${tool} with device acts on the phone as it is: ${given.join(', ')} ${
+      given.length === 1 ? 'applies' : 'apply'
+    } to the headless browser only. Leave ${
+      given.length === 1 ? 'it' : 'them'
+    } out, or leave device out.`
+  );
+}
+
 function createDocsMcpServer({ origin, honoContext, version } = {}) {
   const server = new McpServer(
     { name: 'lowdefy', version },
@@ -130,8 +194,26 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
     });
   }
 
-  registerDevTool('lowdefy_inspect_state', async ({ pageId, pathParams, source, user, data }) => {
-    const result = await inspectState({ origin, pageId, pathParams, source, user, data });
+  registerDevTool(
+    'lowdefy_inspect_state',
+    async ({ pageId, pathParams, source, user, data, device }) => {
+      const result = await inspectState({ origin, pageId, pathParams, source, user, data, device });
+      if (result.error) {
+        return notFoundResult(result.error);
+      }
+      return textResult(result);
+    }
+  );
+
+  registerDevTool('lowdefy_device', async ({ action, platform, device, inject }) => {
+    const result = await deviceAction({
+      action,
+      platform,
+      device,
+      inject,
+      origin,
+      log: (message) => logger.info({ event: 'lowdefy_device' }, message),
+    });
     if (result.error) {
       return notFoundResult(result.error);
     }
@@ -184,7 +266,7 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
 
   registerDevTool(
     'lowdefy_snapshot_state',
-    async ({ pageId, pathParams, name, notes, source, overwrite }) => {
+    async ({ pageId, pathParams, name, notes, source, overwrite, device }) => {
       const result = await snapshotState({
         origin,
         pageId,
@@ -193,6 +275,7 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
         notes,
         source,
         overwrite,
+        device,
       });
       if (result.error) {
         return notFoundResult(result.error);
@@ -201,8 +284,8 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
     }
   );
 
-  registerDevTool('lowdefy_load_state', async ({ name, mode, user, data }) => {
-    const result = await loadState({ origin, name, mode, user, data });
+  registerDevTool('lowdefy_load_state', async ({ name, mode, user, data, device }) => {
+    const result = await loadState({ origin, name, mode, user, data, device });
     if (result.error) {
       return notFoundResult(result.error);
     }
@@ -272,7 +355,41 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
       width,
       height,
       colorScheme,
+      device,
     }) => {
+      if (!type.isNone(device)) {
+        const refused = deviceParamsError({
+          tool: 'lowdefy_screenshot_page',
+          params: {
+            urlQuery,
+            fullPage,
+            clip,
+            scrollX,
+            scrollY,
+            width,
+            height,
+            colorScheme,
+            user,
+            data,
+          },
+          names: [
+            'urlQuery',
+            'fullPage',
+            'clip',
+            'scrollX',
+            'scrollY',
+            'width',
+            'height',
+            'colorScheme',
+            'user',
+            'data',
+          ],
+        });
+        if (refused !== null) {
+          return refused;
+        }
+        return imageResult(await screenshotDevice({ device, pageId, pathParams, steps }));
+      }
       if (!origin) {
         return notFoundResult('Screenshot unavailable: server origin unknown for this transport.');
       }
@@ -292,33 +409,50 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
         height,
         colorScheme,
       });
-      if (result.error) {
-        return notFoundResult(result.error);
-      }
-      const image = { type: 'image', data: result.data, mimeType: result.mimeType };
-      if (!result.failure && result.screenshots.length === 0) {
-        return { content: [image] };
-      }
-      // The final capture shows the page where the steps (or the failing step)
-      // left it; the images of `screenshot` steps follow it in step order, named
-      // in the JSON.
-      const summary = { passed: !result.failure, failure: result.failure };
-      if (result.screenshots.length > 0) {
-        summary.screenshots = result.screenshots.map(({ name }) => ({ name }));
-      }
-      return {
-        content: [
-          { type: 'text', text: JSON.stringify(summary, null, 2) },
-          image,
-          ...result.screenshots.map(({ data, mimeType }) => ({ type: 'image', data, mimeType })),
-        ],
-      };
+      return imageResult(result);
     }
   );
 
   registerDevTool(
     'lowdefy_run_journey',
-    async ({ pageId, pathParams, steps, user, urlQuery, state, timeout, data, exercised }) => {
+    async ({
+      pageId,
+      pathParams,
+      steps,
+      user,
+      urlQuery,
+      state,
+      timeout,
+      data,
+      exercised,
+      device,
+    }) => {
+      if (!type.isNone(device)) {
+        const refused = deviceParamsError({
+          tool: 'lowdefy_run_journey',
+          params: { urlQuery, user, data, exercised },
+          names: ['urlQuery', 'user', 'data', 'exercised'],
+        });
+        if (refused !== null) {
+          return refused;
+        }
+        const result = await runDeviceJourney({
+          device,
+          pageId,
+          pathParams,
+          steps,
+          stepTimeout: timeout,
+          state,
+        });
+        if (result.error) {
+          return notFoundResult(result.error);
+        }
+        const { screenshots, ...rest } = result;
+        return journeyResult({
+          summary: { ...rest, screenshots: screenshots.map(({ name }) => ({ name })) },
+          screenshots,
+        });
+      }
       if (!origin) {
         return notFoundResult('Journey unavailable: server origin unknown for this transport.');
       }
@@ -374,20 +508,13 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
       if (result.error) {
         return notFoundResult(result.error);
       }
-      // The PNGs travel as image content blocks (the shape lowdefy_screenshot_page
-      // returns) so an MCP client renders them; the JSON keeps only their names.
       const { screenshots, exercised: resultExercised, ...rest } = result;
       const summary = {
         ...rest,
         ...selectExercised({ exercised: resultExercised, selection: exercised }),
         screenshots: screenshots.map(({ name }) => ({ name })),
       };
-      return {
-        content: [
-          { type: 'text', text: JSON.stringify(summary, null, 2) },
-          ...screenshots.map(({ data, mimeType }) => ({ type: 'image', data, mimeType })),
-        ],
-      };
+      return journeyResult({ summary, screenshots });
     }
   );
 
@@ -401,7 +528,9 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
 
   registerDevTool('lowdefy_overview', () => textResult(getOverview()));
 
-  registerDevTool('lowdefy_list_types', ({ kind }) => textResult(listTypes({ kind })));
+  registerDevTool('lowdefy_list_types', ({ kind, target }) =>
+    textResult(listTypes({ kind, target }))
+  );
 
   registerDevTool('lowdefy_list_plugins', () => textResult(listPlugins()));
 

package/lib/docs/createDocsMcpServer.test.mjs

@@ -46,6 +46,7 @@ const { default: createDocsMcpServer, subscribeMcpServerToDevEvents } = await im
   './createDocsMcpServer.js'
 );
 const { publish } = await import('./devEventBus.js');
+const { default: createFakePhoneTab, VIEW_PNG } = await import('./device/createFakePhoneTab.mjs');
 
 const EXPECTED_TOOLS = [
   'lowdefy_overview',
@@ -77,6 +78,7 @@ const EXPECTED_TOOLS = [
   'lowdefy_list_state_checkpoints',
   'lowdefy_checkpoint_to_mocks',
   'lowdefy_journey_session',
+  'lowdefy_device',
 ];
 
 async function connectClient() {
@@ -779,3 +781,157 @@ test('MCP tools/call lowdefy_journey_session lists dev sessions and prints one a
     fs.rmSync(configDirectory, { recursive: true, force: true });
   }
 });
+
+test('MCP the device tool adds one tool to the 29 the dev server had', async () => {
+  const client = await connectClient();
+  const { tools } = await client.listTools();
+  expect(tools).toHaveLength(30);
+  const device = tools.find((tool) => tool.name === 'lowdefy_device');
+  expect(device.inputSchema.properties.action.enum).toEqual(['list', 'start', 'inject']);
+  expect(device.inputSchema.properties.inject.properties.kind.enum).toEqual([
+    'scan',
+    'photo',
+    'nfc',
+    'transcript',
+    'location',
+    'permission',
+    'network',
+    'push',
+    'clear',
+  ]);
+  expect(device.inputSchema.required).toEqual(['action']);
+  await client.close();
+});
+
+test('MCP tools that can act on a phone advertise an optional device parameter', async () => {
+  const client = await connectClient();
+  const { tools } = await client.listTools();
+  [
+    'lowdefy_screenshot_page',
+    'lowdefy_run_journey',
+    'lowdefy_inspect_state',
+    'lowdefy_snapshot_state',
+    'lowdefy_load_state',
+  ].forEach((name) => {
+    const tool = tools.find((candidate) => candidate.name === name);
+    expect(tool.inputSchema.properties.device.type).toEqual('string');
+    expect(tool.inputSchema.required ?? []).not.toContain('device');
+  });
+  const listTypesTool = tools.find((tool) => tool.name === 'lowdefy_list_types');
+  expect(listTypesTool.inputSchema.properties.target.enum).toEqual(['web', 'mobile']);
+  await client.close();
+});
+
+test('MCP lowdefy_screenshot_page with device captures the phone, not the headless browser', async () => {
+  const phone = createFakePhoneTab({
+    id: 'mcp-phone',
+    device: { shell: '7.1.0', platform: 'ios', app: 'com.lowdefy.dev', paired: true },
+    page: { pageId: 'ticket', pathParams: {}, instanceKey: 'page:ticket' },
+  });
+  const client = await connectClient();
+  const result = await client.callTool({
+    name: 'lowdefy_screenshot_page',
+    arguments: { pageId: 'ticket', device: 'mcp-phone', steps: [{ click: 'save' }] },
+  });
+  expect(mockScreenshotPage).not.toHaveBeenCalled();
+  expect(phone.requests.map(({ event, data }) => [event, data.step])).toEqual([
+    ['step-request', { click: 'save' }],
+    ['step-request', { screenshot: null }],
+  ]);
+  const summary = JSON.parse(result.content[0].text);
+  expect(summary).toMatchObject({ passed: true, device: 'mcp-phone', capture: 'view' });
+  expect(result.content[1]).toEqual({ type: 'image', data: VIEW_PNG, mimeType: 'image/png' });
+  phone.close();
+  await client.close();
+});
+
+test('MCP lowdefy_screenshot_page with device refuses the headless-only params', async () => {
+  const client = await connectClient();
+  const result = await client.callTool({
+    name: 'lowdefy_screenshot_page',
+    arguments: { pageId: 'ticket', device: 'mcp-phone', width: 390, user: 'member' },
+  });
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toContain('width, user apply to the headless browser only');
+  await client.close();
+});
+
+test('MCP lowdefy_run_journey with device runs on the phone and returns the journey shape', async () => {
+  const phone = createFakePhoneTab({
+    id: 'mcp-phone',
+    device: { shell: '7.1.0', platform: 'android', app: 'com.lowdefy.dev', paired: true },
+    page: { pageId: 'ticket', pathParams: {}, instanceKey: 'page:ticket' },
+  });
+  const client = await connectClient();
+  const result = await client.callTool({
+    name: 'lowdefy_run_journey',
+    arguments: {
+      pageId: 'ticket',
+      device: 'mcp-phone',
+      steps: [
+        { fill: { blockId: 'title', value: 'Leak' } },
+        { screenshot: 'filled' },
+        { expect: { state: { path: 'title', equals: 'Leak' } } },
+      ],
+    },
+  });
+  expect(mockRunJourney).not.toHaveBeenCalled();
+  const summary = JSON.parse(result.content[0].text);
+  expect(summary).toMatchObject({
+    pageId: 'ticket',
+    device: 'mcp-phone',
+    passed: true,
+    state: { title: 'Leak' },
+    screenshots: [{ name: 'filled' }],
+  });
+  expect(result.content[1]).toEqual({ type: 'image', data: VIEW_PNG, mimeType: 'image/png' });
+  phone.close();
+  await client.close();
+});
+
+test('MCP lowdefy_inspect_state reads a phone by its tab id', async () => {
+  const phone = createFakePhoneTab({
+    id: 'mcp-phone',
+    device: { shell: '7.1.0', platform: 'ios', app: 'com.lowdefy.dev', paired: false },
+    page: { pageId: 'ticket', pathParams: {}, instanceKey: 'page:ticket' },
+    state: { title: 'Quarterly' },
+  });
+  const client = await connectClient();
+  const result = await client.callTool({
+    name: 'lowdefy_inspect_state',
+    arguments: { pageId: 'ticket', device: 'mcp-phone', source: 'tab' },
+  });
+  expect(JSON.parse(result.content[0].text)).toMatchObject({
+    source: 'tab',
+    device: 'mcp-phone',
+    state: { title: 'Quarterly' },
+  });
+  phone.close();
+  await client.close();
+});
+
+test('MCP lowdefy_device inject forwards the injection to the phone', async () => {
+  const phone = createFakePhoneTab({
+    id: 'mcp-phone',
+    device: { shell: '7.1.0', platform: 'android', app: 'com.lowdefy.dev', paired: true },
+  });
+  const client = await connectClient();
+  const result = await client.callTool({
+    name: 'lowdefy_device',
+    arguments: {
+      action: 'inject',
+      device: 'mcp-phone',
+      inject: { kind: 'scan', value: { data: 'JOB-42' } },
+    },
+  });
+  expect(phone.requests.map(({ event, data }) => [event, data.inject])).toEqual([
+    ['inject', { kind: 'scan', value: { data: 'JOB-42' } }],
+  ]);
+  expect(JSON.parse(result.content[0].text)).toEqual({
+    device: 'mcp-phone',
+    kind: 'scan',
+    app: { ok: true, kind: 'scan' },
+  });
+  phone.close();
+  await client.close();
+});