Guia de produção do Verniz Sites

Verniz Sites transforma uma aplicação Zolo tipada em site estático portátil, produto híbrido ou servidor standalone. HTML é o produto padrão. JavaScript só entra para islands, entries, mounts, navegação progressiva, offline ou outra capability habilitada explicitamente.

O build normal não exige Node. O typescript-rs embutido verifica e emite TypeScript; Rolldown/Oxc faz bundle, splitting e minificação; Aube resolve npm e JSR atrás do adapter de pacotes selado pelo Zolo.

Comece um projeto completo¶

[project]
entry = "src/main.zolo"

[web]
output = "static"             # static | hybrid | server
out_dir = "dist"
public_dir = "public"
base = "/"
trailing_slash = "always"
minify = true
source_maps = "external"

[client]
target = "es2022"
typecheck = "strict"
split = true

zolo dev
zolo build --web=static
zolo explain web /
zolo preview

Resultado esperado: zolo dev preserva o último programa válido e atualiza a aba após um save correto; o build mostra rotas, HTML/CSS/JS/assets, budgets, rotas renderizadas/reutilizadas e duração; _zolo/web-manifest.json sela cada byte publicado; preview valida o manifesto antes de escutar. Um segundo build byte-idêntico informa produto inalterado sem substituir dist/.

JavaScript, TypeScript, npm e JSR¶

Entries com ./ ou ../ são relativas ao arquivo .zolo; paths sem prefixo são relativos à raiz do projeto:

{client.entry("./client/about.ts")}
{client.entry("src/client/admin.ts")}

TypeScript pequeno pode ficar junto do markup em <script client lang="ts">...</script>. Produção sempre usa o emitter canônico antes do bundler Rust. Dev mantém Program, bundle e last-good incrementais por entry. Maps e diagnostics apontam ao .ts ou ao body exato no .zolo, nunca ao staging.

zolo add npm:[email protected]
zolo add jsr:@luca/[email protected]
zolo install
zolo audit packages --deny warnings
zolo explain packages

O manifesto guarda declarações diretas exatas e zolo.lock sela exports, conditions, transitivas, peers, integrity, licença e provenance. Builds reconstroem o VFS offline/frozen, sem node_modules autoral, rede, install ou lifecycle implícito. O editor consome o mesmo descritor: resolution, completion/auto-import, hover, definition e diagnostics causais usam o pacote que o build realmente usará.

Fronteira tipada e produto completo¶

verniz:routes/actions/env/assets/client são módulos virtuais tipados. client.mount recebe props Wire-safe, abort e cleanup determinístico. Actions têm codecs, cancelamento, revalidation e erros de domínio, HTTP, offline e protocolo separados. Any, closures, handles, filesystem resources e secrets não atravessam essa fronteira silenciosamente.

Collections Markdown/JSON/TOML/YAML tipadas geram páginas, feeds, sitemap e SEO. Provenance por rota limita o rebuild ao documento alterado e aos índices compartilhados. public/ preserva URLs; assets.file gera nomes por conteúdo; imagens podem ganhar dimensões, AVIF/WebP responsivo e placeholder zero-JS; assets.font gera subset WOFF2 auditado ou fallback seguro. CSS, preload, SRI e budgets derivam das arestas reais do grafo.

Navigation/View Transitions, PWA, offline, edge e task cache são opt-ins separados, removíveis e budgetados. O task graph delega sites ao WebGraph e usa inputs/outputs exatos apenas em tarefas genéricas. Vite, Vitest e tsdown são escape hatches externos explícitos.

O candidato de release é medido como comando completo, não como microbenchmark do compilador. A comparação atual no mesmo host, sua variância e o checkpoint histórico P10b estão no benchmark de release do Verniz.

Matriz de exemplos executáveis¶

Capacidade	Exemplo/comando	Prova esperada
Static zero-JS	`zolo build --web=static examples/features/36-web/19-static-site-build.zolo` duas vezes	Duas páginas + 404 + manifesto; segundo build inalterado/reutilizado; 0 B JS.
Rotas dinâmicas	`zolo build --web=static examples/features/36-web/20-static-dynamic-routes.zolo`	Uma página por slug enumerado; params inválidos falham antes do publish.
Assets	`zolo dev examples/features/36-web/21-authored-assets.zolo` e depois build static	HMR do asset no dev; URL de produção hasheada e selada.
Mount/action/Wire	build static de `22-client-mount-actions.zolo`	Chunk tipado e bridge retidos apenas pela rota dona.
Conteúdo/SEO	em `23-content-site`, dois builds static	Páginas, feed e sitemap determinísticos; segundo build reutiliza rotas.
Hybrid	em `24-hybrid-product`, build hybrid + preview	Página estática e runtime standalone selado para rota/action/form.
Navigation	em `25-navigation-site`, build static + explain + preview	Links normais válidos; runtime/targets opt-in explicados.
TS inline	em `26-inline-typescript`, dois builds + dev	Chunk/maps canônicos, reuse e HMR a partir de `.zolo` ou `.ts`.
PWA/offline/edge	em `27-pwa-edge`, build + explain + preview	Manifest, cache budgetado e adapter edge import-free validados.
Tasks/workspace	em `28-task-workspace`, `zolo task build --all --graph` e duas execuções	4 nós/3 arestas, reuse WebGraph e `cache hit` no generator.

Limites honestos¶

Static recusa rotas dependentes de request; use hybrid/server explicitamente.
Dependências diretas usam versões exatas. Ranges/tags esperam uma política de update. O tsgo Microsoft ainda não expõe a API estática de package mappings; a pista nativa completa atual é o typescript-rs.
Offline devolve HTML cacheado só após falha real de rede, nunca para erro HTTP ou navegação com query. Código dinâmico ainda não executa no adapter Wasm edge.
Reconciliação de listas reativas e forms com refinement types continuam como trabalho de linguagem separado. Wire, leak checking, mounts e actions já estão implementados.

A arquitetura normativa e todas as evidências por fase estão em specs/verniz-sites.html.