Um app que imprime etiqueta de verdade — e a história de como ele chegou aqui

Isso aqui não é release note. É a história do freeLabel contada do começo: o problema, as tentativas que falharam, o bug que parecia impossível, as medições que ninguém faz, e o que já dá para fazer hoje com ele.

a tela de trabalho hoje — essa é a versão 1.52.0

Role para baixo. Cada capítulo tem print de verdade — nada de mockup.

Tudo começou com uma situação bem comum em campo: preciso identificar equipamento — bomba, compressor, quadro elétrico, válvula — com etiqueta que aguente o ambiente e que dê para ler daqui a dois anos, com graxa em cima. A solução óbvia é uma impressora térmica de etiquetas. A que apareceu foi uma Seiko SLP650.

O problema não é a impressora. É o caminho até ela:

• O software oficial quer instalar driver e mexer no sistema — coisa que exige senha de admin, e o computador em uso não é meu.
• Sem o driver, o macOS “vê” a impressora, mas imprime lixo: manda texto, sai página em branco; manda PNG, sai uma tarja preta. Cada impressora térmica tem uma linguagem própria.
• O app oficial da SII é pesado, preso à versão do sistema, e não faz o que eu queria: lote a partir de planilha, modelo salvo em arquivo, layout em milímetros.

Depois de muita tentativa (e bastante papel jogado fora), apareceu o caminho: a própria SII distribui um filtro CUPS — um programinha que converte imagem em comandos da impressora. Ele se chama rastertosiislp e vem dentro do pacote oficial, que é só um monte de arquivos.

A ideia então foi simples e teimosa: se o problema é “instalar”, então não instale nada. Copiar o filtro oficial para uma pasta comum, usar o backend USB que já existe no macOS, e chamar a impressão por script — tudo dentro da pasta do usuário, sem sudo, sem driver assinado, sem tocar no sistema.

Nasceram aí os primeiros comandos numerados: 0-liberar (tira a quarentena), 1-diagnostico, 2-imprimir, 3-teste-minimo — que imprime um SLP de teste para separar “problema de transporte” de “problema de conversão”. Até hoje eles estão no pacote, porque diagnóstico é metade do trabalho.

Com o caminho de impressão resolvido, o próximo problema era óbvio: eu estava desenhando etiqueta em editor de imagem, medindo pixel na régua, torcendo para o texto caber. Isso não escala.

A escolha foi radical de propósito: um único arquivo HTML, aberto numa janela própria, sem servidor de internet, sem build complexo. Todas as bibliotecas (código de barras, QR, leitor de planilha) ficam dentro do arquivo. Consequência: funciona sem internet, funciona em Mac antigo, funciona se você copiar a pasta para um pendrive.

Por que milímetros importam tanto

A etiqueta é 54 × 101 mm (rolo SLP-SRL). A térmica imprime a 203 dpi, o que dá exatamente 8 pontos por milímetro. Se o layout fosse em pixel de tela, cada zoom bagunçaria a medida. Em milímetros, o app sabe que 1 mm = 8 pontos e consegue gerar o PNG já no tamanho final de impressão — sem “ajustar à página” e sem sair deslocado.

Modelos que sobrevivem a atualização

Modelo salvo no navegador é frágil: limpar cache, trocar de janela, atualizar o app — some. Aqui o modelo vai para arquivo, em dados/modelos.json ao lado do app, com uma cópia da versão anterior em modelos.bak.json. Se a gravação falhar no meio, o backup salva o dia. E o backup/restauração em JSON existe para levar modelos de uma máquina para outra sem sobrescrever: modelo repetido entra como “(importado)”.

O motivo de o app existir, na prática: casa de bombas com 40 equipamentos. Cada etiqueta tem TAG, nome e setor. Digitar 40 vezes é garantia de erro de digitação — e erro em etiqueta de segurança não é detalhe.

O fluxo é este: você monta uma etiqueta com marcadores {{codigo}}, {{nome}} e {{setor}} (ou liga cada camada a uma coluna pelo painel Campos da etiqueta), escolhe o arquivo .xlsx ou .csv, confere a prévia da primeira etiqueta e manda imprimir. O app lê a planilha dentro da máquina — nada é enviado para a internet.

• Ligar sozinho: o app compara o nome da camada com o nome da coluna e já sugere o vínculo. Palpite conservador de propósito: “Setor B” não vira “setor” por engano.
• Baixar planilha do layout: gera um .xlsx com uma coluna por camada da etiqueta, já com exemplos — acabou o “como é que eu monto a planilha?”.
• Vias por linha: coluna copias/qtd faz a mesma etiqueta sair várias vezes.
• Relatório do lote: ao terminar, dá para baixar um .txt com o que saiu, o que falhou e por quê.

Abrir no Chrome em modo app funciona, mas tem cara de site. A virada foi criar uma janela nativa (WKWebView) gerada na hora com osacompile: ícone no Dock, título, foco, restaurar ao clicar no ícone. O visual segue sendo o mesmo HTML — só que dentro de uma janela de app.

Só que aí apareceu o bug mais instrutivo do projeto. No app instalado, três botões não faziam nada:

• Escolher planilha (.xlsx / .csv)
• Baixar modelo .xlsx
• Baixar planilha do layout

Nenhum erro, nenhum aviso. Clicava e o silêncio. A causa: um WebView não tem seletor de arquivo nem download por padrão. Abrir aquela janelinha do Finder e salvar arquivo são coisas que o app precisa implementar — o Chrome faz, o WebView puro não faz. E o app não tinha esse pedaço.

A gambiarra que virou arquitetura

Como o app já roda um servidor Perl local (é ele que serve o HTML e conversa com a impressora), a solução foi ensinar esse servidor a abrir os diálogos do macOS:

• GET /pick → abre “escolher arquivo”, devolve o arquivo escolhido em base64;
• POST /save → abre “salvar como”, grava e revela no Finder; se o diálogo falhar, salva direto em ~/Downloads;
• o HTML ganhou uma “ponte” que só liga quando percebe que está no WebView — no Chrome continua tudo como sempre foi.

Pergunta legítima de quem vai imprimir: “cabe isso no código?”. Em vez de repetir o que dizem por aí, medi nas bibliotecas que o app realmente usa — e conferi decodificando de volta.

Resumo da medição: um QR de 1.000 caracteres ocupa 105 × 105 módulos; de 2.000, 149 × 149; o teto de 2.953 chega em 177 × 177. No papel, com a térmica a 203 dpi, o mínimo confiável é 2 pontos por módulo (0,25 mm). Numa área de 44 mm isso dá 2,6 pontos/módulo para 1.000 caracteres — passa — e 1,9 para o teto, que sai borrado. Ou seja: até ~1 KB é seguro no lado curto; o teto só cabe no lado longo de 101 mm.

Um pedido simples: começar do zero sem apagar objeto por objeto. Agora existe o botão azul Nova etiqueta no topo do painel esquerdo, antes do seletor de papel. Ele pergunta antes, diz o que vai apagar, e não mexe no que não deve: papel escolhido e calibração ficam, modelos salvos ficam. Deu errado? Ctrl/⌘ Z volta.

Junto veio um detalhe que parecia cosmético e não era: o número da versão no cabeçalho estava digitado à mão no HTML (v1.46.0) enquanto o pacote já ia na 1.50. Ou seja: o app mentia sobre a própria versão — e é justamente esse número que responde “você está com o build novo?”. Agora o número é injetado no build a partir de um único lugar, e o empacotador aborta se não achar o marcador. Nunca mais dessincroniza.

O pedido veio como imagem: uma etiqueta coberta por LACRE em diagonal, e no meio dela, de vez em quando, GARANTIA aparecendo em outro estilo. É o velho truque de segurança: difícil de copiar, fácil de reconhecer de longe — se a etiqueta foi violada, o padrão denuncia.

O modificador virou um item de texto normal com uma chave ligada: Padrão diagonal. Você digita a palavra, opcionalmente a palavra de destaque, e regula quatro coisas:

• % — chance do destaque aparecer (10% é discreto, 15% é o “lacre clássico”);
• entr — espaçamento entre linhas (1,35 denso, 1,75 arejado);
• âng — inclinação (−33° é o padrão que parece carimbo);
• cobrir etiqueta — estica a caixa exatamente na área imprimível.

Para quem gosta do encanamento — e para quem for mexer no app depois:

• Sincronizar entre dispositivos: modelo salvo fica na máquina. Para levar, use backup/restauração em JSON
• Registro de porto/equipamento: o app imprime bem; ele não é banco de dados de ativos (ainda)
• Leitor de código: ele gera QR e código de barras, não lê — conferência é no leitor/sistema de quem usa
• Windows: é macOS. O caminho de impressão depende do filtro CUPS e do backend USB do sistema
• Etiqueta contínua longa: o limite prático é o tamanho de mídia que o driver da SLP650 conhece

Cada item desses é uma decisão adiada de propósito: enquanto não aparecer necessidade real, mexer nisso só aumenta a chance de quebrar o que já funciona. Esse app é usado para imprimir etiqueta de segurança em campo — “bonitinho” perde para “não me deixa errar”.