feat: initial commit with M1-M4 implementation

docs/specs/2026-05-08-physics-dynamics-design.md

@@ -0,0 +1,31 @@
+# Design: Physics & Puck Dynamics (M2)
+
+## Goal
+Implement basic physical properties for the puck to make movement feel natural: gradual slowing down (friction) and energy loss upon hitting boundaries (restitution).
+
+## Architecture
+The physics logic will be integrated into the `World.Update` loop. Constants for physical properties will be defined to allow easy tuning of the game feel.
+
+## Implementation Details
+
+### 1. Physical Constants
+The following constants will be introduced:
+- `PuckFriction`: Multiplier applied to velocity every frame (e.g., `0.99`).
+- `PuckRestitution`: Multiplier applied to velocity upon boundary collision (e.g., `0.8`).
+- `StopThreshold`: Minimum velocity magnitude below which the puck is forced to a complete stop (e.g., `0.1`).
+
+### 2. Movement Logic (World.Update)
+The update loop for the puck will follow these steps:
+1. **Apply Friction**: `velocity = velocity * PuckFriction`.
+2. **Stop Check**: If `length(velocity) < StopThreshold`, then `velocity = (0, 0)`.
+3. **Position Update**: `position = position + velocity`.
+4. **Boundary Collision**:
+    - If the puck hits a boundary (considering its radius):
+        - Invert the velocity component perpendicular to the boundary.
+        - Multiply the resulting velocity by `PuckRestitution`.
+        - **Correction**: Snap the puck's position to be exactly on the boundary edge to prevent it from getting stuck inside the wall.
+
+## Success Criteria
+- The puck gradually slows down and eventually stops.
+- The puck loses speed after bouncing off the walls.
+- The puck does not get stuck in the boundaries.