ADR-006: Editor Architecture

Status: Accepted Date: 2026-01-29

Context

The engine needs a visual editor for scene composition, entity inspection, and developer workflow. Several architectural decisions were made regarding the UI framework, state management, ECS integration, and extensibility.

Decision

1. SolidJS for Editor UI

Use SolidJS as the editor UI framework for its fine-grained reactivity, small bundle size, and performance characteristics well-suited to a real-time editor.

2. Hexagonal (Ports and Adapters) Architecture

Editor-core uses hexagonal architecture separating:

• Domain -- Commands, selection, history (pure logic)
• Ports -- Interfaces for ECS access, persistence, plugin hosting
• Adapters -- Concrete implementations (ECSBridge, LocalStorage, etc.)

This ensures editor core can be tested without the UI framework, and the ECS access is isolated behind a bridge.

3. ECS Bridge Read-Only Pattern

The editor UI accesses ECS data through an ECSBridge that provides read-only access. All mutations go through the command system:

UI --> Command --> Bridge --> ECS World

This prevents accidental world corruption from UI code, makes all mutations undoable, and enables collaborative editing (commands can be serialized).

4. Four-Store Maximum Rule

Editor state is managed across at most 4 stores to prevent dual-truth bugs:

1. ECS World -- Game/scene state (source of truth)
2. EditorStateStore -- UI state (panel visibility, tool selection)
3. SessionManager -- Persistent preferences (layout, recent files)
4. SelectionManager -- Current selection state

5. Plugin System with Lifecycle Hooks

Editor extensibility through a plugin host with lifecycle hooks:

• onActivate -- Plugin initialization
• onDeactivate -- Cleanup
• onDispose -- Final teardown

Consequences

Positive

• Editor core is fully testable without UI (212+ tests)
• All editor mutations are undoable
• Clean separation between game state and editor state
• Plugin system enables community extensions

Negative

• Hexagonal architecture adds indirection layers
• Four-store rule may need relaxation for complex features
• Plugin isolation requires careful API design

Alternatives Considered

• Direct ECS mutation from UI -- Rejected: bypasses undo/redo and collaborative editing
• Single store (Redux-style) -- Rejected: ECS World is inherently separate from UI state
• Micro-frontend architecture -- Rejected: over-engineered for initial editor

Related

• ADR-007: Data-Oriented Design -- Core design principle the editor builds upon