docs: Add handoff for asset regeneration fix

1 files changed, 112 insertions, 0 deletions

diff --git a/HANDOFF_2026-02-07_AssetRegeneration.md b/HANDOFF_2026-02-07_AssetRegeneration.md
new file mode 100644
index 0000000..dd41b31
--- /dev/null
+++ b/HANDOFF_2026-02-07_AssetRegeneration.md
@@ -0,0 +1,112 @@
+# Handoff: Asset Regeneration Fix (February 7, 2026)
+
+## Session Summary
+Fixed build system issue where generated files weren't automatically regenerated after `make clean`, causing "fatal error: 'generated/assets.h' file not found" errors.
+
+## Problem
+After running `make clean` in the build directory, the build would fail because:
+1. Generated asset files (`generated/assets.h`, etc.) were removed
+2. CMake didn't know to regenerate them before compiling libraries
+3. Libraries (`audio`, `3d`, `gpu`) tried to compile before assets existed
+
+## Solution
+
+### 1. Mark Generated Files with GENERATED Property
+Added `set_source_files_properties()` calls to tell CMake these files are generated and should be checked for rebuild:
+
+```cmake
+# Mark generated files so CMake always checks if they need rebuilding
+set_source_files_properties(${GEN_DEMO_H} ${GEN_DEMO_CC} PROPERTIES GENERATED TRUE)
+set_source_files_properties(${GEN_TEST_H} ${GEN_TEST_CC} PROPERTIES GENERATED TRUE)
+set_source_files_properties(${GENERATED_TIMELINE_CC} PROPERTIES GENERATED TRUE)
+set_source_files_properties(${GENERATED_MUSIC_DATA_CC} PROPERTIES GENERATED TRUE)
+set_source_files_properties(${GENERATED_TEST_DEMO_TIMELINE_CC} PROPERTIES GENERATED TRUE)
+set_source_files_properties(${GENERATED_TEST_DEMO_MUSIC_CC} PROPERTIES GENERATED TRUE)
+```
+
+### 2. Add Explicit Library Dependencies
+Added `add_dependencies()` to ensure libraries wait for asset generation:
+
+```cmake
+# Libraries must wait for asset generation (they include generated/assets.h)
+add_dependencies(audio generate_demo_assets)
+add_dependencies(3d generate_demo_assets)
+add_dependencies(gpu generate_demo_assets)
+```
+
+### 3. Update seq_compiler for GpuContext
+Updated code generator to match the GpuContext refactor from earlier session:
+
+**Before:**
+```cpp
+"void LoadTimeline(MainSequence& main_seq, WGPUDevice device, "
+    "WGPUQueue queue, WGPUTextureFormat format) {\n";
+
+">(device, queue, format" << eff.extra_args << "), "
+```
+
+**After:**
+```cpp
+"void LoadTimeline(MainSequence& main_seq, const GpuContext& ctx) {\n";
+
+">(ctx" << eff.extra_args << "), "
+```
+
+### 4. Cleanup Stale Files
+Removed old generated test assets that were incorrectly placed in `src/generated/`:
+- `test_assets.h` / `test_assets_data.cc` (now in `build/src/generated_test/`)
+- `test_demo_assets.h` / `test_demo_assets_data.cc` (now in `build/src/generated_test/`)
+
+## Commit Made
+
+**Commit:** fb2aa8b
+**Title:** `fix: Auto-regenerate assets after clean build`
+
+**Changes:**
+- CMakeLists.txt: +15 lines (GENERATED properties + dependencies)
+- tools/seq_compiler.cc: Updated signatures
+- Removed 4 stale generated files (~41K lines)
+
+## Verification
+
+**Clean Build Test:**
+```bash
+cd build
+make clean
+rm -f ../src/generated/*.{h,cc}
+cmake --build . --target demo64k
+```
+
+**Result:** ✅ Build succeeds, assets regenerated automatically
+
+**Tests:** ✅ All 28 tests pass
+
+## Technical Details
+
+**Build Order (After Fix):**
+1. Build tools: `seq_compiler`, `tracker_compiler`, `asset_packer`
+2. Generate files: `generate_timeline`, `generate_tracker_music`, `generate_demo_assets`
+3. **Wait for generation to complete** (new dependency)
+4. Build libraries: `audio`, `3d`, `gpu` (now safe to compile)
+5. Build executables: `demo64k`, `test_demo`
+
+**Key Insight:**
+The `GENERATED` property alone isn't enough - you also need explicit `add_dependencies()` for libraries that consume generated headers. Without it, CMake may start compiling library sources before the generation targets complete.
+
+## Files Modified
+- CMakeLists.txt (15 insertions)
+- tools/seq_compiler.cc (5 changes)
+- Removed 4 stale files
+
+## Current State
+- ✅ All targets build successfully after clean
+- ✅ All 28 tests passing
+- ✅ Working tree clean
+- ✅ 4 commits ahead of origin/main
+
+## Ready For
+- Push to origin (`git push`)
+- Continue with next priorities
+
+---
+**handoff(Claude):** Asset regeneration fixed. Clean builds now work correctly. All dependencies tracked properly.