Prerequisites
- Node.js (LTS recommended) and npm
- Chrome 113+ with WebGPU support — required for rendering
- Dedicated GPU recommended for smooth 60fps preview
Firefox is supported but requires the Native Helper for project storage because Firefox does not support the File System Access API flow used by Chrome.
On Linux, enable Vulkan for smooth 60fps: chrome://flags/#enable-vulkan
Install and start
Clone the repository
git clone https://github.com/Sportinger/MasterSelects.git
cd MasterSelects
Start the dev server
Opens at http://localhost:5173. Includes HMR (Hot Module Replacement). The engine singleton survives hot reloads via import.meta.hot.data.Use npm run dev (not npm run dev:changelog) during normal development. The changelog dialog only appears in production builds and when explicitly requested via npm run dev:changelog.
Dev scripts
| Script | Description |
|---|
npm run dev | Dev server with HMR at http://localhost:5173 (no changelog dialog) |
npm run dev:changelog | Dev server with changelog dialog on load |
npm run build | Production build — runs tsc then vite build |
npm run build:deploy | Production build — skips tsc, runs vite build only |
npm run lint | ESLint check |
npm run preview | Serve the production build locally |
npm run test | Run all tests with Vitest (once) |
npm run test:watch | Run tests in watch mode |
npm run test:unit | Run unit tests only (tests/unit/) |
npm run test:coverage | Run tests with coverage report |
npm run test:security | Security-focused test suite |
Native Helper (optional)
The Native Helper is a cross-platform Rust companion app. It is required for:
- Firefox project storage — Firefox lacks the File System Access API
- External AI agent bridge —
POST http://127.0.0.1:9877/api/ai-tools
- Video downloads — yt-dlp integration for YouTube, TikTok, Instagram, Vimeo, etc.
cd tools/native-helper
cargo run --release
- WebSocket port 9876 — browser tab connection
- HTTP port 9877 — AI tools bridge and local API
Windows builds require FFMPEG_DIR and LIBCLANG_PATH environment variables. See tools/native-helper/README.md for platform-specific instructions.
- Rust — for building the helper
- yt-dlp — for video downloads (must be on
PATH)
Project structure
src/
├── components/ # React UI
│ ├── timeline/ # Timeline editor (hooks/, components/, utils/)
│ ├── panels/ # Properties, Media, AI, Download, Export, Scopes
│ ├── preview/ # Canvas + overlays + transform handles + SAM2 overlay
│ ├── outputManager/ # Multi-window output with slices
│ ├── export/ # Export dialog, codec selector
│ ├── dock/ # Panel/tab system
│ ├── common/ # Dialogs, tutorial, settings, shared components
│ └── mobile/ # Mobile-responsive layout
├── stores/ # Zustand state management
│ ├── timeline/ # 17 slices: track, clip, keyframe, mask, playback ...
│ └── mediaStore/ # 9 slices: import, folder, proxy, composition ...
├── engine/ # WebGPU rendering pipeline
│ ├── core/ # WebGPUContext, RenderTargetManager
│ ├── render/ # Compositor, RenderLoop, LayerCollector, NestedCompRenderer
│ ├── pipeline/ # CompositorPipeline, EffectsPipeline, OutputPipeline, SlicePipeline
│ ├── texture/ # TextureManager, ScrubbingCache, MaskTextureManager
│ ├── export/ # FrameExporter, VideoEncoder, ClipPreparation
│ ├── audio/ # AudioMixer, AudioEncoder, TimeStretch
│ ├── analysis/ # Histogram, Vectorscope, Waveform scopes
│ └── stats/ # PerformanceStats
├── effects/ # 30 GPU effects (color/, blur/, distort/, stylize/, keying/)
├── services/ # Business logic
│ ├── aiTools/ # 76 AI tool definitions + handlers
│ ├── sam2/ # SAM2 model manager + service
│ ├── project/ # Project persistence, save/load
│ ├── nativeHelper/ # Native decoder + WebSocket client
│ ├── layerBuilder/ # Layer building + video sync
│ └── monitoring/ # Playback health monitors
├── shaders/ # WGSL (composite, effects, output, optical flow, slice)
├── hooks/ # React hooks (useEngine, useGlobalHistory, useMIDI)
├── utils/ # Keyframe interpolation, mask renderer, file loader
├── types/ # TypeScript type definitions
└── workers/ # Transcription worker
tools/
├── native-helper/ # Rust binary (FFmpeg + yt-dlp bridge)
├── ffmpeg-build/ # FFmpeg build scripts
├── ffmpeg-wasm-build/ # FFmpeg WASM build configuration
└── qwen3vl-server/ # Qwen3 VL server for scene description
tests/
├── unit/ # Unit tests (Vitest)
└── stores/ # Store tests
Commit checklist
Before every commit, run all three checks:
npm run build # must complete with no errors
npx eslint . # 0 errors (warnings are OK)
npm run test # all tests must pass
Never commit directly to master. Commit to staging and merge via PR.
Key files
| Area | File |
|---|
| Engine entry | src/engine/WebGPUEngine.ts |
| Engine hook | src/hooks/useEngine.ts |
| Render dispatcher | src/engine/render/RenderDispatcher.ts |
| Timeline store | src/stores/timeline/index.ts |
| Media store | src/stores/mediaStore/index.ts |
| History (undo/redo) | src/stores/historyStore.ts |
| Logger | src/services/logger.ts |
| Feature flags | src/engine/featureFlags.ts |
| Version/changelog | src/version.ts |
Related