first commit

docs/foundation/bitpacker/bitpacker-game/src/prediction/index.md

@@ -0,0 +1,39 @@
+## Prediction
+
+**Path:** `src/prediction/`  
+**Exports:** `PositionPredictor`, `RotationPredictor`, motion math, Kalman filter, prediction algorithms
+
+### What it does
+
+Position and rotation prediction for game state extrapolation. Supports multiple algorithms from simple linear extrapolation to Kalman filtering.
+
+### Key Classes
+
+| Class | Description |
+|-------|-------------|
+| `PositionPredictor` | Predicts future positions from historical data |
+| `RotationPredictor` | Predicts future rotations from historical data |
+
+### Algorithms
+
+| Algorithm | Description |
+|-----------|-------------|
+| `linearPredict` | Constant velocity extrapolation |
+| `quadraticPredict` | Velocity + acceleration |
+| `cubicPredict` | Velocity + acceleration + jerk |
+| `hermitePredict` | Hermite spline extrapolation |
+| `catmullRomPredict` | Catmull-Rom spline extrapolation |
+| `verletPredict` | Physics-based Verlet integration |
+| `kalmanPredict` | Kalman filter prediction |
+
+### Adaptive Mode
+
+`PositionPredictor` with `algorithm: ADAPTIVE` automatically switches algorithms based on prediction error:
+
+- Error > 2× threshold → Kalman
+- Error > threshold → Verlet
+- Otherwise → Cubic
+
+### Depends on
+
+- `../types.js` — `Vector3`, `Rotation`, `PredictionOptions`, `KalmanState`