catalyst-core 1.0.1 → 1.0.2-canary.2

package/dist/native/androidSetup.js

@@ -10,29 +10,25 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 const catalystCorePath = _path.default.dirname(require.resolve("catalyst-core/package.json"));
 const pwd = _path.default.join(catalystCorePath, "dist/native");
 const configPath = `${process.env.PWD}/config/config.json`;
+
+// Sentence case, verb first: these read as a sequence of actions, not as
+// headings.
 const steps = {
-  java: "Check Java Environment",
-  config: "Initialize Configuration",
-  androidTools: "Validate Android Tools",
-  emulator: "Configure Android Emulator",
-  properties: "Update Local Properties",
-  saveConfig: "Save Configuration",
-  setupServer: "Setup Server"
-};
-const progressPaddingConfig = {
-  titlePaddingTop: 2,
-  titlePaddingBottom: 1,
-  stepPaddingLeft: 4,
-  stepSpacing: 1,
-  errorPaddingLeft: 6,
-  bottomMargin: 2
+  java: "Check Java environment",
+  config: "Initialize configuration",
+  androidTools: "Validate Android tools",
+  emulator: "Configure Android emulator",
+  properties: "Update local.properties",
+  saveConfig: "Save configuration",
+  setupServer: "Set up server"
 };
-const progress = new _terminalProgress.default(steps, "Catalyst Universal Android Setup", progressPaddingConfig);
+const progress = new _terminalProgress.default(steps, "catalyst setupEmulator", {
+  subject: "android"
+});
 async function checkJavaInstallation() {
   try {
     (0, _utils.runCommand)("java -version");
     (0, _utils.runCommand)("javac -version");
-    progress.log("Java is installed and configured", "success");
     return true;
   } catch (error) {
     progress.log("Java installation not found or not properly configured", "error");
@@ -87,23 +83,23 @@ async function installJava() {
     // Verify Java configuration
     try {
       const javaVersion = (0, _utils.runCommand)("java -version");
-      progress.log("Java installed and configured successfully", "success");
+      progress.log("Installed Java 17 (Zulu)", "info");
       progress.log(`Java Version: ${javaVersion}`, "info");
       progress.log(`IMPORTANT: Please run the following commands to complete setup:`, "warning");
-      progress.log(`1. source ${shellProfile}`, "info");
-      progress.log(`2. echo $JAVA_HOME`, "info");
+      progress.log(`1. source ${shellProfile}`, "note");
+      progress.log(`2. echo $JAVA_HOME`, "note");
       return true;
     } catch (error) {
       throw new Error(`Java installation verified but environment not configured. Please run:\n1. source ${shellProfile}\n2. echo $JAVA_HOME`);
     }
   } catch (error) {
     progress.log(error.message, "error");
-    progress.log("Manual Setup Instructions:", "info");
-    progress.log("1. Run: brew reinstall --cask zulu@17", "info");
-    progress.log("2. Add to ~/.zshrc:", "info");
-    progress.log("   export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home", "info");
-    progress.log("   export PATH=$JAVA_HOME/bin:$PATH", "info");
-    progress.log("3. Run: source ~/.zshrc", "info");
+    progress.log("Manual Setup Instructions:", "note");
+    progress.log("1. Run: brew reinstall --cask zulu@17", "note");
+    progress.log("2. Add to ~/.zshrc:", "note");
+    progress.log("   export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home", "note");
+    progress.log("   export PATH=$JAVA_HOME/bin:$PATH", "note");
+    progress.log("3. Run: source ~/.zshrc", "note");
     throw error;
   }
 }
@@ -149,18 +145,19 @@ async function saveConfig(newConfig) {
       }
     };
     _fs.default.writeFileSync(configPath, JSON.stringify(updatedConfig, null, 2));
-    progress.log("Configuration saved successfully", "success");
   } catch (error) {
     progress.log("Failed to save configuration: " + error.message, "error");
     process.exit(1);
   }
 }
 function validateAndroidTools(androidConfig) {
-  const ANDROID_SDK = androidConfig.sdkPath;
+  const ANDROID_SDK = (0, _utils.expandHome)(androidConfig.sdkPath);
   const EMULATOR_PATH = `${ANDROID_SDK}/emulator/emulator`;
   const ADB_PATH = `${ANDROID_SDK}/platform-tools/adb`;
   if (!ANDROID_SDK) {
-    throw new Error("Android SDK path is not configured");
+    throw Object.assign(new Error("Android SDK not found"), {
+      hint: _utils.ANDROID_SDK_HINT
+    });
   }
   if (!_fs.default.existsSync(ANDROID_SDK)) {
     throw new Error(`Android SDK path does not exist: ${ANDROID_SDK}`);
@@ -170,7 +167,6 @@ function validateAndroidTools(androidConfig) {
   }
   try {
     (0, _utils.runCommand)(`${ADB_PATH} version`);
-    progress.log("ADB is valid", "success");
   } catch (error) {
     throw new Error(`ADB is not working properly: ${error.message}`);
   }
@@ -179,7 +175,6 @@ function validateAndroidTools(androidConfig) {
   }
   try {
     (0, _utils.runCommand)(`${EMULATOR_PATH} -version`);
-    progress.log("Emulator is valid", "success");
   } catch (error) {
     throw new Error(`Emulator is not working properly: ${error.message}`);
   }
@@ -188,11 +183,10 @@ function validateAndroidTools(androidConfig) {
     if (!avdOutput.includes(androidConfig.emulatorName)) {
       throw new Error(`Specified emulator "${androidConfig.emulatorName}" not found in available AVDs`);
     }
-    progress.log(`Emulator "${androidConfig.emulatorName}" exists`, "success");
+    progress.log(`Using emulator "${androidConfig.emulatorName}"`, "info");
   } catch (error) {
     throw new Error(`Error checking emulator AVD: ${error.message}`);
   }
-  progress.log("Android tools validation completed successfully!", "success");
   return {
     EMULATOR_PATH,
     ADB_PATH
@@ -200,7 +194,9 @@ function validateAndroidTools(androidConfig) {
 }
 async function checkEmulator(ADB_PATH) {
   try {
-    const devices = (0, _utils.runCommand)(`${ADB_PATH} devices`);
+    const devices = (0, _utils.runCommand)(`${ADB_PATH} devices`, {
+      timeout: 15000
+    });
     return devices.includes("emulator");
   } catch (error) {
     progress.log(`Error checking emulator: ${error}`, "error");
@@ -223,7 +219,6 @@ async function updateLocalProperties(sdkPath) {
   progress.start("properties");
   try {
     (0, _utils.runCommand)(`cd ${pwd}/androidProject && ./gradlew updateSdkPath -PsdkPath="${sdkPath}"`);
-    progress.log("Updated local.properties successfully", "success");
     progress.complete("properties");
   } catch (error) {
     progress.fail("properties", `Failed to update local.properties: ${error.message}`);
@@ -249,11 +244,11 @@ async function setupAndroidEnvironment() {
       progress.log("No emulator running, attempting to start one...");
       await startEmulator(EMULATOR_PATH, config.android);
     } else {
-      progress.log("Emulator already running, proceeding with installation...", "success");
+      progress.log("Emulator already running", "info");
     }
     progress.complete("emulator");
     if (config.android?.sdkPath) {
-      await updateLocalProperties(config.android.sdkPath);
+      await updateLocalProperties((0, _utils.expandHome)(config.android.sdkPath));
     }
     progress.start("saveConfig");
     await saveConfig({
@@ -261,40 +256,34 @@ async function setupAndroidEnvironment() {
     });
     progress.complete("saveConfig");
     progress.start("setupServer");
-    await (0, _setupServer.setupServer)(configPath);
+    await (0, _setupServer.setupServer)(configPath, message => progress.log(message, "info"));
     progress.complete("setupServer");
-    progress.printTreeContent("Configuration Explanation", ["WEBVIEW_CONFIG: Main configuration object for the WebView setup", {
-      text: "port: Port number for the WebView server",
-      indent: 1,
-      prefix: "├─ ",
-      color: "gray"
-    }, {
-      text: "android: Android-specific configuration",
-      indent: 1,
-      prefix: "└─ ",
+
+    // What was configured, not what the keys mean -- the explanation
+    // belongs in the docs, not in every successful run's transcript.
+    // validateAndCompleteConfig returns { port, android: {...} } -- flat,
+    // not nested under WEBVIEW_CONFIG.
+    const androidCfg = config.android || {};
+    progress.printTreeContent("Config  config/config.json", [{
+      text: `port           ${config.port ?? ""}`,
       color: "gray"
     }, {
-      text: "buildType: Build type (debug/release)",
-      indent: 2,
-      prefix: "├─ ",
+      text: `buildType      ${androidCfg.buildType ?? ""}`,
       color: "gray"
     }, {
-      text: "sdkPath: Android SDK path",
-      indent: 2,
-      prefix: "├─ ",
+      text: `sdkPath        ${androidCfg.sdkPath ?? ""}`,
       color: "gray"
     }, {
-      text: "emulatorName: Selected Android emulator name",
-      indent: 2,
-      prefix: "└─ ",
+      text: `emulatorName   ${androidCfg.emulatorName ?? ""}`,
       color: "gray"
     }]);
-    progress.printTreeContent("Final Configuration", [JSON.stringify(config, null, 2)]);
+    progress.summary("Ready", "Run catalyst buildApp:android to install the app");
     process.exit(0);
   } catch (error) {
     if (progress.currentStep) {
       progress.fail(progress.currentStep.id, error.message);
     }
+    progress.hint(error.hint);
     process.exit(1);
   }
 }

package/dist/native/buildAndroid/assets.js

@@ -93,22 +93,36 @@ function createAssetsPhase(ctx) {
       progress.log(`Error processing splash screen: ${error.message}`, "warning");
     }
   }
-  async function copyOfflinePage() {
+
+  // Copies public/<fileName> to assets/<destSubdir>/<fileName>. Optional files are
+  // removed from assets when absent so deleting the source turns the feature off.
+  async function copyPublicHtml(fileName, destSubdir, optional = false) {
     try {
-      const sourcePath = `${process.cwd()}/public/offline.html`;
-      const destDir = `${pwd}/androidProject/app/src/main/assets/offline`;
-      const destPath = `${destDir}/offline.html`;
+      const sourcePath = `${process.cwd()}/public/${fileName}`;
+      const destDir = `${pwd}/androidProject/app/src/main/assets/${destSubdir}`;
+      const destPath = `${destDir}/${fileName}`;
       if (!fs.existsSync(sourcePath)) {
-        progress.log("offline.html not found in public/; skipping offline asset copy", "warning");
+        if (optional) {
+          fs.rmSync(destPath, {
+            force: true
+          });
+          return;
+        }
+        progress.log(`${fileName} not found in public/; skipping ${destSubdir} asset copy`, "warning");
         return;
       }
       ctx.runCommand(`mkdir -p ${destDir}`);
       fs.copyFileSync(sourcePath, destPath);
-      progress.log("offline.html copied to Android assets", "success");
     } catch (error) {
-      progress.log(`Warning: Error copying offline.html: ${error.message}`, "warning");
+      progress.log(`Warning: Error copying ${fileName}: ${error.message}`, "warning");
     }
   }
+  async function copyOfflinePage() {
+    await copyPublicHtml("offline.html", "offline");
+  }
+  async function copySplashHtml() {
+    await copyPublicHtml("splashscreen.html", "splash", true);
+  }
   async function copyIconAssets() {
     try {
       const destPath = `${pwd}/androidProject/app/src/main/res`;
@@ -202,9 +216,6 @@ function createAssetsPhase(ctx) {
       if (hasCustomIcons) {
         progress.log("Applied Android launcher icons from public/android/appIcons.", "success");
       }
-      if (usedFallback) {
-        progress.log("Used bundled Catalyst fallback icon for launcher.", "info");
-      }
     } catch (error) {
       progress.log(`Warning: Error copying app icon assets: ${error.message}`, "warning");
     }
@@ -243,7 +254,6 @@ function createAssetsPhase(ctx) {
           });
         }
         fs.copyFileSync(rootGoogleServicesPath, androidGoogleServicesPath);
-        progress.log("Copied google-services.json to androidProject/app/", "success");
         return true;
       } else if (fs.existsSync(androidGoogleServicesPath)) {
         progress.log("google-services.json already exists in androidProject/app/", "info");
@@ -267,7 +277,6 @@ function createAssetsPhase(ctx) {
       await cleanupNotificationMetadata();
       await cleanupNotificationAssets();
       if (!hasNotificationConfig) {
-        progress.log("Notifications disabled - cleaned up notification configurations", "info");
         return;
       }
       const hasGoogleServices = await handleGoogleServicesJson();
@@ -288,7 +297,6 @@ function createAssetsPhase(ctx) {
       const propertiesPath = `${pwd}/androidProject/app/catalyst-build.properties`;
       const propertiesContent = ["# Generated by Catalyst. Used by Android Studio builds when -PconfigPath is not provided.", `notifications.enabled=${notificationsEnabled ? "true" : "false"}`, ""].join("\n");
       fs.writeFileSync(propertiesPath, propertiesContent);
-      progress.log("Updated generated Android build properties", "success");
     } catch (error) {
       throw new Error(`Failed to write generated Android build properties: ${error.message}`);
     }
@@ -541,6 +549,7 @@ function createAssetsPhase(ctx) {
     copyBuildAssets,
     copySplashscreenAssets,
     copyOfflinePage,
+    copySplashHtml,
     copyIconAssets,
     configureAppName,
     processNotifications

package/dist/native/buildAndroid/build.js

@@ -1,14 +1,25 @@
 "use strict";
 
-const fs = require("fs");
-const path = require("path");
 const {
   spawn,
   execFileSync
 } = require("child_process");
+const fs = require("fs");
+const path = require("path");
 const {
   buildAndroidAAB
 } = require("../renameAndroidProject.js");
+const {
+  ensureLocalProperties
+} = require("../utils.js");
+
+// adb answers in milliseconds when healthy. A wedged adb server accepts the
+// connection and never replies, so without a bound the build sat on
+// "detecting physical devices" forever.
+const ADB_TIMEOUT_MS = 15000;
+
+/** A timed-out device tool is fatal: every later adb call would hang the same way. */
+const isToolTimeout = error => error?.code === "ETOOLTIMEOUT";
 const DEFAULT_DEPLOYMENT_PATH = "./deployment";
 const DEFAULT_OLD_PROJECT_NAME = "androidProject";
 const DEFAULT_OVERWRITE_EXISTING = true;
@@ -21,9 +32,11 @@ function createBuildPhase(ctx) {
   } = ctx;
   async function detectPhysicalDevice(ADB_PATH) {
     try {
-      progress.log("Detecting physical devices...", "info");
+      progress.status("detecting physical devices");
       // 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 -l`);
+      const devices = ctx.runCommand(`${ADB_PATH} devices -l`, {
+        timeout: ADB_TIMEOUT_MS
+      });
       const lines = devices.split("\n").filter(line => line.trim() && !line.includes("List of devices"));
       for (const line of lines) {
         const parts = line.trim().split(/\s+/);
@@ -32,13 +45,17 @@ function createBuildPhase(ctx) {
           if (!deviceId.startsWith("emulator-")) {
             try {
               // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - deviceId comes from adb devices output, not user input.
-              const qemuCheck = ctx.runCommand(`${ADB_PATH} -s ${deviceId} shell getprop ro.kernel.qemu`);
+              const qemuCheck = ctx.runCommand(`${ADB_PATH} -s ${deviceId} shell getprop ro.kernel.qemu`, {
+                timeout: ADB_TIMEOUT_MS
+              });
               if (!qemuCheck.trim()) {
                 progress.log(`Physical device detected: ${deviceId}`, "success");
                 let deviceModel = "Unknown Device";
                 try {
                   // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - deviceId comes from adb devices output, not user input.
-                  const model = ctx.runCommand(`${ADB_PATH} -s ${deviceId} shell getprop ro.product.model`);
+                  const model = ctx.runCommand(`${ADB_PATH} -s ${deviceId} shell getprop ro.product.model`, {
+                    timeout: ADB_TIMEOUT_MS
+                  });
                   deviceModel = model.trim() || deviceModel;
                 } catch (e) {
                   // Ignore model detection errors
@@ -57,6 +74,7 @@ function createBuildPhase(ctx) {
       progress.log("No physical devices detected", "info");
       return null;
     } catch (error) {
+      if (isToolTimeout(error)) throw error;
       progress.log("Error detecting physical devices: " + error.message, "error");
       return null;
     }
@@ -114,15 +132,44 @@ function createBuildPhase(ctx) {
   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`);
+      const devices = ctx.runCommand(`${ADB_PATH} devices`, {
+        timeout: ADB_TIMEOUT_MS
+      });
       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) {
+      if (isToolTimeout(error)) throw error;
       progress.log("Error checking emulator status: " + error.message, "error");
       return null;
     }
   }
 
+  /**
+   * The task name from a gradle line, or null for lines worth ignoring.
+   * "> Task :app:compileDebugKotlin" becomes "app:compileDebugKotlin".
+   */
+  function gradleTask(line) {
+    const match = /^>\s*Task\s+:(\S+)/.exec(line.trim());
+    return match ? match[1] : null;
+  }
+
+  /**
+   * Run something that writes directly to the terminal, with the progress
+   * tree stood down for the duration.
+   *
+   * The resume must happen on the failure path too -- a build that throws
+   * while paused would otherwise leave the tree silent for the rest of the
+   * run, hiding exactly the output someone needs when a build fails.
+   */
+  async function withStreamedOutput(fn) {
+    progress.pause();
+    try {
+      return await fn();
+    } finally {
+      progress.resume();
+    }
+  }
+
   // 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
@@ -179,9 +226,12 @@ function createBuildPhase(ctx) {
   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`);
+      const devices = ctx.runCommand(`${ADB_PATH} devices`, {
+        timeout: ADB_TIMEOUT_MS
+      });
       return devices.split("\n").map(line => line.trim().split(/\s+/)[0]).filter(id => id && id.startsWith("emulator-"));
-    } catch {
+    } catch (error) {
+      if (isToolTimeout(error)) throw error;
       return [];
     }
   }
@@ -226,7 +276,10 @@ function createBuildPhase(ctx) {
       const remaining = Math.max(deadline - Date.now(), 1000);
       return execFileSync(ADB_PATH, ["-s", serial, "shell", "getprop", prop], {
         encoding: "utf8",
-        timeout: remaining
+        timeout: remaining,
+        // "adb: device offline" is the expected answer while the
+        // emulator boots; inherited, it landed on the spinner's row.
+        stdio: ["ignore", "pipe", "ignore"]
       }).trim();
     };
     while (Date.now() < deadline) {
@@ -252,7 +305,7 @@ function createBuildPhase(ctx) {
     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");
+    progress.status("setting up emulator");
     let serial = await checkEmulator(ADB_PATH);
     let pid = null;
     if (!serial) {
@@ -281,19 +334,35 @@ function createBuildPhase(ctx) {
     };
   }
   async function buildApp(ADB_PATH, androidConfig, buildOptimisation, targetDevice = null) {
-    progress.log("Building and installing app...", "info");
+    progress.status("building and installing app");
     try {
+      // Gradle needs the SDK location in local.properties. Only
+      // setupEmulator:android wrote it, so building without a prior
+      // setup died in gradle despite a configured sdkPath.
+      if (androidConfig.sdkPath) ensureLocalProperties(`${pwd}/androidProject`, androidConfig.sdkPath);
+
+      // --quiet was the Android silence: it suppresses gradle's task and
+      // error output entirely. --console=rich emits ANSI redraws, which
+      // are meaningless on a pipe; plain gives one line per task.
       // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - pwd and configPath are internal resolved paths, not user input.
-      let buildCommand = `cd ${pwd}/androidProject && ./gradlew generateWebViewConfig -PconfigPath=${configPath} -PbuildOptimisation=${buildOptimisation} && ./gradlew clean installDebug -PconfigPath=${configPath} --quiet --console=rich`;
+      let buildCommand = `cd ${pwd}/androidProject && ./gradlew generateWebViewConfig -PconfigPath=${configPath} -PbuildOptimisation=${buildOptimisation} && ./gradlew clean installDebug -PconfigPath=${configPath} --console=plain`;
       if (targetDevice && targetDevice.type === "physical") {
         buildCommand = buildCommand.replace("installDebug", `installDebug -Pandroid.injected.target.device=${targetDevice.id}`);
       }
+
+      // Gradle emits hundreds of lines that nobody reads on success and
+      // that the error path re-derives from error.output anyway. Show the
+      // current task on the spinner's own row instead of scrolling them.
       await ctx.runInteractiveCommand("sh", ["-c", buildCommand], {
         "BUILD SUCCESSFUL": ""
+      }, {
+        onLine: line => progress.status(gradleTask(line))
       });
-      progress.log("App build and installation completed successfully!", "success");
     } catch (error) {
-      throw new Error("Error building/installing app: " + error.message);
+      // Re-wrapping with a new Error dropped `output`, and with it the
+      // compiler errors. Keep the original and let the reporter mine it.
+      error.stage = "Building and installing the app";
+      throw error;
     }
   }
   async function launchApp(ADB_PATH, buildType = "debug", targetDevice = null) {
@@ -303,16 +372,15 @@ function createBuildPhase(ctx) {
     }
     if (targetDevice.type === "physical") {
       progress.log(`App installed on physical device: ${targetDevice.model}`, "success");
-      progress.log("Manual launch required - check your device to open the app", "info");
+      progress.log("Open the app on your device to launch it", "note");
       return;
     }
     try {
-      progress.log("Launching app on emulator...", "info");
+      progress.status("launching app on emulator");
       const packageName = `${ANDROID_PACKAGE}${buildType === "debug" ? ".debug" : ""}`;
       // 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 launchCommand = `${ADB_PATH} shell monkey -p ${packageName} 1`;
       await ctx.runInteractiveCommand("sh", ["-c", launchCommand], {});
-      progress.log("App launched successfully on emulator!", "success");
     } catch (error) {
       progress.log(`Warning: Could not auto-launch app: ${error.message}`, "warning");
       progress.log("App was installed successfully, but auto-launch failed", "info");
@@ -362,12 +430,9 @@ function createBuildPhase(ctx) {
         return null;
       }
       const currentDate = new Date().toLocaleDateString("en-GB").replace(/\//g, "-");
-      const currentTime = new Date().toLocaleTimeString("en-US", {
-        hour12: true,
-        hour: "2-digit",
-        minute: "2-digit",
-        second: "2-digit"
-      }).replace(/:/g, "-");
+      // 24-hour and locale-free: "02-05-09 PM" put a space in every
+      // artifact name, which breaks unquoted shell use of the path.
+      const currentTime = new Date().toTimeString().slice(0, 8).replace(/:/g, "-");
       let destinationApkFileName = "";
       if (appName) {
         destinationApkFileName = buildType === "release" ? `${appName}-${currentTime}.release.apk` : `${appName}-${currentTime}.debug.apk`;
@@ -405,12 +470,16 @@ function createBuildPhase(ctx) {
   async function buildSignedAAB(androidConfig) {
     progress.log("Building signed AAB for release...", "info");
     try {
+      // Same as buildApp: gradle needs local.properties on a fresh machine.
+      if (androidConfig.sdkPath) ensureLocalProperties(`${pwd}/androidProject`, androidConfig.sdkPath);
       progress.log("Generating webview configuration for release...", "info");
       try {
         // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - pwd and configPath are internal resolved paths, not user input.
         const generateConfigCommand = `cd ${pwd}/androidProject && ./gradlew generateWebViewConfig -PconfigPath=${configPath}`;
         await ctx.runInteractiveCommand("sh", ["-c", generateConfigCommand], {
           "BUILD SUCCESSFUL": ""
+        }, {
+          onLine: line => progress.status(gradleTask(line))
         });
         progress.log("Webview config generated successfully", "success");
       } catch (configError) {
@@ -418,10 +487,13 @@ function createBuildPhase(ctx) {
         throw new Error("Webview config generation is required for release builds");
       }
       const aabConfig = await createAABConfig(androidConfig);
-      await buildAndroidAAB(aabConfig);
+      // buildAndroidAAB shells out to `./gradlew bundleRelease` and prints
+      // its own progress lines, so it owns the screen for its duration.
+      await withStreamedOutput(() => buildAndroidAAB(aabConfig));
       progress.log("Signed AAB build completed successfully!", "success");
     } catch (error) {
-      throw new Error("Error building signed AAB: " + error.message);
+      error.stage = "Building the signed AAB";
+      throw error;
     }
   }
   return {

package/dist/native/buildAndroid/config.js

@@ -1,6 +1,21 @@
 "use strict";
 
 const fs = require("fs");
+const os = require("os");
+const {
+  detectAndroidSdk,
+  listAvds,
+  expandHome,
+  ANDROID_SDK_HINT
+} = require("../utils.js");
+
+/** An error carrying the one action that fixes it, shown as the diagnostic's hint. */
+function withHint(message, hint) {
+  return Object.assign(new Error(message), {
+    hint
+  });
+}
+const tilde = dir => dir.startsWith(os.homedir()) ? `~${dir.slice(os.homedir().length)}` : dir;
 function createConfigPhase(ctx) {
   const {
     configPath,
@@ -17,10 +32,9 @@ function createConfigPhase(ctx) {
       throw new Error("WebView Config missing in " + configPath);
     }
     if (!WEBVIEW_CONFIG.android) {
-      throw new Error("Android config missing in WebView Config");
+      throw withHint("Android config missing in WebView Config", "Run catalyst setupEmulator:android to create it, or add WEBVIEW_CONFIG.android to config/config.json.");
     }
     const buildType = WEBVIEW_CONFIG.android.buildType || "debug";
-    progress.log(`Build Type: ${buildType}`, "info");
     if (buildType === "release") {
       progress.log("Release build detected - AAB will be generated", "info");
     }
@@ -30,23 +44,34 @@ function createConfigPhase(ctx) {
     };
   }
   function validateAndroidTools(androidConfig) {
+    progress.status("validating tools");
+
+    // An unset sdkPath is usually just an SDK in the default place. Use it,
+    // and say so, rather than failing on a field most people never set.
+    if (!androidConfig.sdkPath) {
+      const detected = detectAndroidSdk();
+      if (!detected) throw withHint("Android SDK not found", ANDROID_SDK_HINT);
+      androidConfig.sdkPath = detected;
+      progress.log(`Using the Android SDK at ${tilde(detected)}`, "note");
+    }
+    // "~/Library/Android/sdk", as the hint suggests. Expanded in memory
+    // only; the config file keeps what the user wrote.
+    androidConfig.sdkPath = expandHome(androidConfig.sdkPath);
     const ANDROID_SDK = androidConfig.sdkPath;
     const ADB_PATH = `${ANDROID_SDK}/platform-tools/adb`;
     const EMULATOR_PATH = `${ANDROID_SDK}/emulator/emulator`;
-    progress.log("Validating Android tools...", "info");
-    if (!ANDROID_SDK) {
-      throw new Error("Android SDK path is not configured");
-    }
     if (!fs.existsSync(ANDROID_SDK)) {
-      throw new Error(`Android SDK path does not exist: ${ANDROID_SDK}`);
+      throw withHint(`Android SDK path does not exist: ${ANDROID_SDK}`, ANDROID_SDK_HINT);
     }
     if (!fs.existsSync(ADB_PATH)) {
-      throw new Error(`ADB not found at: ${ADB_PATH}`);
+      throw withHint(`adb not found at ${ADB_PATH}`, "Install Android SDK Platform-Tools from Android Studio's SDK Manager.");
     }
     try {
-      ctx.runCommand(`${ADB_PATH} version`);
-      progress.log("ADB validation successful", "success");
+      ctx.runCommand(`${ADB_PATH} version`, {
+        timeout: 15000
+      });
     } catch (error) {
+      if (error.hint) throw error;
       throw new Error(`ADB is not working properly: ${error.message}`);
     }
     const buildType = androidConfig.buildType || "debug";
@@ -56,10 +81,17 @@ function createConfigPhase(ctx) {
       }
       try {
         ctx.runCommand(`${EMULATOR_PATH} -version`);
-        progress.log("Emulator validation successful", "success");
       } catch (error) {
         throw new Error(`Emulator is not working properly: ${error.message}`);
       }
+      if (!androidConfig.emulatorName) {
+        const [first] = listAvds(ANDROID_SDK);
+        if (!first) {
+          throw withHint("No Android emulator found", "Create one in Android Studio's Device Manager, or set WEBVIEW_CONFIG.android.emulatorName.");
+        }
+        androidConfig.emulatorName = first;
+        progress.log(`Using the "${first}" emulator`, "note");
+      }
       try {
         const avdOutput = ctx.runCommand(`${EMULATOR_PATH} -list-avds`);
         if (!avdOutput.includes(androidConfig.emulatorName)) {
@@ -72,7 +104,6 @@ function createConfigPhase(ctx) {
     } else {
       progress.log("Skipping emulator validation for release build", "info");
     }
-    progress.log("Android tools validation completed successfully!", "success");
     return {
       ANDROID_SDK,
       ADB_PATH,