init wgpu + doc + err robustes

AGENTS.md

@@ -0,0 +1,45 @@
+# WSG - WGPU Simple Graphics Library
+
+## Project Type
+Rust workspace (2024 edition) wrapping [wgpu](https://github.com/gfx-rs/wgpu) for simple 3D drawing operations.
+
+## Workspace Structure
+```
+Cargo.toml          # workspace root — no dependencies here
+lib/Cargo.toml      # wsg-lib crate: wgpu 30.0.0, winit 0.30
+examples/Cargo.toml # depends on wsg-lib via path reference
+lib/lib.rs          # lib entry point
+lib/context.rs      # Context type (aggregates wgpu objects: Instance, Surface, Adapter, Device, Queue)
+lib/renderer.rs     # renderer implementation
+examples/src/main.rs # example binary
+```
+
+**Key convention**: `wsg-lib` is referenced from `examples/` via relative path (`path = "../lib"`). Do not publish this to crates.io as-is — it uses a local path dependency.
+
+## Essential Commands
+| Action | Command |
+|--------|---------|
+| Build everything | `cargo build --workspace` |
+| Run examples | `cargo run -p examples` |
+| Test | `cargo test --workspace` |
+| Check | `cargo check --workspace` |
+| Format | `cargo fmt --all` |
+
+No custom scripts or linting tooling beyond standard Cargo conventions.
+
+## Architecture Overview
+The library's purpose is to abstract the five core wgpu objects into a single **Context**:
+
+- **Instance** — GPU backend selection (Vulkan/Metal/DX12)
+- **Surface** — window rendering surface (via winit)
+- **Adapter** — physical/logical GPU device
+- **Device** — buffer/texture/pipeline creation
+- **Queue** — command submission
+
+WGPU doesn't have a native "Context" object — this type groups them together for a simpler user API. See README.md for the French documentation of each component.
+
+## Gotchas
+- Rust 2024 edition is used. Ensure your Rust toolchain supports it (`rustup update`).
+- wgpu 30.0.0 is pinned in `lib/Cargo.toml`. The comment says "check the latest version" — verify compatibility before upgrading.
+- No feature flags, no dev-dependencies, no tests yet. Adding any requires updating both `Cargo.toml` files if the dependency spans crates.
+- The workspace has no `[workspace.dependencies]` section. Dependencies are declared per-crate rather than centrally.

Cargo.toml

@@ -1,8 +1,3 @@
-[package]
-name = "wsg"
-version = "0.1.0"
-edition = "2024"
+[workspace]
 members = ["lib", "examples"]
 resolver = "2"
-
-[dependencies]

README.md

@@ -0,0 +1,16 @@
+# WSG - WGPU Simple Graphics Library
+
+A simple WGPU wrapper to expose basic objects for drawing and manipulation: Meshes, Vertices, Indexes, UVs
+
+| Component | Ownership | Role |
+|-----------|-----------|------|
+| Instance | wgpu | The entry point. It manages connections with graphics drivers (Vulkan, Metal, DX12). |
+| Surface | wgpu | The link between wgpu and your window (winit). This is where rendering is displayed. |
+| Adapter | wgpu | Represents your GPU (physical or software). |
+| Device | wgpu | The engine's core. It creates buffers, textures, and pipelines. |
+| Queue | wgpu | The queue. You send drawing commands for execution. |
+| Context | Our Lib | A logical container. wgpu doesn't have a "Context" object; we create it to group these disparate objects and simplify your user API. |
+
+Context (Lib) : Initializes the GPU, creates the surface, and holds the Device and Queue. It is static (created once at startup).
+
+Renderer (Lib) : Uses the Device to create pipelines, manages your 500,000 vertices, and uses the Queue to send rendering instructions each frame. It is dynamic (it changes depending on what you want to display).

docs/DOCUMENTATION.md

@@ -0,0 +1,35 @@
+# IAgent Documentation
+
+## Language
+
+All documentation is written in English; as a convention, the code itself uses English for variable names, function names, etc.
+
+## Code Documentation
+
+Every source file and configuration file must be systematically documented following the rules defined in this DOCUMENTATION.md file. Additionally, every directory must contain its own README.md file summarizing and explaining the module's organization at that level: what is the overall responsibility of the files grouped in this directory, which ones they are, and what each one does.
+
+We assume the reader has professional algorithmic knowledge but may not necessarily be a Rust specialist. The reader does know the project's domain — LLM logic, clients, and agents. Documentation should therefore be tailored for a professional developer who knows some programming languages (not necessarily Rust).
+
+### General Rule
+
+Documentation must describe what is coded and what purpose it serves. A LLM reading the code and documentation should be able to verify whether:
+- the documentation correctly describes what the code does,
+- the code doesn't do something other than what the documentation says.
+
+### File Headers
+
+Each module or file must include documentation explaining the module's responsibility and how it interacts with other modules in the program, at least those within its own directory. This documentation must detail the main objects (Struct, Enum, Trait) manipulated in the module and the primary functions that carry the module's core logic.
+
+## Within a File's Code
+
+### Object and Function Headers
+
+At the header of each object, describe what the object represents and its purpose. At the header of each function, describe what the function does, what inputs it expects, and what it returns. Also describe when or by whom it is typically called. This part of the description should fit within three lines maximum. If the function body exceeds fifteen lines of code, also add its internal steps and how it accomplishes them, in three lines maximum. If the function has points of attention or complex technical resolutions (such as a specific Rust idiom or library trick for solving an ownership or lifetime problem), these are documented after the function header in up to three lines of explanation.
+
+### In the Code Body
+
+If an object or function presents a particularity or specific technical point, then a descriptive comment is inserted directly into the code body or function body. If a point of attention or technical point was described in the function header, then a comment in the code body reminds where this point is located.
+
+## Documentation Maintenance
+
+The rules defined in this file are regularly applied across all code documentation to ensure consistency between code evolution and its documentation.

examples/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "examples"
+name = "wsg-examples"
 version = "0.1.0"
 edition = "2024"
 

examples/src/main.rs

@@ -0,0 +1,3 @@
+fn main() {
+    todo!("later");
+}

lib/Cargo.toml

@@ -3,6 +3,10 @@ name = "wsg-lib"
 version = "0.1.0"
 edition = "2024"
 
+[lib]
+path = "lib.rs"
+
 [dependencies]
 wgpu = "30.0.0" # Vérifiez la version la plus récente
 winit = "0.30"  # Pour la gestion de la fenêtre
+thiserror = "2"

lib/context.rs

@@ -0,0 +1,62 @@
+//! # Context Module
+//!
+//! Initializes the GPU, creates the surface, and holds the Device and Queue. It is static (created once at startup).
+
+use std::sync::Arc;
+use wgpu::{Adapter, Device, Instance, Queue, Surface};
+use winit::window::Window;
+
+use crate::error::WsgError;
+
+/// Represents the GPU context. Holds all WGPU objects needed for rendering.
+/// Created once at startup and shared across frames via Arc.
+pub struct Context {
+    /// The entry point to wgpu — manages connections with graphics drivers (Vulkan, Metal, DX12).
+    pub instance: Instance,
+    /// Rendering target surface linking wgpu to the window (winit).
+    pub surface: Surface<'static>,
+    /// Physical or software GPU adapter selected by the user.
+    pub adapter: Adapter,
+    /// The engine core — creates buffers, textures, pipelines.
+    pub device: Device,
+    /// Command submission queue — drawing commands are sent here for execution.
+    pub queue: Queue,
+}
+
+impl Context {
+    /// Initializes the WGPU context. Creates the surface from the window, requests a device from the adapter,
+    /// and stores all required objects (instance, surface, adapter, device, queue).
+    /// Called once at application startup. Returns an error if GPU initialization fails.
+    pub async fn new(window: Arc<Window>) -> Result<Self, WsgError> {
+        // WGPU instance
+        let instance = wgpu::Instance::default();
+
+        // Surface (bound to window lifecycle, so unsafe)
+        let surface = instance
+            .create_surface(window)
+            .map_err(|e| WsgError::SurfaceCreation(e))?;
+
+        // Request for adapter (GPU)
+        let adapter = instance
+            .request_adapter(&wgpu::RequestAdapterOptions {
+                compatible_surface: Some(&surface),
+                ..Default::default()
+            })
+            .await
+            .map_err(|_| WsgError::NoAdapter)?;
+
+        // Request for adapter device and queue
+        let (device, queue) = adapter
+            .request_device(&wgpu::DeviceDescriptor::default())
+            .await
+            .map_err(|_| WsgError::DeviceCreation)?;
+
+        Ok(Self {
+            instance,
+            surface,
+            adapter,
+            device,
+            queue,
+        })
+    }
+}

lib/error.rs

@@ -0,0 +1,28 @@
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum WsgError {
+    /// Error from the windowing system (winit)
+    #[error("Window system error (winit)")]
+    WindowSystem,
+
+    /// No suitable graphics adapter found
+    #[error("No graphics adapter found")]
+    NoAdapter,
+
+    /// Failed to create a WGPU device
+    #[error("Failed to create WGPU device")]
+    DeviceCreation,
+
+    /// Shader compilation or creation error
+    #[error("Shader compilation or creation error: {0}")]
+    ShaderError(String),
+
+    /// Internal WGPU error
+    #[error("Internal WGPU error: {0}")]
+    InternalWgpu(#[from] wgpu::RequestDeviceError),
+
+    /// Failed to create the rendering surface
+    #[error("Failed to create rendering surface")]
+    SurfaceCreation(wgpu::CreateSurfaceError),
+}

lib/lib.rs

@@ -0,0 +1,5 @@
+pub mod context;
+pub mod error;
+pub mod renderer;
+
+pub use error::WsgError; // Pour permettre un import direct du type