build(web): 3D asset pipeline + three/r3f deps (foundation for 3D view)

Add three, @react-three/fiber, @react-three/drei (runtime) and gltf-transform /
gltfpack (dev) plus apps/web/scripts/build-3d-assets.sh, which compresses the
local Baía de Guanabara + celso_furtado source packs into web-ready GLBs
(meshopt geometry + WebP@1024 textures — no KTX2 transcoder needed under our
COOP/COEP). v1 subset = batimetria + ilhas + ponte + vessel (~21MB, down from
~640MB); topografia excluded (pathological per-tile textures). Generated GLBs are
gitignored — run the script once locally before using the 3D view.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -63,3 +63,6 @@ apps/web/public/wasm/*.js
 apps/web/public/wasm/*.wasm
 core/.wasm-stage/
 core/build-wasm/
+
+# 3D meshes (generated by apps/web/scripts/build-3d-assets.sh from local source packs)
+apps/web/public/assets/3d/**/*.glb

apps/web/package.json

@@ -14,6 +14,8 @@
     "test:e2e:ui": "playwright test --ui"
   },
   "dependencies": {
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.6.1",
     "@types/leaflet": "^1.9.21",
     "@ymir/types": "workspace:*",
     "leaflet": "^1.9.4",
@@ -21,9 +23,11 @@
     "react-dom": "^19.2.7",
     "react-leaflet": "^5.0.0",
     "react-router-dom": "^7.18.1",
+    "three": "^0.185.0",
     "zustand": "^5.0.0"
   },
   "devDependencies": {
+    "@gltf-transform/cli": "^4.4.0",
     "@playwright/test": "^1.61.1",
     "@sinclair/typebox": "^0.34.0",
     "@testing-library/jest-dom": "^6.9.1",
@@ -31,8 +35,10 @@
     "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
+    "@types/three": "^0.185.0",
     "@vitejs/plugin-react": "^4.3.0",
     "@vitest/coverage-v8": "^4.1.9",
+    "gltfpack": "^1.1.0",
     "jsdom": "^29.1.1",
     "typescript": "^5.8.0",
     "vite": "^6.3.0",

apps/web/scripts/build-3d-assets.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Compress the heavy source GLB meshes (Unity/FBX exports) into web-ready,
+# meshopt-compressed GLBs under apps/web/public/assets/3d/.
+#
+# The source packages (hundreds of MB) are NOT committed — point SRC_AREA /
+# SRC_VESSEL at the local download folders. Output GLBs are gitignored; run this
+# once per machine (or in CI) before using the 3D view.
+#
+# Usage:
+#   SRC_AREA=~/Downloads/baia_de_guanabara \
+#   SRC_VESSEL=~/Downloads/celso_furtado_l183_32 \
+#   bash apps/web/scripts/build-3d-assets.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WEB_DIR="$(dirname "$SCRIPT_DIR")"
+OUT_AREA="$WEB_DIR/public/assets/3d/baia_de_guanabara"
+OUT_VESSEL="$WEB_DIR/public/assets/3d/vessel"
+
+SRC_AREA="${SRC_AREA:-$HOME/Downloads/baia_de_guanabara}"
+SRC_VESSEL="${SRC_VESSEL:-$HOME/Downloads/celso_furtado_l183_32}"
+
+mkdir -p "$OUT_AREA" "$OUT_VESSEL"
+
+# Geometry → meshopt; textures → WebP @ ≤1024px (decodes natively in the browser,
+# so no KTX2 transcoder is needed under our COOP/COEP headers). Cuts the heavy
+# Unity/FBX exports ~10-20×. Area subset only — terminais_portos.glb (~440MB) is
+# intentionally excluded as too heavy for the web view.
+pack() {
+  echo "[3d] $1 → $2"
+  npx --no-install gltf-transform optimize "$1" "$2" \
+    --compress meshopt --texture-compress webp --texture-size 1024
+}
+
+pack "$SRC_AREA/batimetria_guanabara.glb"  "$OUT_AREA/batimetria.glb"   # bay floor
+pack "$SRC_AREA/ilhas.glb"                 "$OUT_AREA/ilhas.glb"        # islands
+pack "$SRC_AREA/ponte_rio_niteroi.glb"     "$OUT_AREA/ponte.glb"        # Rio-Niterói bridge
+# NOTE: topografia_guanabara.glb is excluded from v1 — 2159 sub-meshes with 2171
+# unique per-tile satellite textures don't merge and stay ~115MB even at 512px.
+# It needs offline texture-atlasing/retopo before it's web-viable.
+
+# Default vessel mesh (used for every vessel in v1).
+pack "$SRC_VESSEL/vessel_web.glb"          "$OUT_VESSEL/celso_furtado.glb"
+
+echo "[3d] done → $WEB_DIR/public/assets/3d"
+du -sh "$OUT_AREA" "$OUT_VESSEL"