O sítio 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/), a aplicação que executa o motor no navegador como WebAssembly (WASM), sem computação do lado do servidor e sem nada enviado. O Studio tem duas vistas de um só motor: a vista Simples (studio/index.html, a resposta primeiro, em linguagem simples) e a vista Avançada (studio/advanced/index.html, o painel completo), que partilha o motor, o worker, os módulos e os dados da vista Simples através de <base href="../">.

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

studio/trust/: a vista de confiança marítima, uma pontuação de confiança do recetor para um fluxo de posições de uma embarcação, com uma trajetória de demonstração em trust/demo/.
studio/training/: o debriefing de formação de tripulações, a repetir 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 do percurso (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 de test bench (#bench), o mapeamento de compliance (#compliance), a verificação Galileo OSNMA (#osnma) e os canais do assistente de IA (#ai).

De onde vêm os ficheiros#

Aqui existem três tipos de ficheiro, e são alterados de três formas diferentes.

Ficheiros portados. As páginas, docs/, css/, js/, assets/, os dados do sítio em data/ (land.json, search.json, series.json) e tudo o que está em studio/ são escritos por web/tools/port_site.py a partir de uma compilação do sítio e do código-fonte do Studio. PORT-MANIFEST.json lista cada um deles com a respetiva soma de controlo SHA-256 (Secure Hash Algorithm, 256 bits). Não os edite aqui: site.test.mjs falha perante uma edição manual. Altere a fonte e execute de novo a portagem:
```
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
```
A portagem é determinista: uma segunda execução não escreve nada, e --check termina com 1 se web/ não for o que a portagem escreveria. Transporta sem alterações os ficheiros de rastreio da compilação do sítio (as etiquetas canónicas, de cartão social e schema.org de cada página, robots.txt, sitemap.xml, llms.txt, llms-full.txt), verifica-os, escreve legacy-redirects.js, 404.html e a página de reencaminhamento no endereço antigo do Studio (playground/index.html, para /studio/), e aponta todas as páginas para os tipos de letra e as bibliotecas de scripts locais (abaixo).
Ficheiros que web/ possui. São fontes por direito próprio e a portagem nunca lhes toca:
- capabilities.json é a fonte estruturada dos cartões de capacidades e da grelha de normas. Edite esse ficheiro, e 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 verifica face à matriz gerada. As cópias do Studio em studio/data/ são estes ficheiros, 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 ficheiros de tipos de letra e a biblioteca de scripts que as páginas usam, descarregados uma vez por tools/fetch_third_party.py e registados (ver "Sem pedidos a terceiros").
- build.sh, smoke.mjs, site.test.mjs, legacy-urls.test.mjs e tools/.
Resultados da compilação, ignorados pelo git e produzidos por build.sh: pkg/ (o pacote wasm-pack, que é também a partir do qual o pacote npm é construído), studio/pkg/ (o mesmo pacote no local onde o Studio o importa) e scenarios/ (todos os cenários de referência, no endereço de onde o sítio 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 cadeia de ferramentas WASM, KSHANA_WASM_PKG=<a built pkg folder> ./web/build.sh prepara um pacote existente em vez de compilar um. O fluxo de trabalho das Pages nunca o usa.

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 controladores do DOM (Document Object Model, a árvore de elementos da página) do Studio são studio/app.js (a vista Simples) e studio/advanced.js (a vista Avançada). A integração contínua executa cada um deles como um passo próprio e falha se um ficheiro de teste em web/ não tiver passo.

Sem pedidos a terceiros#

O kshana.dev serve os seus próprios tipos de letra, estilos e scripts. Nenhuma página faz um pedido a um servidor de tipos de letra ou de scripts, pelo que o endereço de um visitante não lhe é entregue.

O sítio e o Studio são escritos para o Google Fonts e para um servidor de scripts. A portagem substitui a ligação ao Google Fonts de cada página pela folha de estilos correspondente em fonts/ (as mesmas regras @font-face e os mesmos ficheiros de tipos de letra, todos os subconjuntos, de modo que o texto seja desenhado como antes) e cada endereço de servidor de scripts pelo ficheiro em vendor/. fonts/FONTS.json e vendor/VENDOR.json registam de onde veio cada ficheiro e a sua soma de controlo; os tipos de letra 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> é o único passo que usa a rede. Execute-o de novo apenas quando uma página pedir um conjunto de tipos de letra ou uma versão de biblioteca que não esteja aqui: a portagem recusa e di-lo. site.test.mjs falha se alguma página, folha de estilos ou script portado nomear um servidor de tipos de letra ou carregar algo de outro servidor.

A página 404#

O GitHub Pages responde a um endereço em falta com /404.html e o estado 404. A portagem constrói essa página a partir do invólucro da própria página inicial (navegação, rodapé, pesquisa) à volta de uma mensagem curta com ligações para o Início, a Documentação e o Studio. Todos os endereços nela são escritos a partir da raiz do sítio, porque é servida a qualquer profundidade.

Endereços antigos#

Até à v0.28.0, o sítio era uma página única, e tudo ficava atrás de um fragmento em / (/#playground, /#ledger, ligações de partilha como /#s=…, incorporações como /?embed=1&…; o nome antigo de um separador numa ligação de incorporação, como tab=fom, abre o separador do Studio que o substituiu). tools/legacy-urls.json lista cada um desses endereços que material publicado usa e onde passa agora a ficar; a página inicial carrega legacy-redirects.js, gerado a partir dessa lista, para os encaminhar para lá. Acrescente um caso à lista antes de retirar qualquer endereço.

Implementação#

O fluxo de trabalho do GitHub Actions pages implementa uma etiqueta de versão, e não main: release.yml aciona-o depois de uma versão ser publicada, e um acionamento manual reimplementa uma etiqueta indicada. Executa build.sh, prepara web/ sem os testes, o script de compilação, tools/, o manifesto e este ficheiro, e publica o resultado no GitHub Pages.