# 64k Demo Project

## Goal
- Produce a <=64k native demo binary
- Same C++ codebase for Windows, macOS, Linux

## Graphics
- WebGPU via wgpu-native
- WGSL shaders
- Hybrid rendering: Rasterized proxy geometry + SDF raymarching

## Audio
- 32 kHz, 16-bit stereo
- Procedurally generated samples
- Real-time additive synthesis from spectrograms (IDCT)
- Variable tempo system with music time abstraction
- Event-based pattern triggering for dynamic tempo scaling
- Modifiable Loops and Patterns, w/ script to generate them (like a Tracker)
- Unified AudioEngine for lifecycle management

## Constraints
- Size-sensitive
- Minimal dependencies
- Explicit control over all allocations

## Style
- Demoscene
- No engine abstractions

---

## Current Status

- Audio system: Sample-accurate synchronization. Hardware playback time as master clock. Variable tempo support. Pipeline optimized (Task #72): Zero heap allocations per frame, direct ring buffer writes. Comprehensive test coverage.
- Build system: Optimized with proper asset dependency tracking
- Shader system: Parameterization complete (UniformHelper, .seq syntax). Modular with compilation tests. WGSL composability improved (`math/common_utils.wgsl`).
- 3D rendering: Hybrid SDF/rasterization with BVH acceleration and binary scene loader. Object data loading pipeline enhanced.
- Asset pipeline: Blender export script and binary scene ingestion
- Error handling: Dual macro system (`FATAL_XXX` for programming errors, `CHECK_RETURN` for recoverable errors)
- Testing: **36/36 tests passing (100%)** - All tests operational

---

## Next Up

**Active:**
- Task #5: Spectral Brush Editor [IN PROGRESS] - Procedural spectrogram tool (50-100× compression)

**Visuals:**
- Task #52: Procedural SDF Font
- Task #53: Particles Shader Polish
- Task #55: SDF Random Planes Intersection

**Structure:**
- Task #77: Workspace System - Self-contained demo workspaces

**Tooling:**
- Task #54: Tracy Integration
- Task #76: External Library Size Measurement

**Details:** See `TODO.md` and individual design docs

---

## Design Docs Reference

**Core Systems:**
- `doc/ASSET_SYSTEM.md` - Build-time asset packer, 16-byte alignment
- `doc/SEQUENCE.md` - .seq timeline format with BPM notation
- `doc/TRACKER.md` - Audio pattern system, unit-less timing
- `doc/3D.md` - Hybrid SDF raymarching with BVH acceleration

**Formats:**
- `doc/SCENE_FORMAT.md` - Binary scene format (SCN1)
- `doc/MASKING_SYSTEM.md` - Auxiliary texture registry

**Tools & Workflow:**
- `doc/BUILD.md` - Multi-platform builds (Debug/STRIP_ALL/FINAL_STRIP)
- `doc/SPECTRAL_BRUSH_EDITOR.md` - Procedural spectrogram tool
- `doc/WORKSPACE_SYSTEM.md` - Multi-demo organization
- `doc/HOT_RELOAD.md` - Debug-only file change detection
- `doc/SIZE_MEASUREMENT.md` - External library size measurement
- `doc/test_demo_README.md` - 16s audio/visual sync test

**Meta:**
- `doc/CONTEXT_MAINTENANCE.md` - Context hygiene protocol

---

## Recently Completed

**Feb 9, 2026:**
- Size measurement system (Task #76) - Demo: 4.4MB, External: 2.0MB
- Hot-reload file watcher (debug-only, 0 bytes overhead)
- WGSL uniform buffer validation (Task #75)
- Uniform buffer alignment fixes (Task #74)

**Feb 8, 2026:**
- Shader parametrization system (Task #73)

---

For detailed architecture, see `doc/ARCHITECTURE.md`.

For completed tasks history, see `doc/COMPLETED.md` and git history.