fix(lambda-rs): Respect WindowBuilder vsync in render surface configuration (#175)

## Summary

Fixes vsync configuration being effectively ignored in some cases by
ensuring
the requested present mode is respected end-to-end and that “vsync off”
fallbacks prefer true non-vsync modes when available.

## Related Issues

- Resolves #101 

## Changes

- Respect window vsync preference when building a `RenderContext` (when
no explicit present mode is set).
- Prefer `AutoNoVsync` over `Mailbox` when the caller requests non-vsync
presentation but the adapter does not support `Immediate`.
- Add unit tests covering present mode resolution and platform
present-mode fallback ordering.
- Clarify `WindowBuilder::with_vsync` docs (best-effort based on
platform capabilities).

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] Feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation (updates to docs, specs, tutorials, or comments)
- [ ] Refactor (code change that neither fixes a bug nor adds a feature)
- [ ] Performance (change that improves performance)
- [x] Test (adding or updating tests)
- [ ] Build/CI (changes to build process or CI configuration)

## Affected Crates

- [x] `lambda-rs`
- [x] `lambda-rs-platform`
- [ ] `lambda-rs-args`
- [ ] `lambda-rs-logging`
- [ ] Other:

## Checklist

- [ ] Code follows the repository style guidelines (`cargo +nightly fmt
--all`)
- [ ] Code passes clippy (`cargo clippy --workspace --all-targets -- -D
warnings`)
- [ ] Tests pass (`cargo test --workspace`)
- [x] New code includes appropriate documentation
- [ ] Public API changes are documented
- [ ] Breaking changes are noted in this PR description

## Testing

**Commands run:**

```bash
cargo test -p lambda-rs-platform --lib
cargo test -p lambda-rs --lib
```

**Manual verification steps (if applicable):**

1. (Optional) Run a demo with `WindowBuilder::with_vsync(false)` and
confirm frame pacing is no longer refresh-capped on platforms that
support non-vsync modes.

## Screenshots/Recordings

N/A

## Platform Testing

- [x] macOS
- [ ] Windows
- [ ] Linux

## Additional Notes

Author: vmarcella

crates/lambda-rs-platform/src/wgpu/surface.rs

@@ -318,11 +318,23 @@ fn select_present_mode(
     return requested;
   }
 
+  // Note on ordering:
+  // - When callers request non-vsync (Immediate/AutoNoVsync), prefer true
+  //   non-vsync modes (Immediate, AutoNoVsync) over low-latency vsync modes
+  //   (Mailbox). Mailbox still synchronizes presentation to refresh and can
+  //   appear "vsync-like" to users who disable vsync expecting uncapped loops.
   let candidates: &[wgpu::PresentMode] = match requested {
-    wgpu::PresentMode::Immediate | wgpu::PresentMode::AutoNoVsync => &[
+    wgpu::PresentMode::Immediate => &[
       wgpu::PresentMode::Immediate,
+      wgpu::PresentMode::AutoNoVsync,
       wgpu::PresentMode::Mailbox,
+      wgpu::PresentMode::Fifo,
+      wgpu::PresentMode::AutoVsync,
+    ],
+    wgpu::PresentMode::AutoNoVsync => &[
       wgpu::PresentMode::AutoNoVsync,
+      wgpu::PresentMode::Immediate,
+      wgpu::PresentMode::Mailbox,
       wgpu::PresentMode::Fifo,
       wgpu::PresentMode::AutoVsync,
     ],
@@ -336,7 +348,15 @@ fn select_present_mode(
       wgpu::PresentMode::Fifo,
       wgpu::PresentMode::AutoVsync,
     ],
-    wgpu::PresentMode::Fifo | wgpu::PresentMode::AutoVsync => &[
+    wgpu::PresentMode::AutoVsync => &[
+      wgpu::PresentMode::AutoVsync,
+      wgpu::PresentMode::Fifo,
+      wgpu::PresentMode::FifoRelaxed,
+      wgpu::PresentMode::Mailbox,
+      wgpu::PresentMode::Immediate,
+      wgpu::PresentMode::AutoNoVsync,
+    ],
+    wgpu::PresentMode::Fifo => &[
       wgpu::PresentMode::Fifo,
       wgpu::PresentMode::AutoVsync,
       wgpu::PresentMode::FifoRelaxed,
@@ -414,4 +434,39 @@ mod tests {
     let selected = select_present_mode(wgpu::PresentMode::Immediate, available);
     assert_eq!(selected, wgpu::PresentMode::AutoNoVsync);
   }
+
+  #[test]
+  fn select_present_mode_prefers_auto_no_vsync_over_mailbox_for_immediate_request(
+  ) {
+    let available = &[
+      wgpu::PresentMode::Mailbox,
+      wgpu::PresentMode::AutoNoVsync,
+      wgpu::PresentMode::Fifo,
+    ];
+    let selected = select_present_mode(wgpu::PresentMode::Immediate, available);
+    assert_eq!(selected, wgpu::PresentMode::AutoNoVsync);
+  }
+
+  #[test]
+  fn select_present_mode_prefers_auto_no_vsync_when_requested() {
+    let available = &[
+      wgpu::PresentMode::Immediate,
+      wgpu::PresentMode::AutoNoVsync,
+      wgpu::PresentMode::Fifo,
+    ];
+    let selected =
+      select_present_mode(wgpu::PresentMode::AutoNoVsync, available);
+    assert_eq!(selected, wgpu::PresentMode::AutoNoVsync);
+  }
+
+  #[test]
+  fn select_present_mode_prefers_auto_vsync_when_requested() {
+    let available = &[
+      wgpu::PresentMode::Fifo,
+      wgpu::PresentMode::AutoVsync,
+      wgpu::PresentMode::Immediate,
+    ];
+    let selected = select_present_mode(wgpu::PresentMode::AutoVsync, available);
+    assert_eq!(selected, wgpu::PresentMode::AutoVsync);
+  }
 }

crates/lambda-rs/src/render/mod.rs

@@ -190,17 +190,8 @@ impl RenderContextBuilder {
       })?;
 
     let size = window.dimensions();
-    let requested_present_mode = present_mode.unwrap_or_else(|| {
-      if window.vsync_requested() {
-        return PresentMode::Vsync;
-      }
-      return PresentMode::Immediate;
-    });
-    let platform_present_mode = match requested_present_mode {
-      PresentMode::Vsync => targets::surface::PresentMode::Fifo,
-      PresentMode::Immediate => targets::surface::PresentMode::Immediate,
-      PresentMode::Mailbox => targets::surface::PresentMode::Mailbox,
-    };
+    let platform_present_mode =
+      resolve_surface_present_mode(present_mode, window.vsync_requested());
     surface
       .configure_with_defaults(
         &gpu,
@@ -261,6 +252,23 @@ impl RenderContextBuilder {
   }
 }
 
+fn resolve_surface_present_mode(
+  builder_mode: Option<PresentMode>,
+  window_vsync: bool,
+) -> targets::surface::PresentMode {
+  let requested = builder_mode.unwrap_or(if window_vsync {
+    PresentMode::Vsync
+  } else {
+    PresentMode::Immediate
+  });
+
+  return match requested {
+    PresentMode::Vsync => targets::surface::PresentMode::Fifo,
+    PresentMode::Immediate => targets::surface::PresentMode::Immediate,
+    PresentMode::Mailbox => targets::surface::PresentMode::Mailbox,
+  };
+}
+
 /// High‑level rendering context for a single window.
 ///
 /// Purpose
@@ -1104,4 +1112,22 @@ mod tests {
       .expect_err("must error");
     assert!(err.to_string().contains("Unknown pipeline 7"));
   }
+
+  #[test]
+  fn present_mode_defaults_to_window_vsync_true() {
+    let mode = resolve_surface_present_mode(None, true);
+    assert_eq!(mode, targets::surface::PresentMode::Fifo);
+  }
+
+  #[test]
+  fn present_mode_defaults_to_window_vsync_false() {
+    let mode = resolve_surface_present_mode(None, false);
+    assert_eq!(mode, targets::surface::PresentMode::Immediate);
+  }
+
+  #[test]
+  fn present_mode_builder_override_wins_over_window_setting() {
+    let mode = resolve_surface_present_mode(Some(PresentMode::Vsync), false);
+    assert_eq!(mode, targets::surface::PresentMode::Fifo);
+  }
 }

crates/lambda-rs/src/render/window.rs

@@ -56,6 +56,9 @@ impl WindowBuilder {
   ///
   /// This value is consumed when building a `RenderContext` if no explicit
   /// present mode is provided to `RenderContextBuilder`.
+  ///
+  /// Disabling vsync is best‑effort; the final present mode depends on the
+  /// platform and adapter surface capabilities.
   pub fn with_vsync(mut self, vsync: bool) -> Self {
     self.vsync = vsync;
     return self;