//! Shared trampoline-slot pool for closure-driven audio callbacks.
//!
//! raylib's C-side audio processors (`AttachAudioStreamProcessor`,
//! `AttachAudioMixedProcessor`) accept only a function pointer — no
//! user-data parameter. To thread closure state through, we
//! pre-register **30 trampolines** (named `callback_0` through
//! `callback_29`), each with its own
//! `LazyLock<Mutex<AudioCallbackWithUserData>>` slot. A consumer
//! reserves a free slot via [`set_context`], the trampoline for that
//! slot looks up the closure context, and [`clear_context`] frees the
//! slot.
//!
//! Consumers:
//! - Per-stream: [`attach_audio_stream_processor_with_user_data`] /
//!   [`detach_audio_stream_processor_with_user_data`].
//! - Mixed bus: [`attach_audio_mixed_processor_with_user_data`] /
//!   [`detach_audio_mixed_processor_with_user_data`].
//!
//! Both consumers share the same 30-slot pool. The file is named
//! `stream_processor_with_user_data_wrapper.rs` for historical
//! reasons; it now covers both kinds of audio processors.

git add raylib/src/core/callbacks/stream_processor_with_user_data_wrapper.rs
git commit -m "$(cat <<'EOF'
refactor(audio-callbacks): bump slot primitives to pub(crate) + module-level doc

Widens visibility on `set_context` / `clear_context` / `get_callback`
inside the slot-pool macro expansion so the upcoming mixed-bus
consumer can call them. Also replaces the legacy region comments
with a proper module-level doc comment explaining the shared
30-slot pool serves both per-stream and mixed-bus audio processors.

No public API change; no functional change.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

/// Attach a closure-driven processor to raylib's global mixed audio
/// bus. Reserves a slot from the shared 30-slot pool and calls the
/// C-side `AttachAudioMixedProcessor` with that slot's trampoline.
///
/// Returns the slot index — pass it to
/// [`detach_audio_mixed_processor_with_user_data`] when the consumer
/// drops.
pub(crate) fn attach_audio_mixed_processor_with_user_data(
    callback: AudioCallbackWithUserData,
) -> usize {
    let idx = set_context(callback);
    // SAFETY: get_callback(idx) returns the trampoline matching the
    // slot we just reserved; raylib copies the fn pointer into its
    // linked-list entry. We hold the slot until drop calls detach +
    // clear_context.
    unsafe {
        raylib_sys::AttachAudioMixedProcessor(Some(get_callback(idx)));
    }
    idx
}

/// Detach the closure-driven mixed-bus processor and clear the slot.
///
/// Calls the C-side `DetachAudioMixedProcessor` with the same
/// trampoline pointer registered for `index`, so raylib's internal
/// list-search matches and the entry is removed. The slot is only
/// cleared AFTER the C side has stopped iterating it — without this
/// the closure could still receive one more invocation against freed
/// state (same lifecycle ordering as the per-stream sibling fixed in
/// WS8e).
pub(crate) fn detach_audio_mixed_processor_with_user_data(index: usize) {
    let trampoline = get_callback(index);
    // SAFETY: trampoline is the same fn pointer raylib stored at
    // attach time; the C-side list-search matches and removes the
    // entry. clear_context runs AFTER detach completes so raylib has
    // stopped iterating before the closure context disappears.
    unsafe {
        raylib_sys::DetachAudioMixedProcessor(Some(trampoline));
    }
    clear_context(index);
}

git add raylib/src/core/callbacks/stream_processor_with_user_data_wrapper.rs
git commit -m "$(cat <<'EOF'
feat(audio-callbacks): add mixed-bus attach/detach helpers (pub(crate))

Two new `pub(crate)` helpers in the slot-pool file that mirror the
per-stream attach/detach pattern but invoke
AttachAudioMixedProcessor / DetachAudioMixedProcessor instead of
the per-stream FFI calls.

Lifecycle correctness mirrors the WS8e per-stream fix: the detach
helper calls DetachAudioMixedProcessor BEFORE clear_context, so
raylib's internal list-walk has stopped iterating the slot before
the closure context disappears.

No public API yet — the `pub` user-facing entry point lands in
the next task.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

use crate::core::audio::{Music, RaylibAudio};

use crate::core::audio::RaylibAudio;

// region: -- MixedAudioProcessorCallback --

/// Closure-driven processor attached to raylib's **global mixed audio
/// bus**.
///
/// The processor receives every stereo frame after raylib has mixed
/// all playing streams. Multiple `MixedAudioProcessorCallback`
/// instances can be attached simultaneously; they form a chain in
/// raylib's internal linked list and run in attach-order on each
/// frame.
///
/// This is a guard type — drop it to detach. Users obtain one via
/// [`attach_audio_mixed_processor`]; direct construction is not
/// supported (no public constructor).
pub struct MixedAudioProcessorCallback<'a, F>
where
    F: FnMut(&mut [f32], u32) + Send + 'static,
{
    rust_callback: &'a mut F,
    /// Set after `attach_audio_mixed_processor_with_user_data` succeeds.
    /// `None` only during the construction window before attach.
    callback_index: Option<usize>,
}

impl<'a, F> MixedAudioProcessorCallback<'a, F>
where
    F: FnMut(&mut [f32], u32) + Send + 'static,
{
    fn new(closure: &'a mut F) -> Self {
        Self {
            rust_callback: closure,
            callback_index: None,
        }
    }

    fn get_as_user_data(&mut self) -> *mut ::std::os::raw::c_void {
        self as *mut Self as *mut ::std::os::raw::c_void
    }

    fn get_c_callback(
        &mut self,
    ) -> extern "C" fn(
        *mut ::std::os::raw::c_void,
        *mut ::std::os::raw::c_void,
        ::std::os::raw::c_uint,
    ) -> () {
        Self::c_callback
    }

    extern "C" fn c_callback(
        user_data: *mut ::std::os::raw::c_void,
        data_ptr: *mut ::std::os::raw::c_void,
        frame_count: ::std::os::raw::c_uint,
    ) {
        // SAFETY: user_data is `*mut Self` per get_as_user_data; the
        // wrapping Pin<Box<Self>> keeps it stable for the guard's
        // lifetime, which outlives every callback firing per the
        // &'a RaylibAudio borrow. data_ptr is `frame_count * 2 *
        // sizeof(f32)` interleaved stereo bytes (mixed bus is always
        // stereo per raylib.h:1736).
        unsafe {
            let cb: &mut Self = user_data.cast::<Self>().as_mut().unwrap();
            let data = std::slice::from_raw_parts_mut(
                data_ptr as *mut f32,
                frame_count as usize * 2,
            );
            (cb.rust_callback)(data, 2);
        }
    }
}

impl<F> Drop for MixedAudioProcessorCallback<'_, F>
where
    F: FnMut(&mut [f32], u32) + Send + 'static,
{
    fn drop(&mut self) {
        if let Some(idx) = self.callback_index {
            detach_audio_mixed_processor_with_user_data(idx);
        }
    }
}

// endregion: -- MixedAudioProcessorCallback --

use super::callbacks::stream_processor_with_user_data_wrapper::{
    AudioCallbackWithUserData,
    attach_audio_mixed_processor_with_user_data,
    attach_audio_stream_processor_with_user_data,
    detach_audio_mixed_processor_with_user_data,
    detach_audio_stream_processor_with_user_data,
};

git add raylib/src/core/callbacks.rs
git commit -m "$(cat <<'EOF'
feat(audio-callbacks): add MixedAudioProcessorCallback struct + impl + Drop

Mirrors AudioStreamProcessorCallback's shape but for raylib's global
mixed audio bus. Differences from the per-stream sibling:
- No `stream` field (mixed bus is global, not per-stream).
- Drop calls detach_audio_mixed_processor_with_user_data with just
  the slot index (no stream argument needed by the FFI).
- c_callback hardcodes `nb_channels = 2` (mixed bus is always
  stereo per raylib.h:1736).

The struct uses the existing 30-slot trampoline pool, so a
MixedAudioProcessorCallback + a per-stream
AudioStreamProcessorCallback compete for the same 30 slots.

No public attach fn yet — that lands in the next task.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

/// Attach a closure to raylib's **global mixed audio bus**, returning
/// a pinned guard that detaches on drop.
///
/// The callback fires from raylib's internal audio thread, receiving
/// **interleaved stereo** frames (`channels == 2` always — raylib
/// mixes all playing streams down to stereo before invoking the
/// processor). Multiple `MixedAudioProcessorCallback` instances can
/// be attached simultaneously and run in attach-order.
///
/// # Closure constraints
///
/// `F: FnMut(&mut [f32], u32) + Send + 'static`:
/// - `Send + 'static` because the callback runs on raylib's audio
///   thread.
/// - The closure receives a mutable slice of `frame_count * 2`
///   interleaved stereo samples plus the channel count (always `2`).
///   Modifying the slice in-place applies the effect to the mixed
///   bus.
///
/// # Slot pool exhaustion
///
/// The crate supports up to **30 simultaneous** audio-processor
/// closures (shared pool across per-stream and mixed-bus consumers).
/// Attaching a 31st processor panics with `"index out of bounds"`.
/// Detach existing processors (drop their guards) to free slots.
///
/// # Thread safety
///
/// raylib's `AttachAudioMixedProcessor` /
/// `DetachAudioMixedProcessor` are internally mutex-guarded; attach
/// and drop are safe to call from any thread.
pub fn attach_audio_mixed_processor<'a, F>(
    _audio: &'a RaylibAudio,
    processor: &'a mut F,
) -> Pin<Box<MixedAudioProcessorCallback<'a, F>>>
where
    F: FnMut(&mut [f32], u32) + Send + 'static, // static because the function is executed in another thread
{
    let mut cb = Box::new(MixedAudioProcessorCallback::<'a, F>::new(processor));
    let idx = attach_audio_mixed_processor_with_user_data(AudioCallbackWithUserData::new(
        cb.get_as_user_data(),
        cb.get_c_callback(),
    ));
    cb.callback_index = Some(idx);
    Box::into_pin(cb)
}

git add raylib/src/core/callbacks.rs
git commit -m "$(cat <<'EOF'
feat(audio-callbacks): public attach_audio_mixed_processor free fn

User-facing entry point. Mirrors attach_audio_stream_processor_to_music
but takes `&'a RaylibAudio` instead of `&'a Music` — the mixed bus
is global to the audio device, not tied to a single playing stream.

Returns Pin<Box<MixedAudioProcessorCallback>> as a guard. Drop calls
DetachAudioMixedProcessor + clear_context (same lifecycle ordering
as the WS8e per-stream fix).

Rustdoc covers the closure constraints (Send + 'static; stereo-only
buffer), the 30-slot shared-pool exhaustion ceiling, and the C-side
thread-safety story (mutex-guarded attach/detach).

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

#[cfg(test)]
#[cfg(feature = "software_renderer")]
mod mixed_audio_tests {
    use super::*;
    use crate::core::audio::RaylibAudio;

    /// Attaching a mixed-bus processor and immediately dropping the
    /// guard must not panic. Proves the slot pool + Drop's
    /// DetachAudioMixedProcessor + clear_context all work together.
    #[test]
    fn attach_then_drop_does_not_panic() {
        crate::test_harness::with_headless(1, 1, |_rl, _thread| {
            let audio = RaylibAudio::init_audio_device().expect("audio init");
            let mut closure = |_samples: &mut [f32], _ch: u32| {};
            {
                let _guard = attach_audio_mixed_processor(&audio, &mut closure);
                // Guard dropped at end of scope — detach + slot clear.
            }
            // If we got here without panic, attach + drop both worked.
        });
    }

    /// Multiple simultaneous processors plus out-of-order drops must
    /// not corrupt the slot pool or raylib's linked list.
    #[test]
    fn multiple_processors_attach_and_drop_independently() {
        crate::test_harness::with_headless(1, 1, |_rl, _thread| {
            let audio = RaylibAudio::init_audio_device().expect("audio init");
            let mut closure_a = |_s: &mut [f32], _c: u32| {};
            let mut closure_b = |_s: &mut [f32], _c: u32| {};
            let guard_a = attach_audio_mixed_processor(&audio, &mut closure_a);
            let guard_b = attach_audio_mixed_processor(&audio, &mut closure_b);
            // Drop in reverse order; both should clean up.
            drop(guard_b);
            drop(guard_a);
        });
    }
}

cargo test -p raylib --lib --no-default-features --features software_renderer,SUPPORT_MODULE_RSHAPES,SUPPORT_MODULE_RTEXT,SUPPORT_MODULE_RTEXTURES,SUPPORT_MODULE_RAUDIO,SUPPORT_FILEFORMAT_PNG mixed_audio_tests -- --test-threads=1 2>&1 | tail -10

git add raylib/src/core/callbacks.rs
git commit -m "$(cat <<'EOF'
test(mixed-audio): Tier-2 lifecycle tests for attach + drop

Two #[test] fns in a new mixed_audio_tests module at the bottom of
callbacks.rs, gated on feature = "software_renderer":

- attach_then_drop_does_not_panic: single attach + scope-exit drop
  through with_headless + init_audio_device. Proves slot pool +
  Drop's DetachAudioMixedProcessor + clear_context all work together.
- multiple_processors_attach_and_drop_independently: two
  simultaneous attaches + out-of-order drops. Proves the slot pool
  + raylib's linked list survive multi-consumer churn.

Tests require `-- --test-threads=1` per raylib's single-init lock —
matches WS4/WS5 conventions in test.yml.

Firing-correctness ("did the closure actually get invoked?") is
deferred to a future window-opening integration suite per spec §11.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

cargo test -p raylib --lib --no-default-features --features software_renderer,SUPPORT_MODULE_RSHAPES,SUPPORT_MODULE_RTEXT,SUPPORT_MODULE_RTEXTURES,SUPPORT_MODULE_RAUDIO,SUPPORT_FILEFORMAT_PNG -- --test-threads=1 2>&1 | tail -10

- ✅ `AttachAudioMixedProcessor` — wrapped at `raylib/src/core/callbacks.rs::attach_audio_mixed_processor`.
- ✅ `DetachAudioMixedProcessor` — wrapped via `MixedAudioProcessorCallback::Drop` in `raylib/src/core/callbacks.rs`.

- **mixed-audio** ✅ — `MixedAudioProcessorCallback` + `attach_audio_mixed_processor` at `raylib/src/core/callbacks.rs`. RAII guard borrows `&'a RaylibAudio`; Drop detaches before clearing the slot. Tier-2 lifecycle tests under `software_renderer`.

- **Mixed audio bus:** new public API for closure-driven processors on
  raylib's global mixed audio bus:
  - `attach_audio_mixed_processor(audio: &RaylibAudio, processor: &mut F) -> Pin<Box<MixedAudioProcessorCallback<'_, F>>>`
    where `F: FnMut(&mut [f32], u32) + Send + 'static`.
  - `MixedAudioProcessorCallback` — the RAII guard type. Dropping it
    calls `DetachAudioMixedProcessor` and frees the closure slot,
    mirroring the WS8e per-stream-processor soundness fix.
  - Multiple mixed-bus processors can be attached simultaneously
    (they chain in raylib's internal linked list). They share the
    same 30-slot trampoline pool with the per-stream processors.
  - Re-exported via `raylib::prelude`. Closes the `mixed-audio`
    workstream from the cheatsheet-parity audit.

  Also updates the "post-WS8 workstreams" note at the top of the
  6.0.0-rc.1 block: mixed-audio drops out of the list.

> Release candidate 1 for the 6.0 line — the published crate versions are
> `6.0.0-rc.1` while the post-WS8 workstreams (WS9 showcase ...) settle.

git add docs/superpowers/notes/cheatsheet-parity-audit.md CHANGELOG.md
git commit -m "$(cat <<'EOF'
docs(mixed-audio): mark AttachAudioMixedProcessor / DetachAudioMixedProcessor as covered

The mixed-audio workstream from cheatsheet-parity-audit.md §4 is
done; reconcile the audit + CHANGELOG accordingly.

- cheatsheet-parity-audit.md:
  - §1 entries for AttachAudioMixedProcessor + DetachAudioMixedProcessor
    flip 🟥 -> ✅ pointing at raylib/src/core/callbacks.rs (the attach
    fn + MixedAudioProcessorCallback's Drop respectively).
  - §0 totals: Covered 492 -> 494, gaps 7 -> 5, medium workstreams 2 -> 1.
  - §4 mixed-audio workstream moved to the "Done (this audit)"
    subsection.
- CHANGELOG.md ## 6.0.0-rc.1 (unreleased) ### Added: lists the new
  attach_audio_mixed_processor + MixedAudioProcessorCallback with a
  reference to the WS8e per-stream-processor soundness pattern.
  Lead-paragraph note drops mixed-audio from the post-WS8 workstreams
  list (now empty for this group; only WS9 + final-release remain).

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

pixel-pointers ✅ → hashes ✅ → mixed-audio ✅ → raylib-test ← NEXT → ...

git add CLAUDE.md
git commit -m "$(cat <<'EOF'
docs(roadmap): mixed-audio complete; raylib-test is next

CLAUDE.md status line: pre-WS9 queue head flips from mixed-audio to
raylib-test. See docs/superpowers/notes/cheatsheet-parity-audit.md
for the updated cheatsheet coverage (494 / 500 in-scope; 5 gaps
remain in the rtext/rfilesystem out-of-scope sections).

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"
git push fork 6.0-rc 2>&1 | tail -3
git push fork 6.0-rc:unstable 2>&1 | tail -3