Le site kshana.dev

web/ est l'arborescence que GitHub Pages sert sous https://kshana.dev : les pages (index.html, missions.html, capabilities.html, evidence.html, developers.html, editions.html), la documentation sous docs/, et Kshana Studio sous studio/ (servi à https://kshana.dev/studio/), l'application qui exécute le moteur dans le navigateur sous forme de WebAssembly (WASM), sans calcul côté serveur et sans rien téléverser. Le Studio offre deux vues d'un même moteur : la vue Simple (studio/index.html, la réponse d'abord, en langage courant) et la vue Avancée (studio/advanced/index.html, le tableau de bord complet), qui partage le moteur, le worker, les modules et les données de la vue Simple via <base href="../">.

Depuis la 0.35.0, le Studio compte quatre vues de plus, chacune étant sa propre page avec <base href="../">, sans indexation par les moteurs de recherche, et un dossier d'échantillons synthétiques que son test lit :

studio/trust/ : la vue de confiance maritime, un score de confiance du récepteur pour un flux de positions de navire, avec une trace de démonstration dans trust/demo/.
studio/training/ : le débriefing de formation d'équipage, qui rejoue du NMEA synthétique avec un événement de brouillage, de décrochage, de leurrage temporel ou de rejeu (training/demo/).
studio/interference/ : la carte des interférences et l'exposition d'un itinéraire (interference/demo/).
studio/tools/ : une page de cartes d'outils avec des exemples (tools/examples/, tools/samples/), dont les paquets de preuves signés (#evidence), l'export test bench (#bench), la cartographie compliance (#compliance), la vérification Galileo OSNMA (#osnma) et les canaux de l'assistant IA (#ai).

D'où viennent les fichiers#

Trois sortes de fichiers vivent ici, et elles se modifient de trois manières différentes.

Fichiers portés. Les pages, docs/, css/, js/, assets/, les données du site dans data/ (land.json, search.json, series.json) et tout ce qui se trouve sous studio/ sont écrits par web/tools/port_site.py à partir d'une construction du site et de la source du Studio. PORT-MANIFEST.json les liste tous avec leur somme de contrôle SHA-256 (Secure Hash Algorithm, 256 bits). Ne les modifiez pas ici : site.test.mjs échoue en cas de modification manuelle. Changez la source et relancez le portage :
```
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
```
Le portage est déterministe : une seconde exécution n'écrit rien, et --check se termine avec le code 1 si web/ n'est pas ce que le portage écrirait. Il reprend tels quels les fichiers d'exploration de la construction du site (les balises canoniques, de carte sociale et schema.org de chaque page, robots.txt, sitemap.xml, llms.txt, llms-full.txt), les vérifie, écrit legacy-redirects.js, 404.html et la page de redirection à l'ancienne adresse du Studio (playground/index.html, vers /studio/), et fait pointer chaque page vers les polices et bibliothèques de scripts locales (ci-dessous).
Fichiers que possède web/. Ce sont des sources à part entière, et le portage n'y touche jamais :
- capabilities.json est la source structurée des cartes de capacités et de la grille des normes. Modifiez-la, et non le HTML.
- data/verification-matrix.json est généré (cargo run --bin gen_validation_artifacts) et figé par tests/verification_artifacts_doc_sync.rs ; ne le modifiez pas à la main. data/card-matrix-map.json, data/oracle-references.json et data/standards-matrix-map.json sont des correspondances maintenues à la main que le même test vérifie par rapport à la matrice générée. Les copies du Studio sous studio/data/ sont ces fichiers, octet pour octet.
- og-card.svg, og-card.png et og-card.rendered-from.json forment la carte sociale (python3 tools/gen_og_card.py).
- CNAME, .well-known/security.txt, favicon.svg.
- fonts/ et vendor/ : les fichiers de polices et la bibliothèque de scripts qu'utilisent les pages, récupérés une fois par tools/fetch_third_party.py et versionnés (voir « Aucune requête tierce »).
- build.sh, smoke.mjs, site.test.mjs, legacy-urls.test.mjs et tools/.
Sorties de construction, ignorées par git et produites par build.sh : pkg/ (le paquet wasm-pack, à partir duquel le paquet npm est aussi construit), studio/pkg/ (le même paquet à l'endroit où le Studio l'importe) et scenarios/ (chaque scénario de référence, à l'adresse d'où l'ancien site d'une seule page les servait).

Construire et servir en local#

./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/

Sans la chaîne d'outils WASM, KSHANA_WASM_PKG=<a built pkg folder> ./web/build.sh met en place un paquet existant au lieu d'en compiler un. Le workflow Pages ne l'utilise jamais.

Tests#

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

Chaque module de studio/lib/ est de la logique pure avec un *.test.mjs correspondant ; les pilotes du DOM (Document Object Model, l'arbre des éléments de la page) du Studio sont studio/app.js (la vue Simple) et studio/advanced.js (la vue Avancée). L'intégration continue exécute chacun de ces tests comme une étape distincte et échoue si un fichier de test sous web/ n'a pas d'étape.

Aucune requête tierce#

kshana.dev sert ses propres polices, styles et scripts. Une page n'envoie aucune requête à un hébergeur de polices ou de scripts, de sorte que l'adresse d'un visiteur n'est transmise à aucun d'eux.

Le site et le Studio sont écrits pour Google Fonts et un hébergeur de scripts. Le portage remplace le lien Google Fonts de chaque page par la feuille de style correspondante dans fonts/ (les mêmes règles @font-face et les mêmes fichiers de polices, tous les sous-ensembles, de sorte que le texte s'affiche comme avant) et chaque adresse de l'hébergeur de scripts par le fichier sous vendor/. fonts/FONTS.json et vendor/VENDOR.json consignent l'origine de chaque fichier et sa somme de contrôle ; les polices sont sous la SIL Open Font License (fonts/OFL-*.txt) et three.js sous la licence MIT (vendor/three@…/LICENSE).

tools/fetch_third_party.py --from <site folder> --from <Studio folder> est la seule étape qui utilise le réseau. Ne la relancez que lorsqu'une page demande un jeu de polices ou une version de bibliothèque qui n'est pas présent : le portage refuse et le dit. site.test.mjs échoue si une page, une feuille de style ou un script porté nomme un hébergeur de polices ou charge quoi que ce soit depuis un autre hôte.

La page 404#

GitHub Pages répond à une adresse manquante par /404.html et le statut 404. Le portage fabrique cette page à partir de la coque propre à la page d'accueil (navigation, pied de page, recherche) autour d'un court message avec des liens vers l'accueil, la documentation et le Studio. Chaque adresse qu'elle contient est écrite à partir de la racine du site, parce qu'elle est servie à n'importe quelle profondeur.

Anciennes adresses#

Jusqu'à la v0.28.0, le site était une page unique, et tout se trouvait derrière un fragment de / (/#playground, /#ledger, liens de partage sous la forme /#s=…, intégrations sous la forme /?embed=1&… ; l'ancien nom d'onglet d'un lien d'intégration, tel que tab=fom, ouvre l'onglet du Studio qui l'a remplacé). tools/legacy-urls.json liste chaque adresse de ce genre qu'utilise du matériel publié et l'endroit où elle mène désormais ; la page d'accueil charge legacy-redirects.js, généré à partir de cette liste, pour y envoyer les visiteurs. Ajoutez un cas à la liste avant de retirer toute adresse.

Déploiement#

Le workflow GitHub Actions pages déploie une étiquette de version, et non main : release.yml le déclenche une fois qu'une version est publiée, et un déclenchement manuel redéploie une étiquette nommée. Il exécute build.sh, met en place web/ sans les tests, le script de construction, tools/, le manifeste et ce fichier, et publie le résultat sur GitHub Pages.