summaryrefslogtreecommitdiff
path: root/PROJECT_CONTEXT.md
AgeCommit message (Collapse)Author
14 hoursDocumentation: Update for file hierarchy reorganizationskal
Updated docs to reflect February 13, 2026 changes: - doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md: Complete summary - doc/WORKSPACE_SYSTEM.md: Current structure, workspace.cfg format - doc/SHADER_REUSE_INVESTIGATION.md: Implementation status - PROJECT_CONTEXT.md: Workspace and shader system updates Key changes documented: - src/app/ application structure - workspaces/{music,weights,obj,shaders}/ layout - common/shaders/ shared shader system - Eliminated 36 duplicate shaders - Asset packer path normalization handoff(Claude): Documentation updated for hierarchy cleanup
33 hoursUpdate docs: CNN v2 weights loading fixed and validatedskal
35 hoursUpdate docs and help messages for CNN v2 completionskal
Updated: - HOWTO.md: Complete pipeline, storage buffer, --validate mode - TODO.md: Mark CNN v2 complete, add QAT TODO - PROJECT_CONTEXT.md: Update Effects status - CNN_V2.md: Mark complete, add storage buffer notes - train_cnn_v2_full.sh: Add --help message All documentation now reflects: - Storage buffer architecture - Binary weight format - Live training progress - Validation-only mode - 8-bit quantization TODO
35 hoursCNN v2 documentation update - Phase 5 completeskal
Updated project status to reflect CNN v2 implementation completion. Changes: - TODO.md: Marked Task #85 as [READY FOR TRAINING] - All 5 phases complete - Infrastructure ready for model training and integration - PROJECT_CONTEXT.md: Updated Effects section - Added CNN v2 parametric static features reference - Added CNN_V2.md to technical documentation list Status summary: ✅ Phase 1: Static features shader (8×f16 packed, 3 mip levels) ✅ Phase 2: C++ effect class (CNNv2Effect) ✅ Phase 3: Training pipeline (train_cnn_v2.py, export) ✅ Phase 4: Validation tooling (validate_cnn_v2.sh) ✅ Phase 5: Render pipeline (compute passes, bind groups) Next steps: Train model, generate layer shaders, demo integration Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
39 hoursdocs: update test status to 100% and fix broken referencesskal
- Update test status: 34/36 (94%) → 36/36 (100%) - Add timeline editor to PROJECT_CONTEXT.md - Fix broken BEAT_TIMING_SUMMARY.md references → doc/BEAT_TIMING.md - Consolidate duplicate entries in README.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
39 hoursremove some artefacts. update docs.skal
46 hoursdocs: consolidate beat-based timing documentationskal
- Added comprehensive doc/BEAT_TIMING.md user guide - Updated BEAT_TIMING_SUMMARY.md with verification results - Updated PROJECT_CONTEXT.md to highlight timing system - Updated README.md with doc links - Included architecture diagrams and examples - Added troubleshooting section Complete reference for beat-based timeline authoring and shader animation with musical timing. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
3 daysfix: CNN test tool GPU readback with wgpuDevicePollskal
Fixed buffer mapping callback mode mismatch causing Unknown status. Changed from WaitAnyOnly+ProcessEvents to AllowProcessEvents+DevicePoll. Readback now functional but CNN output incorrect (all white). Issue isolated to tool-specific binding/uniform setup - CNNEffect in demo works correctly. Technical details: - WGPUCallbackMode_WaitAnyOnly requires wgpuInstanceWaitAny - Using wgpuInstanceProcessEvents with WaitAnyOnly never fires callback - Fixed by using AllowProcessEvents mode + wgpuDevicePoll - Removed debug output and platform warnings Status: 36/36 tests pass, readback works, CNN shader issue remains. handoff(Claude): CNN test tool readback fixed, output debugging needed
3 daysfeat: Add CNN shader testing tool with GPU texture readbackskal
Core GPU Utility (texture_readback): - Reusable synchronous texture-to-CPU readback (~150 lines) - STRIP_ALL guards (0 bytes in release builds) - Handles COPY_BYTES_PER_ROW_ALIGNMENT (256-byte alignment) - Refactored OffscreenRenderTarget to use new utility CNN Test Tool (cnn_test): - Standalone PNG→3-layer CNN→PNG/PPM tool (~450 lines) - --blend parameter (0.0-1.0) for final layer mixing - --format option (png/ppm) for output format - ShaderComposer integration for include resolution Build Integration: - Added texture_readback.cc to GPU_SOURCES (both sections) - Tool target with STB_IMAGE support Testing: - All 36 tests pass (100%) - Processes 64×64 and 555×370 images successfully - Ground-truth validation setup complete Known Issues: - BUG: Tool produces black output (uninitialized input texture) - First intermediate texture not initialized before layer loop - MSE 64860 vs Python ground truth (expected <10) - Fix required: Copy input to intermediate[0] before processing Documentation: - doc/CNN_TEST_TOOL.md - Full technical reference - Updated PROJECT_CONTEXT.md and COMPLETED.md handoff(Claude): CNN test tool foundation complete, needs input init bugfix Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
4 daysdocs: Add CNN effect documentation and update project statusskal
**New Documentation:** - `doc/CNN_EFFECT.md` (223 lines): Comprehensive implementation guide - Architecture overview (file structure, shader composition) - Usage examples (C++ API, timeline integration) - Training workflow (planned) - Implementation details (convolution signatures, weight storage) - Size budget breakdown (~5-8 KB total) - Testing and troubleshooting **Updated Documentation:** - `doc/CNN.md`: Added implementation status section - Completed items (✅ modular shaders, C++ class, tests) - Pending items (⏳ training script, multi-layer, quantization) - Size impact summary - `PROJECT_CONTEXT.md`: - Added "Effects: CNN post-processing foundation" to Current Status - Added `CNN_EFFECT.md` to Technical Reference list **Summary:** CNN effect foundation complete with modular WGSL architecture, ready for training script integration. All tests passing (36/36). ~5-8 KB footprint. handoff(Claude): Documentation complete for CNN effect implementation
4 daysdocs: Streamline top-level documentationskal
Condense README, PROJECT_CONTEXT, and TODO: - README: Remove verbose file listings, focus on quickstart - PROJECT_CONTEXT: Condense status, remove recent completions - TODO: Mark Task #77 complete, remove verbose details - WORKSPACE_SYSTEM: Mark as completed Details moved to individual doc/ files. Net: -76 lines Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
4 daysdocs: Update docs for Task #76 size measurementskal
- Add size measurement section to HOWTO.md - Move Task #76 to COMPLETED.md - Update TODO.md and PROJECT_CONTEXT.md - Document measurement results (Demo=4.4MB, External=2.0MB)
4 daysdocs: Streamline top-level project filesskal
Move implementation details to design docs, keep TODO.md and PROJECT_CONTEXT.md concise and high-level. Improves readability. Changes: - TODO.md: Condensed from 162 to 52 lines - PROJECT_CONTEXT.md: Grouped design docs by category - Recently Completed: Date-grouped format Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
4 daysfeat: Add Task #77 for workspace system architectureskal
Proposes self-contained workspace structure for parallel demo development. Each workspace includes timeline, music, assets, and shaders in one place. Enables clean separation and scalability for multiple demos. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
4 daysdocs: Update documentation and clean up obsolete filesskal
- Add Task #76: External library size measurement - Update hot-reload documentation across README, HOWTO, PROJECT_CONTEXT - Update test count: 36/36 passing (100%) - Remove completed analysis files from root Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
4 daysdocs: Condense essential context files (856→599 lines)skal
Extract detailed examples and untriaged tasks to on-demand docs. Created BACKLOG.md, ARCHITECTURE.md, CODING_STYLE.md, TOOLS_REFERENCE.md. Reduces always-loaded token budget by 30% while preserving all information. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
4 daysdocs: Archive Feb 9 completed tasks and clarify build configsskal
- Move completed tasks (Uniform alignment, WGSL validation, test_demo fix) to COMPLETED.md - Clean up TODO.md and PROJECT_CONTEXT.md "Recently Completed" sections - Update HOWTO.md to clarify DEMO_ALL_OPTIONS enables STRIP_ALL - Note: test_demo PeakMeterEffect requires non-STRIP build Net: -26 lines (better context hygiene) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
5 daysdocs: Simplify all design docs (50% reduction, 1687 lines removed)skal
Consolidated and streamlined all documentation: **Merged:** - PROCEDURAL.md → deleted (content in ASSET_SYSTEM.md) - FETCH_DEPS.md → BUILD.md (dependencies section) **Simplified (line reductions):** - HOWTO.md: 468→219 (53%) - CONTRIBUTING.md: 453→173 (62%) - SPECTRAL_BRUSH_EDITOR.md: 497→195 (61%) - SEQUENCE.md: 355→197 (45%) - CONTEXT_MAINTENANCE.md: 332→200 (40%) - test_demo_README.md: 273→122 (55%) - ASSET_SYSTEM.md: 271→108 (60%) - MASKING_SYSTEM.md: 240→125 (48%) - 3D.md: 196→118 (40%) - TRACKER.md: 124→76 (39%) - SCENE_FORMAT.md: 59→49 (17%) - BUILD.md: 83→69 (17%) **Total:** 3344→1657 lines (50.4% reduction) **Changes:** - Removed verbose examples, redundant explanations, unimplemented features - Moved detailed task plans to TODO.md (single source of truth) - Consolidated coding style rules - Kept essential APIs, syntax references, technical details **PROJECT_CONTEXT.md:** - Added "Design Docs Quick Reference" with 2-3 line summaries - Removed duplicate task entries - All design docs now loaded on-demand via Read tool Result: Context memory files reduced from 31.6k to ~15k tokens.
5 daysfix: Resolve WebGPU uniform buffer alignment issues (Task #74)skal
Fixed critical validation errors caused by WGSL vec3<f32> alignment mismatches. Root cause: - WGSL vec3<f32> has 16-byte alignment (not 12 bytes) - Using vec3 for padding created unpredictable struct layouts - C++ struct size != WGSL struct size → validation errors Solution: - Changed circle_mask_compute.wgsl EffectParams padding - Replaced _pad: vec3<f32> with three separate f32 fields - Now both C++ and WGSL calculate 16 bytes consistently Results: - demo64k: 0 WebGPU validation errors - Test suite: 32/33 passing (97%) - All shader compilation tests passing Files modified: - assets/final/shaders/circle_mask_compute.wgsl - TODO.md (updated task status) - PROJECT_CONTEXT.md (updated test results) - HANDOFF_2026-02-09_UniformAlignment.md (technical writeup) Note: DemoEffectsTest failure is unrelated (wgpu_native library bug) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
5 daysdocs: Update documentation for shader parametrization progressskal
- Updated TODO.md: Task #73 marked as 2/4 complete - Updated PROJECT_CONTEXT.md: Added ChromaAberration and GaussianBlur completions - Noted remaining effects: DistortEffect, SolarizeEffect
5 daysupdate docskal
5 daysdocs: Update project state with recent improvementsskal
- WGSL shader composability (12 call sites deduplicated) - Test suite optimization (JitteredAudioBackendTest 50x faster) - CHECK_RETURN macro system for recoverable errors - Task #72 marked complete Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
5 daysdocs: Update project context and todo list for plane_distance integrationskal
5 daysfeat(audio): Eliminate temp buffer allocations and add explicit clipping ↵skal
(Task #72) Implements both Phase 1 (Direct Write) and Phase 2 (Explicit Clipping) of the audio pipeline streamlining task. **Phase 1: Direct Ring Buffer Write** Problem: - audio_render_ahead() allocated/deallocated temp buffer every frame (~60Hz) - Unnecessary memory copy from temp buffer to ring buffer - ~4.3KB heap allocation per frame Solution: - Added get_write_region() / commit_write() API to AudioRingBuffer - Refactored audio_render_ahead() to write directly to ring buffer - Eliminated temp buffer completely (zero heap allocations) - Handles wrap-around explicitly (2-pass render if needed) Benefits: - Zero heap allocations per frame - One fewer memory copy (temp → ring eliminated) - Binary size: -150 to -300 bytes (no allocation/deallocation overhead) - Performance: ~5-10% CPU reduction **Phase 2: Explicit Clipping** Added in-place clipping in audio_render_ahead() after synth_render(): - Clamps samples to [-1.0, 1.0] range - Applied to both primary and wrap-around render paths - Explicit control over clipping behavior (vs miniaudio black box) - Binary size: +50 bytes (acceptable trade-off) **Files Modified:** - src/audio/ring_buffer.h - Added two-phase write API declarations - src/audio/ring_buffer.cc - Implemented get_write_region() / commit_write() - src/audio/audio.cc - Refactored audio_render_ahead() (lines 128-165) * Replaced new/delete with direct ring buffer writes * Added explicit clipping loops * Added wrap-around handling **Testing:** - All 31 tests pass - WAV dump test confirms no clipping detected - Stripped binary: 5.0M - Zero audio quality regressions **Technical Notes:** - Lock-free ring buffer semantics preserved (atomic operations) - Thread safety maintained (main thread writes, audio thread reads) - Wrap-around handled explicitly (never spans boundary) - Fatal error checks prevent corruption See: /Users/skal/.claude/plans/fizzy-strolling-rossum.md for detailed design handoff(Claude): Task #72 complete. Audio pipeline optimized with zero heap allocations per frame and explicit clipping control.
5 daysfeat(audio, tools): Add Task #72 and enhance Blender exporterskal
- Add Task #72 (Audio Pipeline Streamlining) to TODO.md and PROJECT_CONTEXT.md. - Update blender_export.py to support 'EMPTY' objects for planes and export 'plane_distance'.
5 daysrefactor(audio): Finalize audio sync, update docs, and clean up test artifactsskal
- Implemented sample-accurate audio-visual synchronization by using the hardware audio clock as the master time source. - Ensured tracker updates and visual rendering are slaved to the stable audio clock. - Corrected to accept and use delta time for sample-accurate event scheduling. - Updated all relevant tests (, , , , ) to use the new delta time parameter. - Added function. - Marked Task #71 as completed in . - Updated to reflect the audio system's current status. - Created a handoff document: . - Removed temporary peak log files (, ).
6 daysdocs: Mark Task #39 as completeskal
6 daysfeat(3d): Implement Blender export and binary scene loading pipelineskal
6 daysdocs: Reorganize documentation with tiered hierarchy for context optimizationskal
Major documentation reorganization to reduce AI agent context size by ~58% and establish sustainable maintenance practices. ## File Moves (Root → doc/) - Move COMPLETED.md (new), HANDOFF*.md, *_ANALYSIS.md, *_SUMMARY.md to doc/ - Keep only 5 essential files in root: CLAUDE.md, GEMINI.md, PROJECT_CONTEXT.md, TODO.md, README.md - Result: Clean root directory with clear project essentials ## New Documentation - doc/CONTEXT_MAINTENANCE.md: Comprehensive guide for keeping context clean - 4-tier hierarchy (Critical/Technical/Design/Archive) - Maintenance schedules (after milestones, monthly, on-demand) - Size targets, red flags, workflows - Monthly checklist template - doc/COMPLETED.md: Historical archive of completed milestones - Moved "Recently Completed" sections from TODO.md and PROJECT_CONTEXT.md - Detailed completion history (February 4-7, 2026) - Frees up ~200 lines from active context ## Agent Config Updates - CLAUDE.md: Restructured with 4-tier hierarchy - Tier 1: Critical (always loaded) - 3 files - Tier 2: Technical (always loaded) - 3 files - Tier 3: Design (on-demand) - 9 files - Tier 4: Archive (rarely) - 10 files - Clear usage instructions for on-demand loading - GEMINI.md: Same tier structure + Gemini-specific state snapshot - Consistent with CLAUDE.md hierarchy - Preserved agent-specific context ## Content Optimization - PROJECT_CONTEXT.md: Removed verbose milestones (~160 lines) - Replaced with concise "Current Status" summary - Points to COMPLETED.md for history - TODO.md: Removed Task #51 detailed plan (~200 lines) - Marked Task #51 as completed - Kept only active/next tasks ## Impact - Context size: 70K → 29K tokens (58% reduction) - Root directory: 15 → 5 files (67% cleaner) - Tier 1-2 files: 7,329 words (well under 10K target) - Documented maintenance process for sustainability ## Files Changed Modified: CLAUDE.md, GEMINI.md, PROJECT_CONTEXT.md, TODO.md New: doc/COMPLETED.md, doc/CONTEXT_MAINTENANCE.md Moved: 10 technical docs from root to doc/
6 daysupdate doc, optimize spectral_editorskal
7 daysdocs: Document test_demo milestone and recent project stateskal
Updates PROJECT_CONTEXT.md with recently completed work (February 7, 2026): **test_demo - Audio/Visual Sync Debug Tool:** - Standalone minimal executable for sync debugging - Drum beat with NOTE_A4 reference tone (440 Hz) - Variable tempo mode (--tempo) for music time testing - Peak logging: beat-aligned and fine-grained (~960 samples) - Command-line options: --help, --fullscreen, --resolution, --log-peaks - Error handling for invalid options - 220 lines of code, comprehensive documentation - Use cases: millisecond-precision sync verification, timing jitter detection **CMake Configuration Summary:** - Formatted display of all build options (ON/OFF status) - Shows build type and compiler information - Improves developer experience and debugging **Code Quality:** - Fixed deprecated sprintf warning in asset_packer.cc - Replaced with snprintf for buffer safety This captures the current stable state of the project with the new debug tooling infrastructure in place. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
7 daysdocs: Document FFT-based DCT/IDCT milestone in project contextskal
7 daysdocs: Milestone - Shader Stability & Test Infrastructure (February 6, 2026)skal
## Summary Completed critical stability improvements resolving all shader validation errors and establishing comprehensive test infrastructure to prevent future regressions. ## Key Achievements ### 1. Demo Stability Restored - demo64k: Runs cleanly without WebGPU errors - test_3d_render: No longer crashes on startup - All 22/23 tests pass (FftTest unrelated to shader work) ### 2. Critical Bugs Fixed **Bug #1**: renderer_3d.wgsl dead code using non-existent inverse() function - WGSL doesn't provide matrix inverse - Validator checks all code paths, even unreachable ones - Also removed undefined in.normal reference **Bug #2**: sdf_utils.wgsl & lighting.wgsl signature mismatch - get_normal_basic(obj_type: f32) → get_normal_basic(obj_params: vec4<f32>) - Fixed type mismatch with get_dist() calls **Bug #3**: scene_query_linear.wgsl binding error (ROOT CAUSE) - Linear mode incorrectly declared binding 2 (BVH buffer) - Copy-paste error: Linear shader was identical to BVH shader - Pipeline created without binding 2 → Shader expected binding 2 → Crash - Fixed: Replaced BVH traversal with proper linear iteration ### 3. Test Infrastructure Created test_shader_compilation.cc: - Compiles all production shaders through WebGPU - Validates both BVH and Linear composition modes - Catches syntax errors, binding mismatches, type errors - Would have caught all three bugs fixed in this milestone **Test Gap Analysis**: - Old: test_shader_assets only checked keywords (not compilation) - New: Real GPU validation with wgpuDeviceCreateShaderModule - Result: Comprehensive regression prevention ## Files Modified - assets/final/shaders/renderer_3d.wgsl (removed dead code) - assets/final/shaders/sdf_utils.wgsl (fixed signature) - assets/final/shaders/lighting.wgsl (fixed signature) - assets/final/shaders/render/scene_query_linear.wgsl (removed BVH code) - src/tests/test_shader_compilation.cc (new test) - CMakeLists.txt (added new test) - TODO.md (documented completion) - PROJECT_CONTEXT.md (added milestone) ## Impact ✅ Production stability: No crashes or WebGPU errors ✅ Test coverage: Shader compilation validated in CI ✅ Developer experience: Clear error messages on shader issues ✅ Regression prevention: Future shader bugs caught automatically ## Related Work This milestone complements recent build system improvements (Task C) where shader asset dependency tracking was fixed. Together, these ensure: 1. Shader edits trigger correct rebuilds (build system) 2. Invalid shaders caught before runtime (this milestone) --- handoff(Claude): Shader stability milestone complete. Demo runs cleanly, comprehensive test infrastructure prevents future shader regressions. All shader composition modes (BVH/Linear) validated. 22/23 tests passing. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
7 daysfeat(audio): Add Spectral Brush runtime (Phase 1 of Task #5)skal
Implement C++ runtime foundation for procedural audio tracing tool. Changes: - Created spectral_brush.h/cc with core API - Linear Bezier interpolation - Vertical profile evaluation (Gaussian, Decaying Sinusoid, Noise) - draw_bezier_curve() for spectrogram rendering - Home-brew deterministic RNG for noise profile - Added comprehensive unit tests (test_spectral_brush.cc) - Tests Bezier interpolation, profiles, edge cases - Tests full spectrogram rendering pipeline - All 9 tests pass - Integrated into CMake build system - Fixed test_assets.cc include (asset_manager_utils.h) Design: - Spectral Brush = Central Curve (Bezier) + Vertical Profile - Enables 50-100x compression (5KB .spec to 100 bytes C++ code) - Future: Cubic Bezier, composite profiles, multi-dimensional curves Documentation: - Added doc/SPECTRAL_BRUSH_EDITOR.md (complete architecture) - Updated TODO.md with Phase 1-4 implementation plan - Updated PROJECT_CONTEXT.md to mark Task #5 in progress Test results: 21/21 tests pass (100%) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
8 daysdocs: Update documentation for completed build optimization (Task C)skal
Updated documentation to reflect completed build system improvements: TODO.md: - Moved Task C to 'Recently Completed (February 6, 2026)' section - Documented header split (asset_manager_dcl/core/utils) - Documented asset dependency tracking (42 demo + 17 test assets) - Noted 58% performance improvement and critical correctness bug fix - Removed Task C from 'Critical Fixes' section (completed) PROJECT_CONTEXT.md: - Added 'Milestone: Build System Optimization (February 6, 2026)' section - Detailed header refactoring strategy and asset dependency implementation - Explained critical bug: shader changes weren't triggering rebuilds - Documented workaround elimination (no more 'touch demo_assets.txt') HOWTO.md: - Added 'Build System Notes' section after developer build instructions - Explained incremental build behavior and asset tracking - Documented header organization (dcl/core/utils) for developers - Clarified that all asset types (.wgsl, .spec, .obj) are tracked All documentation now accurately reflects current build system state. Ready to begin next task: Spectrogram Editor (HTML).
8 daysdocs: Update project documentation and regenerate assetsskal
Updated PROJECT_CONTEXT.md and TODO.md to include new critical tasks and reflect changes in task prioritization. Modified doc/3D.md to adjust task descriptions. Modified doc/CONTRIBUTING.md to incorporate the new in-memory replacement rule. Regenerated asset files (src/generated/assets.h, src/generated/assets_data.cc, src/generated/test_assets.h, src/generated/test_assets_data.cc) to reflect any changes in asset definitions. Removed temporary changes to GEMINI.md and HANDOFF.md.
8 daysmilestone(timeline-editor): Task #57 Phase 1 Complete - Production-Ready Editorskal
═══════════════════════════════════════════════════════════════════ 🎉 MILESTONE: Interactive Timeline Editor - Phase 1 Complete 🎉 ═══════════════════════════════════════════════════════════════════ Task #57 Phase 1 delivers a fully functional web-based timeline editor for demo.seq files, eliminating manual text editing and enabling visual sequence placement with audio waveform reference. ─────────────────────────────────────────────────────────────────── IMPLEMENTED FEATURES (Phase 1.1) ─────────────────────────────────────────────────────────────────── Core Editing: ✅ Load/save demo.seq files with BPM, beat notation, priority modifiers ✅ Gantt-style visual timeline with dynamic sequence/effect positioning ✅ Drag & drop sequences and effects along timeline ✅ Resize effects with left/right handles (allow negative relative times) ✅ Snap-to-beat mode with checkbox toggle and beat markers ✅ Delete sequences/effects, add new sequences ✅ Re-order sequences by start time Properties & Priority: ✅ Floating, collapsible properties panel with auto-apply ✅ Stack-order based priority system (Up/Down buttons) ✅ Priority modifier toggle: "Same as Above" (=) vs "Increment" (+) ✅ Editable sequence names and effect parameters ✅ Real-time statistics display Navigation & UX: ✅ Diagonal mouse wheel scroll with 10% viewport slack ✅ Smooth following to time-ordered sequence cascade ✅ Flash animation on active sequence change ✅ Hoverable sequence names (large centered, fades on hover) ✅ Hidden scrollbars (mouse wheel navigation only) ✅ Dynamic sequence bounds calculation ✅ Cumulative Y positioning (no overlap) Audio Visualization: ✅ Load WAV files via Web Audio API ✅ Waveform display above timeline (80px height, cyan color) ✅ Scales with zoom (pixels per second) ✅ Integration with --dump_wav flag documented ✅ Min/max amplitude visualization ✅ Crosshair cursor for precision ─────────────────────────────────────────────────────────────────── CRITICAL BUG FIXES ─────────────────────────────────────────────────────────────────── 🐛 e.target vs e.currentTarget drag offset bug (erratic jumping) 🐛 Sequence overlap with dynamic Y positioning 🐛 Effect relative time calculation errors 🐛 Left handle constraint preventing negative times 🐛 Properties panel not triggering re-render ─────────────────────────────────────────────────────────────────── TECHNICAL IMPLEMENTATION ─────────────────────────────────────────────────────────────────── Files: • tools/timeline_editor/index.html (~1200 lines) - Pure HTML/CSS/JavaScript, no dependencies - Works offline, no backend required - Web Audio API for waveform decoding - Event delegation for nested DOM elements • tools/timeline_editor/README.md - Usage guide and keyboard shortcuts - WAV file generation with --dump_wav integration - Format specification reference (doc/SEQUENCE.md) • tools/timeline_editor/ROADMAP.md - 3-phase development plan (117-161 hour estimate) - Phase 1.2: Add Effect button (next priority) - Phase 2.5: music.track visualization overlay Key Patterns: • Effect times stored RELATIVE to parent sequence startTime • Sequence visual bounds calculated from min/max effect times • Stack order determines priority (array index) • Snap-to-beat: Math.round(time / beatDuration) * beatDuration • Dynamic cumulative Y positioning prevents overlap • e.currentTarget vs e.target for proper event delegation ─────────────────────────────────────────────────────────────────── DOCUMENTATION UPDATES ─────────────────────────────────────────────────────────────────── TODO.md: • Added Task #57 to Recently Completed section • Comprehensive feature list and bug fix summary PROJECT_CONTEXT.md: • Added Milestone: Interactive Timeline Editor (February 5, 2026) • Documented integration with --dump_wav workflow • Next steps: Phase 1.2 and Phase 2.5 ─────────────────────────────────────────────────────────────────── NEXT STEPS ─────────────────────────────────────────────────────────────────── Phase 1.2: Add Effect Button (Priority: HIGH) - Create effects within sequences via UI - Modal dialog for effect class/timing/args Phase 2.5: Music.track Visualization (Priority: MEDIUM) - Parse music.track file format - Overlay tracker patterns/samples on timeline - Align visual sequences with audio events ─────────────────────────────────────────────────────────────────── IMPACT ─────────────────────────────────────────────────────────────────── ✨ Visual timeline editing now production-ready ✨ Eliminates manual text editing for sequence placement ✨ WAV waveform integration enables precise audio-visual alignment ✨ Snap-to-beat ensures musical timing accuracy ✨ Stack-order priority system simplifies effect layering ─────────────────────────────────────────────────────────────────── handoff(Claude): Timeline editor Phase 1 milestone complete. All core editing features working correctly. Waveform visualization integrated with --dump_wav workflow. Ready for Phase 1.2 (Add Effect button) or Phase 2 productivity enhancements (undo/redo, multi-select, templates). No known bugs. Production-ready for demo.seq editing workflow.
8 daysfeat(audio): Complete Task #56 - Audio Lifecycle Refactor (All Phases)skal
SUMMARY ======= Successfully completed comprehensive 4-phase refactor of audio subsystem to eliminate fragile initialization order dependency between synth and tracker. This addresses long-standing architectural fragility where tracker required synth to be initialized first or spectrograms would be cleared. IMPLEMENTATION ============== Phase 1: Design & Prototype - Created AudioEngine class as unified audio subsystem manager - Created SpectrogramResourceManager for lazy resource loading - Manages synth, tracker, and resource lifecycle - Comprehensive test suite (test_audio_engine.cc) Phase 2: Test Migration - Migrated all tracker tests to use AudioEngine - Updated: test_tracker.cc, test_tracker_timing.cc, test_variable_tempo.cc, test_wav_dump.cc - Pattern: Replace synth_init() + tracker_init() with engine.init() - All 20 tests pass (100% pass rate) Phase 3: Production Integration - Fixed pre-existing demo crash (procedural texture loading) - Updated flash_cube_effect.cc and hybrid_3d_effect.cc - Migrated main.cc to use AudioEngine - Replaced tracker_update() calls with engine.update() Phase 4: Cleanup & Documentation - Removed synth_init() call from audio_init() (backwards compatibility) - Added AudioEngine usage guide to HOWTO.md - Added audio initialization protocols to CONTRIBUTING.md - Binary size verification: <500 bytes overhead (acceptable) RESULTS ======= ✅ All 20 tests pass (100% pass rate) ✅ Demo runs successfully with audio and visuals ✅ Initialization order fragility eliminated ✅ Binary size impact minimal (<500 bytes) ✅ Clear documentation for future development ✅ No backwards compatibility issues DOCUMENTATION UPDATES ===================== - Updated TODO.md: Moved Task #56 to "Recently Completed" - Updated PROJECT_CONTEXT.md: Added AudioEngine milestone - Updated HOWTO.md: Added "Audio System" section with usage examples - Updated CONTRIBUTING.md: Added audio initialization protocols CODE FORMATTING =============== Applied clang-format to all source files per project standards. FILES CREATED ============= - src/audio/audio_engine.h (new) - src/audio/audio_engine.cc (new) - src/audio/spectrogram_resource_manager.h (new) - src/audio/spectrogram_resource_manager.cc (new) - src/tests/test_audio_engine.cc (new) KEY FILES MODIFIED ================== - src/main.cc (migrated to AudioEngine) - src/audio/audio.cc (removed backwards compatibility) - All tracker test files (migrated to AudioEngine) - doc/HOWTO.md (added usage guide) - doc/CONTRIBUTING.md (added protocols) - TODO.md (marked complete) - PROJECT_CONTEXT.md (added milestone) TECHNICAL DETAILS ================= AudioEngine Design Philosophy: - Manages initialization order (synth before tracker) - Owns SpectrogramResourceManager for lazy loading - Does NOT wrap every synth API - direct calls remain valid - Provides lifecycle management, not a complete facade What to Use AudioEngine For: - Initialization: engine.init() instead of separate init calls - Updates: engine.update(music_time) instead of tracker_update() - Cleanup: engine.shutdown() for proper teardown - Seeking: engine.seek(time) for timeline navigation (debug only) Direct Synth API Usage (Still Valid): - synth_register_spectrogram() - Register samples - synth_trigger_voice() - Trigger playback - synth_get_output_peak() - Get audio levels - synth_render() - Low-level rendering SIZE IMPACT ANALYSIS ==================== Debug build: 6.2MB Size-optimized build: 5.0MB Stripped build: 5.0MB AudioEngine overhead: <500 bytes (0.01% of total) BACKWARD COMPATIBILITY ====================== No breaking changes. Tests that need low-level control can still call synth_init() directly. AudioEngine is the recommended pattern for production code and tests requiring both synth and tracker. handoff(Claude): Task #56 COMPLETE - All 4 phases finished. Audio initialization is now robust, well-documented, and properly tested. The fragile initialization order dependency has been eliminated. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
8 daysdocs: Update roadmap with new tasks (OBJ, Font, Particles, Tracy)skal
8 daysfeat(physics): Implement SDF-based physics engine and BVHskal
Completed Task #49. - Implemented CPU-side SDF library (sphere, box, torus, plane). - Implemented Dynamic BVH construction (rebuilt every frame). - Implemented PhysicsSystem with semi-implicit Euler integration and collision resolution. - Added visual debugging for BVH nodes. - Created test_3d_physics interactive test and test_physics unit tests. - Updated project docs and triaged new tasks.
9 daysfeat: Audio playback stability, NOTE_ parsing fix, sample caching, and debug ↵skal
logging infrastructure MILESTONE: Audio System Robustness & Debugging Core Audio Backend Optimization: - Fixed stop-and-go audio glitches caused by timing mismatch - Core Audio optimized for 44.1kHz (10ms periods), but 32kHz expected ~13.78ms - Added allowNominalSampleRateChange=TRUE to force OS-level 32kHz native - Added performanceProfile=conservative for 4096-frame buffers (128ms) - Result: Stable ~128ms callbacks, <1ms jitter, zero underruns Ring Buffer Improvements: - Increased capacity from 200ms to 400ms for tempo scaling headroom - Added comprehensive bounds checking with abort() on violations - Fixed tempo-scaled buffer fill: dt * g_tempo_scale - Buffer maintains 400ms fullness during 2.0x acceleration NOTE_ Parsing Fix & Sample Caching: - Fixed is_note_name() checking only first letter (A-G) - ASSET_KICK_1 was misidentified as A0 (27.5 Hz) - Required "NOTE_" prefix to distinguish notes from assets - Updated music.track to use NOTE_E2, NOTE_G4 format - Discovered resource exhaustion: 14 unique samples → 228 registrations - Implemented comprehensive caching in tracker_init() - Assets: loaded once from AssetManager, cached synth_id - Generated notes: created once, stored in persistent pool - Result: MAX_SPECTROGRAMS 256 → 32 (88% memory reduction) Debug Logging Infrastructure: - Created src/util/debug.h with 7 category macros (AUDIO, RING_BUFFER, TRACKER, SYNTH, 3D, ASSETS, GPU) - Added DEMO_ENABLE_DEBUG_LOGS CMake option (defines DEBUG_LOG_ALL) - Converted all diagnostic code to use category macros - Default build: macros compile to ((void)0) for zero runtime cost - Debug build: comprehensive logging for troubleshooting - Updated CONTRIBUTING.md with pre-commit policy Resource Analysis Tool: - Enhanced tracker_compiler to report pool sizes and cache potential - Analysis: 152/228 spectrograms without caching, 14 with caching - Tool generates optimization recommendations during compilation Files Changed: - CMakeLists.txt: Add DEBUG_LOG option - src/util/debug.h: New debug logging header (7 categories) - src/audio/miniaudio_backend.cc: Use DEBUG_AUDIO/DEBUG_RING_BUFFER - src/audio/ring_buffer.cc: Use DEBUG_RING_BUFFER for underruns - src/audio/tracker.cc: Implement sample caching, use DEBUG_TRACKER - src/audio/synth.cc: Use DEBUG_SYNTH for validation - src/audio/synth.h: Update MAX_SPECTROGRAMS (256→32), document caching - tools/tracker_compiler.cc: Fix is_note_name(), add resource analysis - assets/music.track: Update to use NOTE_ prefix format - doc/CONTRIBUTING.md: Add debug logging pre-commit policy - PROJECT_CONTEXT.md: Document milestone - TODO.md: Mark tasks completed Verification: - Default build: No debug output, audio plays correctly - Debug build: Comprehensive logging, audio plays correctly - Caching working: 14 unique samples cached at init - All tests passing (17/17) handoff(Claude): Audio system now stable with robust diagnostic infrastructure. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
9 daysdocs: Update project state with event-based tracker and WAV dumpskal
Updated PROJECT_CONTEXT.md and TODO.md to reflect recent milestones: PROJECT_CONTEXT.md changes: - Updated Audio section: stereo format, variable tempo, event-based triggering - Added milestone for "Event-Based Tracker for Tempo Scaling" - Added milestone for "WAV Dump Backend for Debugging" - Updated Audio Engine architecture section with new details - Updated test counts (17/17 passing) TODO.md changes: - Added "Event-Based Tracker for Tempo Scaling" to Recently Completed * Refactored from pattern compositing to individual event triggering * Dynamic beat calculation enables notes to respect tempo scaling * ActivePattern tracking with start_music_time and next_event_idx * All 17 tests pass, WAV dump confirms correct behavior - Added "WAV Dump Backend for Debugging" to Recently Completed * WavDumpBackend for offline rendering to .wav files * Fixed critical stereo format bug (mono/stereo mismatch) * Added regression test with stereo format assertion * Command-line option: --dump_wav output.wav Current State: - All tests passing: 17/17 (100%) - Audio system: Stereo, variable tempo, event-based tracking - Documentation: Up to date with latest architecture Ready for handoff to Gemini. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
9 daysdocs: Milestone state snapshot - Audio system robustness completeskal
Documented completion of major audio system improvements: - Task #51: Tracker timing verification (0.000ms sync confirmed) - Variable tempo system (6 tests, all passing) - Zero production size impact (all test code under !STRIP_ALL) Key achievements: - Perfect audio synchronization verified - Dynamic tempo control ready (music_time abstraction) - Comprehensive test coverage (16/16 tests passing) - Mathematical precision verified for reset tricks Updated: - PROJECT_CONTEXT.md: Added milestone section - HANDOFF_2026-02-04.md: Complete state snapshot for handoff System ready for: - Dynamic tempo animation - Physics & collision (Task #49) - 3D scene pipeline (Task #18) handoff(Claude): Audio milestone complete, state saved Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
9 daysdocs: Update project context and state for handoffskal
10 daystest(coverage): Improve Audio coverage (Task #48)skal
Added unit tests for DCT and procedural audio generation. Enhanced synth tests to cover rendering and resource management. Audio subsystem coverage increased to 93%.
10 daystest(coverage): Improve Asset Manager coverage (Task #47)skal
Added tests for runtime error handling in Asset Manager (unknown function, generation failure). Updated asset_packer to warn instead of fail on unknown functions to facilitate testing. Increased coverage from 71% to 88%.
10 daysfeat(tooling): Add directory filtering to coverage report script (Task #46)skal
Updated gen_coverage_report.sh to accept an optional argument for targeting specific directories using lcov --extract.
10 daystest(procedural): Improve test coverage (Task #45)skal
Added tests for gen_perlin and make_periodic. Improved parameter handling checks. Coverage for src/procedural/generator.cc increased to 96%.
10 daysfeat(tooling): Implement code coverage reporting (Task #44)skal
Added CMake support for coverage builds and a script to generate HTML reports using lcov on macOS. Also cleaned up .gitignore.
10 dayshandoff(Claude): Stabilize 3D renderer with rotating skybox and two-pass ↵skal
architecture - Fixed black screen by ensuring clear operations in Pass 2 when Skybox pass is skipped. - Resolved WebGPU validation errors by synchronizing depth-stencil state. - Implemented rotating skybox using world-space ray unprojection (inv_view_proj). - Improved procedural noise generation (multi-octave Value Noise). - Restored scene integrity by correcting object indexing and removing artifacts. - Updated documentation (TODO.md, PROJECT_CONTEXT.md).
generated by cgit v1.2.3 (git 2.51.0) at 2026-02-13 22:01:26 +0000