catalyst-core 0.3.0-canary.1 → 0.3.0-canary.3

package/changelog.md

@@ -1,14 +1,6 @@
-# 1.0.0-beta.1
-
-- Replaced the Webpack build and SSR pipeline with Vite and ESM.
-- Added React 19 Suspense-aware routing, split components, and manifest-based asset loading.
-- Added opt-in request, compression, flush, and bot-aware OpenTelemetry spans.
-- Preserved native application builds, internal plugins, Sentry exports, and safe-area SSR hydration.
-- Removed the legacy `devBuild` and `devServe` commands.
-
 # Changelog
 
-## [0.4.0] - unreleased
+## [1.0.0] - unreleased
 
 This release freezes the public API. The root entry of `catalyst-core` now exports exactly eight names and nothing else: `RouterDataProvider`, `useCurrentRouteData`, `useRouterData`, `MetaTag`, `split`, `hydrationReady`, `Head`, and `Body`. Anything previously reachable through the root entry but not in that list is no longer public. Applications that import a removed name will fail at build time rather than silently resolving to `undefined`.
 
@@ -68,7 +60,7 @@ Where a hook had two names for one value, the shorter one is canonical and the o
 
 Hooks fall into three categories, and the category decides whether a hook has `execute`. A hook that wraps a single native operation exposes it as `execute` plus a domain-specific alias — `takePhoto`, `pickFile`, `openFile`, `signIn`, `trigger`, `request`. A hook that wraps several distinct operations has no single action to name, so its named functions are the API and it has no `execute` at all: `useVideoStream`, `useDataProtection`, and `useNativeTransition` work this way. A read-only hook reports ambient device state and has no action functions at all: `useNetworkStatus`, `useDeviceInfo`, and `useSafeArea` return state plus the runtime-context keys. `useNotification` is the one exception. It carries `execute` and `schedule` as aliases of `scheduleLocal` for backward compatibility. Both are frozen, both are discouraged, and neither should be read as the pattern for multi-action hooks. `execute` never takes an operation name as a string argument; it takes the arguments of the operation itself.
 
-Hook errors are `CatalystError` values from the framework-wide error registry introduced in this release, carrying a `RUNTIME-NATIVE-*` code, a message, a category, a suggested action, a documentation link, and the originating platform error as `cause`. `useVideoStream` in particular used to report seventeen failures as bare `{ message }` objects with no code at all; those now carry real codes, and a camera denial reports the same code whether it comes from the permission hook or the stream.
+Hook errors are `CatalystError` values from the framework-wide error registry introduced in this release, carrying a `RUNTIME-NATIVE-*` code, a message, a category, a suggested action, a documentation link, and the originating platform error as `cause`. `useVideoStream` in particular used to report seventeen failures as bare `{ message }` objects with no code at all; those now carry real codes, and a camera denial reports the same code whether it comes from the permission hook or the stream. The error object's fields changed with it: `action` is now `suggestedAction`, `nativeError` is now `cause`, `recoverable` and `timestamp` are gone, and `code` values are registry codes such as `RUNTIME-NATIVE-001` instead of names such as `PERMISSION_DENIED`, so compare against `ERROR_CODES` from `catalyst-core/errors` rather than string literals.
 
 One consequence for error logging: `CatalystError` extends `Error`, so `message` now lives on the prototype rather than as an own property. Reading `error.message` is unaffected, but `JSON.stringify(error)` no longer includes it. Log `error.message` explicitly, or use the `code` and `docUrl` fields.
 
@@ -86,13 +78,83 @@ The app contract validators in `server/utils/validator.js` used to log a bare me
 
 The route and store checks moved out of the per-request path. `validateGetRoutes` and `validateConfigureStore` now run once when the renderer module loads — at server startup in production, and on the first SSR request in development, where the handler is loaded lazily — rather than once per request inside the handler's `try`/`catch`. The shape of `addMiddlewares` from `server/server.js` is checked during server setup.
 
-Module aliases and `config/config.json` keys are not checked at load time; a missing alias or key still surfaces where it is used. An application that satisfies the contract sees no change. The full contract — the files Catalyst imports by fixed path and the required module aliases — is documented under File Conventions.
+Separately, `catalyst start`, `build` and `serve` now check `config/config.json` and `package.json` before starting and exit with a coded error when either is missing, a required config key is missing, or a required module alias is missing. An application that satisfies the contract sees no change. The full contract — the files Catalyst imports by fixed path and the required module aliases — is documented under File Conventions.
+The webpack-era keys `WEBPACK_DEV_SERVER_HOSTNAME`, `WEBPACK_DEV_SERVER_PORT` and `ANALYZE_BUNDLE` are no longer required or read; remove them from `config/config.json`.
+
+## [0.3.0-beta.5] - 2026-08-18
+
+- Upgrade react-router-dom v6 to v7.18.2 (CVE fixes) (#399).
+- Docs: clarify setMetaData must return array of JSX elements (#327).
+
+## [0.3.0-beta.4] - 2026-08-10
+
+- Detect CommonJS by parsing, not by matching source text (#397).
+- Sub-path base + HMR config for reverse-proxy dev setups (#379).
+
+## [0.3.0-beta.3] - 2026-08-04
+
+- Resolve semgrep and dependency findings from security scan (#375).
+
+## [0.3.0-beta.2] - 2026-08-03
+
+- @catalyst/cloud-ai — multi-provider AI integration with useAI hook (#288).
+- Eliminate SSR streaming race between onShellReady and onAllReady (#323).
+- Update iOS release docs and MCP guidance (#324).
+- Patch @tailwindcss/postcss base so Vite scans the whole app (#326).
+
+## [0.3.0-beta.1] - 2026-07-15
+
+- Replaced the Webpack build and SSR pipeline with Vite and ESM.
+- Added React 19 Suspense-aware routing, split components, and manifest-based asset loading.
+- Added opt-in request, compression, flush, and bot-aware OpenTelemetry spans.
+- Preserved native application builds, internal plugins, Sentry exports, and safe-area SSR hydration.
+- Removed the legacy `devBuild` and `devServe` commands.
+
+## [0.2.0-beta.3] - 2026-07-14
+
+- Catalyst Profiler Runtime (#274).
+
+## [0.2.0-beta.2] - 2026-07-09
+
+- Route Caching (#287).
+- Android build fixes (#303).
+
+## [0.2.0-beta.1] - 2026-07-08
+
+- Catalyst react + rendering update (#293).
+- Add GitHub feedback integration to Catalyst MCP v2 (#272).
+- Sync MCP v2: extract seeding, delegate docs sync, add FTS + initial sync (#295).
+
+## [0.1.0-beta.7] - 2026-06-29
+
+- Syncing dweb branch with main (#283).
+
+## [0.1.0-beta.6] - 2026-06-11
+
+- Add examples folder with local testing app for catalyst-core (#246).
+
+## [0.1.0-beta.5] - 2026-06-09
+
+- Semgrep Plugin Fixes (#266).
+
+## [0.1.0-beta.4] - 2026-06-03
+
+- Merge video hook, web fallback, and plugin system into monorepo (#258).
+
+## [0.1.0-beta.3] - 2026-06-02
+
+- Security Fixes (semgrep) (#259).
+- Catalyst Docs Mismatches Fix (#244).
 
 ## [0.1.0-beta.2] - 2026-05-06
 
 - Moved Catalyst into a monorepo structure with `catalyst-core`, `create-catalyst-app`, the Catalyst docs app, and the Catalyst core test app managed from one repository.
 - Replaced the internal-package pre-release flow with a local release sandbox that scaffolds a real app using current-branch CCA and a locally packed current-branch `catalyst-core`.
 
+## [0.1.0-canary.9] - 2026-05-06
+
+- Changelog-only update; same code as 0.1.0-beta.2.
+
 ## [0.1.0-canary.8] - 2026-04-15
 
 - Introduced Catalyst’s internal plugin architecture, adding the `PluginBridge` web API, native plugin runtimes for Android and iOS, and manifest-driven build composition for modular native capabilities.
@@ -120,7 +182,7 @@ Module aliases and `config/config.json` keys are not checked at load time; a mis
 - Improved universal app runtime behavior with safe-area inset support, edge-to-edge rendering, and notification permission override fixes.
 - Expanded platform support with offline fallback handling, notification/access-control refinements, localhost HTTP allowances for local development, and file-picker/HTTPS server improvements.
 
-## [0.1.0-canary.4] - 2026-02-12
+## [0.1.0-canary.4] - 2026-02-16
 
 - Added Google Sign-In support for both Android and iOS in Catalyst, enabling a unified native authentication experience for apps built on the framework.
 - Improved release/build reliability with related bridge and CI updates, making integration smoother and more consistent across platforms.
@@ -148,26 +210,26 @@ Module aliases and `config/config.json` keys are not checked at load time; a mis
 - Notification refactor: streamlined config toggle for local vs push, centralized permission/asset handling, and simpler routing into the web app
 - Access control: combined access control config for ios
 
-## [0.0.3-canary.18] - 2025-11-19
+## [0.0.3-canary.18] - 2025-11-25
 
 - Configuration Files
 - Android Native WebView - MainActivity.kt
 - Android Native WebView - CustomWebview.kt
 
-## [0.0.3-canary.17] - 2025-11-19
+## [0.0.3-canary.17] - 2025-11-21
 
-- ✨ Added complete notification system (local & push)
-- 🔔 New useNotification() React hook
-- 📱 Firebase Cloud Messaging conditional build support
-- 🤖 Android notification handling in MainActivity
-- 🔧 5 new notification commands + 5 callbacks in NativeBridge
-- 📦 Auto-processing of notification icons & sounds
-- ⚙️ Conditional dependencies based on notification config
-- 🧹 Updated .gitignore & .npmignore
-- 📋 Enhanced build process with automatic permission injection
-- 🔗 Deep link integration with notifications
+- Added complete notification system (local & push)
+- New useNotification() React hook
+- Firebase Cloud Messaging conditional build support
+- Android notification handling in MainActivity
+- 5 new notification commands + 5 callbacks in NativeBridge
+- Auto-processing of notification icons & sounds
+- Conditional dependencies based on notification config
+- Updated .gitignore & .npmignore
+- Enhanced build process with automatic permission injection
+- Deep link integration with notifications
 
-## [0.0.3-canary.16] - 2025-11-19
+## [0.0.3-canary.16] - 2025-11-20
 
 - FeaturesGallery Support for File Picker: Enhanced file picker to open native gallery for selecting images and videos
 - HTTPS Framework Server: Enabled HTTPS support for the framework server with self-signed SSL certificate
@@ -177,17 +239,17 @@ Module aliases and `config/config.json` keys are not checked at load time; a mis
 
 - Adding Android release support and appInfo key
 
-## [0.0.3-canary.14] - 2025-09-29
+## [0.0.3-canary.14] - 2025-10-29
 
 - Android custom splashscreen
 
-## [0.0.3-canary.13] - 2025-09-28
+## [0.0.3-canary.13] - 2025-10-28
 
 - Multi file support in useFilePicker hook
 - Android multiple app icon support
 - Android whitelisting toggle support
 
-## [0.0.3-canary.12] - 2025-09-26
+## [0.0.3-canary.12] - 2025-10-13
 
 - Universal App Context: Added comprehensive context support for building universal mobile applications
 - OpenTelemetry SDK Integration: Built-in support for observability and performance monitoring with Otel SDK
@@ -198,70 +260,42 @@ Module aliases and `config/config.json` keys are not checked at load time; a mis
 - Enhanced Android native support: Add support for native keyboard and webview resizing in Android
 - Device info API web support: Web support in device info API
 
-## [0.0.3-canary.10] - 2025-09-11
+## [0.0.3-canary.10] - 2025-09-17
 
-- **Sentry import bug fix**
-- **Open telemetry SDK**
+- Sentry import bug fix.
+- Open telemetry SDK.
 
 ## [0.0.3-canary.9] - 2025-09-11
 
-- **App name configuration**
-- **Device Info API**
-- **Access control configuration**
-
-## [0.0.3-canary.8] - 2025-01-06
-
-- **App icon configuration**
-- **Splash screen integration**
-- **Url Whitelisting**
+- App name configuration.
+- Device Info API.
+- Access control configuration.
 
-## [0.0.3-canary.7] - 2025-01-06
+## [0.0.3-canary.8] - 2025-08-08
 
-### 🚀 Features
+- App icon configuration.
+- Splash screen integration.
+- Url Whitelisting.
 
-- **Native API Integration**: Enhanced native module integration for better performance
-- **Automated IP Resolution**: Intelligent network detection eliminates manual IP configuration
-- **Universal Build System**: Streamlined one-command builds for both Android and iOS platforms
-- **Enhanced CLI Interface**: Improved command-line tools for better developer experience
-
-### 🐛 Bug Fixes
+## [0.0.3-canary.7] - 2025-08-06
 
+- Native API Integration: Enhanced native module integration for better performance
+- Automated IP Resolution: Intelligent network detection eliminates manual IP configuration
+- Universal Build System: Streamlined one-command builds for both Android and iOS platforms
+- Enhanced CLI Interface: Improved command-line tools for better developer experience
 - Fixed IP address detection issues on development environments
 - Resolved build configuration conflicts between platforms
 - Improved error handling and recovery mechanisms
-
-### 🔧 Improvements
-
-- **Performance**: Optimized native module loading and execution
-- **Developer Experience**: Enhanced CLI with better error messages and debugging info
-- **Configuration**: Dynamic config updates without requiring restarts
-- **Build Process**: Faster and more reliable build pipeline
-
-### 🧪 Testing & Validation
-
-- ✅ **Android Build**: Verified APK generation, installation, and runtime behavior
-- ✅ **iOS Build**: Tested build process and device compatibility
-- ✅ **IP Detection**: Validated automatic network resolution across platforms
-- ✅ **Native Modules**: Confirmed API integration and performance benchmarks
-- ✅ **CLI Operations**: Tested enhanced command-line workflows and error handling
-
-### 🔄 Breaking Changes
-
-**None** - All changes maintain backward compatibility while enhancing existing functionality
-
-### 📝 Technical Details
-
+- Performance: Optimized native module loading and execution
+- Developer Experience: Enhanced CLI with better error messages and debugging info
+- Configuration: Dynamic config updates without requiring restarts
+- Build Process: Faster and more reliable build pipeline
+- Android Build: Verified APK generation, installation, and runtime behavior
+- iOS Build: Tested build process and device compatibility
+- IP Detection: Validated automatic network resolution across platforms
+- Native Modules: Confirmed API integration and performance benchmarks
+- CLI Operations: Tested enhanced command-line workflows and error handling
 - Improved native API bridge for better cross-platform communication
 - Enhanced error reporting with detailed stack traces and suggestions
 - Optimized build configuration for faster development cycles
 - Added comprehensive logging for debugging and monitoring
-
-### 🔗 Migration Notes
-
-- No migration steps required
-- Existing projects will automatically benefit from improvements
-- Optional: Update CLI usage to leverage new enhanced features
-
-## Version
-
-- Target version: 0.0.3-canary.7

package/dist/errors/registry.js

@@ -28,7 +28,9 @@ export const ERROR_CODES = {
 
     BUNDLE_UPSTREAM_ERROR: "BUNDLE-000",
     IOS_UPSTREAM_ERROR: "IOS-000",
+    IOS_SIMULATOR_APP_NOT_FOUND: "IOS-001",
     ANDROID_UPSTREAM_ERROR: "ANDROID-000",
+    ANDROID_EMULATOR_BOOT_TIMEOUT: "ANDROID-001",
 
     RUNTIME_NATIVE_PERMISSION_DENIED: "RUNTIME-NATIVE-001",
     RUNTIME_NATIVE_PERMISSION_REQUIRED: "RUNTIME-NATIVE-002",
@@ -231,12 +233,27 @@ export const ERROR_DEFINITIONS = {
         defaultDetails: "This wraps an error from Xcode/CocoaPods. See the printed upstream output for the cause.",
         suggestedAction: "Read the upstream Xcode/CocoaPods error printed above and fix the underlying issue.",
     },
+    [ERROR_CODES.IOS_SIMULATOR_APP_NOT_FOUND]: {
+        category: "IOS",
+        defaultMessage: "Could not find an installed iOS Simulator app",
+        defaultDetails:
+            "Neither DeviceHub.app (Xcode 27+, bundle id com.apple.dt.Devices) nor the legacy Simulator.app (bundle id com.apple.iphonesimulator) is installed under Xcode's Contents/Applications. The simulator itself may still boot headlessly via simctl, but catalyst-core cannot open or focus its window.",
+        suggestedAction: "Confirm a full Xcode.app (not just Command Line Tools) is installed and selected via xcode-select -p, then reopen it once from Spotlight so macOS registers its app bundle.",
+    },
     [ERROR_CODES.ANDROID_UPSTREAM_ERROR]: {
         category: "ANDROID",
         defaultMessage: "Android build failed in an upstream toolchain step",
         defaultDetails: "This wraps an error from Gradle. See the printed upstream output for the cause.",
         suggestedAction: "Read the upstream Gradle error printed above and fix the underlying issue.",
     },
+    [ERROR_CODES.ANDROID_EMULATOR_BOOT_TIMEOUT]: {
+        category: "ANDROID",
+        defaultMessage: "Timed out waiting for the Android emulator to boot",
+        defaultDetails:
+            "buildApp:android launched the configured AVD but it did not appear in `adb devices` or did not finish booting (sys.boot_completed=1 and init.svc.bootanim=stopped) within the timeout.",
+        suggestedAction:
+            "Try booting the AVD manually first (emulator -avd <name>) to see the actual startup error, check available disk space/RAM, or increase the emulator's cold-boot allowance if the device is unusually slow.",
+    },
 
     [ERROR_CODES.RUNTIME_NATIVE_PERMISSION_DENIED]: {
         category: "RUNTIME-NATIVE",

package/dist/errors-index.json

@@ -244,6 +244,13 @@
         "suggestedAction": "Read the upstream Xcode/CocoaPods error printed above and fix the underlying issue.",
         "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/IOS/IOS-000.md"
     },
+    "IOS-001": {
+        "category": "IOS",
+        "message": "Could not find an installed iOS Simulator app",
+        "details": "Neither DeviceHub.app (Xcode 27+, bundle id com.apple.dt.Devices) nor the legacy Simulator.app (bundle id com.apple.iphonesimulator) is installed under Xcode's Contents/Applications. The simulator itself may still boot headlessly via simctl, but catalyst-core cannot open or focus its window.",
+        "suggestedAction": "Confirm a full Xcode.app (not just Command Line Tools) is installed and selected via xcode-select -p, then reopen it once from Spotlight so macOS registers its app bundle.",
+        "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/IOS/IOS-001.md"
+    },
     "ANDROID-000": {
         "category": "ANDROID",
         "message": "Android build failed in an upstream toolchain step",
@@ -251,6 +258,13 @@
         "suggestedAction": "Read the upstream Gradle error printed above and fix the underlying issue.",
         "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/ANDROID/ANDROID-000.md"
     },
+    "ANDROID-001": {
+        "category": "ANDROID",
+        "message": "Timed out waiting for the Android emulator to boot",
+        "details": "buildApp:android launched the configured AVD but it did not appear in `adb devices` or did not finish booting (sys.boot_completed=1 and init.svc.bootanim=stopped) within the timeout.",
+        "suggestedAction": "Try booting the AVD manually first (emulator -avd <name>) to see the actual startup error, check available disk space/RAM, or increase the emulator's cold-boot allowance if the device is unusually slow.",
+        "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/ANDROID/ANDROID-001.md"
+    },
     "RUNTIME-NATIVE-001": {
         "category": "RUNTIME-NATIVE",
         "message": "Permission denied",

package/dist/native/buildAndroid/build.js

@@ -2,6 +2,10 @@
 
 const fs = require("fs");
 const path = require("path");
+const {
+  spawn,
+  execFileSync
+} = require("child_process");
 const {
   buildAndroidAAB
 } = require("../renameAndroidProject.js");
@@ -101,36 +105,176 @@ function createBuildPhase(ctx) {
       return false;
     }
   }
+
+  // Returns the serial of an online emulator (adb state "device"), or null if
+  // none is online. `devices.includes("emulator")` alone would also match a
+  // serial like "emulator-5554" whose state is "offline" or still enumerating —
+  // i.e. a device that's connected but not actually ready — so this checks the
+  // state column explicitly rather than doing a substring match.
   async function checkEmulator(ADB_PATH) {
     try {
       // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - ADB_PATH is derived from androidConfig.sdkPath, a trusted internal config value.
       const devices = ctx.runCommand(`${ADB_PATH} devices`);
-      return devices.includes("emulator");
+      const onlineEmulator = devices.split("\n").map(line => line.trim().split(/\s+/)).find(([id, state]) => id?.startsWith("emulator-") && state === "device");
+      return onlineEmulator ? onlineEmulator[0] : null;
     } catch (error) {
       progress.log("Error checking emulator status: " + error.message, "error");
-      return false;
+      return null;
     }
   }
+
+  // The Android emulator binary is a long-running server process — it does not
+  // exit after boot, it keeps running until the emulator window is closed. Using
+  // runInteractiveCommand (which only resolves on the child's `close` event, see
+  // utils.js) would block forever waiting for an exit that never happens before
+  // the app finishes booting. Spawn it detached instead (same approach as
+  // androidSetup.js's startEmulator) and let handleEmulatorSetup poll for
+  // readiness separately.
+  /**
+   * Launch the emulator detached and return once it has actually spawned
+   * (not once it exits — see the note above on why runInteractiveCommand
+   * can't be used here).
+   * @returns {Promise<number>} the spawned process's pid, so a caller whose
+   *   boot-readiness wait times out can kill it instead of leaving a
+   *   CPU/RAM-heavy orphaned emulator running past a failed build.
+   */
   async function startEmulator(EMULATOR_PATH, androidConfig) {
     progress.log(`Starting emulator: ${androidConfig.emulatorName}...`, "info");
-    // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - EMULATOR_PATH is derived from androidConfig.sdkPath, a trusted internal config value.
-    return ctx.runInteractiveCommand(EMULATOR_PATH, ["-avd", androidConfig.emulatorName, "-read-only"], {}).then(() => {
-      progress.log("Emulator started successfully", "success");
-    }).catch(error => {
-      progress.log("Error starting emulator: " + error.message, "error");
-      throw error;
+    return new Promise((resolve, reject) => {
+      // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - spawn with an argv array (no shell), so androidConfig.emulatorName can't be interpreted as shell syntax even though it comes from a locally-editable config file.
+      const child = spawn(EMULATOR_PATH, ["-avd", androidConfig.emulatorName, "-read-only"], {
+        detached: true,
+        stdio: "ignore"
+      });
+      child.once("error", error => {
+        progress.log("Error starting emulator: " + error.message, "error");
+        reject(error);
+      });
+      // "error" only fires for spawn failures (e.g. bad EMULATOR_PATH); once the
+      // process has actually spawned we can detach and let the caller poll adb
+      // for boot readiness rather than waiting on this child at all.
+      child.once("spawn", () => {
+        const {
+          pid
+        } = child;
+        child.unref();
+        progress.log("Emulator process started, waiting for it to boot...", "info");
+        resolve(pid);
+      });
     });
   }
+
+  // Best-effort cleanup for an emulator process this build spawned but that
+  // never became ready — kills the whole detached process group (negative pid)
+  // so we don't leave a CPU/RAM-heavy orphaned emulator running after a failed
+  // build. Never throws: a failure here shouldn't mask the original timeout error.
+  function killOrphanedEmulator(pid, emulatorName) {
+    try {
+      process.kill(-pid, "SIGTERM");
+      progress.log(`Stopped orphaned emulator process (pid ${pid}) after boot failure`, "info");
+    } catch (error) {
+      progress.log(`Could not stop orphaned emulator "${emulatorName}" (pid ${pid}): ${error.message}. ` + "You may need to quit it manually.", "warning");
+    }
+  }
+  function listEmulatorSerials(ADB_PATH) {
+    try {
+      // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - ADB_PATH is derived from androidConfig.sdkPath, a trusted internal config value.
+      const devices = ctx.runCommand(`${ADB_PATH} devices`);
+      return devices.split("\n").map(line => line.trim().split(/\s+/)[0]).filter(id => id && id.startsWith("emulator-"));
+    } catch {
+      return [];
+    }
+  }
+
+  // Waits for a NEW emulator-XXXX serial to appear in `adb devices` (one not in
+  // knownSerials, captured before startEmulator was called), so boot polling can
+  // be scoped to the emulator this build just launched rather than whichever
+  // device `adb shell` (with no -s) happens to pick when multiple are connected.
+  async function waitForNewEmulatorSerial(ADB_PATH, knownSerials, {
+    timeoutMs = 30000,
+    pollIntervalMs = 1000
+  } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const current = listEmulatorSerials(ADB_PATH);
+      const newSerial = current.find(id => !knownSerials.includes(id));
+      if (newSerial) return newSerial;
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+    return null;
+  }
+
+  /**
+   * Poll a specific emulator (by adb serial, e.g. "emulator-5554") until it
+   * reports a completed boot and a stopped boot animation, or the timeout
+   * elapses.
+   * @param {string} ADB_PATH Path to the adb executable.
+   * @param {string} serial The emulator's adb serial to target (adb -s).
+   * @param {Object} [options]
+   * @param {number} [options.timeoutMs=120000] Overall deadline in milliseconds.
+   * @param {number} [options.pollIntervalMs=2000] Delay between readiness checks.
+   * @returns {Promise<boolean>} true once both readiness signals are observed;
+   *   false if the deadline elapses first (a transient/hung adb call counts
+   *   against the same deadline via the per-call execFileSync timeout below).
+   */
+  async function waitForEmulatorBoot(ADB_PATH, serial, {
+    timeoutMs = 120000,
+    pollIntervalMs = 2000
+  } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    const getprop = prop => {
+      const remaining = Math.max(deadline - Date.now(), 1000);
+      return execFileSync(ADB_PATH, ["-s", serial, "shell", "getprop", prop], {
+        encoding: "utf8",
+        timeout: remaining
+      }).trim();
+    };
+    while (Date.now() < deadline) {
+      try {
+        const bootCompleted = getprop("sys.boot_completed");
+        const bootAnimDone = getprop("init.svc.bootanim");
+        if (bootCompleted === "1" && bootAnimDone === "stopped") return true;
+      } catch {
+        // adb not ready yet (device still enumerating), or this call hit its
+        // own per-call timeout — either way, keep polling against the outer
+        // deadline rather than treating it as fatal.
+      }
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+    return false;
+  }
+
+  // Message mirrors errors/registry.js ERROR_DEFINITIONS[ANDROID-001] (see
+  // errors/ANDROID/ANDROID-001.md) — this CJS subtree can't import the ESM
+  // error registry (see buildErrorFormat.js), so the code is prefixed onto the
+  // thrown message directly rather than imported.
+  function emulatorBootTimeoutError(detail) {
+    return new Error(`[ANDROID-001] Timed out waiting for the Android emulator to boot: ${detail}`);
+  }
   async function handleEmulatorSetup(ADB_PATH, EMULATOR_PATH, androidConfig) {
     progress.log("Setting up emulator...", "info");
-    const emulatorRunning = await checkEmulator(ADB_PATH);
-    if (!emulatorRunning) {
+    let serial = await checkEmulator(ADB_PATH);
+    let pid = null;
+    if (!serial) {
       progress.log("No emulator running, attempting to start one...", "info");
-      await startEmulator(EMULATOR_PATH, androidConfig);
-      await new Promise(resolve => setTimeout(resolve, 5000));
+      const knownSerials = listEmulatorSerials(ADB_PATH);
+      pid = await startEmulator(EMULATOR_PATH, androidConfig);
+      serial = await waitForNewEmulatorSerial(ADB_PATH, knownSerials);
+      if (!serial) {
+        killOrphanedEmulator(pid, androidConfig.emulatorName);
+        throw emulatorBootTimeoutError(`emulator "${androidConfig.emulatorName}" never appeared in adb devices`);
+      }
     } else {
-      progress.log("Emulator already running", "success");
+      progress.log(`Emulator ${serial} already online, confirming it's fully booted...`, "info");
+    }
+    // Wait for boot readiness whether the emulator was already online (it may
+    // still be finishing its boot animation) or was just launched above.
+    const booted = await waitForEmulatorBoot(ADB_PATH, serial);
+    if (!booted) {
+      if (pid) killOrphanedEmulator(pid, androidConfig.emulatorName);
+      throw emulatorBootTimeoutError(`emulator "${androidConfig.emulatorName}" (${serial}) never finished booting`);
     }
+    progress.log("Emulator booted successfully", "success");
     return {
       type: "emulator",
       name: androidConfig.emulatorName
@@ -286,6 +430,7 @@ function createBuildPhase(ctx) {
     checkEmulator,
     handleEmulatorSetup,
     startEmulator,
+    waitForEmulatorBoot,
     buildApp,
     launchApp,
     createAABConfig,