Maskinoversættelse, ikke gennemgået af en modersmålstalende. Engelsk er referencen.

Kom i gangRedigér på GitHubKilde: web/README.md

Webstedet kshana.dev

web/ er det træ, som GitHub Pages serverer som https://kshana.dev: siderne (index.html, missions.html, capabilities.html, evidence.html, developers.html, editions.html), dokumentationen under docs/ og Kshana Studio under studio/ (serveret på https://kshana.dev/studio/), appen, der kører motoren i browseren som WebAssembly (WASM) uden serverside-beregning og uden at noget uploades. Studio har to visninger af én motor: den enkle visning (studio/index.html, svaret først i almindelige ord) og den avancerede visning (studio/advanced/index.html, det fulde dashboard), som deler den enkle visnings motor, worker, moduler og data gennem <base href="../">.

Siden 0.35.0 har Studio fire visninger mere, hver sin egen side med <base href="../">, ingen søgeindeksering og en mappe med syntetiske eksempler, som dens test læser:

  • studio/trust/: den maritime tillidsvisning, en modtagertillidsscore for et fartøjs positionsstrøm, med et demospor i trust/demo/.
  • studio/training/: mandskabets træningsdebriefing, der afspiller syntetisk NMEA med en hændelse med jamming, drag-off, tidsspoofing eller replay (training/demo/).
  • studio/interference/: interferenskortet og ruteeksponeringen (interference/demo/).
  • studio/tools/: én side med værktøjskort med eksempler (tools/examples/, tools/samples/), herunder signerede bevispakker (#evidence), eksport til test-bench (#bench), compliance-kortlægning (#compliance), verifikation af Galileo OSNMA (#osnma) og AI-assistentkanalerne (#ai).

Hvor filerne kommer fra#

Tre slags filer ligger her, og de ændres på tre forskellige måder.

  1. Porterede filer. Siderne, docs/, css/, js/, assets/, webstedets data i data/ (land.json, search.json, series.json) og alt under studio/ skrives af web/tools/port_site.py ud fra en webstedsbuild og Studios kildekode. PORT-MANIFEST.json opregner hver enkelt med dens SHA-256-kontrolsum (Secure Hash Algorithm, 256-bit). Redigér dem ikke her: site.test.mjs fejler ved en manuel redigering. Ret kilden og kør porteringen igen:

    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

    Porteringen er deterministisk: en anden kørsel skriver intet, og --check afslutter med 1, hvis web/ ikke er det, porteringen ville skrive. Den fører webstedsbuildets crawlfiler uændret over (hver sides canonical-, social-card- og schema.org-tags, robots.txt, sitemap.xml, llms.txt, llms-full.txt), kontrollerer dem, skriver legacy-redirects.js, 404.html og videresendelsessiden på Studios gamle adresse (playground/index.html, til /studio/), og peger hver side mod de lokale skrifttyper og scriptbiblioteker (nedenfor).

  2. Filer, som web/ ejer. Det er kilder i sig selv, og porteringen rører dem aldrig:

    • capabilities.json er den strukturerede kilde til funktionskortene og standardgitteret. Redigér den, ikke HTML'en.
    • data/verification-matrix.json er genereret (cargo run --bin gen_validation_artifacts) og fastholdt af tests/verification_artifacts_doc_sync.rs; redigér den ikke i hånden. data/card-matrix-map.json, data/oracle-references.json og data/standards-matrix-map.json er håndvedligeholdte afbildninger, som den samme test kontrollerer mod den genererede matrix. Studios kopier under studio/data/ er disse filer, byte for byte.
    • og-card.svg, og-card.png og og-card.rendered-from.json er socialkortet (python3 tools/gen_og_card.py).
    • CNAME, .well-known/security.txt, favicon.svg.
    • fonts/ og vendor/: de skrifttypefiler og det scriptbibliotek, siderne bruger, hentet én gang af tools/fetch_third_party.py og indskrevet (se "Ingen tredjepartsanmodninger").
    • build.sh, smoke.mjs, site.test.mjs, legacy-urls.test.mjs og tools/.

  3. Build-output, git-ignoreret og produceret af build.sh: pkg/ (pakken wasm-pack, som også er det, npm-pakken bygges af), studio/pkg/ (den samme pakke, hvor Studio importerer den) og scenarios/ (hvert referencescenarie, på den adresse, det tidligere enkeltsides-websted serverede dem fra).

Byg og server lokalt#

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

Uden WASM-værktøjskæden lægger KSHANA_WASM_PKG=<a built pkg folder> ./web/build.sh en eksisterende pakke klar i stedet for at kompilere en. Pages-workflowet bruger aldrig det.

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

Hvert modul i studio/lib/ er ren logik med en tilhørende *.test.mjs; Studios DOM-drivere (Document Object Model, sidens elementtræ) er studio/app.js (den enkle visning) og studio/advanced.js (den avancerede visning). Kontinuerlig integration kører hver af disse som sit eget trin og fejler, hvis en testfil under web/ ikke har noget trin.

Ingen tredjepartsanmodninger#

kshana.dev serverer sine egne skrifttyper, typografiark og scripts. En side sender ingen anmodning til en skrifttypevært eller en scriptvært, så en besøgendes adresse ikke udleveres til en.

Webstedet og Studio er skrevet mod Google Fonts og en scriptvært. Porteringen erstatter hver sides Google Fonts-link med det tilsvarende typografiark i fonts/ (de samme @font-face-regler og de samme skrifttypefiler, hver delmængde, så tekst vises som før) og hver scriptvært-adresse med filen under vendor/. fonts/FONTS.json og vendor/VENDOR.json registrerer, hvor hver fil kom fra, og dens kontrolsum; skrifttyperne er under SIL Open Font License (fonts/OFL-*.txt) og three.js under MIT-licensen (vendor/three@…/LICENSE).

tools/fetch_third_party.py --from <site folder> --from <Studio folder> er det eneste trin, der bruger netværket. Kør det kun igen, når en side beder om et skrifttypesæt eller en biblioteksversion, som ikke er her: porteringen afviser og siger det. site.test.mjs fejler, hvis en porteret side, et typografiark eller et script navngiver en skrifttypevært eller indlæser noget fra en anden vært.

Siden 404#

GitHub Pages besvarer en manglende adresse med /404.html og status 404. Porteringen laver den side ud fra forsidens egen skal (navigation, fod, søgning) omkring en kort meddelelse med links til Home, Docs og Studio. Hver adresse i den er skrevet fra webstedets rod, fordi den serveres på enhver dybde.

Gamle adresser#

Indtil v0.28.0 var webstedet én side, og alt lå bag et fragment på / (/#playground, /#ledger, delingslinks som /#s=…, indlejringer som /?embed=1&…; et indlejringslinks gamle fanenavn, såsom tab=fom, åbner den Studio-fane, der afløste det). tools/legacy-urls.json opregner hver sådan adresse, som publiceret materiale bruger, og hvor den nu lander; forsiden indlæser legacy-redirects.js, genereret ud fra den liste, for at sende dem dertil. Tilføj et tilfælde til listen, før en adresse udfases.

Udrulning#

GitHub Actions-workflowet pages udruller et release-tag, ikke main: release.yml udløser det, når en udgivelse er publiceret, og en manuel udløsning udruller et navngivet tag igen. Det kører build.sh, stager web/ uden testene, build-scriptet, tools/, manifestet og denne fil og publicerer resultatet på GitHub Pages.