kshana.dev サイト

web/ は、GitHub Pages が https://kshana.dev として配信するツリーです。ページ（index.html、missions.html、capabilities.html、evidence.html、developers.html、editions.html）、docs/ 配下のドキュメント、studio/ 配下の Kshana Studio（https://kshana.dev/studio/ で配信）から成ります。Studio は、サーバー側の計算もアップロードもなしに、エンジンをブラウザー上で WebAssembly（WASM）として実行するアプリです。Studio には、一つのエンジンに対する二つのビューがあります。Simple ビュー（studio/index.html、答えをまず平易な言葉で示す）と Advanced ビュー（studio/advanced/index.html、フルダッシュボード）で、後者は <base href="../"> を通じて Simple ビューのエンジン、ワーカー、モジュール、データを共有します。

0.35.0 以降、Studio にはさらに四つのビューがあり、それぞれが <base href="../"> を備えた独立したページで、検索インデックスには登録されず、そのテストが読み込む合成サンプルのフォルダーを持ちます。

studio/trust/：船舶の信頼性ビュー。船舶の位置ストリームに対する受信機の信頼スコアで、trust/demo/ にデモ用の航跡があります。
studio/training/：乗組員訓練のデブリーフ。ジャミング、ドラッグオフ、時刻スプーフィング、リプレイのいずれかのイベントを含む合成 NMEA を再生します（training/demo/）。
studio/interference/：干渉マップと航路の曝露（interference/demo/）。
studio/tools/：例（tools/examples/、tools/samples/）を添えたツールカードを一つのページにまとめたもので、署名済みエビデンスパック（#evidence）、テスト bench のエクスポート（#bench）、compliance のマッピング（#compliance）、Galileo OSNMA の検証（#osnma）、AI アシスタントのチャネル（#ai）を含みます。

ファイルの出どころ#

ここには三種類のファイルがあり、それぞれ三通りの方法で変更されます。

ポートされるファイル。ページ、docs/、css/、js/、assets/、data/ のサイトデータ（land.json、search.json、series.json）、および studio/ 配下のすべては、サイトビルドと Studio のソースから web/tools/port_site.py によって書き出されます。PORT-MANIFEST.json は、そのすべてを SHA-256（Secure Hash Algorithm、256 ビット）のチェックサムとともに列挙します。ここで編集しないでください。手作業の編集があると site.test.mjs が失敗します。ソースを変更してポートを再実行してください。
```
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
```
ポートは決定的です。二回目の実行では何も書き出されず、web/ がポートの書き出す内容と異なる場合、--check は 1 で終了します。サイトビルドのクローラー用ファイル（各ページの canonical、ソーシャルカード、schema.org のタグ、robots.txt、sitemap.xml、llms.txt、llms-full.txt）はそのまま引き継いで検査し、legacy-redirects.js、404.html、Studio の旧アドレス（playground/index.html）から /studio/ への転送ページを書き出し、すべてのページをローカルのフォントとスクリプトライブラリ（後述）に向けます。
web/ が所有するファイル。これらはそれ自体がソースであり、ポートは決して触れません。
- capabilities.json は、機能カードと標準グリッドの構造化されたソースです。HTML ではなく、こちらを編集してください。
- data/verification-matrix.json は生成されるもの（cargo run --bin gen_validation_artifacts）で、tests/verification_artifacts_doc_sync.rs によって固定されています。手作業で編集しないでください。data/card-matrix-map.json、data/oracle-references.json、data/standards-matrix-map.json は手作業で維持するマッピングで、同じテストが生成されたマトリクスと照合します。studio/data/ 配下の Studio のコピーは、これらのファイルとバイト単位で同一です。
- og-card.svg、og-card.png、og-card.rendered-from.json はソーシャルカードです（python3 tools/gen_og_card.py）。
- CNAME, .well-known/security.txt, favicon.svg.
- fonts/ と vendor/：ページが使うフォントファイルとスクリプトライブラリで、tools/fetch_third_party.py が一度だけ取得してコミットしたものです（「サードパーティへのリクエストなし」を参照）。
- build.sh、smoke.mjs、site.test.mjs、legacy-urls.test.mjs、tools/。
ビルド成果物は git の管理対象外で、build.sh が生成します。pkg/（wasm-pack パッケージで、npm パッケージもこれから作られます）、studio/pkg/（Studio がインポートする場所にある同じパッケージ）、scenarios/（以前の単一ページのサイトが配信していたアドレスにある、すべての参照シナリオ）です。

ローカルでのビルドと配信#

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

WASM ツールチェーンがない場合、KSHANA_WASM_PKG=<a built pkg folder> ./web/build.sh はパッケージをコンパイルする代わりに、既存のパッケージを配置します。Pages のワークフローはこれを決して使いません。

テスト#

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

studio/lib/ の各モジュールは純粋なロジックで、対応する *.test.mjs があります。Studio の DOM（Document Object Model、ページの要素ツリー）ドライバーは、studio/app.js（Simple ビュー）と studio/advanced.js（Advanced ビュー）です。継続的インテグレーションはこれらをそれぞれ独立したステップとして実行し、web/ 配下にステップのないテストファイルがあれば失敗します。

サードパーティへのリクエストなし#

kshana.dev は、自前のフォント、スタイル、スクリプトを配信します。ページはフォントホストやスクリプトホストへリクエストを送らないため、訪問者のアドレスがそれらに渡ることはありません。

サイトと Studio は、Google Fonts とスクリプトホストを前提に書かれています。ポートは、各ページの Google Fonts のリンクを fonts/ 内の対応するスタイルシート（同じ @font-face ルールと同じフォントファイルで、すべてのサブセットを含むため、テキストは以前と同じように表示されます）に置き換え、各スクリプトホストのアドレスを vendor/ 配下のファイルに置き換えます。fonts/FONTS.json と vendor/VENDOR.json は、各ファイルの入手元とチェックサムを記録します。フォントは SIL Open Font License（fonts/OFL-*.txt）、three.js は MIT ライセンス（vendor/three@…/LICENSE）のもとにあります。

tools/fetch_third_party.py --from <site folder> --from <Studio folder> は、ネットワークを使う唯一のステップです。ページがここにないフォントセットやライブラリのバージョンを要求したときにだけ、再度実行してください。そのときはポートが拒否し、その旨を伝えます。site.test.mjs は、ポートされたページ、スタイルシート、スクリプトのいずれかがフォントホストを指定したり、他のホストから何かを読み込んだりすると失敗します。

404 ページ#

GitHub Pages は、存在しないアドレスに /404.html とステータス 404 で応答します。ポートは、そのページを、ホームページ自身のシェル（ナビゲーション、フッター、検索）の中に、ホーム、ドキュメント、Studio へのリンクを添えた短いメッセージを置いて作ります。どの深さでも配信されるため、その中のすべてのアドレスはサイトのルートから書かれています。

旧アドレス#

v0.28.0 まで、サイトは単一ページで、すべてが / のフラグメントの背後にありました（/#playground、/#ledger、/#s=… の形の共有リンク、/?embed=1&… の形の埋め込み。埋め込みリンクの古いタブ名、たとえば tab=fom は、それに代わった Studio のタブを開きます）。tools/legacy-urls.json は、公開済みの資料が使っているそのようなアドレスのすべてと、現在の移動先を列挙します。ホームページは、その一覧から生成された legacy-redirects.js を読み込み、そこへ転送します。アドレスを廃止する前に、必ず一覧にケースを追加してください。

デプロイ#

pages の GitHub Actions ワークフローは、main ではなくリリースタグをデプロイします。リリースの公開後に release.yml がこれを起動し、手動での起動では指定したタグを再デプロイします。build.sh を実行し、テスト、ビルドスクリプト、tools/、マニフェスト、このファイルを除いて web/ を配置し、結果を GitHub Pages に公開します。