html2apk 0.9.0 → 0.11.0

package/README.md

@@ -4,6 +4,50 @@
 
 Use ele quando voce ja tem um app web, por exemplo uma pasta com `index.html`, `style.css`, `app.js` e imagens, e quer gerar um `.apk` instalavel no Android ou um `.aab` para loja.
 
+## Como contribuir sem quebrar o padrão
+
+O html2apk agora é um projeto aberto, mas a regra mais importante para novas features é simples: antes de implementar, entenda como o código atual trabalha. Evite criar uma segunda arquitetura para resolver algo que a ponte existente já resolve.
+
+Antes de mandar qualquer feature nova, o contribuinte precisa estudar o fluxo atual da aplicação e confirmar que a solução segue a mesma estratégia das funções existentes. Não envie código que cria atalhos, caminhos paralelos, outro padrão de bridge, outro jeito de tratar permissão ou outra forma de comunicar JavaScript com Java sem uma justificativa técnica muito clara. Primeiro adapte a ideia ao desenho que já funciona no projeto; só proponha uma abordagem nova se o padrão atual realmente não atender.
+
+Exemplo de postura esperada: "quero colocar uma nova função no projeto; antes de escrever, vou ver como as outras funções foram colocadas, como o código lida com elas, qual é o fluxo completo e por que esse fluxo existe". Essa investigação vem antes da implementação. Ela mostra onde a nova função deve nascer, como deve normalizar argumentos, qual action deve chamar, como o Java deve responder, onde documentar e como testar. É esse cuidado que permite criar algo novo sem quebrar a aplicação.
+
+As funções interpretadas seguem um caminho bem definido:
+
+```text
+JavaScript do app
+  -> função global em português
+  -> aliases quando fizer sentido
+  -> normalização de argumentos
+  -> cordova.exec(action)
+  -> dispatcher Java
+  -> permissão/thread/subsistema Android
+  -> CallbackContext
+  -> Promise no JavaScript
+```
+
+Quando uma feature nova entra, ela deve atravessar esse caminho em vez de criar uma forma paralela de comunicação. Isso evita duplicação, bugs difíceis de testar e diferença de comportamento entre o early bridge, o plugin Cordova, a interface desktop e o app final.
+
+Checklist antes de abrir PR ou commit:
+
+- Entenda a arquitetura existente antes de alterar arquivos. Se ainda não sabe por onde uma função interpretada nasce, passa pela bridge e chega ao Java, pare e leia o código antes de implementar.
+- Confirme que a feature nova não está criando conflito com APIs, helpers, normalizadores, actions ou eventos que já existem.
+- Evite estratégias novas desnecessárias. Se uma função parecida já usa `cordova.exec`, dispatcher Java, `CallbackContext`, permissão pendente ou evento `CustomEvent`, a nova feature deve seguir esse caminho.
+- Leia funções parecidas antes de escrever código novo. Se for arquivo, veja `salvarArquivo`, `baixarArquivo` e `FileProvider`. Se for permissão, veja câmera, microfone, notificação e localização. Se for evento, veja `aoEvento`, notificação e compartilhamento recebido.
+- Mantenha nomes em PT-BR como API principal e aliases em inglês apenas quando combinarem com o padrão existente.
+- Adicione a função no early bridge e no plugin JS com a mesma assinatura pública.
+- Reuse normalizadores e helpers existentes; não trate payload com string solta se o projeto já usa objeto estruturado.
+- No Java, entre pelo dispatcher de `action` existente e retorne JSON consistente.
+- Se precisar de permissão runtime, preserve callback pendente, busy state e abertura de configurações quando o Android exigir.
+- Se tocar arquivos, preserve sanitização de nome, armazenamento interno, MediaStore quando aplicável e FileProvider.
+- Se tocar operações longas, use a thread adequada e não trave a WebView.
+- Atualize `plugin.xml` apenas com permissões, intent filters ou dependências realmente necessárias.
+- Atualize runtime console, aba "Códigos interpretados", laboratório USB, README/SOBRE quando a feature for pública.
+- Adicione ou ajuste testes em `test/config.test.js` para provar que JS, Java, UI e docs continuam alinhados.
+- Rode `npm test` antes de enviar.
+
+O objetivo não é impedir criatividade; é proteger o comportamento previsível da ferramenta. Uma contribuição boa parece nativa no projeto: usa os mesmos nomes, passa pelos mesmos pontos, retorna no mesmo formato e respeita as mesmas fronteiras entre build, desktop, bridge JS e Java Android.
+
 ## O Mais Importante
 
 Na pratica, voce vai usar estes comandos:
@@ -303,6 +347,13 @@ O icone flutuante usa a permissao especial `SYSTEM_ALERT_WINDOW`. A bridge nativ
 
 Mesmo com a permissao declarada no manifesto, o usuario ainda precisa liberar manualmente nas configuracoes do Android. Depois de liberar, volte ao app e chame `iniciarIconeFlutuante()` novamente.
 
+O icone tambem aceita opacidade:
+
+```js
+await iniciarIconeFlutuante({ opacidade: 0.85 });
+await definirOpacidadeIconeFlutuante(0.55);
+```
+
 ### Tema Automatico Do APK
 
 Use `themeMode: "auto"` ou `theme: "auto"` para o APK adaptar as barras nativas do Android a cor que esta visivel na tela. O html2apk observa a tela do WebView e ajusta status bar/navigation bar em tempo real.
@@ -386,7 +437,7 @@ Retorno:
 
 ## Bridge Nativa
 
-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.
+A v0.1 instala um plugin Cordova local com uma API global simples para recursos Android. Todas as funções retornam `Promise`, exceto os ouvintes `aoEvento`/atalhos, que retornam uma função 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.
 
@@ -417,6 +468,8 @@ Exemplos de aliases:
 | `escanearQRCode()` | `scanQRCode()` |
 | `escolherArquivo()` | `pickFile()` |
 | `escolherImagem()` | `pickImage()` |
+| `escolherImagens()` | `pickImages()` |
+| `escolherPasta()` | `pickFolder()` |
 | `salvarArquivo()` | `saveFile()` |
 | `lerArquivo()` | `readFile()` |
 | `listarArquivos()` | `listFiles()` |
@@ -429,7 +482,28 @@ Exemplos de aliases:
 | `definirPapelParede()` | `setWallpaper()` |
 | `infoPapelParede()` | `wallpaperInfo()` |
 | `abrirConfiguracaoPapelParede()` | `openWallpaperSettings()` |
+| `capturarTela()` / `tirarPrint()` | `captureScreen()` / `takeScreenshot()` |
 | `compartilhar()` | `share()` |
+| `compartilharApp()` / `share_me()` | `shareApp()` |
+| `aoReceberCompartilhamento()` | `onShareReceived()` |
+| `obterCompartilhamentoInicial()` | `getInitialShare()` |
+| `procurarBT()` | `scanBluetooth()` |
+| `conectarBT()` | `connectBluetooth()` |
+| `enviarBT()` | `sendBluetooth()` |
+| `aoConectarBT()` | `onBluetoothConnect()` |
+| `aoReceberDadosBT()` | `onBluetoothData()` |
+| `aoDarErroBT()` | `onBluetoothError()` |
+| `procurarWiFi()` | `scanWiFi()` |
+| `conectarWiFi()` | `connectWiFi()` |
+| `enviarWiFi()` | `sendWiFi()` |
+| `aoConectarWiFi()` | `onWiFiConnect()` |
+| `aoReceberDadosWiFi()` | `onWiFiData()` |
+| `aoDarErroWiFi()` | `onWiFiError()` |
+| `ocr()` | `recognizeText()` / `textFromImage()` |
+| `falar()` | `speak()` / `textToSpeech()` |
+| `pararFala()` | `stopSpeaking()` |
+| `ouvir()` | `recognizeSpeech()` / `speechToText()` |
+| `aguardar()` | `loading()` |
 | `copiarTexto()` | `copyText()` |
 | `lerTextoCopiado()` | `readText()` |
 | `abrirNoApp()` | `openInApp()` |
@@ -438,10 +512,18 @@ Exemplos de aliases:
 | `manterTelaLigada()` | `keepScreenOn()` |
 | `brilhoTela()` | `setScreenBrightness()` |
 | `definirCorTema()` | `setThemeColor()` |
+| `volumeAtual()` | `getVolume()` |
+| `definirVolume()` | `setVolume()` |
+| `aumentarVolume()` | `increaseVolume()` |
+| `diminuirVolume()` | `decreaseVolume()` |
 | `infoMemoria()` | `memoryInfo()` |
 | `infoArmazenamento()` | `storageInfo()` |
 | `infoDesempenho()` | `performanceInfo()` |
 | `appsAbertos()` | `openAppsMemory()` |
+| `configurarIconeFlutuante()` | `configureFloatingIcon()` |
+| `definirOpacidadeIconeFlutuante()` | `setFloatingIconOpacity()` |
+| `minimizarApp()` | `minimizeApp()` |
+| `fecharApp()` | `closeApp()` / `exitApp()` |
 | `obterLocalizacao()` | `getLocation()` |
 | `acompanharLocalizacao()` | `watchLocation()` |
 | `pararLocalizacao()` | `stopLocationWatch()` |
@@ -451,9 +533,23 @@ Exemplos de aliases:
 | `removerSeguro()` | `deleteSecure()` |
 | `aoEvento()` | `onEvent()` |
 | `aoMinimizar()` | `onMinimize()` |
+| `aoConectarUSB()` | `onUSBConnect()` |
+| `aoDesconectarUSB()` | `onUSBDisconnect()` |
+| `aoConectarFone()` | `onHeadphoneConnect()` |
+| `aoDesconectarFone()` | `onHeadphoneDisconnect()` |
+| `aoMudarVolume()` | `onVolumeChange()` |
+| `aoAbrirTeclado()` | `onKeyboardOpen()` |
+| `aoFecharTeclado()` | `onKeyboardClose()` |
+| `aoSacudirCelular()` | `onPhoneShake()` |
+| `aoVirarCelularParaBaixo()` | `onPhoneFaceDown()` |
+| `aoAproximarObjeto()` | `onProximityNear()` |
+| `aoTirarPrint()` | `onScreenshot()` |
+| `aoMudarOrientacao()` | `onOrientationChange()` |
+| `aoNFC()` | `onNFC()` |
+| `aoReceberNotificacao()` | `onNotificationReceived()` |
 | `obterLinkInicial()` | `getInitialLink()` |
 
-Os eventos tambem aceitam aliases em ingles em `onEvent()`: `app:ready`, `app:background`, `app:resumed`, `back:button`, `link:opened`, `network:changed`, `battery:changed`, `location:changed`, `notification:received` e `notification:clicked`.
+Os eventos tambem aceitam aliases em ingles em `onEvent()`: `app:ready`, `app:background`, `app:resumed`, `back:button`, `link:opened`, `share:received`, `sharing:received`, `bluetooth:connected`, `bluetooth:data`, `bluetooth:error`, `wifi:connected`, `wifi:data`, `wifi:error`, `usb:connected`, `usb:disconnected`, `headphone:connected`, `headphone:disconnected`, `volume:changed`, `keyboard:opened`, `keyboard:closed`, `phone:shaken`, `phone:faceDown`, `proximity:near`, `screenshot:taken`, `orientation:changed`, `nfc:received`, `network:changed`, `battery:changed`, `location:changed`, `notification:received` e `notification:clicked`.
 
 Como tratar retornos:
 
@@ -470,6 +566,7 @@ No seu JavaScript do app:
 ```js
 toast("Mensagem");
 vibrar(250);
+await aguardar(5000);
 
 await notificar({
   titulo: "Pedido aprovado",
@@ -532,6 +629,14 @@ 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.
 
+`aguardar(ms)` e `loading(ms)` pausam o fluxo com Promise, sem travar a WebView:
+
+```js
+await toast("Comecando");
+await aguardar(5000);
+await toast("Continuando");
+```
+
 `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:
@@ -637,9 +742,10 @@ Arquivos, galeria e compartilhamento:
 
 ```js
 const imagem = await escolherImagem();
-const imagens = await escolherImagens({ multiplo: true });
+const imagens = await escolherImagens({ multiplas: true });
 const pdf = await escolherArquivo({ tipos: ["application/pdf"] });
 const arquivos = await escolherArquivos({ multiplo: true });
+const pasta = await escolherPasta();
 
 await salvarArquivo({
   nome: "relatorio.txt",
@@ -647,9 +753,75 @@ await salvarArquivo({
   conteudo: "Conteudo salvo pelo app"
 });
 
-await compartilhar({ texto: "Veja isso", url: "https://exemplo.com" });
+await compartilhar({
+  titulo: "Material",
+  texto: "Veja isso",
+  url: "https://exemplo.com",
+  arquivo: imagem
+});
+
+aoReceberCompartilhamento((dados) => {
+  console.log("Compartilhamento recebido", dados.tipo, dados.uri || dados.texto);
+});
+
+const texto = await ocr(imagem);
+console.log(texto.texto);
+
+await falar("Ola mundo", { idioma: "pt-BR", velocidade: 1 });
+const voz = await ouvir({ idioma: "pt-BR" });
+console.log(voz.texto);
+
+aoConectarBT((dispositivo) => {
+  console.log("Bluetooth conectado", dispositivo.nome);
+});
+
+aoReceberDadosBT((dados) => {
+  console.log("Dados Bluetooth", dados);
+});
+
+aoDarErroBT((erro) => {
+  console.log("Erro Bluetooth", erro.mensagem || erro.message);
+});
+
+const dispositivos = await procurarBT();
+if (dispositivos[0]) {
+  await conectarBT(dispositivos[0].id);
+  await enviarBT({ mensagem: "Ola por Bluetooth" });
+}
+
+aoConectarWiFi((dispositivo) => {
+  console.log("Wi-Fi conectado", dispositivo.nome || dispositivo.host);
+});
+
+aoReceberDadosWiFi((dados) => {
+  console.log("Dados Wi-Fi", dados);
+});
+
+aoDarErroWiFi((erro) => {
+  console.log("Erro Wi-Fi", erro.mensagem || erro.message);
+});
+
+const dispositivosWifi = await procurarWiFi();
+if (dispositivosWifi[0]) {
+  await conectarWiFi(dispositivosWifi[0].id);
+  await enviarWiFi({ mensagem: "Ola por Wi-Fi" });
+}
+
+await share_me(); // compartilha o APK do proprio app aberto
 ```
 
+`escolherImagem()` e `escolherImagens()` usam o Android Photo Picker no Android 13+ e caem automaticamente para o Storage Access Framework em Android antigo. Quando o Photo Picker esta disponivel, o html2apk nao solicita permissao ampla de armazenamento. O retorno segue o mesmo formato dos seletores: `{ uri, nome, mimeType, tamanho }`.
+
+`compartilhar()` aceita texto, link, imagem, video, PDF, arquivo salvo pelo app, URI `content://` e lista de arquivos em `arquivo`/`arquivos`. O retorno confirma a abertura do share sheet com `{ ok: true }`.
+
+Apps gerados tambem entram no menu Compartilhar do Android para `text/plain`, `image/*`, `video/*`, `application/pdf` e `*/*`. Use `obterCompartilhamentoInicial()` no boot se o app foi aberto por compartilhamento, e `aoReceberCompartilhamento()` para receber novos intents enquanto ele ja esta aberto.
+
+`ocr()` usa ML Kit local para reconhecimento de texto em imagens. O processamento fica offline no aparelho. `falar()` usa o TextToSpeech do Android e `ouvir()` usa o reconhecedor de voz do sistema; ambos aceitam `idioma: "pt-BR"` ou `idioma: "auto"`.
+
+Bluetooth usa RFCOMM classico entre apps html2apk. O aparelho que vai receber registra `aoConectarBT()`, `aoReceberDadosBT()` e, se quiser tratar falhas, `aoDarErroBT()`; isso inicia o servidor interno. O outro chama `procurarBT()`, escolhe um `id`, chama `conectarBT(id)` e envia JSON com `enviarBT(objeto)`. Para aparecer na busca, o aparelho precisa estar pareado ou visivel nas configuracoes Bluetooth do Android.
+
+Wi-Fi local usa descoberta NSD e socket TCP entre apps html2apk na mesma rede ou hotspot. O aparelho que vai receber registra `aoConectarWiFi()`, `aoReceberDadosWiFi()` e `aoDarErroWiFi()`; isso inicia o servidor interno e anuncia o app na rede local. O outro chama `procurarWiFi()`, escolhe um `id`, chama `conectarWiFi(id)` e envia JSON com `enviarWiFi(objeto)`. Nao e Wi-Fi Direct: os dois aparelhos precisam estar conectados na mesma rede local, ou um deles precisa estar no hotspot do outro.
+
 `salvarArquivo()` tem dois modos:
 
 - `salvarArquivo({ nome, conteudo })` abre o seletor nativo para o usuario escolher onde salvar, como ja acontecia.
@@ -684,7 +856,8 @@ await baixarArquivo("https://exemplo.com/relatorio.pdf", "relatorio.pdf");
 await abrirArquivo("relatorio.pdf");
 
 await baixarBase64("foto.png", base64DaImagem, {
-  mimeType: "image/png"
+  mimeType: "image/png",
+  galeria: true
 });
 
 const arquivo = await escolherArquivo();
@@ -695,6 +868,8 @@ if (arquivo) {
 
 Durante `baixarArquivo()`, `baixarBase64()` e `baixarArquivoLocal()`, o Android mostra uma notificacao de progresso quando a permissao `POST_NOTIFICATIONS` estiver liberada. No Android 13+, o html2apk pede essa permissao automaticamente; se o usuario negar, o download continua e o retorno vem com `notificationShown: false`.
 
+Por padrao, o arquivo baixado fica no armazenamento do app para funcionar com `abrirArquivo()` e `compartilharArquivo()`. Para imagem ou video aparecer na galeria, passe `{ galeria: true }`; no Android 10+ o html2apk publica uma copia em `Pictures/html2apk` ou `Movies/html2apk` e retorna `publicUri`.
+
 Papel de parede:
 
 ```js
@@ -853,6 +1028,27 @@ const abertos = await appsAbertos();
 
 Por privacidade, Android moderno pode limitar essa lista ao proprio app e alguns processos visiveis ao APK. Entao essa funcao nao deve ser tratada como gerenciador completo de tarefas do sistema.
 
+Tela, volume e ciclo do app:
+
+```js
+const volume = await volumeAtual();
+console.log(volume.midia.atual, volume.midia.maximo);
+
+await definirVolume("midia", 0.5, { mostrarUI: true });
+await aumentarVolume("midia", 1);
+await diminuirVolume("midia", 1);
+
+const imagem = await capturarTela();
+document.querySelector("img.preview").src = imagem.dataUrl;
+
+await minimizarApp();
+
+// Use somente depois de salvar estado importante:
+// await fecharApp();
+```
+
+`capturarTela()` captura a tela do proprio APK/WebView, nao outros apps ou areas protegidas do sistema. `definirVolume()` aceita porcentagem entre 0 e 1 ou passos absolutos do stream.
+
 Eventos nativos:
 
 ```js
@@ -865,11 +1061,27 @@ aoEvento("botao:voltar", console.log);
 aoEvento("link:aberto", (evento) => console.log(evento.url));
 aoEvento("rede:mudou", console.log);
 aoEvento("bateria:mudou", console.log);
+aoConectarUSB((dados) => console.log("USB conectado", dados));
+aoDesconectarUSB(() => console.log("USB desconectado"));
+aoReceberNotificacao((dados) => console.log("Notificação recebida", dados));
 aoEvento("notificacao:clicada", console.log);
+aoConectarFone((dados) => console.log("Fone conectado", dados.dispositivo));
+aoDesconectarFone(() => console.log("Fone desconectado"));
+aoMudarVolume((dados) => console.log("Volume de mídia", dados.midia.atual));
+aoAbrirTeclado((dados) => console.log("Teclado abriu", dados.alturaTeclado));
+aoFecharTeclado(() => console.log("Teclado fechou"));
+aoMudarOrientacao((dados) => console.log("Orientação", dados.orientacao));
+aoSacudirCelular((dados) => console.log("Sacudiu", dados.forca));
+aoVirarCelularParaBaixo(() => console.log("Tela para baixo"));
+aoAproximarObjeto((dados) => console.log("Objeto perto", dados.distancia));
+aoTirarPrint((dados) => console.log("Print detectado", dados.uri));
+aoNFC((dados) => console.log("Tag NFC", dados.id, dados.mensagens));
 
 parar();
 ```
 
+Eventos de sensor e sistema seguem limites do Android/fabricante. `aoTirarPrint()` observa a MediaStore e depende do nome/pasta da captura; pode não disparar em alguns aparelhos. `aoNFC()` escuta tags enquanto o app está aberto em primeiro plano e exige NFC ligado no aparelho.
+
 Deep links:
 
 ```js

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "html2apk",
-  "version": "0.9.0",
+  "version": "0.11.0",
+  "author": { "name": "Dev Caio Multiversando", "email": "dev@caio.local" },
+
   "description": "Node CLI and library to turn an HTML/CSS/JS folder into an Android APK through Cordova.",
   "main": "index.js",
   "bin": {
-    "html2apk": "./bin/html2apk.js"
+    "html2apk": "bin/html2apk.js"
   },
   "type": "commonjs",
   "license": "MIT",
   "files": [
     "bin",
     "src",
-    "examples",
+    "examples/minimal/app.json",
+    "examples/minimal/index.html",
     "index.js",
     "html2apk.png",
     "README.md"
@@ -21,7 +24,9 @@
     "doctor": "node bin/html2apk.js doctor",
     "desktop": "node bin/html2apk-desktop.js",
     "build-desktop-win": "node scripts/build-desktop-portable.js",
-    "test": "node --test",
+    "build-desktop-deb": "npx electron-builder --linux deb",
+
+    "test": "node --test test/config.test.js",
     "build-win": "pkg . --targets node20-win-x64 --output dist/html2apk.exe",
     "build-linux": "pkg . --targets node20-linux-x64 --output dist/html2apk-linux",
     "build-mac": "pkg . --targets node20-macos-x64 --output dist/html2apk-macos"
@@ -60,6 +65,12 @@
         "portable"
       ],
       "icon": "html2apk.png"
+    },
+    "linux": {
+      "target": [
+        "deb"
+      ],
+      "icon": "html2apk.png"
     }
   },
   "devDependencies": {