@lowdefy/shell 0.0.0-experimental-20261019052246

package/src/dev/tab/getShownPage.js

@@ -0,0 +1,42 @@
+/*
+  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 { getTrace } from '@lowdefy/engine';
+
+// The page instance the shell shows, `{ pageId, pathParams, instanceKey }`, read from the route the
+// focused screen set (host globals), as the trace reads it. A screen's page context is keyed by its
+// route instance too (engine getContext), so the key ends in `@{instanceId}`. Null before the first
+// page renders.
+function getShownPage(lowdefy) {
+  const globals = lowdefy?._internal?.globals;
+  if (type.isNone(globals)) {
+    return null;
+  }
+  const entry = getTrace(lowdefy).pathEntryOf(globals.window.location.href);
+  if (type.isNone(entry)) {
+    return null;
+  }
+  // Only the shell's own globals know the focused screen; a page rendered without one has one
+  // context per page instance.
+  const instanceId = globals.shownScreen?.instanceId;
+  const instanceKey = type.isNone(instanceId)
+    ? entry.instanceKey
+    : `${entry.instanceKey}@${instanceId}`;
+  return { pageId: entry.pageId, pathParams: entry.pathParams, instanceKey };
+}
+
+export default getShownPage;

package/src/dev/tab/readEventStream.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.
+*/
+
+/**
+ * Reads a text/event-stream body (the dev server's /api/reload) and calls onEvent with each event
+ * as `{ event, data }`, the way EventSource dispatches them. React Native has no EventSource, so
+ * the stream is read from a streaming fetch body. Resolves when the stream ends.
+ *
+ * @param {Object} params
+ * @param {ReadableStream} params.body The response body.
+ * @param {(event: { event: string, data: string }) => void} params.onEvent
+ */
+async function readEventStream({ body, onEvent }) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let event = null;
+  let dataLines = [];
+
+  function readLine(line) {
+    if (line === '') {
+      if (dataLines.length > 0 || event !== null) {
+        onEvent({ event: event ?? 'message', data: dataLines.join('\n') });
+      }
+      event = null;
+      dataLines = [];
+      return;
+    }
+    if (line.startsWith(':')) {
+      return;
+    }
+    const colon = line.indexOf(':');
+    const field = colon === -1 ? line : line.slice(0, colon);
+    const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '');
+    if (field === 'event') {
+      event = value;
+    }
+    if (field === 'data') {
+      dataLines.push(value);
+    }
+  }
+
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) {
+      return;
+    }
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split(/\r\n|\r|\n/);
+    buffer = lines.pop();
+    lines.forEach(readLine);
+  }
+}
+
+export default readEventStream;

package/src/dev/tab/reloadApp.js

@@ -0,0 +1,42 @@
+/*
+  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 matchPagePath from '@lowdefy/node-utils/matchPagePath.js';
+
+import encodePagePath from '../../sync/encodePagePath.js';
+
+/**
+ * The dev server rebuilt the app: refetch the root and the page on screen, then rebuild every
+ * screen with empty page state, as a browser tab does on a reload. The shell stays on the page it
+ * shows.
+ *
+ * @param {Object} params
+ * @param {Object} params.session The app session (createAppSession).
+ */
+async function reloadApp({ session }) {
+  const { root } = session.getState();
+  const path = session.getCurrentPath().replace(/^\//, '').split('?')[0];
+  const match =
+    root === null ? null : matchPagePath({ routes: root.pageIndex, path: encodePagePath(path) });
+  if (match !== null) {
+    const entry = root.pageIndex.find((indexEntry) => indexEntry.pageId === match.pageId);
+    await session.loadPage({ entry, path });
+  }
+  // Syncs the root, then starts a new generation: new page contexts on the current route.
+  await session.handleBuildChanged();
+}
+
+export default reloadApp;

package/src/dev/tab/reloadApp.test.js

@@ -0,0 +1,115 @@
+/*
+  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 { act, screen } from '@testing-library/react-native';
+
+import getShownPage from './getShownPage.js';
+import reloadApp from './reloadApp.js';
+import renderPageScreen from '../../test/renderPageScreen.js';
+import { createRoot } from '../../test/fixtures.js';
+
+// The native stack's header height, which a Screen's headerBottom pins under on iOS.
+jest.mock('expo-router/native-stack', () => ({ useAnimatedHeaderHeight: () => 0 }));
+jest.mock('react-native-safe-area-context', () => ({
+  useSafeAreaInsets: () => ({ top: 0, right: 0, bottom: 34, left: 0 }),
+}));
+
+jest.mock('expo-router', () => ({
+  DarkTheme: { fonts: {} },
+  DefaultTheme: { fonts: {} },
+  ThemeProvider: ({ children }) => children,
+  router: { back: jest.fn(), canGoBack: () => false },
+  useFocusEffect: (effect) => {
+    const { useEffect: useReactEffect } = jest.requireActual('react');
+    useReactEffect(effect, [effect]);
+  },
+  useIsFocused: () => true,
+  useNavigation: () => ({ setOptions: jest.fn() }),
+  useRoute: () => ({ key: 'route-1' }),
+}));
+
+function todayPage(greeting) {
+  return {
+    id: 'page:today',
+    pageId: 'today',
+    blockId: 'today',
+    type: 'Screen',
+    properties: { title: 'Today' },
+    slots: {
+      content: {
+        blocks: [
+          {
+            id: 'block:today:greeting:0',
+            blockId: 'greeting',
+            type: 'Box',
+            properties: { content: greeting },
+          },
+        ],
+      },
+    },
+  };
+}
+
+// A dev root: its pages have no hash, so the shell fetches them on each visit.
+async function renderDevPage() {
+  const { server, session } = await renderPageScreen({
+    path: 'today',
+    root: createRoot({
+      pageIndex: [{ path: 'today', pageId: 'today', hash: null, typesKey: 'screen' }],
+      typeSets: {
+        screen: {
+          blocks: [
+            { type: 'Box', package: '@lowdefy/blocks-native', version: 7 },
+            { type: 'Screen', package: '@lowdefy/blocks-native', version: 7 },
+          ],
+        },
+      },
+    }),
+    pages: { today: { pageConfig: todayPage('Hello'), etag: '"p1"' } },
+  });
+  await screen.findByText('Hello');
+  return { server, session };
+}
+
+test('a reload refetches the root and the page on screen, and rebuilds it with empty state', async () => {
+  const { server, session } = await renderDevPage();
+  const before = session.getState().lowdefy;
+  const shown = getShownPage(before);
+  // The screen's page context is keyed by its route instance.
+  expect(shown).toEqual({ pageId: 'today', pathParams: {}, instanceKey: 'page:today@route-1' });
+  before.contexts[shown.instanceKey]._internal.State.set('typed', 'Quarterly');
+  expect(before.contexts[shown.instanceKey].state.typed).toBe('Quarterly');
+
+  server.state.pages.today = { pageConfig: todayPage('Hello again'), etag: '"p2"' };
+  server.state.rootEtag = '"r2"';
+  server.fetch.mockClear();
+  await act(async () => {
+    await reloadApp({ session });
+  });
+
+  const paths = server.fetch.mock.calls.map(([url]) => new URL(url).pathname);
+  // The rebuilt screen revalidates its page, as every screen does after a rebuild, so a screen
+  // under the one shown gets its new version too: the version reloadApp fetched is current.
+  expect(paths).toEqual(['/api/page/today', '/api/mobile/root', '/api/user', '/api/page/today']);
+  const revalidation = server.fetch.mock.calls.at(-1)[1];
+  expect(revalidation.headers).toEqual({ 'If-None-Match': '"p2"' });
+  expect(await screen.findByText('Hello again')).toBeTruthy();
+  expect(session.getCurrentPath()).toBe('/today');
+  const after = session.getState().lowdefy;
+  expect(after).not.toBe(before);
+  expect(after.contexts[shown.instanceKey].state.typed).toBeUndefined();
+});

package/src/device/injected.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.
+*/
+
+// The injector Lowdefy Dev installs (src/dev/inject). A release shell never installs one.
+let injector = null;
+
+/**
+ * The next device result Lowdefy Dev was told to fake, or undefined when there is none: in a
+ * release shell always. A device action reads it first, in one line, and uses the device only when
+ * nothing was injected:
+ *
+ *   const scan = injected('scan');
+ *   if (scan !== undefined) return scan;
+ *
+ * Names:
+ * - `scan`: the next ScanCode or QRScanner read, `{ data, type }`.
+ * - `photo`: the next TakePhoto or PickImage result, `{ base64, mimeType, width, height }`.
+ * - `nfc`: the next ReadNfc read.
+ * - `transcript`: what the next dictation session hears, `{ partials?, final }` or `{ error }`.
+ *   Dictation (blocks-native) reads it through the source Lowdefy Dev installs with
+ *   installDictationSource.
+ * - `location`: the location GeolocationCurrentPosition and geofences read,
+ *   `{ latitude, longitude, accuracy, ... }`.
+ * - `permission:<name>`: the answer to the next request for a permission, 'granted' or 'denied'
+ *   (`permission:microphone` for dictation).
+ *
+ * @param {string} name
+ */
+function injected(name) {
+  if (injector === null) {
+    return undefined;
+  }
+  return injector.take(name);
+}
+
+// Installs the injector `injected` reads (`{ take(name) }`); returns the function that removes it.
+function installInjector(next) {
+  injector = next;
+  return () => {
+    if (injector === next) {
+      injector = null;
+    }
+  };
+}
+
+export { installInjector };
+export default injected;

package/src/device/injected.test.js

@@ -0,0 +1,39 @@
+/*
+  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 injected, { installInjector } from './injected.js';
+
+test('with no injector installed, as in a release shell, nothing is injected', () => {
+  expect(injected('scan')).toBeUndefined();
+  expect(injected('permission:camera')).toBeUndefined();
+});
+
+test('injected reads the installed injector until it is removed', () => {
+  const take = (name) => `next ${name}`;
+  const remove = installInjector({ take });
+  expect(injected('scan')).toBe('next scan');
+  remove();
+  expect(injected('scan')).toBeUndefined();
+});
+
+test('removing an injector that was replaced leaves the newer one installed', () => {
+  const removeFirst = installInjector({ take: () => 'first' });
+  const removeSecond = installInjector({ take: () => 'second' });
+  removeFirst();
+  expect(injected('scan')).toBe('second');
+  removeSecond();
+  expect(injected('scan')).toBeUndefined();
+});

package/src/host/createDeviceStore.js

@@ -0,0 +1,32 @@
+/*
+  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 { Storage } from 'expo-sqlite/kv-store';
+
+// The host store that lasts on the device ({ get, set, remove, keys }), over SQLite's key-value
+// store. The core namespaces its keys per app and user.
+function createDeviceStore() {
+  return {
+    get: (key) => Storage.getItemSync(key),
+    set: (key, value) => Storage.setItemSync(key, String(value)),
+    remove: (key) => {
+      Storage.removeItemSync(key);
+    },
+    keys: () => Storage.getAllKeysSync(),
+  };
+}
+
+export default createDeviceStore;

package/src/host/createMemoryStore.js

@@ -0,0 +1,32 @@
+/*
+  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 store held in memory, for the session store: it lasts as long as the app runs.
+function createMemoryStore() {
+  const stored = new Map();
+  return {
+    get: (key) => stored.get(key) ?? null,
+    set: (key, value) => {
+      stored.set(key, String(value));
+    },
+    remove: (key) => {
+      stored.delete(key);
+    },
+    keys: () => [...stored.keys()],
+  };
+}
+
+export default createMemoryStore;

package/src/host/createNetworkStatus.js

@@ -0,0 +1,94 @@
+/*
+  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 isOnline from './isOnline.js';
+
+/**
+ * The shell's one online state. The NoConnection banner and the app's `online` and `offline`
+ * events (createShellHost) read it, and two sources feed it:
+ * - the phone's network, through expo-network, read while anything subscribes;
+ * - Lowdefy Dev's network injection (`setInjectedOffline`), since a simulator or emulator shares
+ *   the computer's network and cannot go offline itself. A release shell never sets it.
+ *
+ * The shell is online when the phone's network is up and nothing injected offline. Subscribers
+ * hear only changes, as a browser fires `online` and `offline`.
+ *
+ * @param {Object} params
+ * @param {Object} params.network expo-network: `addNetworkStateListener` and
+ *   `getNetworkStateAsync`.
+ */
+function createNetworkStatus({ network }) {
+  const listeners = new Set();
+  let deviceOnline = true;
+  let injectedOffline = false;
+  let online = true;
+  let stopListening = null;
+
+  function settle() {
+    const next = deviceOnline && !injectedOffline;
+    if (next === online) return;
+    online = next;
+    [...listeners].forEach((listener) => listener(online));
+  }
+
+  function setDeviceState(state) {
+    deviceOnline = isOnline(state);
+    settle();
+  }
+
+  // Reads the phone's network until stopped. A change heard before the first read answers is
+  // newer than that read, so the read is then dropped.
+  function listen() {
+    let heard = false;
+    let active = true;
+    const subscription = network.addNetworkStateListener((state) => {
+      heard = true;
+      setDeviceState(state);
+    });
+    network.getNetworkStateAsync().then((state) => {
+      if (active && !heard) setDeviceState(state);
+    });
+    return () => {
+      active = false;
+      subscription.remove();
+    };
+  }
+
+  // Calls the listener with the new online state on every change; returns the function that
+  // stops it.
+  function subscribe(listener) {
+    if (listeners.size === 0) {
+      stopListening = listen();
+    }
+    listeners.add(listener);
+    return () => {
+      if (!listeners.delete(listener)) return;
+      if (listeners.size === 0) {
+        stopListening();
+        stopListening = null;
+      }
+    };
+  }
+
+  function setInjectedOffline(offline) {
+    injectedOffline = offline;
+    settle();
+  }
+
+  return { isOnline: () => online, setInjectedOffline, subscribe };
+}
+
+export default createNetworkStatus;

package/src/host/createNetworkStatus.test.js

@@ -0,0 +1,94 @@
+/*
+  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 createFakeNetwork, { OFFLINE, ONLINE } from '../test/createFakeNetwork.js';
+import createNetworkStatus from './createNetworkStatus.js';
+
+// Lets the first read of the phone's network answer.
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+test('the phone going offline and back is heard by subscribers, once per change', async () => {
+  const network = createFakeNetwork();
+  const status = createNetworkStatus({ network });
+  const listener = jest.fn();
+  status.subscribe(listener);
+  await settle();
+  expect(status.isOnline()).toBe(true);
+  network.change(OFFLINE);
+  network.change(OFFLINE);
+  expect(status.isOnline()).toBe(false);
+  network.change(ONLINE);
+  expect(listener.mock.calls).toEqual([[false], [true]]);
+});
+
+test('the first read of the phone network sets the state', async () => {
+  const status = createNetworkStatus({ network: createFakeNetwork({ state: OFFLINE }) });
+  const listener = jest.fn();
+  status.subscribe(listener);
+  expect(status.isOnline()).toBe(true);
+  await settle();
+  expect(status.isOnline()).toBe(false);
+  expect(listener).toHaveBeenCalledWith(false);
+});
+
+test('a change heard before the first read answers wins over that read', async () => {
+  const network = createFakeNetwork({ state: OFFLINE });
+  const status = createNetworkStatus({ network });
+  status.subscribe(() => undefined);
+  network.change(ONLINE);
+  network.getNetworkStateAsync = async () => OFFLINE;
+  await settle();
+  expect(status.isOnline()).toBe(true);
+});
+
+test('injected offline takes the shell offline while the phone is online, until it is lifted', async () => {
+  const status = createNetworkStatus({ network: createFakeNetwork() });
+  const listener = jest.fn();
+  status.subscribe(listener);
+  await settle();
+  status.setInjectedOffline(true);
+  expect(status.isOnline()).toBe(false);
+  status.setInjectedOffline(false);
+  expect(status.isOnline()).toBe(true);
+  expect(listener.mock.calls).toEqual([[false], [true]]);
+});
+
+test('lifting injected offline leaves the shell offline while the phone is offline', async () => {
+  const network = createFakeNetwork();
+  const status = createNetworkStatus({ network });
+  status.subscribe(() => undefined);
+  await settle();
+  status.setInjectedOffline(true);
+  network.change(OFFLINE);
+  status.setInjectedOffline(false);
+  expect(status.isOnline()).toBe(false);
+});
+
+test('the phone network is read only while something subscribes', async () => {
+  const network = createFakeNetwork();
+  const status = createNetworkStatus({ network });
+  expect(network.listening()).toBe(false);
+  const first = status.subscribe(() => undefined);
+  const second = status.subscribe(() => undefined);
+  expect(network.listening()).toBe(true);
+  first();
+  first();
+  expect(network.listening()).toBe(true);
+  second();
+  expect(network.listening()).toBe(false);
+});

package/src/host/createRouterAdapter.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 { router } from 'expo-router';
+
+import toRouterHref from '../navigation/toRouterHref.js';
+
+// The core's router contract (push, replace, back) on Expo Router.
+function createRouterAdapter({ session }) {
+  function href(target) {
+    return toRouterHref({ ...target, root: session.getState().root });
+  }
+  return {
+    push: (target) => router.push(href(target)),
+    replace: (target) => router.replace(href(target)),
+    back: () => router.back(),
+  };
+}
+
+export default createRouterAdapter;