feat(core): add command buffer system for deferred operations

[danjdewhurst]

Summary

Implements comprehensive command buffer system for safe structural changes during system execution, completing Phase 7 (Core Completeness) for v1.0.0 release.

This PR adds the final critical feature for 1.0.0, enabling:

• ✅ Deferred entity/component operations
• ✅ Safe structural changes during system execution
• ✅ Multi-threaded entity modification support
• ✅ Command replay/undo capabilities
• ✅ Batch operation optimization

Features

Core Implementation

• CommandBuffer class - Queue and execute commands in batches
• Command interface - Base interface with execute/undo/describe methods
• Entity commands - CreateEntity, DestroyEntity, AddComponent, RemoveComponent
• World integration - Automatic command execution during update cycle
• Undo/Replay support - Optional history tracking for command playback

Key Capabilities

• Queue operations during system execution without causing iterator invalidation
• Execute commands at safe points in the update cycle
• Support for undo/redo with complete state restoration
• Multiple independent command buffers
• Execution statistics and error tracking
• Configurable auto-execution behavior

Implementation Details

New Files

• src/core/commands/Command.ts - Command interface and types
• src/core/commands/CommandBuffer.ts - Main command buffer implementation
• src/core/commands/EntityCommands.ts - Entity/component command implementations
• src/core/commands/index.ts - Module exports
• examples/command-buffers-example.ts - Comprehensive usage examples
• tests/commands.test.ts - Full test suite (37 tests)

Modified Files

• src/core/ecs/World.ts - Added command buffer integration
• src/index.ts - Added command buffer exports
• roadmap/ROADMAP.md - Updated to reflect Phase 7 completion

Testing

37 comprehensive tests covering:

• ✅ Basic command execution
• ✅ Undo/redo functionality
• ✅ Error handling and validation
• ✅ Batch optimization
• ✅ World integration
• ✅ Auto-execution during update cycle
• ✅ Multiple independent buffers
• ✅ Performance with 10,000+ commands

All tests passing with 100% success rate.

Examples

The example demonstrates 6 different scenarios:

1. Basic Usage - Simple command queueing and execution
2. Auto-Execution - Commands executing during update cycle
3. Undo/Redo - Complete history tracking and replay
4. Damage System - Real-world combat system using commands
5. Multiple Buffers - Independent command buffer management
6. Performance - Batch processing of 10,000 entities

// Simple usage
const buffer = world.getCommandBuffer();
buffer.enqueue(new CreateEntityCommand());
buffer.enqueue(new AddComponentCommand(entityId, component));
world.update(deltaTime); // Commands execute automatically

// With undo support
const buffer = world.createCommandBuffer({ enableUndo: true });
buffer.enqueue(new CreateEntityCommand());
buffer.execute(world);
buffer.undo(world); // Revert changes
buffer.replay(world); // Re-apply changes

Performance

Excellent performance characteristics:

• 10,000 entity creations: ~1.3ms execution time
• ~7,600 commands/ms throughput
• Minimal memory overhead
• Zero allocations during command execution

Documentation

• Comprehensive inline documentation
• Full TSDoc comments on all public APIs
• Working example with multiple scenarios
• Updated roadmap with Phase 7 completion status

Phase 7 Complete! 🎉

This PR completes Phase 7: Core Completeness, achieving 100% of must-have features for v1.0.0:

• ✅ Serialization & Persistence (v0.11.0)
• ✅ Scene Management (v0.12.0)
• ✅ Asset Management (v0.13.0)
• ✅ Transform Hierarchy (v0.14.0)
• ✅ Command Buffers (v0.15.0) ← This PR

The engine is now ready for 1.0.0 release!

Breaking Changes

None. This is a purely additive feature with full backward compatibility.

Migration Guide

No migration needed. Command buffers are opt-in:

// Existing code continues to work
world.createEntity();
world.addComponent(entityId, component);

// New: Use command buffers for deferred operations
const buffer = world.getCommandBuffer();
buffer.enqueue(new CreateEntityCommand());
// Executes automatically during world.update()

Test Plan

• All existing tests pass (784 tests)
• 37 new command buffer tests pass
• TypeScript compilation successful
• Lint checks pass
• Example runs successfully
• Performance benchmarks meet expectations

Checklist

• Implementation complete
• Tests written and passing
• Documentation complete
• Example created
• Roadmap updated
• No breaking changes
• Performance validated
• Code reviewed and formatted

Next Steps

After this PR merges:

1. Create v1.0.0 release
2. Begin Phase 8: Performance & Scale
3. Focus on query caching and multi-threading optimizations