catalyst-core 1.2.0-canary.3 → 1.2.0-canary.5

package/changelog.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [1.2.0] - Unreleased
+
+This release builds, runs and releases the Android and iOS apps from the CLI, without opening Android Studio or Xcode. The web runtime has no breaking changes. Universal apps should read the breaking changes below and the 1.1.x to 1.2.0 section of the Version Upgrades guide. After upgrading, run `npm audit fix`: the `body-parser` floor is raised to `^1.20.9`.
+
+### One command to run, one to release
+
+New apps have four scripts. `npm run android` and `npm run ios` check the toolchain and install what is missing after asking, start the dev server when nothing answers on `NODE_SERVER_PORT`, and build, install and open the app on an emulator, simulator or phone. Android also saves the app as a debug APK in `build-output/android/debug/` that can be shared. `npm run android:release` writes a signed App Bundle, a signed APK and `upload_certificate.pem` to `build-output/android/<version>-<build>/`, and `npm run ios:release` writes a signed IPA and a zip of its dSYMs to `build-output/ios/<version>-<build>/`. The scripts run `catalyst buildApp:android` and `catalyst buildApp:ios`, with `--release` for the store builds, so older apps keep `buildApp:<platform>` and build a release with `npm run buildApp:<platform> -- --release`. `setupEmulator:android` and `setupEmulator:ios` still work and are no longer needed.
+
+### App config
+
+A native app needs `WEBVIEW_CONFIG.appId`, `appName` and `url`. `appId` is the Android application id and the iOS bundle id, and `android.packageName` and `ios.bundleIdentifier` (then `ios.appBundleId`) win over it. `url` is the deployed site a release opens; debug builds load the dev server. New apps get `appId` and `appName` from the project name. A release run in a terminal asks once for an app id or website that is missing or a placeholder, and saves the answer to `config/config.json`.
+
+### Signing
+
+Signing files live in `credentials/android/` and `credentials/ios/`, which new apps keep out of git. The first Android release in a terminal creates one upload key per app after asking; back it up, because Google Play only accepts updates signed with it. `npx catalyst credentials:export <platform>` prints the folder as one value for the `CATALYST_ANDROID_CREDENTIALS` or `CATALYST_IOS_CREDENTIALS` CI secret. On a Mac signed in to Xcode, an iOS release signs with the Apple account or an installed App Store profile and needs no files; the order the build tries is in the iOS release guide. The version comes from `package.json`, and the build number is `CATALYST_BUILD_NUMBER` or the minutes since 2024-01-01 UTC. Android apps target API 36 and align their native libraries for 16 KB memory pages.
+
+### Breaking changes
+
+- An iOS bundle id with an underscore fails with `NATIVE-010`. Set `ios.bundleIdentifier` to an id without one.
+- A release with a placeholder app id (any `com.example.` id or a template id) fails with `NATIVE-003`. A release whose start URL is `localhost`, a private or link-local address, a `.local` name or this machine fails with `NATIVE-001`, unless `WEBVIEW_CONFIG.allowPrivateHost` is `true`. Run in a terminal, the build asks for the value instead.
+- A debug build no longer installs on a connected phone by itself. A terminal run asks once where to run the app and remembers the answer in `.catalyst/local.json`; without a terminal the emulator or simulator is used. Pass `--device` for the phone.
+- The first debug build rewrites `config/config.json` once: a value equal to this machine's LAN address, and a private `LOCAL_IP` that `NODE_SERVER_HOSTNAME` also holds, go back to `localhost`. Each change is printed. It never runs for a release, in CI or with `allowPrivateHost: true`.
+- Keystore passwords in `android.keystoreConfig` and `android.keystore` are no longer used. Apps that uploaded a build signed with the keystore shipped in the template, or with a key generated by an earlier release build, need an upload key reset in Play Console.
+
+### create-catalyst-app
+
+New apps get a new starter page, an animated HTML splash screen that is on by default (`splashScreen.minDuration` `7000`), a restyled offline page, a placeholder `public/icon.png`, and a `server/index.js` with an empty stub for `preServerInit` and each per-request hook. Their `.gitignore` covers `credentials/`, `.catalyst/` and `build-output/`.
+
+### Fixes
+
+- `MetaTag` waits for a `split()` route's chunk before it replaces the head tags, so the server's tags are no longer removed before the route's `setMetaData` is available.
+- Startup warns when `server/index.js` puts a lifecycle hook inside `export default { ... }`, where Catalyst never calls it. Export each hook by name.
+- `npm run start` prints a hint when `NODE_SERVER_HOSTNAME` is not an address of this machine.
+
 ## [1.1.0] - 2026-10-22
 
 This release contains everything in 1.0.2, namely the HTML splash screen, experimental WebMCP support and the new CLI output, plus one fix. There are no breaking API changes.

package/dist/cli/hints.js

@@ -27,6 +27,11 @@ const HINTS = [
                 : `Something is already on ${where}. Stop it, or set NODE_SERVER_PORT in config/config.json.`
         },
     },
+    {
+        test: /listen EADDRNOTAVAIL\b(?:.*?address not available\s+(\S+):\d+)?/i,
+        hint: (match) =>
+            `NODE_SERVER_HOSTNAME ${match[1] ? `${match[1]} ` : ""}is not an address of this machine; set it to localhost (or this machine's address) in config/config.json.`,
+    },
     {
         test: /SDK location not found|ANDROID_HOME/i,
         hint: () =>

package/dist/errors/registry.js

@@ -330,9 +330,9 @@ export const ERROR_DEFINITIONS = {
         category: "IOS",
         defaultMessage: "iOS code signing is not set up",
         defaultDetails:
-            "A device or release build needs a signing identity and provisioning profile. A release signs with the first of: a .p12 and its profile in credentials/ios/, an installed ios.provisioningProfile, an App Store Connect API key in credentials/ios/, an App Store profile installed on this Mac for the app id (with its certificate in the keychain), or the Apple account signed in to Xcode for WEBVIEW_CONFIG.ios.developmentTeam. xcodebuild reported a signing failure, or a release build has no team to sign for.",
+            "A device or release build needs a signing identity and provisioning profile. A release signs with the first of: a .p12 and its profile in credentials/ios/, an installed ios.provisioningProfile, an App Store Connect API key in credentials/ios/, an App Store profile installed on this Mac for the app id (with its certificate in the keychain), or the Apple account signed in to Xcode for WEBVIEW_CONFIG.ios.developmentTeam. xcodebuild reported a signing failure, or a release build has no team to sign for. A debug build for an iPhone signs with WEBVIEW_CONFIG.ios.developmentTeam from config/config.json, and with the installed development profile ios.provisioningProfile names when that is set. When an App Store release finds no App Store profile for its bundle id and has nothing else to sign with, the error says so first.",
         suggestedAction:
-            "Sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your team, or install that team's App Store profile for your appId. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
+            "For an App Store release, install the App Store provisioning profile for your bundle id (download it from developer.apple.com, or with Xcode > Settings > Accounts > Download Manual Profiles) or set WEBVIEW_CONFIG.ios.provisioningProfile to an installed profile's name. Otherwise, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. For a debug build on an iPhone, set WEBVIEW_CONFIG.ios.developmentTeam in config/config.json to your 10-character team ID (with Xcode signed in to that team, Xcode signs automatically), or also set ios.provisioningProfile to the name of an installed development profile that includes this iPhone. When ios.provisioningProfile is set, check that the profile includes this iPhone, matches the bundle id, and that its certificate is in your keychain. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
     },
     [ERROR_CODES.IOS_ASC_API_KEY_INVALID]: {
         category: "IOS",

package/dist/errors-index.json

@@ -226,8 +226,8 @@
     "IOS-010": {
         "category": "IOS",
         "message": "iOS code signing is not set up",
-        "details": "A device or release build needs a signing identity and provisioning profile. A release signs with the first of: a .p12 and its profile in credentials/ios/, an installed ios.provisioningProfile, an App Store Connect API key in credentials/ios/, an App Store profile installed on this Mac for the app id (with its certificate in the keychain), or the Apple account signed in to Xcode for WEBVIEW_CONFIG.ios.developmentTeam. xcodebuild reported a signing failure, or a release build has no team to sign for.",
-        "suggestedAction": "Sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your team, or install that team's App Store profile for your appId. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
+        "details": "A device or release build needs a signing identity and provisioning profile. A release signs with the first of: a .p12 and its profile in credentials/ios/, an installed ios.provisioningProfile, an App Store Connect API key in credentials/ios/, an App Store profile installed on this Mac for the app id (with its certificate in the keychain), or the Apple account signed in to Xcode for WEBVIEW_CONFIG.ios.developmentTeam. xcodebuild reported a signing failure, or a release build has no team to sign for. A debug build for an iPhone signs with WEBVIEW_CONFIG.ios.developmentTeam from config/config.json, and with the installed development profile ios.provisioningProfile names when that is set. When an App Store release finds no App Store profile for its bundle id and has nothing else to sign with, the error says so first.",
+        "suggestedAction": "For an App Store release, install the App Store provisioning profile for your bundle id (download it from developer.apple.com, or with Xcode > Settings > Accounts > Download Manual Profiles) or set WEBVIEW_CONFIG.ios.provisioningProfile to an installed profile's name. Otherwise, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. For a debug build on an iPhone, set WEBVIEW_CONFIG.ios.developmentTeam in config/config.json to your 10-character team ID (with Xcode signed in to that team, Xcode signs automatically), or also set ios.provisioningProfile to the name of an installed development profile that includes this iPhone. When ios.provisioningProfile is set, check that the profile includes this iPhone, matches the bundle id, and that its certificate is in your keychain. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
         "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/IOS/IOS-010.md"
     },
     "IOS-011": {

package/dist/native/buildAppIos.js

@@ -44,6 +44,7 @@ const {
   planSigningForConfig,
   readIosCredentials,
   resolveExportMethod,
+  settleInstalledProfile,
   settleXcodeTeam
 } = require("./buildIos/signing.js");
 const {
@@ -96,10 +97,11 @@ async function askAndSave(options) {
 /**
  * A release that will sign with the Apple account in Xcode needs
  * ios.developmentTeam. When it is unset, use the one team Xcode has that can
- * sign this export (or ask which, in a terminal). In a terminal the team is
- * saved to config/config.json; without one it is used for this build only.
- * Plans with planSigningForConfig, the same function createIosBuild signs
- * with. Returns the appConfig to build with.
+ * sign this export (or ask which, in a terminal). A release that auto-picked
+ * an installed App Store profile pins it as ios.provisioningProfile. In a
+ * terminal the team or profile is saved to config/config.json; without one
+ * it is used for this build only. Plans with planSigningForConfig, the same
+ * function createIosBuild signs with. Returns the appConfig to build with.
  *
  * Config and credential errors are left for createIosBuild, which reports
  * them the usual way.
@@ -140,6 +142,16 @@ async function ensureSigningTeam({
     found?.cleanup();
   }
   const file = path.join(cwd, "config", "config.json");
+  const profile = settleInstalledProfile({
+    plan,
+    log,
+    save: name => writeConfigKeys(file, {
+      "WEBVIEW_CONFIG.ios.provisioningProfile": name
+    }, {
+      log
+    })
+  });
+  if (profile?.saved) return loadAppConfig();
   const team = await settleXcodeTeam({
     plan,
     release,
@@ -193,7 +205,7 @@ async function main() {
       BUILD_OUTPUT_PATH
     };
     for (const change of migration.changes) {
-      log(`config.json ${change.path}: ${change.from} -> ${change.to}`, "info");
+      log(`config.json ${change.path}: ${change.from} -> ${change.to}`, "note");
     }
     const release = flags.release || isReleaseBuildType(appConfig.WEBVIEW_CONFIG?.ios?.buildType);
     // A store build in a terminal asks once for a missing app id or

package/dist/native/buildIos/build.js

@@ -11,6 +11,7 @@ const {
   runInteractiveCommand
 } = require("../utils.js");
 const {
+  DEBUG_BUILD_SETTINGS,
   xcodeAuthArgs
 } = require("./signing.js");
 module.exports = function createBuildPhase(ctx) {
@@ -138,6 +139,7 @@ module.exports = function createBuildPhase(ctx) {
         CODE_SIGNING_REQUIRED=NO \
         CODE_SIGNING_ALLOWED=NO \
         ONLY_ACTIVE_ARCH=YES \
+        ${DEBUG_BUILD_SETTINGS.join(" ")} \
         BUILD_DIR="${derivedDataPath}/${projectName}-Build/Build/Products" \
         CONFIGURATION_BUILD_DIR="${derivedDataPath}/${projectName}-Build/Build/Products/Debug-iphonesimulator" \
         OS_ACTIVITY_MODE=debug \
@@ -319,7 +321,7 @@ module.exports = function createBuildPhase(ctx) {
     const signingArgs = ctx.signingPlan?.style === "manual" ? [] : xcodeAuthArgs(ctx.apiKey);
     // The streamed output is what tells you how it is going; argv, not a
     // shell string, so a key path with spaces needs no quoting.
-    return runCommandStreaming("xcodebuild", ["-scheme", scheme, "-sdk", "iphoneos", "-configuration", "Debug", "-destination", `platform=iOS,id=${device.udid}`, `PRODUCT_BUNDLE_IDENTIFIER=${bundleId}`, "ONLY_ACTIVE_ARCH=YES", ...signingArgs, "build"]);
+    return runCommandStreaming("xcodebuild", ["-scheme", scheme, "-sdk", "iphoneos", "-configuration", "Debug", "-destination", `platform=iOS,id=${device.udid}`, `PRODUCT_BUNDLE_IDENTIFIER=${bundleId}`, "ONLY_ACTIVE_ARCH=YES", ...DEBUG_BUILD_SETTINGS, ...signingArgs, "build"]);
   }
   async function findPhysicalDeviceAppPath() {
     const DERIVED_DATA_DIR = path.join(os.homedir(), "Library/Developer/Xcode/DerivedData");

package/dist/native/buildIos/index.js

@@ -35,6 +35,8 @@ const {
   createProfileScanner,
   pickInstalledProfile,
   XCODE_TEAM_HINT,
+  deviceSigningHint,
+  missingProfileError,
   buildExportOptions,
   writeExportOptionsPlist,
   isSigningFailure,
@@ -186,7 +188,11 @@ function createIosBuild(config, {
   const apiKey = release ? resolveApiKey() : null;
   if (release && signingPlan.style === "automatic" && !signingPlan.teamId) {
     credentials?.cleanup();
-    throw nativeError("IOS-010", "a signed release with automatic signing needs WEBVIEW_CONFIG.ios.developmentTeam", signingPlan.source === "Xcode account" ? {
+    const detail = "a signed release with automatic signing needs WEBVIEW_CONFIG.ios.developmentTeam";
+    const missing = missingProfileError(signingPlan.missingProfileFor, detail);
+    throw missing ? nativeError("IOS-010", missing.detail, {
+      hint: missing.hint
+    }) : nativeError("IOS-010", detail, signingPlan.source === "Xcode account" ? {
       hint: XCODE_TEAM_HINT
     } : {});
   }
@@ -464,10 +470,12 @@ function createIosBuild(config, {
           progress.complete("build");
         } catch (error) {
           // The diagnostic in the catch below shows what xcodebuild
-          // said. A signing failure gets IOS-010, which names both
-          // ways to set signing up. Not checked up front: an Apple
-          // account signed in to Xcode signs fine without either.
-          const failure = isSigningFailure(error.output) ? signingSetupError("Xcode could not sign the device build", error) : error;
+          // said. A signing failure gets IOS-010 with the
+          // development hint (ios.developmentTeam, or what to check
+          // in ios.provisioningProfile), not the App Store one.
+          const failure = isSigningFailure(error.output) ? signingSetupError("Xcode could not sign the device build", error, {
+            hint: deviceSigningHint(signingPlan)
+          }) : error;
           failure.stage = failure.stage || "Building for the device";
           throw failure;
         }
@@ -611,7 +619,9 @@ function createIosBuild(config, {
       try {
         await runCommandStreaming("xcodebuild", ["archive", "-project", `${PROJECT_NAME}.xcodeproj`, "-scheme", SCHEME_NAME, "-configuration", "Release", "-destination", "generic/platform=iOS", "-archivePath", archivePath, ...signingArgs]);
       } catch (error) {
-        const failure = isSigningFailure(error.output) ? signingSetupError("Xcode could not sign the release archive", error) : error;
+        const failure = isSigningFailure(error.output) ? signingSetupError("Xcode could not sign the release archive", error, {
+          missingProfileFor: signing.missingProfileFor
+        }) : error;
         failure.stage = "Archiving the release build";
         throw failure;
       }
@@ -629,7 +639,9 @@ function createIosBuild(config, {
       try {
         await runCommandStreaming("xcodebuild", ["-exportArchive", "-archivePath", archivePath, "-exportPath", exportPath, "-exportOptionsPlist", optionsPlist, ...(signing.style === "automatic" ? xcodeAuthArgs(ctx.apiKey) : [])]);
       } catch (error) {
-        const failure = isSigningFailure(error.output) ? signingSetupError("Xcode could not sign the IPA for export", error) : error;
+        const failure = isSigningFailure(error.output) ? signingSetupError("Xcode could not sign the IPA for export", error, {
+          missingProfileFor: signing.missingProfileFor
+        }) : error;
         failure.stage = "Exporting the IPA";
         throw failure;
       }

package/dist/native/buildIos/signing.js

@@ -3,13 +3,15 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.XCODE_TEAM_HINT = exports.SIGNING_PROPERTIES = exports.EXPORT_METHODS = void 0;
+exports.XCODE_TEAM_HINT = exports.SIGNING_PROPERTIES = exports.EXPORT_METHODS = exports.DEVICE_TEAM_HINT = exports.DEBUG_BUILD_SETTINGS = void 0;
 exports.buildExportOptions = buildExportOptions;
 exports.chooseXcodeTeam = chooseXcodeTeam;
 exports.createProfileScanner = createProfileScanner;
+exports.deviceSigningHint = deviceSigningHint;
 exports.findInstalledProfileIdentity = findInstalledProfileIdentity;
 exports.isReleaseBuildType = isReleaseBuildType;
 exports.isSigningFailure = isSigningFailure;
+exports.missingProfileError = missingProfileError;
 exports.needsXcodeTeam = needsXcodeTeam;
 exports.parseIdentities = parseIdentities;
 exports.parseIdentity = parseIdentity;
@@ -27,6 +29,7 @@ exports.readProvisioningProfile = readProvisioningProfile;
 exports.readXcodeTeams = readXcodeTeams;
 exports.resolveExportMethod = resolveExportMethod;
 exports.scanInstalledProfiles = scanInstalledProfiles;
+exports.settleInstalledProfile = settleInstalledProfile;
 exports.settleXcodeTeam = settleXcodeTeam;
 exports.setupP12Signing = setupP12Signing;
 exports.signingFailureLine = signingFailureLine;
@@ -220,6 +223,15 @@ function readIosCredentials(dir, {
   };
 }
 
+/**
+ * xcodebuild build settings for every debug build, simulator and iPhone.
+ * ENABLE_DEBUG_DYLIB=NO: for Xcode's Previews a Debug app is split into the
+ * app, <app>.debug.dylib and __preview.dylib, each signed on its own, so an
+ * iPhone build asked for the Keychain password three times. A command line
+ * build has no use for Previews. The release archive does not use them.
+ */
+const DEBUG_BUILD_SETTINGS = exports.DEBUG_BUILD_SETTINGS = ["ENABLE_DEBUG_DYLIB=NO"];
+
 /**
  * xcodebuild flags that let automatic signing create and fetch certificates
  * and profiles: with the API key when there is one (cloud signing),
@@ -296,13 +308,19 @@ function planIosSigning({
   if (release && exportMethod === "app-store-connect" && bundleId && scanProfiles) {
     const scan = scanProfiles();
     const {
-      identity
+      identity,
+      missing
     } = pickInstalledProfile(scan, {
       bundleId,
       teamId,
       needsPush: notifications,
       now
     });
+    // Nothing else to sign with: IOS-010 leads with the missing profile.
+    if (missing) return {
+      ...automatic("Xcode account"),
+      missingProfileFor: bundleId
+    };
     if (identity) {
       // By name, as people know it, unless another installed profile shares it.
       const sameName = scan.profiles.filter(profile => profile.name === identity.profileName).length;
@@ -580,7 +598,9 @@ function isAppStoreProfile(profile) {
  * profile (.mobileprovision, no devices, get-task-allow false) for exactly
  * this bundle id, for `teamId` when set, with aps-environment when
  * `needsPush`. Expired profiles are skipped; the newest one whose
- * certificate is in the keychain wins. Without a match, `reason` says why.
+ * certificate is in the keychain wins. Without a match, `reason` says why,
+ * and `missing` is true when no App Store profile for the bundle id is
+ * installed at all.
  *
  * @param {ReturnType<typeof scanInstalledProfiles>} scan
  * @param {object} options
@@ -589,7 +609,7 @@ function isAppStoreProfile(profile) {
  * @param {string} [options.teamId]
  * @param {boolean} [options.needsPush]
  * @param {Date} [options.now]
- * @returns {{ identity: { sha1: string, name: string, teamId?: string, uuid: string, profileName?: string } | null, reason?: string }}
+ * @returns {{ identity: { sha1: string, name: string, teamId?: string, uuid: string, profileName?: string } | null, reason?: string, missing?: boolean }}
  */
 function pickInstalledProfile(scan, {
   profile,
@@ -611,13 +631,19 @@ function pickInstalledProfile(scan, {
   };
   let candidates = scan?.profiles || [];
   /** Keep the candidates that pass; when none does, that check is the reason. */
-  const steps = wanted ? [[c => c.name === wanted || String(c.uuid).toLowerCase() === wanted.toLowerCase(), () => "no installed profile has that name or UUID"], [c => !(c.expires && c.expires <= now.getTime()), left => `it expired on ${left[0].expirationDate}`], [c => profileMatchesBundleId(c.applicationIdentifier, bundleId), left => `it is for ${appIdOf(left[0])}, not ${bundleId}`]] : [[c => c.file.endsWith(".mobileprovision") && c.applicationIdentifier && appIdOf(c) === bundleId, () => `no installed profile is for exactly ${bundleId}`], [isAppStoreProfile, () => `no installed App Store profile is for ${bundleId}`], [c => !teamId || c.teamId === teamId, () => `no installed App Store profile for ${bundleId} is for team ${teamId}`], [c => !needsPush || Boolean(c.apsEnvironment), () => `no installed App Store profile for ${bundleId} has push notifications`], [c => !(c.expires && c.expires <= now.getTime()), () => `every installed App Store profile for ${bundleId} has expired`]];
-  for (const [keep, reason] of steps) {
+  const steps = wanted ? [[c => c.name === wanted || String(c.uuid).toLowerCase() === wanted.toLowerCase(), () => "no installed profile has that name or UUID"], [c => !(c.expires && c.expires <= now.getTime()), left => `it expired on ${left[0].expirationDate}`], [c => profileMatchesBundleId(c.applicationIdentifier, bundleId), left => `it is for ${appIdOf(left[0])}, not ${bundleId}`]] : [[c => c.file.endsWith(".mobileprovision") && c.applicationIdentifier && appIdOf(c) === bundleId, () => `no installed profile is for exactly ${bundleId}`, true], [isAppStoreProfile, () => `no installed App Store profile is for ${bundleId}`, true], [c => !teamId || c.teamId === teamId, () => `no installed App Store profile for ${bundleId} is for team ${teamId}`], [c => !needsPush || Boolean(c.apsEnvironment), () => `no installed App Store profile for ${bundleId} has push notifications`], [c => !(c.expires && c.expires <= now.getTime()), () => `every installed App Store profile for ${bundleId} has expired`]];
+  for (const [keep, reason, missing] of steps) {
     const left = candidates.filter(keep);
-    if (!left.length) return {
-      identity: null,
-      reason: reason(candidates)
-    };
+    if (!left.length) {
+      return missing ? {
+        identity: null,
+        reason: reason(candidates),
+        missing: true
+      } : {
+        identity: null,
+        reason: reason(candidates)
+      };
+    }
     candidates = left;
   }
   const newestFirst = [...candidates].sort((a, b) => b.expires - a.expires);
@@ -685,6 +711,44 @@ function findInstalledProfileIdentity({
 
 const XCODE_TEAM_HINT = exports.XCODE_TEAM_HINT = "Open Xcode > Settings > Accounts and sign in with the Apple account that has your company's team, or set WEBVIEW_CONFIG.ios.developmentTeam.";
 
+/**
+ * IOS-010's hint when Xcode could not sign a debug build for an iPhone. That
+ * build signs with what config/config.json sets, nothing else: the team, and
+ * an installed development profile when ios.provisioningProfile names one.
+ */
+const DEVICE_TEAM_HINT = exports.DEVICE_TEAM_HINT = "Set WEBVIEW_CONFIG.ios.developmentTeam in config/config.json to your 10-character team ID. With Xcode signed in to that team, Xcode signs automatically. Or also set ios.provisioningProfile to the name of an installed development profile that includes this iPhone.";
+
+/**
+ * DEVICE_TEAM_HINT, or for a plan that signs with ios.provisioningProfile
+ * what to check in that profile.
+ *
+ * @param {ReturnType<typeof planIosSigning>} [plan]
+ * @returns {string}
+ */
+function deviceSigningHint(plan) {
+  if (!plan?.provisioningProfile) return DEVICE_TEAM_HINT;
+  return `Check that the profile "${plan.provisioningProfile}" set in WEBVIEW_CONFIG.ios.provisioningProfile includes this iPhone, matches the bundle id, and that its certificate is in your keychain.`;
+}
+
+/**
+ * IOS-010's detail and hint for an App Store release that found no installed
+ * App Store profile for its bundle id (plan.missingProfileFor) and has no
+ * other signing source: the missing profile first, then every way to sign,
+ * the Xcode account last. Null for any other plan.
+ *
+ * @param {string | undefined} bundleId - plan.missingProfileFor
+ * @param {string} [detail] - what failed after that, e.g. the Xcode account
+ * @returns {{ detail: string, hint: string } | null}
+ */
+function missingProfileError(bundleId, detail) {
+  if (!bundleId) return null;
+  const missing = `no App Store provisioning profile for ${bundleId} is installed on this Mac`;
+  return {
+    detail: detail ? `${missing}, and ${detail}` : missing,
+    hint: `Install the App Store profile for ${bundleId} (download it from developer.apple.com, or with Xcode > Settings > Accounts > Download Manual Profiles), set WEBVIEW_CONFIG.ios.provisioningProfile to an installed profile's name, put a .p12 and its profile or an App Store Connect API key in credentials/ios/, or sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team.`
+  };
+}
+
 /**
  * The teams in IDEProvisioningTeamByIdentifier (account id -> teams), one
  * per team id. `free` is isFreeProvisioningTeam, undefined when Xcode did
@@ -753,31 +817,35 @@ function needsXcodeTeam(plan, {
  * Store, release-testing or enterprise export, so it is left out unless the
  * export is for debugging; a team Xcode did not mark either way is kept.
  * One team is used; several are a question, NATIVE-005 without a terminal;
- * none is IOS-010.
+ * none is IOS-010, which leads with `missingProfileFor` when that is set.
  *
  * @param {object} options
  * @param {ReturnType<typeof parseXcodeTeams>} options.teams - from readXcodeTeams
  * @param {string} [options.exportMethod]
  * @param {boolean} [options.isTTY]
  * @param {typeof select} [options.choose]
+ * @param {string} [options.missingProfileFor] - plan.missingProfileFor
  * @returns {Promise<{ teamId: string, teamName: string, free: boolean | undefined }>}
  */
 async function chooseXcodeTeam({
   teams,
   exportMethod = "app-store-connect",
   isTTY,
-  choose = _utils.select
+  choose = _utils.select,
+  missingProfileFor
 }) {
-  if (!teams) {
-    throw (0, _utils.nativeError)("IOS-010", "could not read which teams are signed in to Xcode", {
+  const noTeam = detail => {
+    const missing = missingProfileError(missingProfileFor, detail);
+    return missing ? (0, _utils.nativeError)("IOS-010", missing.detail, {
+      hint: missing.hint
+    }) : (0, _utils.nativeError)("IOS-010", detail, {
       hint: XCODE_TEAM_HINT
     });
-  }
+  };
+  if (!teams) throw noTeam("could not read which teams are signed in to Xcode");
   const usable = exportMethod === "debugging" ? teams : teams.filter(team => team.free !== true);
   if (!usable.length) {
-    throw (0, _utils.nativeError)("IOS-010", teams.length ? `Xcode is signed in with a personal team only, and a personal team cannot sign ${exportMethod} builds` : "no Apple account with a team is signed in to Xcode", {
-      hint: XCODE_TEAM_HINT
-    });
+    throw noTeam(teams.length ? `Xcode is signed in with a personal team only, and a personal team cannot sign ${exportMethod} builds` : "no Apple account with a team is signed in to Xcode");
   }
   if (usable.length === 1) return usable[0];
   const label = team => `${team.teamName || "Unnamed team"} (${team.teamId})`;
@@ -831,7 +899,8 @@ async function settleXcodeTeam({
     teams: readTeams(),
     exportMethod,
     isTTY: interactive,
-    choose
+    choose,
+    missingProfileFor: plan.missingProfileFor
   });
   const label = `${team.teamName || "Unnamed team"} (${team.teamId})`;
   if (!interactive) {
@@ -849,6 +918,44 @@ async function settleXcodeTeam({
   };
 }
 
+/**
+ * The profile step for a release that auto-picked an installed App Store
+ * profile (planIosSigning's "installed profile"): in a terminal save it as
+ * ios.provisioningProfile with `save`, so later builds sign with the same
+ * one; without a terminal (CI, agents) only use it for this build, since
+ * config.json is never written there. Null for any other plan.
+ *
+ * @param {object} options
+ * @param {ReturnType<typeof planIosSigning>} options.plan - from planSigningForConfig
+ * @param {boolean} [options.isTTY] - defaults to isInteractive()
+ * @param {(profile: string) => void} options.save - writes WEBVIEW_CONFIG.ios.provisioningProfile
+ * @param {(message: string, type?: string) => void} [options.log]
+ * @returns {{ provisioningProfile: string, saved: boolean } | null}
+ */
+function settleInstalledProfile({
+  plan,
+  isTTY,
+  save,
+  log = () => {}
+}) {
+  if (plan?.source !== "installed profile") return null;
+  // The name, or the UUID when another installed profile shares the name.
+  const profile = plan.provisioningProfile;
+  if (!(isTTY ?? (0, _utils.isInteractive)())) {
+    log(`Using the installed profile "${plan.profileName}". Set WEBVIEW_CONFIG.ios.provisioningProfile to keep it.`, "note");
+    return {
+      provisioningProfile: profile,
+      saved: false
+    };
+  }
+  log(`Signing with the installed profile "${plan.profileName}" (team ${plan.teamId})`, "info");
+  save(profile);
+  return {
+    provisioningProfile: profile,
+    saved: true
+  };
+}
+
 /**
  * Local signing with credentials/ios/: import the .p12 into a temporary
  * keychain, put that keychain on the user search list, and install the
@@ -1103,15 +1210,28 @@ function signingFailureLine(output) {
 
 /**
  * The coded error for a signing failure, keeping xcodebuild's transcript for
- * the diagnostic. The detail ends with the line that says what went wrong.
+ * the diagnostic. The detail ends with the line that says what went wrong,
+ * and starts with the missing App Store profile when `missingProfileFor` is set.
  *
  * @param {string} detail
  * @param {any} [cause]
+ * @param {object} [options]
+ * @param {string} [options.missingProfileFor] - plan.missingProfileFor
+ * @param {string} [options.hint] - over the registry's hint, e.g. deviceSigningHint(plan)
  * @returns {any}
  */
-function signingSetupError(detail, cause) {
+function signingSetupError(detail, cause, {
+  missingProfileFor,
+  hint
+} = {}) {
   const said = signingFailureLine(cause?.output);
-  const error = (0, _utils.nativeError)("IOS-010", said ? `${detail}: ${said}` : detail);
+  const failed = said ? `${detail}: ${said}` : detail;
+  const missing = missingProfileError(missingProfileFor, failed);
+  const error = missing ? (0, _utils.nativeError)("IOS-010", missing.detail, {
+    hint: missing.hint
+  }) : (0, _utils.nativeError)("IOS-010", failed, {
+    hint
+  });
   if (cause) {
     error.cause = cause;
     if (cause.output) error.output = cause.output;

package/dist/native/iosToolchain.js

@@ -489,7 +489,8 @@ async function chooseIosTarget({
 /**
  * The host a debug build reaches the dev server on. The simulator shares the
  * Mac's network, so localhost. An iPhone uses the Mac's Bonjour name
- * (`<LocalHostName>.local`), else its LAN IP; IOS-015 when there is neither.
+ * (`<localhostname>.local`, lowercased), else its LAN IP; IOS-015 when there
+ * is neither.
  * It goes into the build only, never into config.json.
  *
  * @param {{ target: string, name?: string } | null} target

package/dist/native/setupServer.js

@@ -72,8 +72,8 @@ function getLocalIPAddress(interfaces = _os.default.networkInterfaces()) {
 
 /**
  * The host a physical device on the same network reaches this Mac on:
- * `<LocalHostName>.local` (Bonjour, survives DHCP changes), else the LAN IP.
- * Null when neither is available.
+ * `<localhostname>.local` (Bonjour, survives DHCP changes, lowercased), else
+ * the LAN IP. Null when neither is available.
  *
  * @param {object} [options]
  * @param {() => string} [options.localHostName] - returns `scutil --get LocalHostName`
@@ -90,8 +90,10 @@ function getDeviceReachableHost({
   } catch (error) {
     // Not macOS, or scutil failed: fall back to the LAN IP.
   }
+  // Lowercase: WebKit sends the Host header lowercased, and Vite's
+  // server.allowedHosts compares it exactly.
   if (/^[A-Za-z0-9-]+$/.test(name)) return {
-    host: `${name}.local`,
+    host: `${name.toLowerCase()}.local`,
     source: "bonjour"
   };
   const ip = getLocalIPAddress(interfaces);
@@ -415,12 +417,14 @@ async function ensureDevServer({
 // One-time migration: older setups wrote this machine's LAN address into
 // config.json (every "localhost", and any http://<ip>), which makes Express
 // bind only that address and breaks adb reverse. Put localhost back, but only
-// for this machine's own addresses: a container IP, 0.0.0.0 or a loopback
-// address is the app's own setting.
+// for this machine's own addresses (or the one it had on another network):
+// a container IP, 0.0.0.0 or a loopback address is the app's own setting.
 // ---------------------------------------------------------------------------
 
 const MIGRATION_KEY = "lanAddresses";
 const IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+// 10/8, 172.16/12, 192.168/16 and link-local 169.254/16.
+const PRIVATE_LAN_IPV4 = /^(?:10|172\.(?:1[6-9]|2\d|3[01])|192\.168|169\.254)\./;
 const isCI = env => {
   const value = env.CI;
   return value !== undefined && value !== "" && value !== "0" && String(value).toLowerCase() !== "false";
@@ -429,10 +433,13 @@ const isCI = env => {
 /**
  * The changes the migration would make, without writing anything. Only a
  * value equal to one of this machine's current IPv4 addresses, or an
- * http:// URL on one of them, goes back to localhost. Any other address,
- * private ones included (a LOCAL_IP pointing at a VPN or LAN staging server),
- * is the app's own setting. WEBVIEW_CONFIG.url is never touched, and nothing
- * is when WEBVIEW_CONFIG.allowPrivateHost is true.
+ * http:// URL on one of them, goes back to localhost. So does a private
+ * LOCAL_IP that NODE_SERVER_HOSTNAME also holds: an earlier setup wrote this
+ * machine's address on another network into both, and the dev server can't
+ * bind it here. Any other address, private ones included (a LOCAL_IP
+ * pointing at a VPN or LAN staging server), is the app's own setting.
+ * WEBVIEW_CONFIG.url is never touched, and nothing is when
+ * WEBVIEW_CONFIG.allowPrivateHost is true.
  *
  * @param {object} config - the parsed config.json (not modified)
  * @param {object} [options]
@@ -451,6 +458,11 @@ function planLanAddressMigration(config, {
   };
   // This machine's IPv4 addresses, without loopback and 0.0.0.0/8.
   const saved = new Set([...localHosts].filter(host => IPV4.test(host) && !/^(?:127|0)\./.test(host)));
+  // The LAN address this machine had when LOCAL_IP was written.
+  const leftover = typeof wv?.LOCAL_IP === "string" ? wv.LOCAL_IP.trim() : "";
+  if (IPV4.test(leftover) && PRIVATE_LAN_IPV4.test(leftover) && String(config.NODE_SERVER_HOSTNAME ?? "").trim() === leftover) {
+    saved.add(leftover);
+  }
   if (!saved.size) return {
     config,
     changes
@@ -532,8 +544,8 @@ function migrateLanAddresses({
     } : undefined).changes;
     const changes = planned.length ? writeConfigKeys(file, Object.fromEntries(planned.map(change => [change.path, change.to]))) : [];
     if (changes.length) {
-      log(`Put localhost back in config/config.json where an earlier setup saved this machine's LAN address:`, "info");
-      for (const change of changes) log(`  ${change.path}: ${change.from} -> ${change.to}`, "info");
+      log(`Put localhost back in config/config.json where an earlier setup saved this machine's LAN address:`, "note");
+      for (const change of changes) log(`  ${change.path}: ${change.from} -> ${change.to}`, "note");
     }
     const state = (0, _localState.readLocalState)({
       cwd

package/dist/native/utils.js

@@ -508,7 +508,7 @@ const NATIVE_ERRORS = exports.NATIVE_ERRORS = {
   },
   "IOS-010": {
     message: "iOS code signing is not set up",
-    hint: "Sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your team, or install that team's App Store profile for your appId. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios."
+    hint: "For an App Store release, install the App Store provisioning profile for your bundle id (download it from developer.apple.com, or with Xcode > Settings > Accounts > Download Manual Profiles) or set WEBVIEW_CONFIG.ios.provisioningProfile to an installed profile's name. Otherwise, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. For a debug build on an iPhone, set WEBVIEW_CONFIG.ios.developmentTeam in config/config.json to your 10-character team ID (with Xcode signed in to that team, Xcode signs automatically), or also set ios.provisioningProfile to the name of an installed development profile that includes this iPhone. When ios.provisioningProfile is set, check that the profile includes this iPhone, matches the bundle id, and that its certificate is in your keychain. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios."
   },
   "IOS-011": {
     message: "App Store Connect API key settings are incomplete or wrong",