html2apk 0.3.0 → 0.4.0

package/README.md

@@ -252,6 +252,7 @@ Campos principais:
 | `orientation` | `default`, `vertical`, `horizontal`, `portrait` ou `landscape`. |
 | `minSdkVersion` | Versao minima do Android em API level. Padrao: `24`. |
 | `themeColor` | Cor base do tema/splash Android, em hexadecimal. Tambem vira fallback do modo automatico. |
+| `icon` | Icone PNG do app. Se ficar vazio, o html2apk usa automaticamente o icone padrao da ferramenta. |
 | `themeMode` | `fixed` usa a cor fixa. `auto` adapta as barras Android a cor visivel na tela do APK. Tambem aceita `theme: "auto"`. |
 | `oneSignalAppId` | Opcional. App ID publico do OneSignal para push remoto. Nao coloque REST API Key no APK. |
 | `deepLinks` | URLs que podem abrir o APK, como `meuapp://rota` ou `https://meusite.com/produto/1`. |
@@ -355,6 +356,8 @@ Retorno:
 
 A v0.1 instala um plugin Cordova local com uma API global simples para recursos Android. Todas as funcoes retornam `Promise`, exceto os ouvintes `aoEvento`/atalhos, que retornam uma funcao para cancelar a escuta.
 
+O html2apk injeta `cordova.js` automaticamente no HTML inicial do APK. Se uma funcao nativa for chamada antes do `deviceready`, a bridge espera o Android ficar pronto antes de executar.
+
 Cada funcao em portugues tambem tem alias em ingles. A interface grafica mostra a sintaxe PT-BR quando o idioma esta em portugues e mostra a sintaxe em ingles quando o usuario troca o idioma para English.
 
 Exemplos de aliases:
@@ -403,15 +406,15 @@ Como tratar retornos:
 
 - Use `await` dentro de `try/catch` quando a acao depender de Android, permissao ou outro app instalado.
 - Seletores de arquivo podem retornar `null`, array vazio ou objeto vazio quando o usuario cancela.
-- APIs de permissao retornam objetos com `granted`; se vier `false`, desative o recurso ou mostre uma etapa de permissao.
+- Funcoes que precisam de permissao pedem automaticamente quando sao chamadas, como `lanterna()`, `notificar()` e `ouvirMic()`.
+- Se o Android nao puder mostrar o pop-up de permissao, o html2apk abre a tela correta de configuracoes e retorna `settingsOpened: true`.
+- APIs manuais de permissao continuam existindo para quem quer explicar antes; elas retornam objetos com `granted`, `requiresSettings` e `settingsOpened`.
 - Eventos retornam uma funcao de cancelamento; guarde essa funcao e chame quando a tela/componente sair.
 - Medidas de memoria, armazenamento e apps abertos sao diagnosticas. Android moderno pode limitar dados de outros apps por privacidade.
 
 No seu JavaScript do app:
 
 ```js
-await solicitarPermissaoNotificacoes();
-
 toast("Mensagem");
 vibrar(250);
 
@@ -532,19 +535,20 @@ O retorno de arquivos tem este formato:
 Microfone:
 
 ```js
-await solicitarPermissaoMicrofone();
-
-await ouvirMic();
-
-// ... depois, quando quiser parar
-const audio = await pararMic();
-const audioUrl = `data:${audio.mimeType};base64,${audio.base64}`;
-
-const player = new Audio(audioUrl);
-player.play();
+const inicio = await ouvirMic();
+if (inicio.settingsOpened) {
+  console.log("Libere Microfone nas configuracoes e tente novamente");
+} else {
+  // ... depois, quando quiser parar
+  const audio = await pararMic();
+  const audioUrl = `data:${audio.mimeType};base64,${audio.base64}`;
+
+  const player = new Audio(audioUrl);
+  player.play();
+}
 ```
 
-`ouvirMic()` comeca a gravar e tambem pede permissao se ela ainda nao foi concedida. Para uma experiencia mais clara, prefira chamar `solicitarPermissaoMicrofone()` antes e explicar ao usuario por que o app precisa do microfone.
+`ouvirMic()` comeca a gravar e tambem pede permissao se ela ainda nao foi concedida. Se a permissao estiver bloqueada pelo Android, a tela de configuracoes do app e aberta automaticamente e o retorno traz `settingsOpened: true`.
 
 `pararMic()` encerra a gravacao e retorna:
 
@@ -563,7 +567,6 @@ Para tratar o retorno, use `mimeType` e `base64` juntos em um Data URL quando qu
 Lanterna, tela, clipboard e intents:
 
 ```js
-await solicitarPermissaoCamera();
 const lanternaStatus = await lanterna(true);
 await alternarLanterna();
 
@@ -667,9 +670,7 @@ Permissoes e alarmes:
 
 ```js
 const status = await statusPermissaoNotificacoes();
-if (!status.granted) {
-  await solicitarPermissaoNotificacoes();
-}
+console.log(status.granted);
 
 const podeUsarAlarmeExato = await podeAgendarNotificacaoExata();
 if (!podeUsarAlarmeExato) {
@@ -677,7 +678,7 @@ if (!podeUsarAlarmeExato) {
 }
 ```
 
-A bridge cria canal de notificacao, solicita/consulta `POST_NOTIFICATIONS` no Android 13+, abre o app com payload quando a notificacao e clicada, persiste notificacoes agendadas e tenta reagendar apos reboot ou update do app.
+A bridge cria canal de notificacao, solicita `POST_NOTIFICATIONS` automaticamente quando `notificar()`/`agendarNotificacao()` precisam, abre configuracoes se o Android bloquear o pop-up, abre o app com payload quando a notificacao e clicada, persiste notificacoes agendadas e tenta reagendar apos reboot ou update do app. Se voce usar `exato: true`/`exact: true` em uma notificacao agendada e o Android exigir liberacao manual de alarme exato, o html2apk abre essa tela automaticamente.
 
 ## Problemas Comuns
 
@@ -748,11 +749,15 @@ Fluxo da interface:
 1. Arraste ou escolha a pasta do projeto.
 2. O app mostra `verificando ambiente` antes de liberar as proximas etapas.
 3. Se faltarem pacotes do Android SDK, ele pede permissao e tenta baixar/instalar mostrando logs.
-4. Preencha as configuracoes obrigatorias: nome do app, Package ID, versao, modo e icone PNG.
-5. Revise, clique em `Gerar APK` e acompanhe a barra de progresso.
+4. Preencha as configuracoes obrigatorias: nome do app, Package ID, versao e modo. Se voce nao escolher icone, o html2apk usa o icone padrao da ferramenta.
+5. Revise e clique em `Gerar APK` para salvar o APK em `dist`, ou `Testar no USB` para gerar debug, instalar e abrir direto em um celular conectado.
 6. Ao concluir, a tela final mostra o APK gerado e botoes para abrir a pasta `dist` ou localizar o arquivo.
 
-O PNG escolhido e usado como icone do aplicativo e tambem como imagem da tela inicial do Android, evitando o splash padrao do Cordova.
+O PNG escolhido e usado como icone do aplicativo e tambem como imagem da tela inicial do Android, evitando o splash padrao do Cordova. Quando nenhum PNG e escolhido, o `html2apk.png` da propria ferramenta entra como fallback.
+
+Depois que a pasta foi escolhida, a interface acompanha mudancas nela automaticamente. Edicoes em HTML, CSS, JS e assets entram no proximo build sem arrastar a pasta de novo. Se `app.json` ou `config.json` mudar, os campos da tela de configuracoes sao recarregados.
+
+Para `Testar no USB`, o celular precisa estar com `Opcoes do desenvolvedor > Depuracao USB` ativa. Ao conectar, desbloqueie o aparelho e aceite a chave RSA. Se o Android aparecer como `unauthorized` ou `offline`, a interface mostra o que fazer nos logs.
 
 Os logs podem ser abertos em uma barra inferior durante qualquer etapa pelo botao `Mostrar logs`. Se atrapalhar a visualizacao, use `Ocultar logs` e a area principal volta a ocupar a altura da janela.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "html2apk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Node CLI and library to turn an HTML/CSS/JS folder into an Android APK through Cordova.",
   "main": "index.js",
   "bin": {

package/src/cordova/project.js

@@ -47,10 +47,28 @@ async function buildAndroid(buildDir, options, buildJsonPath, runner) {
   });
 }
 
+async function runAndroidDevice(buildDir, options, buildJsonPath, runner, deviceId) {
+  const args = ["run", "android", "--device", "--debug", "--no-telemetry"];
+
+  if (deviceId) {
+    args.push(`--target=${deviceId}`);
+  }
+
+  if (buildJsonPath) {
+    args.push("--buildConfig", buildJsonPath);
+  }
+
+  await runner.run("cordova", args, {
+    cwd: buildDir,
+    pipeOutput: options.debug
+  });
+}
+
 module.exports = {
   DEFAULT_ANDROID_PLATFORM,
   createCordovaProject,
   addCordovaPlugin,
   addAndroidPlatform,
-  buildAndroid
+  buildAndroid,
+  runAndroidDevice
 };

package/src/core/build-apk.js

@@ -5,7 +5,7 @@ const os = require("os");
 const path = require("path");
 const { resolveBuildOptions } = require("./config");
 const { validateEntryFile, validateRequiredOptions } = require("./validation");
-const { createCordovaProject, addAndroidPlatform, buildAndroid, addCordovaPlugin } = require("../cordova/project");
+const { createCordovaProject, addAndroidPlatform, buildAndroid, runAndroidDevice, addCordovaPlugin } = require("../cordova/project");
 const { writeConfigXml } = require("../cordova/config-xml");
 const { findApk } = require("../cordova/apk-finder");
 const { copyWebAssets, ensureDir, removePath, copyFile, copyDirectory } = require("../utils/fs-extra");
@@ -16,6 +16,15 @@ const { getRuntimeEnvironment } = require("../runtime-manager");
 const AUTO_THEME_SCRIPT_NAME = "html2apk-auto-theme.js";
 const ONESIGNAL_SCRIPT_NAME = "html2apk-onesignal.js";
 const ONESIGNAL_PLUGIN_PACKAGE = "onesignal-cordova-plugin";
+const DEFAULT_APP_ICON_NAME = "html2apk.png";
+
+function defaultAppIconPath() {
+  return path.resolve(__dirname, "..", "..", DEFAULT_APP_ICON_NAME);
+}
+
+function withDefaultAppIcon(assetPath) {
+  return String(assetPath || "").trim() || defaultAppIconPath();
+}
 
 function isRemoteAsset(assetPath) {
   return /^https?:\/\//i.test(String(assetPath || ""));
@@ -54,6 +63,37 @@ function scriptTag(scriptPath) {
   return `<script src="${scriptPath}"></script>`;
 }
 
+async function injectCordovaRuntimeIntoHtml(htmlPath, scriptPath = "cordova.js") {
+  let html = await fs.readFile(htmlPath, "utf8");
+  if (/<script\b[^>]*\bsrc=["'][^"']*cordova\.js["'][^>]*>/i.test(html)) {
+    return false;
+  }
+
+  const tag = scriptTag(scriptPath);
+  if (/<head\b[^>]*>/i.test(html)) {
+    html = html.replace(/<head\b[^>]*>/i, (match) => `${match}\n  ${tag}`);
+  } else if (/<html\b[^>]*>/i.test(html)) {
+    html = html.replace(/<html\b[^>]*>/i, (match) => `${match}\n  ${tag}`);
+  } else {
+    html = `${tag}\n${html}`;
+  }
+
+  await fs.writeFile(htmlPath, html, "utf8");
+  return true;
+}
+
+async function installCordovaRuntimeScript(buildDir, options) {
+  const wwwDir = path.join(buildDir, "www");
+  const entryHtmlPath = path.resolve(wwwDir, options.entryFile || "index.html");
+  const scriptPath = toCordovaPath(path.relative(path.dirname(entryHtmlPath), path.join(wwwDir, "cordova.js"))) || "cordova.js";
+
+  if (!isInside(wwwDir, entryHtmlPath)) {
+    throw new Error(`Entry file must stay inside the Cordova www folder: ${options.entryFile}`);
+  }
+
+  return injectCordovaRuntimeIntoHtml(entryHtmlPath, scriptPath);
+}
+
 async function injectScriptIntoHtml(htmlPath, scriptPath) {
   let html = await fs.readFile(htmlPath, "utf8");
   if (html.includes(scriptPath)) {
@@ -238,11 +278,147 @@ function outputApkName(options) {
   return `${safeName}-${options.version}-${flavor}.apk`;
 }
 
+function parseAdbDevices(output) {
+  return String(output || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line
+      && !/^list of devices/i.test(line)
+      && !/^\*/.test(line)
+      && !/^adb server/i.test(line))
+    .map((line) => {
+      const parts = line.split(/\s+/);
+      return {
+        id: parts[0],
+        status: parts[1] || "unknown"
+      };
+    })
+    .filter((device) => device.id);
+}
+
+function deviceTargetId(device) {
+  return device && device.id ? String(device.id) : "";
+}
+
+async function ensureUsbDebugDevice(runner) {
+  let result;
+  try {
+    result = await runner.run("adb", ["devices"]);
+  } catch (error) {
+    throw new Error("ADB nao foi encontrado. Instale Android platform-tools pelo ambiente do html2apk e tente novamente.");
+  }
+
+  const devices = parseAdbDevices(result.stdout);
+  const physicalDevices = devices.filter((device) => !/^emulator-/i.test(device.id));
+  const ready = physicalDevices.find((device) => device.status === "device");
+  if (ready) {
+    return ready;
+  }
+
+  if (physicalDevices.some((device) => device.status === "unauthorized")) {
+    throw new Error("Celular encontrado, mas a depuracao USB ainda nao foi autorizada. Desbloqueie o celular e aceite a chave RSA de depuracao USB.");
+  }
+
+  if (physicalDevices.some((device) => device.status === "offline")) {
+    throw new Error("Celular USB encontrado, mas esta offline. Reconecte o cabo USB, desbloqueie o celular e confirme a depuracao USB.");
+  }
+
+  throw new Error("Nenhum celular USB autorizado foi encontrado. Ative Opcoes do desenvolvedor > Depuracao USB, conecte o celular e aceite a permissao RSA.");
+}
+
+async function prepareCordovaProject(projectRoot, buildDir, options, runner, log) {
+  await createCordovaProject(buildDir, options, runner);
+  const cordovaOptions = { ...options };
+  const effectiveIcon = withDefaultAppIcon(options.icon);
+  const effectiveSplash = options.splash || effectiveIcon;
+  if (!String(options.icon || "").trim()) {
+    log("Icon: using the default html2apk icon.");
+  }
+  cordovaOptions.icon = await copyCordovaAsset(projectRoot, buildDir, effectiveIcon, "icon");
+  cordovaOptions.splash = await copyCordovaAsset(projectRoot, buildDir, effectiveSplash, "splash");
+  cordovaOptions.androidSplashScreenAnimatedIcon = toBuildAssetPath(buildDir, cordovaOptions.splash);
+  await writeConfigXml(path.join(buildDir, "config.xml"), cordovaOptions);
+  await copyWebAssets(path.resolve(projectRoot, options.webRoot || "."), path.join(buildDir, "www"), options, projectRoot);
+  if (await installCordovaRuntimeScript(buildDir, options)) {
+    log("Cordova runtime: injected cordova.js into the entry HTML.");
+  }
+  if (await installAutoThemeScript(buildDir, options)) {
+    log("Theme mode: auto (system bars follow the visible screen color).");
+  }
+  if (await installOneSignalScript(buildDir, options)) {
+    log("OneSignal: enabled for remote push notifications.");
+  }
+
+  const bridgePluginPath = await installBridgePlugin(buildDir);
+  await addCordovaPlugin(buildDir, bridgePluginPath, runner);
+
+  if (hasOneSignal(options) && !hasPlugin(options.plugins, ONESIGNAL_PLUGIN_PACKAGE)) {
+    await addCordovaPlugin(buildDir, await prepareBundledPlugin(buildDir, ONESIGNAL_PLUGIN_PACKAGE), runner);
+  }
+
+  for (const plugin of options.plugins) {
+    await addCordovaPlugin(buildDir, plugin, runner);
+  }
+
+  await addAndroidPlatform(buildDir, options, runner);
+}
+
+async function copyBuiltApk(projectRoot, buildDir, options) {
+  const apkPathInBuild = await findApk(buildDir, options);
+  const outputDir = path.resolve(projectRoot, options.outputDir || "dist");
+  await ensureDir(outputDir);
+
+  const apkPath = path.join(outputDir, outputApkName(options));
+  await copyFile(apkPathInBuild, apkPath);
+  return apkPath;
+}
+
+async function ensureBuiltDebugApk(buildDir, options, runner, log) {
+  try {
+    return await findApk(buildDir, options);
+  } catch {
+    log("USB debug: building debug APK for direct ADB install.");
+    await buildAndroid(buildDir, options, null, runner);
+    return findApk(buildDir, options);
+  }
+}
+
+async function installDebugApkWithAdb(buildDir, options, runner, device, log) {
+  const deviceId = deviceTargetId(device);
+  const apkPath = await ensureBuiltDebugApk(buildDir, options, runner, log);
+  log(`USB debug fallback: installing APK with ADB on ${deviceId}.`);
+
+  try {
+    await runner.run("adb", ["-s", deviceId, "install", "-r", "-d", apkPath]);
+  } catch (error) {
+    const output = `${error.stdout || ""}\n${error.stderr || ""}\n${error.message || ""}`;
+    if (/INSTALL_FAILED_UPDATE_INCOMPATIBLE/i.test(output)) {
+      throw new Error("O app ja esta instalado nesse celular com outra assinatura. Desinstale a versao antiga no Android e clique em Testar no USB novamente.");
+    }
+    throw error;
+  }
+
+  log(`USB debug fallback: opening ${options.packageId}.`);
+  await runner.run("adb", [
+    "-s",
+    deviceId,
+    "shell",
+    "monkey",
+    "-p",
+    options.packageId,
+    "-c",
+    "android.intent.category.LAUNCHER",
+    "1"
+  ]);
+
+  return apkPath;
+}
+
 async function buildApk(overrides = {}) {
   const onLog = typeof overrides.onLog === "function" ? overrides.onLog : null;
   const { projectRoot, configPath, options } = await resolveBuildOptions(overrides);
   validateRequiredOptions(options);
-  const { webRoot } = await validateEntryFile(projectRoot, options);
+  await validateEntryFile(projectRoot, options);
 
   const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "html2apk-"));
   const buildDir = path.join(tempRoot, "cordova-project");
@@ -268,41 +444,86 @@ async function buildApk(overrides = {}) {
       log(`JAVA_HOME: ${runtime.javaHome}`);
     }
 
-    await createCordovaProject(buildDir, options, runner);
-    const cordovaOptions = { ...options };
-    cordovaOptions.icon = await copyCordovaAsset(projectRoot, buildDir, options.icon, "icon");
-    cordovaOptions.splash = await copyCordovaAsset(projectRoot, buildDir, options.splash || options.icon, "splash");
-    cordovaOptions.androidSplashScreenAnimatedIcon = toBuildAssetPath(buildDir, cordovaOptions.splash);
-    await writeConfigXml(path.join(buildDir, "config.xml"), cordovaOptions);
-    await copyWebAssets(webRoot, path.join(buildDir, "www"), options, projectRoot);
-    if (await installAutoThemeScript(buildDir, options)) {
-      log("Theme mode: auto (system bars follow the visible screen color).");
-    }
-    if (await installOneSignalScript(buildDir, options)) {
-      log("OneSignal: enabled for remote push notifications.");
-    }
+    await prepareCordovaProject(projectRoot, buildDir, options, runner, log);
+    const buildJsonPath = await createBuildJson(buildDir, options, projectRoot);
+    await buildAndroid(buildDir, options, buildJsonPath, runner);
 
-    const bridgePluginPath = await installBridgePlugin(buildDir);
-    await addCordovaPlugin(buildDir, bridgePluginPath, runner);
+    const apkPath = await copyBuiltApk(projectRoot, buildDir, options);
 
-    if (hasOneSignal(options) && !hasPlugin(options.plugins, ONESIGNAL_PLUGIN_PACKAGE)) {
-      await addCordovaPlugin(buildDir, await prepareBundledPlugin(buildDir, ONESIGNAL_PLUGIN_PACKAGE), runner);
+    if (!options.debug) {
+      await removePath(tempRoot);
+      tempCleaned = true;
     }
 
-    for (const plugin of options.plugins) {
-      await addCordovaPlugin(buildDir, plugin, runner);
+    return {
+      apkPath,
+      buildDir: options.debug ? buildDir : null,
+      logs,
+      status: "success",
+      tempCleaned
+    };
+  } catch (error) {
+    log(`Error: ${error.message}`);
+    if (!options.debug) {
+      await removePath(tempRoot).catch(() => {});
+      tempCleaned = true;
+    } else {
+      log(`Debug mode enabled. Temporary build kept at: ${buildDir}`);
     }
 
-    await addAndroidPlatform(buildDir, options, runner);
-    const buildJsonPath = await createBuildJson(buildDir, options, projectRoot);
-    await buildAndroid(buildDir, options, buildJsonPath, runner);
+    error.logs = logs;
+    error.buildDir = options.debug ? buildDir : null;
+    error.tempCleaned = tempCleaned;
+    error.status = "error";
+    throw error;
+  }
+}
+
+async function runDebugUsb(overrides = {}) {
+  const onLog = typeof overrides.onLog === "function" ? overrides.onLog : null;
+  const resolved = await resolveBuildOptions(overrides);
+  const projectRoot = resolved.projectRoot;
+  const configPath = resolved.configPath;
+  const options = {
+    ...resolved.options,
+    release: false
+  };
+  validateRequiredOptions(options);
+  await validateEntryFile(projectRoot, options);
+
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "html2apk-"));
+  const buildDir = path.join(tempRoot, "cordova-project");
+  const logs = [];
+  const runtime = getRuntimeEnvironment();
+  const runner = createCommandRunner({ logs, env: runtime.env, onLog });
+  let tempCleaned = false;
 
-    const apkPathInBuild = await findApk(buildDir, options);
-    const outputDir = path.resolve(projectRoot, options.outputDir || "dist");
-    await ensureDir(outputDir);
+  function log(line) {
+    logs.push(line);
+    if (onLog) {
+      onLog(line);
+    }
+  }
+
+  try {
+    log(`Project root: ${projectRoot}`);
+    log(configPath ? `Config: ${configPath}` : "Config: defaults only");
+    log("USB debug: checking connected Android device.");
+    const device = await ensureUsbDebugDevice(runner);
+    log(`USB debug device: ${device.id}`);
+
+    await prepareCordovaProject(projectRoot, buildDir, options, runner, log);
+    try {
+      await runAndroidDevice(buildDir, options, null, runner, deviceTargetId(device));
+    } catch (error) {
+      log("USB debug: Cordova run failed. Trying direct ADB install fallback.");
+      if (error.stdout || error.stderr) {
+        log([error.stdout, error.stderr].filter(Boolean).join("\n").trim().slice(-4000));
+      }
+      await installDebugApkWithAdb(buildDir, options, runner, device, log);
+    }
 
-    const apkPath = path.join(outputDir, outputApkName(options));
-    await copyFile(apkPathInBuild, apkPath);
+    const apkPath = await copyBuiltApk(projectRoot, buildDir, options);
 
     if (!options.debug) {
       await removePath(tempRoot);
@@ -312,8 +533,10 @@ async function buildApk(overrides = {}) {
     return {
       apkPath,
       buildDir: options.debug ? buildDir : null,
+      device,
       logs,
       status: "success",
+      usbDebug: true,
       tempCleaned
     };
   } catch (error) {
@@ -334,5 +557,9 @@ async function buildApk(overrides = {}) {
 }
 
 module.exports = {
-  buildApk
+  buildApk,
+  defaultAppIconPath,
+  injectCordovaRuntimeIntoHtml,
+  parseAdbDevices,
+  runDebugUsb
 };

package/src/desktop/main.js

@@ -1,10 +1,11 @@
 "use strict";
 
+const nodeFs = require("fs");
 const fs = require("fs/promises");
 const path = require("path");
 const { spawn } = require("child_process");
 const { app, BrowserWindow, dialog, ipcMain, screen, shell } = require("electron");
-const { buildApk } = require("../core/build-apk");
+const { buildApk, runDebugUsb } = require("../core/build-apk");
 const {
   REQUIRED_ANDROID_BUILD_TOOLS,
   REQUIRED_ANDROID_PLATFORM,
@@ -13,6 +14,9 @@ const {
 const { runDoctor, formatDoctorReport } = require("../runtime-manager/doctor");
 
 let mainWindow = null;
+let projectWatcher = null;
+let projectWatchTimer = null;
+let watchedProjectRoot = null;
 const smokeTest = process.env.HTML2APK_DESKTOP_SMOKE === "1";
 const APP_ID = "dev.caiomultiversando.html2apk";
 const APP_NAME = "html2apk";
@@ -135,6 +139,90 @@ async function inspectProject(projectRoot) {
   };
 }
 
+function shouldIgnoreProjectWatchPath(fileName) {
+  const normalized = String(fileName || "").replace(/\\/g, "/");
+  return normalized
+    && (normalized.includes(".html2apk-doctor-")
+    || normalized.startsWith("dist/")
+    || normalized === "dist"
+    || normalized.startsWith("node_modules/")
+    || normalized === "node_modules"
+    || normalized.startsWith(".git/")
+    || normalized === ".git");
+}
+
+function stopProjectWatcher() {
+  if (projectWatchTimer) {
+    clearTimeout(projectWatchTimer);
+    projectWatchTimer = null;
+  }
+
+  if (projectWatcher) {
+    projectWatcher.close();
+    projectWatcher = null;
+  }
+
+  watchedProjectRoot = null;
+}
+
+function startProjectWatcher(projectRoot, sender) {
+  stopProjectWatcher();
+  watchedProjectRoot = projectRoot;
+
+  try {
+    projectWatcher = nodeFs.watch(projectRoot, { recursive: true }, (eventType, fileName) => {
+      if (shouldIgnoreProjectWatchPath(fileName)) {
+        return;
+      }
+
+      const changedPath = path.join(projectRoot, String(fileName || ""));
+      if (projectWatchTimer) {
+        clearTimeout(projectWatchTimer);
+      }
+
+      projectWatchTimer = setTimeout(async () => {
+        projectWatchTimer = null;
+        try {
+          if (watchedProjectRoot !== projectRoot) {
+            return;
+          }
+
+          const project = await inspectProject(projectRoot);
+          sender.send("project:changed", {
+            eventType,
+            changedPath,
+            project,
+            time: new Date().toISOString()
+          });
+        } catch (error) {
+          sender.send("project:watch-error", {
+            message: error.message,
+            time: new Date().toISOString()
+          });
+        }
+      }, 350);
+    });
+
+    projectWatcher.on("error", (error) => {
+      sender.send("project:watch-error", {
+        message: error.message,
+        time: new Date().toISOString()
+      });
+    });
+
+    return {
+      ok: true,
+      projectRoot
+    };
+  } catch (error) {
+    stopProjectWatcher();
+    return {
+      ok: false,
+      message: error.message
+    };
+  }
+}
+
 function cleanBuildOptions(options = {}) {
   const output = {
     projectRoot: options.projectRoot,
@@ -365,6 +453,7 @@ app.whenReady().then(() => {
 });
 
 app.on("window-all-closed", () => {
+  stopProjectWatcher();
   if (process.platform !== "darwin") {
     app.quit();
   }
@@ -440,6 +529,15 @@ ipcMain.handle("project:inspect", async (_event, projectRoot) => {
   return inspectProject(projectRoot);
 });
 
+ipcMain.handle("project:watch", async (event, projectRoot) => {
+  return startProjectWatcher(projectRoot, event.sender);
+});
+
+ipcMain.handle("project:unwatch", async () => {
+  stopProjectWatcher();
+  return { ok: true };
+});
+
 ipcMain.handle("doctor:run", async (_event, projectRoot) => {
   const report = await runDoctor({ projectRoot });
   return {
@@ -517,6 +615,39 @@ ipcMain.handle("build:run", async (event, options) => {
   }
 });
 
+ipcMain.handle("build:run-usb-debug", async (event, options) => {
+  const buildOptions = cleanBuildOptions(options);
+  const sendLog = (line, kind = "raw") => {
+    event.sender.send("build:log", {
+      line,
+      kind,
+      time: new Date().toISOString()
+    });
+  };
+
+  try {
+    sendLog("Starting html2apk USB debug build.", "system");
+    const result = await runDebugUsb({
+      ...buildOptions,
+      release: false,
+      onLog: (line) => sendLog(line)
+    });
+    sendLog(`USB debug installed on device: ${result.device?.id || "Android device"}`, "success");
+    return {
+      ok: true,
+      result
+    };
+  } catch (error) {
+    sendLog(error.message, "error");
+    return {
+      ok: false,
+      message: error.message,
+      logs: error.logs || [],
+      buildDir: error.buildDir || null
+    };
+  }
+});
+
 ipcMain.handle("shell:open-path", async (_event, targetPath) => {
   if (!targetPath) {
     return false;