html2apk 0.3.0 → 0.5.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 `html2apk-early-bridge.js` e `cordova.js` automaticamente no HTML inicial do APK. A bridge inicial cria as funcoes interpretadas antes dos scripts do seu projeto; se uma funcao nativa for chamada antes do `deviceready`, ela 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,30 +406,41 @@ 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);
 
+await notificar({
+  titulo: "Pedido aprovado",
+  texto: "Toque para abrir o app"
+});
+
 notificar({
   titulo: "Pedido aprovado",
   texto: "Toque para abrir os detalhes",
   acoes: [
-    { id: "abrir", titulo: "Abrir" },
-    { id: "cancelar", titulo: "Cancelar" }
+    {
+      id: "abrir",
+      titulo: "Abrir",
+      open: true,
+      aoClicar: { funcao: "abrirNoApp", argumentos: ["#/pedido/123"] }
+    },
+    {
+      id: "site",
+      titulo: "Ver site",
+      open: false,
+      aoClicar: { funcao: "abrirForaDoApp", argumentos: ["https://exemplo.com/pedido/123"], open: false }
+    }
   ],
-  aoClicar: {
-    acao: "abrir-rota",
-    rota: "/pedido/123",
-    dados: { id: 123 }
-  }
+  aoClicar: () => abrirForaDoApp("https://exemplo.com/pedido/123")
 });
 
 agendarNotificacao({
@@ -434,8 +448,8 @@ agendarNotificacao({
   texto: "Hora de abrir o app",
   quando: Date.now() + 60000,
   aoClicar: {
-    acao: "abrir-rota",
-    rota: "/lembretes"
+    funcao: "abrirNoApp",
+    argumentos: ["#/lembretes"]
   }
 });
 
@@ -463,8 +477,75 @@ const loop = await agendarLoopNotificacoes({
 fullscreen(true);
 ```
 
+`notificar()` nao obriga clique, botao nem funcao. So `titulo` e `texto` ja geram uma notificacao normal. `aoClicar`, `acoes`/`actions` e `open` sao opcionais.
+
 `agendarNotificacao()` agenda uma notificacao. Se voce passar um array para ela, ou usar `agendarNotificacoes()`, o html2apk agenda varias em sequencia. Cada item recebe `id` automatico se voce nao informar um.
 
+Em `aoClicar`, voce pode passar uma funcao diretamente:
+
+```js
+await notificar({
+  titulo: "Pedido aprovado",
+  texto: "Toque para abrir os detalhes",
+  aoClicar: () => abrirForaDoApp("https://exemplo.com/pedido/123")
+});
+```
+
+Nao use `aoClicar: { acao: abrirForaDoApp("https://...") }`, porque os parenteses executam a funcao na hora em que a notificacao e criada. Para notificacao agendada, loop ou app fechado, prefira o formato serializavel:
+
+```js
+await agendarNotificacao({
+  titulo: "Pedido aprovado",
+  texto: "Toque para abrir os detalhes",
+  quando: Date.now() + 60000,
+  aoClicar: {
+    funcao: "abrirForaDoApp",
+    argumentos: ["https://exemplo.com/pedido/123"]
+  }
+});
+```
+
+Esse formato tambem aceita funcoes suas, desde que elas existam em `window` quando o app abrir:
+
+```js
+window.abrirPedido = (id) => abrirNoApp("#/pedido/" + id);
+
+await notificar({
+  titulo: "Pedido aprovado",
+  texto: "Toque para abrir os detalhes",
+  aoClicar: { funcao: "abrirPedido", argumentos: [123] }
+});
+```
+
+Para botoes na notificacao, use `acoes` ou `actions`. Cada botao tambem aceita `aoClicar`/`onClick`:
+
+```js
+window.marcarPedidoLido = (id) => {
+  localStorage.setItem("pedido:" + id, "lido");
+};
+
+await notificar({
+  titulo: "Pedido aprovado",
+  texto: "Escolha uma acao",
+  acoes: [
+    {
+      id: "abrir",
+      titulo: "Abrir",
+      open: true,
+      aoClicar: { funcao: "abrirNoApp", argumentos: ["#/pedido/123"] }
+    },
+    {
+      id: "lido",
+      titulo: "Marcar lido",
+      open: false,
+      aoClicar: { funcao: "marcarPedidoLido", argumentos: [123], open: false }
+    }
+  ]
+});
+```
+
+`open: false` evita trazer a tela do app para frente. Se o app ainda estiver vivo em segundo plano, o html2apk dispara o evento e executa a funcao JavaScript. Se o Android tiver matado o app, JavaScript de WebView nao consegue rodar sem abrir o app; nesse caso, acoes externas como `{ funcao: "abrirForaDoApp", argumentos: ["https://..."], open: false }` ainda funcionam por fallback nativo.
+
 `agendarLoopNotificacoes()` cria um loop recorrente que funciona com o app fechado. Use `aCada`, `intervalo`, `every` ou `interval` em milissegundos ou como texto (`"30min"`, `"12h"`, `"1d"`). A cada disparo, o Android mostra a proxima notificacao da lista. Para parar:
 
 ```js
@@ -532,19 +613,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 +645,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 +748,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 +756,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 +827,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.5.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");
@@ -14,8 +14,18 @@ const { installBridgePlugin } = require("../bridge/install-bridge");
 const { getRuntimeEnvironment } = require("../runtime-manager");
 
 const AUTO_THEME_SCRIPT_NAME = "html2apk-auto-theme.js";
+const EARLY_BRIDGE_SCRIPT_NAME = "html2apk-early-bridge.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 +64,47 @@ function scriptTag(scriptPath) {
   return `<script src="${scriptPath}"></script>`;
 }
 
+async function injectCordovaRuntimeIntoHtml(htmlPath, scriptPath = "cordova.js", earlyBridgePath = EARLY_BRIDGE_SCRIPT_NAME) {
+  let html = await fs.readFile(htmlPath, "utf8");
+  const hasCordova = /<script\b[^>]*\bsrc=["'][^"']*cordova\.js["'][^>]*>/i.test(html);
+  const hasEarlyBridge = /<script\b[^>]*\bsrc=["'][^"']*html2apk-early-bridge\.js["'][^>]*>/i.test(html);
+  if (hasCordova && hasEarlyBridge) {
+    return false;
+  }
+
+  const tags = [
+    hasEarlyBridge ? null : scriptTag(earlyBridgePath),
+    hasCordova ? null : scriptTag(scriptPath)
+  ].filter(Boolean).join("\n  ");
+
+  if (/<head\b[^>]*>/i.test(html)) {
+    html = html.replace(/<head\b[^>]*>/i, (match) => `${match}\n  ${tags}`);
+  } else if (/<html\b[^>]*>/i.test(html)) {
+    html = html.replace(/<html\b[^>]*>/i, (match) => `${match}\n  ${tags}`);
+  } else {
+    html = `${tags}\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";
+  const earlyBridgeSource = path.resolve(__dirname, "..", "templates", EARLY_BRIDGE_SCRIPT_NAME);
+  const earlyBridgeTarget = path.join(wwwDir, EARLY_BRIDGE_SCRIPT_NAME);
+  const earlyBridgePath = toCordovaPath(path.relative(path.dirname(entryHtmlPath), earlyBridgeTarget)) || EARLY_BRIDGE_SCRIPT_NAME;
+
+  if (!isInside(wwwDir, entryHtmlPath)) {
+    throw new Error(`Entry file must stay inside the Cordova www folder: ${options.entryFile}`);
+  }
+
+  await copyFile(earlyBridgeSource, earlyBridgeTarget);
+  return injectCordovaRuntimeIntoHtml(entryHtmlPath, scriptPath, earlyBridgePath);
+}
+
 async function injectScriptIntoHtml(htmlPath, scriptPath) {
   let html = await fs.readFile(htmlPath, "utf8");
   if (html.includes(scriptPath)) {
@@ -238,11 +289,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 +455,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 +544,10 @@ async function buildApk(overrides = {}) {
     return {
       apkPath,
       buildDir: options.debug ? buildDir : null,
+      device,
       logs,
       status: "success",
+      usbDebug: true,
       tempCleaned
     };
   } catch (error) {
@@ -334,5 +568,9 @@ async function buildApk(overrides = {}) {
 }
 
 module.exports = {
-  buildApk
+  buildApk,
+  defaultAppIconPath,
+  injectCordovaRuntimeIntoHtml,
+  parseAdbDevices,
+  runDebugUsb
 };