feat(core): add comprehensive transform hierarchy system

[danjdewhurst]

Summary

Implements Phase 7 feature #4: Transform Hierarchy system for v0.14.0.

This PR adds a complete transform hierarchy system that enables parent-child entity relationships with full spatial transformations.

Features Implemented

Core Transform System

• TransformComponent: Position, rotation (quaternion), scale in local and world space
• TransformHierarchy: Manages parent-child relationships and scene graph operations
• TransformMath: Matrix/quaternion math utilities for spatial transformations
• TransformSystem: Automatic world transform propagation each frame

Hierarchy Operations

• ✅ Parent-child relationship management
• ✅ Cycle prevention and validation
• ✅ Multi-level hierarchy support
• ✅ Depth-first and breadth-first traversal
• ✅ Ancestor/descendant queries
• ✅ Sibling queries
• ✅ Dynamic reparenting
• ✅ Root entity tracking

Transform Math

• ✅ 4x4 matrix multiplication
• ✅ Quaternion operations
• ✅ Vector operations (add, subtract, scale, normalize, dot, cross)
• ✅ Transform propagation through hierarchy
• ✅ Euler angle conversions

Quality Assurance

Testing

• ✅ 38 comprehensive unit tests
• ✅ 100% coverage of hierarchy operations
• ✅ Edge case testing (cycles, invalid operations)
• ✅ Transform math validation

Documentation

• ✅ Comprehensive example with 7 practical scenarios
• ✅ Full API documentation in code
• ✅ Updated roadmap with implementation details

Code Quality

• ✅ Type-safe API with proper error handling
• ✅ Follows ECS architecture principles
• ✅ Performance-optimized (O(1) lookups, efficient traversal)
• ✅ Biome linting compliant

Example Usage

import { World, TransformSystem, createTransformComponent, createVector3 } from '@danjdewhurst/ecs-ts';

const world = new World();
const transformSystem = new TransformSystem(world);
const hierarchy = transformSystem.getHierarchy();

world.addSystem(transformSystem);

// Create parent-child relationship
const ship = world.createEntity();
const turret = world.createEntity();

world.addComponent(ship, createTransformComponent(createVector3(100, 50, 0)));
world.addComponent(turret, createTransformComponent(createVector3(0, 10, 0)));

hierarchy.addRoot(ship);
hierarchy.setParent(turret, ship);

// Update transforms - turret world position automatically calculated
world.update(0.016);

Files Changed

• src/core/transform/ - Complete transform hierarchy module
  • TransformComponent.ts - Transform data structures
  • TransformHierarchy.ts - Hierarchy management
  • TransformMath.ts - Math utilities
  • TransformSystem.ts - ECS system integration
  • index.ts - Public API exports
• examples/transform-hierarchy-example.ts - Comprehensive usage example
• tests/transform.test.ts - Full test suite
• src/index.ts - Added transform exports
• roadmap/ROADMAP.md - Updated to reflect completion

Breaking Changes

None. This is a new feature that doesn't modify existing APIs.

Roadmap Progress

• Phase 7 Progress: 80% → complete (4/5 features)
• Next up: Command Buffers (Phase 7, feature docs: add philosophy references to README and CLAUDE.md #5)

Test Plan

• All 38 new tests passing
• All existing tests passing (747 total tests)
• Example runs successfully
• TypeScript compilation clean
• Biome linting passed

Checklist

• Feature implemented completely
• Tests written and passing
• Example created and tested
• Documentation updated
• Roadmap updated
• Conventional commit format used
• No breaking changes

Related Issues

Closes #TBD (Transform Hierarchy feature request)
Part of Phase 7: Core Completeness for v1.0.0