@lowdefy/shell 0.0.0-experimental-20261019052246

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+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.

package/README.md

@@ -0,0 +1,308 @@
+# @lowdefy/shell
+
+The Expo app every Lowdefy phone app is built from (Expo SDK 58, React Native 0.88, Hermes, New
+Architecture). It carries code only: the Lowdefy engine, `@lowdefy/client-native` and the shell's
+plugin maps. Pages, menus and theme come from the app's Lowdefy server as data. No `ios/` or
+`android/` folder is committed: Expo writes them at build time.
+
+## Config
+
+`app.config.ts` reads `shell.json` from the path in `LOWDEFY_SHELL_CONFIG`, and falls back to
+`shell.dev.json` (Lowdefy Dev):
+
+```json
+{
+  "id": "field",
+  "name": "Field",
+  "profile": "field",
+  "version": "1.4.2",
+  "icon": "./icon.png",
+  "color": "#0B5FFF",
+  "scheme": "field",
+  "environment": "production",
+  "eas": { "owner": "example", "projectId": "2b6f…" },
+  "ios": { "bundleIdentifier": "com.example.field" },
+  "android": { "package": "com.example.field" },
+  "store": { "ios": "https://apps.apple.com/...", "android": "https://play.google.com/..." },
+  "app": { "id": "field", "name": "Field", "urls": { "production": "https://field.example.com" } }
+}
+```
+
+A shell opens exactly one app, named by `app`. Every app's `_js` runs in the shell's one JavaScript
+realm, which cannot be sandboxed, so a second app in the same shell could reach the first one's
+session token, storage and cache. `checkShellConfig.js` refuses a `shell.json` that lists `apps`,
+names more than one app, or has no url for the shell's `environment`; `app.config.ts` runs it, so
+`expo prebuild` and `expo export` fail on such a config.
+
+`profile` names the shell's capability profile, one row of the table in `profiles.js`: `basic`,
+`field`, `field-nfc`, `field-tracking`, and `dev` and `development` for Lowdefy Dev and development
+builds. Each lists the native modules, config plugins, permissions, JavaScript entry modules,
+required-reason APIs and collected data it carries, and may extend another (`field` is `basic` and
+the camera). `basic`, and so every profile, carries on-device dictation (`expo-speech-recognition`)
+with its microphone and speech purpose texts; `expo-camera` is given the same microphone text, so
+plugin order cannot change it. `resolveProfile(name)` flattens one, and throws on a name the table
+lacks. A shell
+config without `profile` is `basic`, or `dev` for Lowdefy Dev. `app.config.ts` applies only the
+profile's config plugins, and sets `capabilities` from it when `shell.json` has none.
+
+The shell's version and type manifest are not in the Expo config: they are
+`src/version/shellVersion.js` and `src/plugins/typeManifest.js`, part of the JavaScript bundle, so
+they match the code that runs. An embedded launch reads the Expo config of the native build, so a
+version there would keep a debug shell on Metro behind an app's `minShellVersion`, and a manifest
+there would hide a type added since. The manifest lists every block, action and operator type the
+shell registers (`src/plugins/types.js`, listed in
+`src/plugins/shellPlugins.json`), with its plugin package and that package's major version.
+`pnpm --filter=@lowdefy/shell type-manifest` rewrites it (`scripts/createTypeManifest.mjs`) after
+a change to the plugin maps, `src/plugins/types.test.js` fails when it is stale, and
+`pnpm release:version` rewrites it after the version bump.
+
+## Shell plugins
+
+`plugins` in `shell.json` lists npm packages that add native code on top of the shell's profile:
+`[{ name, version, typePrefix?, options? }]`, written by `lowdefy mobile config` from
+`mobile.shells[].plugins`, which also installs them in the shell project. Each is a Lowdefy shell
+plugin; `resolveShellPlugins.js` describes the package contract:
+
+- `./shell` (CommonJS): a row shaped like one of `profiles.js` (`capabilities`, `modules`,
+  `plugins`, `permissions`, `privacyReasons`, `dataCollected`). `plugins` may be a function of the
+  plugin's `options`. `app.config.ts` loads it (`resolveShellPlugins.js`) and folds it into the
+  resolved profile (`applyShellPlugins.js`), so its config plugins, permissions, privacy reasons and
+  data join the profile's. Its modules are never excluded.
+- `./native` (optional): named exports `blocks` and `actions`, `{ [typeName]: implementation }`.
+  The shell ships `src/plugins/appTypes.js` empty; `config` rewrites it in the copy to import each
+  plugin's `./native` with its `typePrefix` (`src/plugins/prefixTypes.js`), and `types.js`
+  registers them after the built-in types.
+- `./types` (optional): `native: { blocks, actions, blockMetas, icons }`.
+  `scripts/createTypeManifest.mjs` adds `native.blocks` and `native.actions`, prefixed, to the type
+  manifest with the plugin's major version, and fails when two packages give one type name.
+  `config` runs it with `--write` in the copy, so the bundled `src/plugins/typeManifest.js` lists
+  the plugins' types.
+
+`checkShellPlugins.js` refuses a plugin that links a module `@lowdefy/shell` carries itself
+(`expo-camera`) or asks for a permission some profile carries and the shell's leaves out (the camera
+on `basic`), naming the profile to pick. `config` runs it from the copied shell; `app.config.ts`
+runs it again at prebuild. `fixtures/printer-plugin` is the test plugin.
+
+## Store uploads
+
+`app.config.ts` sets what App Store Connect and Google Play would otherwise ask a person on upload:
+
+- `ios.config.usesNonExemptEncryption: false`: the shell uses only the OS's encryption.
+- `ios.privacyManifests`: the required-reason APIs of the profile's modules (`privacyReasons` in
+  `profiles.js`, where `basic` carries React Native's and expo-sqlite's), each listed once
+  (`getPrivacyManifest.js`).
+- From `shell.json` `icon` (a 1024×1024 PNG, relative to `shell.json`) and `color`: the app icon,
+  the `expo-splash-screen` image on `color`, and the Android adaptive icon on `color`. Its
+  foreground, the icon scaled into the centre 66% of a transparent canvas, is written beside
+  `shell.json` as `adaptive-icon-<hash>.png` (`scripts/createShellAssets.mjs`) once per icon.
+  Without `icon` (Lowdefy Dev) Expo's defaults stay.
+
+## Versions
+
+- `version` in `shell.json` is the store version (`major.minor.patch`), the app config's `version`.
+  Lowdefy Dev has none and builds as `0.0.0`.
+- The shell version is the `@lowdefy/shell` package version, which the runtime sends as
+  `x-lowdefy-shell` and compares with `mobile.minShellVersion`. It is `src/version/shellVersion.js`,
+  which `pnpm --filter=@lowdefy/shell shell-version` rewrites (`scripts/createShellVersion.mjs`) and
+  `pnpm release:version` rewrites after the version bump; `src/version/shellVersion.test.js` fails
+  when it is stale.
+- `runtimeVersion` is `<nativeVersion>-<profile>`, with `-<hash>` of the shell's `plugins` when it
+  lists any (`runtimeVersion.js`, a pure function `lowdefy mobile` reuses). Each plugin is keyed on
+  `name@version` and its `options` as JSON with keys sorted, so a new plugin version or option is a
+  new runtime version and a native build. An over-the-air update reaches only binaries with the same runtime version. Shell
+  identity is not part of it, so every shell on one `nativeVersion` and profile shares it.
+- `nativeVersion` in `package.json` is bumped only when the shell's native dependencies or config
+  plugins change. `pnpm check:native-version` (run by the package's tests) computes Expo's
+  fingerprint of the shell's native inputs for every profile and fails when it differs from the one
+  `native-fingerprint.json` records for the current `nativeVersion`. After a bump,
+  `pnpm check:native-version --write` records the new one.
+- With `eas`, the app config sets `owner`, `updates.url` (`https://u.expo.dev/<projectId>`) and
+  `extra.eas.projectId`.
+
+## Boot, cache and sync
+
+- The shell opens its one app at once. There is no app picker.
+- The last root config and pages the app showed are read from SQLite and rendered at once. The
+  cache is keyed by app, caller (person and organisation) and roles, from the server's
+  `x-lowdefy-caller` stamp.
+- In the background the shell fetches `GET /api/mobile/root` with `If-None-Match`, then every page
+  whose index hash changed, 4 at a time. Dynamic pages, and dev pages (no hash), are fetched on
+  each visit.
+- Every call carries `x-lowdefy-shell` (the shell's version) and the session token as a bearer
+  token, kept in the Keychain or Keystore.
+
+## Sign-in, unlock and sign-out
+
+`src/auth`. The mobile root carries the app's `mobile.auth` (null for an app without auth, which
+opens with no sign-in screen).
+
+- With nobody signed in, the native email-code screen asks for an email, then the 6-digit code
+  (iOS offers it from Mail). It always says "If this email can sign in, a code is on its way".
+  "Other ways to sign in", `emailCode: false`, a server without email codes and a second factor
+  open the app's sign-in page in an ephemeral system sheet (`/auth/mobile`, with a state, a PKCE
+  S256 challenge and the platform). Once signed in, the page asks "Sign in to <app> on this
+  device?"; Continue creates a new session for the phone and returns a one-time token for it. iOS
+  returns to the shell's scheme; Android returns by the verified app link
+  `<app url>/auth/mobile/callback`, which `app.config.ts` declares for each app url
+  (`authCallbackIntentFilters.js`) and the app's `assetlinks.json` names the shell for. The shell
+  checks the state and exchanges the one-time token with the code verifier at
+  `/api/auth/one-time-token/verify`.
+- The session token is kept in `expo-secure-store` on this device only: readable while unlocked,
+  behind biometrics with `unlock: biometric`, or readable after first unlock for the
+  `field-tracking` profile. It is read once per unlock and held in memory. Calls send no cookies.
+- `unlock: biometric` shows a lock screen on launch and after `unlockAfter` seconds in the
+  background, with "Sign in again" as the way out.
+- Sign-out, the token cleared by the core (a Logout action, a 401), and a call with the token
+  answered as the signed-out caller remove the token, every cached root and page of the app and
+  the person's storage keys, then open the app afresh. A 403 drops that caller's cache.
+  `sharedDevice: true` signs out whenever the app goes to the background.
+
+## Version skew
+
+- A page whose type set names a type the shell lacks, or carries at another major version, shows
+  "Update the app to open this page" with the store link. Other pages still open.
+- `mobile.minShellVersion` above the shell's version shows the same screen for every page.
+- A page request refused with a 409 for another build syncs the root and changed pages, then is
+  retried once when its own page did not change; otherwise the screen is rebuilt on the new page.
+- A response answered as another caller drops the screens, syncs under the new caller's key and
+  opens home.
+
+## Navigation
+
+Expo Router, with one route for every page, `app/(t0,t1,t2,t3,t4)/[...path].js`, in five route
+groups: with `mobile.menus.tabs` each tab is a group with its own native stack, under native tabs.
+A `drawer` frame is one stack with a menu button; a `stack` frame is one stack. `Link` actions go
+through the router; a link to a tab's page switches tab (with its query), and links to other sites
+open in the system browser.
+
+A `Screen` page reports its header and `src/navigation/getStackOptions.js` maps it to native stack
+options: the title, or an iOS large title (`largeTitle`) that collapses as the page scrolls; the
+presentation; a native search bar (`headerSearch`, focused on each show with `autoFocus`); and
+the `headerLeft`/`headerRight` slots and `headerActions` at their natural size. On iOS each action
+is a native bar button drawing its SF Symbol in the bar's glass, and an icon with no symbol (or
+the slot) a custom item; elsewhere a side is a row of icon buttons. A side with nothing keeps the
+stack's own (a drawer's menu button). Pull-to-refresh (`onRefresh`) and `onFocus` come from the
+page's screen: `PageScreen` passes `useIsFocused()`.
+
+Before a page is first drawn, `PageScreen` sets the bar its config gives
+(`navigation/getInitialScreenOptions.js`: a literal `largeTitle`, `headerSearch`, `title`,
+`presentation` and `backgroundTint`) and waits a frame: iOS keeps a large title collapsed when
+the page's scroll view was first laid out under a standard bar, and the Screen reports its options
+only once it renders inside that scroll view.
+
+A Screen's `headerBottom` slot pins its blocks under the bar. `PageScreen` passes `headerInset`,
+where the bar's bottom edge is in the page's scroll view: the native stack's
+`useAnimatedHeaderHeight()` (from `expo-router/native-stack`), which follows a large title as it
+collapses, when the page scrolls under the bar (`navigation/isPageUnderHeader.js`: iOS 26 and
+later, or a large title or search bar before that), and 0 when the page sits below it (Android).
+A page with a headerBottom hides the bar's own hairline; the strip draws one under itself.
+A Screen with a `backgroundTint` gets a clear bar on iOS (`headerTransparent`; before iOS 26 also
+clear at the scroll edge, with the chrome material once content scrolls under it), so the tint the
+page draws at the screen's top shows behind the bar, and the page counts as under the bar.
+
+Each screen keeps its page state per route instance (`useRoute().key`), so task B pushed on task A
+has its own, and reads `_url_query` from its own route (`routePath`). The focused screen sets the
+session's current path and instance (`setCurrentPath`), which the host's `location` and Lowdefy
+Dev's shown page (`getShownPage`, `shownScreen` in the shell's globals) read.
+
+Tabs (`mobile.menus.tabs`) draw their icons in the native tab bar, the selected tab in the theme's
+`colorPrimary`. On iOS a tab draws an SF Symbol: its `sfSymbol`, or the symbol client-native's
+`getSfSymbol` maps from its icon (`Inbox` to `tray`, `FileText` to `doc.text`, `edit` to `pencil`).
+Elsewhere, and for an icon with no symbol, `TabIconImages` draws the Lucide icon from the item's
+icon data once, out of sight, and reads it back as a PNG for the tab bar to tint. A tab with
+`role: search` is iOS 26's search tab, apart at the right of the bar with a magnifier; on Android
+and older iOS it is a tab with the search icon. Its page is a Screen with
+`headerSearch: { autoFocus: true }`.
+
+## Plugins, `_js`, locale and theme
+
+- Pages run every actions-core action and the client operators of every default operator package
+  (`src/plugins/types.js`). The actions whose web bodies reach the DOM run native bodies under the
+  same names (`src/actions`): `SetFocus` focuses the control a block registered, `ScrollTo`
+  scrolls the page's ScrollView to a block's measured place, `CopyToClipboard` uses
+  `expo-clipboard`, and the local storage actions keep the app's keys in the device store, from
+  which sign-out clears the user keys. `SetDarkMode` and `SetLocale` keep their actions-core
+  bodies: they call the window members the theme provider and the shell's locale set.
+- `_js` reaches the shell as module text: a page's `_jsEntries`, and the root's for the app
+  events. `src/js/evaluateJsEntries.js` is the one place it becomes functions, with
+  `new Function`.
+- The app's locale is chosen as on the web: the `SetLocale` choice the device keeps, the device's
+  locale the app supports, the app's default. Every dayjs locale is bundled
+  (`src/locale/dayjsLocales.js`, written by `scripts/createDayjsLocales.mjs`) and loaded when
+  used.
+- One theme provider holds the theme mode for every screen, from the root's `theme` and the
+  `SetDarkMode` choice; the root's `classMap`, with a dev page's own `_classMap`, styles classes.
+- Block icons are drawn from the icon data each page carries (`_icons`), which `PageScreen` adds
+  to the icon map client-native's `components.Icon` reads (`types.icons`).
+- Menu icons are drawn from the icon data the root carries: with client-native's `Icon` in the
+  drawer menu, and as SF Symbols or images in the tab bar (see Navigation).
+- Hermes has no `crypto.getRandomValues`, which `_uuid` needs; `expo-crypto` fills it.
+
+## Lowdefy Dev
+
+`src/dev`. Lowdefy Dev is this shell built as the `dev` variant: `LOWDEFY_SHELL_VARIANT=dev | release`
+(`shellVariant.js`), `dev` by default for Lowdefy Dev (no `LOWDEFY_SHELL_CONFIG`) and `release` for
+every other shell. A release bundle resolves `src/dev/index.js` to an empty module
+(`metro.config.js`), so a customer shell carries none of it. Every shell
+leaves out the native modules its profile does not carry, and a release shell also leaves out
+Lowdefy Dev's own (`expo-sensors`, `react-native-view-shot`, `expo-dev-client`) whatever its profile
+(`getExclusions` in `shellVariant.js`): a `basic` shell links no `expo-camera`. `app.config.ts`
+leaves out their config plugins and blocks their Android permissions, `withExcludedNativeModules.js`
+passes them as exclusions to Expo autolinking in the generated Podfile and settings.gradle, and
+`metro.config.js` resolves the left-out profiles' JavaScript entries to empty modules.
+
+`pnpm check:release-bundle` checks a release shell (Lowdefy Dev's, or the one
+`LOWDEFY_SHELL_CONFIG` names) on each release profile (`--profile` names one) and both platforms:
+its bundle holds neither the dev-tab client's marker string nor a left-out module's native name,
+and an `expo prebuild` of it links none of the left-out modules and asks for none of their
+permissions. `--control` first checks that the `dev` variant holds and links them.
+
+- **Connect.** `lowdefy-dev://connect?url=<server>&pair=<token>` (the QR code `lowdefy dev --lan`
+  prints, or the link `--ios`/`--android` open), a scanned code (`expo-camera`), a typed address, or
+  one of the last 5 servers. A server not on this device is confirmed first ("Connect to
+  `<host>`?"); a simulator's or USB phone's localhost connects at once. Lowdefy Dev opens one dev
+  server at a time; switching server closes the open app. Each server is its own app, with its own
+  cache and session, and every call to it (fetch and websocket) carries its pairing
+  token as `x-lowdefy-pair`.
+- **Shake menu** (or `lowdefy-dev://menu`): reload, switch server, clear data, show logs, the block
+  gallery, and the shell version.
+- **Dev-tab client.** The open app joins the dev server's tab channel as a browser tab does: it
+  registers on `/api/reload` (an event stream read from `expo/fetch`, or polls of
+  `/api/reload?transport=poll` every second when the stream cannot be read), posts the page it shows
+  to `/api/dev-inspect/page`, and answers on `/api/dev-inspect`:
+  - `reload`: refetches the root and the page on screen and rebuilds the screens with empty page
+    state, staying on the page.
+  - `inspect-request`, `eval-request`: the browser tab's payloads (shared fixtures with the dev
+    server's tests).
+  - `step-request` `{ step }`: a journey step by block id (`click`, `fill`, `select`,
+    `press: 'Enter'`, `wait`, `screenshot`), run through the engine; it waits for the action chain
+    to settle. A screenshot is the root view as a base64 PNG (`react-native-view-shot`).
+  - `inject` `{ inject: { kind, value, name } }`: fakes the next device result
+    (`src/dev/inject`): `scan` `{ data, type }`, `photo` `{ base64, ... }` and `nfc` for the next
+    read; `transcript` `{ partials?, final }` or `{ error }` for the next dictation session, which
+    plays the partials and the final a moment apart, while a session with nothing injected uses
+    the microphone (blocks-native's `installDictationSource`, which Lowdefy Dev fills with
+    `injected`; `permission` `microphone` answers its prompt);
+    `location` `{ latitude, longitude, ... }`, or a route as a list, read one at a time with
+    the last one staying; `permission` with `name` and `'granted' | 'denied'`, standing until
+    changed; `network` `'offline' | 'online'`, which fails the app's every fetch as offline (the tab
+    client keeps its own) and takes the shell's online state offline (`src/host/networkStatus.js`,
+    which expo-network also feeds), so the NoConnection banner shows and the app's `offline` events
+    fire; `clear`. `push` is refused until the shell carries expo-notifications.
+    Device actions read these with `injected(name)` (`src/device/injected.js`), which returns
+    nothing in a release shell; `GeolocationCurrentPosition` answers with an injected location.
+- **Recorder** (`src/dev/recorder`). What the developer does is recorded as the web recorder records
+  it: the engine trace's events paired with the presses and changes client-native reports by block
+  id, a pageview when the page on screen changes, password inputs redacted, each record labelled
+  `device: ios | android` and `shell_version`, posted to `/api/dev-recording`. `lowdefy journeys
+session` lists and prints phone sessions as it does browser ones.
+
+## Checks
+
+```bash
+pnpm --filter=@lowdefy/shell test         # Jest, and the hello fixture build
+pnpm --filter=@lowdefy/shell export:ios     # Metro and Hermes bundle, no simulator needed
+pnpm --filter=@lowdefy/shell export:android
+pnpm --filter=@lowdefy/shell check:release-bundle   # each release profile links only its modules
+pnpm --filter=@lowdefy/shell check:native-version   # native code changed only with a nativeVersion bump
+```

package/app/(t0,t1,t2,t3,t4)/[...path].js

@@ -0,0 +1,38 @@
+/*
+  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 { useLocalSearchParams } from 'expo-router';
+import { serializeQuery } from '@lowdefy/client-core';
+
+import getTabHref from '../../src/navigation/getTabHref.js';
+import PageScreen from '../../src/components/PageScreen.js';
+import SwitchToTab from '../../src/components/SwitchToTab.js';
+import { useSessionState } from '../../src/ShellContext.js';
+
+// Every Lowdefy page, by path. The page and its path params come from the page index; the route's
+// other params are the page's query. A tab's own page is shown on its tab, not stacked here.
+export default function PathRoute() {
+  const { path, ...query } = useLocalSearchParams();
+  const { root } = useSessionState();
+  const segments = Array.isArray(path) ? path : [path];
+  const pagePath = segments.join('/');
+  const tabHref = getTabHref({ path: pagePath, query: serializeQuery(query), root });
+  if (tabHref !== null) {
+    return <SwitchToTab href={tabHref} />;
+  }
+  return <PageScreen path={pagePath} query={serializeQuery(query)} />;
+}

package/app/(t0,t1,t2,t3,t4)/_layout.js

@@ -0,0 +1,48 @@
+/*
+  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 { Stack } from 'expo-router';
+
+import getFrame from '../../src/navigation/getFrame.js';
+import { getSlotIndex } from '../../src/navigation/frameSlots.js';
+import MenuButton from '../../src/components/MenuButton.js';
+import SlotContext from '../../src/navigation/SlotContext.js';
+import { useSessionState } from '../../src/ShellContext.js';
+
+// A deep link opens on top of the group's first screen, so back leads to it.
+export const unstable_settings = { initialRouteName: 'index' };
+
+// The stack of one frame group (a tab, or the app's one stack). A drawer frame puts its menu
+// button in the header of the group's first screen. Expo Router passes the group's own segment,
+// such as `(t1)`, to a layout shared by several groups; its screens read the group from SlotContext.
+export default function GroupLayout({ segment }) {
+  const { root } = useSessionState();
+  const frame = getFrame(root.menus);
+  return (
+    <SlotContext.Provider value={getSlotIndex(segment)}>
+      <Stack screenOptions={{ title: '' }}>
+        <Stack.Screen
+          name="index"
+          options={
+            frame.kind === 'drawer' ? { headerLeft: () => <MenuButton items={frame.items} /> } : {}
+          }
+        />
+        <Stack.Screen name="[...path]" />
+      </Stack>
+    </SlotContext.Provider>
+  );
+}

package/app/(t0,t1,t2,t3,t4)/index.js

@@ -0,0 +1,38 @@
+/*
+  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, { useContext } from 'react';
+import { useLocalSearchParams } from 'expo-router';
+import { serializeQuery } from '@lowdefy/client-core';
+
+import getSlotRootPath from '../../src/navigation/getSlotRootPath.js';
+import MessageScreen from '../../src/components/MessageScreen.js';
+import PageScreen from '../../src/components/PageScreen.js';
+import SlotContext from '../../src/navigation/SlotContext.js';
+import { useSessionState } from '../../src/ShellContext.js';
+
+// The first screen of a frame group: its tab's page, or the app's home page. A link to a tab's
+// page switches to the tab (toRouterHref) with its query as the route's params.
+export default function GroupIndex() {
+  const slotIndex = useContext(SlotContext);
+  const query = useLocalSearchParams();
+  const { root } = useSessionState();
+  const path = getSlotRootPath({ root, slotIndex });
+  if (path === null) {
+    return <MessageScreen testID="shell-no-home" title="This app has no page to open" />;
+  }
+  return <PageScreen path={path} query={serializeQuery(query)} />;
+}