O site kshana.dev

web/ é a árvore que o GitHub Pages serve como https://kshana.dev: as páginas (index.html, missions.html, capabilities.html, evidence.html, developers.html, editions.html), a documentação em docs/ e o Kshana Studio em studio/ (servido em https://kshana.dev/studio/), o aplicativo que executa o motor no navegador como WebAssembly (WASM), sem computação no servidor e sem nada enviado. O Studio tem duas visões de um mesmo motor: a visão Simple (studio/index.html, a resposta primeiro, em palavras simples) e a visão Advanced (studio/advanced/index.html, o painel completo), que compartilha o motor, o worker, os módulos e os dados da visão Simple por meio de <base href="../">.

Desde a 0.35.0, o Studio tem mais quatro visões, cada uma em sua própria página com <base href="../">, sem indexação por buscadores e com uma pasta de amostras sintéticas que o seu teste lê:

studio/trust/: a visão marítima de confiança, uma pontuação de confiança do receptor para o fluxo de posições de uma embarcação, com uma trilha de demonstração em trust/demo/.
studio/training/: o debriefing de treinamento de tripulação, que reproduz NMEA sintético com um evento de jamming, drag-off, time-spoof ou replay (training/demo/).
studio/interference/: o mapa de interferência e a exposição de rotas (interference/demo/).
studio/tools/: uma página de cartões de ferramentas com exemplos (tools/examples/, tools/samples/), incluindo pacotes de evidências assinados (#evidence), a exportação para test bench (#bench), o mapeamento de compliance (#compliance), a verificação OSNMA do Galileo (#osnma) e os canais do assistente de IA (#ai).

De onde vêm os arquivos#

Três tipos de arquivo ficam aqui, e eles são alterados de três maneiras diferentes.

Arquivos portados. As páginas, docs/, css/, js/, assets/, os dados do site em data/ (land.json, search.json, series.json) e tudo em studio/ são escritos por web/tools/port_site.py a partir de um build do site e do código-fonte do Studio. PORT-MANIFEST.json lista cada um com o seu checksum SHA-256 (Secure Hash Algorithm, 256 bits). Não os edite aqui: site.test.mjs falha diante de uma edição manual. Altere a fonte e execute o port novamente:
```
python3 web/tools/port_site.py --site <built site folder> --studio <Studio folder>
python3 web/tools/port_site.py --site <built site folder> --studio <Studio folder> --check
```
O port é determinístico: uma segunda execução não escreve nada, e --check termina com 1 se web/ não for o que o port escreveria. Ele repassa sem alteração os arquivos de rastreamento do build do site (o canonical, o cartão social e as tags schema.org de cada página, robots.txt, sitemap.xml, llms.txt, llms-full.txt), confere-os, escreve legacy-redirects.js, 404.html e a página de encaminhamento no endereço antigo do Studio (playground/index.html, para /studio/), e aponta cada página para as fontes e bibliotecas de script locais (abaixo).
Arquivos que web/ possui. São fontes por mérito próprio, e o port nunca os toca:
- capabilities.json é a fonte estruturada dos cartões de capacidades e da grade de padrões. Edite esse arquivo, não o HTML.
- data/verification-matrix.json é gerado (cargo run --bin gen_validation_artifacts) e fixado por tests/verification_artifacts_doc_sync.rs; não o edite à mão. data/card-matrix-map.json, data/oracle-references.json e data/standards-matrix-map.json são mapeamentos mantidos à mão que o mesmo teste confere com a matriz gerada. As cópias do Studio em studio/data/ são esses arquivos, byte a byte.
- og-card.svg, og-card.png e og-card.rendered-from.json são o cartão social (python3 tools/gen_og_card.py).
- CNAME, .well-known/security.txt, favicon.svg.
- fonts/ e vendor/: os arquivos de fonte e a biblioteca de script que as páginas usam, obtidos uma única vez por tools/fetch_third_party.py e versionados (veja "Sem requisições a terceiros").
- build.sh, smoke.mjs, site.test.mjs, legacy-urls.test.mjs e tools/.
Saídas de build, ignoradas pelo git e produzidas por build.sh: pkg/ (o pacote wasm-pack, a partir do qual também se constrói o pacote npm), studio/pkg/ (o mesmo pacote, onde o Studio o importa) e scenarios/ (todo cenário de referência, no endereço de onde o site anterior, de página única, os servia).

Compilar e servir localmente#

./web/build.sh                     # compiles the WASM module and stages it for the Studio
python3 -m http.server -d web 8000 # serve over HTTP (required for WASM)
# open http://localhost:8000/

Sem a toolchain WASM, KSHANA_WASM_PKG=<a built pkg folder> ./web/build.sh prepara um pacote existente em vez de compilar um. O fluxo de trabalho do Pages nunca usa isso.

Testes#

node web/smoke.mjs                 # the WASM bindings (needs web/pkg)
node web/site.test.mjs             # the ported tree: manifest, version, counts, links, inline JSON
node web/tools/inline-json.test.mjs  # the guard for corrupt inline page data (an unescaped version bump)
node web/legacy-urls.test.mjs      # every old kshana.dev address still resolves
for f in web/studio/lib/*.test.mjs; do node "$f"; done   # the Studio's modules

Cada módulo em studio/lib/ é lógica pura com um *.test.mjs correspondente; os drivers do DOM (Document Object Model, a árvore de elementos da página) do Studio são studio/app.js (a visão Simple) e studio/advanced.js (a visão Advanced). A integração contínua executa cada um deles como uma etapa própria e falha se um arquivo de teste em web/ não tiver etapa.

Sem requisições a terceiros#

O kshana.dev serve as suas próprias fontes, estilos e scripts. Uma página não faz nenhuma requisição a um host de fontes ou a um host de scripts, de modo que o endereço de um visitante não é entregue a nenhum deles.

O site e o Studio são escritos para usar o Google Fonts e um host de scripts. O port substitui o link do Google Fonts de cada página pela folha de estilo correspondente em fonts/ (as mesmas regras @font-face e os mesmos arquivos de fonte, todos os subconjuntos, de modo que o texto seja renderizado como antes) e cada endereço de host de scripts pelo arquivo em vendor/. fonts/FONTS.json e vendor/VENDOR.json registram de onde veio cada arquivo e o seu checksum; as fontes estão sob a SIL Open Font License (fonts/OFL-*.txt) e o three.js sob a licença MIT (vendor/three@…/LICENSE).

tools/fetch_third_party.py --from <site folder> --from <Studio folder> é a única etapa que usa a rede. Execute-a novamente apenas quando uma página pedir um conjunto de fontes ou uma versão de biblioteca que não esteja aqui: o port recusa e informa isso. site.test.mjs falha se qualquer página, folha de estilo ou script portado nomear um host de fontes ou carregar qualquer coisa de outro host.

A página 404#

O GitHub Pages responde a um endereço inexistente com /404.html e o status 404. O port cria essa página a partir da própria estrutura da página inicial (navegação, rodapé, busca) em torno de uma mensagem curta com links para a Home, a Docs e o Studio. Todo endereço nela é escrito a partir da raiz do site, porque ela é servida em qualquer profundidade.

Endereços antigos#

Até a v0.28.0, o site era uma página única, e tudo ficava atrás de um fragmento em / (/#playground, /#ledger, links de compartilhamento como /#s=…, incorporações como /?embed=1&…; o nome antigo de uma aba em um link de incorporação, como tab=fom, abre a aba do Studio que a substituiu). tools/legacy-urls.json lista todo endereço desse tipo que o material publicado usa e para onde ele leva agora; a página inicial carrega legacy-redirects.js, gerado a partir dessa lista, para encaminhá-los até lá. Acrescente um caso à lista antes de aposentar qualquer endereço.

Implantação#

O fluxo de trabalho pages do GitHub Actions implanta uma tag de release, não main: release.yml o dispara assim que uma release é publicada, e um disparo manual reimplanta uma tag nomeada. Ele executa build.sh, prepara web/ sem os testes, o script de build, tools/, o manifesto e este arquivo, e publica o resultado no GitHub Pages.