docs(architecture): Add custom shaders and window frame architecture document

docs/guide_shaders_and_window.md

@@ -0,0 +1,33 @@
+# Custom Shaders and Window Frame Architecture
+
+## 1. Shader Injection Strategy
+
+### Evaluation
+*   **Dear PyGui (Legacy):** Does not natively support raw GLSL/HLSL shader injection into the UI layer. It relies heavily on fixed-function vertex/fragment shaders compiled into the C++ core. Faux-shaders via DrawList are the only viable path without modifying the DPG source.
+*   **imgui-bundle (Current):** `imgui-bundle` utilizes `hello_imgui` as its application runner, which provides robust lifecycle callbacks (e.g., `callbacks.custom_background`, `callbacks.post_init`). Because `hello_imgui` exposes the underlying OpenGL context, we can use `PyOpenGL` alongside it to execute raw GLSL shaders.
+
+### Chosen Approach: Hybrid Faux-Shader & PyOpenGL FBO
+Given the Python environment, we will adopt a hybrid approach:
+1.  **Faux-Shaders (ImDrawList Batching):** Continue using `imgui.ImDrawList` primitives for simple effects like soft shadows, glows, and basic gradients (as seen in `src/shaders.py`). This is highly performant for UI elements and requires no external dependencies.
+2.  **True GPU Shaders (PyOpenGL + FBO):** For complex post-processing (CRT curvature, bloom, dynamic noise backgrounds), we will integrate `PyOpenGL`. 
+    *   We will compile GLSL shaders during `post_init`.
+    *   We will render the effect into a Framebuffer Object (FBO).
+    *   We will display the resulting texture ID using `imgui.image()` or inject it into the `custom_background` callback.
+
+*Note: This approach introduces `PyOpenGL` as a dependency, which is standard for advanced Python graphics.*
+
+## 2. Custom Window Frame Strategy
+
+### Evaluation
+*   **Native DWM Overloading (PyWin32):** It is possible to use `pywin32` to subclass the application window, intercept `WM_NCHITTEST`, and return `HTCAPTION` for a custom ImGui-drawn title bar region. This preserves Windows snap layouts and native drop shadows. However, it is strictly Windows-only and can conflict with GLFW/SDL2 event loops used by `hello_imgui`.
+*   **Borderless Window Mode (ImGui/GLFW):** `hello_imgui` allows configuring the main window as borderless/undecorated (`runner_params.app_window_params.borderless = True`). We must then manually draw the title bar, minimize/maximize/close buttons, and handle window dragging by updating the OS window position based on ImGui mouse drag deltas.
+
+### Chosen Approach: Pure ImGui Borderless Implementation
+To ensure cross-platform compatibility and avoid brittle Win32 hook collisions with `hello_imgui`, we will use the **Borderless Window Mode** approach.
+1.  **Initialization:** Configure `hello_imgui.RunnerParams` to disable OS window decorations.
+2.  **Title Bar Rendering:** Dedicate the top ~30 pixels of the ImGui workspace to a custom title bar that matches the current theme (e.g., NERV or standard).
+3.  **Window Controls:** Implement custom ImGui buttons for `_`, `[]`, and `X`, which will call native window management functions exposed by `hello_imgui` or `glfw`.
+4.  **Drag Handling:** Detect `imgui.is_mouse_dragging()` on the title bar region and dynamically adjust the application window position.
+
+## 3. Integration with Event Metrics
+Both the shader uniforms (time, resolution) and window control events will be hooked into the existing `dag_engine` and `events` systems to ensure minimal performance overhead and centralized configuration via `config.toml`.