@lowdefy/shell 3.23.3 → 7.2.0

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;

package/src/dev/recorder/createNativeRecorder.test.js

@@ -0,0 +1,307 @@
+/*
+  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 { jest } from '@jest/globals';
+import { Pressable, Text, TextInput as RNTextInput, View } from 'react-native';
+import { act, fireEvent, render, screen } from '@testing-library/react-native';
+import { createNativeGlobals, LowdefyPage } from '@lowdefy/client-native';
+import { SetState } from '@lowdefy/actions-core/actions';
+import { _state } from '@lowdefy/operators-js/operators/client';
+import validateTraceRecord from '@lowdefy/node-utils/journeyTrace/validateTraceRecord.js';
+
+import createMemoryStore from '../../host/createMemoryStore.js';
+import createNativeRecorder from './createNativeRecorder.js';
+
+// The records the dev server's recording validation runs over (server-dev
+// src/routes/devRecording.test.mjs): what this recorder writes for a click, a fill and a select.
+const fixture = require('../../../../servers/server-dev/test/nativeRecordingFixture.json');
+
+// Stand-ins for native blocks that call their methods as blocks-native's do.
+function Box({ content }) {
+  return <View>{content.content?.()}</View>;
+}
+Box.meta = { category: 'container', slots: { content: 'Child blocks.' } };
+
+function Button({ blockId, methods, properties }) {
+  return (
+    <Pressable
+      accessibilityRole="button"
+      onPress={() => methods.triggerEvent({ name: 'onClick' })}
+      testID={`${blockId}-press`}
+    >
+      <Text>{properties.title}</Text>
+    </Pressable>
+  );
+}
+Button.meta = { category: 'display' };
+
+function TextInput({ blockId, methods, properties, value }) {
+  return (
+    <RNTextInput
+      onChangeText={(text) => {
+        methods.setValue(text);
+        methods.triggerEvent({ name: 'onChange', event: { value: text } });
+      }}
+      onSubmitEditing={() => methods.triggerEvent({ name: 'onPressEnter' })}
+      secureTextEntry={properties.type === 'password'}
+      testID={`${blockId}_input`}
+      value={value ?? ''}
+    />
+  );
+}
+TextInput.meta = { category: 'input', valueType: 'string' };
+
+function Selector({ blockId, methods, properties }) {
+  return (
+    <View>
+      {properties.options.map((option) => (
+        <Pressable
+          key={option.value}
+          onPress={() => {
+            methods.setValue(option.value);
+            methods.triggerEvent({ name: 'onChange', event: { value: option.value } });
+          }}
+          testID={`${blockId}-${option.value}`}
+        >
+          <Text>{option.label}</Text>
+        </Pressable>
+      ))}
+    </View>
+  );
+}
+Selector.meta = { category: 'input', valueType: 'any' };
+
+const types = {
+  actions: { SetState },
+  blocks: { Box, Button, Selector, TextInput },
+  operators: { _state },
+};
+
+function block({ id, type, events, ...rest }) {
+  const built = { id: `block:ticket:${id}:0`, blockId: id, type, ...rest };
+  if (events) {
+    built.events = Object.fromEntries(
+      Object.entries(events).map(([name, actions]) => [name, { try: actions, catch: [] }])
+    );
+  }
+  return built;
+}
+
+const pageConfig = {
+  id: 'page:ticket',
+  pageId: 'ticket',
+  blockId: 'ticket',
+  type: 'Box',
+  path: 'ticket',
+  linkPaths: {},
+  subscriptions: [],
+  requests: [],
+  slots: {
+    content: {
+      blocks: [
+        block({
+          id: 'title',
+          type: 'TextInput',
+          events: {
+            onChange: [{ id: 'echo', type: 'SetState', params: { echo: { _state: 'title' } } }],
+          },
+        }),
+        block({ id: 'secret', type: 'TextInput', properties: { type: 'password' } }),
+        block({
+          id: 'priority',
+          type: 'Selector',
+          properties: {
+            options: [
+              { label: 'Low', value: 'low' },
+              { label: 'High', value: 'high' },
+            ],
+          },
+        }),
+        block({
+          id: 'save',
+          type: 'Button',
+          properties: { title: 'Save' },
+          events: {
+            onClick: [{ id: 'saved', type: 'SetState', params: { saved: true } }],
+          },
+        }),
+      ],
+    },
+  },
+};
+
+const rootConfig = {
+  classMap: {},
+  home: { configured: true, pageId: 'ticket' },
+  lowdefyApp: { slug: 'test-app' },
+  menus: [],
+  pagePaths: { ticket: 'ticket' },
+  theme: { light: {}, dark: {} },
+};
+
+const apiBase = 'http://192.168.1.20:3000';
+
+async function renderTicket() {
+  const fetch = jest.fn();
+  const host = {
+    fetch,
+    globals: createNativeGlobals({
+      assign: jest.fn(),
+      fetch,
+      getPath: () => '/ticket?from=list',
+      origin: apiBase,
+    }),
+    onBuildChanged: jest.fn(),
+    onCallerChanged: jest.fn(),
+    router: { back: jest.fn(), push: jest.fn(), replace: jest.fn() },
+    sessionStorage: createMemoryStore(),
+    storage: createMemoryStore(),
+    WebSocket: jest.fn(),
+    websocketUrl: (apiPath) => apiPath,
+  };
+  const lowdefy = {};
+  const core = { apiBase, auth: { authConfig: {} }, basePath: '', lowdefy };
+  await render(
+    <LowdefyPage
+      core={core}
+      host={host}
+      pageConfig={pageConfig}
+      rootConfig={rootConfig}
+      types={types}
+    />
+  );
+  await screen.findByText('Save');
+  return lowdefy;
+}
+
+function startRecorder(lowdefy) {
+  const posts = [];
+  const fetch = jest.fn(async (url, init) => {
+    posts.push({ url, body: JSON.parse(init.body) });
+    return { ok: true, status: 204 };
+  });
+  const kv = createMemoryStore();
+  const recorder = createNativeRecorder({
+    apiBase,
+    device: 'ios',
+    fetch,
+    getBuild: () => 'build-1',
+    getLowdefy: () => lowdefy,
+    kv,
+    shellVersion: '7.4.0',
+  });
+  recorder.start();
+  return { kv, posts, recorder };
+}
+
+function recordsOf(posts) {
+  return posts.flatMap((post) => post.body.records);
+}
+
+// Times and the session id differ on every run; the fixture keeps their order.
+function normalise(records) {
+  const start = Date.parse('2026-10-18T09:00:00.000Z');
+  return records.map((record, index) => ({
+    ...record,
+    session: '20261018T090000Z-ph0ne1',
+    t: new Date(start + index * 1000).toISOString(),
+  }));
+}
+
+async function act$(callback) {
+  await act(async () => {
+    callback();
+  });
+}
+
+let running;
+afterEach(async () => {
+  await running?.recorder.stop();
+  running = null;
+});
+
+test('a click, a fill and a select are recorded by block id, paired with the events they ran', async () => {
+  const lowdefy = await renderTicket();
+  running = startRecorder(lowdefy);
+  await act$(() => fireEvent.changeText(screen.getByTestId('title_input'), 'Pump'));
+  await act$(() => fireEvent.press(screen.getByTestId('priority-high')));
+  await act$(() => fireEvent.press(screen.getByTestId('save-press')));
+  await running.recorder.flush();
+
+  const { posts } = running;
+  expect(posts.map((post) => post.url)).toEqual([`${apiBase}/api/dev-recording`]);
+  const records = recordsOf(posts);
+  expect(records.every((record) => record.session === posts[0].body.session)).toBe(true);
+  expect(normalise(records)).toEqual(fixture.records);
+});
+
+test('every record passes the trace record validation once the dev server stamps its source', async () => {
+  const lowdefy = await renderTicket();
+  running = startRecorder(lowdefy);
+  await act$(() => fireEvent.changeText(screen.getByTestId('title_input'), 'Pump'));
+  await act$(() => fireEvent.press(screen.getByTestId('save-press')));
+  await running.recorder.flush();
+  const records = recordsOf(running.posts);
+  expect(records.length).toBeGreaterThan(0);
+  records.forEach((record) => {
+    expect(validateTraceRecord({ record: { ...record, source: 'dev' } })).toEqual({});
+  });
+});
+
+test('a password input is never recorded', async () => {
+  const lowdefy = await renderTicket();
+  running = startRecorder(lowdefy);
+  await act$(() => fireEvent.changeText(screen.getByTestId('secret_input'), 'hunter2'));
+  await running.recorder.flush();
+  const change = recordsOf(running.posts).find((record) => record.kind === 'change');
+  expect(change).toMatchObject({ target: { block_id: 'secret' }, value: null, redacted: true });
+  expect(JSON.stringify(recordsOf(running.posts))).not.toContain('hunter2');
+});
+
+test('pressing Enter in an input is recorded as an Enter key on its block', async () => {
+  const lowdefy = await renderTicket();
+  running = startRecorder(lowdefy);
+  await act$(() => fireEvent(screen.getByTestId('title_input'), 'submitEditing'));
+  await running.recorder.flush();
+  const key = recordsOf(running.posts).find((record) => record.kind === 'key');
+  expect(key).toMatchObject({ key: 'Enter', target: { block_id: 'title' }, page_id: 'ticket' });
+});
+
+test('the session is kept in the device store, so a new recorder carries it on', async () => {
+  const lowdefy = await renderTicket();
+  running = startRecorder(lowdefy);
+  await running.recorder.flush();
+  const [first] = recordsOf(running.posts);
+  const again = createNativeRecorder({
+    apiBase,
+    device: 'android',
+    fetch: jest.fn(async () => ({ ok: true })),
+    getBuild: () => null,
+    getLowdefy: () => lowdefy,
+    kv: running.kv,
+    shellVersion: '7.4.0',
+  });
+  const stored = JSON.parse(running.kv.get('lowdefy_dev_recording'));
+  expect(stored.id).toBe(first.session);
+  await again.stop();
+});
+
+test('with no open app the recorder records nothing', async () => {
+  running = startRecorder(null);
+  await running.recorder.flush();
+  expect(running.posts).toEqual([]);
+});

package/src/dev/redirectDevLink.js

@@ -0,0 +1,30 @@
+/*
+  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 parseDevLink from './connection/parseDevLink.js';
+import getShellConfig from '../config/getShellConfig.js';
+
+// Expo Router's redirectSystemPath (app/+native-intent.js): a Lowdefy Dev link is DevShell's, not a
+// page path. Opened with one, the app starts on its home screen; while it runs, the router leaves
+// it alone.
+function redirectDevLink({ initial, path }) {
+  if (parseDevLink({ link: path, scheme: getShellConfig().scheme }) === null) {
+    return path;
+  }
+  return initial ? '/' : null;
+}
+
+export default redirectDevLink;

package/src/dev/redirectDevLink.test.js

@@ -0,0 +1,49 @@
+/*
+  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 redirectDevLink from './redirectDevLink.js';
+
+jest.mock('../config/getShellConfig.js', () => () => ({ scheme: 'lowdefy-dev' }));
+
+const { getShellVariant } = require('../../shellVariant.js');
+
+test('a Lowdefy Dev link is left to DevShell: home on launch, nothing while running', () => {
+  const link = 'lowdefy-dev://connect?url=http%3A%2F%2F192.168.1.20%3A3000&pair=k3x9q';
+  expect(redirectDevLink({ initial: true, path: link })).toBe('/');
+  expect(redirectDevLink({ initial: false, path: link })).toBeNull();
+  expect(redirectDevLink({ initial: false, path: 'lowdefy-dev://menu' })).toBeNull();
+});
+
+test('any other link is routed as a page path', () => {
+  expect(redirectDevLink({ initial: false, path: 'lowdefy-dev://tickets/7' })).toBe(
+    'lowdefy-dev://tickets/7'
+  );
+  expect(redirectDevLink({ initial: true, path: '/tickets/7' })).toBe('/tickets/7');
+});
+
+test('Lowdefy Dev builds as dev and every other shell as release unless the build says', () => {
+  expect(getShellVariant({})).toBe('dev');
+  expect(getShellVariant({ LOWDEFY_SHELL_CONFIG: 'shell.json' })).toBe('release');
+  expect(getShellVariant({ LOWDEFY_SHELL_VARIANT: 'release' })).toBe('release');
+  expect(
+    getShellVariant({ LOWDEFY_SHELL_CONFIG: 'shell.json', LOWDEFY_SHELL_VARIANT: 'dev' })
+  ).toBe('dev');
+  expect(() => getShellVariant({ LOWDEFY_SHELL_VARIANT: 'prod' })).toThrow(
+    'LOWDEFY_SHELL_VARIANT must be "dev" or "release". Received "prod".'
+  );
+});