doc

lib/src/lib.rs

@@ -1,14 +1,22 @@
 //! # WSG Library Crate Root
 //!
-//! The top-level entry point for the wsg-lib crate. Exposes five public modules organized by architectural responsibility:
-//! **core** (Manager + Executor layers), **resources** (data types), **pipeline** (shader compilation cache),
-//! **scene** (resource graph and entity management), and **utils** (configuration and error handling).
+//! The top-level entry point for the wsg-lib crate. Exposes seven public modules organized by architectural responsibility:
+//! **app** (App facade + AppBuilder), **handler** (AppHandler trait), **core** (Manager + Executor layers),
+//! **resources** (data types), **pipeline** (shader compilation cache), **scene** (resource graph and entity management),
+//! and **utils** (configuration and error handling).
 //!
 //! ## Module Interaction Map
 //! - `core` consumes resources from `resources`, pipelines from `pipeline`, and errors from `utils`.
 //! - `scene` aggregates Resources, Materials, and Pipelines into an entity graph.
+//! - `app` orchestrates all subsystems plus the event loop; depends on everything else.
+//! - `handler` defines the user-facing interface consumed by `app`.
 //! - `utils` is a leaf module — no internal dependencies on other library modules.
 //!
+//! ## Top-Level Re-Exports
+//! These are the two primary types users interact with when building applications:
+//! - `App` — high-level application facade wrapping window lifecycle, GPU context, and render automation.
+//! - `AppHandler` — trait users implement to inject game logic into the render loop.
+//!
 //! ## Usage
 //! Consumers import through the re-exports defined in each submodule's `mod.rs`:
 //! ```ignore
@@ -16,6 +24,7 @@
 //! use wsg_lib::resources::{Mesh, Material, Vertex};
 //! use wsg_lib::utils::BASIC_SHADER;
 //! ```
+
 pub mod app;
 pub mod core;
 pub mod handler;
@@ -24,4 +33,10 @@ pub mod resources;
 pub mod scene;
 pub mod utils;
 
-pub use handler::AppHandler;
+/// Re-export of the high-level application facade for convenient top-level access.
+/// Users create App instances via `AppBuilder`, then call `.run(handler)` to start the application.
+pub use crate::app::App;
+
+/// Re-export of the user-defined game logic interface for convenient top-level access.
+/// Users implement this trait to define update/render callbacks injected into the render loop.
+pub use crate::handler::AppHandler;