docs: Prioritize next session tasks and update project context

- Consolidated recent 3D and High-DPI fixes into PROJECT_CONTEXT.md.
- Generated a prioritized task list in TODO.md with detailed attack plans.
- Moved completed tasks to the 'Recently Completed' section.
- Set up roadmap for Task #8 (Stripping), Task #20 (Code Hygiene), and Task #21 (Shader Optimization).

1 files changed, 27 insertions, 64 deletions

diff --git a/TODO.md b/TODO.md
index 5e77d74..a6f3d37 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,72 +1,35 @@
 # To-Do List
 
-This file tracks the next set of immediate, actionable tasks for the project.
+This file tracks prioritized tasks with detailed attack plans.
 
-## Next Up
+## Priority 1: Final Build Stripping (Task #8)
+**Goal:** Reduce binary size by removing all non-essential code under the `STRIP_ALL` macro.
+- [ ] **Attack Plan - Rules:** Document stripping rules in `doc/STRIPPING.md`.
+- [ ] **Attack Plan - Error Strings:** Wrap all non-critical `printf`, `std::cerr`, and error strings in `STRIP_ALL`.
+- [ ] **Attack Plan - CLI Parsing:** Disable all non-essential CLI arguments (seek, resolution, debug) in `STRIP_ALL`.
+- [ ] **Attack Plan - Struct Hygiene:** Remove debug-only fields (like `label` or `name`) from core structs.
 
--   **Task #8: Implement Final Build Stripping**
-    - [ ] Define and document a consistent set of rules for code stripping under the `STRIP_ALL` macro.
-    - [ ] Example sub-tasks: remove unused functions, strip debug fields from structs, simplify code paths where possible.
-
--   **Task #19: Update README.md with Quick Start**
-    - [ ] Add a top-level "Quick Start" section to `README.md` with brief build and run instructions for `demo64k`.
-
--   ** Task #?: scripts/build_win.sh is always copying MinGW DLLs file ("Copy MinGW DLLs"). Add a check on date or file size to prevent useless systematic copy.
-
--   ** Task #?: Code hygiene
-    - [ ] make a pass on the code and make sure all useless code is protected by STRIP_ALL #ifdef's
-    - [ ] analyze the #include and check if some standard header inclusion could be removed (<algorithm>, etc.)
-    - [ ] see if all usage of std structs, container, etc. are appropriate:
-           == is this std::map<> needed?
-           == could we remove this std::set<>?
-           == Can this std::vector<T> be replaced by a simple C-like "const T*" array?
-           == are these std::string needed or can they be replaced by some 'const char*' ?
-           == do we need these std::cout, std::cerr, etc. instead of printf()'s?
-           == etc.
-    - [ ] the inclusion of gpu.h (either "gpu.h" or <webgpu/gpu.h>) seems to be a recurring compilation and portability issue. Can we have a single inclusion of gpu.h in some platform header instead of scattered inclusion in .cc files? This would reduce the single-point-of-compilation failures during compilation and portability checks.
-
--   ** Task #?: platform-specific code hygiene
-    There's several platform-specific code scattered over several source files (.cc and .h)
-    For instance:
-```cpp
-#if defined(DEMO_CROSS_COMPILE_WIN32)
-#include <webgpu/webgpu.h>
-#else
-#include <webgpu.h>
-#endif /* defined(DEMO_CROSS_COMPILE_WIN32) */
-```
-    This sort of code should be gathered at once single place (platform.h?) once for all.
-    - [ ] => Make all cross-compile and platform-specific conditional code sit in one single header file.
-
--   ** Task #?: platform_init() should return a PlatformState directly instead of taking a PlatformState& parameter to write into
-    - [ ] maybe incorporate the platform time (platform_get_time()) into the PlatformState directly during platform_poll() call?
-    - [ ] same with aspect_ratio (platform_get_aspect_ratio()) unless it's not an invariant and the function needs to be called each time
-
--   ** Task #?: shader code factorization with macros
-    The shader code is rapidly growing big and hairy. We can probably use macros to factorize most common code (normal calc? bump mapping? sampling?) to reduce the code boilerplate.
-
--   ** Task #?: the SDF calculation should be passed min-distance and max-distance parameters derived from the bounding box hit. This is to narrow the ray-marching and reduce the number of iterations if possible.
+## Priority 2: Platform & Code Hygiene (Task #20)
+**Goal:** Clean up the codebase for easier cross-platform maintenance and CRT replacement.
+- [ ] **Attack Plan - Header Consolidation:** Move all `#ifdef` logic for WebGPU headers and platform-specific shims into `src/platform.h`.
+- [ ] **Attack Plan - Refactor platform_init:** Change `void platform_init(PlatformState* state, ...)` to `PlatformState platform_init(...)`.
+- [ ] **Attack Plan - Unified Poll:** Incorporate `platform_get_time()` and `platform_get_aspect_ratio()` updates into `platform_poll()`.
+- [ ] **Attack Plan - Standard Container Removal:** Replace `std::map`, `std::string`, and `std::vector` in performance-critical or size-sensitive paths with simpler C-style alternatives.
 
+## Priority 3: Shader Optimization (Task #21)
+**Goal:** Improve GPU performance and reduce shader source bloat.
+- [ ] **Attack Plan - Normal Factorization:** Create a standard WGSL helper for normal calculation to avoid duplicate code in every effect.
+- [ ] **Attack Plan - Ray Bounds:** Derive `t_min` and `t_max` for ray-marching from the proxy hull entry/exit points to minimize iterations.
+- [ ] **Attack Plan - SDF Macros:** Use `#define` macros in WGSL to simplify sampling and bump mapping logic.
 
 ## Future Goals
+- [ ] **Task #5: Spectrogram Editor**: Web-based visual tool for extreme audio compression.
+- [ ] **Task #18: 3D System Enhancements**: Blender exporter and GPU-based BVH for complex scenes.
+- [ ] **Task #22: Windows Native Platform**: Replace GLFW with direct Win32 API calls for the final 64k push.
 
--   **Task #5: Implement Spectrogram Editor**
-    - [ ] Develop a web-based tool (`tools/editor`) for creating and editing `.spec` files visually.
-    - [ ] The tool should support generating `.spec` files from elementary shapes (lines, curves) for extreme compression.
--   **Phase 2: Advanced Size Optimization**
-    - [ ] Replace GLFW with a minimal native Windows API layer.
-    - [ ] Investigate and implement advanced asset compression techniques (e.g., logarithmic frequency, quantization).
-    - [ ] Explore replacing the standard C/C++ runtime with a more lightweight alternative.
-
-## Past Tasks
-
--   Centralize generated files into `src/generated`.
--   Vertically compact C++ source code.
--   Create top-level `README.md`.
--   Move non-essential documentation to `doc/`.
--   **Bug Fixes:** 
-    - Resolved high-DPI "squished" rendering by implementing dynamic resolution uniforms and explicit viewport settings.
-    - Fixed missing 3D shadows by unifying all objects (including the floor) under the SDF raymarching path, using 'inv_model' for accurate world-to-local transformations, and implementing robust instance-based self-shadowing prevention.
--   **Code Hygiene:** Completed a project-wide code formatting pass with `clang-format`.
--   **Task #4b:** Create `scripts/check_all.sh` to build and test all platform targets (macOS, Windows, Linux) to ensure stability before commits.
--   **Task #10:** Modify `spectool` to trim leading and trailing silent frames from `.spec` files to reduce asset size.
\ No newline at end of file
+## Recently Completed
+- [x] **High-DPI Fix**: Resolved viewport "squishing" via dynamic resolution uniforms and explicit viewports.
+- [x] **Unified 3D Shadows**: Implemented robust SDF shadows across all objects using `inv_model` transforms.
+- [x] **Tight Proxy Hulls**: Optimized Torus proxy geometry and debug wireframes.
+- [x] **Procedural Textures**: Restored floor grid and SDF bump mapping.
+- [x] **Code Hygiene**: Completed a project-wide code formatting pass with `clang-format`.