@lowdefy/shell 3.23.2 → 7.2.0

package/src/dev/inject/createOfflineFetch.test.js

@@ -0,0 +1,68 @@
+/*
+  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 '../connection/createDevShellConfig.js';
+import createDeviceInjections from './createDeviceInjections.js';
+import createFakeNetwork from '../../test/createFakeNetwork.js';
+import createNetworkStatus from '../../host/createNetworkStatus.js';
+import createOfflineFetch from './createOfflineFetch.js';
+
+const shell = { environment: 'dev', version: '7.4.0' };
+
+function setup({ pair = null } = {}) {
+  const injections = createDeviceInjections({
+    networkStatus: createNetworkStatus({ network: createFakeNetwork() }),
+  });
+  const fetch = jest.fn(async () => ({ ok: true }));
+  const devShell = createDevShellConfig({
+    fetch: createOfflineFetch({ fetch, isOffline: injections.isOffline }),
+    server: { url: 'http://192.168.1.20:3000', host: '192.168.1.20:3000', pair },
+    shell,
+    WebSocket: class {},
+  });
+  return { devShell, fetch, injections };
+}
+
+test("offline, the app's every fetch fails as React Native's fetch fails with no network", async () => {
+  const { devShell, fetch, injections } = setup({ pair: 'token' });
+  await devShell.transport.fetch('http://192.168.1.20:3000/api/page/home');
+  expect(fetch).toHaveBeenCalledTimes(1);
+
+  injections.inject({ kind: 'network', value: 'offline' });
+  const failed = devShell.transport.fetch('http://192.168.1.20:3000/api/request/home/load');
+  await expect(failed).rejects.toThrow(TypeError);
+  await expect(failed).rejects.toThrow('Network request failed');
+  expect(fetch).toHaveBeenCalledTimes(1);
+
+  injections.inject({ kind: 'network', value: 'online' });
+  await devShell.transport.fetch('http://192.168.1.20:3000/api/page/home');
+  expect(fetch).toHaveBeenCalledTimes(2);
+});
+
+test('offline, the dev-tab client still reaches the dev server, so an agent can go back online', async () => {
+  const { devShell, injections } = setup({ pair: 'token' });
+  injections.inject({ kind: 'network', value: 'offline' });
+  const tabFetch = jest.fn(async () => ({ ok: true }));
+  await devShell.transport.wrapFetch(tabFetch)('http://192.168.1.20:3000/api/dev-inspect', {
+    method: 'POST',
+  });
+  expect(tabFetch).toHaveBeenCalledWith('http://192.168.1.20:3000/api/dev-inspect', {
+    method: 'POST',
+    headers: { 'x-lowdefy-pair': 'token' },
+  });
+});

package/src/dev/inject/injectPush.js

@@ -0,0 +1,60 @@
+/*
+  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 * as Notifications from 'expo-notifications';
+import { type } from '@lowdefy/helpers';
+
+import { getCurrentApp } from '../../native/currentApp.js';
+import handleNotificationResponse from '../../notifications/handleNotificationResponse.js';
+
+/**
+ * Lowdefy Dev's push injection: shows `{ title, body, data, categoryId }` as a notification now,
+ * as a push arriving with the app open would (the app's onNotification fires). With `open: true`
+ * it is then tapped (data.path opens, onNotificationAction fires with actionId default); with
+ * `actionId` (and `text` for a reply) that button is pressed instead, as the person would.
+ *
+ * @param {Object} value
+ */
+async function injectPush(value) {
+  if (!type.isObject(value) || !(type.isString(value.title) || type.isString(value.body))) {
+    throw new Error(
+      `A push injection needs { title, body, data?, categoryId?, open?, actionId?, text? }. Received ${JSON.stringify(
+        value
+      )}.`
+    );
+  }
+  const content = {
+    title: value.title,
+    body: value.body,
+    data: value.data ?? {},
+    categoryIdentifier: value.categoryId,
+  };
+  const id = await Notifications.scheduleNotificationAsync({ content, trigger: null });
+  if (value.open !== true && !type.isString(value.actionId)) {
+    return { ok: true, kind: 'push', id };
+  }
+  await handleNotificationResponse({
+    app: await getCurrentApp(),
+    response: {
+      actionIdentifier: value.actionId ?? Notifications.DEFAULT_ACTION_IDENTIFIER,
+      notification: { request: { identifier: id, content } },
+      userText: value.text,
+    },
+  });
+  return { ok: true, kind: 'push', id, responded: value.actionId ?? 'default' };
+}
+
+export default injectPush;

package/src/dev/inject/injectShare.js

@@ -0,0 +1,55 @@
+/*
+  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 { getCurrentApp } from '../../native/currentApp.js';
+
+/**
+ * Lowdefy Dev's share injection: as if `{ text?, url?, files? }` were shared into the app from
+ * another app, so mobile.share.pageId opens with it and onShare fires. Files are
+ * [{ uri, name, mimeType, size? }].
+ *
+ * @param {Object} value
+ */
+async function injectShare(value) {
+  if (
+    !type.isObject(value) ||
+    ![value.text, value.url, value.files].some((item) => !type.isNone(item))
+  ) {
+    throw new Error(
+      `A share injection needs { text?, url?, files? }. Received ${JSON.stringify(value)}.`
+    );
+  }
+  const payloads = [
+    ...(type.isString(value.text) ? [{ shareType: 'text', value: value.text }] : []),
+    ...(type.isString(value.url) ? [{ shareType: 'url', value: value.url }] : []),
+    ...(value.files ?? []).map((file) => ({
+      shareType: 'file',
+      value: file.uri,
+      contentUri: file.uri,
+      contentType: 'file',
+      contentMimeType: file.mimeType ?? null,
+      originalName: file.name ?? null,
+      contentSize: file.size ?? null,
+    })),
+  ];
+  const app = await getCurrentApp();
+  await app.receiveShare({ payloads });
+  return { ok: true, kind: 'share' };
+}
+
+export default injectShare;

package/src/dev/inject/withInjectedDevice.js

@@ -0,0 +1,98 @@
+/*
+  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 { FEATURE_SHELLS } from '@lowdefy/blocks-native/device';
+
+// An injected photo as a picked file: the PickImage shape, with its content inline.
+function toPhotoFile(photo) {
+  const mimeType = photo.mimeType ?? 'image/jpeg';
+  return {
+    name: photo.name ?? 'injected-photo.jpg',
+    mimeType,
+    size: Math.round((photo.base64.length * 3) / 4),
+    uri: `data:${mimeType};base64,${photo.base64}`,
+    width: photo.width ?? null,
+    height: photo.height ?? null,
+    base64: photo.base64,
+  };
+}
+
+// A feature method that answers an injected result first, and asks the shell's own feature
+// otherwise. Lowdefy Dev carries the field profile, so NFC has no feature of its own there: an
+// injection is then the only answer, and a read with none throws as a shell without NFC does.
+function answerFirst({ action, feature, method, read, real, toResult }) {
+  return async (params) => {
+    const value = read();
+    if (value !== undefined) {
+      return toResult(value);
+    }
+    if (real === undefined) {
+      throw new Error(
+        `${action} needs a shell that carries ${feature} (${FEATURE_SHELLS[feature]}). In Lowdefy Dev, inject one.`
+      );
+    }
+    return real[method](params);
+  };
+}
+
+/**
+ * Lowdefy Dev's device: the shell's features, with the next scan, photo and NFC read answered by
+ * what an agent or journey injected (src/device/injected.js) before the camera or the tag reader.
+ *
+ * @param {Object} params
+ * @param {Object} params.features The shell's device features (src/device/device.js).
+ * @param {(name: string) => any} params.read injected().
+ */
+function withInjectedDevice({ features, read }) {
+  const photo = (method, feature, action) =>
+    answerFirst({
+      action,
+      feature,
+      method,
+      read: () => read('photo'),
+      real: features[feature],
+      toResult: (value) => [toPhotoFile(value)],
+    });
+  return {
+    ...features,
+    camera: {
+      ...features.camera,
+      scanCode: answerFirst({
+        action: 'ScanCode',
+        feature: 'camera',
+        method: 'scanCode',
+        read: () => read('scan'),
+        real: features.camera,
+        toResult: (value) => ({ data: value.data, type: value.type ?? 'qr' }),
+      }),
+      takePhoto: photo('takePhoto', 'camera', 'TakePhoto'),
+    },
+    photos: { ...features.photos, pick: photo('pick', 'photos', 'PickImage') },
+    nfc: {
+      ...features.nfc,
+      read: answerFirst({
+        action: 'ReadNfc',
+        feature: 'nfc',
+        method: 'read',
+        read: () => read('nfc'),
+        real: features.nfc,
+        toResult: (value) => value,
+      }),
+    },
+  };
+}
+
+export default withInjectedDevice;

package/src/dev/menu/BlockGallery.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 React from 'react';
+import { Text, View } from 'react-native';
+
+import devStyles from '../devStyles.js';
+
+// The shake menu's block gallery: every native block the shell carries, shown with its examples.
+// The native block set fills it in; until then it says so.
+function BlockGallery() {
+  return (
+    <View style={devStyles.screen} testID="dev-block-gallery">
+      <Text style={devStyles.heading}>Block gallery</Text>
+      <Text style={devStyles.hint}>The gallery of native blocks is not in this build yet.</Text>
+    </View>
+  );
+}
+
+export default BlockGallery;

package/src/dev/menu/DevMenu.js

@@ -0,0 +1,121 @@
+/*
+  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, { useState, useSyncExternalStore } from 'react';
+import { Modal, Pressable, ScrollView, Text, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+import BlockGallery from './BlockGallery.js';
+import devStyles from '../devStyles.js';
+
+function MenuItem({ hint, label, onPress, testID }) {
+  return (
+    <Pressable accessibilityRole="button" onPress={onPress} style={devStyles.row} testID={testID}>
+      <Text style={devStyles.rowText}>{label}</Text>
+      {hint ? <Text style={devStyles.hint}>{hint}</Text> : null}
+    </Pressable>
+  );
+}
+
+function LogList({ logs }) {
+  const entries = useSyncExternalStore(logs.subscribe, logs.entries);
+  if (entries.length === 0) {
+    return <Text style={devStyles.hint}>Nothing logged yet.</Text>;
+  }
+  return entries.map((entry, index) => (
+    <Text key={index} style={devStyles.mono}>
+      {`${entry.at.toISOString().slice(11, 19)} ${entry.level} ${entry.message}`}
+    </Text>
+  ));
+}
+
+/**
+ * The shake menu: reload, switch server, clear data, the shell's logs, the block gallery and the
+ * shell's version.
+ *
+ * @param {Object} props
+ * @param {boolean} props.visible
+ * @param {() => void} props.onClose
+ * @param {() => void} props.onReload
+ * @param {() => void} props.onSwitchServer
+ * @param {() => void} props.onClearData
+ * @param {Object} props.logs The log buffer (createLogBuffer).
+ * @param {string|null} props.server The host of the server Lowdefy Dev is connected to.
+ * @param {Object} props.shell The shell config: name and version.
+ */
+function DevMenu({ logs, onClearData, onClose, onReload, onSwitchServer, server, shell, visible }) {
+  const insets = useSafeAreaInsets();
+  const [panel, setPanel] = useState('menu');
+  function close() {
+    setPanel('menu');
+    onClose();
+  }
+  function act(action) {
+    close();
+    action();
+  }
+  return (
+    <Modal animationType="slide" onRequestClose={close} transparent visible={visible}>
+      <View style={devStyles.backdrop}>
+        <ScrollView
+          contentContainerStyle={[devStyles.sheet, { paddingBottom: insets.bottom + 24 }]}
+          style={{ maxHeight: '85%', flexGrow: 0 }}
+          testID="dev-menu"
+        >
+          {panel === 'menu' ? (
+            <>
+              <Text style={devStyles.sheetTitle}>{shell.name}</Text>
+              <Text style={devStyles.hint} testID="dev-menu-version">
+                {`Shell ${shell.version}${server ? ` · ${server}` : ''}`}
+              </Text>
+              <MenuItem label="Reload" onPress={() => act(onReload)} testID="dev-menu-reload" />
+              <MenuItem
+                hint={server ?? undefined}
+                label="Switch server"
+                onPress={() => act(onSwitchServer)}
+                testID="dev-menu-switch"
+              />
+              <MenuItem
+                hint="Signs out and removes this server's cached pages and storage"
+                label="Clear data"
+                onPress={() => act(onClearData)}
+                testID="dev-menu-clear"
+              />
+              <MenuItem label="Show logs" onPress={() => setPanel('logs')} testID="dev-menu-logs" />
+              <MenuItem
+                label="Block gallery"
+                onPress={() => setPanel('gallery')}
+                testID="dev-menu-gallery"
+              />
+            </>
+          ) : null}
+          {panel === 'logs' ? <LogList logs={logs} /> : null}
+          {panel === 'gallery' ? <BlockGallery /> : null}
+          <Pressable
+            accessibilityRole="button"
+            onPress={panel === 'menu' ? close : () => setPanel('menu')}
+            style={devStyles.secondaryButton}
+            testID="dev-menu-close"
+          >
+            <Text style={devStyles.secondaryButtonText}>{panel === 'menu' ? 'Close' : 'Back'}</Text>
+          </Pressable>
+        </ScrollView>
+      </View>
+    </Modal>
+  );
+}
+
+export default DevMenu;

package/src/dev/menu/createLogBuffer.js

@@ -0,0 +1,83 @@
+/*
+  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 LEVELS = ['log', 'info', 'warn', 'error'];
+
+function formatPart(part) {
+  if (part instanceof Error) {
+    return part.message;
+  }
+  if (typeof part === 'string') {
+    return part;
+  }
+  try {
+    return JSON.stringify(part);
+  } catch (error) {
+    return String(part);
+  }
+}
+
+/**
+ * The shell's recent console output, for the shake menu's "Show logs": the last `limit` lines,
+ * `{ at, level, message }`, oldest first. install() copies every console call into it (the console
+ * still prints); it returns the uninstall function.
+ *
+ * @param {Object} params
+ * @param {Object} params.console The console to follow.
+ * @param {number} [params.limit]
+ */
+function createLogBuffer({ console, limit = 200 }) {
+  // Replaced, never changed, on each line: a snapshot for useSyncExternalStore.
+  let entries = [];
+  const listeners = new Set();
+
+  function add({ level, parts }) {
+    const entry = { at: new Date(), level, message: parts.map(formatPart).join(' ') };
+    entries = [...entries, entry].slice(-limit);
+    // A component may log while React renders another: the log view hears of it afterwards.
+    setTimeout(() => listeners.forEach((listener) => listener()), 0);
+  }
+
+  function install() {
+    const originals = {};
+    LEVELS.forEach((level) => {
+      originals[level] = console[level];
+      console[level] = (...parts) => {
+        add({ level, parts });
+        originals[level].apply(console, parts);
+      };
+    });
+    return () => {
+      LEVELS.forEach((level) => {
+        console[level] = originals[level];
+      });
+    };
+  }
+
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  return {
+    add: (level, ...parts) => add({ level, parts }),
+    entries: () => entries,
+    install,
+    subscribe,
+  };
+}
+
+export default createLogBuffer;

package/src/dev/menu/watchShake.js

@@ -0,0 +1,52 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+const UPDATE_MS = 100;
+// In g: a phone at rest reads about 1.
+const SHAKE_FORCE = 1.8;
+const JOLTS = 3;
+const WINDOW_MS = 800;
+const QUIET_MS = 1500;
+
+/**
+ * Calls onShake when the phone is shaken: 3 jolts over 1.8 g within 0.8 s, then not again for 1.5 s.
+ * Returns the function that stops listening.
+ *
+ * @param {Object} params
+ * @param {Object} params.accelerometer expo-sensors' Accelerometer.
+ * @param {() => void} params.onShake
+ * @param {() => number} [params.now]
+ */
+function watchShake({ accelerometer, now = Date.now, onShake }) {
+  let jolts = [];
+  let quietUntil = 0;
+  accelerometer.setUpdateInterval(UPDATE_MS);
+  const subscription = accelerometer.addListener(({ x, y, z }) => {
+    const time = now();
+    if (time < quietUntil || Math.sqrt(x * x + y * y + z * z) < SHAKE_FORCE) {
+      return;
+    }
+    jolts = [...jolts.filter((at) => time - at <= WINDOW_MS), time];
+    if (jolts.length >= JOLTS) {
+      jolts = [];
+      quietUntil = time + QUIET_MS;
+      onShake();
+    }
+  });
+  return () => subscription.remove();
+}
+
+export default watchShake;

package/src/dev/menu/watchShake.test.js

@@ -0,0 +1,61 @@
+/*
+  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 watchShake from './watchShake.js';
+
+function setup() {
+  let listener = null;
+  let time = 0;
+  const onShake = jest.fn();
+  const stop = watchShake({
+    accelerometer: {
+      setUpdateInterval: jest.fn(),
+      addListener: (fn) => {
+        listener = fn;
+        return { remove: jest.fn() };
+      },
+    },
+    now: () => time,
+    onShake,
+  });
+  function read(g, at) {
+    time = at;
+    listener({ x: g, y: 0, z: 0 });
+  }
+  return { onShake, read, stop };
+}
+
+test('three jolts within 0.8 s open the menu once, then it rests for 1.5 s', () => {
+  const { onShake, read } = setup();
+  read(2.5, 0);
+  read(2.5, 200);
+  expect(onShake).not.toHaveBeenCalled();
+  read(2.5, 400);
+  expect(onShake).toHaveBeenCalledTimes(1);
+  [500, 600, 700].forEach((at) => read(2.5, at));
+  expect(onShake).toHaveBeenCalledTimes(1);
+  [2000, 2100, 2200].forEach((at) => read(2.5, at));
+  expect(onShake).toHaveBeenCalledTimes(2);
+});
+
+test('a phone at rest, or jolts spread out, do not open the menu', () => {
+  const { onShake, read } = setup();
+  [0, 100, 200, 300].forEach((at) => read(1, at));
+  [1000, 2000, 3000].forEach((at) => read(2.5, at));
+  expect(onShake).not.toHaveBeenCalled();
+});