# To-Do List

This file tracks prioritized tasks with detailed attack plans.

**Note:** For completed tasks, see `doc/COMPLETED.md`.

---

## Priority 1: Spectral Brush Editor (Task #5) [IN PROGRESS]

**Goal:** Web-based tool for procedurally tracing audio spectrograms. Replaces large `.spec` binary assets with tiny procedural C++ code (50-100× compression).

**Design Document:** See `doc/SPECTRAL_BRUSH_EDITOR.md` for complete architecture.

**Core Concept:** Bezier curves trace time-frequency paths. Gaussian profiles shape "brush strokes" around curves.

**Workflow:** `.wav` → Load in editor → Trace with Bezier curves → Export `procedural_params.txt` + C++ code

### Phase 1: C++ Runtime (Foundation)
- [ ] Files: `src/audio/spectral_brush.h`, `src/audio/spectral_brush.cc`
- [ ] Define API (`ProfileType`, `draw_bezier_curve()`, `evaluate_profile()`)
- [ ] Implement linear Bezier interpolation
- [ ] Implement Gaussian profile evaluation
- [ ] Implement home-brew deterministic RNG
- [ ] Add unit tests (`src/tests/test_spectral_brush.cc`)
- [ ] **Deliverable:** Compiles, tests pass

### Phase 2: Editor Core
- [ ] Files: `tools/spectral_editor/index.html`, `script.js`, `style.css`, `dct.js`
- [ ] HTML structure (canvas, controls, file input)
- [ ] Canvas rendering (dual-layer: reference + procedural)
- [ ] Bezier curve editor (click, drag, delete control points)
- [ ] Profile controls (Gaussian sigma slider)
- [ ] Real-time spectrogram rendering
- [ ] Audio playback (IDCT → Web Audio API)
- [ ] Undo/Redo system
- [ ] Keyboard shortcuts (1=play procedural, 2=play original, Space, Ctrl+Z, Delete)
- [ ] **Deliverable:** Interactive editor, can trace .wav files

### Phase 3: File I/O
- [ ] Load .wav (decode, FFT/STFT → spectrogram)
- [ ] Load .spec (binary format parser)
- [ ] Save procedural_params.txt (human-readable, re-editable)
- [ ] Generate C++ code (ready to compile)
- [ ] Load procedural_params.txt (re-editing workflow)
- [ ] **Deliverable:** Full save/load cycle works

### Phase 4: Future Extensions (Post-MVP)
- [ ] Cubic Bezier interpolation (smoother curves)
- [ ] Decaying sinusoid profile (metallic sounds)
- [ ] Noise profile (textured sounds)
- [ ] Composite profiles (add/subtract/multiply)

**Design Decisions:** Linear Bezier (Phase 1), cubic later. Soft parameter limits. Home-brew RNG. Single function per sound initially.

**Size Impact:** 50-100× compression (5 KB .spec → ~100 bytes C++ code)

---

## Priority 2: Workspace System (Task #77)

**Goal:** Reorganize project into self-contained workspaces to support parallel demo development.

**Design Document:** See `doc/WORKSPACE_SYSTEM.md` for complete architecture.

**Core Concept:** Each demo gets its own workspace directory with timeline, music, assets, and shaders. Common resources shared via `assets/common/`.

**Proposed Structure:**
```
/workspaces/
  /main/          # Main production demo
    workspace.cfg
    timeline.seq
    music.track
    assets.txt
    /assets/
    /shaders/
  /test/          # Test demo
    ...
/assets/common/   # Shared resources
  /shaders/
  /audio/
```

**Benefits:**
- Clear project organization
- Parallel development without conflicts
- Easy workspace switching (`-DDEMO_WORKSPACE=main`)
- Scales to multiple demos

**Implementation:** 12-16 hours (5 phases)

**Priority:** Medium (workflow improvement)

---

## Priority 3: 3D System Enhancements (Task #18)

**Goal:** Establish pipeline for importing complex 3D scenes to replace hardcoded geometry.

**Progress:** C++ pipeline for loading object-specific data (plane_distance) is in place. Shader integration for SDFs pending.

---

## Priority 3: WGSL Modularization (Task #50) [RECURRENT]

**Goal:** Refactor `ShaderComposer` and WGSL assets to support granular, reusable snippets. Ongoing task for shader code hygiene.

### Sub-task: Split common_uniforms.wgsl (Low Priority)
**Current:** `common_uniforms.wgsl` contains 4 structs (CommonUniforms, GlobalUniforms, ObjectData, ObjectsBuffer)

**Goal:** Split into separate files:
- `common_uniforms/common.wgsl` - CommonUniforms only
- `common_uniforms/global.wgsl` - GlobalUniforms only
- `common_uniforms/object.wgsl` - ObjectData + ObjectsBuffer

**Benefit:** Shaders only include what they need, reducing compiled size

**Impact:** Minimal (most shaders only use CommonUniforms)

**Priority:** Low (nice-to-have)

### Sub-task: Type-safe shader composition (Low Priority)
**Problem:** Recurrent error of forgetting `ShaderComposer::Get().Compose({}, code)` and using raw `code` directly. Runtime error only (crashes demo, tests may pass).

**Solution:** Use strong typing to make it compile-time error:
```cpp
class ComposedShader {
 private:
  std::string code_;
  friend class ShaderComposer;
  explicit ComposedShader(std::string code) : code_(std::move(code)) {}
 public:
  const char* c_str() const { return code_.c_str(); }
};
```

**Changes:**
- `ShaderComposer::Compose()` returns `ComposedShader` instead of `std::string`
- All shader creation functions take `const ComposedShader&` instead of `const char*`
- Cannot pass raw string to shader functions (compile error)

**Benefits:** Impossible to forget composition (type mismatch). Self-documenting API. Compile-time error.

**Trade-offs:** More verbose code. Small overhead (extra std::string copy, negligible).

**Priority:** Low (recurrent but rare, easy to catch in testing)

---

## Phase 2: Size Optimization (Final Goal)

- [ ] **Task #34: Full STL Removal** - Replace remaining `std::vector`, `std::map`, `std::string` with custom containers
- [ ] **Task #22: Windows Native Platform** - Replace GLFW with Win32 API
- [ ] **Task #28: Spectrogram Quantization** - Research optimal frequency distribution
- [ ] **Task #35: CRT Replacement** - Investigation and implementation of CRT-free entry
- [ ] **Task #76: External Library Size Measurement** - STRIP_EXTERNAL_LIBS mode with stub implementations to measure core demo size vs external library overhead. See `doc/SIZE_MEASUREMENT.md`.

---

For untriaged future goals and ideas, see `doc/BACKLOG.md`.