@axonpack/preview 0.0.0-stage → 0.1.0

package/ios/PreviewState.swift

@@ -0,0 +1,236 @@
+import Foundation
+import React
+import os
+
+let previewLog = Logger(subsystem: "dev.axonpack.preview", category: "AxonpackPreview")
+
+/**
+ Which bundle the next start should load. JS writes `state.json` under the app's Documents folder
+ (what expo-file-system calls the documents directory), and native only ever reads it. The bundle
+ path in it is relative, because the app's container path changes when the app is updated.
+ */
+enum PreviewState {
+  static var root: URL? {
+    FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first?
+      .appendingPathComponent("preview", isDirectory: true)
+  }
+
+  /// Previews need the New Architecture; under the old one only the base bundle ever loads.
+  static var newArchitecture: Bool { RCTIsNewArchEnabled() }
+
+  static func warnOldArchitecture() {
+    previewLog.warning("@axonpack/preview needs the New Architecture, so the selected preview is ignored and the base bundle loads")
+  }
+
+  /// The selected preview if this app can run it, else nil for the base bundle.
+  static func bundleToLoad() -> URL? {
+    guard let preview = selectedBundle() else {
+      return nil
+    }
+    guard madeForThisBuild() else {
+      return nil
+    }
+    guard newArchitecture else {
+      warnOldArchitecture()
+      return nil
+    }
+    if let embedded = embeddedHermesVersion, let version = hermesVersion(of: preview), embedded != version {
+      previewLog.warning("The preview is Hermes bytecode \(version) but this build runs \(embedded), so the base bundle loads")
+      return nil
+    }
+    guard claimStart() else {
+      return nil
+    }
+    return preview
+  }
+
+  /// The bundle inside the app was compiled by the Hermes this build runs. A debug build has none,
+  /// and then nothing is checked.
+  static let embeddedHermesVersion: UInt32? = Bundle.main.url(forResource: "main", withExtension: "jsbundle")
+    .flatMap { hermesVersion(of: $0) }
+
+  /// Hermes bytecode starts with an 8-byte magic number, then its format version as a 32-bit int.
+  /// Nil for anything else, such as a plain JS bundle.
+  static func hermesVersion(of url: URL) -> UInt32? {
+    guard let handle = try? FileHandle(forReadingFrom: url) else {
+      return nil
+    }
+    defer { try? handle.close() }
+    guard let header = try? handle.read(upToCount: 12), header.count == 12 else {
+      return nil
+    }
+    let magic: [UInt8] = [0xc6, 0x1f, 0xbc, 0x03, 0xc1, 0x03, 0x19, 0x1f]
+    guard Array(header.prefix(8)) == magic else {
+      return nil
+    }
+    return header.suffix(4).enumerated().reduce(UInt32(0)) { $0 | UInt32($1.element) << (8 * UInt32($1.offset)) }
+  }
+
+  // Crash fallback. Every JS start has its own token. A preview start writes it into the state as
+  // `pending`, and JS clears it once the app has mounted. Finding someone else's token means an
+  // earlier start of this preview never got that far, so the preview is marked broken and the base
+  // bundle loads instead. Several lookups in one start see their own token and change nothing.
+  private static let processToken = UUID().uuidString
+  private static var starts = 0
+  private static var token: String { "\(processToken):\(starts)" }
+
+  /// Called before a reload, so the next start has a token of its own.
+  static func nextStart() {
+    starts += 1
+  }
+
+  private static var stateURL: URL? { root?.appendingPathComponent("state.json") }
+
+  private static func readJson() -> [String: Any] {
+    guard
+      let stateURL,
+      let data = try? Data(contentsOf: stateURL),
+      let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+    else {
+      return [:]
+    }
+    return json
+  }
+
+  private static func writeJson(_ json: [String: Any]) {
+    guard let root, let stateURL else {
+      return
+    }
+    try? FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+    try? JSONSerialization.data(withJSONObject: json).write(to: stateURL, options: .atomic)
+  }
+
+  private static func claimStart() -> Bool {
+    var json = readJson()
+    let pending = json["pending"] as? String ?? ""
+    if pending == token {
+      return true
+    }
+    if !pending.isEmpty {
+      let id = (json["bundle"] as? String ?? "").components(separatedBy: "/").first ?? ""
+      previewLog.warning("The preview \(id, privacy: .public) stopped before it finished starting, so it is marked broken and the base bundle loads")
+      json["broken"] = (json["broken"] as? [String] ?? []) + [id]
+      json["bundle"] = nil
+      json["pending"] = nil
+      writeJson(json)
+      return false
+    }
+    json["pending"] = token
+    writeJson(json)
+    return true
+  }
+
+  /// The key the config plugin baked into this build; nil without the plugin.
+  private static var buildKey: String? {
+    Bundle.main.object(forInfoDictionaryKey: "AxonpackPreviewKey") as? String
+  }
+
+  /// A preview chosen on an earlier build (the app was updated since) is not loaded: with app
+  /// version matching, a new version is a new native build. The choice is cleared, so the app and
+  /// the list both show the base bundle. Without a key on either side there is nothing to compare.
+  private static func madeForThisBuild() -> Bool {
+    var json = readJson()
+    guard let chosenFor = json["key"] as? String, let build = buildKey, chosenFor != build else {
+      return true
+    }
+    previewLog.warning("The chosen preview was made for build \(chosenFor, privacy: .public) but this is \(build, privacy: .public), so the base bundle loads")
+    json["bundle"] = nil
+    json["key"] = nil
+    json["pending"] = nil
+    writeJson(json)
+    return false
+  }
+
+  /// JS calls this once the app has mounted: this start worked.
+  static func confirmStart() {
+    var json = readJson()
+    if json["pending"] as? String == token {
+      json["pending"] = nil
+      writeJson(json)
+    }
+  }
+
+  /// Records the choice for the next start or reload. Nil clears it, so the base bundle loads. The
+  /// path is relative to the preview folder and must stay inside it. Choosing a preview again takes
+  /// it off the broken list, since it may have been fixed and downloaded again.
+  static func select(_ bundle: String?, key: String? = nil) throws {
+    guard let root else {
+      return
+    }
+    var json = readJson()
+    json["pending"] = nil
+    if let bundle {
+      guard root.appendingPathComponent(bundle).standardizedFileURL.path.hasPrefix(root.standardizedFileURL.path + "/") else {
+        throw PreviewPathOutsideException()
+      }
+      let id = bundle.components(separatedBy: "/").first ?? ""
+      json["bundle"] = bundle
+      json["key"] = key
+      json["broken"] = (json["broken"] as? [String] ?? []).filter { $0 != id }
+    } else {
+      json["bundle"] = nil
+      json["key"] = nil
+    }
+    writeJson(json)
+  }
+
+  // Local Metro servers (debug builds only). `localServer` sits next to the preview fields and
+  // never changes them, so stopping a local server brings back whatever preview was chosen.
+
+  /// The chosen local server's bundle URL, or nil; always nil in a release build.
+  static var localServerURL: URL? {
+    #if DEBUG
+    guard
+      let server = readJson()["localServer"] as? [String: Any],
+      let url = server["url"] as? String
+    else {
+      return nil
+    }
+    return URL(string: url)
+    #else
+    return nil
+    #endif
+  }
+
+  static func selectLocalServer(_ url: String?) {
+    var json = readJson()
+    if let url {
+      json["localServer"] = ["url": url]
+    } else {
+      json["localServer"] = nil
+    }
+    writeJson(json)
+  }
+
+  /// The raw choice and the broken list, for JS to show.
+  static func read() -> [String: Any?] {
+    let json = readJson()
+    return [
+      "bundle": json["bundle"] as? String,
+      "broken": json["broken"] as? [String] ?? [],
+      "localServer": (json["localServer"] as? [String: Any])?["url"] as? String,
+    ]
+  }
+
+  /// Nil means "load the base bundle", which is also the answer to anything unexpected.
+  static func selectedBundle() -> URL? {
+    guard let root, let data = try? Data(contentsOf: root.appendingPathComponent("state.json")) else {
+      return nil
+    }
+    guard
+      let state = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+      let relative = state["bundle"] as? String, !relative.isEmpty
+    else {
+      previewLog.warning("Could not read the preview state, loading the base bundle")
+      return nil
+    }
+    let bundle = root.appendingPathComponent(relative).standardizedFileURL
+    // A path like "../x" must not let the state point outside our own folder.
+    let inside = bundle.path.hasPrefix(root.standardizedFileURL.path + "/")
+    guard inside, FileManager.default.fileExists(atPath: bundle.path) else {
+      previewLog.warning("Selected bundle \(relative, privacy: .public) is missing, loading the base bundle")
+      return nil
+    }
+    return bundle
+  }
+}

package/notes/README.md

@@ -0,0 +1,36 @@
+# @axonpack/preview notes
+
+Scope: this package only. One note per area, and **each one owns its own feature status**: what is
+built, what is not, and what never will be. There is no combined list anywhere; a second copy would
+only disagree with these.
+
+| Note                                               | Covers                                                            |
+| -------------------------------------------------- | ----------------------------------------------------------------- |
+| [bundles.md](./bundles.md)                         | Building a preview bundle, and which native build it can run on   |
+| [native-loader.md](./native-loader.md)             | Starting the app from a downloaded bundle, and getting back again |
+| [distribution.md](./distribution.md)               | Publishing a preview so installed apps can find it                |
+| [storage.md](./storage.md)                         | Where previews are kept, and running a local S3 to test with      |
+| [testing.md](./testing.md)                         | Running the example end to end on your own machine                |
+| [dev-preview-servers.md](./dev-preview-servers.md) | Several local Metro servers for one app, switched live (debug)    |
+
+To run the example end to end without a cloud account, follow [testing.md](./testing.md).
+
+## How to edit an area note
+
+- **Features first**, as a checklist: `- [x]` for shipped, `- [ ]` for not built yet. One
+  plain-English line each, no sub-lists, no paragraphs.
+- **Describe a feature from the outside**: what someone using the package gets. No file names, no
+  function or option names, and no explanation of how it works. That belongs in the prose below the
+  checklist and in the code comments.
+- **Prose after the checklist** carries the design: how it works, and the decisions that constrain
+  it. Why, not what.
+- **Won't do goes last**, for what the platform makes impossible. No checkboxes there, because nothing in
+  it is waiting to be built. Move a line there instead of deleting it, so the reason survives. If
+  something becomes possible, move it back up as `- [ ]`.
+- **A feature belongs to exactly one note.** If two notes would list it, one of them is wrong.
+- New work goes in the note for its area; only a genuinely new surface earns a new note, and a new
+  note earns a row in the table above.
+
+The writing rules that apply to every note in the repo, and how the symlinks under
+`notes/@axonpack/` work, are in
+[the repo's notes guide](https://github.com/axonpack/axonpack/blob/main/notes/README.md).

package/notes/bundles.md

@@ -0,0 +1,35 @@
+# Bundles
+
+Building a preview bundle, and which native build it can run on.
+
+- [x] Builds the same release bundle and images the native build would embed, for Android and iOS
+- [x] Names a preview after its branch, with a readable title QA sees
+- [x] Marks every preview with the native build it was made for, so an app only ever offers ones it can run
+- [x] Lets the developer match previews to builds by app version (the default) or by native fingerprint
+
+A preview is the output of `expo export:embed --bytecode`: Hermes bytecode plus the images next to
+it, in the folders the native build uses. React Native finds images beside a bundle loaded from a
+file, so nothing in JS has to map them.
+
+Bytecode runs only on a build with the same native code and the same Hermes version. Each build
+gets a key, and the app lists only previews published under its own key. The developer picks how
+the key is made, with one option in the app config that the build and `publish` both read:
+
+```json
+"plugins": [["@axonpack/preview", { "compatibility": "appVersion" }]]
+```
+
+| `compatibility`        | Key                     | Pick it when                                                                                               |
+| ---------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `appVersion` (default) | `version-<app version>` | You bump the version for every native change. Simple, and readable in the bucket                           |
+| `fingerprint`          | `fingerprint-<hash>`    | Native changes can land without a version bump. Exact, the same hash expo-updates' fingerprint policy uses |
+
+The trade-off of `appVersion`: a native change without a version bump is not detected, so a preview
+built on the old native code is still offered. Two things catch most of the damage: a preview whose
+Hermes bytecode version differs from the build's is not loaded, and a preview that fails while
+starting falls back to the base bundle and is marked broken. `publish` prints a one-line warning in
+this mode. With `fingerprint`, any native change (a new native dependency, a config plugin change,
+a prebuild with different settings) makes older previews incompatible.
+
+A preview chosen on one build is not started by a later build with another key; the app starts the
+base bundle and the download moves to Incompatible.

package/notes/dev-preview-servers.md

@@ -0,0 +1,67 @@
+# Dev preview servers
+
+Several Metro servers for the same app, one per task or worktree, and one debug build that switches
+between them live.
+
+- [x] Lists every Metro server for this app on the developer's computer, in a debug build
+- [x] Finds plain `expo start` servers, and servers started with `preview start` with their branch
+- [x] Shows a new server within about two seconds, and drops one that stopped
+- [x] Leaves out other apps' servers; keeps the same app built for other native code, marked
+- [x] Switches the running app to a server, and back, with no rebuild
+- [x] Starts Metro on a free port and announces it with one command, `preview start`
+- [x] Asks for the name the app shows, prefilled from the branch (`--title` or no terminal skips it)
+- [x] Off unless the app turns it on, and never in a release build
+- [x] Only this app's servers, by the slug the config plugin bakes in; a build without it says so
+
+## Turning it on
+
+```ts
+<PreviewProvider config={{ ...config, devPreviewServers: true }}>
+```
+
+It is one switch, off by default, and only shows in a debug build. Nothing else is set: the app probes
+ports 8081 to 8099, asks the registry on port 19150 (the same constant `preview start` uses, in
+`src/constants/dev-preview-servers/dev-preview-servers.const.ts`), looks on the host its own Metro is on (plus `10.0.2.2` on the
+Android emulator), and lists only servers for the slug the config plugin baked into the build. A
+build made without the plugin has no slug, and the section says so instead of listing anything.
+
+## How it works
+
+**Running it.** In the example, `bun run start:preview` (or `bunx preview start`).
+
+**The name.** In a terminal, `preview start` asks for the name the app's list shows, prefilled with
+the branch's readable title (`task-1-login-fix` becomes "Task 1 login fix"). Enter keeps it, or edit
+it first. `--title <name>` skips the question, and so does a run with no terminal (CI, an AI agent),
+which takes the branch title. `publish` asks the same way for the title QA sees.
+
+**Two sources.** `preview start` runs `expo start` on a free port and announces it to a small
+registry on the computer (started by the first `start`, gone once no server is left), with the
+branch, worktree and the native key `publish` would use. Heartbeats every 5 s keep it listed; it
+drops out 15 s after the last, so a killed process goes too. Plain `expo start` servers are found
+by probing the port range for Metro's `/status`; each one's Expo manifest then gives its slug,
+name, version and bundle URL. A server found both ways uses the registry's details. While the list
+is on screen the app looks every 2 s, and never starts a look while the last one runs. A probe gives
+up after 2 s: Android sends 5 requests per host at a time and the emulator takes about 400 ms to
+refuse a closed port, so a tighter limit dropped live servers there. A closed port on the computer
+itself fails at once, so the scan stays cheap.
+
+**Which servers.** Only the app's own slug, which the config plugin bakes into the build. A server
+for the same app but another native key (another app version, or another fingerprint) is listed and
+marked, since a developer may still want it. A plain server in fingerprint mode shows "native build
+unknown", because its manifest does not carry a fingerprint.
+
+**Reaching it.** The app probes the host its own Metro is on. On the Android emulator it also tries
+`10.0.2.2`, which reaches the computer with no `adb reverse`. A phone on USB needs `adb reverse`,
+which `preview start` runs for its port and the registry's when `adb` is on the PATH. A phone
+on Wi-Fi was started from the computer's LAN address, so the same rule finds the others.
+
+**Switching.** The choice is stored next to the preview choice and never changes it. On every start
+of a debug build the dev preview server wins, then a downloaded preview, then the default Metro. Android
+points React Native's dev support at the server (and puts the developer's own dev-menu host back
+afterwards); iOS starts from the server's bundle URL. "Stop using dev preview server" brings back what ran
+before, a chosen preview included; "Back to base" stops both.
+
+## Won't do
+
+- Run in a release build. There is no Metro there, and a release build ignores the setting even if it
+  is in the saved state.

package/notes/distribution.md

@@ -0,0 +1,138 @@
+# Distribution
+
+Publishing a preview so installed apps can find it.
+
+- [x] Publishes a preview from the developer's machine with one command
+- [x] Replaces a preview when the same branch is published again
+- [x] Gives every preview a changelog, from the branch's commits unless one is passed in
+- [x] Keeps one list per native build for the app, and one list of everything for people
+- [x] Removes a preview, and cleans up files nothing uses any more
+- [x] Runs against a local S3 server while developing
+
+Previews go to an S3-compatible bucket: S3, R2, MinIO or any other host with the S3 API. The app
+gets the endpoint, the bucket and, for a private bucket, a read-only key from the config it passes
+in.
+
+## Commands
+
+Run from the app's root (`--project <dir>` otherwise). `preview --help` lists every option.
+
+```sh
+npx preview publish                  # id = git branch, both platforms; asks for the title
+npx preview publish --id task-1 --changelog="- Fixes the login"
+npx preview unpublish task-1
+npx preview prune
+```
+
+`publish` builds with `expo export:embed --dev false --bytecode`, the same step a release build
+runs, so the bundle is Hermes bytecode with its images beside it. It reads the `compatibility`
+option from the app config (see [bundles.md](./bundles.md)), builds the same key the app was built
+with, records the app version and the native fingerprint either way, uploads each file once under
+its sha256, writes the preview's manifest, and only then adds it to the lists. `--compatibility`
+overrides the option, with a warning, since a build of the app would then not list the preview. An app never sees a preview whose files
+are not all there. The changelog is the commit subjects since the branch left the base branch
+(`--base`, default: the repo's default branch); `--changelog=<text>` or `--changelog-file` replace it.
+
+### EAS environment
+
+`--environment <name>` builds with an EAS environment's variables, like `eas update --environment`:
+
+```sh
+npx preview publish --environment preview
+```
+
+It runs `eas env:pull --environment <name> --non-interactive` into a temp folder outside the app,
+reads the file and deletes it. The values go into the environment of everything publish runs that
+reads the app config: the config itself (app version, slug), the fingerprint and `expo
+export:embed`, so the key matches a build made in that environment. A variable already set in the
+shell wins over the EAS one. Without the flag nothing changes and eas-cli is never called.
+
+It needs eas-cli installed, a login (`eas login`, or `EXPO_TOKEN` in CI) and the app linked to an
+EAS project (`eas init`); publish says which one is missing. Variables with **secret** visibility
+are never readable outside EAS servers: `eas env:pull` leaves them out (as a comment), so set them
+in the shell if the bundle needs them. Plain text and sensitive ones come through. A file-type
+variable is written by `eas env:pull` itself into the app's `.eas/.env/` folder, and its value is
+that file's path.
+
+## CI
+
+[`ci/github-actions/`](../ci/github-actions/) has a sample GitHub Actions workflow for each
+package manager. Copy the one that matches your app's lockfile into `.github/workflows/`; GitHub
+does not run them from this package.
+
+| Lockfile            | File to copy                                                |
+| ------------------- | ----------------------------------------------------------- |
+| `bun.lock`          | [`preview.bun.yml`](../ci/github-actions/preview.bun.yml)   |
+| `package-lock.json` | [`preview.npm.yml`](../ci/github-actions/preview.npm.yml)   |
+| `pnpm-lock.yaml`    | [`preview.pnpm.yml`](../ci/github-actions/preview.pnpm.yml) |
+| `yarn.lock`         | [`preview.yarn.yml`](../ci/github-actions/preview.yarn.yml) |
+
+All four have the same jobs; only the setup, install and run steps differ. The yarn file uses
+`yarn install --immutable` (Yarn 2 and later); for Yarn 1 change it to `--frozen-lockfile`. It
+publishes each pull request when it is opened, pushed to or reopened, with the branch name as the
+id and the pull request's base branch for the changelog. Pull requests from forks get no secrets,
+so it only works for branches in the repo.
+
+Repository secrets it reads:
+
+| Secret                         | Needed                                          |
+| ------------------------------ | ----------------------------------------------- |
+| `PREVIEW_S3_URL`               | yes                                             |
+| `PREVIEW_S3_ACCESS_KEY_ID`     | yes                                             |
+| `PREVIEW_S3_SECRET_ACCESS_KEY` | yes                                             |
+| `PREVIEW_S3_REGION`            | no, default `us-east-1`                         |
+| `EXPO_TOKEN`                   | only for `--environment` (an Expo access token) |
+
+Without EAS variables, drop the `expo/expo-github-action` step, `EXPO_TOKEN` and `EAS_ENVIRONMENT`.
+
+### Run by hand
+
+Each workflow also has a `workflow_dispatch` trigger, for publishing any branch, or removing a
+preview, without a pull request. Run it from the Actions tab
+([GitHub's guide](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow)). Its inputs:
+
+| Input         | Values                                      | Meaning                                                       |
+| ------------- | ------------------------------------------- | ------------------------------------------------------------- |
+| `action`      | `publish` (default), `unpublish`            | Which job runs                                                |
+| `id`          | any, optional                               | The preview id. Empty means the branch the run was started on |
+| `platform`    | `all` (default), `android`, `ios`           | Publish only                                                  |
+| `environment` | `preview` (default), or any EAS environment | Passed as `--environment`. Empty means no `--environment`     |
+
+A dispatched publish counts the changelog from the repository's default branch. A pull request
+run always uses `--environment preview`.
+
+### Unpublish on close (optional)
+
+When a pull request closes, merged or not, the `unpublish` job removes its preview from every
+build's list. The job is optional. To keep previews after close, do one of these in your copy of
+the workflow:
+
+- remove `closed` from the trigger's `types` (a dispatch can still unpublish)
+- delete the `unpublish` job
+- change the job's condition to `if: false`
+
+The last two also turn off unpublishing by dispatch.
+
+Then remove previews by hand with `preview unpublish <id>`, and delete the files no preview uses
+any more with `preview prune`.
+
+## Layout
+
+```
+index.json                            every native build and its previews, for people
+index/<platform>/<key>.json           what one native build can run; the app reads this
+previews/<platform>/<key>/<id>.json   one preview's manifest: files, changelog, versions
+files/<sha256>                        bundle and image blobs, shared between previews
+```
+
+`<key>` is `version-1.0.0` or `fingerprint-<hash>`. Every manifest and index entry also records the
+compatibility setting, the app version and the native fingerprint, so `index.json` can group builds
+by version whichever setting made them.
+
+```
+
+```
+
+Both lists are read, changed and written back only if nobody wrote in between (`If-Match` on the
+ETag, or `If-None-Match: *` for a new file). A clash reads again and retries, so two publishes at
+once both end up listed. `unpublish` leaves files in place; `prune` deletes the ones no manifest uses.

package/notes/native-loader.md

@@ -0,0 +1,56 @@
+# Native loader
+
+Starting the app from a downloaded bundle, and getting back again.
+
+- [ ] Starts the app from the chosen preview, with no change to the app's native code
+- [ ] Switches to another preview or back to the base build with one restart
+- [ ] Works in debug builds too: a chosen preview loads instead of Metro, and going back to the base build returns to Metro
+- [x] Falls back to the base build when a preview crashes before it has started
+- [ ] Works next to expo-updates, which keeps managing the base build
+- [ ] Needs the New Architecture; under the old one it logs a warning and always loads the base build
+
+Previews need React Native's New Architecture, the default from Expo SDK 53. Under the old one the
+package never loads a preview: it logs one warning and the base bundle loads, so the app still
+starts.
+
+In a debug build the base is whatever Metro serves. While a preview is chosen it loads from the
+device and Metro is not asked; going back to the base reloads from Metro.
+
+If a preview fails before the app has mounted, it is marked broken and the base bundle loads. On
+Android that happens straight away: the app restarts into the base bundle. On iOS the failed preview
+leaves a blank screen until the app is closed and opened again, and that next start is the base
+bundle. Errors that do not come from a starting preview are thrown on as usual, so the app behaves as
+it would without this package.
+
+With no preview chosen, the package changes nothing at startup: expo-updates, or the bundle inside
+the app, loads as usual.
+
+expo-updates is placed ahead of every other module on both platforms, so this package is never
+asked first. On Android a chosen preview is also put straight into React's host, in the private
+field expo-dev-launcher uses, so it wins even after expo-updates has applied a downloaded update; if
+that field is missing, the base loads and a warning says why. On iOS, while expo-updates is active,
+the base bundle starts and the app reloads once straight into the preview. Going back to the base
+hands the start back to expo-updates.
+
+## Testing next to expo-updates
+
+The example leaves expo-updates out, so its default setup stays small. To try the two together:
+
+1. In `example/`, run `npx expo install expo-updates`.
+2. Add to `app.json` under `expo`, so expo-updates is on in release builds but never asks the
+   network and always starts its embedded update:
+   ```json
+   "runtimeVersion": "1.0.0",
+   "updates": {
+     "url": "https://localhost.invalid/preview-example",
+     "checkAutomatically": "NEVER",
+     "fallbackToCacheTimeout": 0
+   }
+   ```
+3. `npx expo prebuild`, then a release build: `npx expo run:android --variant release` or
+   `npx expo run:ios --configuration Release`.
+4. With no preview chosen, the app shows the embedded bundle. Choose a preview: it loads, and again
+   after closing and reopening the app. Go back to the base: the embedded bundle loads.
+5. To check the case where expo-updates has applied a downloaded update, point `updates.url` at a
+   real update server (EAS Update, or your own), publish an update, let the app apply it, then
+   repeat step 4. Going back to the base should load that update.