docs: add Docusaurus documentation site (#185)

* docs: add Docusaurus documentation site with Lichtblick alignment

- Switch from MkDocs to Docusaurus to align with Lichtblick docs framework
- Add 10 documentation pages: home, getting started, panel settings,
  architecture overview, converter pipeline, caching, features,
  frame transforms, lanes/logical lanes reference, contributing
- Reference Lichtblick documentation for shared concepts (extensions,
  message converters, 3D panel) instead of re-explaining them
- Add GitHub Actions workflow for Pages deployment
- Migrate existing docs/lanes.md and docs/logical-lanes.md to
  docs/reference/ with corrected image paths
- Website lives in website/ with isolated package.json (no impact
  on extension dependencies)

* docs: fix inaccuracies found during audit

- Fix broken URL for asam-osi-utilities convert_osi2mcap.cpp (moved to cpp/examples/)
- Move STOP-only admonition from Traffic Lights to Road Markings section
- Clarify BB Center → Rear Axle transform is conditional on bbcenter_to_rear
- Fix NONDRIVING lane color to match exact source value (111/255, 91/255)
---------

Signed-off-by: jdsika <carlo.van-driesten@bmw.de>

Author: jdsika

.github/workflows/docs.yaml

@@ -0,0 +1,52 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "website/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        working-directory: website
+        run: npm install
+
+      - name: Build documentation
+        working-directory: website
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: website/build
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -117,3 +117,7 @@ dist
 
 # Playground
 .playground/
+
+# Docusaurus
+website/build/
+website/.docusaurus/

docs/architecture/caching.md

@@ -0,0 +1,98 @@
+---
+sidebar_position: 3
+---
+
+# Caching
+
+The converter uses a multi-layer caching system to avoid redundant work across frames. This is critical for performance — lane geometry and 3D models rarely change between frames but are expensive to rebuild.
+
+## Cache layers
+
+### Frame cache
+
+**Purpose:** Skip entire conversion if the same message object arrives again with the same config.
+
+| Property | Value |
+|----------|-------|
+| Structure | `Map<configSignature, WeakMap<GroundTruth, PartialSceneEntity[]>>` |
+| Key | Config signature (outer), message object reference (inner) |
+| Hit condition | Same config + same message object identity |
+| Invalidation | Outer map entry cleared when config signature changes |
+
+The `WeakMap` allows garbage collection of message objects no longer referenced by the runtime.
+
+### Lane boundary cache
+
+**Purpose:** Reuse rendered lane boundary entities when the set of boundaries hasn't changed.
+
+| Property | Value |
+|----------|-------|
+| Structure | `Map<string, PartialSceneEntity[]>` |
+| Key | Hash of all `lane_boundary[].id` values |
+| Hit condition | Same set of boundary IDs (regardless of data changes) |
+| Invalidation | Cleared on config change or when `caching` is disabled |
+
+### Lane cache
+
+**Purpose:** Reuse rendered lane entities when both lanes and their referenced boundaries are unchanged.
+
+| Property | Value |
+|----------|-------|
+| Structure | `Map<string, PartialSceneEntity[]>` |
+| Key | Hash of all `lane[].id` values |
+| Hit condition | Boundary cache was hit **and** same set of lane IDs |
+| Invalidation | Cleared on config change; depends on boundary cache state |
+
+:::note[Cache dependency]
+
+The lane cache is only checked if the boundary cache was hit. This ensures coherence — if boundaries changed, lanes must be rebuilt even if their IDs are the same.
+
+:::
+
+### Logical lane boundary / lane caches
+
+Same pattern as physical lane caches, for `LogicalLaneBoundary` and `LogicalLane` entities.
+
+### Model cache
+
+**Purpose:** Reuse loaded 3D model primitives across frames.
+
+| Property | Value |
+|----------|-------|
+| Structure | `Map<string, ModelPrimitive>` |
+| Key | `defaultModelPath + model_reference` (full file path) |
+| Hit condition | Same model path |
+| Invalidation | Cleared on config change |
+
+## Invalidation triggers
+
+All caches are cleared when:
+
+- Panel settings change (detected by comparing JSON-stringified config signatures)
+- The `caching` panel setting is `false` (geometry caches are bypassed entirely)
+
+## Cache flow diagram
+
+```
+New frame arrives
+    │
+    ├── Config changed? → Clear ALL caches
+    │
+    ├── Frame cache hit? → Return cached entities (skip everything)
+    │
+    ├── Boundary IDs unchanged?
+    │       ├── Yes → Reuse boundary entities
+    │       │         └── Lane IDs unchanged? → Reuse lane entities
+    │       └── No  → Rebuild boundaries and lanes
+    │
+    ├── Build remaining entities (moving objects, signs, etc.)
+    │
+    └── Update all caches
+```
+
+## Performance characteristics
+
+- **Best case** (frame cache hit): O(1) — returns cached array directly
+- **Static scene** (boundary/lane cache hits): Only moving objects, signs, and lights are rebuilt
+- **Config change**: Full rebuild of all entities (unavoidable)
+- **Typical frame**: Moving objects rebuilt (they change position), geometry reused from cache

docs/architecture/converter-pipeline.md

@@ -0,0 +1,96 @@
+---
+sidebar_position: 2
+---
+
+# Converter Pipeline
+
+This page describes the end-to-end conversion flow for `osi3.GroundTruth → foxglove.SceneUpdate`, the primary converter. For general information about message converters, see the [Lichtblick message converter guide](https://lichtblick-suite.github.io/docs/guides/create-message-converter).
+
+## Pipeline stages
+
+### 1. Configuration
+
+The converter reads panel settings from `event.topicConfig` (typed as `GroundTruthPanelSettings`). If no config is provided, it falls back to `DEFAULT_CONFIG`.
+
+A **config signature** (JSON-stringified config) is computed. If the signature differs from the previous frame, all caches are invalidated.
+
+### 2. Host vehicle resolution
+
+The host vehicle is identified by `message.host_vehicle_id.value`. If absent, a fallback from the SensorView wrapper is used. Warnings are emitted via `emitAlert()` for:
+
+- Missing host vehicle ID (both sources)
+- Host vehicle ID not found in `moving_object` array
+- Divergence between GroundTruth and SensorView host vehicle IDs
+
+### 3. Frame cache check
+
+If caching is enabled, the converter checks a `WeakMap<GroundTruth, entities>` keyed by config signature. If the exact same message object was already converted with the same config, the cached result is returned immediately.
+
+### 4. Deletion detection
+
+For each entity type, the converter compares current-frame entity IDs against a stored `Set<number>` from the previous frame. Missing IDs generate `SceneEntityDeletion` entries with the current timestamp.
+
+### 5. Entity building
+
+Entities are built by feature modules in this order:
+
+| Step | Feature | Condition | Builder |
+|------|---------|-----------|---------|
+| 1 | Moving objects | Always | `buildMovingObjectEntity()` |
+| 2 | Stationary objects | Always | `buildStationaryObjectEntity()` |
+| 3 | Traffic signs | Always | `buildTrafficSignEntity()` |
+| 4 | Traffic lights | Always | `buildTrafficLightEntity()` |
+| 5 | Road markings | Always (STOP only) | `buildRoadMarkingEntity()` |
+| 6 | Lane boundaries | `showPhysicalLanes` | `buildLaneBoundaryEntity()` |
+| 7 | Lanes | `showPhysicalLanes` | `buildLaneEntity()` |
+| 8 | Logical lane boundaries | `showLogicalLanes` | `buildLogicalLaneBoundaryEntity()` |
+| 9 | Logical lanes | `showLogicalLanes` | `buildLogicalLaneEntity()` |
+| 10 | Reference lines | `showReferenceLines` | `buildReferenceLineEntity()` |
+
+### 6. Geometry cache reuse
+
+Lane and boundary entities are expensive to rebuild. The converter uses geometry-aware caching:
+
+```
+Compute hash of lane_boundary IDs
+  → If cached, reuse lane boundary entities (skip rebuild)
+  → If boundaries unchanged, check lane cache too
+  → Same logic for logical lanes/boundaries
+```
+
+See [Caching](caching.md) for details.
+
+### 7. State update
+
+After building entities:
+
+- Update `previousXyzIds` sets for next frame's deletion detection
+- Store current config and config signature
+- Populate frame cache and geometry caches
+
+### 8. Return
+
+```typescript
+{
+  deletions: SceneEntityDeletion[],  // Entities removed since last frame
+  entities: SceneEntity[]            // All current-frame entities
+}
+```
+
+## Error handling
+
+The entire conversion is wrapped in `try/catch`. On failure:
+
+- Error is logged to `console.error`
+- An alert is emitted with `severity: "error"`
+- An empty `SceneUpdate` (no entities) is returned — deletions are still applied
+- Exceptions never propagate to the Lichtblick runtime
+
+## Feature builder pattern
+
+Each feature module exports:
+
+- `build*Entity()` — Creates a `PartialSceneEntity` with Foxglove primitives (cubes, models, triangles, arrows)
+- `build*Metadata()` — Creates `KeyValuePair[]` metadata for panel displays
+
+Builders receive the OSI entity cast as `DeepRequired<T>` (from `ts-essentials`), which satisfies TypeScript but does **not** validate field presence at runtime.

docs/architecture/features.md

@@ -0,0 +1,103 @@
+---
+sidebar_position: 4
+---
+
+# Features
+
+Each feature module in `src/features/` is responsible for converting one OSI entity type into [Foxglove scene primitives](https://lichtblick-suite.github.io/docs/docs/visualization/message-schemas).
+
+## Moving objects
+
+**Module:** `src/features/movingobjects/`
+**OSI type:** `MovingObject`
+**Primitives:** CubePrimitive, ModelPrimitive, ArrowPrimitive
+
+Renders vehicles, pedestrians, and animals. The host vehicle is colored blue; others are colored by type:
+
+| Type | Color |
+|------|-------|
+| VEHICLE | Red |
+| PEDESTRIAN | Yellow |
+| ANIMAL | Green |
+| HOST_OBJECT | Blue |
+| UNKNOWN | Gray |
+| OTHER | Cyan |
+
+Includes optional 3D model rendering (when `show3dModels` is enabled) and light state visualization for vehicles (brake lights, indicators).
+
+## Stationary objects
+
+**Module:** `src/features/stationaryobjects/`
+**OSI type:** `StationaryObject`
+**Primitives:** CubePrimitive, ModelPrimitive, ArrowPrimitive
+
+Renders static scene objects with bounding boxes. Colors are determined by the object's `classification.color` field. Supports 3D model loading.
+
+## Traffic lights
+
+**Module:** `src/features/trafficlights/`
+**OSI type:** `TrafficLight`
+**Primitives:** ModelPrimitive (embedded glTF with texture), CubePrimitive, ArrowPrimitive
+
+Renders traffic lights using built-in 3D models with dynamically colored textures based on the light state (red, yellow, green). Includes mode handling (standard, flashing, counting).
+
+## Traffic signs
+
+**Module:** `src/features/trafficsigns/`
+**OSI type:** `TrafficSign` (main + supplementary)
+**Primitives:** ModelPrimitive
+
+Renders traffic signs using dynamically loaded PNG textures. Textures are preloaded at extension activation via `preloadDynamicTextures()` and cached for reuse.
+
+## Road markings
+
+**Module:** `src/features/roadmarkings/`
+**OSI type:** `RoadMarking`
+**Primitives:** CubePrimitive
+
+Renders road markings (currently STOP markings only) as oriented cubes. Position is centered on `base.position`, orientation applied from `base.orientation`, and dimensions follow the OSI road marking coordinate system where the x-axis is the surface normal.
+
+:::note
+
+Only road markings with `traffic_main_sign_type == STOP` are currently rendered. Other marking types are filtered out.
+
+:::
+
+## Lanes
+
+**Module:** `src/features/lanes/`
+**OSI type:** `Lane`, `LaneBoundary`
+**Primitives:** TriangleListPrimitive
+
+Renders lane surfaces and lane boundaries as triangle meshes. Lane boundaries are extruded from point lists with width and optional dashing. Lanes are filled surfaces connecting their left and right boundaries.
+
+Lane colors vary by type:
+
+| Type | Color |
+|------|-------|
+| DRIVING | Cyan |
+| INTERSECTION | Red |
+| NONDRIVING | Coral |
+| UNKNOWN / OTHER | Gray |
+
+The host vehicle's lane is highlighted in orange when identifiable.
+
+See [Lanes Reference](../reference/lanes.md) for detailed color tables.
+
+## Logical lanes
+
+**Module:** `src/features/logicallanes/`
+**OSI type:** `LogicalLane`, `LogicalLaneBoundary`
+**Primitives:** TriangleListPrimitive
+
+Same rendering approach as physical lanes but with distinct colors (green surfaces, red boundaries) and a slight height offset (`0.02m`) to visually separate them from physical lanes.
+
+See [Logical Lanes Reference](../reference/logical-lanes.md) for details.
+
+## Reference lines
+
+**Module:** `src/features/referenceline/`
+**OSI type:** `ReferenceLine`
+**Primitives:** TriangleListPrimitive
+
+Renders reference lines as green line strips with a configurable width (`0.2m`).