réorg doc

docs/user/README.md

@@ -27,7 +27,7 @@ GPU graphics background is required.
 | [DoF (depth of field)](dof.md) | Cinematic bokeh blur, focus plane, opt-in via `with_dof()` |
 | [GPU-driven rendering](gpu-driven.md) | GPU world matrices + indirect draws, opt-in frustum culling |
 | [Camera & input](camera-input.md) | Active camera, orbital controller, unified keyboard/mouse state |
-| [Examples](examples.md) | The 7 repo examples, the advanced `manual` workflow, adding your own example |
+| [Examples](examples.md) | The 16 repo examples in 4 folders (`meshes/`, `lights/`, `cameras/`, `effects/`), the advanced `manual` workflow, adding your own example |
 
 The pages are cross-linked: each page ends with a link to the next one.
 

docs/user/camera-input.md

@@ -57,7 +57,7 @@ Two public fields tune the feel of the camera (defaults in parentheses):
 | `zoom_factor` | multiplicative distance change per wheel notch (`distance *= factor^scroll`) | `0.9` (10% per notch) |
 
 The exact wiring snippet (orbit + zoom + reset + `1`/`2`/`3` presets, driven from
-`app.input`) is in [`demo.rs`](../../lib/examples/demo.rs), `update()` section.
+`app.input`) is in [`demo.rs`](../../lib/examples/effects/demo.rs), `update()` section.
 
 ## 3. The unified input state
 

docs/user/examples.md

@@ -1,17 +1,33 @@
 # Examples
 
-Seven examples live in [`lib/examples/`](../../lib/examples/) and all launch with
-`cargo run -p wsg-lib --example <name>`. They are **self-contained**: no assets on disk
-(procedural textures, hard-coded geometries).
+Sixteen examples live in [`lib/examples/`](../../lib/examples/), organized into
+**four category folders** — [`meshes/`](../../lib/examples/meshes/README.md),
+[`lights/`](../../lib/examples/lights/README.md),
+[`cameras/`](../../lib/examples/cameras/README.md),
+[`effects/`](../../lib/examples/effects/README.md) — each folder with its own
+`README.md` (per-example details: keys, what to observe). All launch with
+`cargo run -p wsg-lib --example <name>` (names are stable, run from the repo
+root). They are **self-contained**: no assets on disk (procedural textures,
+hard-coded geometries).
 
-| Example | Command | What it shows | Corresponding page |
-|---------|----------|---------------|--------------------|
-| `simple` | `cargo run -p wsg-lib --example simple` | The minimal declarative workflow: a two-tone 2D quad, **unlit**, rendered automatically. The "15 lines, no wgpu" model | [Quickstart](quickstart.md), [Materials](materials.md) (§ unlit) |
-| `cube` | `cargo run -p wsg-lib --example cube` | The 3D MVP: a textured (checkerboard) cube, lit (directional + point + spot), spinning | [Meshes](meshes.md), [Materials](materials.md), [Lights](lights.md) |
-| `demo` | `cargo run -p wsg-lib --example demo` | The full showcase: ground + 6 primitives, textures, 3 lights, **shadows**, **orbital camera** on keyboard/mouse (left-drag = orbit, wheel = zoom, `R` = reset, `1`/`2`/`3` = presets) | [All pages](README.md) |
-| `shadow_test` | `cargo run -p wsg-lib --example shadow_test` | Isolated shadow mapping: a cube casts a PCF-softened shadow on the ground (`clear_lights` technique → caster at index 0) | [Shadows](shadows.md) |
-| `spot_test` | `cargo run -p wsg-lib --example spot_test` | Isolated spot (ambient nearly zero): the directed beam, the penumbra, the attenuation | [Lights](lights.md) |
-| `manual` | `cargo run -p wsg-lib --example manual` | The **advanced** workflow: `Context`/`Renderer`/`PipelineCache` driven by hand, without the `App` facade (winit 0.30 `ApplicationHandler`) | below |
+| Folder | Example | What it shows | Corresponding page |
+|--------|---------|---------------|--------------------|
+| `meshes/` | `simple` | The minimal declarative workflow: a two-tone 2D quad, **unlit**, rendered automatically. The "15 lines, no wgpu" model | [Quickstart](quickstart.md), [Materials](materials.md) (§ unlit) |
+| `meshes/` | `cube` | The 3D MVP: a textured (checkerboard) cube, lit (directional + point + spot), spinning | [Meshes](meshes.md), [Materials](materials.md), [Lights](lights.md) |
+| `meshes/` | `pbr` | PBR metallic/roughness + normal mapping (6 materials) | [Materials](materials.md) |
+| `meshes/` | `import` | OBJ file import (non-graphical, prints stats to stdout) | [Meshes](mesh.md) |
+| `meshes/` | `manual` | The **advanced** workflow: `Context`/`Renderer`/`PipelineCache` driven by hand, without the `App` facade | below |
+| `lights/` | `shadow` | Shadow mapping in isolation (4 objects on a floor) | [Shadows](shadows.md) |
+| `lights/` | `shadow_test` | Isolated shadow mapping: a cube casts a PCF-softened shadow on the ground (`clear_lights` technique → caster at index 0) | [Shadows](shadows.md) |
+| `lights/` | `spot_test` | Isolated spot (ambient nearly zero): the directed beam, the penumbra, the attenuation | [Lights](lights.md) |
+| `lights/` | `emissive` | Emissive materials (intensities 0 → 4.0) + runtime exposure | [Emissive & exposure](emissive-exposure.md) |
+| `cameras/` | `culling` | GPU-driven frustum culling: 15×15 grid, off-frustum cubes skipped (zero CPU cost) | [GPU-driven](gpu-driven.md) |
+| `effects/` | `demo` | The full showcase: ground + 6 LOD primitives, textures, 3 lights, **shadows**, **orbital camera** on keyboard/mouse, HDR/ACES, bloom | [All pages](README.md) |
+| `effects/` | `bloom` | Post-process bloom (threshold → blur → composite) | [Bloom](bloom.md) |
+| `effects/` | `hdr` | HDR + tone mapping (ACES) + runtime exposure control | [HDR](hdr.md) |
+| `effects/` | `msaa` | MSAA 4× (smooth edges vs stair-stepped) | [MSAA](msaa.md) |
+| `effects/` | `fog` | Distance fog (3 modes: linear, exp, exp²) | [Fog](fog.md) |
+| `effects/` | `dof` | Depth of field (cinematic bokeh, focus presets) | [effects README](../../lib/examples/effects/README.md) |
 
 ## The `manual` workflow (advanced)
 
@@ -26,7 +42,7 @@ framework, experimentation), you bypass `App` and drive directly:
 
 The window and GPU are created in winit 0.30's `resumed()` callback (`run_app` +
 `ApplicationHandler`), as in `app.rs`. The reference file is
-[`manual.rs`](../../lib/examples/manual.rs); the two-layer architecture is detailed in
+[`manual.rs`](../../lib/examples/meshes/manual.rs); the two-layer architecture is detailed in
 [ARCHI_APP](../tech/ARCHI_APP.md) and [FRAME_LOOP](../tech/FRAME_LOOP.md).
 
 > **Tip**: start with the declarative workflow. The manual workflow doesn't render more
@@ -34,12 +50,19 @@ The window and GPU are created in winit 0.30's `resumed()` callback (`run_app` +
 
 ## Adding your own example
 
-Repo conventions (see `lib/examples/README.md`):
+Repo conventions (see [`lib/examples/README.md`](../../lib/examples/README.md)):
 
-1. Create `lib/examples/my_example.rs` (Cargo discovers it automatically).
-2. Keep it **self-contained**: procedural textures, hard-coded geometries, no external assets.
-3. Use the declarative workflow (`AppBuilder` + `Scene`) when possible.
-4. Document the example in `lib/examples/README.md` (and here, `docs/user/examples.md`).
+1. Create `lib/examples/<folder>/my_example.rs` (pick the matching category —
+   `meshes/`, `lights/`, `cameras/`, `effects/` — or add a new folder + README).
+2. Declare it in `lib/Cargo.toml` — examples live in subfolders, so Cargo does
+   **not** discover them automatically:
+   ```toml
+   [[example]]
+   name = "my_example"
+   path = "examples/<folder>/my_example.rs"
+   ```
+3. Keep it **self-contained**: procedural textures, hard-coded geometries, no external assets.
+4. Document the example in the folder's `README.md` (and here, `docs/user/examples.md`).
 
 ## Links
 

docs/user/fog.md

@@ -125,7 +125,7 @@ brouillé. Résultat : le brouillard est perceptuellement cohérent.
 
 ## Exemple
 
-Voir `examples/fog.rs` : 15 cubes en rangée + 5 sphères sur un plan 80×80,
+Voir `lib/examples/effects/fog.rs` : 15 cubes en rangée + 5 sphères sur un plan 80×80,
 avec commutation runtime entre les 3 modes.
 
 ```sh

docs/user/lights.md

@@ -37,9 +37,9 @@ app.scene.add_spot_light(
 ).unwrap();
 ```
 
-These three calls are the ones in the [`demo`](../../lib/examples/demo.rs) example;
-[`cube.rs`](../../lib/examples/cube.rs) shows a point + a spot on top of the default
-directional, and [`spot_test.rs`](../../lib/examples/spot_test.rs) isolates a single spot
+These three calls are the ones in the [`demo`](../../lib/examples/effects/demo.rs) example;
+[`cube.rs`](../../lib/examples/meshes/cube.rs) shows a point + a spot on top of the default
+directional, and [`spot_test.rs`](../../lib/examples/lights/spot_test.rs) isolates a single spot
 (ambient nearly zero).
 
 Global settings:
@@ -68,7 +68,7 @@ Two consequences:
    [Shadows](shadows.md).
 2. If you want **your** light to be the only one (and thus at index 0), clear the list
    first: `app.scene.clear_lights();` then `add_*_light(…)` (this is the technique in
-   [`shadow_test.rs`](../../lib/examples/shadow_test.rs)).
+   [`shadow_test.rs`](../../lib/examples/lights/shadow_test.rs)).
 
 ## Intensities and tints
 

docs/user/materials.md

@@ -43,7 +43,7 @@ app.scene.create_mesh("cube_mesh", cube(1.0), Some("mat_textured")).unwrap();
 
 A mesh created with `material = None` is rendered with the scene's **default material**
 (`standard`, built once then cached) — that is the behavior of the
-[`simple`](../../lib/examples/simple.rs) example.
+[`simple`](../../lib/examples/meshes/simple.rs) example.
 
 ## 3. Diffuse textures
 
@@ -70,7 +70,7 @@ app.scene.add_material_texture("ground_mat", "standard", "checker_texture").unwr
 ```
 
 The exact snippet (8×8 checkerboard + stripes generation) is in
-[`demo.rs`](../../lib/examples/demo.rs) and [`cube.rs`](../../lib/examples/cube.rs).
+[`demo.rs`](../../lib/examples/effects/demo.rs) and [`cube.rs`](../../lib/examples/meshes/cube.rs).
 
 Two conditions for a texture to show up:
 1. the material is created via `add_material_texture` (otherwise the 1×1 white placeholder

docs/user/meshes.md

@@ -86,7 +86,7 @@ horizon — see [ROADMAP](../ROADMAP.md)).
 Placement lives on the **entity** (not on the mesh): `Transform { translation: Vec3,
 rotation: Quat, scale: Vec3 }`, converted to a world matrix by the engine every frame.
 
-The snippet below is the animation from the [`cube`](../../lib/examples/cube.rs) example:
+The snippet below is the animation from the [`cube`](../../lib/examples/meshes/cube.rs) example:
 
 ```rust
 fn update(&mut self, app: &mut wsg_lib::App) {

docs/user/msaa.md

@@ -123,5 +123,5 @@ let app = AppBuilder::new()
     .await?;
 ```
 
-See `examples/msaa.rs` for a full interactive demo with cube, sphere,
+See `lib/examples/effects/msaa.rs` for a full interactive demo with cube, sphere,
 and ground plane where aliasing is clearly visible without MSAA.

docs/user/quickstart.md

@@ -22,7 +22,7 @@ pollster = { version = "1", features = ["macro"] }   # for #[pollster::main] (Ap
 
 ## 2. The minimal application
 
-This snippet is the [`simple`](../../lib/examples/simple.rs) example from the repo, almost
+This snippet is the [`simple`](../../lib/examples/meshes/simple.rs) example from the repo, almost
 verbatim: a flat two-tone quad, rendered automatically every frame.
 
 ```rust
@@ -107,7 +107,8 @@ Golden rule: **mutate the scene in `update()`** (and `setup()`), only read it in
 
 ## 4. Running it
 
-From the WSG repo root (the examples live in `lib/examples/`):
+From the WSG repo root (the examples live in `lib/examples/`, one folder per
+category: `meshes/`, `lights/`, `cameras/`, `effects/`):
 
 | Command | What you see |
 |----------|--------------|

docs/user/shadows.md

@@ -29,7 +29,7 @@ Two ways to avoid it:
    app.scene.set_shadow_caster(Some(0));           // now it really is YOUR light
    ```
 
-   This is the technique in [`shadow_test.rs`](../../lib/examples/shadow_test.rs).
+   This is the technique in [`shadow_test.rs`](../../lib/examples/lights/shadow_test.rs).
 
 2. **Count the indices** — if you keep the default light and add yours, it lands at index 1:
 
@@ -38,7 +38,7 @@ Two ways to avoid it:
    app.scene.set_shadow_caster(Some(1)); // this is the demo's warm light that casts
    ```
 
-   This is the technique in [`demo.rs`](../../lib/examples/demo.rs).
+   This is the technique in [`demo.rs`](../../lib/examples/effects/demo.rs).
 
 ## How it works (to understand the limits)