tempestweb 🌩️¶

Construa web apps em Python tipado. Uma árvore declarativa de widgets, um renderizador DOM, e dois modos de execução que compartilham 100% do código de aplicação.

tempestweb é o irmão web do tempestroid — a mesma ideia de uma árvore, múltiplos renderizadores. Você escreve uma função view() em Python e ela roda, sem alteração, em dois modos:

Modo A — WASM

Seu Python roda no browser via Pyodide. Análogo a PyScript. Offline pleno depois do load.
Modo B — Servidor

Seu Python roda no servidor (FastAPI) e fala com um cliente JS fino por WebSocket ou SSE. Análogo a Phoenix LiveView.

O segredo: o app nunca nomeia um transporte. O mesmo examples/counter/app.py roda sob --mode wasm e --mode server sem mudar uma linha. 🚀

Como funciona¶

   view(app) ──build──▶ árvore de Node (IR)        ← core compartilhado
                            │
                          diff
                            ▼
                        [ Patch ]              insert / remove / update / reorder / replace
                       ╱          ╲
              Transporte Modo A   Transporte Modo B
              (pyodide.ffi)       (WebSocket / SSE)
                       ╲          ╱
                  client/ (JS puro): aplica patches no DOM
                  + Style→CSS + captura de eventos   ← MESMO código nos dois modos

A função view() produz uma árvore de widgets (IR). O reconciliador faz diff entre a árvore antiga e a nova e emite patches — dados puros serializados. O cliente JS só sabe consumir patch e mutar o DOM; não liga de onde o patch veio. Por isso o renderizador é um só nos dois modos.

Por onde começar

Vá direto para a Instalação e depois siga o Tutorial — o Counter. Em quatro páginas curtas você constrói o app canônico e entende o contrato de fronteira de ponta a ponta.

O que você vai encontrar aqui¶

Instalação — prepare o ambiente em um minuto.
Arquitetura — as quatro camadas e por que o renderizador é compartilhado.
Tutorial — construa o counter, um conceito por página.
Contrato de fronteira — o wire format Python↔cliente.
Capacidades — Web APIs tipadas (geolocation, clipboard, camera) como awaitables Python.
PWA e offline — app instalável, service worker, IndexedDB, WebPush.
Observabilidade — telemetry, logger, feature flags, auth.
Roadmap e docs de design — o que vem por aí e os planos vivos do projeto.

Idioma

Esta documentação é bilíngue. Use o seletor de idioma no topo da página para alternar entre Português (Brasil) e English (US).

Convenções do projeto¶

Python: aspas duplas, tipagem completa (mypy --strict), docstrings Google em inglês, async-first. Cliente: JavaScript puro — sem TypeScript, sem framework, sem passo de build.

Estado do projeto

🚧 tempestweb está em construção inicial. Os planos de design vivos estão versionados no repositório: plan.md, roadmap.md e contract.md. Esta documentação reflete a superfície já construída e linka os planos para o detalhe completo.