1 files changed, 146 insertions, 0 deletions
diff --git a/PROTOTYPING.md b/PROTOTYPING.md
new file mode 100644
index 0000000..e220f9a
--- /dev/null
+++ b/PROTOTYPING.md
@@ -0,0 +1,146 @@
+# PixiJS Prototyping Framework
+
+A minimal PixiJS framework with core architecture patterns (DOM initialization, Service initialization, State management) for rapid prototyping.
+
+## Quick Start
+
+```bash
+npm run dev
+```
+
+Open browser to `http://localhost:5173/`
+
+## Architecture
+
+The framework follows a clean initialization pattern:
+
+1. **DOM Initialization** - Reference DOM elements
+2. **Renderer Initialization** - Set up PixiJS with WebGPU/WebGL
+3. **Services Initialization** - Start the update loop
+
+## Global Objects (Available in Console)
+
+- `window.PIXI` - Complete PixiJS namespace
+- `window.pixiApp` - PixiJS Application instance
+- `window.state` - StateManager instance (reactive state)
+- `window.log` - Logger function
+
+## Rapid Prototyping Examples
+
+### Example 1: Draw a Rectangle
+
+Open browser console:
+
+```javascript
+const graphics = new PIXI.Graphics();
+graphics.rect(100, 100, 200, 150);
+graphics.fill(0xff0000);
+pixiApp.stage.addChild(graphics);
+```
+
+### Example 2: Animated Sprite
+
+```javascript
+const graphics = new PIXI.Graphics();
+graphics.circle(0, 0, 50);
+graphics.fill(0x00ff00);
+pixiApp.stage.addChild(graphics);
+
+// Add to update loop in main.js:
+// graphics.x = Math.sin(state.state.time.current) * 200 + pixiApp.screen.width / 2;
+// graphics.y = pixiApp.screen.height / 2;
+```
+
+### Example 3: Using State System
+
+The framework includes a reactive state manager:
+
+```javascript
+// Listen to state changes
+state.on('time.current', ({ value }) => {
+    console.log('Time:', value);
+});
+
+// Modify state (triggers listeners)
+state.state.time.speed = 2.0; // Double speed
+
+// Toggle pause
+state.togglePause();
+```
+
+### Example 4: Register Input Actions
+
+```javascript
+// In main.js, add to setupControls():
+state.registerAction('myAction', () => {
+    log('Action triggered!');
+});
+
+state.mapKey('KeyP', 'myAction');
+```
+
+## Modifying the Update Loop
+
+Edit `/src/main.js` function `update()`:
+
+```javascript
+function update() {
+    state.incrementTime(0.016); // ~60fps increment
+    state.updateRealElapsed();
+    state.state.rendering.frameCounter++;
+
+    // YOUR PROTOTYPE CODE GOES HERE
+    // Example:
+    mySprite.rotation += 0.01;
+    myGraphics.x = Math.sin(state.state.time.current) * 100;
+}
+```
+
+## State Structure
+
+```javascript
+state.state = {
+    userPrefs: {
+        showGrid: true,
+        showMetrics: true,
+        theme: 'dark',
+        // ... persisted to localStorage
+    },
+
+    uiConfig: {
+        canvasWidth: number,
+        canvasHeight: number,
+        // ...
+    },
+
+    time: {
+        current: number,        // Increments every frame
+        realElapsed: number,    // Real seconds since start
+        speed: number,          // Time multiplier
+        isPaused: boolean,
+    },
+
+    rendering: {
+        rendererType: 'webgpu' | 'webgl',
+        frameCounter: number,
+    },
+
+    health: {
+        fps: number,
+        updateMs: number,
+        renderMs: number,
+    },
+}
+```
+
+## Tips
+
+1. **Use the console** - All major objects are exposed globally
+2. **Hot reload** - Vite will automatically reload on file changes
+3. **State persistence** - userPrefs automatically save to localStorage
+4. **Responsive** - Canvas automatically resizes with window
+5. **WebGPU fallback** - Automatically falls back to WebGL if WebGPU unavailable
+
+## Clean Slate
+
+The framework intentionally draws nothing by default. Start adding your PixiJS objects and see results immediately.