refactor(rust): fix Provider lifecycle, improve cross-platform scripts, and address PR #44 review feedback

Rust bindings improvements:
- Provider::open_device: clean up callbacks before destroying handle (prevents UAF/leaks)
- set_resolution: add rollback logic to avoid partial state updates if height set fails
- Global error callback: clarify process-global semantics with alias APIs
  - Add set_global_error_callback() and clear_global_error_callback() aliases
  - Always clear C-side callback in clear_error_callback()

Build and test script improvements:
- build_and_test.sh: cross-platform CPU core detection (nproc → sysctl/getconf fallback)
- build_and_test.sh: robust CLI binary discovery (handle .exe on Windows)
- build_and_test.sh: remove duplicate echo output
- test_remote_crate.sh: fix cargo metadata version detection (remove --no-deps)
- test_remote_crate.sh: improve cargo update error handling message

Documentation fixes:
- Wrap bare URLs in angle brackets (MD034)
- Fix list indentation and table formatting (MD007/MD060)
- Add blank lines around list features (MD032)

Verified with:
- cargo fmt (format all code)
- cargo test (Rust bindings pass)
- markdownlint (no errors remaining)

Author: wysaid

README.md

@@ -212,8 +212,8 @@ int main() {
 
 Rust bindings are available as a crate on crates.io:
 
-- Crate: https://crates.io/crates/ccap-rs
-- Docs: https://docs.rs/ccap-rs
+- Crate: <https://crates.io/crates/ccap-rs>
+- Docs: <https://docs.rs/ccap-rs>
 - Source: `bindings/rust/`
 
 Quick install:
@@ -256,6 +256,7 @@ cmake --build .
 ```
 
 **Key Features:**
+
 - 📷 List and select camera devices
 - 🎯 Capture single or multiple images
 - 👁️ Real-time preview window (with GLFW)
@@ -265,12 +266,13 @@ cmake --build .
 - ⏱️ Duration-based or count-based capture modes
 - 🔁 Video looping and playback speed control
 
+
 For complete CLI documentation, see [CLI Tool Guide](./docs/content/cli.md).
 
 ## System Requirements
 
 | Platform | Compiler | System Requirements |
-|----------|----------|---------------------|
+| -------- | -------- | ------------------- |
 | **Windows** | MSVC 2019+ (including 2026) / MinGW-w64 | DirectShow |
 | **macOS** | Xcode 11+ | macOS 10.13+ |
 | **iOS** | Xcode 11+ | iOS 13.0+ |
@@ -290,7 +292,7 @@ For complete CLI documentation, see [CLI Tool Guide](./docs/content/cli.md).
 ## Examples
 
 | Example | Description | Language | Platform |
-|---------|-------------|----------|----------|
+| ------- | ----------- | -------- | -------- |
 | [0-print_camera](./examples/desktop/0-print_camera.cpp) / [0-print_camera_c](./examples/desktop/0-print_camera_c.c) | List available cameras | C++ / C | Desktop |
 | [1-minimal_example](./examples/desktop/1-minimal_example.cpp) / [1-minimal_example_c](./examples/desktop/1-minimal_example_c.c) | Basic frame capture | C++ / C | Desktop |
 | [2-capture_grab](./examples/desktop/2-capture_grab.cpp) / [2-capture_grab_c](./examples/desktop/2-capture_grab_c.c) | Continuous capture | C++ / C | Desktop |

bindings/rust/README.md

@@ -31,7 +31,7 @@ If you want the crate name in code to be `ccap` (recommended), set it explicitly
 ccap = { package = "ccap-rs", version = "<latest>" }
 ```
 
-> Tip: Replace `<latest>` with the latest version shown on https://crates.io/crates/ccap-rs
+> Tip: Replace `<latest>` with the latest version shown on <https://crates.io/crates/ccap-rs>
 
 ### Basic Usage
 
@@ -94,12 +94,8 @@ cargo run --example capture_callback
 
 This crate supports two build modes:
 
-- **Distribution mode (default):** `build-source`
-    - Builds the native C/C++ implementation via the `cc` crate.
-    - Intended for crates.io users.
-- **Development mode:** `static-link`
-    - Links against a pre-built native library from a CameraCapture checkout (e.g. `build/Debug/libccap.a`).
-    - Intended for developing this repository.
+- **Distribution mode (default):** `build-source` — Builds the native C/C++ implementation via the `cc` crate (intended for crates.io users).
+- **Development mode:** `static-link` — Links against a pre-built native library from a CameraCapture checkout (e.g. `build/Debug/libccap.a`) (intended for developing this repository).
 
 ### Prerequisites
 
@@ -142,21 +138,16 @@ An ASan-instrumented `libccap.a` requires the ASan runtime at link/run time.
 
 - When using `static-link`, `build.rs` will **only** link the ASan runtime **if it detects** ASan symbols inside the prebuilt `libccap.a`.
 - This does **not** affect the default crates.io build (`build-source`).
-- You can disable the auto-link behavior by setting:
-    - `CCAP_RUST_NO_ASAN_LINK=1`
+- You can disable the auto-link behavior by setting `CCAP_RUST_NO_ASAN_LINK=1`.
 
 ## Feature flags
 
 - `build-source` (default): build the C/C++ ccap sources during `cargo build` (best for crates.io usage).
-- `static-link`: link against a pre-built static library from a CameraCapture checkout (best for development).
-    - If you use this mode, make sure you have built the C/C++ project first, and set `CCAP_SOURCE_DIR` when needed.
+- `static-link`: link against a pre-built static library from a CameraCapture checkout (best for development). If you use this mode, make sure you have built the C/C++ project first, and set `CCAP_SOURCE_DIR` when needed.
 
 ## Platform notes
 
-- Camera capture:
-    - Windows: DirectShow
-    - macOS/iOS: AVFoundation
-    - Linux: V4L2
+- Camera capture: Windows (DirectShow), macOS/iOS (AVFoundation), Linux (V4L2)
 - Video file playback support depends on the underlying C/C++ library backend (currently Windows/macOS only).
 
 ## API Documentation
@@ -193,12 +184,12 @@ match provider.grab_frame(3000) {  // 3 second timeout
 
 ## Platform Support
 
-| Platform | Backend | Status |
-|----------|---------|---------|
-| Windows  | DirectShow | ✅ Supported |
+| Platform | Backend      | Status       |
+| -------- | ------------ | ------------ |
+| Windows  | DirectShow   | ✅ Supported |
 | macOS    | AVFoundation | ✅ Supported |
 | iOS      | AVFoundation | ✅ Supported |
-| Linux    | V4L2 | ✅ Supported |
+| Linux    | V4L2         | ✅ Supported |
 
 ## System Requirements
 

bindings/rust/build_and_test.sh

@@ -4,6 +4,25 @@
 
 set -e
 
+jobs_count() {
+    # Cross-platform parallelism detection.
+    if command -v nproc >/dev/null 2>&1; then
+        nproc
+        return
+    fi
+
+    if command -v sysctl >/dev/null 2>&1; then
+        # macOS / BSD
+        sysctl -n hw.ncpu 2>/dev/null && return
+    fi
+
+    if command -v getconf >/dev/null 2>&1; then
+        getconf _NPROCESSORS_ONLN 2>/dev/null && return
+    fi
+
+    echo 4
+}
+
 detect_cli_devices() {
     local cli_bin=""
     local original_dir
@@ -27,12 +46,18 @@ detect_cli_devices() {
 
         # Reconfigure with CLI enabled (idempotent)
         cmake ../.. -DCMAKE_BUILD_TYPE=Debug -DCCAP_BUILD_CLI=ON
-        cmake --build . --config Debug --target ccap-cli -- -j"$(nproc 2>/dev/null || echo 4)"
+        cmake --build . --config Debug --target ccap-cli -- -j"$(jobs_count)"
 
         popd >/dev/null
         popd >/dev/null
 
-        cli_bin="$PROJECT_ROOT/build/Debug/ccap"
+        if [ -x "$PROJECT_ROOT/build/Debug/ccap" ]; then
+            cli_bin="$PROJECT_ROOT/build/Debug/ccap"
+        elif [ -x "$PROJECT_ROOT/build/Debug/ccap.exe" ]; then
+            cli_bin="$PROJECT_ROOT/build/Debug/ccap.exe"
+        else
+            cli_bin="$PROJECT_ROOT/build/Debug/ccap"
+        fi
     fi
 
     cd "$original_dir"
@@ -94,7 +119,7 @@ if [ ! -f "$PROJECT_ROOT/build/Debug/libccap.a" ] && [ ! -f "$PROJECT_ROOT/build
         cmake ../.. -DCMAKE_BUILD_TYPE=Debug
     fi
 
-    cmake --build . --config Debug -- -j"$(nproc 2>/dev/null || echo 4)"
+    cmake --build . --config Debug -- -j"$(jobs_count)"
 
     cd "$RUST_DIR"
 else
@@ -113,7 +138,6 @@ cargo clean
 echo "Building with default features..."
 cargo build
 
-
 # Run tests
 echo ""
 echo "Step 3: Running tests..."
@@ -203,4 +227,3 @@ echo "  cargo run --example capture_callback"
 echo ""
 echo "To use in your project, add to Cargo.toml:"
 echo '  ccap = { package = "ccap-rs", path = "'$RUST_DIR'" }'
-echo '  ccap = { package = "ccap-rs", path = "'$RUST_DIR'" }'

bindings/rust/src/provider.rs

@@ -212,6 +212,11 @@ impl Provider {
         if let Some(name) = device_name {
             // Recreate provider with specific device
             if !self.handle.is_null() {
+                // If the previous provider was running, stop it and detach callbacks
+                // before destroying the underlying handle.
+                let _ = self.stop_capture();
+                let _ = self.remove_new_frame_callback();
+                self.cleanup_callback();
                 unsafe {
                     sys::ccap_provider_destroy(self.handle);
                 }
@@ -284,8 +289,18 @@ impl Provider {
 
     /// Set camera resolution
     pub fn set_resolution(&mut self, width: u32, height: u32) -> Result<()> {
+        // Avoid leaving the device in a partially-updated state if only one property update
+        // succeeds (e.g. width succeeds but height fails).
+        let (old_w, old_h) = self.resolution()?;
+
         self.set_property(PropertyName::Width, width as f64)?;
-        self.set_property(PropertyName::Height, height as f64)?;
+        if let Err(e) = self.set_property(PropertyName::Height, height as f64) {
+            // Best-effort rollback.
+            let _ = self.set_property(PropertyName::Width, old_w as f64);
+            let _ = self.set_property(PropertyName::Height, old_h as f64);
+            return Err(e);
+        }
+
         Ok(())
     }
 
@@ -383,6 +398,9 @@ impl Provider {
     /// This is a **global** callback that persists until replaced or cleared.
     /// Calling this function multiple times will properly clean up the previous callback.
     ///
+    /// **Important**: this callback is process-global (shared by all `Provider` instances).
+    /// The last one set wins.
+    ///
     /// # Thread Safety
     ///
     /// The callback will be invoked from the camera capture thread. Ensure your
@@ -443,6 +461,16 @@ impl Provider {
         }
     }
 
+    /// Set the **global** error callback.
+    ///
+    /// This is an alias for [`Provider::set_error_callback`] to make the global scope explicit.
+    pub fn set_global_error_callback<F>(callback: F)
+    where
+        F: Fn(i32, &str) + Send + Sync + 'static,
+    {
+        Self::set_error_callback(callback)
+    }
+
     /// Clear the global error callback
     ///
     /// This removes the error callback and frees associated memory.
@@ -451,15 +479,25 @@ impl Provider {
 
         // Use module-level GLOBAL_ERROR_CALLBACK (same as set_error_callback)
         if let Ok(mut guard) = GLOBAL_ERROR_CALLBACK.lock() {
+            // Always clear the C-side callback even if we don't have a stored Rust callback.
+            unsafe {
+                sys::ccap_set_error_callback(None, ptr::null_mut());
+            }
             if let Some(SendSyncPtr(old_ptr)) = guard.take() {
                 unsafe {
                     let _ = Box::from_raw(old_ptr as *mut ErrorCallbackBox);
-                    sys::ccap_set_error_callback(None, ptr::null_mut());
                 }
             }
         }
     }
 
+    /// Clear the **global** error callback.
+    ///
+    /// This is an alias for [`Provider::clear_error_callback`] to make the global scope explicit.
+    pub fn clear_global_error_callback() {
+        Self::clear_error_callback()
+    }
+
     /// Open device with index and auto start
     pub fn open_with_index(&mut self, device_index: i32, auto_start: bool) -> Result<()> {
         // Destroy old handle if exists

scripts/test_remote_crate.sh

@@ -117,13 +117,13 @@ PY
 
     # Get the actual version being used
     log "Running cargo update..."
-    if ! cargo update --quiet 2>&1; then
-        warn "cargo update had warnings/errors, continuing..."
+    if ! cargo update --quiet; then
+        warn "cargo update failed (possibly offline or registry issues). Continuing..."
     fi
 
     local actual_version
-    actual_version=$(cargo metadata --format-version=1 --no-deps 2>/dev/null |
-        python3 -c "import sys, json; data = json.load(sys.stdin); pkg = next((p for p in data.get('packages', []) if p.get('name') == 'ccap-rs'), None); print(pkg['version'] if pkg else 'unknown')" 2>/dev/null || echo "unknown")
+    actual_version=$(cargo metadata --format-version=1 2>/dev/null |
+        python3 -c "import sys, json; data = json.load(sys.stdin); pkgs = data.get('packages', []); pkg = next((p for p in pkgs if p.get('name') == 'ccap-rs'), None); print(pkg.get('version') if pkg else 'unknown')" 2>/dev/null || echo "unknown")
 
     log "Testing ccap-rs version: ${actual_version}"