@lowdefy/shell 0.0.0-experimental-20261019052246

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/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();
+});

package/src/dev/recorder/createNativeRecorder.js

@@ -0,0 +1,204 @@
+/*
+  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 {
+  createPairingBuffer,
+  createPasswordRedactor,
+  createRecordBatcher,
+  createRecordingSession,
+  sendRecords,
+} from '@lowdefy/client-core';
+import { describeBlock } from '@lowdefy/client-native';
+import { getTrace } from '@lowdefy/engine';
+import { type } from '@lowdefy/helpers';
+
+import getShownPage from '../tab/getShownPage.js';
+
+const PAGE_CHECK_MS = 500;
+
+// A TextInput of type password draws a secure field; its value is never recorded.
+function isPasswordBlock(block) {
+  return block?.eval?.properties?.type === 'password';
+}
+
+function findBlock({ blockId, lowdefy, page }) {
+  return (
+    lowdefy.contexts?.[page?.instanceKey]?._internal.RootSlots?.map?.[blockId] ??
+    lowdefy.appContext?._internal.RootSlots?.map?.[blockId] ??
+    null
+  );
+}
+
+function currentUrl(lowdefy) {
+  const { location } = lowdefy._internal.globals.window;
+  return `${location.pathname}${location.search}`;
+}
+
+// The device store as the sessionStorage the recording session keeps its id in, so a session lasts
+// across reloads and a restart of the app within 10 minutes.
+function createSessionStorage(kv) {
+  return {
+    getItem: (key) => kv.get(key) ?? null,
+    setItem: (key, value) => kv.set(key, value),
+  };
+}
+
+/**
+ * Lowdefy Dev's recorder: what a developer does on the phone, written as the web recorder writes
+ * it (server-dev client/recorder/createRecorder.js), so `lowdefy journeys session` and the
+ * journeys-from-dev skill read phone sessions as they read browser ones.
+ *
+ * - The engine trace's interactions (client-native reports presses and changes by block id) pair
+ *   with its completed events through the shared pairing buffer (@lowdefy/client-core).
+ * - A pageview is recorded when the page on screen changes, checked every 500 ms and before each
+ *   interaction and event.
+ * - Targets are block ids (client-native describeBlock). Password inputs are redacted.
+ * - Each record is labelled with the device (`ios` or `android`) and the shell's version, and
+ *   batches are posted to the dev server's /api/dev-recording.
+ * - A reload of the app makes a new lowdefy object: the recorder follows it.
+ *
+ * @param {Object} params
+ * @param {string} params.apiBase The dev server's URL.
+ * @param {string} params.device 'ios' or 'android'.
+ * @param {Function} params.fetch The Fetch API, with the pairing and shell headers.
+ * @param {() => string|null} params.getBuild The build of the root the shell holds.
+ * @param {() => Object|null} params.getLowdefy The open app's lowdefy object.
+ * @param {Object} params.kv The device store.
+ * @param {string} params.shellVersion
+ * @param {() => number} [params.now]
+ */
+function createNativeRecorder({
+  apiBase,
+  device,
+  fetch,
+  getBuild,
+  getLowdefy,
+  kv,
+  now = Date.now,
+  shellVersion,
+}) {
+  const session = createRecordingSession({ storage: createSessionStorage(kv), now });
+  const batcher = createRecordBatcher({
+    send: (records) => sendRecords({ basePath: apiBase, records, fetch }),
+  });
+  let lowdefy = null;
+  let detach = () => undefined;
+  let shown = null;
+  let timer = null;
+
+  const buffer = createPairingBuffer({
+    onRecord: (record) => batcher.add({ ...record, device, shell_version: shellVersion }),
+    now,
+    getSession: () => session.getId(),
+    getRoles: () => lowdefy?.user?.roles ?? [],
+    getBuild,
+    redactor: createPasswordRedactor({ isPassword: isPasswordBlock }),
+  });
+
+  // Records a pageview when the page instance on screen changed. `t` places it before the
+  // interaction or event that found the change, which happened on the new page.
+  function checkPage({ t } = {}) {
+    if (lowdefy === null) return;
+    const page = getShownPage(lowdefy);
+    if (page === null || page.instanceKey === shown?.instanceKey) return;
+    shown = page;
+    buffer.addInteraction({
+      t: t ?? now(),
+      kind: 'pageview',
+      pageId: page.pageId,
+      pathParams: page.pathParams,
+      url: currentUrl(lowdefy),
+    });
+  }
+
+  function onInteraction(interaction) {
+    try {
+      checkPage({ t: interaction.t - 1 });
+      const target = describeBlock({ blockId: interaction.blockId, lowdefy });
+      buffer.addInteraction({
+        t: interaction.t,
+        kind: interaction.kind,
+        element: findBlock({ blockId: interaction.blockId, lowdefy, page: shown }),
+        target,
+        pageId: target.page_id ?? shown?.pageId,
+        value: interaction.value,
+        key: interaction.key,
+      });
+    } catch (error) {
+      // Recording is best effort: it never gets in the app's way.
+    }
+  }
+
+  function onTrace(payload) {
+    try {
+      checkPage();
+      buffer.addEvent(payload, { urlAfter: currentUrl(lowdefy) });
+    } catch (error) {
+      // Recording is best effort.
+    }
+  }
+
+  function flush() {
+    try {
+      buffer.flushAll();
+      return batcher.flush();
+    } catch (error) {
+      return Promise.resolve();
+    }
+  }
+
+  // Follows the open app's lowdefy object, which a reload replaces.
+  function follow() {
+    const next = getLowdefy();
+    if (next === lowdefy) {
+      checkPage();
+      return;
+    }
+    detach();
+    flush();
+    lowdefy = next;
+    shown = null;
+    if (type.isNone(lowdefy)) {
+      lowdefy = null;
+      detach = () => undefined;
+      return;
+    }
+    const trace = getTrace(lowdefy);
+    const unsubscribeEvents = trace.subscribe(onTrace, { state: true });
+    const unsubscribeInteractions = trace.subscribeInteractions(onInteraction);
+    detach = () => {
+      unsubscribeEvents();
+      unsubscribeInteractions();
+    };
+    checkPage();
+  }
+
+  function start() {
+    follow();
+    timer = setInterval(follow, PAGE_CHECK_MS);
+  }
+
+  function stop() {
+    clearInterval(timer);
+    detach();
+    detach = () => undefined;
+    return flush();
+  }
+
+  return { flush, start, stop };
+}
+
+export default createNativeRecorder;