catalyst-core 1.2.0-canary.4 → 1.2.0

package/changelog.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## [1.2.0] - Unreleased
+## [1.2.0] - 2026-11-13
 
 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`.
 

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. 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.",
+            "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, and for a device build, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. 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. 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, and for a device build, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. 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/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,7 @@ const {
   createProfileScanner,
   pickInstalledProfile,
   XCODE_TEAM_HINT,
+  deviceSigningHint,
   missingProfileError,
   buildExportOptions,
   writeExportOptionsPlist,
@@ -469,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;
         }

package/dist/native/buildIos/signing.js

@@ -3,10 +3,11 @@
 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;
@@ -222,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),
@@ -701,6 +711,25 @@ 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
@@ -1188,17 +1217,21 @@ function signingFailureLine(output) {
  * @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, {
-  missingProfileFor
+  missingProfileFor,
+  hint
 } = {}) {
   const said = signingFailureLine(cause?.output);
   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);
+  }) : (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);

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: "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, and for a device build, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. 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",

package/dist/vite/resolveDevServerConfig.js

@@ -38,11 +38,13 @@ export function resolveDevFsAllow(devFs, frameworkPaths) {
  * CATALYST_DEV_ALLOWED_HOSTS. `catalyst buildApp:ios` sets it to the Mac's
  * `<name>.local` when a physical iPhone loads the dev server by that name:
  * Vite answers 403 to any Host header that is not localhost or an IP.
+ * Hosts are lowercased: browsers send the Host header lowercased and Vite
+ * compares it exactly.
  */
 export function withExtraAllowedHosts(allowedHosts, extra) {
     const hosts = String(extra || "")
         .split(",")
-        .map((host) => host.trim())
+        .map((host) => host.trim().toLowerCase())
         .filter(Boolean)
     if (allowedHosts === true || hosts.length === 0) return allowedHosts
     const base = Array.isArray(allowedHosts) ? allowedHosts : []

package/mcp_v2/knowledge-base.json

@@ -170,7 +170,7 @@
     {
         "section": "build_system",
         "title": "iOS Build Pipeline",
-        "content": "npm run ios (catalyst buildApp:ios) checks full Xcode and offers the licence and first-launch steps, installs a simulator runtime, uses an existing iPhone simulator (ios.simulatorName, else the last pick, a booted one or the newest; 'Catalyst iPhone' is created after asking only when there is none), picks the target (simulator by default; a terminal run asks when an iPhone is connected; --device uses the iPhone; the pick is remembered in .catalyst/local.json), starts catalyst start when nothing answers and waits for it, generates ConfigConstants.swift and plugin metadata from WEBVIEW_CONFIG, syncs public/ios assets into the package-owned Xcode project, compiles with the Debug configuration, and installs and launches the .app. The simulator loads the dev server on localhost; an iPhone on the Mac's <LocalHostName>.local (else the LAN IP), with NSAllowsLocalNetworking in debug, and needs ios.developmentTeam plus an Apple account signed in to Xcode once (a free account works). config.json is never written. With --release (or the deprecated ios.buildType release) it archives and exports the signed store IPA instead. The generated project is located under the resolved catalyst-core package at dist/native/iosnativeWebView/iosnativeWebView.xcodeproj.",
+        "content": "npm run ios (catalyst buildApp:ios) checks full Xcode and offers the licence and first-launch steps, installs a simulator runtime, uses an existing iPhone simulator (ios.simulatorName, else the last pick, a booted one or the newest; 'Catalyst iPhone' is created after asking only when there is none), picks the target (simulator by default; a terminal run asks when an iPhone is connected; --device uses the iPhone; the pick is remembered in .catalyst/local.json), starts catalyst start when nothing answers and waits for it, generates ConfigConstants.swift and plugin metadata from WEBVIEW_CONFIG, syncs public/ios assets into the package-owned Xcode project, compiles with the Debug configuration, and installs and launches the .app. The simulator loads the dev server on localhost; an iPhone on the Mac's <localhostname>.local, lowercased (else the LAN IP), with NSAllowsLocalNetworking in debug. An iPhone build signs with what config.json sets and looks nothing up: ios.developmentTeam (with Xcode signed in to that team, Xcode signs automatically; a free account works), plus ios.provisioningProfile to sign with an installed development profile that includes the iPhone (and ios.bundleIdentifier when the profile is for another id); a signing failure is IOS-010. A debug build never writes config.json. With --release (or the deprecated ios.buildType release) it archives and exports the signed store IPA instead. The generated project is located under the resolved catalyst-core package at dist/native/iosnativeWebView/iosnativeWebView.xcodeproj.",
         "layer": "Build",
         "source": "static",
         "tags": ["ios", "build", "buildApp:ios", "debug", "xcode"],
@@ -484,7 +484,7 @@
     {
         "section": "config_structure",
         "title": "WEBVIEW_CONFIG Required Fields",
-        "content": "WEBVIEW_CONFIG field reference (catalyst-core 1.2.0+, from nativeConfig.js):\n\nTOP-LEVEL (both platforms):\n- appId (string, required for release): Android application id and iOS bundle id, e.g. com.company.app. android.packageName / ios.bundleIdentifier / ios.appBundleId win over it when set. Release refuses com.example.* (NATIVE-003); a release in a terminal asks for it once and saves it. An iOS bundle id allows only letters, digits, - and ., so an appId with an underscore fails every iOS build (NATIVE-010): set ios.bundleIdentifier\n- appName (string, optional): name under the icon; wins over android.appName / ios.appName\n- url (string, required for release): https origin the release app loads, no path. --url overrides. Debug builds ignore it\n- allowPrivateHost (boolean, optional): lets a release load a private host\n- LOCAL_IP (string, optional): 'localhost' makes debug builds use the dev server (they work out its address). A real host (public, or a private VPN/LAN staging server, not this machine's own address) is loaded by debug builds instead; apps without url still use LOCAL_IP/port/useHttps as the release host\n- port (string, optional): dev server port when NODE_SERVER_PORT is not set\n- appInfo (string, optional): free-form text useDeviceInfo() reports, e.g. \"android-5Feb2026-v2.1.0\". The iOS build writes \"\" when it is missing\n- cachePattern (optional): set it per platform instead. A top-level cachePattern wins over android.cachePattern and ios.cachePattern\n- accessControl.enabled / allowedUrls (optional): URL allowlist, off when the block is missing; debug builds add the dev server origin\n\nANDROID (WEBVIEW_CONFIG.android, all optional):\n- sdkPath: else ANDROID_HOME, ANDROID_SDK_ROOT, default location; installed when missing\n- emulatorName: else the last used or catalyst-api36, created when missing\n- buildType: deprecated; 'release' builds a release with a warning\n- outputPath: release folder instead of build-output/android\n- buildOptimisation\n- cachePattern: comma-separated string of globs, e.g. \"*.css,*.js,*.png\"\n\nIOS (WEBVIEW_CONFIG.ios, all optional):\n- developmentTeam: Apple team ID, needed for an iPhone and for cloud or Xcode-account signing (IOS-010)\n- simulatorName: simulator to use when it exists; else the last pick, a booted iPhone simulator or the newest one. 'Catalyst iPhone' is created only when there is no iPhone simulator\n- deviceUDID: which iPhone --device uses without a terminal\n- provisioningProfile: installed profile name (or UUID) for manual signing; a terminal release saves the installed App Store profile it picked here, pinning later releases to it (remove the key to let the build pick again)\n- exportMethod: app-store-connect (default), release-testing, enterprise or debugging\n- buildType: deprecated; 'release' builds the store IPA with a warning\n- cachePattern: array of globs, e.g. [\"*.css\", \"*.js\"]; a string is read as one pattern, not split on commas\n\nVersion comes from package.json; signing files live in credentials/android/ and credentials/ios/, never in config.json.",
+        "content": "WEBVIEW_CONFIG field reference (catalyst-core 1.2.0+, from nativeConfig.js):\n\nTOP-LEVEL (both platforms):\n- appId (string, required for release): Android application id and iOS bundle id, e.g. com.company.app. android.packageName / ios.bundleIdentifier / ios.appBundleId win over it when set. Release refuses com.example.* (NATIVE-003); a release in a terminal asks for it once and saves it. An iOS bundle id allows only letters, digits, - and ., so an appId with an underscore fails every iOS build (NATIVE-010): set ios.bundleIdentifier\n- appName (string, optional): name under the icon; wins over android.appName / ios.appName\n- url (string, required for release): https origin the release app loads, no path. --url overrides. Debug builds ignore it\n- allowPrivateHost (boolean, optional): lets a release load a private host\n- LOCAL_IP (string, optional): 'localhost' makes debug builds use the dev server (they work out its address). A real host (public, or a private VPN/LAN staging server, not this machine's own address) is loaded by debug builds instead; apps without url still use LOCAL_IP/port/useHttps as the release host\n- port (string, optional): dev server port when NODE_SERVER_PORT is not set\n- appInfo (string, optional): free-form text useDeviceInfo() reports, e.g. \"android-5Feb2026-v2.1.0\". The iOS build writes \"\" when it is missing\n- cachePattern (optional): set it per platform instead. A top-level cachePattern wins over android.cachePattern and ios.cachePattern\n- accessControl.enabled / allowedUrls (optional): URL allowlist, off when the block is missing; debug builds add the dev server origin\n\nANDROID (WEBVIEW_CONFIG.android, all optional):\n- sdkPath: else ANDROID_HOME, ANDROID_SDK_ROOT, default location; installed when missing\n- emulatorName: else the last used or catalyst-api36, created when missing\n- buildType: deprecated; 'release' builds a release with a warning\n- outputPath: release folder instead of build-output/android\n- buildOptimisation\n- cachePattern: comma-separated string of globs, e.g. \"*.css,*.js,*.png\"\n\nIOS (WEBVIEW_CONFIG.ios, all optional):\n- developmentTeam: Apple team ID, needed for an iPhone and for cloud or Xcode-account signing (IOS-010); an iPhone debug build reads it from here only, a release in a terminal reads it from Xcode and saves it here when unset\n- simulatorName: simulator to use when it exists; else the last pick, a booted iPhone simulator or the newest one. 'Catalyst iPhone' is created only when there is no iPhone simulator\n- deviceUDID: which iPhone --device uses without a terminal\n- provisioningProfile: installed profile name (or UUID) for manual signing; an iPhone debug build signs with the development profile named here, which must include the iPhone; a terminal release saves the installed App Store profile it picked here, pinning later releases to it (remove the key to let the build pick again)\n- exportMethod: app-store-connect (default), release-testing, enterprise or debugging\n- buildType: deprecated; 'release' builds the store IPA with a warning\n- cachePattern: array of globs, e.g. [\"*.css\", \"*.js\"]; a string is read as one pattern, not split on commas\n\nVersion comes from package.json; signing files live in credentials/android/ and credentials/ios/, never in config.json.",
         "layer": "Config",
         "source": "static",
         "tags": ["config", "WEBVIEW_CONFIG", "android", "ios", "required", "fields"]

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "catalyst-core",
-    "version": "1.2.0-canary.4",
+    "version": "1.2.0",
     "type": "module",
     "main": "./dist/index.jsx",
     "description": "Web framework that provides great performance out of the box",

package/test/native/iosInstalledSigning.test.ts

@@ -5,8 +5,10 @@ import path from "path"
 import { afterEach, describe, expect, it } from "vitest"
 
 import {
+    DEVICE_TEAM_HINT,
     XCODE_TEAM_HINT,
     chooseXcodeTeam,
+    deviceSigningHint,
     missingProfileError,
     createProfileScanner,
     findInstalledProfileIdentity,
@@ -743,4 +745,26 @@ describe("signing failure detail", () => {
             /^For an App Store release/
         )
     })
+
+    it("gives a device build the config hint: the team, or what to check in the profile", () => {
+        const output = 'error: Signing for "iosnativeWebView" requires a development team.'
+        const automatic = planIosSigning({ iosConfig: {} })
+        const error = signingSetupError(
+            "Xcode could not sign the device build",
+            { output },
+            {
+                hint: deviceSigningHint(automatic),
+            }
+        )
+        expect(error.hint).toBe(DEVICE_TEAM_HINT)
+        expect(error.hint).toMatch(/WEBVIEW_CONFIG\.ios\.developmentTeam in config\/config\.json/)
+        expect(error.hint).not.toMatch(/App Store/)
+        const manual = planIosSigning({
+            iosConfig: { developmentTeam: "ABCDE12345", provisioningProfile: "Shop Dev" },
+        })
+        expect(deviceSigningHint(manual)).toBe(
+            'Check that the profile "Shop Dev" set in WEBVIEW_CONFIG.ios.provisioningProfile includes this iPhone, matches the bundle id, and that its certificate is in your keychain.'
+        )
+        expect(deviceSigningHint(undefined)).toBe(DEVICE_TEAM_HINT)
+    })
 })

package/test/native/iosSigning.test.ts

@@ -8,6 +8,7 @@ import { fileURLToPath } from "url"
 import { afterEach, describe, expect, it } from "vitest"
 
 import {
+    DEBUG_BUILD_SETTINGS,
     buildExportOptions,
     findInstalledProfileIdentity,
     isReleaseBuildType,
@@ -784,6 +785,20 @@ describe("signing failures", () => {
     })
 })
 
+describe("debug xcodebuild settings", () => {
+    it("turn off Xcode's debug dylib, so a debug build signs only the app", () => {
+        expect(DEBUG_BUILD_SETTINGS).toEqual(["ENABLE_DEBUG_DYLIB=NO"])
+    })
+
+    it("go into the simulator command and the iPhone arguments, not the release archive", () => {
+        const build = fs.readFileSync(path.join(here, "../../src/native/buildIos/build.js"), "utf8")
+        expect(build).toContain('${DEBUG_BUILD_SETTINGS.join(" ")} \\')
+        expect(build).toMatch(/"ONLY_ACTIVE_ARCH=YES",\s+\.\.\.DEBUG_BUILD_SETTINGS,/)
+        const index = fs.readFileSync(path.join(here, "../../src/native/buildIos/index.js"), "utf8")
+        expect(index).not.toContain("DEBUG_BUILD_SETTINGS")
+    })
+})
+
 describe("generateXCConfig signing and version", () => {
     function phase(iosConfig: Record<string, any>, extra: Record<string, any> = {}) {
         const projectDir = tempDir()

package/test/native/setupServer.test.ts

@@ -56,11 +56,17 @@ describe("getDeviceReachableHost", () => {
         expect(
             getDeviceReachableHost({ localHostName: () => "Janes-MacBook-Pro\n", interfaces: {} as any })
         ).toEqual({
-            host: "Janes-MacBook-Pro.local",
+            host: "janes-macbook-pro.local",
             source: "bonjour",
         })
     })
 
+    it("lowercases the Bonjour name, since WebKit sends the Host header lowercased", () => {
+        expect(
+            getDeviceReachableHost({ localHostName: () => "G206F1WHVF", interfaces: {} as any })?.host
+        ).toBe("g206f1whvf.local")
+    })
+
     it("falls back to the LAN IP, then null", () => {
         const fails = () => {
             throw new Error("no scutil")

package/test/vite/resolveDevServerConfig.test.js

@@ -125,6 +125,14 @@ test("withExtraAllowedHosts: adds the env hosts to the app's list", () => {
     assert.equal(withExtraAllowedHosts(undefined, ""), undefined)
 })
 
+test("withExtraAllowedHosts: lowercases the env hosts and compares them exactly, as Vite does", () => {
+    assert.deepEqual(withExtraAllowedHosts(undefined, "G206F1WHVF.local"), ["g206f1whvf.local"])
+    assert.deepEqual(withExtraAllowedHosts(["My-Mac.local"], "my-mac.local"), [
+        "My-Mac.local",
+        "my-mac.local",
+    ])
+})
+
 test("buildDevServer: CATALYST_DEV_ALLOWED_HOSTS reaches server.allowedHosts", () => {
     const before = process.env.CATALYST_DEV_ALLOWED_HOSTS
     process.env.CATALYST_DEV_ALLOWED_HOSTS = "my-mac.local"