@lowdefy/shell 3.23.2 → 7.2.0

package/src/locale/dayjsLocales.js

@@ -0,0 +1,165 @@
+/*
+  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.
+*/
+
+// Generated by scripts/createDayjsLocales.mjs from the dayjs package the shell carries. Do not edit.
+
+const dayjsLocales = {
+  af: () => require('dayjs/locale/af.js'),
+  am: () => require('dayjs/locale/am.js'),
+  ar: () => require('dayjs/locale/ar.js'),
+  'ar-dz': () => require('dayjs/locale/ar-dz.js'),
+  'ar-iq': () => require('dayjs/locale/ar-iq.js'),
+  'ar-kw': () => require('dayjs/locale/ar-kw.js'),
+  'ar-ly': () => require('dayjs/locale/ar-ly.js'),
+  'ar-ma': () => require('dayjs/locale/ar-ma.js'),
+  'ar-sa': () => require('dayjs/locale/ar-sa.js'),
+  'ar-tn': () => require('dayjs/locale/ar-tn.js'),
+  az: () => require('dayjs/locale/az.js'),
+  be: () => require('dayjs/locale/be.js'),
+  bg: () => require('dayjs/locale/bg.js'),
+  bi: () => require('dayjs/locale/bi.js'),
+  bm: () => require('dayjs/locale/bm.js'),
+  bn: () => require('dayjs/locale/bn.js'),
+  'bn-bd': () => require('dayjs/locale/bn-bd.js'),
+  bo: () => require('dayjs/locale/bo.js'),
+  br: () => require('dayjs/locale/br.js'),
+  bs: () => require('dayjs/locale/bs.js'),
+  ca: () => require('dayjs/locale/ca.js'),
+  cs: () => require('dayjs/locale/cs.js'),
+  cv: () => require('dayjs/locale/cv.js'),
+  cy: () => require('dayjs/locale/cy.js'),
+  da: () => require('dayjs/locale/da.js'),
+  de: () => require('dayjs/locale/de.js'),
+  'de-at': () => require('dayjs/locale/de-at.js'),
+  'de-ch': () => require('dayjs/locale/de-ch.js'),
+  dv: () => require('dayjs/locale/dv.js'),
+  el: () => require('dayjs/locale/el.js'),
+  en: () => require('dayjs/locale/en.js'),
+  'en-au': () => require('dayjs/locale/en-au.js'),
+  'en-ca': () => require('dayjs/locale/en-ca.js'),
+  'en-gb': () => require('dayjs/locale/en-gb.js'),
+  'en-ie': () => require('dayjs/locale/en-ie.js'),
+  'en-il': () => require('dayjs/locale/en-il.js'),
+  'en-in': () => require('dayjs/locale/en-in.js'),
+  'en-nz': () => require('dayjs/locale/en-nz.js'),
+  'en-sg': () => require('dayjs/locale/en-sg.js'),
+  'en-tt': () => require('dayjs/locale/en-tt.js'),
+  eo: () => require('dayjs/locale/eo.js'),
+  es: () => require('dayjs/locale/es.js'),
+  'es-do': () => require('dayjs/locale/es-do.js'),
+  'es-mx': () => require('dayjs/locale/es-mx.js'),
+  'es-pr': () => require('dayjs/locale/es-pr.js'),
+  'es-us': () => require('dayjs/locale/es-us.js'),
+  et: () => require('dayjs/locale/et.js'),
+  eu: () => require('dayjs/locale/eu.js'),
+  fa: () => require('dayjs/locale/fa.js'),
+  fi: () => require('dayjs/locale/fi.js'),
+  fo: () => require('dayjs/locale/fo.js'),
+  fr: () => require('dayjs/locale/fr.js'),
+  'fr-ca': () => require('dayjs/locale/fr-ca.js'),
+  'fr-ch': () => require('dayjs/locale/fr-ch.js'),
+  fy: () => require('dayjs/locale/fy.js'),
+  ga: () => require('dayjs/locale/ga.js'),
+  gd: () => require('dayjs/locale/gd.js'),
+  gl: () => require('dayjs/locale/gl.js'),
+  'gom-latn': () => require('dayjs/locale/gom-latn.js'),
+  gu: () => require('dayjs/locale/gu.js'),
+  he: () => require('dayjs/locale/he.js'),
+  hi: () => require('dayjs/locale/hi.js'),
+  hr: () => require('dayjs/locale/hr.js'),
+  ht: () => require('dayjs/locale/ht.js'),
+  hu: () => require('dayjs/locale/hu.js'),
+  'hy-am': () => require('dayjs/locale/hy-am.js'),
+  id: () => require('dayjs/locale/id.js'),
+  is: () => require('dayjs/locale/is.js'),
+  it: () => require('dayjs/locale/it.js'),
+  'it-ch': () => require('dayjs/locale/it-ch.js'),
+  ja: () => require('dayjs/locale/ja.js'),
+  jv: () => require('dayjs/locale/jv.js'),
+  ka: () => require('dayjs/locale/ka.js'),
+  kk: () => require('dayjs/locale/kk.js'),
+  km: () => require('dayjs/locale/km.js'),
+  kn: () => require('dayjs/locale/kn.js'),
+  ko: () => require('dayjs/locale/ko.js'),
+  ku: () => require('dayjs/locale/ku.js'),
+  ky: () => require('dayjs/locale/ky.js'),
+  lb: () => require('dayjs/locale/lb.js'),
+  lo: () => require('dayjs/locale/lo.js'),
+  lt: () => require('dayjs/locale/lt.js'),
+  lv: () => require('dayjs/locale/lv.js'),
+  me: () => require('dayjs/locale/me.js'),
+  mi: () => require('dayjs/locale/mi.js'),
+  mk: () => require('dayjs/locale/mk.js'),
+  ml: () => require('dayjs/locale/ml.js'),
+  mn: () => require('dayjs/locale/mn.js'),
+  mr: () => require('dayjs/locale/mr.js'),
+  ms: () => require('dayjs/locale/ms.js'),
+  'ms-my': () => require('dayjs/locale/ms-my.js'),
+  mt: () => require('dayjs/locale/mt.js'),
+  my: () => require('dayjs/locale/my.js'),
+  nb: () => require('dayjs/locale/nb.js'),
+  ne: () => require('dayjs/locale/ne.js'),
+  nl: () => require('dayjs/locale/nl.js'),
+  'nl-be': () => require('dayjs/locale/nl-be.js'),
+  nn: () => require('dayjs/locale/nn.js'),
+  'oc-lnc': () => require('dayjs/locale/oc-lnc.js'),
+  'pa-in': () => require('dayjs/locale/pa-in.js'),
+  pl: () => require('dayjs/locale/pl.js'),
+  pt: () => require('dayjs/locale/pt.js'),
+  'pt-br': () => require('dayjs/locale/pt-br.js'),
+  rn: () => require('dayjs/locale/rn.js'),
+  ro: () => require('dayjs/locale/ro.js'),
+  ru: () => require('dayjs/locale/ru.js'),
+  rw: () => require('dayjs/locale/rw.js'),
+  sd: () => require('dayjs/locale/sd.js'),
+  se: () => require('dayjs/locale/se.js'),
+  si: () => require('dayjs/locale/si.js'),
+  sk: () => require('dayjs/locale/sk.js'),
+  sl: () => require('dayjs/locale/sl.js'),
+  sq: () => require('dayjs/locale/sq.js'),
+  sr: () => require('dayjs/locale/sr.js'),
+  'sr-cyrl': () => require('dayjs/locale/sr-cyrl.js'),
+  ss: () => require('dayjs/locale/ss.js'),
+  sv: () => require('dayjs/locale/sv.js'),
+  'sv-fi': () => require('dayjs/locale/sv-fi.js'),
+  sw: () => require('dayjs/locale/sw.js'),
+  ta: () => require('dayjs/locale/ta.js'),
+  te: () => require('dayjs/locale/te.js'),
+  tet: () => require('dayjs/locale/tet.js'),
+  tg: () => require('dayjs/locale/tg.js'),
+  th: () => require('dayjs/locale/th.js'),
+  tk: () => require('dayjs/locale/tk.js'),
+  'tl-ph': () => require('dayjs/locale/tl-ph.js'),
+  tlh: () => require('dayjs/locale/tlh.js'),
+  tr: () => require('dayjs/locale/tr.js'),
+  tzl: () => require('dayjs/locale/tzl.js'),
+  tzm: () => require('dayjs/locale/tzm.js'),
+  'tzm-latn': () => require('dayjs/locale/tzm-latn.js'),
+  'ug-cn': () => require('dayjs/locale/ug-cn.js'),
+  uk: () => require('dayjs/locale/uk.js'),
+  ur: () => require('dayjs/locale/ur.js'),
+  uz: () => require('dayjs/locale/uz.js'),
+  'uz-latn': () => require('dayjs/locale/uz-latn.js'),
+  vi: () => require('dayjs/locale/vi.js'),
+  'x-pseudo': () => require('dayjs/locale/x-pseudo.js'),
+  yo: () => require('dayjs/locale/yo.js'),
+  zh: () => require('dayjs/locale/zh.js'),
+  'zh-cn': () => require('dayjs/locale/zh-cn.js'),
+  'zh-hk': () => require('dayjs/locale/zh-hk.js'),
+  'zh-tw': () => require('dayjs/locale/zh-tw.js'),
+};
+
+export default dayjsLocales;

package/src/locale/getDeviceLocales.js

@@ -0,0 +1,23 @@
+/*
+  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 device's locale, which Hermes' Intl reads from the platform (iOS's NSLocale, Android's
+// default Locale).
+function getDeviceLocales() {
+  return [Intl.DateTimeFormat().resolvedOptions().locale];
+}
+
+export default getDeviceLocales;

package/src/locale/loadDayjsLocale.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 dayjs from 'dayjs';
+
+import dayjsLocales from './dayjsLocales.js';
+
+// Makes a dayjs locale the one _dayjs formats with, loading its data the first time. The dayjs
+// instance is the one @lowdefy/operators-dayjs imports. An id dayjs does not ship leaves the
+// locale as it is, as on the web.
+function loadDayjsLocale(id) {
+  if (!Object.hasOwn(dayjsLocales, id)) {
+    return;
+  }
+  dayjsLocales[id]();
+  dayjs.locale(id);
+}
+
+export default loadDayjsLocale;

package/src/locale/resolveActiveLocale.js

@@ -0,0 +1,46 @@
+/*
+  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 first device locale the app supports, by exact code, then by language.
+function pickBest({ candidates, supported }) {
+  for (const candidate of candidates) {
+    if (supported.includes(candidate)) return candidate;
+    const language = candidate.split('-')[0];
+    const match = supported.find((code) => code.split('-')[0] === language);
+    if (match) return match;
+  }
+  return undefined;
+}
+
+/**
+ * The app's active locale, as the web client picks it (useLocale): the person's choice (SetLocale)
+ * when the app supports it, else the device's locale the app supports best, else the app's
+ * default. Undefined for an app without i18n.
+ *
+ * @param {Object} params
+ * @param {string[]} params.deviceLocales The device's locales, preferred first.
+ * @param {Object} params.i18n The app's i18n config: `{ defaultLocale, locales }`.
+ * @param {string} params.preference A locale code, or 'auto'.
+ */
+function resolveActiveLocale({ deviceLocales, i18n, preference }) {
+  const supported = (i18n.locales ?? []).map((locale) => locale.code);
+  if (preference !== 'auto' && supported.includes(preference)) {
+    return preference;
+  }
+  return pickBest({ candidates: deviceLocales, supported }) ?? i18n.defaultLocale;
+}
+
+export default resolveActiveLocale;

package/src/locale/resolveActiveLocale.test.js

@@ -0,0 +1,40 @@
+/*
+  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 resolveActiveLocale from './resolveActiveLocale.js';
+
+const i18n = {
+  defaultLocale: 'en-US',
+  locales: [{ code: 'en-US' }, { code: 'af-ZA' }, { code: 'pt-BR' }],
+};
+
+test('resolveActiveLocale takes the person choice when the app supports it', () => {
+  expect(resolveActiveLocale({ deviceLocales: ['pt-BR'], i18n, preference: 'af-ZA' })).toBe(
+    'af-ZA'
+  );
+  expect(resolveActiveLocale({ deviceLocales: ['pt-BR'], i18n, preference: 'de-DE' })).toBe(
+    'pt-BR'
+  );
+});
+
+test('resolveActiveLocale matches the device locale by code, then by language', () => {
+  expect(resolveActiveLocale({ deviceLocales: ['pt-BR'], i18n, preference: 'auto' })).toBe('pt-BR');
+  expect(resolveActiveLocale({ deviceLocales: ['pt-PT'], i18n, preference: 'auto' })).toBe('pt-BR');
+});
+
+test('resolveActiveLocale falls back to the app default', () => {
+  expect(resolveActiveLocale({ deviceLocales: ['ja-JP'], i18n, preference: 'auto' })).toBe('en-US');
+});

package/src/native/backgroundFetch.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 * as BackgroundTask from 'expo-background-task';
+import * as Notifications from 'expo-notifications';
+import * as TaskManager from 'expo-task-manager';
+import { type } from '@lowdefy/helpers';
+
+import callEndpoint from './callEndpoint.js';
+import { getCurrentApp } from './currentApp.js';
+import refreshWidgets from '../widgets/refreshWidgets.js';
+import reportShellError from '../host/reportShellError.js';
+
+const TASK = 'lowdefy-background-fetch';
+
+/**
+ * One background fetch run, with the app closed: calls mobile.background.endpointId with
+ * { reason: 'background' } and applies its answer ({ badge?, refreshWidgets? }), sends the offline
+ * queue and refreshes the cached root and pages. No page or app event runs.
+ *
+ * @param {Object} app The open app (currentApp.js).
+ */
+async function runBackgroundFetch(app) {
+  const background = app.session.getState().root?.background;
+  if (type.isNone(background)) {
+    return;
+  }
+  const answer = await callEndpoint({
+    app,
+    endpointId: background.endpointId,
+    payload: { reason: 'background' },
+  });
+  if (type.isNumber(answer?.badge)) {
+    await Notifications.setBadgeCountAsync(answer.badge);
+  }
+  await Promise.all([
+    app.requestQueue.replay(),
+    app.session.sync(),
+    answer?.refreshWidgets === false ? null : refreshWidgets(),
+  ]);
+}
+
+// Defined when the bundle loads, so a launch in the background finds it.
+TaskManager.defineTask(TASK, async () => {
+  const app = await getCurrentApp();
+  try {
+    await runBackgroundFetch(app);
+    return BackgroundTask.BackgroundTaskResult.Success;
+  } catch (error) {
+    reportShellError({ error, session: app.session });
+    return BackgroundTask.BackgroundTaskResult.Failed;
+  }
+});
+
+/**
+ * Registers background fetch while the app's root has mobile.background, at its interval in
+ * minutes (the phone decides the real timing), and unregisters it otherwise.
+ *
+ * @param {Object} params
+ * @param {Object} params.app The open app (currentApp.js).
+ * @returns {() => void} Stops following the root.
+ */
+function startBackgroundFetch({ app }) {
+  let applied;
+  async function applyRoot() {
+    const background = app.session.getState().root?.background ?? null;
+    if (background === applied) return;
+    applied = background;
+    const registered = await TaskManager.isTaskRegisteredAsync(TASK);
+    if (background === null) {
+      if (registered) await BackgroundTask.unregisterTaskAsync(TASK);
+      return;
+    }
+    await BackgroundTask.registerTaskAsync(TASK, { minimumInterval: background.interval });
+  }
+  const unsubscribe = app.session.subscribe(() => {
+    applyRoot().catch(() => {});
+  });
+  applyRoot().catch(() => {});
+  return unsubscribe;
+}
+
+export { runBackgroundFetch };
+export default startBackgroundFetch;

package/src/native/callEndpoint.js

@@ -0,0 +1,63 @@
+/*
+  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 { decodeErrorBody, getAuthorizationHeaders } from '@lowdefy/client-core';
+import { serializer, type } from '@lowdefy/helpers';
+
+import readServerError from '../host/readServerError.js';
+
+/**
+ * Calls one of the app's API endpoints from the shell itself, with the session token: push token
+ * registration, notification buttons, uploads, widget sources, background fetch and background
+ * location. No page is involved, so no build id is sent (endpoints are the stable contract across
+ * builds). Returns the endpoint's response; throws when the server refuses the call (the error
+ * carries the HTTP `status`) or the endpoint rejects or errors.
+ *
+ * @param {Object} params
+ * @param {Object} params.app The open app ({ apiBase, fetch, tokenStore }, currentApp.js).
+ * @param {string} params.endpointId
+ * @param {Object} [params.payload]
+ */
+async function callEndpoint({ app, endpointId, payload = {} }) {
+  const res = await app.fetch(`${app.apiBase}/api/endpoints/${endpointId}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...getAuthorizationHeaders({ host: { authTransport: 'bearer', tokenStore: app.tokenStore } }),
+    },
+    body: JSON.stringify({ payload: serializer.serialize(payload) }),
+  });
+  if (!res.ok) {
+    throw await readServerError({
+      res,
+      message: `Endpoint "${endpointId}" answered ${res.status}.`,
+    });
+  }
+  const body = await res.json();
+  if (body.success === false) {
+    throw (
+      decodeErrorBody(body.error) ??
+      new Error(
+        type.isString(body.error?.message)
+          ? body.error.message
+          : `Endpoint "${endpointId}" answered ${body.status}.`
+      )
+    );
+  }
+  return serializer.deserialize(body.response);
+}
+
+export default callEndpoint;

package/src/native/createAppEventTrigger.js

@@ -0,0 +1,70 @@
+/*
+  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 { LowdefyInternalError } from '@lowdefy/errors';
+
+import reportShellError from '../host/reportShellError.js';
+
+const RETRY_MS = 300;
+const MAX_TRIES = 100;
+
+/**
+ * Runs one of the app's mobile.events (onNotification, onNotificationAction, onShare, onShortcut,
+ * onGeofence, onRequestQueue) with an event object. The app context is made when the first page
+ * renders, so an event that arrives before it (a notification tap that launched the app) waits for
+ * it, trying every 300 ms for up to 30 seconds. Never throws: an app event's failure is reported by
+ * the engine's own error handling, and an event that never ran (no app context came, or the engine
+ * itself threw) is reported here.
+ *
+ * @param {Object} params
+ * @param {Object} params.session The app session (createAppSession).
+ */
+function createAppEventTrigger({ session }) {
+  return function triggerAppEvent({ name, event }) {
+    let tries = 0;
+    return new Promise((resolve) => {
+      function attempt() {
+        const appContext = session.getState().lowdefy?.appContext;
+        if (appContext === undefined || appContext === null) {
+          tries += 1;
+          if (tries > MAX_TRIES) {
+            reportShellError({
+              error: new LowdefyInternalError(
+                `App event "${name}" was dropped: no page created the app context within ${
+                  (RETRY_MS * MAX_TRIES) / 1000
+                } seconds.`
+              ),
+              session,
+            });
+            resolve(null);
+            return;
+          }
+          setTimeout(attempt, RETRY_MS);
+          return;
+        }
+        Promise.resolve(appContext._internal.triggerPageEvent({ name, event }))
+          .catch((error) => {
+            reportShellError({ error, session });
+            return null;
+          })
+          .then(resolve);
+      }
+      attempt();
+    });
+  };
+}
+
+export default createAppEventTrigger;

package/src/native/currentApp.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.
+*/
+
+// The app the shell has open, for native work that starts outside React: a notification button
+// pressed with the app in the background, a background fetch, a geofence crossing. AppProvider sets
+// it once the app's auth and session exist; work started before then waits for it.
+let current = null;
+let waiting = [];
+
+/**
+ * @param {Object|null} app { apiBase, auth, fetch, router, session, shell, tokenStore,
+ *   triggerAppEvent }, or null when the app closes (a sign-out opens it afresh).
+ */
+function setCurrentApp(app) {
+  current = app;
+  if (app !== null) {
+    waiting.splice(0).forEach((resolve) => resolve(app));
+  }
+}
+
+// The open app, once there is one.
+function getCurrentApp() {
+  if (current !== null) {
+    return Promise.resolve(current);
+  }
+  return new Promise((resolve) => {
+    waiting.push(resolve);
+  });
+}
+
+// The open app, or null: for work that only makes sense while one is open.
+function peekCurrentApp() {
+  return current;
+}
+
+export { getCurrentApp, peekCurrentApp, setCurrentApp };

package/src/native/getPagePath.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.
+*/
+
+/**
+ * The path of a page in the app's root page index, or null when the caller cannot open it.
+ *
+ * @param {Object} params
+ * @param {Object} params.root The mobile root.
+ * @param {string} params.pageId
+ */
+function getPagePath({ pageId, root }) {
+  const entry = (root?.pageIndex ?? []).find((item) => item.pageId === pageId);
+  if (entry === undefined) {
+    return null;
+  }
+  return entry.path.startsWith('/') ? entry.path : `/${entry.path}`;
+}
+
+export default getPagePath;