[update] spacing.

Author: vmarcella

docs/game_roadmap_and_prototype.md

@@ -24,6 +24,7 @@ This document outlines current engine capabilities, the gaps to address for 2D/3
 Key modules: windowing/events (winit), GPU (wgpu), render context, runtime loop, and GLSL→SPIR‑V shader compilation (naga).
 
 Frame flow:
+
 ```
 App Components --> ApplicationRuntime --> RenderContext --> wgpu (Device/Queue/Surface)
          |                 |                 |                  |
@@ -49,6 +50,7 @@ Currently supported commands: Begin/EndRenderPass, SetPipeline, SetViewports, Se
 ## Targeted API Additions (sketches)
 
 Bind groups and uniforms (value: larger, structured GPU data; portable across adapters; enables cameras/materials):
+
 ```rust
 // Layout with one uniform buffer at set(0) binding(0)
 let layout = BindGroupLayoutBuilder::new()
@@ -84,10 +86,12 @@ RC::Draw { vertices: 0..3 };
 ```
 
 Notes
+
 - UBO vs push constants: UBOs scale to KBs and are supported widely; use for view/projection and per‑frame data.
 - Dynamic offsets (optional later) let you pack many small structs into one UBO.
 
 Textures and samplers (value: sprites, materials, UI images; sRGB correctness):
+
 ```rust
 let tex = TextureBuilder::new_2d(TextureFormat::Rgba8UnormSrgb)
   .with_size(w, h)
@@ -109,6 +113,7 @@ let tex_group = BindGroupBuilder::new(&tex_layout)
 ```
 
 Index draw and instancing (value: reduce vertex duplication; batch many objects in one draw):
+
 ```rust
 RC::BindVertexBuffer { pipeline: pipe_id, buffer: 0 };
 RC::BindVertexBuffer { pipeline: pipe_id, buffer: 1 }; // instances
@@ -117,6 +122,7 @@ RC::DrawIndexed { indices: 0..index_count, base_vertex: 0, instances: 0..instanc
 ```
 
 Instance buffer attributes example
+
 ```rust
 // slot 1: per-instance mat3x2 (2D) packed as 3x vec2, plus tint color
 let instance_attrs = vec![
@@ -130,6 +136,7 @@ let instance_attrs = vec![
 ```
 
 Depth/MSAA (value: correct 3D visibility and improved edge quality):
+
 ```rust
 let pass = RenderPassBuilder::new()
   .with_clear_color(wgpu::Color::BLACK)
@@ -154,10 +161,12 @@ let pipe = RenderPipelineBuilder::new()
 ```
 
 Notes
+
 - Use reversed‑Z (Greater) later for precision, but start with Less.
 - MSAA sample count must match between pass and pipeline.
 
 Offscreen render targets (value: post‑processing, shadow maps, UI composition, picking):
+
 ```rust
 let offscreen = RenderTargetBuilder::new()
   .with_color(TextureFormat::Rgba8UnormSrgb, width, height)
@@ -189,6 +198,7 @@ RC::EndRenderPass;
 ```
 
 WGSL support (value: first‑class wgpu shader language, fewer translation pitfalls):
+
 ```rust
 let vs = VirtualShader::WgslSource { source: include_str!("shaders/quad.wgsl").into(), name: "quad".into(), entry_point: "vs_main".into() };
 let fs = VirtualShader::WgslSource { source: include_str!("shaders/quad.wgsl").into(), name: "quad".into(), entry_point: "fs_main".into() };
@@ -201,6 +211,7 @@ Shader hot‑reload (value: faster iteration; no rebuild): watch file timestamps
 Goals: sprite batching via instancing; atlas textures; ortho camera; input mapping; text HUD. Target 60 FPS with 10k sprites (mid‑range GPU).
 
 Core draw:
+
 ```rust
 RC::BeginRenderPass { render_pass: pass_id, viewport };
 RC::SetPipeline { pipeline: pipe_id };
@@ -214,12 +225,14 @@ RC::EndRenderPass;
 ```
 
 Building instance data each frame (value: dynamic transforms with minimal overhead):
+
 ```rust
 // CPU side: update transforms and pack into a Vec<Instance>
 queue.write_buffer(instance_vbo.raw(), 0, bytemuck::cast_slice(&instances));
 ```
 
 Text rendering options (value: legible UI/HUD):
+
 - Bitmap font atlas: simplest path; pack glyphs into the sprite pipeline.
 - glyphon/glyph_brush integration: high‑quality layout; more deps; implement later.
 
@@ -230,6 +243,7 @@ Goals: depth test/write, indexed mesh, textured material, simple lighting; orbit
 Core draw mirrors 2D but with depth enabled and mesh buffers.
 
 Camera helpers (value: reduce boilerplate and bugs):
+
 ```rust
 let proj = matrix::perspective_matrix(60f32.to_radians(), width as f32 / height as f32, 0.1, 100.0);
 let view = matrix::translation_matrix([0.0, 0.0, -5.0]); // or look_at helper later

docs/specs/depth-stencil-msaa.md

@@ -18,6 +18,7 @@ tags: ["spec", "rendering", "depth", "stencil", "msaa"]
 # Depth/Stencil and Multi-Sample Rendering
 
 Summary
+
 - Add configurable depth testing/writes and multi-sample anti-aliasing (MSAA)
   to the high-level rendering API via builders, without exposing `wgpu` types.
 - Provide validation and predictable defaults to enable 3D scenes and
@@ -85,6 +86,7 @@ App Code
     - `RenderPipelineBuilder::with_stencil(StencilState) -> Self`
     - `RenderPipelineBuilder::with_multi_sample(u32) -> Self`
   - Example (engine types only)
+
     ```rust
     use lambda::render::render_pass::RenderPassBuilder;
     use lambda::render::pipeline::{RenderPipelineBuilder, CompareFunction};
@@ -113,6 +115,7 @@ App Code
         Some(&fragment_shader),
       );
     ```
+
 - Behavior
   - Defaults
     - If neither depth nor stencil is requested on the pass, the pass MUST NOT
@@ -178,6 +181,7 @@ App Code
   - `render-validation-device`: device/format capability advisories (MSAA sample support).
 
 Always-on safeguards (release and debug)
+
 - Clamp depth clear to `[0.0, 1.0]`.
 - Align pipeline `sample_count` to the pass `sample_count`.
 - Clamp invalid MSAA sample counts to `1`.
@@ -254,6 +258,7 @@ Always-on safeguards (release and debug)
   defaults (no depth, no multi-sampling) unless explicitly configured.
 
 ## Changelog
+
 - 2025-12-15 (v0.5.0) — Update example code to use `render_context.gpu()` and add `surface_format`/`depth_format` parameters to `RenderPassBuilder` and `RenderPipelineBuilder`.
 - 2025-11-21 (v0.4.1) — Clarify depth attachment and clear behavior for
   stencil-only passes; align specification with engine behavior that preserves

docs/specs/indexed-draws-and-multiple-vertex-buffers.md

@@ -18,6 +18,7 @@ tags: ["spec", "rendering", "vertex-input", "indexed-draws"]
 # Indexed Draws and Multiple Vertex Buffers
 
 ## Table of Contents
+
 - [Summary](#summary)
 - [Scope](#scope)
 - [Terminology](#terminology)

docs/specs/textures-and-samplers.md

@@ -18,6 +18,7 @@ tags: ["spec", "rendering", "textures", "samplers", "wgpu"]
 # Textures and Samplers
 
 Summary
+
 - Introduces first-class 2D and 3D sampled textures and samplers with a
   builder-based application programming interface and platform abstraction.
 - Rationale: Texture sampling is foundational for images, sprites, materials,
@@ -305,6 +306,7 @@ Render pass: SetPipeline -> SetBindGroup -> Draw
 ## Example Usage
 
 Rust (2D high level)
+
 ```rust
 use lambda::render::texture::{TextureBuilder, SamplerBuilder, TextureFormat};
 use lambda::render::bind::{BindGroupLayoutBuilder, BindGroupBuilder, BindingVisibility};
@@ -338,6 +340,7 @@ RC::SetBindGroup { set: 0, group: group_id, dynamic_offsets: vec![] };
 ```
 
 WGSL snippet (2D)
+
 ```wgsl
 @group(0) @binding(1) var texture_color: texture_2d<f32>;
 @group(0) @binding(2) var sampler_color: sampler;
@@ -350,6 +353,7 @@ fn fs_main(in_uv: vec2<f32>) -> @location(0) vec4<f32> {
 ```
 
 Rust (3D high level)
+
 ```rust
 use lambda::render::texture::{TextureBuilder, TextureFormat};
 use lambda::render::bind::{BindGroupLayoutBuilder, BindGroupBuilder};
@@ -375,6 +379,7 @@ let group3d = BindGroupBuilder::new()
 ```
 
 WGSL snippet (3D)
+
 ```wgsl
 @group(0) @binding(1) var volume_tex: texture_3d<f32>;
 @group(0) @binding(2) var volume_samp: sampler;

docs/specs/uniform-buffers-and-bind-groups.md

@@ -18,6 +18,7 @@ tags: ["spec", "rendering", "uniforms", "bind-groups", "wgpu"]
 # Uniform Buffers and Bind Groups
 
 Summary
+
 - Specifies uniform buffer objects (UBOs) and bind groups for the
   wgpu‑backed renderer, preserving builder/command patterns and the separation
   between platform and high‑level layers.
@@ -72,6 +73,7 @@ Summary
     platform layer.
 
 Data flow (one-time setup → per-frame):
+
 ```
 BindGroupLayoutBuilder --> BindGroupLayout --+--> RenderPipelineBuilder (layouts)
                                              |
@@ -142,6 +144,7 @@ Per-frame commands: BeginRenderPass -> SetPipeline -> SetBindGroup -> Draw -> En
 ## Example Usage
 
 Rust (high level)
+
 ```rust
 use lambda::render::{
   bind::{BindGroupLayoutBuilder, BindGroupBuilder, BindingVisibility},
@@ -198,6 +201,7 @@ rc.render(cmds);
 ```
 
 WGSL snippet
+
 ```wgsl
 struct Globals { view_proj: mat4x4<f32>; };
 @group(0) @binding(0) var<uniform> globals: Globals;
@@ -209,12 +213,14 @@ fn vs_main(in_pos: vec3<f32>) -> @builtin(position) vec4<f32> {
 ```
 
 GLSL snippet (via naga -> SPIR-V)
+
 ```glsl
 layout(set = 0, binding = 0) uniform Globals { mat4 view_proj; } globals;
 void main() { gl_Position = globals.view_proj * vec4(in_pos, 1.0); }
 ```
 
 Dynamic offsets
+
 ```rust
 let dyn_layout = BindGroupLayoutBuilder::new()
   .with_uniform_dynamic(0, BindingVisibility::Vertex)
@@ -226,6 +232,7 @@ let stride = lambda::render::validation::align_up(size, align);
 let offsets = vec![0u32, stride as u32, (2*stride) as u32];
 RC::SetBindGroup { set: 0, group: dyn_group_id, dynamic_offsets: offsets };
 ```
+
 ## Performance Considerations
 
 - Prefer `Properties::DEVICE_LOCAL` for long‑lived uniform buffers that are
@@ -293,8 +300,6 @@ RC::SetBindGroup { set: 0, group: dyn_group_id, dynamic_offsets: offsets };
   groups continue to function. New pipelines MAY specify layouts via
   `with_layouts` without impacting prior behavior.
 
-
-
 ## Changelog
 
 - 2025-12-15 (v0.5.0) — Update example code to use `rc.gpu()` and add `surface_format`/`depth_format` parameters to `RenderPipelineBuilder`.

docs/tutorials/indexed-draws-and-multiple-vertex-buffers.md

@@ -16,11 +16,13 @@ tags: ["tutorial", "graphics", "indexed-draws", "vertex-buffers", "rust", "wgpu"
 ---
 
 ## Overview <a name="overview"></a>
+
 This tutorial constructs a small scene rendered with indexed geometry and multiple vertex buffers. The example separates per-vertex positions from per-vertex colors and draws the result using the engine’s high-level buffer and command builders.
 
 Reference implementation: `crates/lambda-rs/examples/indexed_multi_vertex_buffers.rs`.
 
 ## Table of Contents
+
 - [Overview](#overview)
 - [Goals](#goals)
 - [Prerequisites](#prerequisites)
@@ -86,6 +88,7 @@ Render Pass → wgpu::RenderPass::{set_vertex_buffer, set_index_buffer, draw_ind
 ## Implementation Steps <a name="implementation-steps"></a>
 
 ### Step 1 — Shaders and Vertex Types <a name="step-1"></a>
+
 Step 1 defines the shader interface and vertex structures used by the example. The shaders consume positions and colors at locations `0` and `1`, and the vertex types store those attributes as three-component floating-point arrays.
 
 ```glsl
@@ -130,6 +133,7 @@ struct ColorVertex {
 The shader `location` qualifiers match the vertex buffer layouts declared on the pipeline, and the `PositionVertex` and `ColorVertex` types mirror the `vec3` inputs as `[f32; 3]` arrays in Rust.
 
 ### Step 2 — Component State and Shader Construction <a name="step-2"></a>
+
 Step 2 introduces the `IndexedMultiBufferExample` component and its `Default` implementation, which builds shader objects from the GLSL source and initializes render-resource fields and window dimensions.
 
 ```rust
@@ -192,6 +196,7 @@ impl Default for IndexedMultiBufferExample {
 This `Default` implementation ensures that the component has valid shaders and initial dimensions before it attaches to the render context.
 
 ### Step 3 — Render Pass, Vertex Data, Buffers, and Pipeline <a name="step-3"></a>
+
 Step 3 implements `on_attach` to create the render pass, vertex and index data, GPU buffers, and the render pipeline, then attaches them to the `RenderContext`.
 
 ```rust
@@ -328,6 +333,7 @@ fn on_attach(
 The pipeline uses the order of `with_buffer` calls to assign vertex buffer slots. The first buffer occupies slot `0` and provides attributes at location `0`, while the second buffer occupies slot `1` and provides attributes at location `1`. The component stores attached resource identifiers and the index count for use during rendering.
 
 ### Step 4 — Resize Handling and Updates <a name="step-4"></a>
+
 Step 4 wires window resize events into the component and implements detach and update hooks. The resize handler keeps `width` and `height` in sync with the window so that the viewport matches the surface size.
 
 ```rust
@@ -368,6 +374,7 @@ fn on_update(
 The resize path is the only dynamic input in this example. The update hook is a no-op that keeps the component interface aligned with other examples.
 
 ### Step 5 — Render Commands and Runtime Entry Point <a name="step-5"></a>
+
 Step 5 records the render commands that bind the pipeline, vertex buffers, and index buffer, and then wires the component into the runtime as a windowed application.
 
 ```rust

docs/tutorials/instanced-quads.md

@@ -16,6 +16,7 @@ tags: ["tutorial", "graphics", "instancing", "vertex-buffers", "rust", "wgpu"]
 ---
 
 ## Overview <a name="overview"></a>
+
 This tutorial builds an instanced rendering example using the `lambda-rs` crate. The final application renders a grid of 2D quads that all share the same geometry but read per-instance offsets and colors from a second vertex buffer. The example demonstrates how to configure per-vertex and per-instance buffers, construct an instanced render pipeline, and issue draw commands with a multi-instance range.
 
 Reference implementation: `crates/lambda-rs/examples/instanced_quads.rs`.
@@ -69,6 +70,7 @@ Render Pass
 ## Implementation Steps <a name="implementation-steps"></a>
 
 ### Step 1 — Shaders and Attribute Layout <a name="step-1"></a>
+
 Step 1 defines the vertex and fragment shaders for instanced quads. The vertex shader consumes per-vertex positions and per-instance offsets and colors, and the fragment shader writes the interpolated color.
 
 ```glsl
@@ -101,6 +103,7 @@ void main() {
 Attribute locations `0`, `1`, and `2` correspond to pipeline vertex attribute definitions for the per-vertex position and the per-instance offset and color. These locations will be matched by `VertexAttribute` entries when the render pipeline is constructed.
 
 ### Step 2 — Vertex and Instance Types and Component State <a name="step-2"></a>
+
 Step 2 introduces the Rust vertex and instance structures and prepares the component state. The component stores compiled shaders and identifiers for the render pass, pipeline, and buffers.
 
 ```rust
@@ -210,6 +213,7 @@ impl Default for InstancedQuadsExample {
 The `QuadVertex` and `InstanceData` structures mirror the GLSL inputs as arrays of `f32`, and the component tracks resource identifiers and counts that are populated during attachment. The `Default` implementation constructs shader objects from the GLSL source so that the component is ready to build a pipeline when it receives a `RenderContext`.
 
 ### Step 3 — Render Pass, Geometry, Instances, and Buffers <a name="step-3"></a>
+
 Step 3 implements the `on_attach` method for the component. This method creates the render pass, quad geometry, instance data, GPU buffers, and the render pipeline. It also records the number of indices and instances for use during rendering.
 
 ```rust
@@ -352,6 +356,7 @@ fn on_attach(
 The first buffer created by `with_buffer` is treated as a per-vertex buffer in slot `0`, while `with_instance_buffer` registers the instance buffer in slot `1` with per-instance step mode. The `vertex_attributes` and `instance_attributes` vectors connect shader locations `0`, `1`, and `2` to their corresponding buffer slots and formats, and the component records index and instance counts for later draws. The effective byte offset of each attribute is computed as `attribute.offset + attribute.element.offset`. In this example `attribute.offset` is kept at `0` for all attributes, and the struct layout is expressed entirely through `VertexElement::offset` (for example, the `color` field in `InstanceData` starts 12 bytes after the `offset` field). More complex layouts MAY use a non-zero `attribute.offset` to reuse the same attribute description at different base positions within a vertex or instance element.
 
 ### Step 4 — Resize Handling and Updates <a name="step-4"></a>
+
 Step 4 wires window resize events into the component and implements detach and update hooks. The resize handler keeps `width` and `height` in sync with the window so that the viewport matches the surface size.
 
 ```rust
@@ -393,6 +398,7 @@ fn on_update(
 The component does not modify instance data over time, so `on_update` is a no-op. The resize path is the only dynamic input and ensures that the viewport used during rendering matches the current window size.
 
 ### Step 5 — Render Commands and Runtime Entry Point <a name="step-5"></a>
+
 Step 5 records the render commands that bind the pipeline, vertex buffers, and index buffer, then wires the component into the `lambda-rs` runtime as a windowed application.
 
 ```rust