docs: expand README with detailed performance explanations

Add code examples showing zero-allocation getter pattern and explain
why the fork is faster (latest Rapier, optimized WASM boundary).

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

Author: alexandernanberg

README.md

@@ -26,13 +26,14 @@
 
 ## Fork Differences
 
-This is a fork of [@dimforge/rapier.js](https://github.com/dimforge/rapier.js) with:
+This is a fork of [@dimforge/rapier.js](https://github.com/dimforge/rapier.js) with performance improvements and modernized tooling.
 
-- Rapier 0.32 with glam math library
-- pnpm monorepo with tsdown bundler
-- Zero-allocation getters (optional target parameter)
-- Built-in benchmarks
-- Simplified package variants (4 per dimension)
+### Why This Fork?
+
+1. **Latest Rapier**: Rapier 0.32 (official npm is on 0.29)
+2. **Zero-allocation getters**: Optional `target` parameter avoids object creation in hot paths
+3. **Optimized WASM boundary**: Ray casting passes primitives directly instead of temporary WASM objects
+4. **Modern build**: pnpm monorepo, tsdown bundler, smaller bundles
 
 ### Benchmarks vs Official
 
@@ -46,11 +47,34 @@ Comparison against `@dimforge/rapier3d-compat@0.19.3` (3D, 1000 bodies):
 | body.translation()   | 73µs     | 210µs    | **2.9x**    |
 | body.rotation()      | 70µs     | 223µs    | **3.2x**    |
 
-Key improvements:
+### What Makes It Faster
+
+**Zero-allocation getters (3x faster)**
+
+The official package allocates a new object every call:
+
+```typescript
+// Official: allocates {x, y, z} every call
+for (const body of bodies) {
+  const pos = body.translation(); // new object
+}
+```
+
+This fork accepts an optional target to reuse:
+
+```typescript
+// Fork: zero allocations
+const pos = {x: 0, y: 0, z: 0};
+for (const body of bodies) {
+  body.translation(pos); // writes into existing object
+}
+```
+
+Supported: `translation()`, `rotation()`, `linvel()`, `angvel()`, `nextTranslation()`, `nextRotation()`, `localCom()`, `worldCom()`
+
+**Optimized ray casting (35% faster)**
 
-- **Getters**: 3x faster (zero-allocation optimization)
-- **Ray casting**: 35% faster (primitives passed directly to WASM)
-- **Body creation**: 7% faster
+Ray origin/direction passed as primitives directly to WASM, avoiding temporary `RawVector` allocations.
 
 Run `pnpm bench --official` to compare on your machine.