improved prompting/UX

agents.md

@@ -1,88 +0,0 @@
-# VibeGame Engine Context
-
-You are a VibeGame specialist. VibeGame is a 3D game engine with declarative XML syntax and ECS architecture. Your role is to help users create games efficiently using VibeGame's declarative approach.
-
-## Core Architecture
-
-**ECS Pattern**: Entities (IDs) + Components (data) + Systems (logic)
-**Declarative XML**: Game entities defined in `<world>` tags
-**Auto-Creation**: Engine provides player, camera, lighting by default
-
-## Essential Syntax
-
-```xml
-<world canvas="#game-canvas" sky="#87ceeb">
-  <!-- REQUIRED: Ground to prevent falling -->
-  <static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"></static-part>
-
-  <!-- Physics objects -->
-  <dynamic-part pos="0 5 0" shape="sphere" size="1" color="#ff0000"></dynamic-part>
-  <kinematic-part pos="5 2 0" shape="box" size="3 0.5 3" color="#0000ff">
-    <tween target="body.pos-y" from="2" to="5" duration="3" loop="ping-pong"></tween>
-  </kinematic-part>
-</world>
-```
-
-## Key Recipes & Components
-
-- `<static-part>` - Immovable (grounds, walls)
-- `<dynamic-part>` - Gravity-affected (balls, crates)
-- `<kinematic-part>` - Script-controlled (moving platforms)
-- `<player>`, `<camera>` - Auto-created if missing
-- `<entity>` - Base with custom components
-
-## Critical Rules
-
-⚠️ **Physics Override**: Body position overrides transform position. Always use `pos` on physics entities.
-
-```xml
-<!-- ✅ CORRECT -->
-<dynamic-part pos="0 5 0" shape="sphere"></dynamic-part>
-
-<!-- ❌ WRONG: Transform ignored -->
-<entity transform="pos: 0 5 0" body collider></entity>
-```
-
-## Component Syntax
-
-```xml
-<!-- Bare attributes = defaults -->
-<entity transform body collider renderer></entity>
-
-<!-- Override properties -->
-<entity transform="pos: 0 5 0" body="type: dynamic; mass: 10" collider renderer></entity>
-```
-
-**Shorthands**: `pos`, `color`, `size` auto-expand to matching component properties.
-
-## Development Commands
-
-- `bun dev` - Start development server
-- `bun run build` - Production build
-- `bun run check` - TypeScript validation
-- `bun test` - Run tests
-
-## Features Available
-
-✅ Physics (Rapier), rendering (Three.js), input, tweening, player controller, orbital camera, collision detection, respawn, post-processing
-
-❌ Audio, multiplayer, save/load, inventory, AI, particles, custom shaders
-
-## Documentation Access
-
-**For detailed information**: Use Context7 to fetch comprehensive docs:
-1. `mcp__context7__resolve-library-id` with "/dylanebert/vibegame"
-2. `mcp__context7__get-library-docs` with resolved ID
-
-**Quick Reference**: Shapes (`box`, `sphere`, `cylinder`, `capsule`), Physics (`static`, `dynamic`, `kinematic`), Easing functions, Loop modes (`once`, `loop`, `ping-pong`)
-
-## Best Practices
-
-1. Always include ground platforms
-2. Use recipes over raw entities
-3. Leverage auto-creation defaults
-4. Set positions on physics bodies, not transforms
-5. Query Context7 for detailed API references
-6. Test incrementally
-
-This provides foundational VibeGame knowledge. Use Context7 for comprehensive documentation and examples.

bun.lock

@@ -11,13 +11,12 @@
         "@langchain/mcp-adapters": "^0.6.0",
         "@modelcontextprotocol/sdk": "^0.6.0",
         "@modelcontextprotocol/server-filesystem": "^0.6.2",
-        "@types/marked": "^6.0.0",
         "@types/node": "^24.3.3",
         "gsap": "^3.13.0",
-        "marked": "^16.2.1",
+        "htmlparser2": "^10.0.0",
         "monaco-editor": "^0.50.0",
         "svelte-splitpanes": "^8.0.5",
-        "vibegame": "^0.1.7",
+        "vibegame": "^0.1.9",
         "zod": "^4.1.8",
       },
       "devDependencies": {
@@ -117,7 +116,7 @@
 
     "@huggingface/jinja": ["@huggingface/jinja@0.5.1", "", {}, "sha512-yUZLld4lrM9iFxHCwFQ7D1HW2MWMwSbeB7WzWqFYDWK+rEb+WldkLdAJxUPOmgICMHZLzZGVcVjFh3w/YGubng=="],
 
-    "@huggingface/tasks": ["@huggingface/tasks@0.19.45", "", {}, "sha512-lM3QOgbfkGZ5gAZOYWOmzMM6BbKcXOIHjgnUAoymTdZEcEcGSr0vy/LWGEiK+vBXC4vU+sCT+WNoA/JZ8TEWdA=="],
+    "@huggingface/tasks": ["@huggingface/tasks@0.19.46", "", {}, "sha512-c6F/r7zRQjmyo6Ji8c2TUbdeeu6WAdZxYLRd+G7Xxvfbadi6iDwk2szt/oinC5v5Ljyc2sjzesaqGB6hLWy/DA=="],
 
     "@humanfs/core": ["@humanfs/core@0.19.1", "", {}, "sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA=="],
 
@@ -217,8 +216,6 @@
 
     "@types/json5": ["@types/json5@0.0.29", "", {}, "sha512-dRLjCWHYg4oaA77cxO64oO+7JwCwnIzkZPdrrC71jQmQtlhM556pwKo5bUzqvZndkVbeFLIIi+9TC40JNF5hNQ=="],
 
-    "@types/marked": ["@types/marked@6.0.0", "", { "dependencies": { "marked": "*" } }, "sha512-jmjpa4BwUsmhxcfsgUit/7A9KbrC48Q0q8KvnY107ogcjGgTFDlIL3RpihNpx2Mu1hM4mdFQjoVc4O6JoGKHsA=="],
-
     "@types/node": ["@types/node@24.5.0", "", { "dependencies": { "undici-types": "~7.12.0" } }, "sha512-y1dMvuvJspJiPSDZUQ+WMBvF7dpnEqN4x9DDC9ie5Fs/HUZJA3wFp7EhHoVaKX/iI0cRoECV8X2jL8zi0xrHCg=="],
 
     "@types/pug": ["@types/pug@2.0.10", "", {}, "sha512-Sk/uYFOBAB7mb74XcpizmH0KOR2Pv3D2Hmrh1Dmy5BmK3MpdSa5kqZcg6EKBdklU0bFXX9gCfzvpnyUehrPIuA=="],
@@ -373,6 +370,14 @@
 
     "doctrine": ["doctrine@2.1.0", "", { "dependencies": { "esutils": "^2.0.2" } }, "sha512-35mSku4ZXK0vfCuHEDAwt55dg2jNajHZ1odvF+8SSr82EsZY4QmXfuWso8oEd8zRhVObSN18aM0CjSdoBX7zIw=="],
 
+    "dom-serializer": ["dom-serializer@2.0.0", "", { "dependencies": { "domelementtype": "^2.3.0", "domhandler": "^5.0.2", "entities": "^4.2.0" } }, "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg=="],
+
+    "domelementtype": ["domelementtype@2.3.0", "", {}, "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw=="],
+
+    "domhandler": ["domhandler@5.0.3", "", { "dependencies": { "domelementtype": "^2.3.0" } }, "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w=="],
+
+    "domutils": ["domutils@3.2.2", "", { "dependencies": { "dom-serializer": "^2.0.0", "domelementtype": "^2.3.0", "domhandler": "^5.0.3" } }, "sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw=="],
+
     "dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
 
     "eastasianwidth": ["eastasianwidth@0.2.0", "", {}, "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA=="],
@@ -383,6 +388,8 @@
 
     "encodeurl": ["encodeurl@2.0.0", "", {}, "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg=="],
 
+    "entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
+
     "es-abstract": ["es-abstract@1.24.0", "", { "dependencies": { "array-buffer-byte-length": "^1.0.2", "arraybuffer.prototype.slice": "^1.0.4", "available-typed-arrays": "^1.0.7", "call-bind": "^1.0.8", "call-bound": "^1.0.4", "data-view-buffer": "^1.0.2", "data-view-byte-length": "^1.0.2", "data-view-byte-offset": "^1.0.1", "es-define-property": "^1.0.1", "es-errors": "^1.3.0", "es-object-atoms": "^1.1.1", "es-set-tostringtag": "^2.1.0", "es-to-primitive": "^1.3.0", "function.prototype.name": "^1.1.8", "get-intrinsic": "^1.3.0", "get-proto": "^1.0.1", "get-symbol-description": "^1.1.0", "globalthis": "^1.0.4", "gopd": "^1.2.0", "has-property-descriptors": "^1.0.2", "has-proto": "^1.2.0", "has-symbols": "^1.1.0", "hasown": "^2.0.2", "internal-slot": "^1.1.0", "is-array-buffer": "^3.0.5", "is-callable": "^1.2.7", "is-data-view": "^1.0.2", "is-negative-zero": "^2.0.3", "is-regex": "^1.2.1", "is-set": "^2.0.3", "is-shared-array-buffer": "^1.0.4", "is-string": "^1.1.1", "is-typed-array": "^1.1.15", "is-weakref": "^1.1.1", "math-intrinsics": "^1.1.0", "object-inspect": "^1.13.4", "object-keys": "^1.1.1", "object.assign": "^4.1.7", "own-keys": "^1.0.1", "regexp.prototype.flags": "^1.5.4", "safe-array-concat": "^1.1.3", "safe-push-apply": "^1.0.0", "safe-regex-test": "^1.1.0", "set-proto": "^1.0.0", "stop-iteration-iterator": "^1.1.0", "string.prototype.trim": "^1.2.10", "string.prototype.trimend": "^1.0.9", "string.prototype.trimstart": "^1.0.8", "typed-array-buffer": "^1.0.3", "typed-array-byte-length": "^1.0.3", "typed-array-byte-offset": "^1.0.4", "typed-array-length": "^1.0.7", "unbox-primitive": "^1.1.0", "which-typed-array": "^1.1.19" } }, "sha512-WSzPgsdLtTcQwm4CROfS5ju2Wa1QQcVeT37jFjYzdFz1r9ahadC8B8/a4qxJxM+09F18iumCdRmlr96ZYkQvEg=="],
 
     "es-define-property": ["es-define-property@1.0.1", "", {}, "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g=="],
@@ -529,6 +536,8 @@
 
     "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
 
+    "htmlparser2": ["htmlparser2@10.0.0", "", { "dependencies": { "domelementtype": "^2.3.0", "domhandler": "^5.0.3", "domutils": "^3.2.1", "entities": "^6.0.0" } }, "sha512-TwAZM+zE5Tq3lrEHvOlvwgj1XLWQCtaaibSN11Q+gGBAS7Y1uZSWwXXRe4iF6OXnaq1riyQAPFOBtYc77Mxq0g=="],
+
     "http-errors": ["http-errors@2.0.0", "", { "dependencies": { "depd": "2.0.0", "inherits": "2.0.4", "setprototypeof": "1.2.0", "statuses": "2.0.1", "toidentifier": "1.0.1" } }, "sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ=="],
 
     "iconv-lite": ["iconv-lite@0.7.0", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-cf6L2Ds3h57VVmkZe+Pn+5APsT7FpqJtEhhieDCvrE2MK5Qk9MyffgQyuxQTm6BChfeZNtcOLHp9IcWRVcIcBQ=="],
@@ -641,8 +650,6 @@
 
     "magic-string": ["magic-string@0.30.19", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.5" } }, "sha512-2N21sPY9Ws53PZvsEpVtNuSW+ScYbQdp4b9qUaL+9QkHUrGFKo56Lg9Emg5s9V/qrtNBmiR01sYhUOwu3H+VOw=="],
 
-    "marked": ["marked@16.3.0", "", { "bin": { "marked": "bin/marked.js" } }, "sha512-K3UxuKu6l6bmA5FUwYho8CfJBlsUWAooKtdGgMcERSpF7gcBUrCGsLH7wDaaNOzwq18JzSUDyoEb/YsrqMac3w=="],
-
     "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
 
     "mdn-data": ["mdn-data@2.0.30", "", {}, "sha512-GaqWWShW4kv/G9IEucWScBx9G1/vsFZZJUO+tD26M8J8z3Kw5RDQjaoZe03YAClgeS/SWPOcb4nkFBTEi5DUEA=="],
@@ -915,7 +922,7 @@
 
     "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
 
-    "vibegame": ["vibegame@0.1.7", "", { "dependencies": { "@dimforge/rapier3d-compat": "^0.18.2", "gsap": "^3.13.0", "postprocessing": "^6.37.8", "zod": "^4.1.5" }, "peerDependencies": { "bitecs": ">=0.3.40", "three": ">=0.170.0" } }, "sha512-KFzNGi+EnlEWt4R3QKPN5jVJhkgBgMg443Qq3muzSjfrp+GJ1fsHIB8ovYylRFHg8+9P3kSlWmiQ6PlDiZ8msQ=="],
+    "vibegame": ["vibegame@0.1.9", "", { "dependencies": { "@dimforge/rapier3d-compat": "^0.18.2", "gsap": "^3.13.0", "postprocessing": "^6.37.8", "zod": "^4.1.5" }, "peerDependencies": { "bitecs": ">=0.3.40", "three": ">=0.170.0" } }, "sha512-f83vO9BSuG6IjwI0n6xsPYwTg9ApEBmdQBTebf5UT/Si6lgLdX6EElU8CUORb0147IXyyxk5GXzJzLpF9S24NQ=="],
 
     "vite": ["vite@5.4.20", "", { "dependencies": { "esbuild": "^0.21.3", "postcss": "^8.4.43", "rollup": "^4.20.0" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^18.0.0 || >=20.0.0", "less": "*", "lightningcss": "^1.21.0", "sass": "*", "sass-embedded": "*", "stylus": "*", "sugarss": "*", "terser": "^5.4.0" }, "optionalPeers": ["@types/node", "less", "lightningcss", "sass", "sass-embedded", "stylus", "sugarss", "terser"], "bin": { "vite": "bin/vite.js" } }, "sha512-j3lYzGC3P+B5Yfy/pfKNgVEg4+UtcIJcVRt2cDjIOmhLourAqPqf8P7acgxeiSgUB7E3p2P8/3gNIgDLpwzs4g=="],
 
@@ -979,6 +986,8 @@
 
     "chokidar/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
 
+    "dom-serializer/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
+
     "eslint/ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],
 
     "eslint-import-resolver-node/debug": ["debug@3.2.7", "", { "dependencies": { "ms": "^2.1.1" } }, "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ=="],

layers/structure.md

@@ -54,7 +54,7 @@ vibegame/
 ├── tsconfig.json      # TypeScript configuration
 ├── vite.config.ts     # Vite + Svelte + VibeGame config
 ├── bun.lock          # Dependency lock file
-├── agents.md          # VibeGame documentation
+├── llms.txt          # VibeGame documentation
 └── README.md
 ```
 

llms.txt

@@ -0,0 +1,2430 @@
+# VibeGame Engine
+
+A 3D game engine with declarative XML syntax and ECS architecture. Start playing immediately with automatic player, camera, and lighting - just add a ground to prevent falling.
+
+## Core Architecture
+
+### ECS (Entity Component System)
+- **Entities**: Just numbers (IDs), no data or behavior
+- **Components**: Pure data containers (position, health, color)
+- **Systems**: Functions that process entities with specific components
+- **Queries**: Find entities with specific component combinations
+
+### Plugin System
+Bevy-inspired modular architecture:
+- **Components**: Data definitions using bitECS
+- **Systems**: Logic organized by update phases (setup, fixed, simulation, draw)
+- **Recipes**: XML entity templates with preset components
+- **Config**: Defaults, shorthands, enums, validations, parsers
+
+### Update Phases
+1. **SetupBatch**: Input gathering and frame setup
+2. **FixedBatch**: Physics simulation at fixed timestep (50Hz)
+3. **SimulationBatch**: Game logic and state updates
+4. **DrawBatch**: Rendering and interpolation
+
+## Critical Rules
+
+⚠️ **Physics Position Override**: Physics bodies override transform positions. Always use `pos` attribute on physics entities, not transform position.
+
+⚠️ **Ground Required**: Always include ground/platforms or the player falls infinitely.
+
+⚠️ **Component Declaration**: Bare attributes mean "include with defaults", not "empty".
+
+## Essential Knowledge
+
+## Instant Playable Game
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/vibegame@latest/dist/cdn/vibegame.standalone.iife.js"></script>
+
+<world canvas="#game-canvas" sky="#87ceeb">
+  <!-- Ground (REQUIRED to prevent player falling) -->
+  <static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"></static-part>
+</world>
+
+<canvas id="game-canvas"></canvas>
+<script>
+  GAME.run();
+</script>
+```
+
+This creates a complete game with:
+- ✅ Player character (auto-created)
+- ✅ Orbital camera (auto-created)
+- ✅ Directional + ambient lighting (auto-created)
+- ✅ Ground platform (you provide this)
+- ✅ WASD movement, mouse camera, space to jump
+
+## Development Setup
+
+After installation with `npm create vibegame@latest my-game`:
+
+```bash
+cd my-game
+bun dev    # Start dev server with hot reload
+```
+
+### Project Structure
+- **TypeScript** - Full TypeScript support with strict type checking
+- **src/main.ts** - Entry point for your game
+- **index.html** - HTML template with canvas element
+- **vite.config.ts** - Build configuration
+
+### Commands
+- `bun dev` - Development server with hot reload
+- `bun run build` - Production build
+- `bun run preview` - Preview production build
+- `bun run check` - TypeScript type checking
+- `bun run lint` - Lint code with ESLint
+- `bun run format` - Format code with Prettier
+
+## Physics Objects
+
+```xml
+<world canvas="#game-canvas">
+  <!-- 1. Static: Never moves (grounds, walls, platforms) -->
+  <static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#808080"></static-part>
+  
+  <!-- 2. Dynamic: Falls with gravity (balls, crates, debris) -->
+  <dynamic-part pos="0 5 0" shape="sphere" size="1" color="#ff0000"></dynamic-part>
+  
+  <!-- 3. Kinematic: Script-controlled movement (moving platforms, doors) -->
+  <kinematic-part pos="5 2 0" shape="box" size="3 0.5 3" color="#0000ff">
+    <!-- Animate the platform up and down -->
+    <tween target="body.pos-y" from="2" to="5" duration="3" loop="ping-pong"></tween>
+  </kinematic-part>
+</world>
+```
+
+## CRITICAL: Physics Position vs Transform Position
+
+<warning>
+⚠️ **Physics bodies override transform positions!** 
+Always set position on the body, not the transform, for physics entities.
+</warning>
+
+```xml
+<!-- ✅ BEST: Use recipe with pos shorthand -->
+<dynamic-part pos="0 5 0" shape="sphere" size="1"></dynamic-part>
+
+<!-- ❌ WRONG: Transform position ignored if body exists -->
+<entity transform="pos: 0 5 0" body collider></entity>  <!-- Falls to 0,0,0! -->
+
+<!-- ✅ CORRECT: Set body position explicitly (if using raw entity) -->
+<entity transform body="pos: 0 5 0" collider></entity>
+```
+
+## ECS Architecture Explained
+
+Unlike traditional game engines with GameObjects, VibeGame uses Entity-Component-System:
+
+- **Entities**: Just numbers (IDs), no data or behavior
+- **Components**: Pure data containers (position, health, color)
+- **Systems**: Functions that process entities with specific components
+
+```typescript
+// Component = Data only
+const Health = GAME.defineComponent({
+  current: GAME.Types.f32,
+  max: GAME.Types.f32
+});
+
+// System = Logic only
+const healthQuery = GAME.defineQuery([Health]);
+const DamageSystem: GAME.System = {
+  update: (state) => {
+    const entities = healthQuery(state.world);
+    for (const entity of entities) {
+      Health.current[entity] -= 1 * state.time.deltaTime;
+      if (Health.current[entity] <= 0) {
+        state.destroyEntity(entity);
+      }
+    }
+  }
+};
+```
+
+## What's Auto-Created (Game Engine Defaults)
+
+The engine automatically creates these if missing:
+1. **Player** - Character with physics, controls, and respawn (at 0, 1, 0)
+2. **Camera** - Orbital camera following the player
+3. **Lighting** - Ambient + directional light with shadows
+
+You only need to provide:
+- **Ground/platforms** - Or the player falls forever
+- **Game objects** - Whatever makes your game unique
+
+### Override Auto-Creation (When Needed)
+
+While auto-creation is recommended, you can manually create these for customization:
+
+```xml
+<world canvas="#game-canvas">
+  <static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"></static-part>
+  
+  <!-- Custom player spawn position and properties -->
+  <player pos="0 10 0" speed="8" jump-height="3"></player>
+  
+  <!-- Custom camera settings -->
+  <camera orbit-camera="distance: 10; target-pitch: 0.5"></camera>
+  
+  <!-- Custom lighting (or use <light> for both ambient + directional) -->
+  <ambient-light sky-color="#ff6b6b" ground-color="#4ecdc4" intensity="0.8"></ambient-light>
+  <directional-light color="#ffffff" intensity="0.5" direction="-1 -2 -1"></directional-light>
+</world>
+```
+
+**Best Practice**: Use auto-creation unless you specifically need custom positions, properties, or multiple instances. The defaults are well-tuned for most games.
+
+## Post-Processing Effects
+
+```xml
+<!-- Bloom effect for glow -->
+<camera bloom="intensity: 2; luminance-threshold: 0.8"></camera>
+
+<!-- Retro dithering (reduces color palette) -->
+<camera dithering="color-bits: 3; scale: 2; noise: 1"></camera>
+
+<!-- Tonemapping for HDR-like visuals -->
+<camera tonemapping="mode: aces-filmic"></camera>
+
+<!-- Combined cinematic style -->
+<camera bloom="intensity: 1.5" tonemapping="mode: aces-filmic"></camera>
+```
+
+## Common Game Patterns
+
+### Basic Platformer
+```xml
+<world canvas="#game-canvas">
+  <!-- Ground -->
+  <static-part pos="0 -0.5 0" shape="box" size="50 1 50" color="#90ee90"></static-part>
+  
+  <!-- Platforms at different heights -->
+  <static-part pos="-5 2 0" shape="box" size="3 0.5 3" color="#808080"></static-part>
+  <static-part pos="0 4 0" shape="box" size="3 0.5 3" color="#808080"></static-part>
+  <static-part pos="5 6 0" shape="box" size="3 0.5 3" color="#808080"></static-part>
+  
+  <!-- Moving platform -->
+  <kinematic-part pos="0 3 5" shape="box" size="4 0.5 4" color="#4169e1">
+    <tween target="body.pos-x" from="-10" to="10" duration="5" loop="ping-pong"></tween>
+  </kinematic-part>
+  
+  <!-- Goal area -->
+  <static-part pos="10 8 0" shape="box" size="5 0.5 5" color="#ffd700"></static-part>
+</world>
+```
+
+### Collectible Coins (Collision-based)
+```xml
+<world canvas="#game-canvas">
+  <static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"></static-part>
+  
+  <!-- Spinning coins -->
+  <kinematic-part pos="2 1 0" shape="cylinder" size="0.5 0.1 0.5" color="#ffd700">
+    <tween target="body.euler-y" from="0" to="360" duration="2" loop="loop"></tween>
+  </kinematic-part>
+  
+  <kinematic-part pos="-2 1 0" shape="cylinder" size="0.5 0.1 0.5" color="#ffd700">
+    <tween target="body.euler-y" from="0" to="360" duration="2" loop="loop"></tween>
+  </kinematic-part>
+</world>
+```
+
+### Physics Playground
+```xml
+<world canvas="#game-canvas">
+  <!-- Ground -->
+  <static-part pos="0 -0.5 0" shape="box" size="30 1 30" color="#90ee90"></static-part>
+  
+  <!-- Walls -->
+  <static-part pos="15 5 0" shape="box" size="1 10 30" color="#808080"></static-part>
+  <static-part pos="-15 5 0" shape="box" size="1 10 30" color="#808080"></static-part>
+  <static-part pos="0 5 15" shape="box" size="30 10 1" color="#808080"></static-part>
+  <static-part pos="0 5 -15" shape="box" size="30 10 1" color="#808080"></static-part>
+  
+  <!-- Spawn balls at different positions -->
+  <dynamic-part pos="-5 10 0" shape="sphere" size="1" color="#ff0000"></dynamic-part>
+  <dynamic-part pos="0 12 0" shape="sphere" size="1.5" color="#00ff00"></dynamic-part>
+  <dynamic-part pos="5 8 0" shape="sphere" size="0.8" color="#0000ff"></dynamic-part>
+  
+  <!-- Bouncy ball (high restitution) -->
+  <dynamic-part pos="0 15 5" shape="sphere" size="1" color="#ff00ff" 
+                collider="restitution: 0.9"></dynamic-part>
+</world>
+```
+
+## Recipe Reference
+
+| Recipe | Purpose | Key Attributes | Common Use |
+|--------|---------|---------------|------------|
+| `<static-part>` | Immovable objects | `pos`, `shape`, `size`, `color` | Grounds, walls, platforms |
+| `<dynamic-part>` | Gravity-affected objects | `pos`, `shape`, `size`, `color`, `mass` | Balls, crates, falling objects |
+| `<kinematic-part>` | Script-controlled physics | `pos`, `shape`, `size`, `color` | Moving platforms, doors |
+| `<player>` | Player character | `pos`, `speed`, `jump-height` | Main character (auto-created) |
+| `<entity>` | Base entity | Any components via attributes | Custom entities |
+
+### Shape Options
+- `box` - Rectangular solid (default)
+- `sphere` - Ball shape
+- `cylinder` - Cylindrical shape
+- `capsule` - Pill shape (good for characters)
+
+### Size Attribute
+- Box: `size="width height depth"` or `size="2 1 2"`
+- Sphere: `size="diameter"` or `size="1"`
+- Cylinder: `size="diameter height"` or `size="1 2"`
+- Broadcast: `size="2"` becomes `size="2 2 2"`
+
+## How Recipes and Shorthands Work
+
+### Everything is an Entity
+Every XML tag creates an entity. Recipes like `<static-part>` are just shortcuts for `<entity>` with preset components.
+
+```xml
+<!-- These are equivalent: -->
+<static-part pos="0 0 0" color="#ff0000"></static-part>
+
+<entity 
+  transform 
+  body="type: fixed" 
+  collider 
+  renderer="color: 0xff0000"
+  pos="0 0 0"></entity>
+```
+
+### Component Attributes
+Components are declared using bare attributes (no value means "use defaults"):
+
+```xml
+<!-- Bare attributes declare components with default values -->
+<entity transform body collider renderer></entity>
+
+<!-- Add properties to override defaults -->
+<entity transform="pos-x: 5; pos-y: 2; pos-z: -3; scale: 2"></entity>
+
+<!-- Mix bare and valued attributes -->
+<entity transform="pos: 0 5 0" body="type: dynamic; mass: 10" collider renderer></entity>
+
+<!-- Property groups -->
+<entity transform="pos: 5 2 -3; scale: 2 2 2"></entity>
+```
+
+**Important**: Bare attributes like `transform` mean "include this component with default values", NOT "empty" or "disabled".
+
+### Automatic Shorthand Expansion
+Shorthands expand to ANY component with matching properties:
+
+```xml
+<!-- "pos" shorthand applies to components with posX, posY, posZ -->
+<entity transform body pos="0 5 0"></entity>
+<!-- Both transform AND body get pos values -->
+
+<!-- "color" shorthand applies to renderer.color -->
+<entity renderer color="#ff0000"></entity>  
+
+<!-- "size" shorthand (broadcasts single value) -->
+<entity collider size="2"></entity>
+<!-- Expands to: sizeX: 2, sizeY: 2, sizeZ: 2 -->
+
+<!-- Multiple shorthands together -->
+<entity transform body collider renderer pos="0 5 0" size="1" color="#ff0000"></entity>
+```
+
+### Recipe Internals
+Recipes are registered component bundles with defaults:
+
+```xml
+<!-- What <dynamic-part> actually is: -->
+<entity 
+  transform
+  body="type: dynamic"     <!-- Override -->
+  collider
+  renderer
+  respawn
+></entity>
+
+<!-- So this: -->
+<dynamic-part pos="0 5 0" color="#ff0000"></dynamic-part>
+
+<!-- Is really: -->
+<entity 
+  transform="pos: 0 5 0"
+  body="type: dynamic; pos: 0 5 0"  <!-- pos applies to body too! -->
+  collider
+  renderer="color: 0xff0000"
+  respawn
+></entity>
+```
+
+### Common Pitfall: Component Requirements
+```xml
+<!-- ❌ BAD: Missing required components -->
+<entity pos="0 5 0"></entity>  <!-- No transform component! -->
+
+<!-- ✅ GOOD: Explicit components -->
+<entity transform="pos: 0 5 0"></entity>
+
+<!-- ✅ BEST: Use recipe with built-in components -->
+<static-part pos="0 5 0"></static-part>
+```
+
+### Best Practices Summary
+1. **Use recipes** (`<static-part>`, `<dynamic-part>`, etc.) instead of raw `<entity>` tags
+2. **Use shorthands** (`pos`, `size`, `color`) for cleaner code
+3. **Override only what you need** - recipes have good defaults
+4. **Mix recipes with custom components** - e.g., `<dynamic-part health="max: 100">`
+
+## Currently Supported Features
+
+### ✅ What Works Well
+- **Basic platforming** - Jump puzzles, obstacle courses
+- **Physics interactions** - Balls, dominoes, stacking
+- **Moving platforms** - Via kinematic bodies + tweening
+- **Collectibles** - Using collision detection in systems
+- **Third-person character control** - WASD + mouse camera
+- **Gamepad support** - Xbox/PlayStation controllers
+- **Visual effects** - Tweening colors, positions, rotations
+- **Post-processing** - Bloom, dithering, and tonemapping effects for visual styling
+- **Game UI/HUD** - HTML/CSS overlays with GSAP animations, ECS state integration
+
+### Example Prompts That Work
+- "Create a platformer with moving platforms and collectible coins"
+- "Make bouncing balls that collide with walls"
+- "Build an obstacle course with rotating platforms"
+- "Add falling crates that stack up"
+- "Create a simple parkour level"
+- "Add a score display and upgrade menu with animations"
+- "Create a game with currency system and floating text effects"
+
+### Troubleshooting
+
+- **Physics not working?** → Check if ground exists, verify `<world>` tag
+- **Entity not appearing?** → Verify transform component, check position values
+- **Movement feels wrong?** → Physics body position overrides transform position
+- **Player falling forever?** → Add a ground/platform with `<static-part>`
+
+## Plugin Development Pattern
+
+```typescript
+// Component Definition
+export const MyComponent = GAME.defineComponent({
+  value: GAME.Types.f32,
+  enabled: GAME.Types.ui8
+});
+
+// System Definition
+const myQuery = GAME.defineQuery([MyComponent]);
+export const MySystem: GAME.System = {
+  group: 'simulation', // or 'setup', 'fixed', 'draw'
+  update: (state) => {
+    const entities = myQuery(state.world);
+    for (const entity of entities) {
+      // System logic
+      MyComponent.value[entity] += state.time.deltaTime;
+    }
+  }
+};
+
+// Plugin Bundle
+export const MyPlugin: GAME.Plugin = {
+  components: { MyComponent },
+  systems: [MySystem],
+  config: {
+    defaults: { "my-component": { value: 1, enabled: 1 } },
+    shorthands: { "my-val": "my-component.value" }
+  }
+};
+
+// Registration
+GAME.withPlugin(MyPlugin).run();
+```
+
+## State Management Patterns
+
+### Singleton Entities (Game State)
+```typescript
+function getOrCreateGameState(state: GAME.State): number {
+  const query = GAME.defineQuery([GameState]);
+  const entities = query(state.world);
+  if (entities.length > 0) return entities[0];
+
+  const entity = state.createEntity();
+  state.addComponent(entity, GameState, { score: 0, level: 1 });
+  return entity;
+}
+```
+
+### Component Access (bitECS style)
+```typescript
+// Direct property access
+GAME.Transform.posX[entity] = 10;
+GAME.Transform.posY[entity] = 5;
+
+// Read values
+const x = GAME.Transform.posX[entity];
+const health = GAME.Health.current[entity];
+```
+
+## Features Not Yet Built-In
+
+### ❌ Engine Features Not Available
+- **Multiplayer/Networking** - No server sync
+- **Sound/Audio** - No audio system yet
+- **Save/Load** - No persistence system
+- **Inventory** - No item management system built-in (but easily implementable with UI)
+- **Dialog/NPCs** - No conversation system built-in (but easily implementable with UI)
+- **AI/Pathfinding** - No enemy AI
+- **Particles** - No particle effects (though UI can create particle-like effects)
+- **Custom shaders** - Fixed rendering pipeline
+- **Terrain** - Use box platforms instead
+
+### Recommended Approaches
+- **Complex UI** → HTML/CSS overlays (this is actually superior to most game engines)
+- **Animations** → GSAP for smooth transitions and effects
+- **Level progression** → Reload with different XML or hide/show worlds
+- **Enemy behavior** → Tweened movement patterns
+- **Interactions** → Collision detection in custom systems
+
+## Common Mistakes to Avoid
+
+### ❌ Forgetting the Ground
+```xml
+<!-- BAD: No ground, player falls forever -->
+<world canvas="#game-canvas">
+  <dynamic-part pos="0 5 0" shape="sphere"></dynamic-part>
+</world>
+```
+
+### ❌ Setting Transform Position on Physics Objects
+```xml
+<!-- BAD: Transform position ignored -->
+<entity transform="pos: 0 5 0" body collider></entity>
+
+<!-- GOOD: Set body position (raw entity) -->
+<entity transform body="pos: 0 5 0" collider></entity>
+
+<!-- BEST: Use recipes with pos shorthand -->
+<dynamic-part pos="0 5 0" shape="sphere"></dynamic-part>
+```
+
+### ❌ Missing World Tag
+```xml
+<!-- BAD: Entities outside world tag -->
+<static-part pos="0 0 0" shape="box"></static-part>
+
+<!-- GOOD: Everything inside world -->
+<world canvas="#game-canvas">
+  <static-part pos="0 0 0" shape="box"></static-part>
+</world>
+```
+
+### ❌ Wrong Physics Type
+```xml
+<!-- BAD: Dynamic platform (falls with gravity) -->
+<dynamic-part pos="0 3 0" shape="box">
+  <tween target="body.pos-x" from="-5" to="5"></tween>
+</dynamic-part>
+
+<!-- GOOD: Kinematic for controlled movement -->
+<kinematic-part pos="0 3 0" shape="box">
+  <tween target="body.pos-x" from="-5" to="5"></tween>
+</kinematic-part>
+```
+
+## Custom Components and Systems
+
+### Creating a Health System
+```typescript
+import * as GAME from 'vibegame';
+
+// Define the component
+const Health = GAME.defineComponent({
+  current: GAME.Types.f32,
+  max: GAME.Types.f32
+});
+
+// Create the system
+const HealthSystem: GAME.System = {
+  update: (state) => {
+    const entities = GAME.defineQuery([Health])(state.world);
+    for (const entity of entities) {
+      // Regenerate health over time
+      if (Health.current[entity] < Health.max[entity]) {
+        Health.current[entity] += 5 * state.time.deltaTime;
+      }
+    }
+  }
+};
+
+// Bundle as plugin
+const HealthPlugin: GAME.Plugin = {
+  components: { Health },
+  systems: [HealthSystem],
+  config: {
+    defaults: {
+      "health": { current: 100, max: 100 }
+    }
+  }
+};
+
+// Use in game
+GAME.withPlugin(HealthPlugin).run();
+```
+
+### Using in XML
+```xml
+<world canvas="#game-canvas">
+  <!-- Add health to a dynamic entity (best practice: use recipes) -->
+  <dynamic-part pos="0 2 0" shape="sphere" color="#ff0000"
+                health="current: 50; max: 100"></dynamic-part>
+</world>
+```
+
+## State API Reference
+
+Available in all systems via the `state` parameter:
+
+### Entity Management
+- `createEntity(): number` - Create new entity
+- `destroyEntity(entity: number)` - Remove entity
+- `query(...Components): number[]` - Find entities with components
+
+### Component Operations  
+- `addComponent(entity, Component, data?)` - Add component
+- `removeComponent(entity, Component)` - Remove component
+- `hasComponent(entity, Component): boolean` - Check component
+- `getComponent(name: string): Component | null` - Get by name
+
+### Time
+- `time.delta: number` - Frame time in seconds
+- `time.elapsed: number` - Total time in seconds
+- `time.fixed: number` - Fixed timestep (1/50)
+
+### Physics Helpers
+- `addComponent(entity, ApplyImpulse, {x, y, z})` - One-time push
+- `addComponent(entity, ApplyForce, {x, y, z})` - Continuous force
+- `addComponent(entity, KinematicMove, {x, y, z})` - Move kinematic
+
+## Plugin System
+
+### Using Specific Plugins
+```typescript
+import * as GAME from 'vibegame';
+
+// Start with no plugins
+GAME
+  .withoutDefaultPlugins()
+  .withPlugin(TransformsPlugin)  // Just transforms
+  .withPlugin(RenderingPlugin)   // Add rendering
+  .withPlugin(PhysicsPlugin)     // Add physics
+  .run();
+```
+
+### Default Plugin Bundle
+- **RecipesPlugin** - XML parsing and entity creation
+- **TransformsPlugin** - Position, rotation, scale, hierarchy
+- **RenderingPlugin** - Three.js meshes, lights, camera
+- **PhysicsPlugin** - Rapier physics simulation
+- **InputPlugin** - Keyboard, mouse, gamepad input
+- **OrbitCameraPlugin** - Third-person camera
+- **PlayerPlugin** - Character controller
+- **TweenPlugin** - Animation system
+- **RespawnPlugin** - Fall detection and reset
+- **StartupPlugin** - Auto-create player/camera/lights
+
+## Plugin Reference
+
+### Core
+
+Math utilities for interpolation and 3D transformations.
+
+### Functions
+
+#### lerp(a, b, t): number
+Linear interpolation
+
+#### slerp(fromX, fromY, fromZ, fromW, toX, toY, toZ, toW, t): Quaternion
+Quaternion spherical interpolation
+
+#### Examples
+
+## Usage Note
+
+Math utilities are used internally by systems like tweening and transforms. For animating properties, use the Tween system instead of directly calling interpolation functions. For transformations, use the Transform component's euler angles which are automatically converted to quaternions by the system.
+
+### Animation
+
+Procedural character animation with body parts that respond to movement states.
+
+### Components
+
+#### AnimatedCharacter
+- headEntity: eid
+- torsoEntity: eid
+- leftArmEntity: eid
+- rightArmEntity: eid
+- leftLegEntity: eid
+- rightLegEntity: eid
+- phase: f32 - Walk cycle phase (0-1)
+- jumpTime: f32
+- fallTime: f32
+- animationState: ui8 - 0=IDLE, 1=WALKING, 2=JUMPING, 3=FALLING, 4=LANDING
+- stateTransition: f32
+
+#### HasAnimator
+Tag component (no properties)
+
+### Systems
+
+#### AnimatedCharacterInitializationSystem
+- Group: setup
+- Creates body part entities for AnimatedCharacter components
+
+#### AnimatedCharacterUpdateSystem
+- Group: simulation
+- Updates character animation based on movement and physics state
+
+#### Examples
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Add animated character to a player entity
+const player = state.createEntity();
+state.addComponent(player, GAME.AnimatedCharacter);
+state.addComponent(player, GAME.CharacterController);
+state.addComponent(player, GAME.Transform);
+
+// The AnimatedCharacterInitializationSystem will automatically
+// create body parts in the next setup phase
+```
+
+### Accessing Animation State
+
+```typescript
+import * as GAME from 'vibegame';
+
+const characterQuery = GAME.defineQuery([GAME.AnimatedCharacter]);
+const MySystem: GAME.System = {
+  update: (state) => {
+    const characters = characterQuery(state.world);
+    for (const entity of characters) {
+      const animState = GAME.AnimatedCharacter.animationState[entity];
+      if (animState === 2) { // JUMPING
+        console.log('Character is jumping!');
+      }
+    }
+  }
+};
+```
+
+### XML Declaration
+
+```xml
+<!-- Player entity with animated character -->
+<entity 
+  animated-character
+  character-controller
+  transform="pos: 0 2 0"
+/>
+```
+
+### Input
+
+Focus-aware input handling for mouse, keyboard, and gamepad with buffered actions. Keyboard input only responds when canvas has focus.
+
+### Components
+
+#### InputState
+- moveX: f32 - Horizontal axis (-1 left, 1 right)
+- moveY: f32 - Forward/backward (-1 back, 1 forward)
+- moveZ: f32 - Vertical axis (-1 down, 1 up)
+- lookX: f32 - Mouse delta X
+- lookY: f32 - Mouse delta Y
+- scrollDelta: f32 - Mouse wheel delta
+- jump: ui8 - Jump available (0/1)
+- primaryAction: ui8 - Primary action (0/1)
+- secondaryAction: ui8 - Secondary action (0/1)
+- leftMouse: ui8 - Left button (0/1)
+- rightMouse: ui8 - Right button (0/1)
+- middleMouse: ui8 - Middle button (0/1)
+- jumpBufferTime: f32
+- primaryBufferTime: f32
+- secondaryBufferTime: f32
+
+### Systems
+
+#### InputSystem
+- Group: simulation
+- Updates InputState components with current input data
+
+### Functions
+
+#### setTargetCanvas(canvas: HTMLCanvasElement | null): void
+Registers canvas for focus-based keyboard input
+
+#### consumeJump(): boolean
+Consumes buffered jump input
+
+#### consumePrimary(): boolean
+Consumes buffered primary action
+
+#### consumeSecondary(): boolean
+Consumes buffered secondary action
+
+#### handleMouseMove(event: MouseEvent): void
+Processes mouse movement
+
+#### handleMouseDown(event: MouseEvent): void
+Processes mouse button press
+
+#### handleMouseUp(event: MouseEvent): void
+Processes mouse button release
+
+#### handleWheel(event: WheelEvent): void
+Processes mouse wheel
+
+### Constants
+
+#### INPUT_CONFIG
+Default input mappings and sensitivity settings
+
+#### Examples
+
+## Examples
+
+### Basic Plugin Registration
+
+```typescript
+import * as GAME from 'vibegame';
+
+GAME
+  .withPlugin(GAME.InputPlugin)
+  .run();
+```
+
+### Reading Input in a Custom System
+
+```typescript
+import * as GAME from 'vibegame';
+
+const playerQuery = GAME.defineQuery([GAME.Player, GAME.InputState]);
+const PlayerControlSystem: GAME.System = {
+  update: (state) => {
+    const players = playerQuery(state.world);
+    
+    for (const player of players) {
+      // Read movement axes
+      const moveX = GAME.InputState.moveX[player];
+      const moveY = GAME.InputState.moveY[player];
+      
+      // Check for jump
+      if (GAME.InputState.jump[player]) {
+        // Jump is available this frame
+      }
+      
+      // Check mouse buttons
+      if (GAME.InputState.leftMouse[player]) {
+        // Left mouse is held
+      }
+    }
+  }
+};
+```
+
+### Consuming Buffered Actions
+
+```typescript
+import * as GAME from 'vibegame';
+
+const CombatSystem: GAME.System = {
+  update: (state) => {
+    // Consume jump if available (prevents double consumption)
+    if (GAME.consumeJump()) {
+      // Perform jump
+      velocity.y = JUMP_FORCE;
+    }
+    
+    // Consume primary action
+    if (GAME.consumePrimary()) {
+      // Fire weapon
+      spawnProjectile();
+    }
+  }
+};
+```
+
+### Custom Input Mappings
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Modify before starting the game
+GAME.INPUT_CONFIG.mappings.jump = ['Space', 'KeyX'];
+GAME.INPUT_CONFIG.mappings.moveForward = ['KeyW', 'KeyZ', 'ArrowUp'];
+GAME.INPUT_CONFIG.mouseSensitivity.look = 0.3;
+
+GAME.run();
+```
+
+### Manual Event Handling
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Use the exported handlers directly if needed
+canvas.addEventListener('mousedown', GAME.handleMouseDown);
+canvas.addEventListener('mouseup', GAME.handleMouseUp);
+```
+
+### Orbit Camera
+
+Orbital camera controller for third-person views and smooth target following.
+
+### Components
+
+#### OrbitCamera
+- target: eid (0) - Target entity ID
+- current-yaw: f32 (π) - Current horizontal angle
+- current-pitch: f32 (π/6) - Current vertical angle
+- current-distance: f32 (4) - Current distance
+- target-yaw: f32 (π) - Target horizontal angle
+- target-pitch: f32 (π/6) - Target vertical angle
+- target-distance: f32 (4) - Target distance
+- min-distance: f32 (1)
+- max-distance: f32 (25)
+- min-pitch: f32 (0)
+- max-pitch: f32 (π/2)
+- smoothness: f32 (0.5) - Interpolation speed
+- offset-x: f32 (0)
+- offset-y: f32 (1.25)
+- offset-z: f32 (0)
+
+### Systems
+
+#### OrbitCameraSystem
+- Group: draw
+- Updates camera position and rotation around target
+
+### Recipes
+
+#### camera
+- Creates orbital camera with default settings
+- Components: orbit-camera, transform, world-transform, main-camera
+
+#### Examples
+
+## Examples
+
+### Basic Camera
+
+```xml
+<!-- Create default orbital camera -->
+<camera />
+```
+
+### Camera Following Player
+
+```xml
+<world>
+  <!-- Player entity -->
+  <player id="player" pos="0 0 0" />
+  
+  <!-- Camera following player -->
+  <camera 
+    target="#player"
+    target-distance="10"
+    min-distance="5"
+    max-distance="20"
+    offset-y="2"
+  />
+</world>
+```
+
+### Custom Orbit Settings
+
+```xml
+<entity 
+  orbit-camera="
+    target: #boss;
+    target-distance: 15;
+    target-yaw: 0;
+    target-pitch: 0.5;
+    smoothness: 0.2;
+    offset-y: 3
+  "
+  transform
+  main-camera
+/>
+```
+
+### Programmatic Usage
+
+```typescript
+import * as GAME from 'vibegame';
+
+const cameraQuery = GAME.defineQuery([GAME.OrbitCamera]);
+const CameraControlSystem = {
+  update: (state) => {
+    const cameras = cameraQuery(state.world);
+    
+    for (const camera of cameras) {
+      // Rotate camera on input
+      if (state.input.mouse.deltaX) {
+        GAME.OrbitCamera.targetYaw[camera] += state.input.mouse.deltaX * 0.01;
+      }
+      
+      // Zoom on scroll
+      if (state.input.mouse.wheel) {
+        GAME.OrbitCamera.targetDistance[camera] = Math.max(
+          GAME.OrbitCamera.minDistance[camera],
+          Math.min(
+            GAME.OrbitCamera.maxDistance[camera],
+            GAME.OrbitCamera.targetDistance[camera] - state.input.mouse.wheel * 0.5
+          )
+        );
+      }
+    }
+  }
+};
+```
+
+### Dynamic Target Switching
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Switch camera target
+const switchTarget = (state, cameraEntity, newTargetEntity) => {
+  GAME.OrbitCamera.target[cameraEntity] = newTargetEntity;
+};
+```
+
+### Physics
+
+3D physics simulation with Rapier including rigid bodies, collisions, and character controllers.
+
+### Constants
+
+- DEFAULT_GRAVITY: -60
+
+### Enums
+
+#### BodyType
+- Dynamic = 0 - Affected by forces
+- Fixed = 1 - Immovable static
+- KinematicPositionBased = 2 - Script position
+- KinematicVelocityBased = 3 - Script velocity
+
+#### ColliderShape
+- Box = 0
+- Sphere = 1
+- Capsule = 2
+
+### Components
+
+#### PhysicsWorld
+- gravityX: f32 (0)
+- gravityY: f32 (-60)
+- gravityZ: f32 (0)
+
+#### Body
+- type: ui8 - BodyType enum (Fixed)
+- mass: f32 (1)
+- linearDamping: f32 (0)
+- angularDamping: f32 (0)
+- gravityScale: f32 (1)
+- ccd: ui8 (0)
+- lockRotX: ui8 (0)
+- lockRotY: ui8 (0)
+- lockRotZ: ui8 (0)
+- posX, posY, posZ: f32
+- rotX, rotY, rotZ, rotW: f32 (rotW=1)
+- eulerX, eulerY, eulerZ: f32
+- velX, velY, velZ: f32
+- rotVelX, rotVelY, rotVelZ: f32
+- lastPosX, lastPosY, lastPosZ: f32
+
+#### Collider
+- shape: ui8 - ColliderShape enum (Box)
+- sizeX, sizeY, sizeZ: f32 (1)
+- radius: f32 (0.5)
+- height: f32 (1)
+- friction: f32 (0.5)
+- restitution: f32 (0)
+- density: f32 (1)
+- isSensor: ui8 (0)
+- membershipGroups: ui16 (0xffff)
+- filterGroups: ui16 (0xffff)
+- posOffsetX, posOffsetY, posOffsetZ: f32
+- rotOffsetX, rotOffsetY, rotOffsetZ, rotOffsetW: f32 (rotOffsetW=1)
+
+#### CharacterController
+- offset: f32 (0.08)
+- maxSlope: f32 (45°)
+- maxSlide: f32 (30°)
+- snapDist: f32 (0.5)
+- autoStep: ui8 (1)
+- maxStepHeight: f32 (0.3)
+- minStepWidth: f32 (0.05)
+- upX, upY, upZ: f32 (upY=1)
+- moveX, moveY, moveZ: f32
+- grounded: ui8
+- platform: eid - Entity the character is standing on
+- platformVelX, platformVelY, platformVelZ: f32
+- platformDeltaX, platformDeltaY, platformDeltaZ: f32
+
+#### CharacterMovement
+- desiredVelX, desiredVelY, desiredVelZ: f32
+- velocityY: f32
+- actualMoveX, actualMoveY, actualMoveZ: f32
+
+#### InterpolatedTransform
+- prevPosX, prevPosY, prevPosZ: f32
+- prevRotX, prevRotY, prevRotZ, prevRotW: f32
+- posX, posY, posZ: f32
+- rotX, rotY, rotZ, rotW: f32
+
+#### Force/Impulse Components
+- ApplyForce: x, y, z (f32)
+- ApplyTorque: x, y, z (f32)
+- ApplyImpulse: x, y, z (f32)
+- ApplyAngularImpulse: x, y, z (f32)
+- SetLinearVelocity: x, y, z (f32)
+- SetAngularVelocity: x, y, z (f32)
+- KinematicMove: x, y, z (f32)
+- KinematicRotate: x, y, z, w (f32)
+
+#### Collision Events
+- CollisionEvents: activeEvents (ui8)
+- TouchedEvent: other, handle1, handle2 (ui32)
+- TouchEndedEvent: other, handle1, handle2 (ui32)
+
+### Systems
+
+- PhysicsWorldSystem - Initializes physics world
+- PhysicsInitializationSystem - Creates bodies and colliders
+- PhysicsCleanupSystem - Removes physics on entity destroy
+- PlatformDeltaSystem - Tracks platform position changes
+- CharacterMovementSystem - Character controller movement with platform sticking
+- CollisionEventCleanupSystem - Clears collision events
+- ApplyForcesSystem - Applies forces
+- ApplyTorquesSystem - Applies torques
+- ApplyImpulsesSystem - Applies impulses
+- ApplyAngularImpulsesSystem - Applies angular impulses
+- SetVelocitySystem - Sets velocities
+- TeleportationSystem - Instant position changes
+- KinematicMovementSystem - Kinematic movement
+- PhysicsStepSystem - Steps simulation
+- PhysicsRapierSyncSystem - Syncs Rapier to ECS
+- PhysicsInterpolationSystem - Interpolates for rendering
+
+### Functions
+
+#### initializePhysics(): Promise<void>
+Initializes Rapier WASM physics engine
+
+### Recipes
+
+- static-part - Immovable physics objects
+- dynamic-part - Gravity-affected objects
+- kinematic-part - Script-controlled objects
+
+#### Examples
+
+## Examples
+
+### Basic Usage
+
+#### XML Recipes
+
+##### Static Floor
+```xml
+<static-part
+  pos="0 -0.5 0"
+  shape="box"
+  size="20 1 20"
+  color="#90ee90"
+/>
+```
+
+##### Dynamic Ball
+```xml
+<dynamic-part
+  pos="0 5 0"
+  shape="sphere"
+  radius="0.5"
+  color="#ff0000"
+  mass="2"
+  restitution="0.8"
+/>
+```
+
+##### Moving Platform
+```xml
+<kinematic-part
+  pos="0 2 0"
+  shape="box"
+  size="3 0.2 3"
+  color="#4169e1"
+>
+  <!-- Add movement with tweening -->
+  <tween
+    target="body.pos-y"
+    from="2"
+    to="5"
+    duration="3"
+    ease="sine-in-out"
+    loop="ping-pong"
+  />
+</kinematic-part>
+```
+
+##### Character with Controller
+```xml
+<entity
+  pos="0 1 0"
+  body="type: kinematic-position"
+  collider="shape: capsule; height: 1.8; radius: 0.4"
+  character-controller
+  character-movement
+  transform
+  renderer
+/>
+```
+
+#### JavaScript API
+
+##### Create Physics Entity
+```typescript
+import * as GAME from 'vibegame';
+
+// Create a dynamic physics box
+const entity = state.createEntity();
+
+state.addComponent(entity, GAME.Body, {
+  type: GAME.BodyType.Dynamic,
+  mass: 5,
+  posX: 0, posY: 10, posZ: 0
+});
+
+state.addComponent(entity, GAME.Collider, {
+  shape: GAME.ColliderShape.Box,
+  sizeX: 1, sizeY: 1, sizeZ: 1,
+  friction: 0.7,
+  restitution: 0.3
+});
+
+// Note: Physics body won't exist until next fixed update
+// Transform will be overwritten by Body position after initialization
+```
+
+##### Moving Physics Bodies
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Dynamic bodies - Use forces/impulses for movement
+if (GAME.Body.type[entity] === GAME.BodyType.Dynamic) {
+  // Apply force for gradual acceleration
+  state.addComponent(entity, GAME.ApplyForce, { x: 10, y: 0, z: 0 });
+  
+  // Apply impulse for instant velocity change
+  state.addComponent(entity, GAME.ApplyImpulse, { x: 0, y: 50, z: 0 });
+  
+  // Direct position setting only for teleportation
+  GAME.Body.posX[entity] = 10; // Teleport - use sparingly
+}
+
+// Kinematic bodies - Direct control via movement components
+if (GAME.Body.type[entity] === GAME.BodyType.KinematicPositionBased) {
+  state.addComponent(entity, GAME.KinematicMove, { x: 5, y: 2, z: 0 });
+}
+
+if (GAME.Body.type[entity] === GAME.BodyType.KinematicVelocityBased) {
+  state.addComponent(entity, GAME.SetLinearVelocity, { x: 3, y: 0, z: 0 });
+}
+
+// Never modify Transform directly for physics entities
+// GAME.Transform.posX[entity] = 10; // ❌ Will be overwritten by Body
+```
+
+##### Apply Forces
+```typescript
+import * as GAME from 'vibegame';
+
+// Apply upward impulse (jump)
+state.addComponent(entity, GAME.ApplyImpulse, {
+  x: 0, y: 50, z: 0
+});
+
+// Apply continuous force
+state.addComponent(entity, GAME.ApplyForce, {
+  x: 10, y: 0, z: 0
+});
+
+// Set velocity directly
+state.addComponent(entity, GAME.SetLinearVelocity, {
+  x: 0, y: 5, z: 0
+});
+```
+
+##### Handle Collisions
+```typescript
+import * as GAME from 'vibegame';
+
+const touchedQuery = GAME.defineQuery([GAME.TouchedEvent]);
+const CollisionSystem: GAME.System = {
+  update: (state) => {
+    // Query entities with collision events
+    for (const entity of touchedQuery(state.world)) {
+      const otherEntity = GAME.TouchedEvent.other[entity];
+      console.log(`Entity ${entity} collided with ${otherEntity}`);
+      
+      // React to collision
+      state.addComponent(entity, GAME.ApplyImpulse, {
+        x: 0, y: 10, z: 0
+      });
+    }
+  }
+};
+```
+
+##### Character Movement
+```typescript
+import * as GAME from 'vibegame';
+
+const PlayerMovementSystem: GAME.System = {
+  update: (state) => {
+    const movementQuery = GAME.defineQuery([GAME.CharacterMovement, GAME.CharacterController]);
+    for (const entity of movementQuery(state.world)) {
+      // Set desired movement based on input
+      GAME.CharacterMovement.desiredVelX[entity] = input.x * 5;
+      GAME.CharacterMovement.desiredVelZ[entity] = input.z * 5;
+      
+      // Jump if grounded
+      if (GAME.CharacterController.grounded[entity] && input.jump) {
+        GAME.CharacterMovement.velocityY[entity] = 10;
+      }
+    }
+  }
+};
+```
+
+##### Custom Plugin Integration
+```typescript
+import * as GAME from 'vibegame';
+
+// Initialize physics before running
+await GAME.initializePhysics();
+
+// Use with builder
+GAME
+  .withPlugin(GAME.PhysicsPlugin)
+  .run();
+```
+
+### Player
+
+Complete player character controller with physics movement, jumping, and platform momentum preservation.
+
+### Components
+
+#### Player
+- speed: f32 (5.3)
+- jumpHeight: f32 (2.3)
+- rotationSpeed: f32 (10)
+- canJump: ui8 (1)
+- isJumping: ui8 (0)
+- jumpCooldown: f32 (0)
+- lastGroundedTime: f32 (0)
+- jumpBufferTime: f32 (-10000)
+- cameraSensitivity: f32 (0.007)
+- cameraZoomSensitivity: f32 (1.5)
+- cameraEntity: eid (0)
+- inheritedVelX: f32 (0) - Horizontal momentum inherited from platform
+- inheritedVelZ: f32 (0) - Horizontal momentum inherited from platform
+
+### Systems
+
+#### PlayerMovementSystem
+- Group: fixed
+- Handles movement, rotation, jumping with platform momentum preservation
+
+#### PlayerGroundedSystem
+- Group: fixed
+- Tracks grounded state, jump availability, and clears inherited momentum on landing
+
+#### PlayerCameraLinkingSystem
+- Group: simulation
+- Links player to orbit camera
+
+#### PlayerCameraControlSystem
+- Group: simulation
+- Camera control via mouse input
+
+### Recipes
+
+#### player
+- Complete player setup with physics
+- Components: player, character-movement, transform, world-transform, body, collider, character-controller, input-state, respawn
+
+### Functions
+
+#### processInput(moveForward, moveRight, cameraYaw): Vector3
+Converts input to world-space movement
+
+#### handleJump(entity, jumpPressed, currentTime): number
+Processes jump with buffering
+
+#### updateRotation(entity, inputVector, deltaTime, rotationData): Quaternion
+Smooth rotation towards movement
+
+#### Examples
+
+## Examples
+
+### Basic Player Usage (XML)
+
+```xml
+<world>
+  <!-- Player auto-created if not specified -->
+  <player pos="0 2 0" speed="6" jump-height="3" />
+</world>
+```
+
+### Custom Player Configuration (XML)
+
+```xml
+<world>
+  <player 
+    pos="5 1 -10"
+    speed="8"
+    jump-height="4"
+    rotation-speed="15"
+    camera-sensitivity="0.005"
+  />
+</world>
+```
+
+### Accessing Player Component (JavaScript)
+
+```typescript
+import * as GAME from 'vibegame';
+
+const playerQuery = GAME.defineQuery([GAME.Player]);
+const MySystem: GAME.System = {
+  update: (state) => {
+    const players = playerQuery(state.world);
+    for (const entity of players) {
+      // Check if player is jumping
+      if (GAME.Player.isJumping[entity]) {
+        console.log('Player is airborne!');
+      }
+      
+      // Modify player speed
+      GAME.Player.speed[entity] = 10;
+    }
+  }
+};
+```
+
+### Creating Player Programmatically
+
+```typescript
+import * as GAME from 'vibegame';
+
+const PlayerSpawnSystem: GAME.System = {
+  setup: (state) => {
+    // Create player entity
+    const player = state.createEntity();
+    
+    // Add player recipe components
+    state.addComponent(player, GAME.Player, {
+      speed: 7,
+      jumpHeight: 3.5,
+      cameraSensitivity: 0.01
+    });
+    
+    // Add required components
+    state.addComponent(player, GAME.Transform, { posY: 5 });
+    state.addComponent(player, GAME.Body, { type: GAME.BodyType.KinematicPositionBased });
+    state.addComponent(player, GAME.CharacterController);
+    state.addComponent(player, GAME.InputState);
+  }
+};
+```
+
+### Movement Controls
+
+**Keyboard:**
+- W/S or Arrow Up/Down - Move forward/backward
+- A/D or Arrow Left/Right - Move left/right 
+- Space - Jump
+
+**Mouse:**
+- Right-click + drag - Rotate camera
+- Scroll wheel - Zoom in/out
+
+### Plugin Registration
+
+```typescript
+import * as GAME from 'vibegame';
+
+GAME
+  .withPlugin(GAME.PlayerPlugin)  // Included in defaults
+  .run();
+```
+
+### Rendering
+
+Three.js rendering pipeline with meshes, lights, cameras, and post-processing effects.
+
+### Components
+
+#### Renderer
+- shape: ui8 - 0=box, 1=sphere, 2=cylinder, 3=plane
+- sizeX, sizeY, sizeZ: f32 (1)
+- color: ui32 (0xffffff)
+- visible: ui8 (1)
+
+#### RenderContext
+- clearColor: ui32 (0x000000)
+- hasCanvas: ui8
+
+#### MainCamera
+Tag component (no properties)
+
+#### Ambient
+- skyColor: ui32 (0x87ceeb)
+- groundColor: ui32 (0x4a4a4a)
+- intensity: f32 (0.6)
+
+#### Directional
+- color: ui32 (0xffffff)
+- intensity: f32 (1)
+- castShadow: ui8 (1)
+- shadowMapSize: ui32 (4096)
+- directionX: f32 (-1)
+- directionY: f32 (2)
+- directionZ: f32 (-1)
+- distance: f32 (30)
+
+#### Bloom
+- intensity: f32 (1.0) - Bloom intensity
+- luminanceThreshold: f32 (1.0) - Luminance threshold for bloom
+- luminanceSmoothing: f32 (0.03) - Smoothness of luminance threshold
+- mipmapBlur: ui8 (1) - Enable mipmap blur
+- radius: f32 (0.85) - Blur radius for mipmap blur
+- levels: ui8 (8) - Number of MIP levels for mipmap blur
+
+#### Dithering
+- colorBits: ui8 (4) - Bits per color channel (1-8)
+- intensity: f32 (1.0) - Effect intensity (0-1)
+- grayscale: ui8 (0) - Enable grayscale mode (0/1)
+- scale: f32 (1.0) - Pattern scale (higher = coarser dithering)
+- noise: f32 (1.0) - Noise threshold intensity
+
+### Systems
+
+#### MeshInstanceSystem
+- Group: draw
+- Synchronizes transforms with Three.js meshes
+
+#### LightSyncSystem
+- Group: draw
+- Updates Three.js lights
+
+#### CameraSyncSystem
+- Group: draw
+- Updates Three.js camera and manages post-processing effects
+
+#### WebGLRenderSystem
+- Group: draw (last)
+- Renders scene through EffectComposer
+
+### Functions
+
+#### setCanvasElement(entity, canvas): void
+Associates canvas with RenderContext
+
+### Recipes
+
+- ambient-light - Ambient hemisphere lighting
+- directional-light - Directional light with shadows
+- light - Both ambient and directional
+
+#### Examples
+
+## Examples
+
+### Basic Rendering Setup
+
+```xml
+<!-- Declarative scene with lighting and rendered objects -->
+<world canvas="#game-canvas" sky="#87ceeb">
+  <!-- Default lighting -->
+  <light></light>
+  
+  <!-- Rendered box -->
+  <entity 
+    transform
+    renderer="shape: box; color: 0xff0000; size-x: 2"
+    pos="0 1 0"
+  />
+  
+  <!-- Rendered sphere -->
+  <entity
+    transform
+    renderer="shape: sphere; color: 0x00ff00"
+    pos="3 1 0"
+  />
+</world>
+```
+
+### Custom Lighting
+
+```xml
+<!-- Separate ambient and directional lights -->
+<ambient-light 
+  sky-color="#ffd4a3"
+  ground-color="#808080"
+  intensity="0.4"
+/>
+
+<directional-light
+  color="#ffffff"
+  intensity="1.5"
+  direction-x="-1"
+  direction-y="3"
+  direction-z="-0.5"
+  cast-shadow="1"
+  shadow-map-size="2048"
+/>
+```
+
+### Imperative Usage
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Create rendered entity programmatically
+const entity = state.createEntity();
+
+// Add transform for positioning
+state.addComponent(entity, GAME.Transform, {
+  posX: 0, posY: 5, posZ: 0
+});
+
+// Add renderer component
+state.addComponent(entity, GAME.Renderer, {
+  shape: 1,        // sphere
+  sizeX: 2,
+  sizeY: 2,
+  sizeZ: 2,
+  color: 0xff00ff,
+  visible: 1
+});
+
+// Set canvas for rendering context
+const contextQuery = GAME.defineQuery([GAME.RenderContext]);
+const contextEntity = contextQuery(state.world)[0];
+const canvas = document.getElementById('game-canvas');
+GAME.setCanvasElement(contextEntity, canvas);
+```
+
+### Shape Types
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Available shape enums
+const shapes = {
+  box: 0,
+  sphere: 1,
+  cylinder: 2,
+  plane: 3
+};
+
+// Use in XML
+<entity renderer="shape: sphere"></entity>
+
+// Or with enum names
+<entity renderer="shape: 1"></entity>
+```
+
+### Visibility Control
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Hide/show entities
+GAME.Renderer.visible[entity] = 0; // Hide
+GAME.Renderer.visible[entity] = 1; // Show
+
+// In XML
+<entity renderer="visible: 0"></entity>  <!-- Initially hidden -->
+```
+
+### Post-Processing Effects
+
+```xml
+<!-- Camera with bloom effect (using defaults) -->
+<camera bloom></camera>
+
+<!-- Camera with custom bloom settings -->
+<camera bloom="intensity: 2; luminance-threshold: 0.8; luminance-smoothing: 0.05"></camera>
+
+<!-- Camera with mipmap blur settings -->
+<camera bloom="mipmap-blur: 1; radius: 0.9; levels: 10"></camera>
+
+<!-- Camera without effects (still uses composer internally) -->
+<camera></camera>
+
+<!-- Camera with retro dithering effect -->
+<camera dithering="color-bits: 3; intensity: 0.8; scale: 2"></camera>
+
+<!-- Combined bloom and dithering for retro aesthetic -->
+<camera bloom="intensity: 1.5" dithering="color-bits: 2; grayscale: 1; scale: 3"></camera>
+
+<!-- Subtle dithering for vintage look -->
+<camera dithering="color-bits: 5; intensity: 0.5; scale: 1"></camera>
+
+<!-- Coarse pixel-art style dithering -->
+<camera dithering="color-bits: 2; scale: 4; intensity: 1"></camera>
+```
+
+### Respawn
+
+Automatic respawn system that resets entities when falling below Y=-100.
+
+### Components
+
+#### Respawn
+- posX, posY, posZ: f32 - Spawn position
+- eulerX, eulerY, eulerZ: f32 - Spawn rotation (degrees)
+
+### Systems
+
+#### RespawnSystem
+- Group: simulation
+- Resets entities when Y < -100
+
+#### Examples
+
+## Examples
+
+### Player with Respawn (Automatic)
+
+The `<player>` recipe automatically includes respawn:
+
+```xml
+<world>
+  <!-- Player spawns at 0,5,0 and respawns there if falling -->
+  <player pos="0 5 0"></player>
+</world>
+```
+
+### Manual Respawn Component
+
+```xml
+<entity transform body collider respawn="pos: 0 10 -5">
+  <!-- Entity respawns at 0,10,-5 when falling below Y=-100 -->
+</entity>
+```
+
+### Imperative Usage
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Add respawn to an entity
+const entity = state.createEntity();
+
+// Set spawn point from current transform
+state.addComponent(entity, GAME.Transform, {
+  posX: 0, posY: 10, posZ: 0,
+  eulerX: 0, eulerY: 0, eulerZ: 0
+});
+
+state.addComponent(entity, GAME.Respawn, {
+  posX: 0, posY: 10, posZ: 0,
+  eulerX: 0, eulerY: 0, eulerZ: 0
+});
+
+// Entity will respawn at (0,10,0) when falling
+```
+
+### Update Spawn Point
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Change respawn position dynamically
+GAME.Respawn.posX[entity] = 20;
+GAME.Respawn.posY[entity] = 5;
+GAME.Respawn.posZ[entity] = -10;
+```
+
+### XML with Transform Sync
+
+Position attributes automatically populate the respawn component:
+
+```xml
+<!-- Position sets both transform and respawn -->
+<player pos="5 3 -2" euler="0 90 0"></player>
+```
+
+### Startup
+
+Auto-creates player, camera, and lighting entities at startup if missing.
+
+### Systems
+
+#### LightingStartupSystem
+- Group: setup
+- Creates default lighting if none exists
+
+#### CameraStartupSystem
+- Group: setup
+- Creates main camera if none exists
+
+#### PlayerStartupSystem
+- Group: setup
+- Creates player entity if none exists
+
+#### PlayerCharacterSystem
+- Group: setup
+- Adds animated character to players
+
+#### Examples
+
+## Examples
+
+### Basic Usage (Auto-Creation)
+
+```typescript
+// The plugin automatically creates defaults when included
+import * as GAME from 'vibegame';
+
+// This will create player, camera, and lighting automatically
+GAME.run(); // Uses DefaultPlugins which includes StartupPlugin
+```
+
+### Preventing Auto-Creation with XML
+
+```xml
+<world>
+  <!-- Creating your own player prevents auto-creation -->
+  <player pos="10 2 -5" speed="12" />
+  
+  <!-- Creating custom lighting prevents default lights -->
+  <entity ambient="sky-color: 0xff0000" directional />
+</world>
+```
+
+### Manual Plugin Registration
+
+```typescript
+import * as GAME from 'vibegame';
+
+// Use startup plugin without other defaults
+GAME.withoutDefaultPlugins()
+  .withPlugin(GAME.TransformsPlugin)
+  .withPlugin(GAME.RenderingPlugin) 
+  .withPlugin(GAME.StartupPlugin)
+  .run();
+```
+
+### System Behavior
+
+The startup systems are idempotent - they check for existing entities before creating:
+
+```typescript
+import * as GAME from 'vibegame';
+
+// First run: Creates player, camera, lights
+const playerQuery = GAME.defineQuery([GAME.Player]);
+playerQuery(state.world).length // 0 -> creates player
+
+// Subsequent runs: Skips creation
+playerQuery(state.world).length // 1 -> skips creation
+```
+
+### Transforms
+
+3D transforms with position, rotation, scale, and parent-child hierarchies.
+
+### Components
+
+#### Transform
+- posX, posY, posZ: f32 (0)
+- rotX, rotY, rotZ, rotW: f32 (rotW=1) - Quaternion
+- eulerX, eulerY, eulerZ: f32 (0) - Degrees
+- scaleX, scaleY, scaleZ: f32 (1)
+
+#### WorldTransform
+- Same properties as Transform
+- Auto-computed from hierarchy (read-only)
+
+### Systems
+
+#### TransformHierarchySystem
+- Group: simulation (last)
+- Syncs euler/quaternion and computes world transforms
+
+#### Examples
+
+## Examples
+
+### Basic Usage
+
+#### XML Position and Rotation
+```xml
+<!-- Position only -->
+<entity transform="pos: 0 5 -3"></entity>
+
+<!-- Euler rotation (degrees) -->
+<entity transform="euler: 0 45 0"></entity>
+
+<!-- Scale (single value applies to all axes) -->
+<entity transform="scale: 2"></entity>
+
+<!-- Combined transform -->
+<entity transform="pos: 0 5 0; euler: 0 45 0; scale: 1.5"></entity>
+```
+
+#### JavaScript API
+```typescript
+import * as GAME from 'vibegame';
+
+// In a system
+const MySystem = {
+  update: (state) => {
+    const entity = state.createEntity();
+    
+    // Add transform component with initial values
+    state.addComponent(entity, GAME.Transform, {
+      posX: 10, posY: 5, posZ: -3,
+      eulerX: 0, eulerY: 45, eulerZ: 0,
+      scaleX: 2, scaleY: 2, scaleZ: 2
+    });
+    
+    // Transform system automatically syncs euler to quaternion
+  }
+};
+```
+
+### Transform Hierarchy
+
+#### Parent-Child Relationships
+```xml
+<!-- Parent at origin -->
+<entity transform="pos: 0 0 0">
+  <!-- Children positioned relative to parent -->
+  <entity transform="pos: 2 0 0"></entity>
+  <entity transform="pos: -2 0 0"></entity>
+</entity>
+
+<!-- Rotating parent affects all children -->
+<entity transform="euler: 0 45 0">
+  <entity id="arm" transform="pos: 0 2 0">
+    <entity id="hand" transform="pos: 0 2 0"></entity>
+  </entity>
+</entity>
+```
+
+#### Accessing World Transform
+```typescript
+import * as GAME from 'vibegame';
+
+const transformQuery = GAME.defineQuery([GAME.Transform, GAME.WorldTransform]);
+const WorldTransformSystem = {
+  update: (state) => {
+    // Query entities with both transforms
+    const entities = transformQuery(state.world);
+    
+    for (const entity of entities) {
+      // Local position
+      const localX = GAME.Transform.posX[entity];
+      
+      // World position (after parent transforms)
+      const worldX = GAME.WorldTransform.posX[entity];
+      
+      console.log(`Local: ${localX}, World: ${worldX}`);
+    }
+  }
+};
+```
+
+### Common Patterns
+
+#### Setting Transform Values
+```typescript
+import * as GAME from 'vibegame';
+
+// Direct property access (bitECS style)
+GAME.Transform.posX[entity] = 10;
+GAME.Transform.posY[entity] = 5;
+GAME.Transform.posZ[entity] = -3;
+
+// Using euler angles for rotation
+GAME.Transform.eulerX[entity] = 0;
+GAME.Transform.eulerY[entity] = 45;
+GAME.Transform.eulerZ[entity] = 0;
+// Quaternion will be auto-synced by TransformHierarchySystem
+
+// Uniform scale
+GAME.Transform.scaleX[entity] = 2;
+GAME.Transform.scaleY[entity] = 2;
+GAME.Transform.scaleZ[entity] = 2;
+```
+
+#### Transform Interpolation
+```typescript
+import * as GAME from 'vibegame';
+
+// Interpolate between two positions
+const t = 0.5; // 50% between start and end
+GAME.Transform.posX[entity] = startX + (endX - startX) * t;
+GAME.Transform.posY[entity] = startY + (endY - startY) * t;
+GAME.Transform.posZ[entity] = startZ + (endZ - startZ) * t;
+```
+
+### Tweening
+
+Animates component properties with easing functions and loop modes. Kinematic velocity bodies use velocity-based tweening for smooth physics-correct movement.
+
+### Components
+
+#### Tween
+- duration: f32 (1) - Seconds
+- elapsed: f32
+- easingIndex: ui8
+- loopMode: ui8 - 0=Once, 1=Loop, 2=PingPong
+
+#### TweenValue
+- source: ui32 - Tween entity
+- target: ui32 - Target entity
+- componentId: ui32
+- fieldIndex: ui32
+- from: f32
+- to: f32
+- value: f32 - Current value
+
+#### KinematicTween
+- tweenEntity: ui32 - Associated tween entity
+- targetEntity: ui32 - Kinematic body entity
+- axis: ui8 - 0=X, 1=Y, 2=Z
+- from: f32 - Start position
+- to: f32 - End position
+- lastPosition: f32
+- targetPosition: f32
+
+### Systems
+
+#### KinematicTweenSystem
+- Group: fixed
+- Converts position tweens to velocity for kinematic bodies
+
+#### TweenSystem
+- Group: simulation
+- Interpolates values with easing and auto-cleanup
+
+### Functions
+
+#### createTween(state, entity, target, options): number | null
+Animates component property
+
+### Easing Functions
+
+- linear
+- sine-in, sine-out, sine-in-out
+- quad-in, quad-out, quad-in-out
+- cubic-in, cubic-out, cubic-in-out
+- quart-in, quart-out, quart-in-out
+- expo-in, expo-out, expo-in-out
+- circ-in, circ-out, circ-in-out
+- back-in, back-out, back-in-out
+- elastic-in, elastic-out, elastic-in-out
+- bounce-in, bounce-out, bounce-in-out
+
+### Loop Modes
+
+- once - Play once and destroy
+- loop - Repeat indefinitely
+- ping-pong - Alternate directions
+
+### Shorthand Targets
+
+- rotation - body.eulerX/Y/Z
+- at - body.posX/Y/Z
+- scale - transform.scaleX/Y/Z
+
+#### Examples
+
+## Examples
+
+### Basic XML Tween
+
+```xml
+<!-- Animate Y position from 5 to 10 over 2 seconds -->
+<kinematic-part pos="0 5 -5">
+  <tween 
+    target="body.pos-y" 
+    from="5" 
+    to="10" 
+    duration="2" 
+    ease="sine-in-out" 
+    loop="ping-pong"
+  />
+</kinematic-part>
+```
+
+### Multiple Properties
+
+```xml
+<!-- Animate rotation on all axes -->
+<entity transform renderer>
+  <tween 
+    target="rotation" 
+    to="0 360 0" 
+    duration="4" 
+    loop="loop"
+  />
+</entity>
+```
+
+### Body Physics Properties
+
+```xml
+<!-- Animate physics body velocity -->
+<dynamic-part pos="0 10 0">
+  <tween 
+    target="body.velocity-x" 
+    from="0" 
+    to="10" 
+    duration="1" 
+    ease="quad-out"
+  />
+</tween>
+```
+
+### Programmatic Usage
+
+```typescript
+import * as GAME from 'vibegame';
+
+// In a system
+const MySystem = {
+  setup: (state) => {
+    const entity = state.createEntity();
+    state.addComponent(entity, GAME.Transform);
+    
+    // Create tween programmatically
+    GAME.createTween(state, entity, 'body.pos-y', {
+      from: 0,
+      to: 10,
+      duration: 2,
+      easing: 'bounce-out',
+      loop: 'once'
+    });
+  }
+};
+```
+
+### Complex Animation Sequence
+
+```xml
+<!-- Platform with multiple animated properties -->
+<kinematic-part pos="0 0 0" color="#ff0000">
+  <!-- Position animation -->
+  <tween target="body.pos-x" from="-5" to="5" duration="3" loop="ping-pong"></tween>
+  <!-- Rotation animation -->
+  <tween target="body.euler-y" to="360" duration="10" loop="loop"></tween>
+  <!-- Scale pulse -->
+  <tween target="transform.scale-x" from="1" to="1.5" duration="1" ease="sine-in-out" loop="ping-pong"></tween>
+  <tween target="transform.scale-z" from="1" to="1.5" duration="1" ease="sine-in-out" loop="ping-pong"></tween>
+</kinematic-part>
+```
+
+### Ui
+
+Web-native UI system using HTML/CSS overlays positioned over the 3D canvas. Includes GSAP for animations, ECS state synchronization, and external library support. This provides capabilities superior to most game engines' built-in UI systems.
+
+### Components
+
+#### UIManager
+- element: HTMLElement - Root UI container
+- state: State - ECS state reference for updates
+- visible: ui8 (1) - UI visibility toggle
+
+### Systems
+
+#### UIUpdateSystem
+- Group: simulation
+- Updates UI elements from ECS component state
+
+#### UIEventSystem
+- Group: setup
+- Handles UI event binding and canvas focus management
+
+### Functions
+
+#### createUIOverlay(canvas: HTMLCanvasElement): HTMLElement
+Creates positioned UI overlay container
+
+#### bindUIToState(uiManager: UIManager, state: State): void
+Connects UI updates to ECS state changes
+
+#### showFloatingText(x: number, y: number, text: string): void
+Creates animated floating text at screen coordinates
+
+### Patterns
+
+#### Basic UI Setup
+```html
+<div id="game-ui">
+  <div class="hud">
+    <span id="score">0</span>
+    <span id="health">100</span>
+  </div>
+</div>
+```
+
+#### ECS Integration
+```typescript
+const UISystem = {
+  update: (state) => {
+    // Update UI from game state components
+    const scoreEl = document.getElementById('score');
+    if (scoreEl) scoreEl.textContent = getScore(state);
+  }
+};
+```
+
+#### GSAP Animations
+```typescript
+gsap.to("#currency", {
+  scale: 1.2,
+  duration: 0.2,
+  yoyo: true,
+  repeat: 1
+});
+```
+
+#### Examples
+
+## Examples
+
+### Basic Game HUD
+
+```html
+<!doctype html>
+<html>
+<head>
+  <style>
+    body { margin: 0; font-family: Arial; }
+    #game-ui {
+      position: fixed;
+      top: 0;
+      left: 0;
+      right: 0;
+      bottom: 0;
+      pointer-events: none;
+      z-index: 1000;
+    }
+    .hud {
+      position: absolute;
+      top: 20px;
+      left: 20px;
+      background: rgba(0,0,0,0.7);
+      padding: 15px;
+      border-radius: 8px;
+      color: white;
+      pointer-events: auto;
+    }
+  </style>
+</head>
+<body>
+  <world canvas="#game-canvas">
+    <static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"></static-part>
+  </world>
+
+  <canvas id="game-canvas"></canvas>
+
+  <div id="game-ui">
+    <div class="hud">
+      <div>Score: <span id="score">0</span></div>
+      <div>Coins: <span id="coins">0</span></div>
+    </div>
+  </div>
+
+  <script type="module">
+    import * as GAME from 'vibegame';
+
+    const GameState = GAME.defineComponent({
+      score: GAME.Types.ui32,
+      coins: GAME.Types.ui32
+    });
+
+    const UISystem = {
+      update: (state) => {
+        const query = GAME.defineQuery([GameState]);
+        const entities = query(state.world);
+
+        if (entities.length > 0) {
+          const entity = entities[0];
+          document.getElementById('score').textContent = GameState.score[entity];
+          document.getElementById('coins').textContent = GameState.coins[entity];
+        }
+      }
+    };
+
+    GAME.withPlugin({
+      components: { GameState },
+      systems: [UISystem]
+    }).run();
+  </script>
+</body>
+</html>
+```
+
+### Animated Currency with GSAP
+
+```javascript
+import gsap from 'gsap';
+
+class AnimatedCounter {
+  constructor(elementId) {
+    this.element = document.getElementById(elementId);
+    this.currentValue = 0;
+    this.displayValue = 0;
+  }
+
+  setValue(newValue) {
+    this.currentValue = newValue;
+
+    gsap.to(this, {
+      displayValue: newValue,
+      duration: 0.8,
+      ease: "power2.out",
+      onUpdate: () => {
+        this.element.textContent = Math.floor(this.displayValue);
+      }
+    });
+  }
+}
+
+// Usage in ECS system
+const coinCounter = new AnimatedCounter('coins');
+
+const UISystem = {
+  update: (state) => {
+    const coins = getCoinsFromState(state);
+    coinCounter.setValue(coins);
+  }
+};
+```
+
+### Floating Damage Text
+
+```javascript
+function showDamageText(worldX, worldY, worldZ, damage) {
+  // Convert 3D world position to screen coordinates
+  const camera = getMainCamera(state);
+  const screenPos = worldToScreen(worldX, worldY, worldZ, camera);
+
+  const element = document.createElement('div');
+  element.textContent = `-${damage}`;
+  element.style.cssText = `
+    position: fixed;
+    left: ${screenPos.x}px;
+    top: ${screenPos.y}px;
+    color: #ff4444;
+    font-weight: bold;
+    font-size: 24px;
+    pointer-events: none;
+    z-index: 10000;
+  `;
+
+  document.body.appendChild(element);
+
+  gsap.timeline()
+    .to(element, {
+      y: screenPos.y - 100,
+      opacity: 0,
+      duration: 1.5,
+      ease: "power2.out"
+    })
+    .call(() => element.remove());
+}
+
+// Usage in collision system
+const DamageSystem = {
+  update: (state) => {
+    // When player takes damage
+    const playerPos = getPlayerPosition(state);
+    showDamageText(playerPos.x, playerPos.y + 2, playerPos.z, 25);
+  }
+};
+```
+
+### Menu System with State
+
+```javascript
+class GameMenu {
+  constructor() {
+    this.isOpen = false;
+    this.element = document.getElementById('main-menu');
+  }
+
+  toggle() {
+    this.isOpen = !this.isOpen;
+
+    if (this.isOpen) {
+      this.show();
+    } else {
+      this.hide();
+    }
+  }
+
+  show() {
+    this.element.style.display = 'block';
+    gsap.fromTo(this.element,
+      { opacity: 0, scale: 0.8 },
+      { opacity: 1, scale: 1, duration: 0.3, ease: "back.out(1.7)" }
+    );
+  }
+
+  hide() {
+    gsap.to(this.element, {
+      opacity: 0,
+      scale: 0.8,
+      duration: 0.2,
+      onComplete: () => {
+        this.element.style.display = 'none';
+      }
+    });
+  }
+}
+
+// Integration with input system
+const menu = new GameMenu();
+
+const MenuSystem = {
+  update: (state) => {
+    // Check for escape key press
+    if (GAME.consumeInput(state, 'escape')) {
+      menu.toggle();
+    }
+  }
+};
+```

package.json

@@ -9,6 +9,8 @@
     "check": "tsc --noEmit && svelte-check",
     "check:ts": "tsc --noEmit",
     "check:svelte": "svelte-check",
+    "update": "cp node_modules/vibegame/llms.txt ./llms.txt && echo '✓ Updated llms.txt from vibegame'",
+    "postinstall": "test -f node_modules/vibegame/llms.txt && cp node_modules/vibegame/llms.txt ./llms.txt || true",
     "test": "bun test",
     "test:watch": "bun test --watch",
     "format": "prettier --write .",
@@ -43,13 +45,12 @@
     "@langchain/mcp-adapters": "^0.6.0",
     "@modelcontextprotocol/sdk": "^0.6.0",
     "@modelcontextprotocol/server-filesystem": "^0.6.2",
-    "@types/marked": "^6.0.0",
     "@types/node": "^24.3.3",
     "gsap": "^3.13.0",
-    "marked": "^16.2.1",
+    "htmlparser2": "^10.0.0",
     "monaco-editor": "^0.50.0",
     "svelte-splitpanes": "^8.0.5",
-    "vibegame": "^0.1.7",
+    "vibegame": "^0.1.9",
     "zod": "^4.1.8"
   }
 }

src/App.svelte

@@ -2,10 +2,12 @@
     import { onMount, onDestroy } from 'svelte';
     import { registerShortcuts, shortcuts } from './lib/config/shortcuts';
     import { loadingStore } from './lib/stores/loading';
+    import { uiStore } from './lib/stores/ui';
     import { contentManager } from './lib/services/content-manager';
     import AppHeader from './lib/components/layout/AppHeader.svelte';
     import SplitView from './lib/components/layout/SplitView.svelte';
     import LoadingScreen from './lib/components/layout/LoadingScreen.svelte';
+    import About from './lib/components/about/About.svelte';
 
     let unregisterShortcuts: () => void;
 
@@ -39,7 +41,11 @@
 
 <main>
     <AppHeader />
-    <SplitView />
+    {#if $uiStore.viewMode === 'about'}
+        <About />
+    {:else}
+        <SplitView />
+    {/if}
 </main>
 
 <style>

src/lib/components/about/About.svelte

@@ -0,0 +1,310 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { uiStore } from '../../stores/ui';
+  import gsap from 'gsap';
+
+  onMount(() => {
+    gsap.fromTo('.about-container',
+      { opacity: 0, scale: 0.95 },
+      { opacity: 1, scale: 1, duration: 0.3, ease: 'power2.out' }
+    );
+  });
+
+  function handleClose() {
+    uiStore.hideAbout();
+  }
+</script>
+
+<div class="about-container">
+  <div class="about-content">
+    <button class="close-button" on:click={handleClose} aria-label="Close">
+      <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+        <path d="M8 8.707l3.646 3.647.708-.708L8.707 8l3.647-3.646-.708-.708L8 7.293 4.354 3.646l-.708.708L7.293 8l-3.647 3.646.708.708L8 8.707z"/>
+      </svg>
+    </button>
+
+    <div class="about-header">
+      <h1>
+        <span class="app-icon">🥕</span>
+        VibeGame
+      </h1>
+      <p class="tagline">A 3D game engine designed for vibe coding</p>
+    </div>
+
+    <div class="about-body">
+      <p class="description">
+        AI-assisted game development with declarative HTML-like syntax, ECS architecture, and built-in physics/rendering.
+        Create 3D games with real-time feedback and scale from prototypes to complex projects.
+      </p>
+
+      <div class="features-grid">
+        <div class="feature">
+          <strong>Declarative</strong>
+          <span>HTML-like tags</span>
+        </div>
+        <div class="feature">
+          <strong>ECS</strong>
+          <span>Clean architecture</span>
+        </div>
+        <div class="feature">
+          <strong>Physics</strong>
+          <span>Rapier built-in</span>
+        </div>
+        <div class="feature">
+          <strong>Rendering</strong>
+          <span>Three.js powered</span>
+        </div>
+        <div class="feature">
+          <strong>Live Edit</strong>
+          <span>Real-time feedback</span>
+        </div>
+        <div class="feature">
+          <strong>AI-Ready</strong>
+          <span>LangGraph.js</span>
+        </div>
+      </div>
+
+      <div class="quick-start">
+        <h3>Quick Start</h3>
+        <pre><code>&lt;world canvas="#game-canvas" sky="#87ceeb"&gt;
+  &lt;!-- Ground --&gt;
+  &lt;static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"&gt;&lt;/static-part&gt;
+
+  &lt;!-- Ball --&gt;
+  &lt;dynamic-part pos="-2 4 -3" shape="sphere" size="1" color="#ff4500"&gt;&lt;/dynamic-part&gt;
+&lt;/world&gt;
+
+&lt;canvas id="game-canvas"&gt;&lt;/canvas&gt;
+
+&lt;script type="module"&gt;
+  import * as GAME from 'vibegame';
+  GAME.run();
+&lt;/script&gt;</code></pre>
+      </div>
+
+      <div class="links">
+        <a href="https://github.com/dylanebert/VibeGame" target="_blank" rel="noopener noreferrer" class="link">
+          <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor">
+            <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/>
+          </svg>
+          GitHub
+        </a>
+        <a href="https://www.npmjs.com/package/vibegame" target="_blank" rel="noopener noreferrer" class="link">
+          NPM
+        </a>
+        <a href="https://huggingface.co/spaces/dylanebert/VibeGame" target="_blank" rel="noopener noreferrer" class="link">
+          Demo
+        </a>
+        <a href="https://jsfiddle.net/zhLtd6e2/6/" target="_blank" rel="noopener noreferrer" class="link">
+          JSFiddle
+        </a>
+      </div>
+    </div>
+  </div>
+</div>
+
+<style>
+  .about-container {
+    width: 100%;
+    height: calc(100vh - 40px);
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    background: linear-gradient(135deg, #0B0A09 0%, #0F0E0C 100%);
+    padding: 1rem;
+  }
+
+  .about-content {
+    position: relative;
+    max-width: 860px;
+    width: 100%;
+    background: rgba(15, 14, 12, 0.95);
+    border: 1px solid rgba(139, 115, 85, 0.2);
+    border-radius: 0.75rem;
+    padding: 2.5rem;
+    max-height: calc(100vh - 60px);
+    overflow-y: auto;
+  }
+
+  .close-button {
+    position: absolute;
+    top: 1rem;
+    right: 1rem;
+    background: transparent;
+    border: none;
+    color: rgba(251, 248, 244, 0.5);
+    cursor: pointer;
+    padding: 0.25rem;
+    border-radius: 0.25rem;
+    transition: all 0.2s;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .close-button:hover {
+    color: rgba(251, 248, 244, 0.9);
+    background: rgba(139, 115, 85, 0.1);
+  }
+
+  .about-header {
+    text-align: center;
+    margin-bottom: 1.5rem;
+    padding-bottom: 1rem;
+    border-bottom: 1px solid rgba(139, 115, 85, 0.15);
+  }
+
+  .about-header h1 {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+    font-size: 1.75rem;
+    color: rgba(251, 248, 244, 0.95);
+    margin: 0 0 0.25rem 0;
+  }
+
+  .app-icon {
+    font-size: 1.75rem;
+  }
+
+  .tagline {
+    font-size: 1rem;
+    color: rgba(251, 248, 244, 0.7);
+    margin: 0;
+  }
+
+  .about-body {
+    display: flex;
+    flex-direction: column;
+    gap: 1.5rem;
+  }
+
+  .description {
+    font-size: 0.9375rem;
+    line-height: 1.6;
+    color: rgba(251, 248, 244, 0.8);
+    margin: 0;
+  }
+
+  .features-grid {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    gap: 0.75rem;
+  }
+
+  .feature {
+    background: rgba(139, 115, 85, 0.06);
+    border: 1px solid rgba(139, 115, 85, 0.12);
+    border-radius: 0.375rem;
+    padding: 0.75rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    transition: all 0.2s;
+  }
+
+  .feature:hover {
+    background: rgba(139, 115, 85, 0.1);
+    border-color: rgba(124, 152, 133, 0.2);
+  }
+
+  .feature strong {
+    font-size: 0.875rem;
+    color: rgba(251, 248, 244, 0.9);
+    font-weight: 600;
+  }
+
+  .feature span {
+    font-size: 0.75rem;
+    color: rgba(251, 248, 244, 0.65);
+  }
+
+  .quick-start {
+    background: rgba(15, 14, 12, 0.6);
+    border: 1px solid rgba(139, 115, 85, 0.15);
+    border-radius: 0.375rem;
+    padding: 1rem;
+  }
+
+  .quick-start h3 {
+    font-size: 1rem;
+    color: rgba(251, 248, 244, 0.9);
+    margin: 0 0 0.75rem 0;
+    font-weight: 600;
+  }
+
+  .quick-start pre {
+    margin: 0;
+    background: rgba(0, 0, 0, 0.3);
+    padding: 0.875rem;
+    border-radius: 0.375rem;
+    overflow-x: auto;
+  }
+
+  .quick-start code {
+    font-family: 'Monaco', 'Courier New', monospace;
+    font-size: 0.8125rem;
+    color: #7C9885;
+    line-height: 1.5;
+    white-space: pre;
+  }
+
+  .links {
+    display: flex;
+    gap: 0.5rem;
+    flex-wrap: wrap;
+  }
+
+  .link {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+    padding: 0.625rem 1rem;
+    background: rgba(139, 115, 85, 0.08);
+    border: 1px solid rgba(139, 115, 85, 0.2);
+    border-radius: 0.375rem;
+    color: rgba(251, 248, 244, 0.85);
+    text-decoration: none;
+    font-size: 0.875rem;
+    font-weight: 500;
+    transition: all 0.2s;
+  }
+
+  .link:hover {
+    background: rgba(124, 152, 133, 0.15);
+    border-color: rgba(124, 152, 133, 0.3);
+    color: rgba(251, 248, 244, 0.95);
+    transform: translateY(-1px);
+  }
+
+  .link svg {
+    width: 14px;
+    height: 14px;
+  }
+
+  /* Scrollbar */
+  .about-content::-webkit-scrollbar {
+    width: 6px;
+  }
+
+  .about-content::-webkit-scrollbar-track {
+    background: rgba(139, 115, 85, 0.05);
+    border-radius: 3px;
+  }
+
+  .about-content::-webkit-scrollbar-thumb {
+    background: rgba(139, 115, 85, 0.2);
+    border-radius: 3px;
+  }
+
+  .about-content::-webkit-scrollbar-thumb:hover {
+    background: rgba(139, 115, 85, 0.3);
+  }
+
+  @media (max-width: 600px) {
+    .features-grid {
+      grid-template-columns: repeat(2, 1fr);
+    }
+  }
+</style>

src/lib/components/about/context.md

@@ -0,0 +1,31 @@
+# About Component
+
+Project information display
+
+## Purpose
+
+- Display project overview and features
+- Provide quick start example
+- Link to resources (GitHub, NPM, demos)
+- Modal-style overlay presentation
+
+## Structure
+
+```
+about/
+├── context.md        # This file
+└── About.svelte      # Project info modal
+```
+
+## Features
+
+- Compact card layout with 860px max width
+- Feature grid (3 columns)
+- Full Quick Start code example
+- Resource links to GitHub, NPM, Demo, JSFiddle
+- Close via X button, About toggle, or title click
+
+## Dependencies
+
+- uiStore for view mode control
+- GSAP for fade animation

src/lib/components/chat/ChatPanel.svelte

@@ -4,6 +4,7 @@
   import gsap from "gsap";
   import MessageList from "./MessageList.svelte";
   import MessageInput from "./MessageInput.svelte";
+  import ExampleRow from "./ExampleRow.svelte";
   import { isConnected, isProcessing, messages, error } from "../../stores/chat-store";
   import { chatController } from "../../controllers/chat-controller";
   import { authStore } from "../../services/auth";
@@ -118,6 +119,11 @@
     {/if}
   </div>
 
+  <ExampleRow
+    onSendMessage={handleExampleMessage}
+    visible={$messages.length === 0 && $authStore.isAuthenticated && $isConnected}
+  />
+
   <MessageInput
     bind:value={inputValue}
     placeholder={!$authStore.isAuthenticated
@@ -140,8 +146,8 @@
     flex-direction: column;
     height: 100%;
     width: 100%;
-    background: rgba(8, 7, 6, 0.4);
-    border-top: 1px solid rgba(139, 115, 85, 0.06);
+    background: rgba(12, 11, 10, 0.85);
+    border-top: 1px solid rgba(139, 115, 85, 0.12);
     position: relative;
   }
 
@@ -150,8 +156,8 @@
     justify-content: space-between;
     align-items: center;
     padding: 10px 16px;
-    background: rgba(15, 14, 12, 0.3);
-    border-bottom: 1px solid rgba(139, 115, 85, 0.06);
+    background: rgba(18, 17, 16, 0.6);
+    border-bottom: 1px solid rgba(139, 115, 85, 0.15);
     flex-shrink: 0;
   }
 
@@ -159,7 +165,7 @@
     margin: 0;
     font-size: 11px;
     font-weight: 500;
-    color: rgba(251, 248, 244, 0.5);
+    color: rgba(251, 248, 244, 0.7);
     text-transform: uppercase;
     letter-spacing: 0.5px;
   }
@@ -169,9 +175,9 @@
 
   .clear-button {
     padding: 4px 10px;
-    background: rgba(139, 115, 85, 0.03);
-    color: rgba(251, 248, 244, 0.4);
-    border: 1px solid rgba(139, 115, 85, 0.08);
+    background: rgba(139, 115, 85, 0.08);
+    color: rgba(251, 248, 244, 0.55);
+    border: 1px solid rgba(139, 115, 85, 0.15);
     border-radius: 4px;
     font-size: 10px;
     font-weight: 500;
@@ -185,9 +191,9 @@
   }
 
   .clear-button:hover {
-    background: rgba(139, 115, 85, 0.06);
-    color: rgba(251, 248, 244, 0.6);
-    border-color: rgba(139, 115, 85, 0.12);
+    background: rgba(139, 115, 85, 0.12);
+    color: rgba(251, 248, 244, 0.75);
+    border-color: rgba(139, 115, 85, 0.2);
   }
 
   .clear-button:active {

src/lib/components/chat/ExampleMessages.svelte

@@ -1,183 +1,152 @@
 <script lang="ts">
-  import { onMount, onDestroy } from "svelte";
   import { fade } from "svelte/transition";
-  import gsap from "gsap";
-
-  export let onSendMessage: (message: string) => void;
-
-  const examples = [
-    { icon: "🏀", text: "add another ball" },
-    { icon: "📝", text: "explain what the code does" },
-    { icon: "🎮", text: "make an obby" },
-    { icon: "⬆️", text: "increase the player jump height" }
-  ];
-
-  let exampleCards: HTMLButtonElement[] = [];
-
-  onMount(() => {
-    exampleCards.forEach((card, index) => {
-      if (!card) return;
-
-      gsap.fromTo(card, {
-        opacity: 0,
-        y: 15,
-        scale: 0.97
-      }, {
-        opacity: 1,
-        y: 0,
-        scale: 1,
-        duration: 0.2,
-        delay: index * 0.02,
-        ease: "power3.out"
-      });
-    });
-  });
+</script>
 
-  onDestroy(() => {
-    exampleCards.forEach((card) => {
-      if (card) {
-        gsap.killTweensOf(card);
-      }
-    });
-  });
+<div class="warning-container" transition:fade={{ duration: 200 }}>
+  <div class="model-warning">
+    <div class="warning-badge">
+      <span class="warning-icon">⚠️</span>
+      <span class="warning-label">Model Limitations</span>
+    </div>
+    <p class="warning-text">
+      This demo uses <a href="https://huggingface.co/Qwen/Qwen3-Next-80B-A3B-Instruct" target="_blank" rel="noopener">Qwen3-Next-80B-A3B-Instruct</a>.
+      <br />
+      For complex tasks, run locally with frontier code agents like Claude Code.
+    </p>
+    <a href="https://github.com/dylanebert/VibeGame" target="_blank" rel="noopener" class="warning-link">
+      <span>Learn More</span>
+      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M7 17L17 7M17 7H7M17 7V17" />
+      </svg>
+    </a>
+  </div>
+</div>
 
-  function handleClick(text: string) {
-    onSendMessage(text);
+<style>
+  .warning-container {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 100%;
+    padding: 2rem 1rem;
   }
 
-  function handleMouseEnter(event: MouseEvent) {
-    const card = event.currentTarget as HTMLButtonElement;
-    gsap.to(card, {
-      scale: 1.03,
-      boxShadow: "0 6px 24px rgba(65, 105, 225, 0.25)",
-      borderColor: "rgba(65, 105, 225, 0.5)",
-      duration: 0.08,
-      ease: "power2.out"
-    });
+  .model-warning {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 1rem;
+    padding: 1.5rem;
+    background: rgba(255, 255, 255, 0.01);
+    border: 1px solid rgba(255, 255, 255, 0.06);
+    border-radius: 12px;
+    max-width: 500px;
+    animation: warning-fade-in 0.4s ease-out;
+    position: relative;
   }
 
-  function handleMouseLeave(event: MouseEvent) {
-    const card = event.currentTarget as HTMLButtonElement;
-    gsap.to(card, {
-      scale: 1,
-      boxShadow: "0 2px 10px rgba(0, 0, 0, 0.2)",
-      borderColor: "rgba(255, 255, 255, 0.05)",
-      duration: 0.1,
-      ease: "power2.out"
-    });
+  .model-warning::before {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background: linear-gradient(135deg,
+      rgba(255, 165, 0, 0.02) 0%,
+      rgba(255, 165, 0, 0.04) 100%);
+    border-radius: 12px;
+    pointer-events: none;
   }
 
-  function handleMouseDown(event: MouseEvent) {
-    const card = event.currentTarget as HTMLButtonElement;
-    gsap.to(card, {
-      scale: 0.97,
-      duration: 0.03,
-      ease: "power2.in"
-    });
+  @keyframes warning-fade-in {
+    from {
+      opacity: 0;
+      transform: translateY(10px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
   }
 
-  function handleMouseUp(event: MouseEvent) {
-    const card = event.currentTarget as HTMLButtonElement;
-    gsap.to(card, {
-      scale: 1.03,
-      duration: 0.05,
-      ease: "back.out(1.5)"
-    });
+  .warning-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.25rem 0.75rem;
+    background: rgba(255, 165, 0, 0.08);
+    border: 1px solid rgba(255, 165, 0, 0.15);
+    border-radius: 20px;
+    z-index: 1;
   }
-</script>
 
-<div class="examples-container" transition:fade={{ duration: 200 }}>
-  <div class="examples-header">
-    <span class="header-text">Try an example</span>
-  </div>
-  <div class="examples-grid">
-    {#each examples as example, i}
-      <button
-        bind:this={exampleCards[i]}
-        class="example-card"
-        on:click={() => handleClick(example.text)}
-        on:mouseenter={handleMouseEnter}
-        on:mouseleave={handleMouseLeave}
-        on:mousedown={handleMouseDown}
-        on:mouseup={handleMouseUp}
-      >
-        <span class="example-icon">{example.icon}</span>
-        <span class="example-text">{example.text}</span>
-      </button>
-    {/each}
-  </div>
-</div>
-
-<style>
-  .examples-container {
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    justify-content: center;
-    padding: 2rem 1rem;
-    height: 100%;
-    min-height: 300px;
-    gap: 1.5rem;
+  .warning-icon {
+    font-size: 0.875rem;
+    line-height: 1;
   }
 
-  .examples-header {
-    color: rgba(255, 255, 255, 0.3);
-    font-size: 0.75rem;
+  .warning-label {
+    font-size: 0.625rem;
     text-transform: uppercase;
-    letter-spacing: 0.1em;
-    font-weight: 500;
+    letter-spacing: 0.08em;
+    color: rgba(255, 165, 0, 0.9);
+    font-weight: 600;
+    font-family: "Monaco", "Menlo", monospace;
   }
 
-  .header-text {
-    animation: gentle-pulse 3s ease-in-out infinite;
+  .warning-text {
+    margin: 0;
+    font-size: 0.75rem;
+    line-height: 1.6;
+    color: rgba(255, 255, 255, 0.5);
+    font-family: "Monaco", "Menlo", monospace;
+    text-align: center;
+    z-index: 1;
   }
 
-  @keyframes gentle-pulse {
-    0%, 100% {
-      opacity: 0.5;
-    }
-    50% {
-      opacity: 0.8;
-    }
+  .warning-text a {
+    color: rgba(255, 165, 0, 0.85);
+    text-decoration: none;
+    transition: all 0.15s ease;
+    border-bottom: 1px dotted rgba(255, 165, 0, 0.3);
   }
 
-  .examples-grid {
-    display: grid;
-    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-    gap: 0.75rem;
-    width: 100%;
-    max-width: 600px;
+  .warning-text a:hover {
+    color: rgba(255, 190, 0, 1);
+    border-bottom-color: rgba(255, 190, 0, 0.5);
   }
 
-  .example-card {
-    display: flex;
+  .warning-link {
+    display: inline-flex;
     align-items: center;
-    gap: 0.5rem;
+    gap: 0.375rem;
     padding: 0.5rem 1rem;
-    background: rgba(255, 255, 255, 0.02);
-    border: 1px solid rgba(255, 255, 255, 0.05);
-    border-radius: 6px;
-    cursor: pointer;
-    transition: none;
+    background: transparent;
+    border: 1px solid rgba(255, 255, 255, 0.08);
+    border-radius: 8px;
+    color: rgba(255, 255, 255, 0.7);
+    font-size: 0.75rem;
+    font-weight: 500;
+    text-decoration: none;
+    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
     font-family: "Monaco", "Menlo", monospace;
-    font-size: 0.875rem;
-    color: rgba(255, 255, 255, 0.85);
-    will-change: transform, box-shadow;
-    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.2);
+    z-index: 1;
   }
 
-  .example-icon {
-    font-size: 1rem;
-    opacity: 0.8;
+  .warning-link:hover {
+    background: rgba(255, 255, 255, 0.03);
+    border-color: rgba(255, 255, 255, 0.15);
+    color: rgba(255, 255, 255, 0.9);
+    transform: translateY(-2px);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
   }
 
-  .example-text {
-    flex: 1;
+  .warning-link svg {
+    transition: transform 0.2s ease;
   }
 
-  @media (max-width: 600px) {
-    .examples-grid {
-      grid-template-columns: 1fr;
-    }
+  .warning-link:hover svg {
+    transform: translate(2px, -2px);
   }
-</style>
+</style>

src/lib/components/chat/ExampleRow.svelte

@@ -0,0 +1,183 @@
+<script lang="ts">
+  import { onMount, onDestroy } from "svelte";
+  import { fade } from "svelte/transition";
+  import gsap from "gsap";
+
+  export let onSendMessage: (message: string) => void;
+  export let visible: boolean = true;
+
+  const examples = [
+    { icon: "🏀", text: "add another ball" },
+    { icon: "📝", text: "explain what the code does" },
+    { icon: "🎮", text: "make a moving platform" },
+    { icon: "⬆️", text: "increase the player jump height" }
+  ];
+
+  let exampleCards: HTMLButtonElement[] = [];
+
+  onMount(() => {
+    if (visible) {
+      exampleCards.forEach((card, index) => {
+        if (!card) return;
+
+        gsap.fromTo(card, {
+          opacity: 0,
+          x: -10,
+          scale: 0.95
+        }, {
+          opacity: 1,
+          x: 0,
+          scale: 1,
+          duration: 0.15,
+          delay: index * 0.03,
+          ease: "power2.out"
+        });
+      });
+    }
+  });
+
+  onDestroy(() => {
+    exampleCards.forEach((card) => {
+      if (card) {
+        gsap.killTweensOf(card);
+      }
+    });
+  });
+
+  function handleClick(text: string) {
+    onSendMessage(text);
+  }
+
+  function handleMouseEnter(event: MouseEvent) {
+    const card = event.currentTarget as HTMLButtonElement;
+    gsap.to(card, {
+      scale: 1.05,
+      duration: 0.08,
+      ease: "power2.out"
+    });
+  }
+
+  function handleMouseLeave(event: MouseEvent) {
+    const card = event.currentTarget as HTMLButtonElement;
+    gsap.to(card, {
+      scale: 1,
+      duration: 0.1,
+      ease: "power2.out"
+    });
+  }
+
+  function handleMouseDown(event: MouseEvent) {
+    const card = event.currentTarget as HTMLButtonElement;
+    gsap.to(card, {
+      scale: 0.97,
+      duration: 0.03,
+      ease: "power2.in"
+    });
+  }
+
+  function handleMouseUp(event: MouseEvent) {
+    const card = event.currentTarget as HTMLButtonElement;
+    gsap.to(card, {
+      scale: 1.05,
+      duration: 0.05,
+      ease: "back.out(1.5)"
+    });
+  }
+</script>
+
+{#if visible}
+  <div class="examples-row" transition:fade={{ duration: 200 }}>
+    <span class="examples-label">Try an example:</span>
+    <div class="examples-list">
+      {#each examples as example, i}
+        <button
+          bind:this={exampleCards[i]}
+          class="example-pill"
+          on:click={() => handleClick(example.text)}
+          on:mouseenter={handleMouseEnter}
+          on:mouseleave={handleMouseLeave}
+          on:mousedown={handleMouseDown}
+          on:mouseup={handleMouseUp}
+        >
+          <span class="example-icon">{example.icon}</span>
+          <span class="example-text">{example.text}</span>
+        </button>
+      {/each}
+    </div>
+  </div>
+{/if}
+
+<style>
+  .examples-row {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    padding: 0.75rem 1rem;
+    background: rgba(0, 0, 0, 0.3);
+    border-top: 1px solid rgba(255, 255, 255, 0.03);
+  }
+
+  .examples-label {
+    font-size: 0.7rem;
+    color: rgba(255, 255, 255, 0.35);
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    font-weight: 500;
+    font-family: "Monaco", "Menlo", monospace;
+    flex-shrink: 0;
+  }
+
+  .examples-list {
+    display: flex;
+    gap: 0.5rem;
+    flex-wrap: wrap;
+    flex: 1;
+  }
+
+  .example-pill {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+    padding: 0.3rem 0.625rem;
+    background: rgba(255, 255, 255, 0.02);
+    border: 1px solid rgba(255, 255, 255, 0.05);
+    border-radius: 16px;
+    cursor: pointer;
+    transition: none;
+    font-family: "Monaco", "Menlo", monospace;
+    font-size: 0.7rem;
+    color: rgba(255, 255, 255, 0.65);
+    will-change: transform, box-shadow;
+    white-space: nowrap;
+  }
+
+  .example-pill:hover {
+    background: rgba(255, 255, 255, 0.04);
+    border-color: rgba(255, 255, 255, 0.08);
+    color: rgba(255, 255, 255, 0.85);
+  }
+
+  .example-icon {
+    font-size: 0.75rem;
+    opacity: 0.8;
+  }
+
+  .example-text {
+    font-size: 0.7rem;
+  }
+
+  @media (max-width: 600px) {
+    .examples-row {
+      flex-direction: column;
+      align-items: stretch;
+      gap: 0.5rem;
+      padding: 0.75rem;
+    }
+    .examples-label {
+      text-align: center;
+    }
+    .examples-list {
+      justify-content: center;
+    }
+  }
+</style>

src/lib/components/chat/Message.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { onMount } from "svelte";
+  import { onMount, afterUpdate } from "svelte";
   import gsap from "gsap";
   import type { ChatMessage } from "../../models/chat-data";
   import MessageContent from "./MessageContent.svelte";
@@ -7,16 +7,19 @@
   export let message: ChatMessage;
 
   let messageRef: HTMLDivElement;
+  let hasAnimated = false;
 
   onMount(() => {
-    if (messageRef) {
+    if (messageRef && !hasAnimated) {
       const isUser = message.role === 'user';
 
-      gsap.fromTo(messageRef,
+      const tl = gsap.timeline();
+
+      tl.fromTo(messageRef,
         {
           opacity: 0,
-          y: 8,
-          x: isUser ? 10 : -10,
+          y: isUser ? 5 : 10,
+          x: isUser ? 8 : -8,
           scale: 0.98
         },
         {
@@ -24,18 +27,47 @@
           y: 0,
           x: 0,
           scale: 1,
-          duration: 0.25,
-          ease: "power2.out",
-          delay: 0.05
+          duration: 0.35,
+          ease: "power2.out"
         }
       );
 
       if (!isUser) {
-        gsap.fromTo(messageRef.querySelector('.message-content'),
-          { opacity: 0 },
-          { opacity: 1, duration: 0.3, delay: 0.1, ease: "power1.out" }
+        tl.fromTo(messageRef.querySelector('.message-content'),
+          {
+            opacity: 0,
+            borderLeftWidth: "0px"
+          },
+          {
+            opacity: 1,
+            borderLeftWidth: "2px",
+            duration: 0.3,
+            ease: "power2.out"
+          },
+          "-=0.2"
         );
       }
+
+      hasAnimated = true;
+    }
+  });
+
+  afterUpdate(() => {
+    if (messageRef && !message.streaming && message.role === 'assistant' && hasAnimated) {
+      const borderEl = messageRef.querySelector('.message-content') as HTMLElement;
+      if (borderEl && !borderEl.dataset.completed) {
+        borderEl.dataset.completed = "true";
+        gsap.to(borderEl, {
+          borderLeftColor: "rgba(76, 175, 80, 0.4)",
+          duration: 0.3,
+          yoyo: true,
+          repeat: 1,
+          ease: "power2.inOut",
+          onComplete: () => {
+            gsap.set(borderEl, { borderLeftColor: "rgba(139, 115, 85, 0.08)" });
+          }
+        });
+      }
     }
   });
 </script>

src/lib/components/chat/MessageContent.svelte

@@ -3,14 +3,15 @@
   import TextRenderer from "./TextRenderer.svelte";
   import ToolBlock from "./segments/ToolBlock.svelte";
   import TodoSegment from "./segments/TodoSegment.svelte";
+  import { filterToolCalls } from "../../utils/tool-call-parser";
 
   export let message: ChatMessage;
 
   $: hasSegments = message.segments && message.segments.length > 0;
   $: isStreaming = message.streaming || (message.segments?.some(s => s.streaming));
 
-  // Normalize content for consistent rendering
-  $: normalizedContent = hasSegments ? null : (message.content || "");
+  // Normalize content for consistent rendering with tool call filtering
+  $: normalizedContent = hasSegments ? null : filterToolCalls(message.content || "");
 
   // Filter segments for rendering
   $: segmentsToRender = hasSegments ? message.segments!.filter((segment) => {
@@ -34,7 +35,7 @@
     <!-- Segmented content rendering -->
     {#each segmentsToRender as segment (segment.id)}
       {#if segment.type === "text"}
-        <TextRenderer content={segment.content} streaming={segment.streaming || false} />
+        <TextRenderer content={filterToolCalls(segment.content)} streaming={segment.streaming || false} />
       {:else if segment.type === "tool-invocation"}
         <ToolBlock
           invocation={segment}

src/lib/components/chat/MessageInput.svelte

@@ -16,32 +16,48 @@
 
   function handleSubmit() {
     if (value.trim() && !disabled && !processing) {
+      const tl = gsap.timeline();
+
       if (sendButtonRef) {
-        gsap.to(sendButtonRef, {
-          scale: 0.9,
+        tl.to(sendButtonRef, {
+          scale: 0.85,
           duration: 0.1,
-          yoyo: true,
-          repeat: 1,
-          ease: "power2.inOut",
-          onComplete: () => {
-            gsap.to(sendButtonRef, {
-              rotationY: 360,
-              duration: 0.6,
-              ease: "back.out(1.7)"
-            });
-          }
-        });
+          ease: "power2.in"
+        })
+        .to(sendButtonRef, {
+          scale: 1.1,
+          rotation: 360,
+          duration: 0.4,
+          ease: "back.out(2)"
+        })
+        .to(sendButtonRef, {
+          scale: 1,
+          duration: 0.2,
+          ease: "power2.out"
+        }, "-=0.1");
       }
 
-      dispatch("send", value.trim());
-      value = "";
-
       if (textareaRef) {
-        gsap.fromTo(textareaRef,
-          { scale: 1.02 },
-          { scale: 1, duration: 0.3, ease: "power2.out" }
+        tl.to(textareaRef,
+          {
+            borderColor: "rgba(76, 175, 80, 0.3)",
+            backgroundColor: "rgba(76, 175, 80, 0.02)",
+            duration: 0.2
+          },
+          0
+        )
+        .to(textareaRef,
+          {
+            borderColor: "rgba(139, 115, 85, 0.08)",
+            backgroundColor: "rgba(139, 115, 85, 0.03)",
+            duration: 0.3,
+            ease: "power2.out"
+          }
         );
       }
+
+      dispatch("send", value.trim());
+      value = "";
     }
   }
 
@@ -60,6 +76,8 @@
     }
   }
 
+  let isTyping = false;
+
   onMount(() => {
     if (inputAreaRef) {
       gsap.fromTo(inputAreaRef,
@@ -84,6 +102,30 @@
     gsap.set(stopButtonRef, { scale: 1 });
   }
 
+  $: if (value.length > 0 && !isTyping) {
+    isTyping = true;
+    if (sendButtonRef) {
+      gsap.to(sendButtonRef, {
+        scale: 1.05,
+        backgroundColor: "rgba(124, 152, 133, 0.12)",
+        duration: 0.3,
+        ease: "power2.out"
+      });
+    }
+  }
+
+  $: if (value.length === 0 && isTyping) {
+    isTyping = false;
+    if (sendButtonRef) {
+      gsap.to(sendButtonRef, {
+        scale: 1,
+        backgroundColor: "rgba(124, 152, 133, 0.08)",
+        duration: 0.3,
+        ease: "power2.out"
+      });
+    }
+  }
+
   function handleKeydown(event: KeyboardEvent) {
     if (event.key === "Enter" && !event.shiftKey) {
       event.preventDefault();
@@ -135,8 +177,8 @@
     display: flex;
     gap: 0.5rem;
     padding: 12px 16px;
-    background: transparent;
-    border-top: 1px solid rgba(139, 115, 85, 0.06);
+    background: rgba(20, 19, 17, 0.5);
+    border-top: 1px solid rgba(139, 115, 85, 0.18);
   }
 
   .input-wrapper {
@@ -161,9 +203,9 @@
 
   textarea {
     width: 100%;
-    background: rgba(139, 115, 85, 0.03);
-    color: rgba(251, 248, 244, 0.9);
-    border: 1px solid rgba(139, 115, 85, 0.08);
+    background: rgba(30, 28, 26, 0.5);
+    color: rgba(251, 248, 244, 0.95);
+    border: 1px solid rgba(139, 115, 85, 0.15);
     border-radius: 4px;
     padding: 0.4rem 0.6rem;
     resize: none;
@@ -177,9 +219,9 @@
 
   textarea:focus {
     outline: none;
-    border-color: rgba(124, 152, 133, 0.2);
-    background: rgba(139, 115, 85, 0.06);
-    box-shadow: 0 0 0 1px rgba(124, 152, 133, 0.1);
+    border-color: rgba(124, 152, 133, 0.3);
+    background: rgba(35, 33, 30, 0.6);
+    box-shadow: 0 0 0 1px rgba(124, 152, 133, 0.15);
   }
 
   textarea:focus + .input-glow {
@@ -197,9 +239,9 @@
     display: flex;
     align-items: center;
     justify-content: center;
-    background: rgba(124, 152, 133, 0.08);
-    color: rgba(124, 152, 133, 0.8);
-    border: 1px solid rgba(124, 152, 133, 0.15);
+    background: rgba(124, 152, 133, 0.12);
+    color: rgba(124, 152, 133, 0.9);
+    border: 1px solid rgba(124, 152, 133, 0.2);
     border-radius: 4px;
     cursor: pointer;
     transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
@@ -219,10 +261,10 @@
   }
 
   .send-btn:hover:not(:disabled) {
-    background: rgba(124, 152, 133, 0.15);
-    border-color: rgba(124, 152, 133, 0.3);
+    background: rgba(124, 152, 133, 0.2);
+    border-color: rgba(124, 152, 133, 0.35);
     transform: translateY(-1px);
-    box-shadow: 0 4px 12px rgba(124, 152, 133, 0.2);
+    box-shadow: 0 4px 12px rgba(124, 152, 133, 0.25);
     color: rgba(124, 152, 133, 1);
   }
 
@@ -246,9 +288,9 @@
     display: flex;
     align-items: center;
     justify-content: center;
-    background: rgba(184, 84, 80, 0.08);
-    color: rgba(184, 84, 80, 0.8);
-    border: 1px solid rgba(184, 84, 80, 0.15);
+    background: rgba(184, 84, 80, 0.12);
+    color: rgba(184, 84, 80, 0.9);
+    border: 1px solid rgba(184, 84, 80, 0.2);
     border-radius: 4px;
     cursor: pointer;
     transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
@@ -281,10 +323,10 @@
   }
 
   .stop-btn:hover {
-    background: rgba(184, 84, 80, 0.15);
-    border-color: rgba(184, 84, 80, 0.3);
+    background: rgba(184, 84, 80, 0.2);
+    border-color: rgba(184, 84, 80, 0.35);
     transform: translateY(-1px);
-    box-shadow: 0 4px 12px rgba(184, 84, 80, 0.2);
+    box-shadow: 0 4px 12px rgba(184, 84, 80, 0.25);
     color: rgba(184, 84, 80, 1);
   }
 

src/lib/components/chat/MessageList.svelte

@@ -35,15 +35,27 @@
 
     $: if ($typingIndicator && typingIndicatorRef) {
         gsap.fromTo(typingIndicatorRef,
-            { opacity: 0, y: 10 },
-            { opacity: 1, y: 0, duration: 0.3, ease: "power2.out" }
+            { opacity: 0, y: 10, scale: 0.95 },
+            { opacity: 1, y: 0, scale: 1, duration: 0.3, ease: "power2.out" }
         );
+
+        const dots = typingIndicatorRef.querySelectorAll('.dot');
+        gsap.to(dots, {
+            y: -3,
+            duration: 0.6,
+            stagger: 0.15,
+            repeat: -1,
+            yoyo: true,
+            ease: "power1.inOut"
+        });
     }
 
     $: if (!$typingIndicator && typingIndicatorRef) {
+        gsap.killTweensOf(typingIndicatorRef.querySelectorAll('.dot'));
         gsap.to(typingIndicatorRef, {
             opacity: 0,
             y: -5,
+            scale: 0.95,
             duration: 0.2,
             ease: "power2.in"
         });
@@ -53,7 +65,7 @@
 <div class="messages" bind:this={messagesDiv} on:scroll={handleScroll}>
     {#if messages.length === 0 && isConnected && onSendMessage}
         <div class="welcome-section">
-            <ExampleMessages {onSendMessage} />
+            <ExampleMessages />
         </div>
     {/if}
 
@@ -101,44 +113,63 @@
         display: flex;
         align-items: center;
         gap: 0.5rem;
-        padding: 0.375rem 0.5rem;
-        margin: 0.125rem 0;
-        border-left: 2px solid rgba(124, 152, 133, 0.2);
-        padding-left: 0.5rem;
+        padding: 0.5rem;
+        margin: 0.25rem 0;
+        border-left: 2px solid rgba(33, 150, 243, 0.3);
+        background: linear-gradient(90deg,
+            rgba(33, 150, 243, 0.05),
+            transparent);
+        border-radius: 0 4px 4px 0;
+        position: relative;
+        overflow: hidden;
+    }
+
+    .typing-indicator::before {
+        content: '';
+        position: absolute;
+        top: 0;
+        left: -100%;
+        width: 100%;
+        height: 100%;
+        background: linear-gradient(90deg,
+            transparent,
+            rgba(33, 150, 243, 0.1),
+            transparent);
+        animation: shimmer 2s ease-in-out infinite;
+    }
+
+    @keyframes shimmer {
+        to { left: 100%; }
     }
 
     .typing-dots {
         display: flex;
-        gap: 0.25rem;
+        gap: 0.3rem;
+        align-items: center;
     }
 
     .dot {
-        width: 4px;
-        height: 4px;
+        width: 6px;
+        height: 6px;
         border-radius: 50%;
-        background: rgba(124, 152, 133, 0.6);
-        animation: typing-bounce 1.4s ease-in-out infinite both;
-    }
-
-    .dot:nth-child(1) { animation-delay: -0.32s; }
-    .dot:nth-child(2) { animation-delay: -0.16s; }
-    .dot:nth-child(3) { animation-delay: 0s; }
-
-    @keyframes typing-bounce {
-        0%, 80%, 100% {
-            transform: scale(0);
-            opacity: 0.5;
-        }
-        40% {
-            transform: scale(1);
-            opacity: 1;
-        }
+        background: linear-gradient(135deg,
+            rgba(33, 150, 243, 0.8),
+            rgba(100, 181, 246, 0.6));
+        display: inline-block;
+        position: relative;
     }
 
     .typing-text {
         font-size: 11px;
-        color: rgba(251, 248, 244, 0.3);
-        font-style: italic;
+        color: rgba(251, 248, 244, 0.4);
+        font-style: normal;
+        letter-spacing: 0.3px;
+        animation: fade-pulse 2s ease-in-out infinite;
+    }
+
+    @keyframes fade-pulse {
+        0%, 100% { opacity: 0.4; }
+        50% { opacity: 0.7; }
     }
 
     .error-message {

src/lib/components/chat/TextRenderer.svelte

@@ -1,22 +1,66 @@
 <script lang="ts">
-  import { onMount } from "svelte";
+  import { onMount, afterUpdate } from "svelte";
   import gsap from "gsap";
+  import { StreamingToolCallParser, filterToolCalls } from "../../utils/tool-call-parser";
 
   export let content: string;
   export let streaming: boolean = false;
 
   let textEl: HTMLDivElement;
   let cursorEl: HTMLSpanElement;
+  let lastContentLength = 0;
+  let newContentEl: HTMLSpanElement;
+  let parser: StreamingToolCallParser | null = null;
+
+  // Initialize parser for streaming mode
+  $: {
+    if (streaming && !parser) {
+      parser = new StreamingToolCallParser();
+    } else if (!streaming && parser) {
+      parser = null;
+    }
+  }
+
+  // Filter content based on streaming state
+  $: filteredContent = (() => {
+    if (streaming && parser) {
+      // Use streaming parser to incrementally process content
+      parser.reset();
+      const result = parser.process(content);
+      return result.safeText;
+    } else {
+      // Use static filter for non-streaming content
+      return filterToolCalls(content);
+    }
+  })();
 
   onMount(() => {
     if (textEl && !streaming) {
       gsap.fromTo(textEl,
         { opacity: 0, y: 3, scale: 0.99 },
-        { opacity: 1, y: 0, scale: 1, duration: 0.2, ease: "power2.out" }
+        { opacity: 1, y: 0, scale: 1, duration: 0.3, ease: "power2.out" }
       );
     }
   });
 
+  // Animate new characters appearing during streaming
+  afterUpdate(() => {
+    if (streaming && filteredContent.length > lastContentLength) {
+      const newChars = filteredContent.slice(lastContentLength);
+      if (newContentEl && newChars.length > 0) {
+        gsap.fromTo(newContentEl,
+          { opacity: 0, scale: 0.95 },
+          { opacity: 1, scale: 1, duration: 0.15, ease: "power2.out" }
+        );
+      }
+      lastContentLength = filteredContent.length;
+    }
+
+    if (!streaming) {
+      lastContentLength = 0;
+    }
+  });
+
   $: if (streaming && cursorEl) {
     gsap.to(cursorEl, {
       opacity: 0.3,
@@ -32,14 +76,32 @@
     gsap.to(cursorEl, {
       opacity: 0,
       duration: 0.3,
-      ease: "power2.out"
+      ease: "power2.out",
+      onComplete: () => {
+        // Small celebration pulse on complete
+        if (textEl) {
+          gsap.to(textEl, {
+            borderLeftColor: "rgba(76, 175, 80, 0.3)",
+            duration: 0.3,
+            yoyo: true,
+            repeat: 1,
+            ease: "power2.inOut"
+          });
+        }
+      }
     });
   }
 </script>
 
 <div class="text-renderer" bind:this={textEl}>
   <span class="content">
-    {content}{#if streaming}<span class="cursor" bind:this={cursorEl}>▊</span>{/if}
+    {#if streaming && lastContentLength > 0}
+      {filteredContent.slice(0, lastContentLength)}
+      <span bind:this={newContentEl}>{filteredContent.slice(lastContentLength)}</span>
+    {:else}
+      {filteredContent}
+    {/if}
+    {#if streaming}<span class="cursor" bind:this={cursorEl}>▊</span>{/if}
   </span>
 </div>
 

src/lib/components/chat/context.md

@@ -1,30 +1,31 @@
 # Chat Context
 
-AI chat interface with enhanced feedback and micro-interactions.
+AI chat interface with enhanced contrast dark theme and dopamine-driven micro-interactions.
 
 ## Components
 
 - `ChatPanel.svelte` - Main container with auth handling
-- `MessageList.svelte` - Message container with typing indicators
-- `Message.svelte` - Message wrapper with entrance animations
-- `MessageContent.svelte` - Content normalizer and router
-- `TextRenderer.svelte` - Text display with streaming cursors
-- `MessageInput.svelte` - Input with enhanced button feedback
-- `ExampleMessages.svelte` - Initial prompt suggestions
-- `segments/ToolBlock.svelte` - Collapsible tool invocation/result
-- `segments/TodoSegment.svelte` - Task list display
+- `MessageList.svelte` - Message container with animated typing indicators
+- `Message.svelte` - Message wrapper with coordinated entrance animations
+- `MessageContent.svelte` - Content normalizer and router with segment-level filtering
+- `TextRenderer.svelte` - Progressive text reveal with streaming-aware tool call filtering
+- `MessageInput.svelte` - Input with charge-up animations and success feedback
+- `ExampleMessages.svelte` - Model limitations warning when chat is empty
+- `ExampleRow.svelte` - Horizontal example prompts above input
+- `segments/ToolBlock.svelte` - Tool execution with icons, colors, and progress bars
+- `segments/TodoSegment.svelte` - Task tracker with progress bar and milestone celebrations
 
 ## Architecture
 
 Clean MVC separation:
 
-- **Model**: Enhanced chat store with feedback states
+- **Model**: Chat store with state management
 - **View**: Component hierarchy with GSAP animations
-- **Controller**: WebSocket handling with state management
+- **Controller**: WebSocket handling with agent communication
 
 ## Design
 
-- Consistent styling matches console/header color scheme
-- GSAP micro-interactions provide constant user feedback
-- Typing indicators and status management for engagement
-- Single text renderer with streaming state animations
+- Tool-specific icons and color coding for visual hierarchy
+- Progress indicators with anticipation curves
+- Success celebrations through subtle animations
+- Consistent feedback loops for all interactions

src/lib/components/chat/segments/TodoSegment.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { onMount } from "svelte";
+  import { onMount, afterUpdate } from "svelte";
   import gsap from "gsap";
   import type { MessageSegment } from "../../../models/chat-data";
   import type { TodoListView } from "../../../models/segment-view";
@@ -9,20 +9,66 @@
 
   let todoList: TodoListView | null = null;
   let containerEl: HTMLDivElement;
+  let progressBarEl: HTMLDivElement;
+  let lastCompletedCount = 0;
+  let taskElements: HTMLDivElement[] = [];
 
   $: {
     const content = segment.toolOutput || segment.content;
     todoList = parseTodoList(content);
   }
 
+  $: progressPercentage = todoList
+    ? (todoList.completedCount / todoList.totalCount) * 100
+    : 0;
+
   onMount(() => {
     if (containerEl) {
       gsap.from(containerEl, {
         opacity: 0,
-        y: 3,
+        y: 5,
+        duration: 0.3,
+        ease: "power2.out",
+      });
+
+      gsap.from(".todo-task", {
+        opacity: 0,
+        x: -10,
         duration: 0.2,
+        stagger: 0.05,
+        ease: "power2.out",
+      });
+    }
+  });
+
+  afterUpdate(() => {
+    if (progressBarEl && todoList) {
+      gsap.to(progressBarEl, {
+        width: `${progressPercentage}%`,
+        duration: 0.6,
         ease: "power2.out",
       });
+
+      if (todoList.completedCount > lastCompletedCount) {
+        if (progressPercentage === 100) {
+          gsap.to(containerEl, {
+            borderColor: "rgba(76, 175, 80, 0.5)",
+            duration: 0.3,
+            yoyo: true,
+            repeat: 2,
+            ease: "power2.inOut",
+          });
+        } else if (progressPercentage === 50 || progressPercentage === 75) {
+          gsap.to(progressBarEl, {
+            backgroundColor: "rgba(76, 175, 80, 0.6)",
+            duration: 0.3,
+            yoyo: true,
+            repeat: 1,
+            ease: "power2.inOut",
+          });
+        }
+        lastCompletedCount = todoList.completedCount;
+      }
     }
   });
 </script>
@@ -36,10 +82,25 @@
       </span>
     </div>
 
+    <div class="progress-track">
+      <div class="progress-bar" bind:this={progressBarEl} style="width: {progressPercentage}%"></div>
+    </div>
+
     <div class="todo-list">
-      {#each todoList.tasks as task}
-        <div class="todo-task {task.status}">
-          <span class="task-emoji">{task.emoji}</span>
+      {#each todoList.tasks as task, i}
+        <div
+          class="todo-task {task.status}"
+          bind:this={taskElements[i]}
+        >
+          <span class="task-indicator">
+            {#if task.status === 'completed'}
+              <span class="checkmark">✓</span>
+            {:else if task.status === 'in_progress'}
+              <span class="progress-dot">●</span>
+            {:else}
+              <span class="pending-circle">○</span>
+            {/if}
+          </span>
           <span class="task-text">{task.description}</span>
         </div>
       {/each}
@@ -81,6 +142,21 @@
     border-radius: 10px;
   }
 
+  .progress-track {
+    height: 3px;
+    background: rgba(255, 255, 255, 0.05);
+    position: relative;
+    overflow: hidden;
+  }
+
+  .progress-bar {
+    height: 100%;
+    background: linear-gradient(90deg,
+      rgba(76, 175, 80, 0.3),
+      rgba(76, 175, 80, 0.5));
+    transition: width 0.6s ease-out;
+  }
+
   .todo-list {
     padding: 0.375rem 0.5rem;
   }
@@ -89,16 +165,48 @@
     display: flex;
     align-items: center;
     gap: 0.375rem;
-    padding: 0.25rem 0;
+    padding: 0.3rem 0;
     font-size: 0.75rem;
     color: rgba(255, 255, 255, 0.7);
+    transition: all 0.2s ease;
   }
 
-  .task-emoji {
-    font-size: 0.9rem;
+  .task-indicator {
+    width: 16px;
+    height: 16px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
     flex-shrink: 0;
   }
 
+  .checkmark {
+    color: rgba(76, 175, 80, 0.9);
+    font-weight: bold;
+    animation: checkPop 0.3s ease-out;
+  }
+
+  @keyframes checkPop {
+    0% { transform: scale(0); }
+    50% { transform: scale(1.2); }
+    100% { transform: scale(1); }
+  }
+
+  .progress-dot {
+    color: rgba(33, 150, 243, 0.9);
+    animation: progressPulse 1.5s ease-in-out infinite;
+  }
+
+  @keyframes progressPulse {
+    0%, 100% { opacity: 0.4; transform: scale(0.8); }
+    50% { opacity: 1; transform: scale(1.2); }
+  }
+
+  .pending-circle {
+    color: rgba(255, 255, 255, 0.3);
+    font-size: 10px;
+  }
+
   .task-text {
     flex: 1;
   }
@@ -110,6 +218,10 @@
 
   .todo-task.in_progress {
     color: rgba(255, 255, 255, 0.9);
+    background: rgba(33, 150, 243, 0.05);
+    border-left: 2px solid rgba(33, 150, 243, 0.3);
+    padding-left: 0.5rem;
+    margin-left: -0.5rem;
   }
 
   .todo-task.in_progress .task-text {

src/lib/components/chat/segments/ToolBlock.svelte

@@ -1,24 +1,119 @@
 <script lang="ts">
   import { slide } from "svelte/transition";
+  import { onMount } from "svelte";
+  import gsap from "gsap";
   import type { MessageSegment } from "../../../models/chat-data";
 
   export let invocation: MessageSegment | null = null;
   export let result: MessageSegment | null = null;
 
   let isExpanded = false;
+  let blockRef: HTMLDivElement;
+  let progressRef: HTMLDivElement;
+  let iconRef: HTMLSpanElement;
 
   $: segment = result || invocation;
   $: isRunning = segment?.streaming || segment?.toolStatus === "running";
   $: isError = segment?.toolError || segment?.toolStatus === "error";
   $: hasOutput = result?.toolOutput || result?.content;
+  $: isSuccess = !isRunning && !isError && hasOutput;
 
-  // Auto-expand on error
   $: if (isError && !isExpanded) {
     isExpanded = true;
   }
 
+  $: if (isSuccess && iconRef) {
+    gsap.fromTo(iconRef,
+      { scale: 1, rotation: 0 },
+      {
+        scale: 1.2,
+        rotation: 360,
+        duration: 0.6,
+        ease: "elastic.out(1, 0.5)",
+        onComplete: () => {
+          gsap.to(iconRef, { scale: 1, duration: 0.2 });
+        }
+      }
+    );
+  }
+
+  onMount(() => {
+    if (blockRef) {
+      gsap.fromTo(blockRef,
+        { opacity: 0, x: -10 },
+        { opacity: 1, x: 0, duration: 0.3, ease: "power2.out" }
+      );
+    }
+
+    if (isRunning && progressRef) {
+      gsap.fromTo(progressRef,
+        { scaleX: 0 },
+        { scaleX: 1, duration: 3, ease: "power1.inOut" }
+      );
+    }
+  });
+
   function toggleExpanded() {
     isExpanded = !isExpanded;
+    if (blockRef) {
+      gsap.to(blockRef, {
+        backgroundColor: isExpanded ? "rgba(255, 255, 255, 0.02)" : "rgba(255, 255, 255, 0.01)",
+        duration: 0.2
+      });
+    }
+  }
+
+  function getToolIcon(): string {
+    const name = invocation?.toolName || result?.toolName || "";
+    const lowerName = name.toLowerCase();
+
+    // Editor tools
+    if (lowerName === "read_editor" || lowerName === "read_editor_lines") return "📄";
+    if (lowerName === "write_editor") return "💾";
+    if (lowerName === "edit_editor") return "✏️";
+    if (lowerName === "search_editor") return "🔍";
+
+    // Task management
+    if (lowerName === "plan_tasks") return "📋";
+    if (lowerName === "update_task") return "✅";
+    if (lowerName === "view_tasks") return "👁️";
+
+    // Documentation/library tools
+    if (lowerName === "resolve_library_id") return "📚";
+    if (lowerName === "get_library_docs") return "📖";
+
+    // Console observation
+    if (lowerName === "observe_console") return "🖥️";
+
+    // Generic fallbacks
+    if (lowerName.includes("read")) return "📄";
+    if (lowerName.includes("write") || lowerName.includes("edit")) return "✏️";
+    if (lowerName.includes("search")) return "🔍";
+    if (lowerName.includes("task")) return "✅";
+
+    return "🔧";
+  }
+
+  function getToolColor(): string {
+    const name = invocation?.toolName || result?.toolName || "";
+    const lowerName = name.toLowerCase();
+
+    // Editor tools
+    if (lowerName === "read_editor" || lowerName === "read_editor_lines") return "rgba(100, 149, 237, 0.08)"; // Cornflower blue
+    if (lowerName === "write_editor") return "rgba(255, 165, 0, 0.08)"; // Orange
+    if (lowerName === "edit_editor") return "rgba(255, 215, 0, 0.08)"; // Gold
+    if (lowerName === "search_editor") return "rgba(147, 112, 219, 0.08)"; // Medium purple
+
+    // Task management
+    if (lowerName.includes("task")) return "rgba(76, 175, 80, 0.08)"; // Green
+
+    // Documentation
+    if (lowerName.includes("library") || lowerName.includes("docs")) return "rgba(70, 130, 180, 0.08)"; // Steel blue
+
+    // Console
+    if (lowerName === "observe_console") return "rgba(96, 125, 139, 0.08)"; // Blue grey
+
+    return "rgba(255, 255, 255, 0.03)";
   }
 
   function getToolName(): string {
@@ -43,12 +138,17 @@
   }
 </script>
 
-<div class="tool-block" class:error={isError}>
+<div class="tool-block" class:error={isError} class:success={isSuccess} bind:this={blockRef} style="background: {getToolColor()}">
+  {#if isRunning}
+    <div class="progress-bar" bind:this={progressRef}></div>
+  {/if}
+
   <button
     class="tool-header"
     on:click={toggleExpanded}
     class:expanded={isExpanded}
   >
+    <span class="tool-icon" bind:this={iconRef}>{getToolIcon()}</span>
     <span class="tool-name">{getToolName()}</span>
 
     {#if isRunning}
@@ -59,7 +159,7 @@
     {:else if isError}
       <span class="status error">❌ {getStatusText()}</span>
     {:else if hasOutput}
-      <span class="status completed">{getStatusText()}</span>
+      <span class="status completed">✓ {getStatusText()}</span>
     {/if}
 
     <span class="expand-icon" class:expanded={isExpanded}>▶</span>
@@ -101,10 +201,42 @@
     border-radius: 4px;
     background: rgba(255, 255, 255, 0.01);
     overflow: hidden;
+    position: relative;
+    transition: all 0.3s ease;
   }
 
   .tool-block.error {
     border-color: rgba(244, 67, 54, 0.2);
+    animation: errorShake 0.3s ease-in-out;
+  }
+
+  .tool-block.success {
+    border-color: rgba(76, 175, 80, 0.15);
+  }
+
+  @keyframes errorShake {
+    0%, 100% { transform: translateX(0); }
+    25% { transform: translateX(-2px); }
+    75% { transform: translateX(2px); }
+  }
+
+  .progress-bar {
+    position: absolute;
+    top: 0;
+    left: 0;
+    height: 2px;
+    width: 100%;
+    background: linear-gradient(90deg,
+      rgba(33, 150, 243, 0.8),
+      rgba(100, 181, 246, 1),
+      rgba(33, 150, 243, 0.8));
+    transform-origin: left;
+    animation: shimmer 2s ease-in-out infinite;
+  }
+
+  @keyframes shimmer {
+    0%, 100% { opacity: 0.6; }
+    50% { opacity: 1; }
   }
 
   .tool-header {
@@ -126,6 +258,12 @@
     background: rgba(255, 255, 255, 0.02);
   }
 
+  .tool-icon {
+    font-size: 1rem;
+    margin-right: 0.25rem;
+    display: inline-block;
+  }
+
   .tool-name {
     flex: 1;
     font-size: 0.8rem;
@@ -152,7 +290,8 @@
   }
 
   .status.completed {
-    color: rgba(255, 255, 255, 0.5);
+    background: rgba(76, 175, 80, 0.1);
+    color: rgba(76, 175, 80, 0.9);
   }
 
   .pulse-dot {

src/lib/components/game/GameCanvas.svelte

@@ -10,21 +10,29 @@
   let previousContent = '';
   let isInitialized = false;
   let lastRestartTime = 0;
+  let reloadInProgress = false;
 
   $: if ($contentManager.content !== previousContent && $gameStore.isAutoRunning && isInitialized) {
     previousContent = $contentManager.content;
     clearTimeout(reloadTimer);
 
     const now = Date.now();
-    if (now - lastRestartTime >= 2000) {
+    // Ensure minimum time between reloads and no overlapping reloads
+    if (now - lastRestartTime >= 2000 && !reloadInProgress) {
       reloadTimer = setTimeout(async () => {
         const currentTime = Date.now();
-        if (currentTime - lastRestartTime < 2000 || $gameStore.isStarting) {
+        if (currentTime - lastRestartTime < 2000 || $gameStore.isStarting || reloadInProgress) {
           return;
         }
         lastRestartTime = currentTime;
+        reloadInProgress = true;
 
-        await gameEngine.startFromDocument($contentManager.content);
+        try {
+          await gameEngine.startFromDocument($contentManager.content);
+        } finally {
+          // Ensure we always reset the flag
+          reloadInProgress = false;
+        }
       }, 1500);
     }
   }

src/lib/components/game/context.md

@@ -6,20 +6,20 @@ Game rendering and error display
 
 - Render game canvas
 - Display game errors
-- Manage game lifecycle
+- Manage game lifecycle with reload protection
 
 ## Layout
 
 ```
 game/
 ├── context.md         # This file
-├── GameCanvas.svelte  # Game rendering canvas
+├── GameCanvas.svelte  # Game rendering with automatic reload
 └── GameError.svelte   # Error message display
 ```
 
 ## Scope
 
-- In-scope: Game display, error UI
+- In-scope: Game display, error UI, reload management
 - Out-of-scope: Game logic, physics
 
 ## Entrypoints

src/lib/components/layout/AppHeader.svelte

@@ -12,10 +12,24 @@
       await gameEngine.startFromDocument($contentManager.content);
     }
   }
-  
+
   function handleViewModeChange(mode: 'code' | 'preview') {
     uiStore.setViewMode(mode);
   }
+
+  function handleAboutClick() {
+    if ($uiStore.viewMode === 'about') {
+      uiStore.hideAbout();
+    } else {
+      uiStore.showAbout();
+    }
+  }
+
+  function handleTitleClick() {
+    if ($uiStore.viewMode === 'about') {
+      uiStore.hideAbout();
+    }
+  }
   
   onMount(() => {
     gsap.fromTo(".app-header", 
@@ -62,10 +76,24 @@
 
 <div class="app-header">
   <div class="header-left">
-    <div class="app-title">
+    <button
+      class="app-title-button"
+      class:clickable={$uiStore.viewMode === 'about'}
+      on:click={handleTitleClick}
+    >
       <span class="app-icon">🥕</span>
       <span class="app-name">VibeGame</span>
-    </div>
+    </button>
+    <span class="header-separator">|</span>
+    <button
+      class="nav-button"
+      class:active={$uiStore.viewMode === 'about'}
+      on:click={handleAboutClick}
+      aria-label="About"
+    >
+      About
+    </button>
+    <span class="header-separator">|</span>
     <a href="https://github.com/dylanebert/VibeGame"
        target="_blank"
        rel="noopener noreferrer"
@@ -78,22 +106,24 @@
   </div>
   
   <div class="header-center">
-    <div class="view-toggle">
-      <button 
-        class="toggle-btn" 
-        class:active={$uiStore.viewMode === 'code'}
-        on:click={() => handleViewModeChange('code')}
-      >
-        Code
-      </button>
-      <button 
-        class="toggle-btn" 
-        class:active={$uiStore.viewMode === 'preview'}
-        on:click={() => handleViewModeChange('preview')}
-      >
-        Preview
-      </button>
-    </div>
+    {#if $uiStore.viewMode !== 'about'}
+      <div class="view-toggle">
+        <button
+          class="toggle-btn"
+          class:active={$uiStore.viewMode === 'code'}
+          on:click={() => handleViewModeChange('code')}
+        >
+          Code
+        </button>
+        <button
+          class="toggle-btn"
+          class:active={$uiStore.viewMode === 'preview'}
+          on:click={() => handleViewModeChange('preview')}
+        >
+          Preview
+        </button>
+      </div>
+    {/if}
   </div>
   
   <div class="header-right">
@@ -146,14 +176,28 @@
 
   .header-left {
     justify-content: flex-start;
-    gap: 0.75rem;
+    gap: 0.5rem;
+    align-items: center;
   }
 
-  .app-title {
+  .app-title-button {
     display: flex;
     align-items: center;
     gap: 0.5rem;
     user-select: none;
+    background: transparent;
+    border: none;
+    padding: 0;
+    cursor: default;
+    transition: all 0.2s;
+  }
+
+  .app-title-button.clickable {
+    cursor: pointer;
+  }
+
+  .app-title-button.clickable:hover .app-name {
+    color: rgba(251, 248, 244, 0.75);
   }
 
   .app-icon {
@@ -168,6 +212,59 @@
     letter-spacing: 0.025em;
   }
 
+  .header-separator {
+    color: rgba(251, 248, 244, 0.2);
+    font-size: 0.875rem;
+    user-select: none;
+    padding: 0 0.25rem;
+  }
+
+  .nav-button {
+    background: transparent;
+    border: none;
+    color: rgba(251, 248, 244, 0.5);
+    font-size: 0.875rem;
+    font-weight: 500;
+    padding: 0.375rem 0.625rem;
+    border-radius: 0.25rem;
+    cursor: pointer;
+    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+    position: relative;
+  }
+
+  .nav-button::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: 0.25rem;
+    background: rgba(139, 115, 85, 0.08);
+    opacity: 0;
+    transition: opacity 0.2s ease-out;
+  }
+
+  .nav-button:hover {
+    color: rgba(251, 248, 244, 0.9);
+  }
+
+  .nav-button:hover::before {
+    opacity: 1;
+  }
+
+  .nav-button:active {
+    transform: scale(0.98);
+  }
+
+  .nav-button.active {
+    background: rgba(124, 152, 133, 0.12);
+    color: rgba(251, 248, 244, 0.95);
+    border-radius: 0.25rem;
+  }
+
+  .nav-button.active::before {
+    opacity: 1;
+    background: rgba(124, 152, 133, 0.1);
+  }
+
   .github-link {
     display: flex;
     align-items: center;

src/lib/components/layout/SplitView.svelte

@@ -37,7 +37,7 @@
         };
     });
 
-    $: if (viewMode) {
+    $: if (viewMode && viewMode !== 'about') {
         handleViewModeAnimation(viewMode);
     }
 

src/lib/components/layout/context.md

@@ -5,9 +5,9 @@ Application layout structure
 ## Purpose
 
 - Loading state management
-- Header navigation
+- Header navigation with view switching
 - Two-pane layout with nested splits
-- View mode transitions
+- View mode transitions (code/preview/about)
 
 ## Structure
 
@@ -15,7 +15,7 @@ Application layout structure
 layout/
 ├── context.md           # This file
 ├── LoadingScreen.svelte # Initial loading with spinner
-├── AppHeader.svelte     # Top navigation bar
+├── AppHeader.svelte     # Top navigation bar with Title | About | Repo
 └── SplitView.svelte     # Two-pane layout with nested splits
 ```
 
@@ -24,10 +24,11 @@ layout/
 - Main split: Editor pane (left) | Preview pane (right)
 - Editor pane: Code editor (top) | Chat panel (bottom)
 - Preview pane: Game canvas (top) | Console (bottom)
+- View modes: code, preview, or about page overlay
 
 ## Dependencies
 
 - loadingStore for loading state
-- uiStore for view mode
+- uiStore for view mode management
 - svelte-splitpanes for resizable panes
 - GSAP for animations

src/lib/config/animations.ts

@@ -1,43 +0,0 @@
-export const animationConfig = {
-  header: {
-    initial: { opacity: 0, y: -20 },
-    animate: { opacity: 1, y: 0, duration: 0.6, ease: "power3.out" },
-  },
-
-  editor: {
-    initial: { opacity: 0, x: -20 },
-    animate: {
-      opacity: 1,
-      x: 0,
-      duration: 0.6,
-      delay: 0.1,
-      ease: "power3.out",
-    },
-  },
-
-  preview: {
-    initial: { opacity: 0, x: 20 },
-    animate: {
-      opacity: 1,
-      x: 0,
-      duration: 0.6,
-      delay: 0.2,
-      ease: "power3.out",
-    },
-  },
-
-  consoleMessage: {
-    initial: { opacity: 0, y: -5 },
-    animate: { opacity: 1, y: 0, duration: 0.3, ease: "power2.out" },
-  },
-
-  error: {
-    initial: { opacity: 0, transform: "translateY(-10px)" },
-    animate: { opacity: 1, transform: "translateY(0)", duration: 0.3 },
-  },
-
-  viewTransition: {
-    duration: 0.2,
-    ease: "power2.inOut",
-  },
-};

src/lib/config/context.md

@@ -5,16 +5,14 @@ Application configuration and constants
 ## Purpose
 
 - Centralize configuration values
-- Define animation settings
 - Keyboard shortcuts registry
 
 ## Layout
 
 ```
 config/
-├── context.md      # This file
-├── animations.ts   # GSAP animation configs
-└── shortcuts.ts    # Keyboard shortcut definitions
+├── context.md    # This file
+└── shortcuts.ts  # Keyboard shortcut definitions
 ```
 
 ## Scope
@@ -24,7 +22,6 @@ config/
 
 ## Entrypoints
 
-- `animationConfig` - Animation presets
 - `shortcuts` - Keyboard shortcut definitions
 - `registerShortcuts()` - Setup keyboard handlers
 

src/lib/controllers/animation-controller.ts

@@ -1,190 +0,0 @@
-import gsap from "gsap";
-
-type AnimationTarget = HTMLElement | null;
-type AnimationId = string;
-
-interface AnimationConfig {
-  target: AnimationTarget;
-  animation: gsap.core.Tween | gsap.core.Timeline;
-}
-
-export class AnimationController {
-  private animations = new Map<AnimationId, AnimationConfig>();
-
-  register(id: AnimationId, target: AnimationTarget): void {
-    if (!target) return;
-    this.cleanup(id);
-    this.animations.set(id, { target, animation: null! });
-  }
-
-  cleanup(id: AnimationId): void {
-    const config = this.animations.get(id);
-    if (config?.animation) {
-      config.animation.kill();
-    }
-    if (config?.target) {
-      gsap.killTweensOf(config.target);
-    }
-    this.animations.delete(id);
-  }
-
-  cleanupAll(): void {
-    this.animations.forEach((_, id) => this.cleanup(id));
-  }
-
-  buttonPress(element: AnimationTarget): void {
-    if (!element) return;
-    gsap.to(element, {
-      scale: 0.9,
-      duration: 0.1,
-      ease: "power2.in",
-      onComplete: () => {
-        gsap.to(element, {
-          scale: 1,
-          duration: 0.2,
-          ease: "elastic.out(1, 0.5)",
-        });
-      },
-    });
-  }
-
-  buttonHover(element: AnimationTarget, entering: boolean): void {
-    if (!element) return;
-    gsap.to(element, {
-      scale: entering ? 1.05 : 1,
-      duration: 0.2,
-      ease: "power2.out",
-    });
-  }
-
-  fadeIn(element: AnimationTarget, duration = 0.3): void {
-    if (!element) return;
-    gsap.fromTo(
-      element,
-      { opacity: 0, y: 5 },
-      { opacity: 1, y: 0, duration, ease: "power2.out" },
-    );
-  }
-
-  fadeOut(element: AnimationTarget, duration = 0.2): Promise<void> {
-    return new Promise((resolve) => {
-      if (!element) {
-        resolve();
-        return;
-      }
-      gsap.to(element, {
-        opacity: 0,
-        duration,
-        ease: "power2.in",
-        onComplete: resolve,
-      });
-    });
-  }
-
-  pulseGlow(id: AnimationId, element: AnimationTarget, color: string): void {
-    if (!element) return;
-    const animation = gsap.to(element, {
-      boxShadow: `0 0 25px ${color}`,
-      duration: 2.5,
-      repeat: -1,
-      yoyo: true,
-      ease: "sine.inOut",
-    });
-    this.animations.set(id, { target: element, animation });
-  }
-
-  borderPulse(id: AnimationId, element: AnimationTarget, color: string): void {
-    if (!element) return;
-    const animation = gsap.to(element, {
-      borderColor: color,
-      duration: 2,
-      repeat: -1,
-      yoyo: true,
-      ease: "sine.inOut",
-    });
-    this.animations.set(id, { target: element, animation });
-  }
-
-  smoothScroll(
-    element: AnimationTarget,
-    targetScroll: number,
-    duration?: number,
-  ): Promise<void> {
-    return new Promise((resolve) => {
-      if (!element) {
-        resolve();
-        return;
-      }
-
-      const currentScroll = element.scrollTop;
-      const distance = Math.abs(targetScroll - currentScroll);
-      const calculatedDuration = duration ?? Math.min(0.5, distance / 1000);
-
-      gsap.to(element, {
-        scrollTop: targetScroll,
-        duration: calculatedDuration,
-        ease: "power2.out",
-        onComplete: resolve,
-      });
-    });
-  }
-
-  cursorBlink(id: AnimationId, element: AnimationTarget): void {
-    if (!element) return;
-    gsap.set(element, { display: "inline-block", opacity: 1 });
-    const animation = gsap.to(element, {
-      opacity: 0,
-      duration: 0.5,
-      repeat: -1,
-      yoyo: true,
-      ease: "steps(1)",
-    });
-    this.animations.set(id, { target: element, animation });
-  }
-
-  hideCursor(element: AnimationTarget): Promise<void> {
-    return new Promise((resolve) => {
-      if (!element) {
-        resolve();
-        return;
-      }
-      gsap.killTweensOf(element);
-      gsap.to(element, {
-        opacity: 0,
-        duration: 0.2,
-        onComplete: () => {
-          gsap.set(element, { display: "none" });
-          resolve();
-        },
-      });
-    });
-  }
-
-  slideDown(element: AnimationTarget, duration = 0.3): void {
-    if (!element) return;
-    gsap.from(element, {
-      height: 0,
-      opacity: 0,
-      duration,
-      ease: "power2.out",
-    });
-  }
-
-  slideUp(element: AnimationTarget, duration = 0.3): Promise<void> {
-    return new Promise((resolve) => {
-      if (!element) {
-        resolve();
-        return;
-      }
-      gsap.to(element, {
-        height: 0,
-        opacity: 0,
-        duration,
-        ease: "power2.in",
-        onComplete: resolve,
-      });
-    });
-  }
-}
-
-export const animationController = new AnimationController();

src/lib/controllers/context.md

@@ -12,23 +12,20 @@ Business logic and orchestration layer
 
 ```
 controllers/
-├── context.md              # This file
-├── chat-controller.ts      # Chat operations and state management
-└── animation-controller.ts # Centralized GSAP animations
+├── context.md          # This file
+└── chat-controller.ts  # Chat operations and state management
 ```
 
 ## Scope
 
-- In-scope: Business logic, state orchestration, animations
+- In-scope: Business logic, state orchestration
 - Out-of-scope: UI rendering, direct store access from components
 
 ## Entrypoints
 
 - `chatController` - All chat operations
-- `animationController` - UI animations
 
 ## Dependencies
 
 - Stores for state updates
 - Services for external operations
-- GSAP for animations

src/lib/models/context.md

@@ -10,8 +10,9 @@ Define data shapes, types, and factory functions for type safety
 
 ```
 models/
-├── context.md     # This file
-└── chat-data.ts   # Chat types and factories
+├── context.md        # This file
+├── chat-data.ts      # Chat types and factories
+└── segment-view.ts   # Segment visualization and todo parsing
 ```
 
 ## Scope

src/lib/models/segment-view.ts

@@ -77,9 +77,6 @@ function getSegmentTitle(segment: MessageSegment): string {
       update_task: "✏️ Update Task",
       view_tasks: "👀 View Tasks",
       observe_console: "📺 Console Output",
-      read_file: "📖 Read File",
-      write_file: "✍️ Write File",
-      edit_file: "✏️ Edit File",
     };
     return toolNames[segment.toolName] || `🔧 ${segment.toolName}`;
   }

src/lib/server/console-buffer.ts

@@ -3,13 +3,16 @@ export interface ConsoleBufferMessage {
   type: "log" | "warn" | "error" | "info";
   message: string;
   timestamp: number;
+  context?: string;
 }
 
 export class ConsoleBuffer {
   private static instance: ConsoleBuffer | null = null;
   private messages: ConsoleBufferMessage[] = [];
-  private maxMessages = 100;
+  private maxMessages = 200;
   private lastReadTimestamp = 0;
+  private executionContext: string | null = null;
+  private messagesSinceLastTool: ConsoleBufferMessage[] = [];
 
   private constructor() {}
 
@@ -21,19 +24,39 @@ export class ConsoleBuffer {
   }
 
   addMessage(message: ConsoleBufferMessage): void {
+    if (this.executionContext) {
+      message.context = this.executionContext;
+    }
+
     this.messages.push(message);
+    this.messagesSinceLastTool.push(message);
 
     if (this.messages.length > this.maxMessages) {
       this.messages = this.messages.slice(-this.maxMessages);
     }
+
+    if (this.messagesSinceLastTool.length > 50) {
+      this.messagesSinceLastTool = this.messagesSinceLastTool.slice(-50);
+    }
   }
 
-  getRecentMessages(since?: number): ConsoleBufferMessage[] {
+  getRecentMessages(since?: number, limit?: number): ConsoleBufferMessage[] {
     const sinceTimestamp = since || this.lastReadTimestamp;
-    return this.messages.filter((msg) => msg.timestamp > sinceTimestamp);
+    const filtered = this.messages.filter(
+      (msg) => msg.timestamp > sinceTimestamp,
+    );
+
+    if (limit && limit > 0 && filtered.length > limit) {
+      return filtered.slice(-limit);
+    }
+
+    return filtered;
   }
 
-  getAllMessages(): ConsoleBufferMessage[] {
+  getAllMessages(limit?: number): ConsoleBufferMessage[] {
+    if (limit && limit > 0 && this.messages.length > limit) {
+      return this.messages.slice(-limit);
+    }
     return [...this.messages];
   }
 
@@ -45,8 +68,40 @@ export class ConsoleBuffer {
   }
 
   clear(): void {
-    this.messages = [];
     this.lastReadTimestamp = Date.now();
+    this.messagesSinceLastTool = [];
+  }
+
+  onGameReloadStart(): void {
+    this.messagesSinceLastTool = [];
+    this.lastReadTimestamp = Date.now();
+    this.addMessage({
+      id: `reload-${Date.now()}`,
+      type: "info",
+      message: "🔄 Game reloading...",
+      timestamp: Date.now(),
+    });
+  }
+
+  onGameReloadComplete(): void {
+    this.addMessage({
+      id: `reload-complete-${Date.now()}`,
+      type: "info",
+      message: "✅ Game reload complete",
+      timestamp: Date.now(),
+    });
+  }
+
+  setExecutionContext(context: string | null): void {
+    this.executionContext = context;
+  }
+
+  getMessagesSinceLastTool(): ConsoleBufferMessage[] {
+    return [...this.messagesSinceLastTool];
+  }
+
+  clearToolMessages(): void {
+    this.messagesSinceLastTool = [];
   }
 
   getGameStateFromMessages(): {
@@ -54,8 +109,21 @@ export class ConsoleBuffer {
     hasError: boolean;
     lastError?: string;
     isReady: boolean;
+    isReloading: boolean;
+    messageCount: number;
   } {
-    const recentMessages = this.getRecentMessages(Date.now() - 5000);
+    const recentMessages =
+      this.messagesSinceLastTool.length > 0
+        ? this.messagesSinceLastTool
+        : this.getRecentMessages(Date.now() - 5000);
+
+    const hasReloadStartMessage = recentMessages.some((msg) =>
+      msg.message.includes("🔄 Game reloading"),
+    );
+
+    const hasReloadCompleteMessage = recentMessages.some((msg) =>
+      msg.message.includes("✅ Game reload complete"),
+    );
 
     const hasStartMessage = recentMessages.some(
       (msg) =>
@@ -70,6 +138,7 @@ export class ConsoleBuffer {
         msg.message.includes("✅ Game started") ||
         msg.message.includes("Game started!") ||
         msg.message.includes("Game script loaded!") ||
+        msg.message.includes("✅ Game reload complete") ||
         msg.message.includes("successfully"),
     );
 
@@ -87,12 +156,18 @@ export class ConsoleBuffer {
         ? errorMessages[errorMessages.length - 1].message
         : undefined;
 
+    const isReloading = hasReloadStartMessage && !hasReloadCompleteMessage;
+
     return {
       isLoading:
-        hasStartMessage && !hasSuccessMessage && errorMessages.length === 0,
+        (hasStartMessage || isReloading) &&
+        !hasSuccessMessage &&
+        errorMessages.length === 0,
       hasError: errorMessages.length > 0,
       lastError,
-      isReady: hasSuccessMessage && errorMessages.length === 0,
+      isReady: hasSuccessMessage && errorMessages.length === 0 && !isReloading,
+      isReloading,
+      messageCount: recentMessages.length,
     };
   }
 }

src/lib/server/context.md

@@ -4,19 +4,21 @@ WebSocket server with LangGraph agent for AI-assisted game development.
 
 ## Key Components
 
-- **api.ts** - WebSocket message routing with virtual file sync
-- **langgraph-agent.ts** - LangGraph agent with MCP tools
-- **mcp-client.ts** - MCP tools for virtual file operations and Context7 docs
-- **tools.ts** - Console observation and task tracking
-- **console-buffer.ts** - Console message buffering with game state analysis
+- **api.ts** - WebSocket message routing and connection management
+- **langgraph-agent.ts** - LangGraph agent with tool deduplication and conflict detection
+- **mcp-client.ts** - Editor tools with pre-validation and standardized responses
+- **tools.ts** - Console observation with tail limiting
+- **task-tracker.ts** - Task planning and management tools
+- **console-buffer.ts** - Console buffering with lifecycle events and tail limiting
 
 ## Architecture
 
-LangGraph agent with bidirectional content synchronization:
+LangGraph agent with robust tool execution:
 
-- Virtual file system treats editor as single HTML file
-- MCP tools operate directly on virtual file system
-- Real-time bidirectional sync with ContentManager
+- Virtual file system with version tracking and edit history
+- Tool call deduplication to prevent redundant operations
+- Sequential tool execution with state tracking
+- Pre-validation for edit operations to detect conflicts
 - Context7 integration for external library documentation
 - Buffered streaming with segment handling
 - AbortController for canceling conversations

src/lib/server/documentation.ts

@@ -5,7 +5,7 @@ export class DocumentationService {
   private cache: string | null = null;
   private readonly docsPath: string;
 
-  constructor(filename: string = "agents.md") {
+  constructor(filename: string = "llms.txt") {
     this.docsPath = join(process.cwd(), filename);
   }
 

src/lib/server/langgraph-agent.ts

@@ -10,6 +10,11 @@ import { observeConsoleTool } from "./tools";
 import { mcpClientManager, setMCPWebSocketConnection } from "./mcp-client";
 import { planTasksTool, updateTaskTool, viewTasksTool } from "./task-tracker";
 import { documentationService } from "./documentation";
+import {
+  StreamingToolCallParser,
+  extractToolCalls,
+} from "../utils/tool-call-parser";
+import { virtualFileSystem } from "../services/virtual-fs";
 import type { WebSocket } from "ws";
 
 const AgentState = Annotation.Root({
@@ -58,146 +63,86 @@ export class LangGraphAgent {
       const messages = this.formatMessages(state.messages, systemPrompt);
 
       let fullResponse = "";
+      const parser = new StreamingToolCallParser();
       let currentSegmentId: string | null = null;
-      let currentSegmentContent = "";
-      let buffer = "";
       const messageId = config?.metadata?.messageId;
       const abortSignal = config?.metadata?.abortSignal as
         | AbortSignal
         | undefined;
 
-      const toolRegex = /TOOL:\s*(\w+)\s+ARGS:\s*({[^}]*})/g;
-
       for await (const token of this.streamModelResponse(
         messages,
         abortSignal,
       )) {
         fullResponse += token;
         config?.writer?.({ type: "token", content: token });
-        buffer += token;
-
-        let processedUpTo = 0;
-        let match;
-        toolRegex.lastIndex = 0;
-
-        while ((match = toolRegex.exec(buffer)) !== null) {
-          const textBefore = buffer.substring(processedUpTo, match.index);
-
-          if (textBefore.trim() && this.ws) {
-            if (!currentSegmentId) {
-              currentSegmentId = `seg_${Date.now()}_${Math.random()}`;
-              currentSegmentContent = "";
-              this.ws.send(
-                JSON.stringify({
-                  type: "segment_start",
-                  payload: {
-                    segmentId: currentSegmentId,
-                    segmentType: "text",
-                    messageId,
-                  },
-                  timestamp: Date.now(),
-                }),
-              );
-            }
 
-            currentSegmentContent += textBefore;
-            this.ws.send(
-              JSON.stringify({
-                type: "segment_token",
-                payload: {
-                  segmentId: currentSegmentId,
-                  token: textBefore,
-                  messageId,
-                },
-                timestamp: Date.now(),
-              }),
-            );
-          }
+        // Process token through the parser
+        const parseResult = parser.process(token);
 
-          if (currentSegmentId && currentSegmentContent.trim() && this.ws) {
+        // Only stream safe text (without tool calls)
+        if (parseResult.safeText) {
+          // Start a text segment if needed
+          if (!currentSegmentId && parseResult.safeText.trim() && this.ws) {
+            currentSegmentId = `seg_${Date.now()}_${Math.random()}`;
             this.ws.send(
               JSON.stringify({
-                type: "segment_end",
+                type: "segment_start",
                 payload: {
                   segmentId: currentSegmentId,
-                  content: currentSegmentContent,
+                  segmentType: "text",
                   messageId,
                 },
                 timestamp: Date.now(),
               }),
             );
-            currentSegmentId = null;
-            currentSegmentContent = "";
           }
 
-          processedUpTo = match.index + match[0].length;
-        }
-
-        if (processedUpTo > 0) {
-          buffer = buffer.substring(processedUpTo);
-        } else if (buffer.length > 100 && !buffer.includes("TOOL:")) {
-          if (!currentSegmentId && buffer.trim() && this.ws) {
-            currentSegmentId = `seg_${Date.now()}_${Math.random()}`;
-            currentSegmentContent = "";
+          // Stream the safe text
+          if (currentSegmentId && this.ws) {
             this.ws.send(
               JSON.stringify({
-                type: "segment_start",
+                type: "segment_token",
                 payload: {
                   segmentId: currentSegmentId,
-                  segmentType: "text",
+                  token: parseResult.safeText,
                   messageId,
                 },
                 timestamp: Date.now(),
               }),
             );
           }
-
-          if (currentSegmentId) {
-            currentSegmentContent += buffer;
-            if (this.ws) {
-              this.ws.send(
-                JSON.stringify({
-                  type: "segment_token",
-                  payload: {
-                    segmentId: currentSegmentId,
-                    token: buffer,
-                    messageId,
-                  },
-                  timestamp: Date.now(),
-                }),
-              );
-            }
-          }
-          buffer = "";
         }
-      }
 
-      if (buffer.trim() && !buffer.match(/TOOL:\s*(\w+)\s+ARGS:\s*({[^}]*})/)) {
-        if (!currentSegmentId && this.ws) {
-          currentSegmentId = `seg_${Date.now()}_${Math.random()}`;
-          currentSegmentContent = "";
+        // If we detected a tool call start, end the current text segment
+        if (parseResult.pendingToolCall && currentSegmentId && this.ws) {
           this.ws.send(
             JSON.stringify({
-              type: "segment_start",
+              type: "segment_end",
               payload: {
                 segmentId: currentSegmentId,
-                segmentType: "text",
                 messageId,
               },
               timestamp: Date.now(),
             }),
           );
+          currentSegmentId = null;
         }
+      }
 
-        if (currentSegmentId) {
-          currentSegmentContent += buffer;
-          if (this.ws) {
+      // Finalize any remaining text segment
+      if (currentSegmentId && this.ws) {
+        // Process any remaining buffered content
+        const remainingBuffer = parser.getBuffer();
+        if (remainingBuffer && !parser.isInToolCall()) {
+          const finalResult = parser.process("");
+          if (finalResult.safeText) {
             this.ws.send(
               JSON.stringify({
                 type: "segment_token",
                 payload: {
                   segmentId: currentSegmentId,
-                  token: buffer,
+                  token: finalResult.safeText,
                   messageId,
                 },
                 timestamp: Date.now(),
@@ -205,15 +150,12 @@ export class LangGraphAgent {
             );
           }
         }
-      }
 
-      if (currentSegmentId && currentSegmentContent.trim() && this.ws) {
         this.ws.send(
           JSON.stringify({
             type: "segment_end",
             payload: {
               segmentId: currentSegmentId,
-              content: currentSegmentContent,
               messageId,
             },
             timestamp: Date.now(),
@@ -221,7 +163,7 @@ export class LangGraphAgent {
         );
       }
 
-      const toolCalls = this.parseToolCalls(fullResponse);
+      const toolCalls = extractToolCalls(fullResponse);
 
       if (toolCalls.length > 0) {
         const toolResults = await this.executeToolsWithSegments(
@@ -294,85 +236,156 @@ export class LangGraphAgent {
   }
 
   private buildSystemPrompt(): string {
-    return `You are an expert VibeGame developer assistant with MCP (Model Context Protocol) tools for direct code manipulation.
-
-## Core Principles
-- ALWAYS use tools to complete tasks - never provide instructions without execution
-- Use the EXACT format: TOOL: tool_name ARGS: {"param": "value"}
-- Wait for tool results before proceeding to next step
-- The game auto-reloads after each editor change
-
-## Tool Usage Strategy
-
-### 1. SEARCH FIRST
-Always search before reading or editing to locate relevant code:
-- search_editor: Find functions, components, or patterns by text/regex
-- read_editor_lines: Examine specific sections after search
-- read_editor: Only when you need the complete file context
-
-### 2. EDIT INCREMENTALLY
-Keep edits small and focused:
-- edit_editor: For targeted changes (max ~20 lines)
-- write_editor: Only for complete file rewrites or new files
-- Break large changes into multiple edit_editor calls
-
-### 3. TASK PLANNING
-For complex work (3+ steps), use task management:
-- plan_tasks: Decompose work into clear steps
-- update_task: Track progress (in_progress → completed)
-- view_tasks: Review current task list
-
-### 4. RESEARCH LIBRARIES
-For external libraries/frameworks beyond VibeGame:
-- resolve_library_id: Find Context7-compatible library ID first
-- get_library_docs: Fetch current documentation with targeted search
-
-### 5. VERIFY CHANGES
-- observe_console: Check for errors after edits
-- Monitor game reload status in tool responses
-
-## MCP Tools Reference
-
-### Code Analysis
-- search_editor: {"query": "text", "mode": "text|regex", "contextLines": 2}
-- read_editor: {}
-- read_editor_lines: {"startLine": 1, "endLine": 10}
-
-### Code Modification
-- edit_editor: {"oldText": "exact text", "newText": "replacement"}
-- write_editor: {"content": "complete file content"}
-
-### Task Management
-- plan_tasks: {"tasks": ["step 1", "step 2", ...]}
-- update_task: {"taskId": 1, "status": "in_progress|completed"}
-- view_tasks: {}
-
-
-### Documentation & Research
-- resolve_library_id: {"libraryName": "gsap"} - Find Context7-compatible library ID
-- get_library_docs: {"context7CompatibleLibraryID": "/greensock/gsap", "tokens": 5000, "topic": "animations"} - Fetch up-to-date docs
-
-### Debugging
-- observe_console: {}
-
-## VibeGame Context
+    return `## Role & Primary Guidance
+You are a VibeGame Engine Specialist operating in a single-file editor environment. You work with ONE game file that users can see and edit in real-time, similar to JSFiddle or CodePen.
+
+## Live Coding Environment Context
+- **SINGLE EDITOR**: There is exactly ONE editor file containing the game's XML/HTML code
+- **"The code" ALWAYS refers to**: The content currently in the editor
+- **Live Preview**: Changes to the editor automatically reload the game
+- **User's View**: Users see the same editor you're modifying
+- **GAME is PRE-IMPORTED**: The GAME object is automatically available - NEVER write \`import * as GAME from 'vibegame'\`
+- **Auto-run enabled**: GAME.run() is called automatically - use \`GAME.withPlugin(MyPlugin)\` NOT \`GAME.withPlugin(MyPlugin).run()\`
+
+## VibeGame Expert Knowledge
 ${this.documentation}
 
-## Example Workflows
-
-### VibeGame Edit:
-User: "Change the ball color to blue"
-1. TOOL: search_editor ARGS: {"query": "ball"}
-2. TOOL: read_editor_lines ARGS: {"startLine": 10, "endLine": 15}
-3. TOOL: edit_editor ARGS: {"oldText": "color=\\"#ff4500\\"", "newText": "color=\\"#0000ff\\""}
-4. TOOL: observe_console ARGS: {}
-
-### External Library Research:
-User: "How do I create GSAP animations?"
-1. TOOL: resolve_library_id ARGS: {"libraryName": "gsap"}
-2. TOOL: get_library_docs ARGS: {"context7CompatibleLibraryID": "/greensock/gsap", "topic": "animations"}
-
-Remember: Execute immediately. Don't explain - just do.`;
+## MCP Tool Execution Protocol
+
+### Format Requirements
+- MANDATORY format: <tool name="tool_name">{"param": "value"}</tool>
+- JSON arguments must be valid JSON (use double quotes for strings)
+- **CRITICAL**: Execute ONE tool at a time and wait for the result
+- The parser will handle unclosed tags gracefully for recovery
+- **NEVER** generate multiple tool calls in a single response
+- After each tool execution, analyze the result before deciding next action
+- ALWAYS check console after making changes
+- The game auto-reloads after editor changes
+
+### Tool Execution Rules
+1. Execute a single tool
+2. Read and analyze the tool's response
+3. Only then decide if another tool is needed
+4. If multiple edits are needed, use plan_tasks first to organize them
+
+### Available MCP Tools (All operate on the SINGLE editor file)
+
+#### Understanding the Editor Content
+- search_editor: Find text/patterns in the current game code
+  Parameters:
+  - query: string - Text or regex pattern to search for
+  - mode: "text" | "regex" - Search mode (optional, default: "text")
+  - contextLines: number - Lines of context (optional, default: 2, max: 5)
+  Example: <tool name="search_editor">{"query": "dynamic-part", "mode": "text"}</tool>
+
+- read_editor_lines: Read specific lines from the current game code
+  Parameters:
+  - startLine: number - Starting line (1-indexed)
+  - endLine: number - Ending line (optional, defaults to startLine)
+  Example: <tool name="read_editor_lines">{"startLine": 10, "endLine": 20}</tool>
+
+- read_editor: Read the complete game code currently in the editor
+  Parameters: none
+  Example: <tool name="read_editor">{}</tool>
+  Note: Use when user asks to "explain the code", "show the code", or needs full context
+
+#### Modifying the Game
+- edit_editor: Make targeted changes to the game code
+  Parameters:
+  - oldText: string - Exact text to find and replace (max ~20 lines). MUST include actual content, not just whitespace
+  - newText: string - Replacement text
+  Example: <tool name="edit_editor">{"oldText": "color='#ff0000'", "newText": "color='#00ff00'"}</tool>
+  IMPORTANT: Always include meaningful content (tags, comments, or code) in oldText, never just spaces/newlines
+  Note: Returns standardized response with game status and console output
+
+- write_editor: Replace all game code with new content
+  Parameters:
+  - content: string - Complete new game code
+  Example: <tool name="write_editor">{"content": "<world>...</world>"}</tool>
+  Note: Use ONLY for starting fresh or complete rewrites
+
+#### Task Management
+- plan_tasks: Create task list for complex operations
+  Parameters:
+  - tasks: string[] - Array of task descriptions
+  Example: <tool name="plan_tasks">{"tasks": ["Add physics component", "Create gravity system", "Test gravity effect"]}</tool>
+
+- update_task: Update task status
+  Parameters:
+  - taskId: number - Task ID to update
+  - status: "pending" | "in_progress" | "completed"
+  Example: <tool name="update_task">{"taskId": 1, "status": "completed"}</tool>
+
+- view_tasks: View current task list
+  Parameters: none
+  Example: <tool name="view_tasks">{}</tool>
+
+#### Runtime Monitoring
+- observe_console: Check console messages and game state
+  Parameters: none
+  Example: <tool name="observe_console">{}</tool>
+  Note: Returns recent console messages and game status
+
+## Tool Response Format
+All editor modification tools return:
+- Success indicator (✅ or ❌)
+- Action description
+- Game status (Running/Error/Loading)
+- Console output from the game
+
+## Common User Requests (Context Clarification)
+When users say:
+- "explain the code" → Read and explain the CURRENT editor content
+- "what's in the game?" → Describe the entities/elements in the editor
+- "fix the error" → Check console, then modify the editor content
+- "add a..." → Add new elements to the existing editor content
+- "change the..." → Modify existing elements in the editor
+
+## Execution Patterns
+
+### Code Writing Rules (Live Environment)
+- **NO IMPORTS**: GAME is pre-imported globally - NEVER write \`import * as GAME from 'vibegame'\`
+- **NO .run()**: Auto-run is enabled - write \`GAME.withPlugin(MyPlugin)\` not \`GAME.withPlugin(MyPlugin).run()\`
+- **Direct access**: Use GAME.defineComponent, GAME.Types, etc. directly
+- **Script tags**: When adding JavaScript, use \`<script>\` tags in the XML/HTML
+
+### Standard Workflow (ONE TOOL AT A TIME)
+1. Execute: <tool name="read_editor">{}</tool> (if needed) → WAIT for result
+2. Execute: <tool name="search_editor">{"query": "target_element"}</tool> → WAIT for result
+3. Execute: <tool name="read_editor_lines">{"startLine": X, "endLine": Y}</tool> → WAIT for result
+4. Execute: <tool name="edit_editor">{"oldText": "...", "newText": "..."}</tool> → WAIT for result
+5. Execute: <tool name="observe_console">{}</tool> → WAIT for result
+6. Based on console output, decide if another edit is needed
+
+### IMPORTANT: Sequential Tool Execution
+- NEVER chain multiple TOOL: commands in one response
+- Each tool call must be in its own separate message
+- Always analyze the tool result before proceeding
+- If you need to make multiple edits, use plan_tasks to organize them first
+
+### Error Recovery
+When you see an error in tool results:
+1. Read the error message carefully
+2. Search for the problematic code
+3. Make corrections with edit_editor
+4. Verify fix with observe_console
+
+### Complex Changes
+For changes requiring multiple edits:
+1. <tool name="plan_tasks">{"tasks": [...]}</tool>
+2. Update task status as you progress
+3. Break edits into small chunks (<20 lines each)
+4. Test after each significant change
+
+## Critical Rules
+- REMEMBER: You work with ONE editor file - all references to "the code" mean this single file
+- ALWAYS check console output after edits
+- NEVER skip tool execution - implement directly
+- Use exact text matches for edit_editor
+- Keep individual edits small and focused
+- When unsure what user refers to, assume they mean the editor content
+
+Remember: You're in a live coding environment. Users see the same editor you're modifying. Tool responses include console output - read them carefully to understand game state.`;
   }
 
   private async *streamModelResponse(
@@ -407,37 +420,6 @@ Remember: Execute immediately. Don't explain - just do.`;
     return fullContent;
   }
 
-  private parseToolCalls(
-    response: string,
-  ): Array<{ name: string; args: Record<string, unknown> }> {
-    const toolCalls = [];
-    const toolRegex = /TOOL:\s*(\w+)\s+ARGS:\s*({[^}]*})/gs;
-    let match;
-
-    while ((match = toolRegex.exec(response)) !== null) {
-      const toolName = match[1];
-      let params = {};
-
-      if (match[2]) {
-        try {
-          params = JSON.parse(match[2]);
-        } catch {
-          console.error(
-            `Failed to parse tool parameters for ${toolName}: ${match[2]}`,
-          );
-          params = {};
-        }
-      }
-
-      toolCalls.push({
-        name: toolName,
-        args: params,
-      });
-    }
-
-    return toolCalls;
-  }
-
   private shouldUseTools(content: string): boolean {
     const lowerContent = content.toLowerCase();
 
@@ -469,6 +451,39 @@ Remember: Execute immediately. Don't explain - just do.`;
     return actionKeywords.some((keyword) => lowerContent.includes(keyword));
   }
 
+  /**
+   * Deduplicate tool calls to prevent redundant operations
+   */
+  private deduplicateToolCalls(
+    toolCalls: Array<{ name: string; args: Record<string, unknown> }>,
+  ): Array<{ name: string; args: Record<string, unknown> }> {
+    const deduplicated: Array<{ name: string; args: Record<string, unknown> }> =
+      [];
+    const seenOperations = new Set<string>();
+
+    for (const call of toolCalls) {
+      let signature = `${call.name}:`;
+
+      if (call.name === "edit_editor") {
+        const oldText = call.args.oldText as string;
+        signature += oldText?.substring(0, 100);
+      } else if (call.name === "write_editor") {
+        signature += "FULL_REPLACE";
+      } else {
+        signature += JSON.stringify(call.args);
+      }
+
+      if (!seenOperations.has(signature)) {
+        seenOperations.add(signature);
+        deduplicated.push(call);
+      } else {
+        console.warn(`Skipping duplicate tool call: ${call.name}`);
+      }
+    }
+
+    return deduplicated;
+  }
+
   private formatMessages(
     messages: BaseMessage[],
     systemPrompt: string,
@@ -504,9 +519,47 @@ Remember: Execute immediately. Don't explain - just do.`;
   ): Promise<BaseMessage[]> {
     const results = [];
 
-    for (const call of toolCalls) {
+    const processedCalls = this.deduplicateToolCalls(toolCalls);
+    const stateTracker = {
+      editorModified: false,
+      lastEditContent: "",
+    };
+
+    for (const call of processedCalls) {
       const segmentId = `seg_tool_${Date.now()}_${Math.random()}`;
 
+      const validation = this.validateToolCall(call);
+      if (!validation.valid) {
+        console.error(`Invalid tool call: ${call.name}`, validation.error);
+        results.push(
+          new ToolMessage({
+            content: `Error: ${validation.error}`,
+            tool_call_id: segmentId,
+            name: call.name,
+          }),
+        );
+        continue;
+      }
+
+      if (call.name === "edit_editor" && stateTracker.editorModified) {
+        const currentContent = virtualFileSystem.getGameFile().content;
+        const oldText = call.args.oldText as string;
+
+        if (!currentContent.includes(oldText)) {
+          console.warn(
+            `Skipping edit_editor: Text no longer exists after previous edit`,
+          );
+          results.push(
+            new ToolMessage({
+              content: `Skipped: The text to replace was already modified by a previous edit. The current operation is no longer needed.`,
+              tool_call_id: segmentId,
+              name: call.name,
+            }),
+          );
+          continue;
+        }
+      }
+
       try {
         const argString = JSON.stringify(call.args);
         const estimatedTokens = argString.length / 4;
@@ -571,6 +624,12 @@ Remember: Execute immediately. Don't explain - just do.`;
         if (tool) {
           result = await tool.func(call.args);
 
+          if (call.name === "edit_editor" || call.name === "write_editor") {
+            stateTracker.editorModified = true;
+            stateTracker.lastEditContent =
+              virtualFileSystem.getGameFile().content;
+          }
+
           const consoleMatch = result.match(/Console output:\n([\s\S]*?)$/);
           if (consoleMatch) {
             consoleOutput = consoleMatch[1]
@@ -674,6 +733,91 @@ Remember: Execute immediately. Don't explain - just do.`;
     return results;
   }
 
+  private validateToolCall(call: {
+    name: string;
+    args: Record<string, unknown>;
+  }): { valid: boolean; error?: string } {
+    // Basic validation for known tools
+    const toolValidations: Record<
+      string,
+      (args: Record<string, unknown>) => string | null
+    > = {
+      edit_editor: (args) => {
+        if (!args.oldText || typeof args.oldText !== "string") {
+          return "Missing or invalid 'oldText' parameter";
+        }
+        if (!args.newText || typeof args.newText !== "string") {
+          return "Missing or invalid 'newText' parameter";
+        }
+        const lines = (args.oldText as string).split("\n").length;
+        if (lines > 30) {
+          return `Edit too large (${lines} lines). Break into smaller edits.`;
+        }
+        return null;
+      },
+      write_editor: (args) => {
+        if (!args.content || typeof args.content !== "string") {
+          return "Missing or invalid 'content' parameter";
+        }
+        return null;
+      },
+      search_editor: (args) => {
+        if (!args.query || typeof args.query !== "string") {
+          return "Missing or invalid 'query' parameter";
+        }
+        if (args.mode && !["text", "regex"].includes(args.mode as string)) {
+          return "Invalid 'mode' parameter. Must be 'text' or 'regex'";
+        }
+        return null;
+      },
+      read_editor_lines: (args) => {
+        if (!args.startLine || typeof args.startLine !== "number") {
+          return "Missing or invalid 'startLine' parameter";
+        }
+        if (args.startLine < 1) {
+          return "'startLine' must be >= 1";
+        }
+        if (args.endLine && typeof args.endLine !== "number") {
+          return "Invalid 'endLine' parameter";
+        }
+        return null;
+      },
+      plan_tasks: (args) => {
+        if (!args.tasks || !Array.isArray(args.tasks)) {
+          return "Missing or invalid 'tasks' parameter. Must be an array.";
+        }
+        if (args.tasks.length === 0) {
+          return "'tasks' array cannot be empty";
+        }
+        return null;
+      },
+      update_task: (args) => {
+        if (typeof args.taskId !== "number") {
+          return "Missing or invalid 'taskId' parameter";
+        }
+        if (
+          !args.status ||
+          !["pending", "in_progress", "completed"].includes(
+            args.status as string,
+          )
+        ) {
+          return "Invalid 'status' parameter. Must be 'pending', 'in_progress', or 'completed'";
+        }
+        return null;
+      },
+    };
+
+    const validator = toolValidations[call.name];
+    if (validator) {
+      const error = validator(call.args);
+      if (error) {
+        return { valid: false, error };
+      }
+    }
+
+    return { valid: true };
+  }
+
   async processMessage(
     message: string,
     messageHistory: BaseMessage[] = [],

src/lib/server/mcp-client.ts

@@ -2,7 +2,7 @@ import { DynamicStructuredTool } from "@langchain/core/tools";
 import { z } from "zod";
 import type { WebSocket } from "ws";
 import { consoleBuffer } from "./console-buffer";
-import { virtualFileSystem, VirtualFileSystem } from "../services/virtual-fs";
+import { virtualFileSystem } from "../services/virtual-fs";
 
 interface EditorWebSocketConnection {
   send: (message: {
@@ -28,6 +28,116 @@ export function setMCPWebSocketConnection(ws: WebSocket) {
   };
 }
 
+/**
+ * Standardized tool response builder
+ */
+function buildToolResponse({
+  success,
+  action,
+  error,
+  gameState,
+  consoleOutput,
+}: {
+  success: boolean;
+  action: string;
+  error?: string;
+  gameState?: ReturnType<typeof consoleBuffer.getGameStateFromMessages>;
+  consoleOutput?: string[];
+}): string {
+  const sections: string[] = [];
+
+  // Status section
+  if (success) {
+    sections.push(`✅ ${action} completed successfully.`);
+  } else {
+    sections.push(`❌ ${action} failed.`);
+  }
+
+  // Error section
+  if (error) {
+    sections.push(`\nError: ${error}`);
+  }
+
+  // Game state section
+  if (gameState) {
+    if (gameState.isReady) {
+      sections.push("\n🎮 Game Status: Running");
+    } else if (gameState.hasError) {
+      sections.push(`\n🎮 Game Status: Error\n   ${gameState.lastError}`);
+    } else if (gameState.isLoading) {
+      sections.push("\n🎮 Game Status: Loading...");
+    } else {
+      sections.push("\n🎮 Game Status: Unknown");
+    }
+  }
+
+  // Console output section
+  if (consoleOutput && consoleOutput.length > 0) {
+    sections.push("\n📝 Console Output:");
+    sections.push(consoleOutput.join("\n"));
+  }
+
+  return sections.join("\n");
+}
+
+/**
+ * Wait for game state with improved console capture
+ */
+async function waitForGameState(
+  toolName: string,
+  maxWaitTime: number = 5000,
+): Promise<{
+  gameState: ReturnType<typeof consoleBuffer.getGameStateFromMessages>;
+  consoleOutput: string[];
+}> {
+  // Set execution context for console messages
+  consoleBuffer.setExecutionContext(toolName);
+  consoleBuffer.clearToolMessages();
+
+  const startTime = Date.now();
+
+  // Initial wait for game to process changes (increased to match GameCanvas reload delay)
+  await new Promise((resolve) => setTimeout(resolve, 2000));
+
+  while (Date.now() - startTime < maxWaitTime) {
+    const gameState = consoleBuffer.getGameStateFromMessages();
+
+    // Check if we have a definitive state (not reloading, and either ready or error)
+    if (!gameState.isReloading && (gameState.isReady || gameState.hasError)) {
+      const messages = consoleBuffer.getMessagesSinceLastTool();
+      const consoleOutput = messages
+        .slice(-30)
+        .map((m) => `[${m.type}] ${m.message}`);
+
+      // Clear context
+      consoleBuffer.setExecutionContext(null);
+      consoleBuffer.markAsRead();
+
+      return { gameState, consoleOutput };
+    }
+
+    // If still reloading, wait longer
+    if (gameState.isReloading) {
+      await new Promise((resolve) => setTimeout(resolve, 200));
+    } else {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  // Timeout - return current state
+  const gameState = consoleBuffer.getGameStateFromMessages();
+  const messages = consoleBuffer.getMessagesSinceLastTool();
+  const consoleOutput = messages
+    .slice(-30)
+    .map((m) => `[${m.type}] ${m.message}`);
+
+  // Clear context
+  consoleBuffer.setExecutionContext(null);
+  consoleBuffer.markAsRead();
+
+  return { gameState, consoleOutput };
+}
+
 /**
  * MCPClientManager provides MCP-style tools for editor operations
  * Currently uses local implementation, can be extended to use actual MCP servers
@@ -48,30 +158,6 @@ export class MCPClientManager {
   private createEditorTools(): DynamicStructuredTool[] {
     const tools: DynamicStructuredTool[] = [];
 
-    tools.push(
-      new DynamicStructuredTool({
-        name: "read_file",
-        description:
-          "Read a file from the virtual file system - defaults to /game.html",
-        schema: z.object({
-          path: z
-            .string()
-            .optional()
-            .describe("File path to read (default: /game.html)"),
-        }),
-        func: async (input: { path?: string }) => {
-          const filePath = input.path || VirtualFileSystem.GAME_FILE_PATH;
-          const file = virtualFileSystem.readFile(filePath);
-
-          if (!file) {
-            return `Error: File not found: ${filePath}`;
-          }
-
-          return `Current content of ${filePath}:\n${file.content}`;
-        },
-      }),
-    );
-
     tools.push(
       new DynamicStructuredTool({
         name: "read_editor",
@@ -85,47 +171,6 @@ export class MCPClientManager {
       }),
     );
 
-    tools.push(
-      new DynamicStructuredTool({
-        name: "read_lines",
-        description:
-          "Read specific lines from a file - use AFTER search_file to examine found code sections in detail",
-        schema: z.object({
-          startLine: z
-            .number()
-            .min(1)
-            .describe("The starting line number (1-indexed)"),
-          endLine: z
-            .number()
-            .min(1)
-            .optional()
-            .describe(
-              "The ending line number (inclusive). If not provided, only the start line is returned",
-            ),
-          path: z
-            .string()
-            .optional()
-            .describe("File path to read from (default: /game.html)"),
-        }),
-        func: async (input: {
-          startLine: number;
-          endLine?: number;
-          path?: string;
-        }) => {
-          const result = virtualFileSystem.getLines(
-            input.startLine,
-            input.endLine,
-          );
-
-          if (result.error) {
-            return `Error: ${result.error}`;
-          }
-
-          return result.content;
-        },
-      }),
-    );
-
     tools.push(
       new DynamicStructuredTool({
         name: "read_editor_lines",
@@ -159,56 +204,6 @@ export class MCPClientManager {
       }),
     );
 
-    tools.push(
-      new DynamicStructuredTool({
-        name: "search_file",
-        description:
-          "Search for content in a file and get line numbers - use FIRST to locate specific functions, classes, or components before reading or editing",
-        schema: z.object({
-          query: z.string().describe("Text or regex pattern to search for"),
-          mode: z
-            .enum(["text", "regex"])
-            .optional()
-            .describe(
-              "Search mode: 'text' for literal text search, 'regex' for pattern matching (default: text)",
-            ),
-          path: z
-            .string()
-            .optional()
-            .describe("File path to search in (default: /game.html)"),
-        }),
-        func: async (input: {
-          query: string;
-          mode?: "text" | "regex";
-          path?: string;
-        }) => {
-          const mode = input.mode || "text";
-          const results = virtualFileSystem.searchContent(input.query, mode);
-
-          if (results.length === 0) {
-            return `No matches found for "${input.query}" in virtual file system`;
-          }
-
-          const totalMatches = results.length;
-          const displayMatches = results.slice(0, 10);
-
-          let output = `Found ${totalMatches} match${totalMatches > 1 ? "es" : ""} for "${input.query}":\n\n`;
-
-          displayMatches.forEach((match, index) => {
-            if (index > 0) output += "\n---\n\n";
-            output += `${match.path}:\n`;
-            output += match.context.join("\n");
-          });
-
-          if (totalMatches > 10) {
-            output += `\n\n(Showing first 10 of ${totalMatches} matches. Use more specific search terms to narrow results)`;
-          }
-
-          return output;
-        },
-      }),
-    );
-
     tools.push(
       new DynamicStructuredTool({
         name: "search_editor",
@@ -262,78 +257,6 @@ export class MCPClientManager {
       }),
     );
 
-    tools.push(
-      new DynamicStructuredTool({
-        name: "edit_file",
-        description:
-          "Replace specific text in a file - use for SMALL, targeted changes (max ~20 lines). For large changes, use multiple edit_file calls with plan_tasks",
-        schema: z.object({
-          oldText: z
-            .string()
-            .describe(
-              "The exact text to find and replace (keep small - max ~20 lines)",
-            ),
-          newText: z.string().describe("The text to replace it with"),
-          path: z
-            .string()
-            .optional()
-            .describe("File path to edit (default: /game.html)"),
-        }),
-        func: async (input: {
-          oldText: string;
-          newText: string;
-          path?: string;
-        }) => {
-          const result = virtualFileSystem.editContent(
-            input.oldText,
-            input.newText,
-          );
-
-          if (!result.success) {
-            return `Error: ${result.error}`;
-          }
-
-          const file = virtualFileSystem.getGameFile();
-          this.syncEditorContent(file.content);
-
-          consoleBuffer.clear();
-
-          const startTime = Date.now();
-          const maxWaitTime = 3000;
-
-          await new Promise((resolve) => setTimeout(resolve, 1000));
-
-          while (Date.now() - startTime < maxWaitTime) {
-            const gameState = consoleBuffer.getGameStateFromMessages();
-
-            if (gameState.isReady) {
-              const messages = consoleBuffer.getRecentMessages();
-              consoleBuffer.markAsRead();
-              return `Text replaced successfully. Game reloaded without errors.\nRecent console output:\n${messages
-                .map((m) => `[${m.type}] ${m.message}`)
-                .join("\n")}`;
-            }
-
-            if (gameState.hasError) {
-              const messages = consoleBuffer.getRecentMessages();
-              consoleBuffer.markAsRead();
-              return `Text replaced but game failed to start.\nError: ${gameState.lastError}\nFull console output:\n${messages
-                .map((m) => `[${m.type}] ${m.message}`)
-                .join("\n")}`;
-            }
-
-            await new Promise((resolve) => setTimeout(resolve, 100));
-          }
-
-          const messages = consoleBuffer.getRecentMessages();
-          consoleBuffer.markAsRead();
-          return `Text replaced. Game reload status uncertain (timeout).\nConsole output:\n${messages
-            .map((m) => `[${m.type}] ${m.message}`)
-            .join("\n")}`;
-        },
-      }),
-    );
-
     tools.push(
       new DynamicStructuredTool({
         name: "edit_editor",
@@ -348,112 +271,45 @@ export class MCPClientManager {
           newText: z.string().describe("The text to replace it with"),
         }),
         func: async (input: { oldText: string; newText: string }) => {
+          const currentContent = virtualFileSystem.getGameFile().content;
+          if (!currentContent.includes(input.oldText)) {
+            const shortPreview =
+              input.oldText.substring(0, 50) +
+              (input.oldText.length > 50 ? "..." : "");
+
+            return buildToolResponse({
+              success: false,
+              action: "Text replacement",
+              error: `Text not found: "${shortPreview}". This might be due to a previous edit already modifying this text. Please verify the current content with read_editor or search_editor.`,
+            });
+          }
+
           const result = virtualFileSystem.editContent(
             input.oldText,
             input.newText,
           );
 
           if (!result.success) {
-            return `Error: ${result.error}`;
+            return buildToolResponse({
+              success: false,
+              action: "Text replacement",
+              error: result.error,
+            });
           }
 
           const file = virtualFileSystem.getGameFile();
           this.syncEditorContent(file.content);
 
-          consoleBuffer.clear();
-
-          const startTime = Date.now();
-          const maxWaitTime = 3000;
-
-          await new Promise((resolve) => setTimeout(resolve, 1000));
-
-          while (Date.now() - startTime < maxWaitTime) {
-            const gameState = consoleBuffer.getGameStateFromMessages();
-
-            if (gameState.isReady) {
-              const messages = consoleBuffer.getRecentMessages();
-              consoleBuffer.markAsRead();
-              return `Text replaced successfully. Game reloaded without errors.\nRecent console output:\n${messages
-                .map((m) => `[${m.type}] ${m.message}`)
-                .join("\n")}`;
-            }
-
-            if (gameState.hasError) {
-              const messages = consoleBuffer.getRecentMessages();
-              consoleBuffer.markAsRead();
-              return `Text replaced but game failed to start.\nError: ${gameState.lastError}\nFull console output:\n${messages
-                .map((m) => `[${m.type}] ${m.message}`)
-                .join("\n")}`;
-            }
-
-            await new Promise((resolve) => setTimeout(resolve, 100));
-          }
-
-          const messages = consoleBuffer.getRecentMessages();
-          consoleBuffer.markAsRead();
-          return `Text replaced. Game reload status uncertain (timeout).\nConsole output:\n${messages
-            .map((m) => `[${m.type}] ${m.message}`)
-            .join("\n")}`;
-        },
-      }),
-    );
+          // Wait for game to reload and capture console
+          const { gameState, consoleOutput } =
+            await waitForGameState("edit_editor");
 
-    tools.push(
-      new DynamicStructuredTool({
-        name: "write_file",
-        description:
-          "Replace entire file content - use ONLY for creating new files or complete rewrites. For modifications, use edit_file with plan_tasks instead",
-        schema: z.object({
-          content: z.string().describe("The complete file content to write"),
-          path: z
-            .string()
-            .optional()
-            .describe("File path to write to (default: /game.html)"),
-        }),
-        func: async (input: { content: string; path?: string }) => {
-          const filePath = input.path || VirtualFileSystem.GAME_FILE_PATH;
-
-          if (filePath !== VirtualFileSystem.GAME_FILE_PATH) {
-            return `Error: Only ${VirtualFileSystem.GAME_FILE_PATH} can be written to`;
-          }
-
-          virtualFileSystem.updateGameContent(input.content);
-          this.syncEditorContent(input.content);
-
-          consoleBuffer.clear();
-
-          const startTime = Date.now();
-          const maxWaitTime = 3000;
-
-          await new Promise((resolve) => setTimeout(resolve, 1000));
-
-          while (Date.now() - startTime < maxWaitTime) {
-            const gameState = consoleBuffer.getGameStateFromMessages();
-
-            if (gameState.isReady) {
-              const messages = consoleBuffer.getRecentMessages();
-              consoleBuffer.markAsRead();
-              return `File updated successfully. Game reloaded without errors.\nRecent console output:\n${messages
-                .map((m) => `[${m.type}] ${m.message}`)
-                .join("\n")}`;
-            }
-
-            if (gameState.hasError) {
-              const messages = consoleBuffer.getRecentMessages();
-              consoleBuffer.markAsRead();
-              return `File updated but game failed to start.\nError: ${gameState.lastError}\nFull console output:\n${messages
-                .map((m) => `[${m.type}] ${m.message}`)
-                .join("\n")}`;
-            }
-
-            await new Promise((resolve) => setTimeout(resolve, 100));
-          }
-
-          const messages = consoleBuffer.getRecentMessages();
-          consoleBuffer.markAsRead();
-          return `File updated. Game reload status uncertain (timeout).\nConsole output:\n${messages
-            .map((m) => `[${m.type}] ${m.message}`)
-            .join("\n")}`;
+          return buildToolResponse({
+            success: true,
+            action: "Text replacement",
+            gameState,
+            consoleOutput,
+          });
         },
       }),
     );
@@ -472,40 +328,16 @@ export class MCPClientManager {
           virtualFileSystem.updateGameContent(input.content);
           this.syncEditorContent(input.content);
 
-          consoleBuffer.clear();
-
-          const startTime = Date.now();
-          const maxWaitTime = 3000;
-
-          await new Promise((resolve) => setTimeout(resolve, 1000));
-
-          while (Date.now() - startTime < maxWaitTime) {
-            const gameState = consoleBuffer.getGameStateFromMessages();
-
-            if (gameState.isReady) {
-              const messages = consoleBuffer.getRecentMessages();
-              consoleBuffer.markAsRead();
-              return `Code updated successfully. Game reloaded without errors.\nRecent console output:\n${messages
-                .map((m) => `[${m.type}] ${m.message}`)
-                .join("\n")}`;
-            }
-
-            if (gameState.hasError) {
-              const messages = consoleBuffer.getRecentMessages();
-              consoleBuffer.markAsRead();
-              return `Code updated but game failed to start.\nError: ${gameState.lastError}\nFull console output:\n${messages
-                .map((m) => `[${m.type}] ${m.message}`)
-                .join("\n")}`;
-            }
+          // Wait for game to reload and capture console
+          const { gameState, consoleOutput } =
+            await waitForGameState("write_editor");
 
-            await new Promise((resolve) => setTimeout(resolve, 100));
-          }
-
-          const messages = consoleBuffer.getRecentMessages();
-          consoleBuffer.markAsRead();
-          return `Code updated. Game reload status uncertain (timeout).\nConsole output:\n${messages
-            .map((m) => `[${m.type}] ${m.message}`)
-            .join("\n")}`;
+          return buildToolResponse({
+            success: true,
+            action: "Editor content update",
+            gameState,
+            consoleOutput,
+          });
         },
       }),
     );

src/lib/server/tools.ts

@@ -1,12 +1,20 @@
 import { DynamicTool } from "@langchain/core/tools";
 import { consoleBuffer } from "./console-buffer";
 
+interface ObserveConsoleOptions {
+  tailSize?: number;
+}
+
 export const observeConsoleTool = new DynamicTool({
   name: "observe_console",
   description:
     "Read console messages and game state - use to check for errors after making changes",
-  func: async () => {
-    const messages = consoleBuffer.getRecentMessages();
+  func: async (input: string | ObserveConsoleOptions = {}) => {
+    const options: ObserveConsoleOptions =
+      typeof input === "string" ? {} : input;
+    const tailSize = options.tailSize || 10;
+
+    const messages = consoleBuffer.getRecentMessages(undefined, tailSize);
     const allMessages = consoleBuffer.getAllMessages();
     const gameState = consoleBuffer.getGameStateFromMessages();
 
@@ -17,6 +25,7 @@ export const observeConsoleTool = new DynamicTool({
 Total messages in buffer: ${allMessages.length}
 Game State Analysis:
 - Loading: ${gameState.isLoading}
+- Reloading: ${gameState.isReloading}
 - Ready: ${gameState.isReady}
 - Has Error: ${gameState.hasError}
 ${gameState.lastError ? `- Last Error: ${gameState.lastError}` : ""}
@@ -32,7 +41,14 @@ ${allMessages
       return debugInfo;
     }
 
-    let output = `Console Messages (${messages.length} new):\n`;
+    const totalNew = consoleBuffer.getRecentMessages().length;
+    const displayedCount = messages.length;
+    const headerInfo =
+      totalNew > displayedCount
+        ? `Console Messages (showing last ${displayedCount} of ${totalNew} new):`
+        : `Console Messages (${displayedCount} new):`;
+
+    let output = `${headerInfo}\n`;
     output += messages
       .map(
         (msg) =>
@@ -42,6 +58,7 @@ ${allMessages
 
     output += "\n\nGame State:";
     output += `\n- Loading: ${gameState.isLoading}`;
+    output += `\n- Reloading: ${gameState.isReloading}`;
     output += `\n- Ready: ${gameState.isReady}`;
     output += `\n- Has Error: ${gameState.hasError}`;
     if (gameState.lastError) {
@@ -52,7 +69,3 @@ ${allMessages
     return output;
   },
 });
-
-import { taskTrackerTools } from "./task-tracker";
-
-export const tools = [observeConsoleTool, ...taskTrackerTools];

src/lib/services/content-manager.ts

@@ -10,6 +10,8 @@ export interface ContentState {
   version: number;
   isUISynced: boolean;
   isAgentSynced: boolean;
+  lastSource: "ui" | "agent" | "init";
+  isConflicted: boolean;
 }
 
 export interface ContentChange {
@@ -46,11 +48,15 @@ class ContentManager {
     version: 1,
     isUISynced: true,
     isAgentSynced: true,
+    lastSource: "init",
+    isConflicted: false,
   });
 
   private syncTimeout: number | null = null;
   private readonly DEBOUNCE_MS = 300;
   private isUpdating = false;
+  private agentEditInProgress = false;
+  private lastAgentVersion = 0;
 
   private constructor() {
     this.setupSyncSubscription();
@@ -84,7 +90,16 @@ class ContentManager {
    * Debounced for smooth typing experience
    */
   updateFromUI(content: string): void {
-    if (this.isUpdating) return;
+    if (this.isUpdating || this.agentEditInProgress) {
+      // Agent is editing, mark as conflicted
+      if (this.agentEditInProgress) {
+        this.contentStore.update((state) => ({
+          ...state,
+          isConflicted: true,
+        }));
+      }
+      return;
+    }
 
     this.updateContent(content, "ui");
     this.debouncedAgentSync();
@@ -92,14 +107,42 @@ class ContentManager {
 
   /**
    * Update content from agent (MCP tools)
-   * Always overwrites UI content - agent wins conflicts
+   * Now handles version conflicts more gracefully
    */
   updateFromAgent(content: string): void {
     if (this.isUpdating) return;
 
     this.isUpdating = true;
+    this.agentEditInProgress = true;
+
+    const currentState = get(this.contentStore);
+
+    // Check for version conflict
+    if (
+      currentState.version > this.lastAgentVersion &&
+      currentState.lastSource === "ui"
+    ) {
+      // UI has made changes since agent started editing
+      console.warn("Agent edit conflicted with UI changes - agent wins");
+      this.contentStore.update((state) => ({
+        ...state,
+        isConflicted: true,
+      }));
+    }
+
     this.updateContent(content, "agent");
+    this.lastAgentVersion = get(this.contentStore).version;
     this.clearSyncTimeout();
+
+    // Allow UI to resume editing after a short delay
+    setTimeout(() => {
+      this.agentEditInProgress = false;
+      this.contentStore.update((state) => ({
+        ...state,
+        isConflicted: false,
+      }));
+    }, 500);
+
     this.isUpdating = false;
   }
 
@@ -116,7 +159,11 @@ class ContentManager {
     this.contentStore.update((state) => ({
       ...state,
       isAgentSynced: true,
+      isConflicted: false,
     }));
+
+    // Initialize version tracking
+    this.lastAgentVersion = 1;
   }
 
   /**
@@ -133,6 +180,13 @@ class ContentManager {
     return get(this.contentStore);
   }
 
+  /**
+   * Check if agent is currently editing
+   */
+  isAgentEditing(): boolean {
+    return this.agentEditInProgress;
+  }
+
   /**
    * Force full sync (for reconnection scenarios)
    */
@@ -185,6 +239,8 @@ class ContentManager {
         version: state.version + 1,
         isUISynced: source === "ui" || source === "init",
         isAgentSynced: source === "agent" || source === "init",
+        lastSource: source,
+        isConflicted: false,
       };
     });
   }

src/lib/services/context.md

@@ -11,13 +11,13 @@ Single source of truth content management, game lifecycle, and virtual file oper
 ```
 services/
 ├── context.md              # This file
-├── content-manager.ts      # Single source of truth for editor content
+├── content-manager.ts      # Editor content with conflict detection
 ├── auth.ts                 # Hugging Face OAuth
 ├── websocket.ts            # WebSocket connection
 ├── message-handler.ts      # Message routing with segment processing
-├── game-engine.ts          # VibeGame lifecycle with DOM-based rendering
+├── game-engine.ts          # VibeGame lifecycle with reload events
 ├── html-document-parser.ts # HTML parsing using DOMParser
-├── virtual-fs.ts           # Virtual file system for editor content
+├── virtual-fs.ts           # Virtual file system with version tracking
 └── console-sync.ts         # Console interception
 ```
 

src/lib/services/game-engine.ts

@@ -2,6 +2,7 @@ import * as GAME from "vibegame";
 import type { System, Plugin, Component, BuilderOptions } from "vibegame";
 import { gameStore } from "../stores/game";
 import { uiStore } from "../stores/ui";
+import { consoleBuffer } from "../server/console-buffer";
 import {
   HTMLDocumentParser,
   type ParsedDocument,
@@ -24,6 +25,7 @@ export class GameEngine {
 
   async startFromDocument(htmlContent: string): Promise<void> {
     if (this.gameInstance) {
+      consoleBuffer.onGameReloadStart();
       this.stop();
       await new Promise((resolve) => setTimeout(resolve, 100));
     }
@@ -37,6 +39,7 @@ export class GameEngine {
       this.renderDocument(parsed);
       await this.initializeGame(parsed.scripts);
       console.info("✅ Game started!");
+      consoleBuffer.onGameReloadComplete();
     } catch (error: unknown) {
       const errorMsg = error instanceof Error ? error.message : String(error);
       uiStore.setError(errorMsg);
@@ -59,6 +62,7 @@ export class GameEngine {
 
   private async startFromParsed(parsed: ParsedDocument): Promise<void> {
     if (this.gameInstance) {
+      consoleBuffer.onGameReloadStart();
       this.stop();
       await new Promise((resolve) => setTimeout(resolve, 100));
     }
@@ -71,6 +75,7 @@ export class GameEngine {
       this.renderDocument(parsed);
       await this.initializeGame(parsed.scripts);
       console.info("✅ Game started!");
+      consoleBuffer.onGameReloadComplete();
     } catch (error: unknown) {
       const errorMsg = error instanceof Error ? error.message : String(error);
       uiStore.setError(errorMsg);

src/lib/services/message-handler.ts

@@ -8,6 +8,7 @@ export class MessageHandler {
   private currentSegments: Map<string, MessageSegment> = new Map();
   private completedSegments: MessageSegment[] = [];
   private latestTodoSegmentId: string | null = null;
+  private updateTimer: ReturnType<typeof setTimeout> | null = null;
 
   handleMessage(message: WebSocketMessage): void {
     switch (message.type) {
@@ -143,7 +144,15 @@ export class MessageHandler {
         content: segment.content + (token as string),
       };
       this.currentSegments.set(segmentId as string, updatedSegment);
-      this.updateMessageSegments();
+
+      // Throttle updates during streaming to avoid excessive re-renders
+      if (this.updateTimer) {
+        clearTimeout(this.updateTimer);
+      }
+      this.updateTimer = setTimeout(() => {
+        this.updateMessageSegments();
+        this.updateTimer = null;
+      }, 50);
     }
   }
 
@@ -158,6 +167,12 @@ export class MessageHandler {
     } = message.payload;
     if (!segmentId) return;
 
+    // Clear any pending update timer for immediate final update
+    if (this.updateTimer) {
+      clearTimeout(this.updateTimer);
+      this.updateTimer = null;
+    }
+
     const segment = this.currentSegments.get(segmentId as string);
     if (segment) {
       const completedSegment: MessageSegment = {
@@ -219,16 +234,19 @@ export class MessageHandler {
 
   private buildContentFromSegments(segments: MessageSegment[]): string {
     let content = "";
+    let lastWasText = false;
 
     for (const segment of segments) {
       if (segment.type === "text" && segment.content) {
+        // Add spacing between text segments if needed
+        if (lastWasText && content && !content.endsWith("\n")) {
+          content += " ";
+        }
         content += segment.content;
-      } else if (segment.type === "tool-invocation") {
-        // Tool invocations are now handled in the UI
-        continue;
-      } else if (segment.type === "tool-result") {
-        // Tool results are now handled in the UI
-        continue;
+        lastWasText = true;
+      } else {
+        // Tool segments are handled in UI, but reset text flag
+        lastWasText = false;
       }
     }
 

src/lib/services/segment-formatter.ts

@@ -144,9 +144,6 @@ export class SegmentFormatter {
         update_task: "✏️",
         view_tasks: "👀",
         observe_console: "📺",
-        read_file: "📖",
-        write_file: "✍️",
-        edit_file: "✏️",
       };
       return toolIcons[segment.toolName] || iconMap[segment.type] || "📄";
     }

src/lib/services/virtual-fs.ts

@@ -2,6 +2,7 @@ export interface VirtualFile {
   path: string;
   content: string;
   lastModified: Date;
+  version?: number;
 }
 
 /**
@@ -11,6 +12,12 @@ export interface VirtualFile {
 export class VirtualFileSystem {
   private static instance: VirtualFileSystem | null = null;
   private gameFile: VirtualFile;
+  private editHistory: Array<{
+    timestamp: Date;
+    oldText: string;
+    newText: string;
+    version: number;
+  }> = [];
 
   public static readonly GAME_FILE_PATH = "/game.html";
 
@@ -19,6 +26,7 @@ export class VirtualFileSystem {
       path: VirtualFileSystem.GAME_FILE_PATH,
       content: "",
       lastModified: new Date(),
+      version: 0,
     };
   }
 
@@ -43,10 +51,12 @@ export class VirtualFileSystem {
       );
     }
 
+    const newVersion = (this.gameFile.version || 0) + 1;
     this.gameFile = {
       path,
       content,
       lastModified: new Date(),
+      version: newVersion,
     };
   }
 
@@ -114,29 +124,199 @@ export class VirtualFileSystem {
     return results;
   }
 
+  /**
+   * Normalize text for flexible matching while preserving exact replacement
+   */
+  private normalizeForMatching(text: string): string {
+    // Normalize line endings and trim each line
+    return text
+      .split(/\r?\n/)
+      .map((line) => line.trimEnd())
+      .join("\n")
+      .trim();
+  }
+
+  /**
+   * Find all positions where normalized text matches
+   */
+  private findNormalizedMatches(
+    content: string,
+    searchText: string,
+  ): Array<{ start: number; end: number; text: string }> {
+    const matches: Array<{ start: number; end: number; text: string }> = [];
+    const normalizedSearch = this.normalizeForMatching(searchText);
+    const lines = content.split(/\r?\n/);
+
+    // Try to find matches line by line with flexible whitespace
+    for (let startLine = 0; startLine < lines.length; startLine++) {
+      // Build potential match starting from this line
+      for (
+        let endLine = startLine;
+        endLine < lines.length && endLine < startLine + 100;
+        endLine++
+      ) {
+        const candidateLines = lines.slice(startLine, endLine + 1);
+        const candidateText = candidateLines.join("\n");
+        const normalizedCandidate = this.normalizeForMatching(candidateText);
+
+        if (normalizedCandidate === normalizedSearch) {
+          // Found a match! Calculate actual positions in original content
+          let position = 0;
+          for (let i = 0; i < startLine; i++) {
+            position += lines[i].length + 1; // +1 for newline
+          }
+          const start = position;
+          const end = start + candidateText.length;
+
+          matches.push({
+            start,
+            end,
+            text: candidateText,
+          });
+          break; // Don't look for longer matches starting from same line
+        }
+      }
+    }
+
+    return matches;
+  }
+
+  /**
+   * Get context lines around a position in content
+   */
+  private getContextAtPosition(
+    content: string,
+    position: number,
+    contextLines: number = 3,
+  ): string {
+    const lines = content.split(/\r?\n/);
+    let currentPos = 0;
+    let targetLine = 0;
+
+    // Find which line contains the position
+    for (let i = 0; i < lines.length; i++) {
+      if (currentPos + lines[i].length >= position) {
+        targetLine = i;
+        break;
+      }
+      currentPos += lines[i].length + 1;
+    }
+
+    const startLine = Math.max(0, targetLine - contextLines);
+    const endLine = Math.min(lines.length - 1, targetLine + contextLines);
+
+    const contextParts: string[] = [];
+    for (let i = startLine; i <= endLine; i++) {
+      const lineNum = i + 1;
+      const prefix = i === targetLine ? ">>> " : "    ";
+      contextParts.push(`${prefix}${lineNum}: ${lines[i]}`);
+    }
+
+    return contextParts.join("\n");
+  }
+
   editContent(
     oldText: string,
     newText: string,
-  ): { success: boolean; error?: string } {
-    if (!this.gameFile.content.includes(oldText)) {
+  ): { success: boolean; error?: string; version?: number } {
+    const currentVersion = this.gameFile.version || 0;
+    if (this.gameFile.content.includes(oldText)) {
+      const occurrences = this.gameFile.content.split(oldText).length - 1;
+      if (occurrences === 1) {
+        const newContent = this.gameFile.content.replace(oldText, newText);
+        this.editHistory.push({
+          timestamp: new Date(),
+          oldText,
+          newText,
+          version: currentVersion,
+        });
+
+        if (this.editHistory.length > 20) {
+          this.editHistory = this.editHistory.slice(-20);
+        }
+
+        this.updateGameContent(newContent);
+        return { success: true, version: this.gameFile.version };
+      } else if (occurrences > 1) {
+        return {
+          success: false,
+          error: `Found ${occurrences} exact occurrences of the text. Be more specific.`,
+        };
+      }
+    }
+
+    const matches = this.findNormalizedMatches(this.gameFile.content, oldText);
+
+    if (matches.length === 0) {
+      // Show context to help understand why match failed
+      const shortPreview =
+        oldText.substring(0, 50) + (oldText.length > 50 ? "..." : "");
+      const searchResults = this.searchContent(
+        oldText.split(/\r?\n/)[0].trim(),
+        "text",
+      );
+
+      let errorMsg = `Could not find the specified text to replace: "${shortPreview}"`;
+      if (searchResults.length > 0) {
+        errorMsg += "\n\nDid you mean one of these locations?\n";
+        searchResults.slice(0, 3).forEach((result) => {
+          errorMsg += "\n" + result.context.join("\n") + "\n";
+        });
+      }
+
       return {
         success: false,
-        error: "Could not find the specified text to replace.",
+        error: errorMsg,
       };
     }
 
-    const occurrences = this.gameFile.content.split(oldText).length - 1;
-    if (occurrences > 1) {
+    if (matches.length > 1) {
+      let errorMsg = `Found ${matches.length} matches with normalized whitespace. Please be more specific.\n\nMatches found at:`;
+      matches.slice(0, 3).forEach((match, i) => {
+        errorMsg += `\n\nMatch ${i + 1}:\n`;
+        errorMsg += this.getContextAtPosition(
+          this.gameFile.content,
+          match.start,
+        );
+      });
+
       return {
         success: false,
-        error: `Found ${occurrences} occurrences of the text. Be more specific.`,
+        error: errorMsg,
       };
     }
 
-    const newContent = this.gameFile.content.replace(oldText, newText);
+    // Exactly one match found - replace it
+    const match = matches[0];
+    const newContent =
+      this.gameFile.content.substring(0, match.start) +
+      newText +
+      this.gameFile.content.substring(match.end);
+    this.editHistory.push({
+      timestamp: new Date(),
+      oldText,
+      newText,
+      version: currentVersion,
+    });
+
+    if (this.editHistory.length > 20) {
+      this.editHistory = this.editHistory.slice(-20);
+    }
+
     this.updateGameContent(newContent);
+    return { success: true, version: this.gameFile.version };
+  }
 
-    return { success: true };
+  /**
+   * Get recent edit history for debugging
+   */
+  getEditHistory(): Array<{
+    timestamp: Date;
+    oldText: string;
+    newText: string;
+    version: number;
+  }> {
+    return [...this.editHistory];
   }
 
   getLines(

src/lib/stores/context.md

@@ -16,7 +16,7 @@ stores/
 ├── console.ts     # Console messages with unique IDs
 ├── editor.ts      # Editor content and settings
 ├── chat-store.ts  # Chat messages and connection state
-└── ui.ts          # UI state (view mode, errors)
+└── ui.ts          # UI state (view modes including about, errors)
 ```
 
 ## Scope

src/lib/stores/ui.ts

@@ -1,9 +1,10 @@
 import { writable } from "svelte/store";
 
-export type ViewMode = "code" | "preview";
+export type ViewMode = "code" | "preview" | "about";
 
 export interface UIState {
   viewMode: ViewMode;
+  previousViewMode: "code" | "preview";
   error: string | null;
   isAnimating: boolean;
 }
@@ -11,6 +12,7 @@ export interface UIState {
 function createUIStore() {
   const { subscribe, update, set } = writable<UIState>({
     viewMode: "code",
+    previousViewMode: "code",
     error: null,
     isAnimating: false,
   });
@@ -18,7 +20,15 @@ function createUIStore() {
   return {
     subscribe,
     setViewMode: (viewMode: ViewMode) =>
-      update((state) => ({ ...state, viewMode })),
+      update((state) => {
+        const previousViewMode =
+          state.viewMode === "about"
+            ? state.previousViewMode
+            : state.viewMode === "code" || state.viewMode === "preview"
+              ? state.viewMode
+              : state.previousViewMode;
+        return { ...state, viewMode, previousViewMode };
+      }),
     setError: (error: string | null) =>
       update((state) => ({ ...state, error })),
     setAnimating: (isAnimating: boolean) =>
@@ -27,10 +37,26 @@ function createUIStore() {
       update((state) => ({
         ...state,
         viewMode: state.viewMode === "code" ? "preview" : "code",
+        previousViewMode: state.viewMode === "code" ? "preview" : "code",
+      })),
+    showAbout: () =>
+      update((state) => ({
+        ...state,
+        previousViewMode:
+          state.viewMode === "code" || state.viewMode === "preview"
+            ? state.viewMode
+            : state.previousViewMode,
+        viewMode: "about",
+      })),
+    hideAbout: () =>
+      update((state) => ({
+        ...state,
+        viewMode: state.previousViewMode,
       })),
     reset: () =>
       set({
         viewMode: "code",
+        previousViewMode: "code",
         error: null,
         isAnimating: false,
       }),

src/lib/utils/context.md

@@ -0,0 +1,32 @@
+# Utils Context
+
+Shared utility functions and helpers
+
+## Purpose
+
+- Reusable utilities for the application
+- Cross-cutting concerns like parsing and validation
+
+## Layout
+
+```
+utils/
+├── context.md                   # This file
+├── tool-call-parser.ts          # Tool call extraction wrapper
+└── tool-parser-htmlparser2.ts  # Regex-based parser for tool tags
+```
+
+## Scope
+
+- In-scope: Stateless utilities, parsers, formatters
+- Out-of-scope: Business logic, UI components, state management
+
+## Entrypoints
+
+- `tool-call-parser.ts` - StreamingToolCallParser class and utility functions
+- `tool-parser-htmlparser2.ts` - ToolParser class for extracting tool tags
+
+## Dependencies
+
+- No external dependencies
+- Used by chat components and server-side agent

src/lib/utils/tool-call-parser.ts

@@ -0,0 +1,88 @@
+import {
+  StreamingToolParser as HTMLStreamingToolParser,
+  extractToolCalls as htmlExtractToolCalls,
+  filterToolCalls as htmlFilterToolCalls,
+} from "./tool-parser-htmlparser2";
+
+export interface ToolCallMatch {
+  toolName: string;
+  startIndex: number;
+  endIndex?: number;
+  args?: string;
+  complete: boolean;
+}
+
+export class StreamingToolCallParser {
+  private htmlParser: HTMLStreamingToolParser;
+  private buffer = "";
+
+  constructor() {
+    this.htmlParser = new HTMLStreamingToolParser();
+  }
+
+  reset(): void {
+    this.buffer = "";
+    this.htmlParser.reset();
+  }
+
+  /**
+   * Process incoming text and detect tool call boundaries
+   * Returns the safe text (without tool calls) and any detected tool calls
+   */
+  process(text: string): {
+    safeText: string;
+    toolCalls: ToolCallMatch[];
+    pendingToolCall: boolean;
+  } {
+    this.buffer += text;
+    const result = this.htmlParser.write(text);
+
+    return {
+      safeText: result.safeText,
+      toolCalls: result.toolCalls.map((tc) => ({
+        toolName: tc.name,
+        startIndex: tc.startIndex || 0,
+        endIndex: tc.endIndex,
+        args: tc.rawArgs,
+        complete: tc.complete,
+      })),
+      pendingToolCall: result.pendingToolCall,
+    };
+  }
+
+  /**
+   * Get any buffered content that hasn't been processed yet
+   */
+  getBuffer(): string {
+    return this.buffer;
+  }
+
+  /**
+   * Check if parser is currently inside a tool call
+   */
+  isInToolCall(): boolean {
+    const result = this.htmlParser.write("");
+    return result.pendingToolCall;
+  }
+}
+
+/**
+ * Static utility to filter tool calls from text (non-streaming)
+ */
+export function filterToolCalls(text: string): string {
+  return htmlFilterToolCalls(text);
+}
+
+/**
+ * Static utility to extract tool calls from text
+ */
+export function extractToolCalls(
+  text: string,
+): Array<{ name: string; args: Record<string, unknown> }> {
+  const htmlToolCalls = htmlExtractToolCalls(text);
+
+  return htmlToolCalls.map((tc) => ({
+    name: tc.name,
+    args: tc.args,
+  }));
+}

src/lib/utils/tool-parser-htmlparser2.ts

@@ -0,0 +1,205 @@
+export interface ToolCall {
+  name: string;
+  args: Record<string, unknown>;
+  rawArgs: string;
+  startIndex?: number;
+  endIndex?: number;
+  complete: boolean;
+}
+
+export interface ParseResult {
+  safeText: string;
+  toolCalls: ToolCall[];
+  pendingToolCall: boolean;
+  errors: string[];
+}
+
+export class ToolParser {
+  private buffer = "";
+  private textBuffer = "";
+  private lastReturnedTextLength = 0;
+  private toolCalls: ToolCall[] = [];
+  private errors: string[];
+  private processedUpTo = 0;
+
+  constructor() {
+    this.errors = [];
+  }
+
+  reset(): void {
+    this.buffer = "";
+    this.textBuffer = "";
+    this.lastReturnedTextLength = 0;
+    this.toolCalls = [];
+    this.errors = [];
+    this.processedUpTo = 0;
+  }
+
+  process(text: string): ParseResult {
+    this.buffer += text;
+
+    // Use regex to find complete tool tags
+    // This avoids htmlparser2 interpreting HTML inside JSON strings
+    const toolRegex = /<tool\s+name="([^"]+)">([^]*?)<\/tool>/g;
+    toolRegex.lastIndex = 0;
+
+    let match;
+    let lastMatchEnd = this.processedUpTo;
+
+    while ((match = toolRegex.exec(this.buffer)) !== null) {
+      // Only process new matches
+      if (match.index < this.processedUpTo) continue;
+
+      // Add text before the tool tag to textBuffer
+      if (match.index > lastMatchEnd) {
+        this.textBuffer += this.buffer.slice(lastMatchEnd, match.index);
+      }
+
+      const toolName = match[1];
+      const rawContent = match[2];
+
+      // Parse the JSON content
+      let args: Record<string, unknown> = {};
+      try {
+        const trimmedContent = rawContent.trim();
+        if (trimmedContent) {
+          args = JSON.parse(trimmedContent);
+        }
+      } catch (e) {
+        this.errors.push(`Failed to parse tool args for ${toolName}: ${e}`);
+        args = {};
+      }
+
+      this.toolCalls.push({
+        name: toolName,
+        args,
+        rawArgs: rawContent,
+        startIndex: match.index,
+        endIndex: match.index + match[0].length,
+        complete: true,
+      });
+
+      lastMatchEnd = match.index + match[0].length;
+      this.processedUpTo = lastMatchEnd;
+    }
+
+    // Check for incomplete tool tag at the end
+    const remainingText = this.buffer.slice(this.processedUpTo);
+    const incompleteToolRegex = /<tool\s+name="[^"]*"?\s*>?[^]*$/;
+    const incompleteMatch = incompleteToolRegex.test(remainingText);
+
+    if (!incompleteMatch && remainingText) {
+      // No pending tool tag, add remaining text
+      this.textBuffer += remainingText;
+      this.processedUpTo = this.buffer.length;
+    }
+
+    // Return only new text since last call
+    const newText = this.textBuffer.slice(this.lastReturnedTextLength);
+    this.lastReturnedTextLength = this.textBuffer.length;
+
+    return {
+      safeText: newText,
+      toolCalls: [...this.toolCalls],
+      pendingToolCall: incompleteMatch,
+      errors: [...this.errors],
+    };
+  }
+
+  finalize(): ParseResult {
+    // Process any remaining text
+    const remainingText = this.buffer.slice(this.processedUpTo);
+    if (remainingText && !/<tool\s/.test(remainingText)) {
+      this.textBuffer += remainingText;
+    }
+
+    // Return any remaining text
+    const newText = this.textBuffer.slice(this.lastReturnedTextLength);
+    this.lastReturnedTextLength = this.textBuffer.length;
+
+    return {
+      safeText: newText,
+      toolCalls: [...this.toolCalls],
+      pendingToolCall: false,
+      errors: [...this.errors],
+    };
+  }
+
+  getAllText(): string {
+    return this.textBuffer;
+  }
+}
+
+export class StreamingToolParser {
+  private parser: ToolParser;
+  private lastToolCount = 0;
+  private safeTextCallback?: (text: string) => void;
+  private toolCallCallback?: (tool: ToolCall) => void;
+  private errorCallback?: (error: string) => void;
+
+  constructor(options?: {
+    onSafeText?: (text: string) => void;
+    onToolCall?: (tool: ToolCall) => void;
+    onError?: (error: string) => void;
+  }) {
+    this.parser = new ToolParser();
+    this.safeTextCallback = options?.onSafeText;
+    this.toolCallCallback = options?.onToolCall;
+    this.errorCallback = options?.onError;
+  }
+
+  write(chunk: string): ParseResult {
+    const result = this.parser.process(chunk);
+
+    // Handle callbacks
+    if (result.safeText && this.safeTextCallback) {
+      this.safeTextCallback(result.safeText);
+    }
+
+    if (result.toolCalls.length > this.lastToolCount) {
+      const newTools = result.toolCalls.slice(this.lastToolCount);
+      for (const tool of newTools) {
+        if (tool.complete && this.toolCallCallback) {
+          this.toolCallCallback(tool);
+        }
+      }
+      this.lastToolCount = result.toolCalls.length;
+    }
+
+    if (result.errors.length > 0 && this.errorCallback) {
+      for (const error of result.errors) {
+        this.errorCallback(error);
+      }
+    }
+
+    return result;
+  }
+
+  end(): ParseResult {
+    return this.parser.finalize();
+  }
+
+  reset(): void {
+    this.parser.reset();
+    this.lastToolCount = 0;
+  }
+}
+
+export function extractToolCalls(text: string): ToolCall[] {
+  const parser = new ToolParser();
+  parser.process(text);
+  const result = parser.finalize();
+
+  if (result.errors.length > 0) {
+    console.warn("Tool parsing errors:", result.errors);
+  }
+
+  return result.toolCalls.filter((tc) => tc.complete);
+}
+
+export function filterToolCalls(text: string): string {
+  const parser = new ToolParser();
+  parser.process(text);
+  parser.finalize();
+  return parser.getAllText();
+}

tests/api.test.ts

@@ -1,229 +0,0 @@
-import { describe, test, expect, beforeEach, mock } from "bun:test";
-import { wsManager } from "../src/lib/server/api";
-import type { WebSocket } from "ws";
-import type { IncomingMessage } from "http";
-
-describe("WebSocket API", () => {
-  let manager: typeof wsManager;
-  let mockWs: Partial<WebSocket>;
-  let mockRequest: Partial<IncomingMessage>;
-
-  beforeEach(() => {
-    manager = wsManager;
-
-    mockWs = {
-      readyState: 1,
-      OPEN: 1,
-      send: mock((_data: string) => {}),
-      on: mock((_event: string, _handler: (...args: unknown[]) => void) => {}),
-      close: mock(() => {}),
-    };
-
-    mockRequest = {
-      headers: {},
-      url: "/",
-    };
-  });
-
-  test("handles new connection", () => {
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    expect(mockWs.send).toHaveBeenCalled();
-    const sentData = (mockWs.send as ReturnType<typeof mock>).mock
-      .calls[0][0] as string;
-    const message = JSON.parse(sentData);
-
-    expect(message.type).toBe("status");
-    expect(message.payload.connected).toBe(true);
-  });
-
-  test("registers event handlers", () => {
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    expect(mockWs.on).toHaveBeenCalledWith("message", expect.any(Function));
-    expect(mockWs.on).toHaveBeenCalledWith("close", expect.any(Function));
-    expect(mockWs.on).toHaveBeenCalledWith("error", expect.any(Function));
-  });
-
-  test("handles authentication message", async () => {
-    const handlers: Record<string, (...args: unknown[]) => void> = {};
-    mockWs.on = mock((event: string, handler: (...args: unknown[]) => void) => {
-      handlers[event] = handler;
-    });
-
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    const authMessage = JSON.stringify({
-      type: "auth",
-      payload: { token: "test-token" },
-      timestamp: Date.now(),
-    });
-
-    await handlers["message"](authMessage);
-
-    expect(mockWs.send).toHaveBeenCalled();
-  });
-
-  test("handles editor sync message", async () => {
-    const handlers: Record<string, (...args: unknown[]) => void> = {};
-    mockWs.on = mock((event: string, handler: (...args: unknown[]) => void) => {
-      handlers[event] = handler;
-    });
-
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    const editorMessage = JSON.stringify({
-      type: "editor_sync",
-      payload: { content: "<div>New content</div>" },
-      timestamp: Date.now(),
-    });
-
-    await handlers["message"](editorMessage);
-
-    expect(mockWs.send).toHaveBeenCalled();
-  });
-
-  test("handles console sync message", async () => {
-    const handlers: Record<string, (...args: unknown[]) => void> = {};
-    mockWs.on = mock((event: string, handler: (...args: unknown[]) => void) => {
-      handlers[event] = handler;
-    });
-
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    const consoleMessage = JSON.stringify({
-      type: "console_sync",
-      payload: {
-        id: "1",
-        type: "log",
-        message: "Test log",
-      },
-      timestamp: Date.now(),
-    });
-
-    await handlers["message"](consoleMessage);
-  });
-
-  test("handles abort message", async () => {
-    const handlers: Record<string, (...args: unknown[]) => void> = {};
-    mockWs.on = mock((event: string, handler: (...args: unknown[]) => void) => {
-      handlers[event] = handler;
-    });
-
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    const abortMessage = JSON.stringify({
-      type: "abort",
-      payload: {},
-      timestamp: Date.now(),
-    });
-
-    await handlers["message"](abortMessage);
-
-    expect(mockWs.send).toHaveBeenCalled();
-  });
-
-  test("handles clear conversation message", async () => {
-    const handlers: Record<string, (...args: unknown[]) => void> = {};
-    mockWs.on = mock((event: string, handler: (...args: unknown[]) => void) => {
-      handlers[event] = handler;
-    });
-
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    const clearMessage = JSON.stringify({
-      type: "clear_conversation",
-      payload: {},
-      timestamp: Date.now(),
-    });
-
-    await handlers["message"](clearMessage);
-
-    expect(mockWs.send).toHaveBeenCalled();
-  });
-
-  test("handles malformed message", async () => {
-    const handlers: Record<string, (...args: unknown[]) => void> = {};
-    mockWs.on = mock((event: string, handler: (...args: unknown[]) => void) => {
-      handlers[event] = handler;
-    });
-
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    await handlers["message"]("invalid json");
-
-    expect(mockWs.send).toHaveBeenCalled();
-    const sentData = (mockWs.send as ReturnType<typeof mock>).mock
-      .calls[1][0] as string;
-    const message = JSON.parse(sentData);
-    expect(message.type).toBe("error");
-  });
-
-  test("cleans up on close", () => {
-    const handlers: Record<string, (...args: unknown[]) => void> = {};
-    mockWs.on = mock((event: string, handler: (...args: unknown[]) => void) => {
-      handlers[event] = handler;
-    });
-
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    handlers["close"]();
-  });
-
-  test("handles connection error", () => {
-    const handlers: Record<string, (...args: unknown[]) => void> = {};
-    mockWs.on = mock((event: string, handler: (...args: unknown[]) => void) => {
-      handlers[event] = handler;
-    });
-
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    const error = new Error("Connection failed");
-    handlers["error"](error);
-  });
-
-  test("sends status updates", () => {
-    manager.handleConnection(
-      mockWs as WebSocket,
-      mockRequest as IncomingMessage,
-    );
-
-    manager["sendMessage"](mockWs as WebSocket, {
-      type: "status",
-      payload: { processing: true },
-      timestamp: Date.now(),
-    });
-
-    expect(mockWs.send).toHaveBeenCalled();
-  });
-});

tests/console-buffer.test.ts

@@ -1,162 +0,0 @@
-import { describe, test, expect, beforeEach } from "bun:test";
-import { ConsoleBuffer } from "../src/lib/server/console-buffer";
-
-describe("Console Buffer", () => {
-  let buffer: ConsoleBuffer;
-
-  beforeEach(() => {
-    buffer = ConsoleBuffer.getInstance();
-    buffer.clear();
-  });
-
-  test("adds and retrieves messages", () => {
-    buffer.addMessage({
-      id: "1",
-      type: "log",
-      message: "Test message",
-      timestamp: Date.now(),
-    });
-
-    const messages = buffer.getAllMessages();
-    expect(messages).toHaveLength(1);
-    expect(messages[0].message).toBe("Test message");
-  });
-
-  test("retrieves recent messages since timestamp", () => {
-    const now = Date.now();
-
-    buffer.addMessage({
-      id: "1",
-      type: "log",
-      message: "Old message",
-      timestamp: now - 1000,
-    });
-
-    buffer.addMessage({
-      id: "2",
-      type: "log",
-      message: "New message",
-      timestamp: now + 1000,
-    });
-
-    const recent = buffer.getRecentMessages(now);
-    expect(recent).toHaveLength(1);
-    expect(recent[0].message).toBe("New message");
-  });
-
-  test("marks messages as read", () => {
-    buffer.addMessage({
-      id: "1",
-      type: "log",
-      message: "Message 1",
-      timestamp: Date.now(),
-    });
-
-    buffer.markAsRead();
-
-    buffer.addMessage({
-      id: "2",
-      type: "log",
-      message: "Message 2",
-      timestamp: Date.now() + 100,
-    });
-
-    const recent = buffer.getRecentMessages();
-    expect(recent).toHaveLength(1);
-    expect(recent[0].message).toBe("Message 2");
-  });
-
-  test("limits buffer to max messages", () => {
-    for (let i = 0; i < 150; i++) {
-      buffer.addMessage({
-        id: `msg-${i}`,
-        type: "log",
-        message: `Message ${i}`,
-        timestamp: Date.now() + i,
-      });
-    }
-
-    const messages = buffer.getAllMessages();
-    expect(messages.length).toBeLessThanOrEqual(100);
-    expect(messages[messages.length - 1].message).toContain("149");
-  });
-
-  test("clears all messages", () => {
-    buffer.addMessage({
-      id: "1",
-      type: "log",
-      message: "Test",
-      timestamp: Date.now(),
-    });
-
-    buffer.clear();
-    const messages = buffer.getAllMessages();
-    expect(messages).toHaveLength(0);
-  });
-
-  test("detects loading game state", () => {
-    buffer.addMessage({
-      id: "1",
-      type: "log",
-      message: "🎮 Starting game",
-      timestamp: Date.now(),
-    });
-
-    const state = buffer.getGameStateFromMessages();
-    expect(state.isLoading).toBe(true);
-    expect(state.hasError).toBe(false);
-    expect(state.isReady).toBe(false);
-  });
-
-  test("detects ready game state", () => {
-    buffer.addMessage({
-      id: "1",
-      type: "log",
-      message: "✅ Game started",
-      timestamp: Date.now(),
-    });
-
-    const state = buffer.getGameStateFromMessages();
-    expect(state.isLoading).toBe(false);
-    expect(state.hasError).toBe(false);
-    expect(state.isReady).toBe(true);
-  });
-
-  test("detects error game state", () => {
-    buffer.addMessage({
-      id: "1",
-      type: "error",
-      message: "❌ Error: Failed to load",
-      timestamp: Date.now(),
-    });
-
-    const state = buffer.getGameStateFromMessages();
-    expect(state.hasError).toBe(true);
-    expect(state.lastError).toContain("Failed to load");
-    expect(state.isReady).toBe(false);
-  });
-
-  test("handles different message types", () => {
-    const types = ["log", "warn", "error", "info"] as const;
-
-    types.forEach((type, index) => {
-      buffer.addMessage({
-        id: `${index}`,
-        type,
-        message: `${type} message`,
-        timestamp: Date.now() + index,
-      });
-    });
-
-    const messages = buffer.getAllMessages();
-    expect(messages).toHaveLength(4);
-    expect(messages.map((m) => m.type)).toEqual(types);
-  });
-
-  test("singleton instance", () => {
-    const instance1 = ConsoleBuffer.getInstance();
-    const instance2 = ConsoleBuffer.getInstance();
-
-    expect(instance1).toBe(instance2);
-  });
-});

tests/langgraph-agent.test.ts

@@ -1,133 +0,0 @@
-import { describe, test, expect, beforeEach, mock } from "bun:test";
-import { LangGraphAgent } from "../src/lib/server/langgraph-agent";
-import { HumanMessage, AIMessage } from "@langchain/core/messages";
-import type { WebSocket } from "ws";
-
-describe("LangGraph Agent", () => {
-  let agent: LangGraphAgent;
-
-  beforeEach(() => {
-    agent = new LangGraphAgent();
-  });
-
-  test("initializes with HF token", async () => {
-    const mockWs = {
-      readyState: 1,
-      OPEN: 1,
-      send: mock(() => {}),
-    } as unknown as WebSocket;
-
-    await agent.initialize("test-token", mockWs);
-    expect(agent).toBeDefined();
-  });
-
-  test("throws error without HF token", async () => {
-    expect(async () => {
-      await agent.initialize("");
-    }).toThrow();
-  });
-
-  test("processes simple message", async () => {
-    await agent.initialize("test-token");
-
-    const messages = [new HumanMessage("Hello")];
-
-    const mockWriter = {
-      writes: [] as Array<{ type: string; content?: string }>,
-      write: function (data: { type: string; content?: string }) {
-        this.writes.push(data);
-      },
-    };
-
-    const config = {
-      writer: mockWriter.write.bind(mockWriter),
-      metadata: {
-        messageId: "test-123",
-      },
-    };
-
-    try {
-      const result = await agent.processMessage(messages, config);
-      expect(result).toBeDefined();
-      expect(result.messages).toBeDefined();
-      expect(result.messages.length).toBeGreaterThan(0);
-    } catch (error) {
-      expect(error).toBeDefined();
-    }
-  });
-
-  test("handles abort signal", async () => {
-    await agent.initialize("test-token");
-
-    const controller = new AbortController();
-    const messages = [new HumanMessage("Test")];
-
-    const config = {
-      metadata: {
-        abortSignal: controller.signal,
-        messageId: "test-abort",
-      },
-    };
-
-    setTimeout(() => controller.abort(), 10);
-
-    try {
-      await agent.processMessage(messages, config);
-    } catch (error) {
-      expect(["AbortError", "TypeError"]).toContain((error as Error).name);
-    }
-  });
-
-  test("clears conversation", () => {
-    if (typeof agent.clearConversation === "function") {
-      agent.clearConversation();
-    }
-    expect(agent).toBeDefined();
-  });
-
-  test("formats messages with system prompt", async () => {
-    await agent.initialize("test-token");
-
-    const messages = [
-      new HumanMessage("Create a game"),
-      new AIMessage("I'll help you create a game"),
-    ];
-
-    const formatted = agent["formatMessages"](messages, "System prompt");
-    expect(formatted).toBeDefined();
-    expect(formatted.length).toBeGreaterThan(0);
-    expect(formatted[0].role).toBe("system");
-  });
-
-  test("builds system prompt with documentation", async () => {
-    await agent.initialize("test-token");
-
-    const prompt = agent["buildSystemPrompt"]();
-    expect(prompt).toBeDefined();
-    expect(prompt).toContain("VibeGame");
-    expect(prompt).toContain("WebGL");
-  });
-
-  test("handles multiple messages in conversation", async () => {
-    await agent.initialize("test-token");
-
-    const messages = [
-      new HumanMessage("First message"),
-      new AIMessage("First response"),
-      new HumanMessage("Second message"),
-    ];
-
-    const config = {
-      metadata: {
-        messageId: "test-multi",
-      },
-    };
-
-    try {
-      const result = await agent.processMessage(messages, config);
-      expect(result.messages).toBeDefined();
-    } catch (error) {
-      expect(error).toBeDefined();
-    }
-  });
-});