@lowdefy/shell 3.23.2 → 7.2.0

package/src/dev/connect/QrScanner.js

@@ -0,0 +1,89 @@
+/*
+  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 React, { useRef } from 'react';
+import { Modal, Pressable, StyleSheet, Text, View } from 'react-native';
+import { CameraView, useCameraPermissions } from 'expo-camera';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+import devStyles from '../devStyles.js';
+
+const styles = StyleSheet.create({
+  camera: { flex: 1 },
+  footer: { padding: 24, gap: 12, backgroundColor: '#ffffff' },
+});
+
+/**
+ * Scans the QR code `lowdefy dev --lan` prints, with expo-camera. onScanned gets the code's text
+ * once; the caller reads it as a link.
+ *
+ * @param {Object} props
+ * @param {boolean} props.visible
+ * @param {(text: string) => void} props.onScanned
+ * @param {() => void} props.onClose
+ */
+function QrScanner({ onClose, onScanned, visible }) {
+  const [permission, requestPermission] = useCameraPermissions();
+  const scanned = useRef(false);
+  const insets = useSafeAreaInsets();
+  if (!visible) {
+    scanned.current = false;
+  }
+  const granted = permission?.granted === true;
+  return (
+    <Modal animationType="slide" onRequestClose={onClose} visible={visible}>
+      <View style={{ flex: 1, paddingTop: insets.top }} testID="dev-qr-scanner">
+        {granted ? (
+          <CameraView
+            barcodeScannerSettings={{ barcodeTypes: ['qr'] }}
+            onBarcodeScanned={({ data }) => {
+              if (scanned.current) return;
+              scanned.current = true;
+              onScanned(data);
+            }}
+            style={styles.camera}
+          />
+        ) : (
+          <View style={devStyles.screen}>
+            <Text style={devStyles.hint}>
+              Lowdefy Dev uses the camera only to read the code lowdefy dev prints.
+            </Text>
+            <Pressable
+              accessibilityRole="button"
+              onPress={requestPermission}
+              style={devStyles.button}
+              testID="dev-qr-allow"
+            >
+              <Text style={devStyles.buttonText}>Allow the camera</Text>
+            </Pressable>
+          </View>
+        )}
+        <View style={[styles.footer, { paddingBottom: insets.bottom + 24 }]}>
+          <Pressable
+            accessibilityRole="button"
+            onPress={onClose}
+            style={devStyles.secondaryButton}
+            testID="dev-qr-close"
+          >
+            <Text style={devStyles.secondaryButtonText}>Close</Text>
+          </Pressable>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+export default QrScanner;

package/src/dev/connection/createDevShellConfig.js

@@ -0,0 +1,47 @@
+/*
+  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 createDevTransport from './createDevTransport.js';
+
+/**
+ * Lowdefy Dev's shell config for one dev server: its one app is that server, named by its host,
+ * and its calls carry the server's pairing token (shell.transport, read by createShellApp). Each
+ * server is its own app, so its cache, session token and storage are kept apart from another's.
+ *
+ * @param {Object} params
+ * @param {Object} params.server `{ url, host, pair }`.
+ * @param {Object} params.shell The shell config (getShellConfig).
+ * @param {Function} [params.fetch] The Fetch API.
+ * @param {Function} [params.WebSocket] The WebSocket class.
+ */
+function createDevShellConfig({
+  fetch = globalThis.fetch,
+  server,
+  shell,
+  WebSocket = globalThis.WebSocket,
+}) {
+  return {
+    ...shell,
+    app: {
+      id: `dev-${server.host.replace(/[^A-Za-z0-9._-]/g, '_')}`,
+      name: server.host,
+      urls: { [shell.environment]: server.url },
+    },
+    transport: createDevTransport({ fetch, pair: server.pair, WebSocket }),
+  };
+}
+
+export default createDevShellConfig;

package/src/dev/connection/createDevTransport.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.
+*/
+
+const PAIR_HEADER = 'x-lowdefy-pair';
+
+/**
+ * How calls reach a dev server: `{ fetch, WebSocket, wrapFetch }`, sending the pairing token of
+ * `lowdefy dev --lan` as x-lowdefy-pair on every request and websocket upgrade. wrapFetch adds it
+ * to another Fetch API (the dev-tab client's streaming one). Without a token (a simulator, a USB
+ * phone) they are the platform's own.
+ *
+ * @param {Object} params
+ * @param {Function} params.fetch The Fetch API.
+ * @param {Function} params.WebSocket The WebSocket class (React Native's takes headers).
+ * @param {string|null} params.pair The pairing token.
+ */
+function createDevTransport({ fetch, pair, WebSocket }) {
+  if (pair === null) {
+    return { fetch, WebSocket, wrapFetch: (baseFetch) => baseFetch };
+  }
+  function wrapFetch(baseFetch) {
+    return function pairedFetch(url, init = {}) {
+      return baseFetch(url, { ...init, headers: { ...init.headers, [PAIR_HEADER]: pair } });
+    };
+  }
+  class PairedWebSocket extends WebSocket {
+    constructor(url, protocols, options = {}) {
+      super(url, protocols, {
+        ...options,
+        headers: { ...options.headers, [PAIR_HEADER]: pair },
+      });
+    }
+  }
+  return { fetch: wrapFetch(fetch), WebSocket: PairedWebSocket, wrapFetch };
+}
+
+export { PAIR_HEADER };
+export default createDevTransport;

package/src/dev/connection/createDevTransport.test.js

@@ -0,0 +1,87 @@
+/*
+  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';
+
+import createDevShellConfig from './createDevShellConfig.js';
+import createDevTransport from './createDevTransport.js';
+import createMemoryStore from '../../host/createMemoryStore.js';
+import createServerList from './createServerList.js';
+
+const shell = { id: 'lowdefy-dev', environment: 'dev', scheme: 'lowdefy-dev', version: '7.0.0' };
+
+class FakeWebSocket {
+  constructor(url, protocols, options) {
+    this.args = { url, protocols, options };
+  }
+}
+
+test('a paired server gets the pairing token on every call and websocket upgrade', async () => {
+  const fetch = jest.fn(async () => ({ status: 200 }));
+  const transport = createDevTransport({ fetch, pair: 'k3x9q', WebSocket: FakeWebSocket });
+  await transport.fetch('http://192.168.1.20:3000/api/mobile/root', { headers: { a: '1' } });
+  expect(fetch.mock.calls[0][1].headers).toEqual({ a: '1', 'x-lowdefy-pair': 'k3x9q' });
+  const socket = new transport.WebSocket('ws://192.168.1.20:3000/api/websocket', undefined, {
+    headers: { Authorization: 'Bearer t' },
+  });
+  expect(socket).toBeInstanceOf(FakeWebSocket);
+  expect(socket.args.options.headers).toEqual({
+    Authorization: 'Bearer t',
+    'x-lowdefy-pair': 'k3x9q',
+  });
+  const streamFetch = jest.fn(async () => ({ status: 200 }));
+  await transport.wrapFetch(streamFetch)('http://192.168.1.20:3000/api/reload');
+  expect(streamFetch.mock.calls[0][1].headers).toEqual({ 'x-lowdefy-pair': 'k3x9q' });
+});
+
+test('a server on this device gets the platform fetch and WebSocket, with no token', () => {
+  const fetch = jest.fn();
+  const transport = createDevTransport({ fetch, pair: null, WebSocket: FakeWebSocket });
+  expect(transport.fetch).toBe(fetch);
+  expect(transport.WebSocket).toBe(FakeWebSocket);
+});
+
+test('each dev server is its own app, at its url', () => {
+  const config = createDevShellConfig({
+    fetch: jest.fn(),
+    server: { url: 'http://192.168.1.20:3000', host: '192.168.1.20:3000', pair: 'k3x9q' },
+    shell,
+    WebSocket: FakeWebSocket,
+  });
+  expect(config.app).toEqual({
+    id: 'dev-192.168.1.20_3000',
+    name: '192.168.1.20:3000',
+    urls: { dev: 'http://192.168.1.20:3000' },
+  });
+  expect(config).not.toHaveProperty('apps');
+  expect(config.version).toBe('7.0.0');
+});
+
+test('the last 5 servers are remembered, the last one first', () => {
+  const servers = createServerList({ kv: createMemoryStore() });
+  [1, 2, 3, 4, 5, 6].forEach((n) => {
+    servers.remember({ url: `http://10.0.0.${n}:3000`, host: `10.0.0.${n}:3000`, pair: null });
+  });
+  servers.remember({ url: 'http://10.0.0.4:3000', host: '10.0.0.4:3000', pair: 'p' });
+  expect(servers.list().map((server) => server.host)).toEqual([
+    '10.0.0.4:3000',
+    '10.0.0.6:3000',
+    '10.0.0.5:3000',
+    '10.0.0.3:3000',
+    '10.0.0.2:3000',
+  ]);
+  expect(servers.last()).toEqual({ url: 'http://10.0.0.4:3000', host: '10.0.0.4:3000', pair: 'p' });
+});

package/src/dev/connection/createServerList.js

@@ -0,0 +1,48 @@
+/*
+  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 SERVERS_KEY = 'lowdefy-dev:servers';
+const MAX_SERVERS = 5;
+
+/**
+ * The dev servers Lowdefy Dev connected to, the last one first: `[{ url, host, pair }]`, at most 5.
+ * The pairing token is kept with its server; it lasts as long as that `lowdefy dev` session.
+ *
+ * @param {Object} params
+ * @param {{ get, set }} params.kv The device store.
+ */
+function createServerList({ kv }) {
+  function list() {
+    const stored = JSON.parse(kv.get(SERVERS_KEY) ?? '[]');
+    return type.isArray(stored) ? stored : [];
+  }
+
+  function remember({ url, host, pair }) {
+    const servers = [
+      { url, host, pair: pair ?? null },
+      ...list().filter((server) => server.url !== url),
+    ].slice(0, MAX_SERVERS);
+    kv.set(SERVERS_KEY, JSON.stringify(servers));
+    return servers;
+  }
+
+  return { last: () => list()[0] ?? null, list, remember };
+}
+
+export { SERVERS_KEY };
+export default createServerList;

package/src/dev/connection/isLoopbackHost.js

@@ -0,0 +1,25 @@
+/*
+  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.
+*/
+
+// A host on this device: a simulator's localhost is the Mac's, and a USB Android phone's is the
+// computer's through adb reverse. Neither reaches a server on a network.
+function isLoopbackHost(host) {
+  const hostname = host.startsWith('[') ? host.slice(0, host.indexOf(']') + 1) : host.split(':')[0];
+  const name = hostname.toLowerCase();
+  return name === 'localhost' || name === '[::1]' || /^127\.\d+\.\d+\.\d+$/.test(name);
+}
+
+export default isLoopbackHost;

package/src/dev/connection/pairedShellApp.test.js

@@ -0,0 +1,104 @@
+/*
+  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';
+
+import createDevShellConfig from './createDevShellConfig.js';
+import createFakeServer, { header } from '../../test/createFakeServer.js';
+import createShellApp from '../../createShellApp.js';
+import { createPages, createRoot } from '../../test/fixtures.js';
+
+// createShellApp as the app runs it, over in-memory stores.
+jest.mock('expo-sqlite', () => ({ openDatabaseSync: () => ({}) }));
+jest.mock('../../cache/createSqliteCacheStore.js', () =>
+  jest.requireActual('../../test/createMemoryCacheStore.js')
+);
+jest.mock('../../host/createDeviceStore.js', () =>
+  jest.requireActual('../../host/createMemoryStore.js')
+);
+jest.mock('expo-secure-store', () =>
+  jest.requireActual('../../test/createFakeSecureStore.js').default()
+);
+jest.mock('expo-crypto', () => ({}));
+jest.mock('expo-web-browser', () => ({}));
+jest.mock('expo-local-authentication', () => ({}));
+jest.mock('expo-network', () => ({ addNetworkStateListener: () => ({ remove: () => undefined }) }));
+jest.mock('expo-router', () => ({ router: {} }));
+jest.mock('expo-clipboard', () => ({}));
+jest.mock('expo/fetch', () => ({
+  fetch: jest.fn(async () => ({ status: 200, headers: { get: () => null } })),
+}));
+
+class FakeWebSocket {
+  constructor(url, protocols, options) {
+    this.options = options;
+  }
+}
+
+const shell = {
+  id: 'lowdefy-dev',
+  environment: 'dev',
+  profile: 'dev',
+  scheme: 'lowdefy-dev',
+  version: '7.0.0',
+};
+
+test('every call of an app on a paired dev server carries the pairing token', async () => {
+  const server = createFakeServer({
+    root: createRoot(),
+    rootEtag: '"root-1"',
+    pages: createPages([['today', 'today', '"p-today-1"']]),
+  });
+  const devShell = createDevShellConfig({
+    fetch: server.fetch,
+    server: { url: 'http://192.168.1.20:3000', host: '192.168.1.20:3000', pair: 'k3x9q' },
+    shell,
+    WebSocket: FakeWebSocket,
+  });
+  const { auth, host, session } = await createShellApp({
+    onSignedOut: jest.fn(),
+    shell: devShell,
+  });
+  await session.sync();
+  await host.fetch('http://192.168.1.20:3000/api/endpoints/save', { method: 'POST' });
+
+  const calls = server.fetch.mock.calls;
+  expect(calls.map(([url]) => new URL(url).pathname)).toEqual([
+    '/api/mobile/root',
+    '/api/user',
+    '/api/page/today',
+    '/api/page/jobs',
+    '/api/page/jobs/%7Bjob_id%7D',
+    '/api/endpoints/save',
+  ]);
+  calls.forEach(([url, init]) => {
+    expect(url.startsWith('http://192.168.1.20:3000/')).toBe(true);
+    expect(header(init, 'x-lowdefy-pair')).toBe('k3x9q');
+    expect(header(init, 'x-lowdefy-shell')).toBe('7.0.0');
+  });
+  // A block's streamed call (AgentChat's chat stream) goes through expo/fetch, sent the same way.
+  const { fetch: expoFetch } = jest.requireMock('expo/fetch');
+  await host.streamFetch('http://192.168.1.20:3000/api/agent/chat/assistant', { method: 'POST' });
+  expect(server.fetch).toHaveBeenCalledTimes(calls.length);
+  const [[streamUrl, streamInit]] = expoFetch.mock.calls;
+  expect(streamUrl).toBe('http://192.168.1.20:3000/api/agent/chat/assistant');
+  expect(streamInit.credentials).toBe('omit');
+  expect(header(streamInit, 'x-lowdefy-pair')).toBe('k3x9q');
+  expect(header(streamInit, 'x-lowdefy-shell')).toBe('7.0.0');
+  const socket = new host.WebSocket('ws://192.168.1.20:3000/api/websocket');
+  expect(socket.options.headers).toEqual({ 'x-lowdefy-pair': 'k3x9q' });
+  auth.dispose();
+});

package/src/dev/connection/parseDevLink.js

@@ -0,0 +1,66 @@
+/*
+  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 parseQuery from './parseQuery.js';
+import parseServerUrl from './parseServerUrl.js';
+
+/**
+ * What a Lowdefy Dev link asks for, or null for any other URL (the app's own deep links):
+ * - `lowdefy-dev://connect?url=<server>&pair=<token>`: `{ kind: 'connect', url, host, pair }`,
+ *   as `lowdefy dev --lan` prints it in its QR code, and `--ios`/`--android` open it (no pair).
+ * - `lowdefy-dev://menu`: `{ kind: 'menu' }`, the shake menu, for a simulator that cannot shake.
+ * A connect link without a usable url is `{ kind: 'invalid', reason }`.
+ *
+ * @param {Object} params
+ * @param {string} params.link The URL the app was opened with.
+ * @param {string} params.scheme The shell's URL scheme (lowdefy-dev).
+ */
+function parseDevLink({ link, scheme }) {
+  if (!type.isString(link) || !type.isString(scheme)) {
+    return null;
+  }
+  const prefix = `${scheme.toLowerCase()}://`;
+  if (!link.toLowerCase().startsWith(prefix)) {
+    return null;
+  }
+  const rest = link.slice(prefix.length);
+  const queryIndex = rest.indexOf('?');
+  const target = (queryIndex === -1 ? rest : rest.slice(0, queryIndex)).replace(/\/+$/, '');
+  const query = parseQuery(queryIndex === -1 ? '' : rest.slice(queryIndex + 1).split('#')[0]);
+  if (target === 'menu') {
+    return { kind: 'menu' };
+  }
+  if (target !== 'connect') {
+    return null;
+  }
+  const server = parseServerUrl(query.url);
+  if (server === null) {
+    return {
+      kind: 'invalid',
+      reason: `The link has no dev server url. Received ${JSON.stringify(query.url ?? null)}.`,
+    };
+  }
+  return {
+    kind: 'connect',
+    url: server.url,
+    host: server.host,
+    pair: type.isString(query.pair) && query.pair.length > 0 ? query.pair : null,
+  };
+}
+
+export default parseDevLink;

package/src/dev/connection/parseDevLink.test.js

@@ -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 isLoopbackHost from './isLoopbackHost.js';
+import parseDevLink from './parseDevLink.js';
+import parseServerInput from './parseServerInput.js';
+
+const scheme = 'lowdefy-dev';
+
+test('a connect link from lowdefy dev --lan gives the server and its pairing token', () => {
+  expect(
+    parseDevLink({
+      link: 'lowdefy-dev://connect?url=http%3A%2F%2F192.168.1.20%3A3000%2F&pair=k3x9q',
+      scheme,
+    })
+  ).toEqual({
+    kind: 'connect',
+    url: 'http://192.168.1.20:3000',
+    host: '192.168.1.20:3000',
+    pair: 'k3x9q',
+  });
+});
+
+test('a connect link from lowdefy dev --ios has no pairing token', () => {
+  expect(
+    parseDevLink({ link: 'lowdefy-dev://connect?url=http%3A%2F%2Flocalhost%3A3000', scheme })
+  ).toEqual({ kind: 'connect', url: 'http://localhost:3000', host: 'localhost:3000', pair: null });
+});
+
+test('a connect link whose url carries userinfo is invalid, so it never passes for loopback', () => {
+  [
+    'http://localhost:3000@evil.example',
+    'http://[::1]:1@evil.example',
+    'http://localhost\\@evil.example',
+  ].forEach((url) => {
+    const result = parseDevLink({
+      link: `lowdefy-dev://connect?url=${encodeURIComponent(url)}`,
+      scheme,
+    });
+    expect(result.kind).toBe('invalid');
+  });
+});
+
+test('a menu link opens the dev menu', () => {
+  expect(parseDevLink({ link: 'lowdefy-dev://menu', scheme })).toEqual({ kind: 'menu' });
+});
+
+test('a connect link without a server url is invalid', () => {
+  expect(parseDevLink({ link: 'lowdefy-dev://connect?url=ftp%3A%2F%2Fx', scheme })).toEqual({
+    kind: 'invalid',
+    reason: 'The link has no dev server url. Received "ftp://x".',
+  });
+});
+
+test('links that are not Lowdefy Dev links are left to the router', () => {
+  expect(parseDevLink({ link: 'lowdefy-dev://tickets/7', scheme })).toBeNull();
+  expect(parseDevLink({ link: 'field://connect?url=http%3A%2F%2Fx', scheme })).toBeNull();
+  expect(parseDevLink({ link: '/tickets/7', scheme })).toBeNull();
+});
+
+test('the connect screen reads a typed address or a pasted link', () => {
+  expect(parseServerInput({ input: ' 192.168.1.20:3000 ', scheme })).toEqual({
+    url: 'http://192.168.1.20:3000',
+    host: '192.168.1.20:3000',
+    pair: null,
+  });
+  expect(
+    parseServerInput({
+      input: 'lowdefy-dev://connect?url=http%3A%2F%2F192.168.1.20%3A3000&pair=k3x9q',
+      scheme,
+    })
+  ).toEqual({ url: 'http://192.168.1.20:3000', host: '192.168.1.20:3000', pair: 'k3x9q' });
+  expect(parseServerInput({ input: 'not a server', scheme }).error).toMatch(/Enter the address/);
+});
+
+test.each([
+  ['localhost:3000', true],
+  ['127.0.0.1:3000', true],
+  ['[::1]:3000', true],
+  ['192.168.1.20:3000', false],
+  ['localhost.example.com', false],
+])('isLoopbackHost(%s) is %s', (host, expected) => {
+  expect(isLoopbackHost(host)).toBe(expected);
+});

package/src/dev/connection/parseQuery.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.
+*/
+
+// A link's query string as an object of decoded values. Read by hand: the link arrives before any
+// URL polyfill can be relied on, and it holds only a url and a pairing token.
+function parseQuery(query) {
+  const values = {};
+  (query ?? '')
+    .split('&')
+    .filter((part) => part.length > 0)
+    .forEach((part) => {
+      const index = part.indexOf('=');
+      const name = index === -1 ? part : part.slice(0, index);
+      const value = index === -1 ? '' : part.slice(index + 1);
+      values[decodeURIComponent(name)] = decodeURIComponent(value.replace(/\+/g, ' '));
+    });
+  return values;
+}
+
+export default parseQuery;