rust-wasm-geo

Rust / WASM geo

既定のスタックコンテキスト：tech-stack スキル。このスキルでは Rust/WASM geo のみを扱います。

適用する場面

• Turf または JS のジオメトリ処理が遅すぎる場合（まずプロファイリングしてください — メインスレッドのブロックが約 100ms を超える場合）
• OSM の解析、マップモデルの構築、等時間圏、空間インデックス、グラフルーティング
• 数千件のフィーチャー、ジオメトリ演算の繰り返し、大規模なポリゴンブーリアン演算
• wasm-pack クレート、wasm.ts 境界、Vite WASM プラグインを追加またはレビューする場合

プロトタイピング中、小規模な GeoJSON に対する単一フィーチャーの演算や、インタラクティブな編集フィードバックには Turf（JS）を使い続けてください。

Turf と Rust/WASM の比較

Turf（JS）を使い続ける場面	Rust/WASM を追加する場面
小規模な GeoJSON に対する単一フィーチャーの演算	数千件のフィーチャー、演算の繰り返し、グラフルーティング
インタラクティブな編集フィードバック	OSM の解析、マップモデルの構築、等時間圏、空間インデックス
プロトタイピング	メインスレッドのブロックが約 100ms を超える場合（まずプロファイリング）

大きな配列のジオメトリをまとめて処理する場合（ルーティング／OSM 以外）：独自実装の代わりに geoarrow-wasm を使ってください。

クレートの選択（クイックガイド）

必要なもの	クレート
ジオメトリ／GeoJSON	geo、geojson
空間インデックス	rstar
道路ルーティング	fast_paths
グラフアルゴリズム	petgraph
OSM → グラフ	osm-reader（a-b-street のフォーク）
トレースを道路にスナップ	route-snapper-graph
ポリゴンブーリアン演算	i_overlay（a-b-street/utils を参照）
等高線／等値線	contour
シリアライズされたマップモデル	bincode + serde
ベクターファイルの I/O	flatgeobuf、geozero

各クレートの使用上の注意と WASM 依存関係のバージョン：crates-and-packages.md。

プロジェクト構成

アプリごとに 1 つのクレートを作成し、計算内容が分かる名前を付けます（geo-isochrone、route-buffer など）。

app/
├── wasm/
│   └── geo-isochrone/          # Rust crate (wasm-pack output → pkg/)
│       ├── Cargo.toml
│       └── src/
│           ├── lib.rs          # #[wasm_bindgen] surface only
│           └── isochrone.rs    # pure geo logic
└── src/
    └── features/isochrone/
        ├── wasm.ts             # sole JS import of pkg — React never imports pkg directly
        └── useIsochrone.ts     # React hook / Query wrapper

• lib.rs = #[wasm_bindgen] エクスポート。内部モジュールには純粋なジオメトリロジックを配置します（WASM なしでテスト可能）。
• JS 境界： エクスポートを wasm.ts でラップします。GeoJSON 文字列または bincode の Uint8Array を渡し、JS オブジェクトを手作業で構築して渡さないでください。
• 状態の分離： 永続的な計算状態は Rust に、UI 状態は React（Zustand / URL / ローカルの useState）に保持します。

WASM スタック（Cargo）

Crate	役割
wasm-bindgen	JS ↔ Rust の境界
serde-wasm-bindgen	境界をまたぐシリアライズ／デシリアライズ
wasm-bindgen-futures	非同期エクスポート
console_error_panic_hook	開発者ツールで読みやすいパニックを表示
getrandom with features = ["js"]	ブラウザーでの乱数生成
web-time	WASM での時間

ビルド： wasm-pack（--target web）、vite-plugin-wasm、ターゲット wasm32-unknown-unknown。

参考セットアップ：a-b-street/ltn、a-b-street/15m、a-b-street/utils。

行き詰まったときのドキュメント： wasm-bindgen book、docs.rs の geo。

アプリの統合

アプリの種類	ガイド
Vite SPA（Start なし）	vite-spa-integration.md
TanStack Start	tanstack-start-integration.md

どちらの場合も、WASM は wasm.ts からのみ動的インポートしてください。サーバーで読み込まれる可能性のある共有モジュールで、.wasm をトップレベルから import しないでください。

絶対に守るべきルール

トピック	ルール
React のインポート	コンポーネント／フックは wasm.ts のみをインポートし、pkg/ や生の .wasm は決してインポートしないでください
境界の型	GeoJSON は string または bincode の Uint8Array とし、パース後に JS 側で Zod を使って検証してください
座標	WGS84。すべての API 境界で [lng, lat] を使用してください
サーバーモジュール	*.server.ts、サーバーローダー、createServerFn ハンドラーでは WASM を初期化しないでください
SSR	WASM はクライアントのみで実行し、ハイドレーション後に遅延初期化してください（ルートの ssr については Start ガイドを参照）
Turf のフォールバック	WASM が必要だとプロファイリングで確認されるまでは、小規模またはインタラクティブな処理経路で Turf を使い続けてください

関連スキル

トピック	スキル
Map React API、レイヤー、イベント	react-map-gl
ローダー、検索パラメーター、Query	tanstack-router-conventions
ルート SSR、Start のレイアウト、サーバー	tanstack-start-conventions
マップツール周辺のクライアント UI 状態	zustand-state-management
useEffect／マップリスナー	react-dev