Apps do Desk de página: HTML, CSS e JS na tela do Miblo Desk

O que é#

A partir do Miblo 1.45, o App do Desk padrão é uma página web. Você escreve HTML, CSS e JavaScript; o Miblo Hub renderiza a página em 240x240 no computador e manda para o Miblo Desk, pela rede local, só os pixels que mudaram. O computador desenha, o Miblo Desk só pinta.

Os Apps do Desk feitos do jeito antigo (cards, frames, animações e gráficos ao vivo) ficaram obsoletos, mas não saíram: continuam funcionando. Um App do Desk novo deve ser uma página; a referência do jeito antigo está em A tela App e em Animações.

Esta página cobre o App do Desk de página de ponta a ponta: como começar, o manifest.json, o que o main.js e a página fazem, as qualidades, os arquivos, a rede, o equivalente no SDK e, no fim, as limitações, que valem ler antes de começar.

Comece um#

miblo apps new "Meu relógio" --page
miblo apps dev meu-relogio

A pasta tem manifest.json, main.js, page.html e um README.md. O modelo é um relógio com o quanto do expediente já passou, e uma configuração (o fim do expediente). O simulador mostra a página ao vivo, ao lado da tela, com o mesmo window.miblo que a página recebe no Miblo Desk, e a carrega de novo a cada vez que você salva. Os outros comandos estão em Desenvolver sem um Miblo.

O manifest#

{
  "id": "meu-relogio",
  "api": 4,
  "display": "page",
  "page": "page.html",
  "network": [],
  "intervalMs": 60000
}

(Os campos de sempre, como name, promise e settings, continuam valendo: Publicar.)

• display: "page" e page: um arquivo .html da pasta do App do Desk. Pode estar numa subpasta (web/index.html).

• api: 4 (Miblo 1.45). Um manifest com display: "page" e api menor que 4 é recusado.

• Um App do Desk de página não pode ser só de alertas (screen: false).

• network: os únicos endereços que a página alcança (fetch, imagens, fontes). É a mesma regra do ctx.fetchJson; o resto é bloqueado e aparece uma vez no log do App do Desk. Veja A rede.

O main.js dá os dados, a página desenha#

O main.js continua sendo o programa que o Miblo roda a cada intervalMs. Em vez de um card, o run() devolve { data }: JSON, no máximo 16 KB.

export async function run(ctx) {
  return { data: { temp: 29, cidade: 'Recife' } };   // JSON, no máximo 16 KB
}

A página recebe os dados e desenha:

<script>
  function mostra(d) { if (d) document.querySelector('#t').textContent = d.temp + '°'; }
  mostra(window.miblo?.data);
  window.miblo?.on('data', mostra);
</script>

O Miblo entrega os dados à página: o primeiro run() abre a página já com eles, e cada um que muda chega depois. Dados iguais aos anteriores não são mandados de novo.

O window.miblo na página:

Desenhe em 240x240 e anime pelo tempo#

A viewport da página é exatamente 240x240 pixels CSS. Anime pelo tempo (animações CSS, o timestamp do requestAnimationFrame), nunca contando quadros: a página renderiza mais rápido do que o Miblo Desk pinta.

Qualidade#

O auto (o padrão) começa em medium, desce um nível quando o envio engasga e sobe depois de uns 5 s limpos, nunca acima de max. A página pode trocar a qualquer hora com miblo.quality(q): um layout parado em ultra, um fundo de vídeo em low.

Arquivos da página#

O CSS, as imagens, as fontes, os scripts e os vídeos ficam ao lado da página e carregam por caminho relativo.

Cada arquivo tem no máximo 256 KB; um vídeo pode ter o quanto o pacote permitir (2 MB no total). Para publicar na Loja de Apps do Desk, veja Publicar.

A rede#

A página carrega só arquivos da própria pasta e os endereços que o network do manifest permite, por https. O que não estiver na lista é bloqueado, e o bloqueio aparece uma vez no log do App do Desk. O main.js busca na internet com ctx.fetchJson, sob a mesma regra. Sem WebSocket, WebTransport nem WebRTC (veja as limitações).

Sem ser um App do Desk: o SDK#

Um programa que não é um App do Desk faz o mesmo pelo SDK, na tela do tool dele:

const screen = new MibloStatus().screen({ tool: 'clima' });
await screen.page('clima.html', { data: { city: 'Recife', temp: 29 }, quality: 'auto', max: 'high' });
await screen.data({ city: 'Recife', temp: 30 });   // a página ouve com miblo.on('data')
await screen.quality('ultra');                     // ou a própria página: miblo.quality('ultra')
await screen.clear();

• page(file, { data, quality, max }): file é um .html relativo à pasta de trabalho do programa (a página de um App do Desk instalado é sempre um arquivo do pacote dele). data é JSON, no máximo 16 KB. quality é 'auto' (o padrão), 'verylow', 'low', 'medium', 'high' ou 'ultra'; max limita até onde o auto sobe.

• data(obj): manda dados novos para a página.

• quality(q): troca a qualidade agora.

• Erro novo: no_page (status 409), quando data() ou quality() vêm antes de page().

Por enquanto, só o pacote @miblo/status (TypeScript) tem esses três métodos. O pacote Python ainda não, mas qualquer linguagem alcança a rota POST /sdk/v1/screen/page (e screen/data, screen/quality) pela referência.

Limitações#

O que uma página pode e não pode fazer, sem rodeios:

• O computador desenha. Um App do Desk de página só aparece enquanto o computador está ligado, acordado, com o Miblo Hub rodando e na mesma rede local do Miblo Desk. Quando o computador dorme ou sai da rede, a página para e o Miblo Desk volta às próprias telas (sessões, limites, alertas).

• Miblo Desk 1.45 ou mais novo. Um Miblo Desk mais antigo não mostra um App do Desk de página (a Loja de Apps do Desk e o miblo apps dizem "precisa de uma atualização de firmware"); os caminhos obsoletos de card, frame e animação continuam funcionando nos aparelhos mais antigos.

• A taxa de quadros é uma meta, não uma promessa. verylow mira 30 fps, ultra uns 10; o Wi-Fi decide o que chega (cerca de ±3 fps de uma vez para outra, em casa). Movimento rápido na tela inteira custa detalhe; texto fino se lê melhor em high ou ultra. No macOS, o AirDrop, o Handoff e as buscas de Wi-Fi dos Serviços de Localização travam o rádio por cerca de 100 ms, o que aparece como engasgos. A solução: AirDrop em "Ninguém", Handoff desligado e Serviços de Localização → Rede Wi-Fi desligado (Ajustes do Sistema → Privacidade e Segurança → Serviços de Localização → Serviços do Sistema).

• A tela. 240x240 pixels, 65 mil cores (RGB565); a imagem viaja em blocos 4x4 comprimidos, então as qualidades mais baixas suavizam o detalhe e as cores formam faixas leves em degradês suaves.

• Vídeo. WebM (VP9, AV1) sempre toca. MP4 H.264/AAC só toca quando o computador tem o Google Chrome ou o Microsoft Edge (o Chromium que o Miblo Hub baixa quando não há nenhum não tem os codecs licenciados). Sem som: o Miblo Desk não tem alto-falante, e as páginas ficam mudas.

• Sem entrada. A página não recebe cliques, toques nem teclas do Miblo Desk; ela reage aos dados que o App do Desk manda e ao tempo.

• Uma página por vez em cada Miblo Desk. Um alerta sempre toma a tela na hora (a página pausa e volta depois dele).

• Dados e rede. O que o run() devolve tem no máximo 16 KB de JSON; a página carrega só arquivos da própria pasta e os endereços que o network do manifest permite, por https. Sem WebSocket, WebTransport nem WebRTC: eles não existem num App do Desk de página (nem nos frames e workers dele), e os pop-ups, shared workers e service workers dele nunca rodam.

• O custo no computador. Um navegador headless para todas as páginas (cerca de 1-3 ms de CPU por quadro decodificado); quando não há Chrome, Edge nem Chromium instalado, o Miblo Hub baixa um (cerca de 100 MB) uma vez, em silêncio, na primeira vez que um App do Desk de página roda.