Architecture
How the packages fit together - dependency graph, data flow, and internal module structure
Timelinx is a modular monorepo with four published packages. Each layer depends only on the layers below it - you can use any layer independently.
Package Dependency Graph
The Layers
Core
The headless engine. Pure-function dispatch model for timeline state management. Zero runtime dependencies, no side effects.
React
React bindings. Bridges the core engine to React's rendering model via useSyncExternalStore.
UI
UI components. Drop-in React components for building timeline editors. Tracks, clips, panels, and more.
Media Web
Web-native media adapters. WebCodecs decoding, WebAudio waveforms, thumbnail extraction, WebGL compositing, and export.
Core Internal Architecture
@timelinx/core is the foundation - a deterministic, frame-based editing kernel with zero runtime dependencies.
Key design decisions:
React Binding Architecture
@timelinx/react bridges the core engine to React's rendering model.
Key insight
Uses useSyncExternalStore so only components that read changed state re-render. No prop drilling, no unnecessary renders.
UI Component Map
@timelinx/ui provides 29+ React components organized into five categories:
Media Pipeline
@timelinx/media-web implements the pipeline contracts defined in @timelinx/core using browser-native APIs:
End-to-End Data Flow
This is how a user interaction flows through the entire stack:
Serialization & Interchange
@timelinx/core supports multiple interchange formats for professional workflows:
All state is plain objects - no class instances, no circular references. Serialize to JSON, persist anywhere, sync across tabs, or send to a server.