README updated

Author: VolksRat71

README.md

@@ -1,38 +1,93 @@
-# sv
+# React2Shell (CVE-2025-55182) Visualization
 
-Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
+An interactive educational visualization explaining the React2Shell vulnerability - a critical CVSS 10.0 remote code execution flaw in React Server Components.
 
-## Creating a project
+## What This Is
 
-If you're seeing this, you've probably already done this step. Congrats!
+A 5-step narrated walkthrough that explains:
 
-```sh
-# create a new project in the current directory
-npx sv create
+1. **Traditional SSR** - How server-side rendering works and the "JSON bottleneck" problem
+2. **RSC Streaming** - How React Server Components solve this with streaming
+3. **The Exploit** - How prototype pollution + gadget chains enable RCE
+4. **The Fix** - The one-line `hasOwnProperty` check that prevents the attack
+5. **Key Takeaways** - Lessons learned for secure architecture
 
-# create a new project in my-app
-npx sv create my-app
-```
+Each step features:
+- Synced audio narration (~5.5 minutes total)
+- Keyframe-driven animations timed to the narration
+- Video player controls (play/pause, seek, speed, captions)
+- Visual highlighting of key concepts
 
-## Developing
+## Tech Stack
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+- **SvelteKit** with Svelte 5 runes
+- **ElevenLabs** for AI voice generation
+- **OpenAI Whisper** for audio transcription & timestamp extraction
+- **TypeScript** throughout
+
+## Development
 
 ```sh
+npm install
 npm run dev
+```
+
+## Changing the Voice / Narration
+
+The narration system is designed to be easily swappable:
+
+### 1. Edit the script
+Scripts are in `scripts/`:
+- `ssr-narration.txt`
+- `rsc-narration.txt`
+- `exploit-narration.txt`
+- `fix-narration.txt`
+- `lessons-narration.txt`
+
+Use ElevenLabs audio tags like `[pause]`, `[short pause]`, `[long pause]` for timing.
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+### 2. Generate audio with ElevenLabs
+Upload the script to ElevenLabs and download the MP3.
+
+### 3. Place the audio file
+Drop the MP3 in `static/audio/` with the matching name (e.g., `ssr-narration.mp3`).
+
+### 4. Transcribe with Whisper
+```sh
+python scripts/transcribe.py ssr
+python scripts/transcribe.py rsc
+python scripts/transcribe.py exploit
+python scripts/transcribe.py fix
+python scripts/transcribe.py lessons
 ```
 
-## Building
+Options:
+- `--model small` - Use a larger Whisper model for better accuracy
+- Custom audio path: `python scripts/transcribe.py ssr ~/Downloads/new-voice.mp3`
+
+The script outputs JSON to `src/lib/data/` with word-level timestamps that drive the animations.
 
-To create a production version of your app:
+## How the Animation System Works
+
+1. **Whisper JSON** contains word-level timestamps
+2. **Trigger extraction** (`src/lib/utils/whisper-parser.ts`) finds key phrases and returns their timestamps
+3. **Keyframes** map timestamps to animation states
+4. **Timeline controller** (`src/lib/stores/timeline.svelte.ts`) syncs audio playback with animation state
+5. **Components** derive their visual state from `currentTime` using `getAnimationState()`
+
+## Building for Production
 
 ```sh
 npm run build
+npm run preview
 ```
 
-You can preview the production build with `npm run preview`.
+## Resources
+
+- [react2shell.com](https://react2shell.com/) - Original disclosure
+- [Wiz Deep Dive](https://www.wiz.io/blog/nextjs-cve-2025-55182-react2shell-deep-dive)
+- [Datadog Security Labs](https://securitylabs.datadoghq.com/articles/cve-2025-55182-react2shell-remote-code-execution-react-server-components/)
+
+## License
 
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+Educational purposes. Created for security awareness.