Refactor/modules

ARCHITECTURE.md

@@ -8,12 +8,41 @@ The scene engine is deliberately split into small stages so Wallpaper Engine's
 original OpenGL pass model can be rebuilt incrementally in Rust, and so each
 stage can be inspected on its own when a wallpaper renders wrongly.
 
+## Source layout
+
+```text
+src/
+  main.rs, cli/        the wp-engine binary and its commands, one file per area
+  bin/                 the scan-wallpapers tool
+  workshop/            finding Workshop items; project.json and user properties
+  formats/             .pkg archives, .tex textures, the asset store
+  engine/              the scene engine
+    model/             what a scene is: scene.json types, resolving into layers
+    sim/               what changes: particles, timelines, SceneScript, cameras, puppets
+    gpu/               how it's drawn: the renderer, targets, lighting, shadows, shaders
+    cpu/               the CPU fallback renderer
+  content/             wallpaper content (scene/video/web/image), frame sources,
+                       render settings, the per-output session the backends share
+  services/            what wallpapers react to: audio, media, battery/lock, pause rules
+  platform/            presentation: wayland/, x11/, macos/, GPU device, scaler
+  daemon/, application/, settings.rs, schedule.rs   lifecycle and saved setup
+  ui/                  the desktop app, one file per part of the window
+```
+
+Large modules are folders whose `mod.rs` holds the types and says where the
+rest lives — for example `engine/gpu/renderer/` splits into `pipelines`,
+`build`, `live`, `draw`, `lights` and `params`, and `engine/sim/particle/`
+into `config`, `build`, `step`, `operators` and `draw`. Tests sit beside
+them in `tests.rs`.
+
+## Pipeline
+
 ### 1. Workshop Content Detection
 
 The app starts from either a Steam Workshop item or a direct file path.
 
 - `src/workshop` scans Wallpaper Engine Workshop projects.
-- `src/render/content.rs` classifies content as static image, video, scene, or
+- `src/content/wallpaper.rs` classifies content as static image, video, scene, or
   web.
 - Static, video, and web wallpapers flow through the frame-source path.
 - Scene wallpapers are handed to the engine pipeline below.
@@ -22,7 +51,7 @@ The app starts from either a Steam Workshop item or a direct file path.
 
 Scene assets can exist as loose files or packed archives.
 
-- `src/engine/assets.rs` mounts the wallpaper directory.
+- `src/formats/assets.rs` mounts the wallpaper directory.
 - Loose files are preferred.
 - `scene.pkg` and `gifscene.pkg` are loaded as fallbacks.
 - Asset paths are normalized to Wallpaper Engine's forward-slash layout.
@@ -36,7 +65,7 @@ lookup layer.
 
 The engine reads `scene.json` into loose, tolerant Rust structs.
 
-- `src/engine/scene.rs` parses objects, camera data, effects, visibility,
+- `src/engine/model/scene.rs` parses objects, camera data, effects, visibility,
   origins, sizes, parallax, and texture overrides.
 - Fields that vary between Wallpaper Engine versions are kept as
   `serde_json::Value` until a later stage knows how to interpret them.
@@ -48,7 +77,7 @@ slightly different schema.
 
 The scene graph resolves object references into typed engine data.
 
-- `src/engine/material.rs` loads model JSON files.
+- `src/engine/cpu/material.rs` loads model JSON files for the CPU path.
 - Models point at material JSON files.
 - Materials contain passes, shaders, texture bindings, combos, constants,
   blending, culling, and depth flags.
@@ -69,7 +98,7 @@ scene object
 
 ### 5. Scene Graph
 
-`src/engine/graph.rs` builds a resolved scene graph.
+`src/engine/cpu/graph.rs` builds a resolved scene graph.
 
 For each visible object it records:
 
@@ -87,7 +116,7 @@ rendering.
 
 ### 6. Shader Translation Layer
 
-`src/engine/shaders/transpiler.rs` turns Wallpaper Engine's GLSL into WGSL:
+`src/engine/gpu/shaders/transpiler/` turns Wallpaper Engine's GLSL into WGSL:
 resolve `shaders/<name>.vert|frag`, expand includes and combo `#define`s,
 compile to SPIR-V with shaderc, then translate to WGSL with Naga.
 
@@ -104,7 +133,7 @@ compile — shaderc's line numbers refer to that text and nothing else prints it
 
 ### 7. GPU Scene Renderer
 
-`src/engine/gpu_renderer.rs` is the production renderer — `GpuSceneInstance` and
+`src/engine/gpu/renderer/` is the production renderer — `GpuSceneInstance` and
 `gpu_scene_render_loop`, used by `set`, `set-file`, and `test-scene`.
 
 It owns the full pass model: per-object composite buffers, ping-pong FBOs,
@@ -119,7 +148,7 @@ only way to inspect the live path off-screen.
 
 ### 8. Web Wallpapers
 
-`src/render/web.rs` renders HTML wallpapers with an embedded Chromium through
+`src/content/web.rs` renders HTML wallpapers with an embedded Chromium through
 CEF, off-screen: each painted frame becomes an `RgbaImage` on the same channel
 video and CPU scene rendering use, so every presentation path works unchanged.
 
@@ -130,7 +159,8 @@ bands. Behind the off-by-default `web` feature; see **Building**.
 
 ### 9. CPU Fallback Renderer
 
-`src/engine/render.rs` keeps the older CPU compositor alive.
+`ResolvedScene::render` (`src/engine/model/resolve/`) keeps the older CPU
+compositor alive, with its frame loop and scene graph in `src/engine/cpu/`.
 
 It:
 
@@ -161,33 +191,37 @@ handle; if that fails (or `WP_ENGINE_FORCE_SHM` is set) it falls back to RGBA
 readback + SHM buffers. The same module feeds the real cursor position into
 camera parallax and `g_PointerPosition`.
 
-On **X11**, `src/platform/x11` draws into the root window's background pixmap
-and publishes `_XROOTPMAP_ID`/`ESETROOT_PMAP_ID`, the convention every WM and
-compositor honours (it is what `feh --bg` sets). There is no direct-presentation
-equivalent, so every frame is read back and pushed with `PutImage`. X11 gets
+On **X11**, `src/platform/x11` draws each frame into a root-sized pixmap and
+publishes it as the root background (`_XROOTPMAP_ID`/`ESETROOT_PMAP_ID`, what
+`feh --bg` sets). Desktop environments cover the root with their own desktop, so
+when the window manager supports EWMH desktop windows the same pixmap also backs
+a click-through `_NET_WM_WINDOW_TYPE_DESKTOP` window of ours. Frames are read
+back and pushed with `PutImage`; there is no direct-presentation path yet. X11 gets
 better parallax for free: `QueryPointer` reports the global cursor regardless of
 which window has focus.
 
 Both the X11 and Wayland backends also implement the real Wallpaper Engine's
-own "pause wallpaper rendering when..." settings (`engine::playback_gate` —
+own "pause wallpaper rendering when..." settings (`services::playback_gate` —
 recovered from the Ghidra dump's import table, not the usual property scan;
 see the report's Follow-up (ff)): on battery power, when the session is
 locked, and when another application is fullscreen or maximized (X11 via
 EWMH's `_NET_ACTIVE_WINDOW`/`_NET_WM_STATE`; Wayland via
 `zwlr_foreign_toplevel_management`, so it only works on compositors that
 support that wlroots-ecosystem protocol — Sway/Hyprland/river, not
 GNOME/Mutter). Session-lock detection is Linux-only (logind over D-Bus, via
-`platform::power::LockWatcher`). Each condition defaults per
-`engine::playback_gate::PauseConditions::default`'s own doc comment (WE's
+`services::power::LockWatcher`). Each condition defaults per
+`services::playback_gate::PlaybackPolicy::default`'s own doc comment (WE's
 real defaults for these aren't recoverable from the binary) and is
 overridable with `WP_ENGINE_PAUSE_ON_BATTERY`/`_LOCK`/`_FULLSCREEN`/
 `_MAXIMIZED=0`/`1`. macOS currently has none of this wired in (see
-`platform::macos`'s own "step 2 of the port" status note) — `platform::
+`platform::macos`'s own "step 2 of the port" status note) — `services::
 power::is_on_battery` already works there (via `pmset`) for whenever that
 backend's render loop is built out far enough to use it.
 
-Static images, videos, and web wallpapers flow through `src/render/frame.rs`
-frame sources.
+Static images, videos, and web wallpapers flow through `src/content/frame.rs`
+frame sources. What every output does whichever backend shows it — building its
+renderer, live property edits, the pause rules — lives once in
+`src/content/session.rs`.
 
 ### 11. Application Lifecycle
 
@@ -210,15 +244,15 @@ rather than stack. The GUI forwards live quality/volume changes the same way.
 
 ### 12. User Properties
 
-`src/engine/properties.rs` loads `project.json` `general.properties`,
+`src/workshop/properties.rs` loads `project.json` `general.properties`,
 applies `--set-property NAME=VALUE` overrides, and rewrites `{"user": ...}`
 references inside `scene.json` before parsing — the Rust counterpart of the
 reference `PropertyParser`/`UserSettingParser`. `wp-engine list-properties
 <id>` lists what a wallpaper exposes.
 
 ### 13. Camera Dynamics
 
-`src/engine/camera_dynamics.rs` implements scene-level `camerashake`,
+`src/engine/sim/camera_dynamics.rs` implements scene-level `camerashake`,
 `camerafade`, and `cameraparallax` from the resolved general settings. Shake
 and per-layer parallax feed the composite pass as UV offsets; fade drives
 global scene opacity.

Cargo.toml

@@ -13,7 +13,7 @@ path = "src/main.rs"
 
 [[bin]]
 name = "scan-wallpapers"
-path = "src/tests/scan_wallpapers.rs"
+path = "src/bin/scan_wallpapers.rs"
 
 [features]
 default = []

src/application/application_context.rs

@@ -2,7 +2,7 @@ use std::collections::HashMap;
 use std::path::PathBuf;
 use std::sync::{Arc, Mutex};
 
-use crate::render::RenderSettings;
+use crate::content::RenderSettings;
 
 /// Runtime configuration for a wallpaper run (the Rust counterpart of the C++
 /// `ApplicationContext`). Built from the CLI by `main.rs` and consumed by
@@ -36,7 +36,7 @@ pub struct ApplicationContext {
 impl ApplicationContext {
     pub fn new(background: PathBuf) -> Self {
         let saved = crate::settings::WpSettings::load();
-        let fps = saved.fps.unwrap_or(crate::render::settings::DEFAULT_FPS);
+        let fps = saved.fps.unwrap_or(crate::content::settings::DEFAULT_FPS);
         let scaling = saved.scaling.unwrap_or_default();
         Self {
             background,
@@ -83,7 +83,7 @@ impl ApplicationContext {
         S: AsRef<str>,
     {
         for arg in args {
-            let (name, value) = crate::engine::properties::parse_property_arg(arg.as_ref());
+            let (name, value) = crate::workshop::properties::parse_property_arg(arg.as_ref());
             self.properties.insert(name, value);
         }
     }

src/application/mod.rs

@@ -12,8 +12,8 @@ use std::time::Duration;
 
 use anyhow::{Context, Result};
 
+use crate::content::{ScreenContent, ScreenSettings, WallpaperContent};
 use crate::platform::{self, WallpaperHandle};
-use crate::render::{ScreenContent, ScreenSettings, WallpaperContent};
 
 pub mod application_context;
 pub use application_context::ApplicationContext;
@@ -37,7 +37,7 @@ impl WallpaperApplication {
     /// Prepare the application: installs the context's property overrides so
     /// every scene loaded afterwards resolves user settings against them.
     pub fn new(context: ApplicationContext) -> Self {
-        crate::engine::properties::set_overrides_for(
+        crate::workshop::properties::set_overrides_for(
             &context.background,
             context.properties.clone(),
         );

src/tests/scan_wallpapers.rs → src/bin/scan_wallpapers.rs

@@ -272,7 +272,8 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     results.sort_by(|a, b| a.id.cmp(&b.id));
 
     // ── Write errors.txt ──────────────────────────────────────────────────────
-    let out_path = "src/tests/errors.txt";
+    // Generated output: target/ is already ignored and always exists after a build.
+    let out_path = "target/scan-wallpapers-errors.txt";
     let mut out = fs::File::create(out_path)?;
 
     for r in &results {