docs: Refactor and prioritize project task lists

- Restructured PROJECT_CONTEXT.md to introduce a clear roadmap with 'Next Up', 'In Progress', and 'Future Goals'.
- Condensed the 'Session Decisions' section into a concise 'Architectural Overview' focusing on the current state.
- Updated TODO.md to reflect the highest priority tasks: finalizing the build system and optimizing spectrogram assets.

2 files changed, 62 insertions, 86 deletions

diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md
index 2d3e21d..ca8a858 100644
--- a/PROJECT_CONTEXT.md
+++ b/PROJECT_CONTEXT.md
@@ -23,65 +23,58 @@ Style:
 - Demoscene
 - No engine abstractions
 
-Incoming tasks in no particular order:
-- [x] 1. add a fullscreen mode (as command line option)
-- [x] 2. parse the keyboard key. Exit the demo when 'esc' is pressed. Toggle full-screen when 'f' is pressed.
-- [x] 3. add binary crunchers for all platforms
-- [ ] 4. add cross-compilation for PC+linux (x86_64) and PC+Windows (.exe binary)
-    - [x] a. PC+Windows (.exe binary) via MinGW
-    - [ ] b. PC+linux (x86_64)
-    - [ ] c. have a shell script (check_all.sh) under scripts/ to verify all builds (PC, MacOS, Win64) for all config. To be run before a major commit. Script can be slow to pass, doesn't matter.
-- 5. implement a spectrogram editor for representing .spec with elementary shapes (bezier curves, lines, random noise, rectangles...) as a mean of compression / spec generation
-- [x] 6. add a scripting tool to edit the demo (compiled into the binary at the end)
-- [x] 7. compile wgpu-native in optimized mode (not unoptimized)
-- [x] 8. add a #define STRIP_ALL to remove all unnecessary code for the final build (for instance, command-line args parsing, or unnecessary options, constant parameters to function calls, etc.)
-    Sub-tasks to define an overall code-stripping rule (to be captured in the CONTRIBUTING.md rules):
-    - [ ] a. function implementations are removed
-    - [ ] b. useless struct fields are removed (is_fullscreen_, debug_mode_, etc. e.g.)
-    - [ ] c. static arrays are malloc'd instead of initialized to zero
-    - [ ] d. code is simplified for size if possible (propose an alternate code implementation inside a STRIP_ALL #ifdef if needed)
-- [x] 9. work on the compact in-line and off-line asset system (@ASSET_SYSTEM.md)
-- 10. optimize spectool to remove trailing zeroes from a spec file before saving it. Remove the leading zeroes too.
-- [x] 11. implement a general [time / timer / beat] system in the demo, for effects timing
-- [x] 12. Implement 'Sequence' and 'Effect' system:
-    - `Effect` interface: `init`, `start`, `compute`, `render`, `end`, `priority`.
-    - `Sequence` manager: Handles a list of temporally sorted `SequenceItem`s.
-    - `MainSequence`: Manages global resources (`device`, `queue`) and orchestrates the frame render.
-    - Refactored `gpu.cc` to use `MainSequence`.
-    - Moved concrete effects to `src/gpu/demo_effects.cc`.
-- 13. Implement Procedural Texture system (Task #3 -> #1):
-    - `src/procedural/` module (Done).
-    - Integration with WebGPU: Generate textures at runtime and upload to GPU (Done).
-    - `src/gpu/texture_manager` implemented and tested.
-- 14. Implement 3D system (Task #1 -> #2):
-    - `src/3d/` module (math, camera, scene, renderer) (Done).
-    - `Renderer3D` implemented with basic cube rendering (Done).
-    - `test_3d_render` mini-demo created (Debugging crash in `wgpuInstanceWaitAny`).
-- 15. Shader Logic (Task #2 -> #3):
-    - Ray-object intersection & SDF rendering in WGSL (Done).
-    - SDF Box, Sphere, Torus implemented.
-    - Hybrid normal calculation (Analytical + Numerical) (Done).
-    - Bump mapping with procedural noise (Done).
-    - Periodic texture generation (Done).
-- [x] 16. Integrate 3D Renderer into Main Demo:
-    - Update `main.cc` / `gpu.cc` to use `Renderer3D`.
-    - Apply Gaussian Blur and Chromatic Aberration post-processing.
+---
+## Project Roadmap
 
-*   **[x] 17. Implement Asset Manager Caching & Procedural Generation**
-    *   17a. **(Task a)** Implemented array-based caching in `asset_manager.cc` for `GetAsset` (Done).
-    *   17b. **(Task b)** Modify `asset_packer` to parse a new `PROC(function_name)` compression method. This will generate a record mapping an Asset ID to the procedural function's name.
-    *   17c. **(Task b)** Implement a runtime dispatcher in `GetAsset`. When a `PROC` asset is requested, the dispatcher will look up the function by its name and execute it. The result will then be cached.
-    *   17d. **(Task c)** Update the asset management test suite to include a test case with `PROC(function_name)` in `test_assets_list.txt` to verify the generation and caching.
-    *   17e. **(Task d)** Integrate into `demo64k` by adding a procedural noise texture to `demo_assets.txt` and using this new mechanism in the `Hybrid3DEffect` for bump mapping.
+### Next Up
+- **Task #4: Finalize Build System**
+    - [ ] 4a. Implement Linux cross-compilation from macOS.
+    - [ ] 4b. Create `scripts/check_all.sh` to build and test all platform targets (macOS, Windows, Linux) to ensure stability before commits.
+- **Task #10: Optimize Spectrogram Assets**
+    - [ ] Modify `spectool` to trim leading and trailing silent frames from `.spec` files to reduce asset size.
 
-## Session Decisions and Current State
+### In Progress
+- **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.
+
+### Future Goals
+- **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.
+
+---
+*For a list of completed tasks, see the git history.*
+
+## Architectural Overview
+
+### Sequence & Effect System
+- **Core Idea**: The demo is orchestrated by a powerful sequence and effect system.
+- **`Effect`**: An abstract base class for any visual element (e.g., 3D scene, post-processing). Effects are managed within a timeline.
+- **`Sequence`**: A timeline that manages the start and end times of multiple `Effect`s.
+- **`MainSequence`**: The top-level manager that holds core WebGPU resources and renders the active `Sequence`s for each frame.
+- **`seq_compiler`**: A custom tool that transpiles a simple text file (`assets/demo.seq`) into a C++ timeline (`timeline.cc`), allowing for rapid iteration on the demo's choreography without recompiling the engine.
+
+### Asset & Build System
+- **`asset_packer`**: A tool that packs binary assets (like `.spec` files) into C++ arrays.
+- **Runtime Manager**: A highly efficient, array-based lookup system (`GetAsset`) provides O(1) access to all packed assets.
+- **Procedural Assets**: The system supports `PROC(function, params...)` syntax in asset lists, enabling runtime generation of assets like noise textures. The `asset_packer` stores the function name, and a runtime dispatcher executes the corresponding C++ function.
+- **Automation**: The entire build, asset generation, and packaging process is automated via CMake and helper scripts (`gen_assets.sh`, `build_win.sh`).
+
+### Audio Engine
+- **Real-time Synthesis**: The engine uses an additive synthesizer that generates audio in real-time from spectrograms (`.spec` files) via an Inverse Discrete Cosine Transform (IDCT).
+- **Dynamic Updates**: Employs a thread-safe double-buffer mechanism to allow spectrogram data to be modified live for dynamic and evolving soundscapes.
+- **Procedural Generation**: Includes a library for generating note spectrograms at runtime, complete with spectral filters for effects like noise and phasing.
+
+### Platform & Windowing
+- **Stateless Refactor**: The entire platform layer (`platform.h`, `platform.cc`) is stateless. All window and input state is encapsulated in a `PlatformState` struct, which is passed to all platform functions.
+- **High-DPI Aware**: The platform layer correctly queries framebuffer dimensions in pixels, resolving rendering issues on high-DPI (Retina) displays.
+- **Cross-Platform Surface**: Uses `glfw3webgpu` to create a WebGPU-compatible surface on Windows, macOS, and Linux.
 
-### 3D Renderer Implementation
-- **Renderer3D**: Encapsulates pipeline creation and render pass recording.
-- **Shader**: Currently uses a simple vertex/fragment shader for cubes.
-- **Storage**: Objects are stored in a `StorageBuffer` (instance data).
-- **Test Tool**: `test_3d_render` created to isolate 3D development.
-- **Issue**: `test_3d_render` crashes with "not implemented" in `wgpuInstanceWaitAny` on macOS.
 
 ### Procedural Textures
 - **TextureManager**: Handles CPU generation -> GPU upload.
diff --git a/TODO.md b/TODO.md
index e0e6b14..414ff0f 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,35 +1,18 @@
-# list of quick TODO tasks
+# To-Do List
 
-this is temporary, frequently-updated, list of quick TODO that
-don't warrant a 'Task' in itself.
-Once done, move the task description to the 'Past Tasks' section
+This file tracks the next set of immediate, actionable tasks for the project.
 
+## Next Up
 
-## Up-to-date Tasks list
+-   **Task #4: Finalize Build System**
+    -   [ ] Implement Linux cross-compilation from macOS.
+    -   [ ] Create `scripts/check_all.sh` to build and test all platform targets (macOS, Windows, Linux) to ensure stability before commits.
+-   **Task #10: Optimize Spectrogram Assets**
+    -   [ ] Modify `spectool` to trim leading and trailing silent frames from `.spec` files to reduce asset size.
 
-In no particular order, they just need to be done:
-
-  * A) each build_XXX build directory is generating its own build_XXX/src/generated/* assets and code.
-       This is wrong and error-prone. There should be one source of truth
-       for the generated assets/data/code at the top of the tree, under a common
-       src/generated/ directory. Adapt all the code for that. Pay attention
-       to tests (test_assets, e.g.) that *also* generate assets. They must§
-       generate them in a throw-away directory.
-
-  * B) make a pass of 'vertical compaction' for the code: there's a lot of
-       superfluous '\n' empty lines in the code that shouldn't be here.
-       Remove them to have a vertically more dense code. Use clang-format if needed.
-
-  * C) add a top-level @README.md file with a short description of the
-       project for new-comers, a one-line description of each .md files, and
-       a quick layout and description of the source tree.
-
-  * D) move all the non-essential .md files to a top-level doc/ directory
-       (or any other more appropriate name) to remove the top-level file
-       clutter. Keep ony the essential ones at top level. Update the git
-       repo accordingly.
-
-## Past Tasks
-
-The past TODO are already done (stored here for archiving):
+## Completed
 
+-   Centralize generated files into `src/generated`.
+-   Vertically compact C++ source code.
+-   Create top-level `README.md`.
+-   Move non-essential documentation to `doc/`.
\ No newline at end of file