From 34d18c4152d016b1e1bc5fd02252fb5d537b89fe Mon Sep 17 00:00:00 2001
From: Noah <noahcorona231@gmail.com>
Date: Sat, 9 May 2026 00:56:11 -0700
Subject: [PATCH 1/4] feat(phase-3b T6): voice-note card + single-instance
 VoiceNotePlayer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces the `<AttachmentVoiceNote>` placeholder with the full
spec surface from `docs/specs/2026-04-19-ui-design/files-inline.md`
§Voice note:

- Card on `--bg-2` with `--line` border, radius 10 px, 10/12
  padding, max-width 420 px (100% on mobile).
- 32×32 play / pause IconBtn (`--moss-2` border, switches between
  `icon_play` / `icon_pause` glyphs added in this commit).
- Waveform strip — fixed 24 px tall SVG with 64 bars, `--moss-1`
  for unplayed and `--moss-2` for played. Peaks come from
  `AudioContext.decodeAudioData` over the fetched blob; on decode
  failure (codec unsupported, AudioContext unavailable) the strip
  stays at the flat 0.05 baseline so the chrome reads as "loading"
  rather than "broken".
- mm:ss / mm:ss timer in the spec mono font / 11 px / `--ink-3`,
  with `--:--` for the duration until `loadedmetadata` fires.

Single-instance playback (`VoiceNotePlayer` in
`crates/web/src/voice_note_player.rs`): each card claims the player
slot on play and watches the shared signal so a competing claim
pauses our `<audio>` element. `release_if_active` only clears when
the active id matches us, so a stale paused-card can't pre-empt a
fresh claim from somebody else.

Bytes flow: fetch the blob via `WebClientHandle::fetch_blob`, build
a `blob:` Object URL on the card-local `<audio>` (revoked via
`on_cleanup` so a long-running session doesn't leak URLs), and in
parallel spawn the AudioContext decode for waveform peaks. The two
paths are independent — playback works even if waveform decoding
fails.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 crates/web/Cargo.toml                         |   1 +
 crates/web/src/app.rs                         |   5 +
 .../src/components/attachment/voice_note.rs   | 422 +++++++++++++++++-
 crates/web/src/components/message.rs          |   6 +-
 crates/web/src/icons.rs                       |  18 +
 crates/web/src/lib.rs                         |   1 +
 crates/web/src/voice_note_player.rs           |  93 ++++
 crates/web/style.css                          |  91 ++++
 8 files changed, 627 insertions(+), 10 deletions(-)
 create mode 100644 crates/web/src/voice_note_player.rs

diff --git a/crates/web/Cargo.toml b/crates/web/Cargo.toml
index 367fd4dc..359d7cbc 100644
--- a/crates/web/Cargo.toml
+++ b/crates/web/Cargo.toml
@@ -33,6 +33,7 @@ web-sys = { version = "0.3", features = [
     "ScrollIntoViewOptions", "ScrollBehavior", "ScrollLogicalPosition",
     "DisplayMediaStreamConstraints",
     "AudioContext", "BaseAudioContext", "AudioNode",
+    "AudioBuffer",
     "AnalyserNode", "MediaStreamAudioSourceNode",
     "RtcSignalingState", "RtcRtpTransceiver",
     "Response", "Headers",
diff --git a/crates/web/src/app.rs b/crates/web/src/app.rs
index 2f6e40ae..c2fb7dbf 100644
--- a/crates/web/src/app.rs
+++ b/crates/web/src/app.rs
@@ -192,6 +192,11 @@ pub fn App() -> impl IntoView {
     // the same `UploadQueue`.
     provide_context(crate::upload_state::UploadQueue::new());
 
+    // Phase 3b T6 — single-instance voice-note player. Each
+    // `<AttachmentVoiceNote>` reads this from context to coordinate
+    // "starting one pauses any other" per spec §Voice note.
+    provide_context(crate::voice_note_player::VoiceNotePlayer::new());
+
     // Phase 3c.3 — per-channel reaction recency. Drives the picker's
     // "recent" shelf in both the composer's emoji button and the
     // row's "more reactions" toolbar. The Resource refreshes when
diff --git a/crates/web/src/components/attachment/voice_note.rs b/crates/web/src/components/attachment/voice_note.rs
index 8d1b5876..4a956700 100644
--- a/crates/web/src/components/attachment/voice_note.rs
+++ b/crates/web/src/components/attachment/voice_note.rs
@@ -1,21 +1,425 @@
 //! `<AttachmentVoiceNote>` — voice-note playback card per
 //! `docs/specs/2026-04-19-ui-design/files-inline.md` §Voice note.
 //!
-//! T6 of the phase-3b plan lands the full surface (play / pause IconBtn,
-//! `<audio>` element, mm:ss / mm:ss timer, single-instance playback
-//! coordinated by `VoiceNotePlayer`). This file is the placeholder
-//! shipped alongside the [`super::pick`] decision table.
+//! Lays out the spec card (`--bg-2` on `--line`, radius 10 px,
+//! `10/12` padding, `max-width: 420px` desktop), with:
+//!
+//! - Play / pause IconBtn (32×32, `--moss-2` foreground).
+//! - Waveform strip (fixed 24 px tall, `--moss-1` bars on `--bg-1`,
+//!   with a `--moss-2` progress fill on the played portion).
+//! - Timer in the spec mono font (`mm:ss / mm:ss`).
+//!
+//! Single-instance playback is coordinated via
+//! [`crate::voice_note_player::VoiceNotePlayer`]: each card writes
+//! its own id when it starts, and watches the shared signal so a
+//! competing claim pauses our `<audio>` element.
+//!
+//! Bytes flow: on mount we fetch the blob, build a `blob:` Object
+//! URL on the card's `<audio>`, and (in parallel) decode the same
+//! bytes via `AudioContext.decodeAudioData` to extract a tiny peak
+//! summary used to draw the waveform. Decode failures fall back to a
+//! flat baseline waveform — playback still works because the
+//! `<audio>` element handles its own decode.
 
 use leptos::prelude::*;
+use wasm_bindgen::JsCast;
 
-/// Placeholder voice-note component.
+use crate::app::WebClientHandle;
+use crate::icons;
+use crate::voice_note_player::use_voice_note_player;
+
+/// Number of waveform bars per card. 64 keeps the SVG cheap to
+/// render and lines up with the spec's "fixed height 24 px" strip
+/// at typical desktop widths.
+const WAVEFORM_BARS: usize = 64;
+
+/// Voice-note card. Fetches the blob, decodes it for waveform peaks,
+/// and drives playback through a card-local `<audio>` element while
+/// the [`crate::voice_note_player::VoiceNotePlayer`] context arbiters
+/// single-instance.
 ///
-/// **Stub.** The full component lands in T6.
+/// Stable id derives from the blob hash + filename so each row in the
+/// chat keeps the same identity across re-renders. The hash alone is
+/// content-addressed (great for dedup) but two messages quoting the
+/// same file would share an id and pause each other on play; pairing
+/// with the filename keeps that edge-case sane.
 #[component]
-pub fn AttachmentVoiceNote(filename: String) -> impl IntoView {
+pub fn AttachmentVoiceNote(
+    /// Hex-encoded blob hash from `EventKind::FileMessage::hash`.
+    hash: String,
+    /// Sender-declared filename, surfaced in the IconBtn's
+    /// `aria-label` so screen readers identify which clip is being
+    /// played.
+    filename: String,
+    /// Sender-declared size in bytes — display only. Reserved for a
+    /// future "Xs · 12 KB" subtitle row; today we don't render it.
+    size_bytes: u64,
+) -> impl IntoView {
+    let _ = size_bytes;
+    let id = format!("vn-{}-{}", &hash[..hash.len().min(12)], filename);
+    let player = use_voice_note_player();
+    let handle = use_context::<WebClientHandle>();
+    let audio_ref = NodeRef::<leptos::html::Audio>::new();
+
+    let (src, set_src) = signal(String::new());
+    let (peaks, set_peaks) = signal::<Vec<f32>>(vec![0.05; WAVEFORM_BARS]);
+    let (current, set_current) = signal(0.0_f64);
+    let (duration, set_duration) = signal(0.0_f64);
+    let (playing, set_playing) = signal(false);
+
+    // Fetch + decode the blob on mount. Object URL feeds <audio>;
+    // decoded peaks feed the waveform. Independent paths — a decode
+    // failure leaves the flat baseline waveform but playback still
+    // works because <audio> handles its own decode.
+    let fetch_hash = hash.clone();
+    Effect::new(move |_| {
+        let Some(handle) = handle.clone() else {
+            return;
+        };
+        let Some(blob_hash) = willow_client::hex_to_blob_hash(&fetch_hash) else {
+            tracing::warn!(hash = %fetch_hash, "AttachmentVoiceNote: malformed hex hash");
+            return;
+        };
+        wasm_bindgen_futures::spawn_local(async move {
+            let bytes = match handle.fetch_blob(blob_hash).await {
+                Ok(Some(b)) => b,
+                Ok(None) => {
+                    tracing::warn!("AttachmentVoiceNote: blob not available locally");
+                    return;
+                }
+                Err(e) => {
+                    tracing::warn!(error = ?e, "AttachmentVoiceNote: blob fetch failed");
+                    return;
+                }
+            };
+            // Build the playable Object URL first so the user can
+            // press play even if waveform decoding takes longer.
+            if let Some(url) = bytes_to_object_url(&bytes) {
+                let url_for_cleanup = url.clone();
+                on_cleanup(move || {
+                    let _ = web_sys::Url::revoke_object_url(&url_for_cleanup);
+                });
+                set_src.set(url);
+            }
+            decode_peaks_async(bytes, WAVEFORM_BARS, set_peaks);
+        });
+    });
+
+    // Pause us when somebody else claims the player slot.
+    let id_for_effect = id.clone();
+    Effect::new(move |_| {
+        let active = player.active.get();
+        if active.as_deref() != Some(&id_for_effect) {
+            if let Some(el) = audio_ref.get() {
+                if !el.paused() {
+                    let _ = el.pause();
+                }
+            }
+            // Mirror in our own `playing` signal so the icon flips
+            // back to `play` even when the pause came from outside.
+            set_playing.set(false);
+        }
+    });
+
+    let id_play = id.clone();
+    let on_toggle = move |_ev: web_sys::MouseEvent| {
+        let Some(el) = audio_ref.get() else {
+            return;
+        };
+        if el.paused() {
+            player.claim(id_play.clone());
+            // play() returns a Promise; we don't await — the `play`
+            // event will flip `playing` once the engine starts.
+            let _ = el.play();
+        } else {
+            let _ = el.pause();
+        }
+    };
+
+    let id_pause = id.clone();
+    let on_pause = move |_ev: web_sys::Event| {
+        set_playing.set(false);
+        player.release_if_active(&id_pause);
+    };
+    let on_play = move |_ev: web_sys::Event| {
+        set_playing.set(true);
+    };
+    let on_loaded_metadata = move |_ev: web_sys::Event| {
+        if let Some(el) = audio_ref.get() {
+            let dur = el.duration();
+            if dur.is_finite() {
+                set_duration.set(dur);
+            }
+        }
+    };
+    let on_time_update = move |_ev: web_sys::Event| {
+        if let Some(el) = audio_ref.get() {
+            set_current.set(el.current_time());
+        }
+    };
+    let id_ended = id.clone();
+    let on_ended = move |_ev: web_sys::Event| {
+        set_playing.set(false);
+        set_current.set(0.0);
+        player.release_if_active(&id_ended);
+    };
+
+    let aria_label_play = format!("play voice note {filename}");
+    let aria_label_pause = format!("pause voice note {filename}");
+    let aria_label_button = move || {
+        if playing.get() {
+            aria_label_pause.clone()
+        } else {
+            aria_label_play.clone()
+        }
+    };
+
+    let progress_ratio = Memo::new(move |_| {
+        let d = duration.get();
+        if d <= 0.0 {
+            0.0
+        } else {
+            (current.get() / d).clamp(0.0, 1.0)
+        }
+    });
+
     view! {
-        <div class="attachment attachment--voice-note" data-stub="t6-pending">
-            <span class="attachment__filename">{filename}</span>
+        <div class="attachment attachment--voice-note">
+            <button
+                class="attachment__voice-toggle"
+                type="button"
+                aria-label=aria_label_button
+                on:click=on_toggle
+            >
+                {move || if playing.get() {
+                    icons::icon_pause().into_any()
+                } else {
+                    icons::icon_play().into_any()
+                }}
+            </button>
+            <div class="attachment__voice-body">
+                <Waveform peaks=peaks progress=progress_ratio.into() />
+                <div class="attachment__voice-timer">
+                    {move || format_timer(current.get(), duration.get())}
+                </div>
+            </div>
+            <audio
+                node_ref=audio_ref
+                class="attachment__voice-audio"
+                preload="metadata"
+                src=move || src.get()
+                on:play=on_play
+                on:pause=on_pause
+                on:ended=on_ended
+                on:loadedmetadata=on_loaded_metadata
+                on:timeupdate=on_time_update
+            />
         </div>
     }
 }
+
+/// The waveform strip — `WAVEFORM_BARS` rect bars in an SVG, sized
+/// to fill the parent. Past the playback head, bars are `--moss-1`;
+/// before, `--moss-2`. The peaks signal updates once decoding lands;
+/// before then we render the flat baseline so the strip never has
+/// the "missing chrome" look of an empty SVG.
+#[component]
+fn Waveform(peaks: ReadSignal<Vec<f32>>, progress: Signal<f64>) -> impl IntoView {
+    let bars = move || {
+        let p = peaks.get();
+        let prog = progress.get();
+        let n = p.len().max(1) as f64;
+        let bar_w = 100.0 / n;
+        let played_bars = (prog * n).round() as usize;
+        p.into_iter()
+            .enumerate()
+            .map(|(i, peak)| {
+                let h = (peak.clamp(0.05, 1.0) as f64) * 100.0;
+                let y = 50.0 - h / 2.0;
+                let x = i as f64 * bar_w;
+                let class_attr = if i < played_bars {
+                    "attachment__voice-bar attachment__voice-bar--played"
+                } else {
+                    "attachment__voice-bar"
+                };
+                view! {
+                    <rect
+                        class=class_attr
+                        x=format!("{x:.3}%")
+                        y=format!("{y:.3}%")
+                        width=format!("{:.3}%", bar_w * 0.7)
+                        height=format!("{h:.3}%")
+                        rx="0.5"
+                    />
+                }
+            })
+            .collect_view()
+    };
+    view! {
+        <svg
+            class="attachment__voice-waveform"
+            viewBox="0 0 100 100"
+            preserveAspectRatio="none"
+            aria-hidden="true"
+        >
+            {bars}
+        </svg>
+    }
+}
+
+/// `mm:ss / mm:ss` timer per spec. NaN/infinite duration (e.g. while
+/// the file is still streaming the metadata header) renders as
+/// `--:--` for the total.
+pub(crate) fn format_timer(current: f64, duration: f64) -> String {
+    let cur = format_mm_ss(current);
+    let total = if duration.is_finite() && duration > 0.0 {
+        format_mm_ss(duration)
+    } else {
+        "--:--".to_string()
+    };
+    format!("{cur} / {total}")
+}
+
+fn format_mm_ss(seconds: f64) -> String {
+    if !seconds.is_finite() || seconds < 0.0 {
+        return "0:00".to_string();
+    }
+    let total = seconds.round() as i64;
+    let m = total / 60;
+    let s = total % 60;
+    format!("{m}:{s:02}")
+}
+
+/// Build a `blob:` Object URL for arbitrary audio bytes. We don't
+/// pass a MIME type because the `<audio>` element sniffs from the
+/// container; that keeps the helper agnostic to whatever codec the
+/// sender chose (webm/opus, mp3, ogg, etc.).
+fn bytes_to_object_url(data: &[u8]) -> Option<String> {
+    let array = js_sys::Uint8Array::from(data);
+    let parts = js_sys::Array::new();
+    parts.push(&array.buffer());
+    let blob = web_sys::Blob::new_with_u8_array_sequence(&parts).ok()?;
+    web_sys::Url::create_object_url_with_blob(&blob).ok()
+}
+
+/// Spawn the AudioContext decode + peak extraction on the JS event
+/// loop. On success, `set_peaks` receives `bars` peaks in `[0.05, 1.0]`.
+/// On any failure (decode error, AudioContext unavailable in this
+/// browser, etc.) the signal stays at its baseline default.
+fn decode_peaks_async(bytes: Vec<u8>, bars: usize, set_peaks: WriteSignal<Vec<f32>>) {
+    wasm_bindgen_futures::spawn_local(async move {
+        let ctx = match web_sys::AudioContext::new() {
+            Ok(c) => c,
+            Err(e) => {
+                tracing::debug!(?e, "AttachmentVoiceNote: AudioContext::new failed");
+                return;
+            }
+        };
+        let array = js_sys::Uint8Array::from(bytes.as_slice());
+        let buffer: js_sys::ArrayBuffer = array.buffer().unchecked_into();
+        let promise = match ctx.decode_audio_data(&buffer) {
+            Ok(p) => p,
+            Err(e) => {
+                tracing::debug!(?e, "AttachmentVoiceNote: decode_audio_data failed");
+                return;
+            }
+        };
+        let result = wasm_bindgen_futures::JsFuture::from(promise).await;
+        // Drop the AudioContext as soon as decoding settles, regardless
+        // of outcome — we never play audio through it, so holding it
+        // would just leak.
+        drop(ctx);
+        let buf = match result {
+            Ok(v) => v,
+            Err(e) => {
+                tracing::debug!(?e, "AttachmentVoiceNote: decode promise rejected");
+                return;
+            }
+        };
+        let Ok(audio_buf) = buf.dyn_into::<web_sys::AudioBuffer>() else {
+            return;
+        };
+        let Ok(channel) = audio_buf.get_channel_data(0) else {
+            return;
+        };
+        let peaks = bucket_peaks(&channel, bars);
+        set_peaks.set(peaks);
+    });
+}
+
+/// Bucket a PCM channel into `bars` peaks normalised to `[0.05, 1.0]`.
+/// The 0.05 floor keeps quiet sections visually present so the
+/// waveform doesn't disappear into the strip background.
+fn bucket_peaks(samples: &[f32], bars: usize) -> Vec<f32> {
+    if samples.is_empty() || bars == 0 {
+        return vec![0.05; bars];
+    }
+    let bucket = (samples.len() / bars).max(1);
+    let mut out = Vec::with_capacity(bars);
+    for b in 0..bars {
+        let start = b * bucket;
+        let end = ((b + 1) * bucket).min(samples.len());
+        let slice = &samples[start..end];
+        let mut peak = 0.0_f32;
+        for &s in slice {
+            let a = s.abs();
+            if a > peak {
+                peak = a;
+            }
+        }
+        out.push(peak.clamp(0.05, 1.0));
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn format_mm_ss_pads_seconds() {
+        assert_eq!(format_mm_ss(0.0), "0:00");
+        assert_eq!(format_mm_ss(7.0), "0:07");
+        assert_eq!(format_mm_ss(60.0), "1:00");
+        assert_eq!(format_mm_ss(125.0), "2:05");
+    }
+
+    #[test]
+    fn format_mm_ss_handles_garbage() {
+        assert_eq!(format_mm_ss(f64::NAN), "0:00");
+        assert_eq!(format_mm_ss(-3.0), "0:00");
+    }
+
+    #[test]
+    fn format_timer_uses_dashes_when_duration_unknown() {
+        assert_eq!(format_timer(2.0, f64::NAN), "0:02 / --:--");
+        assert_eq!(format_timer(0.0, 0.0), "0:00 / --:--");
+    }
+
+    #[test]
+    fn format_timer_renders_both_sides() {
+        assert_eq!(format_timer(15.0, 60.0), "0:15 / 1:00");
+    }
+
+    #[test]
+    fn bucket_peaks_normalises_to_floor() {
+        let samples = vec![0.0; 100];
+        let peaks = bucket_peaks(&samples, 10);
+        assert_eq!(peaks.len(), 10);
+        for p in peaks {
+            assert!(
+                (p - 0.05).abs() < 1e-6,
+                "silence buckets to the visual floor"
+            );
+        }
+    }
+
+    #[test]
+    fn bucket_peaks_picks_max_amplitude_per_bucket() {
+        let samples = vec![0.1, -0.9, 0.3, 0.4, -0.2, 0.5];
+        let peaks = bucket_peaks(&samples, 2);
+        assert_eq!(peaks.len(), 2);
+        assert!((peaks[0] - 0.9).abs() < 1e-6, "first half max is |-0.9|");
+        assert!((peaks[1] - 0.5).abs() < 1e-6, "second half max is 0.5");
+    }
+}
diff --git a/crates/web/src/components/message.rs b/crates/web/src/components/message.rs
index 54142e6e..50bf94f9 100644
--- a/crates/web/src/components/message.rs
+++ b/crates/web/src/components/message.rs
@@ -862,7 +862,11 @@ pub fn MessageView(
                     }
                     .into_any(),
                     AttachmentKind::VoiceNote => view! {
-                        <AttachmentVoiceNote filename=attachment.filename.clone() />
+                        <AttachmentVoiceNote
+                            hash=attachment.hash.clone()
+                            filename=attachment.filename.clone()
+                            size_bytes=attachment.size_bytes
+                        />
                     }
                     .into_any(),
                 };
diff --git a/crates/web/src/icons.rs b/crates/web/src/icons.rs
index 480371ca..36dd9243 100644
--- a/crates/web/src/icons.rs
+++ b/crates/web/src/icons.rs
@@ -613,6 +613,24 @@ pub fn icon_check_small() -> impl IntoView {
     }
 }
 
+/// Play triangle (lucide-style). Voice-note IconBtn idle state.
+pub fn icon_play() -> impl IntoView {
+    icon(
+        &format!(r#"<svg {SVG_ATTRS}><polygon points="6 3 20 12 6 21 6 3"/></svg>"#),
+        "icon-play",
+    )
+}
+
+/// Pause bars (lucide-style). Voice-note IconBtn playing state.
+pub fn icon_pause() -> impl IntoView {
+    icon(
+        &format!(
+            r#"<svg {SVG_ATTRS}><rect x="6" y="4" width="4" height="16" rx="1"/><rect x="14" y="4" width="4" height="16" rx="1"/></svg>"#
+        ),
+        "icon-pause",
+    )
+}
+
 /// Willow brand mark — three drooping fronds with leaf tips.
 /// Rendered with its own viewBox (48) and stroke width (1.5) to match the
 /// foundation iconography rules for brand surfaces.
diff --git a/crates/web/src/lib.rs b/crates/web/src/lib.rs
index 8bd53240..d038b7c4 100644
--- a/crates/web/src/lib.rs
+++ b/crates/web/src/lib.rs
@@ -27,3 +27,4 @@ pub mod trust_store;
 pub mod upload_state;
 pub mod util;
 pub mod voice;
+pub mod voice_note_player;
diff --git a/crates/web/src/voice_note_player.rs b/crates/web/src/voice_note_player.rs
new file mode 100644
index 00000000..76f1a758
--- /dev/null
+++ b/crates/web/src/voice_note_player.rs
@@ -0,0 +1,93 @@
+//! Single-instance voice-note playback coordinator.
+//!
+//! Spec: `docs/specs/2026-04-19-ui-design/files-inline.md` §Voice
+//! note: "Playback persists across other audio (one voice note at a
+//! time; starting another pauses the previous)."
+//!
+//! One [`VoiceNotePlayer`] is provided into Leptos context at the
+//! app shell. Each [`crate::components::AttachmentVoiceNote`] writes
+//! its own id to [`VoiceNotePlayer::active`] when it starts playing,
+//! and watches the same signal to pause itself when somebody else
+//! takes over. Cards key off the message-author hash + filename so
+//! each row in the chat has a stable identity that survives
+//! re-renders of the message list.
+
+use leptos::prelude::*;
+
+/// Shared, app-scoped voice-note player. Cloneable + Copy because
+/// the only mutable field is a Leptos signal handle (Copy in 0.8).
+#[derive(Clone, Copy)]
+pub struct VoiceNotePlayer {
+    /// Currently-playing voice-note id. `None` when nothing is
+    /// playing. Cards write their own id on play and clear it on
+    /// pause / end.
+    pub active: RwSignal<Option<String>>,
+}
+
+impl VoiceNotePlayer {
+    pub fn new() -> Self {
+        Self {
+            active: RwSignal::new(None),
+        }
+    }
+
+    /// Mark `id` as the active player. Other cards subscribing to
+    /// `active` will see the change and pause themselves.
+    pub fn claim(&self, id: String) {
+        self.active.set(Some(id));
+    }
+
+    /// Clear `active` if and only if the active id is `id`. Used by
+    /// the owning card on `pause` / `ended` so a stale clear from a
+    /// paused card can't pre-empt a different card that already
+    /// claimed the slot.
+    pub fn release_if_active(&self, id: &str) {
+        self.active.update(|cur| {
+            if cur.as_deref() == Some(id) {
+                *cur = None;
+            }
+        });
+    }
+}
+
+impl Default for VoiceNotePlayer {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Read the player from context, providing a fresh one if absent
+/// (matches `use_upload_queue` for consistency with the other
+/// shared-state contexts in this crate).
+pub fn use_voice_note_player() -> VoiceNotePlayer {
+    use_context::<VoiceNotePlayer>().unwrap_or_else(|| {
+        let player = VoiceNotePlayer::new();
+        provide_context(player);
+        player
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn release_only_clears_when_we_are_active() {
+        let p = VoiceNotePlayer::new();
+        p.claim("alpha".to_string());
+        // Different id can't preempt our active claim by accident.
+        p.release_if_active("beta");
+        assert_eq!(p.active.get_untracked().as_deref(), Some("alpha"));
+        // Our own release does clear.
+        p.release_if_active("alpha");
+        assert_eq!(p.active.get_untracked(), None);
+    }
+
+    #[test]
+    fn second_claim_overrides_first() {
+        let p = VoiceNotePlayer::new();
+        p.claim("alpha".to_string());
+        p.claim("beta".to_string());
+        assert_eq!(p.active.get_untracked().as_deref(), Some("beta"));
+    }
+}
diff --git a/crates/web/style.css b/crates/web/style.css
index 620c74ef..6553dee6 100644
--- a/crates/web/style.css
+++ b/crates/web/style.css
@@ -6970,6 +6970,97 @@ select:focus-visible {
     line-height: 1.4;
 }
 
+/* ── Voice-note card ──────────────────────────────────────────────
+ * Spec: docs/specs/2026-04-19-ui-design/files-inline.md §Voice note.
+ * `--bg-2` card on `--line` border, radius 10 px, 10/12 padding,
+ * max-width 420 px desktop. Play/pause IconBtn (32x32, --moss-2),
+ * waveform strip (24 px tall, --moss-1 bars on --bg-1, --moss-2
+ * progress fill), elapsed/total timer in font-mono / 11 px / --ink-3
+ * with mm:ss / mm:ss format.
+ */
+
+.attachment--voice-note {
+    background: var(--bg-2);
+    border: 1px solid var(--line);
+    border-radius: 10px;
+    padding: 10px 12px;
+    max-width: 420px;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+}
+
+@media (max-width: 720px) {
+    .attachment--voice-note {
+        max-width: 100%;
+    }
+}
+
+.attachment__voice-toggle {
+    width: 32px;
+    height: 32px;
+    flex-shrink: 0;
+    border-radius: 16px;
+    border: 1px solid var(--moss-2);
+    background: transparent;
+    color: var(--moss-2);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    -webkit-tap-highlight-color: transparent;
+    transition: background var(--transition-fast), color var(--transition-fast);
+}
+
+.attachment__voice-toggle:hover,
+.attachment__voice-toggle:focus-visible {
+    background: rgba(66, 92, 61, 0.18);
+    color: var(--ink-0);
+    outline: none;
+}
+
+.attachment__voice-toggle .icon {
+    font-size: 14px;
+}
+
+.attachment__voice-body {
+    flex: 1;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+}
+
+.attachment__voice-waveform {
+    width: 100%;
+    height: 24px;
+    display: block;
+    background: var(--bg-1);
+    border-radius: 4px;
+}
+
+.attachment__voice-bar {
+    fill: var(--moss-1);
+}
+
+.attachment__voice-bar--played {
+    fill: var(--moss-2);
+}
+
+.attachment__voice-timer {
+    color: var(--ink-3);
+    font-family: var(--font-mono, ui-monospace, monospace);
+    font-size: 11px;
+    font-variant-numeric: tabular-nums;
+}
+
+.attachment__voice-audio {
+    /* Native controls suppressed — the card drives play/pause via the
+       toggle button. The element stays focusable for screen readers
+       so they still announce state changes. */
+    display: none;
+}
+
 /* ── Phase 3c — emoji picker, pinned panel, header pin badge ───────────
  *
  * Spec: docs/specs/2026-04-19-ui-design/reactions-pins.md.

From 7c864eb2bbe7c561a3c503f0bf829b7e16c57c0f Mon Sep 17 00:00:00 2001
From: Noah <noahcorona231@gmail.com>
Date: Sat, 9 May 2026 00:56:24 -0700
Subject: [PATCH 2/4] test+docs(phase-3b T6): voice-note browser tests + close
 out plan

- `phase_3b_voice_note::voice_note_card_renders_spec_surface`
  pins the toggle button, waveform SVG, timer container, the
  initial `0:00 / --:--` copy, the `play voice note {filename}`
  aria-label, and the embedded `<audio>` element. Covers AG-5.
- `phase_3b_voice_note::second_claim_pauses_first_via_shared_player`
  drives the `VoiceNotePlayer.claim` signal across two cards and
  asserts the active-id semantics that AG-6 turns into the
  `pause()` call in production. Real audio playback timing isn't
  drivable in the wasm-pack harness (no codec backend), so the
  test focuses on the load-bearing claim/release coordinator.
- Spec ticks AG-5 + AG-6; plan T6 marks landed with a back-pointer
  to the two browser tests + a note on the `AudioContext` fallback.

Phase 3b is now feature-complete: every plan task except T15 (the
final spec stamp) is landed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 crates/web/tests/browser.rs                   | 94 +++++++++++++++++++
 .../2026-05-08-ui-phase-3b-files-inline.md    |  2 +-
 .../2026-04-19-ui-design/files-inline.md      | 10 +-
 3 files changed, 102 insertions(+), 4 deletions(-)

diff --git a/crates/web/tests/browser.rs b/crates/web/tests/browser.rs
index 0bfaf966..4fede3a1 100644
--- a/crates/web/tests/browser.rs
+++ b/crates/web/tests/browser.rs
@@ -15228,3 +15228,97 @@ mod phase_3b_paste_filename {
         }
     }
 }
+
+/// Phase 3b T6 — voice-note card mounts the spec surface and the
+/// single-instance coordinator pauses other cards on claim.
+///
+/// Spec: `docs/specs/2026-04-19-ui-design/files-inline.md` §Voice
+/// note + acceptance criteria AG-5 / AG-6. The DOM tier covers the
+/// surface (toggle button + waveform + timer) and the coordinator's
+/// claim/release semantics. Real audio decoding + playback timing
+/// needs a real browser; that's out of scope for the wasm-pack
+/// harness (no codec backend), so the test here drives the
+/// `VoiceNotePlayer` claim signal directly to assert other cards
+/// react to a competing claim.
+mod phase_3b_voice_note {
+    use super::*;
+    use willow_web::components::attachment::AttachmentVoiceNote;
+    use willow_web::voice_note_player::VoiceNotePlayer;
+
+    fn mount_card(player: VoiceNotePlayer, hash: &str, filename: &str) -> web_sys::HtmlElement {
+        let h = hash.to_string();
+        let f = filename.to_string();
+        mount_test(move || {
+            provide_context(player);
+            view! {
+                <AttachmentVoiceNote
+                    hash=h
+                    filename=f
+                    size_bytes=4_096
+                />
+            }
+        })
+    }
+
+    #[wasm_bindgen_test]
+    async fn voice_note_card_renders_spec_surface() {
+        let player = VoiceNotePlayer::new();
+        let container = mount_card(player, "deadbeef".repeat(8).as_str(), "hello.opus");
+        tick().await;
+
+        // Spec §Voice note: card with toggle button, waveform strip,
+        // timer.
+        let card =
+            query(&container, ".attachment--voice-note").expect("voice-note card root must mount");
+        assert!(query(&container, ".attachment__voice-toggle").is_some());
+        assert!(query(&container, ".attachment__voice-waveform").is_some());
+        assert!(query(&container, ".attachment__voice-timer").is_some());
+
+        // Initial timer reads `0:00 / --:--` (no metadata loaded yet).
+        let timer = query(&container, ".attachment__voice-timer").unwrap();
+        assert_eq!(text(&timer), "0:00 / --:--");
+
+        // Idle aria label is the play form.
+        let toggle = query(&container, ".attachment__voice-toggle").unwrap();
+        let aria = toggle.get_attribute("aria-label").unwrap_or_default();
+        assert!(
+            aria.starts_with("play voice note"),
+            "aria-label starts in play form: {aria}"
+        );
+
+        // The card root contains an <audio> element so playback hooks
+        // can attach. Using contains() avoids brittle DOM ordering.
+        let audio = card.query_selector("audio").unwrap();
+        assert!(audio.is_some(), "card must contain an <audio> element");
+    }
+
+    #[wasm_bindgen_test]
+    async fn second_claim_pauses_first_via_shared_player() {
+        let player = VoiceNotePlayer::new();
+
+        // Two independent cards sharing one player context.
+        let _container_a = mount_card(player, "aaaa".repeat(16).as_str(), "alpha.opus");
+        let _container_b = mount_card(player, "bbbb".repeat(16).as_str(), "beta.opus");
+        tick().await;
+
+        // Card alpha claims the slot — drives the per-card `Effect`
+        // that watches `player.active`.
+        player.claim("alpha".to_string());
+        tick().await;
+        assert_eq!(player.active.get_untracked().as_deref(), Some("alpha"));
+
+        // Card beta then claims; the shared signal is now `beta`.
+        // Card alpha's effect reads the new value and (in production)
+        // calls `audio.pause()` on its own element. We can't drive a
+        // real `<audio>` in the headless harness, but the claim
+        // semantics are the load-bearing half of AG-6.
+        player.claim("beta".to_string());
+        tick().await;
+        assert_eq!(player.active.get_untracked().as_deref(), Some("beta"));
+
+        // Releasing a non-active id is a no-op (defensive against a
+        // stale paused-card racing a fresh claim).
+        player.release_if_active("alpha");
+        assert_eq!(player.active.get_untracked().as_deref(), Some("beta"));
+    }
+}
diff --git a/docs/plans/2026-05-08-ui-phase-3b-files-inline.md b/docs/plans/2026-05-08-ui-phase-3b-files-inline.md
index 3c3d4510..5c6affd2 100644
--- a/docs/plans/2026-05-08-ui-phase-3b-files-inline.md
+++ b/docs/plans/2026-05-08-ui-phase-3b-files-inline.md
@@ -119,7 +119,7 @@
 
 - [x] **T5.** Implement `<AttachmentImage>` per spec (inline `<img loading="lazy">` wrapped in anchor with `target="_blank"`, caption row below in `--ink-3` mono, `max-width` 380 / 280 px). The `<img>` `src` is left empty pending the T8/T9 blob-fetch wiring; the spec layout + caption are final. **Tests:** `caption_format_matches_spec` pins the byte-exact `filename · size · e2e encrypted` format. **Verify:** `cargo test -p willow-web --lib attachment`.
 
-- [ ] **T6.** Implement `<AttachmentVoiceNote>` per spec + `VoiceNotePlayer` single-instance coordinator. **Browser tests:** AG-5, AG-6. **Verify:** `just test-browser`.
+- [x] **T6.** Implement `<AttachmentVoiceNote>` per spec + `VoiceNotePlayer` single-instance coordinator. **Browser tests:** AG-5, AG-6. **Verify:** `just test-browser`. *(Landed: card-local `<audio>` for playback, `AudioContext.decodeAudioData` for waveform peaks with a flat baseline fallback, shared `VoiceNotePlayer` context with `claim` / `release_if_active` semantics. AG-5 covered by `phase_3b_voice_note::voice_note_card_renders_spec_surface`; AG-6 covered by `second_claim_pauses_first_via_shared_player`.)*
 
 - [x] **T7.** Wire the typed `EventKind::FileMessage` rendering branch in `message.rs` to call `attachment::pick()` and render the appropriate component. Projection updated: `DisplayMessage` gains `attachment: Option<willow_state::FileAttachment>` populated by `views::compute_messages_view` from the underlying `ChatMessage::attachment`. Legacy base64 `[file:…]` branch kept after the typed branch so historical messages still render. Reviewer-flagged fixes from T2 also landed in this commit:
   - `derive_client_events` now matches `EventKind::Message | EventKind::FileMessage` so attachment messages produce `ClientEvent::MessageReceived` and the UI signal layer fires.
diff --git a/docs/specs/2026-04-19-ui-design/files-inline.md b/docs/specs/2026-04-19-ui-design/files-inline.md
index 85134858..3c2797ae 100644
--- a/docs/specs/2026-04-19-ui-design/files-inline.md
+++ b/docs/specs/2026-04-19-ui-design/files-inline.md
@@ -215,9 +215,13 @@ easing. Drag overlay crossfades in under reduced motion.
 - [x] File cards render with mime icon, filename, size, download
       IconBtn, and respect `max-width: 420px` desktop / `100%` mobile.
       *(`<AttachmentFileCard>` — phase 3b T4.)*
-- [ ] Voice notes render the waveform + play / pause + mm:ss timer
-      card, and starting one pauses any other. *(Placeholder ships in
-      phase 3b; full surface in T6.)*
+- [x] Voice notes render the waveform + play / pause + mm:ss timer
+      card, and starting one pauses any other.
+      *(`<AttachmentVoiceNote>` + `VoiceNotePlayer` coordinator —
+      phase 3b T6. Waveform peaks come from `AudioContext.decodeAudioData`
+      with a flat baseline fallback if decoding fails; playback uses
+      a card-local `<audio>` element so the player works even when
+      the codec for waveform extraction isn't available.)*
 - [x] Upload dialog opens from the composer attach button with a
       picker row, per-file rows + cancel, and the footer actions in
       §Copy. *(`<UploadDialog>` + `UploadQueue` context — phase 3b T8.

From 7bcd845999ae0533ec89b255aa29316998aa2c44 Mon Sep 17 00:00:00 2001
From: Noah <noahcorona231@gmail.com>
Date: Sat, 9 May 2026 01:17:36 -0700
Subject: [PATCH 3/4] fix(phase-3b T6): close AudioContext + gate pause-effect
 re-fire

Review feedback on PR #640:

- `decode_peaks_async` now calls `ctx.close()` before dropping the
  Rust handle. `drop(ctx)` alone keeps the underlying audio output
  device open until JS GC runs, and a long chat scroll can stack
  dozens of sleeping contexts past the per-tab limit (~6 on Chrome).
  Decode-only use isn't gated by the autoplay policy so this never
  throws.
- The card's pause-effect early-exits when `playing.get_untracked()`
  is already false. Previously, `on_pause` would write
  `set_playing.set(false)` *and* call `player.release_if_active`,
  which mutated `player.active` and re-fired the effect for an
  idempotent no-op write. Untracked read avoids subscribing the
  effect to its own mirror signal.
- `second_claim_pauses_first_via_shared_player` now actually
  exercises the per-card pause-effect: dispatches a synthetic
  `play` event to flip card A into the visual "playing" state,
  claims B's real id (matching the card's `vn-{hash[..12]}-{name}`
  derivation), then asserts card A's toggle aria-label flipped
  back to "play voice note". The `audio.pause()` call against a
  headless `<audio>` is verified by inspection (no codec backend
  in wasm-pack), but the load-bearing reactive wiring is now
  covered.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../src/components/attachment/voice_note.rs   | 38 ++++++---
 crates/web/tests/browser.rs                   | 77 ++++++++++++++-----
 2 files changed, 85 insertions(+), 30 deletions(-)

diff --git a/crates/web/src/components/attachment/voice_note.rs b/crates/web/src/components/attachment/voice_note.rs
index 4a956700..b6fab239 100644
--- a/crates/web/src/components/attachment/voice_note.rs
+++ b/crates/web/src/components/attachment/voice_note.rs
@@ -105,20 +105,28 @@ pub fn AttachmentVoiceNote(
         });
     });
 
-    // Pause us when somebody else claims the player slot.
+    // Pause us when somebody else claims the player slot. Reads
+    // `playing.get_untracked()` (not subscribed) so a follow-up
+    // `release_if_active` from `on_pause` doesn't re-fire the
+    // effect with no useful work — the previous pass already wrote
+    // `playing=false` and called `audio.pause()`.
     let id_for_effect = id.clone();
     Effect::new(move |_| {
         let active = player.active.get();
-        if active.as_deref() != Some(&id_for_effect) {
-            if let Some(el) = audio_ref.get() {
-                if !el.paused() {
-                    let _ = el.pause();
-                }
+        if active.as_deref() == Some(&id_for_effect) {
+            return;
+        }
+        if !playing.get_untracked() {
+            return;
+        }
+        if let Some(el) = audio_ref.get() {
+            if !el.paused() {
+                let _ = el.pause();
             }
-            // Mirror in our own `playing` signal so the icon flips
-            // back to `play` even when the pause came from outside.
-            set_playing.set(false);
         }
+        // Mirror in our own `playing` signal so the icon flips
+        // back to `play` even when the pause came from outside.
+        set_playing.set(false);
     });
 
     let id_play = id.clone();
@@ -325,9 +333,15 @@ fn decode_peaks_async(bytes: Vec<u8>, bars: usize, set_peaks: WriteSignal<Vec<f3
             }
         };
         let result = wasm_bindgen_futures::JsFuture::from(promise).await;
-        // Drop the AudioContext as soon as decoding settles, regardless
-        // of outcome — we never play audio through it, so holding it
-        // would just leak.
+        // Close the AudioContext explicitly so the browser releases
+        // the underlying audio output device immediately. `drop(ctx)`
+        // alone only releases the Rust handle; the JS side holds on
+        // until GC, which on a long chat scroll can stack dozens of
+        // sleeping contexts and blow past the per-tab limit
+        // (~6 on Chrome). Decode-only use isn't gated by the autoplay
+        // policy, so this never throws — the returned Promise is
+        // dropped intentionally.
+        let _ = ctx.close();
         drop(ctx);
         let buf = match result {
             Ok(v) => v,
diff --git a/crates/web/tests/browser.rs b/crates/web/tests/browser.rs
index 4fede3a1..9bf3e53d 100644
--- a/crates/web/tests/browser.rs
+++ b/crates/web/tests/browser.rs
@@ -15296,29 +15296,70 @@ mod phase_3b_voice_note {
     async fn second_claim_pauses_first_via_shared_player() {
         let player = VoiceNotePlayer::new();
 
-        // Two independent cards sharing one player context.
-        let _container_a = mount_card(player, "aaaa".repeat(16).as_str(), "alpha.opus");
-        let _container_b = mount_card(player, "bbbb".repeat(16).as_str(), "beta.opus");
+        // Two independent cards sharing one player context. The
+        // mounts must outlive every assertion below — the
+        // pause-watching `Effect` only runs while the card is alive.
+        let container_a =
+            mount_card(player, "aaaa".repeat(16).as_str(), "alpha.opus");
+        let _container_b =
+            mount_card(player, "bbbb".repeat(16).as_str(), "beta.opus");
+        tick().await;
+
+        // Drive card A into the "playing" visual state by firing a
+        // synthetic `play` event on its <audio>. The headless
+        // harness can't actually play audio (no codec backend), but
+        // the event handler doesn't care — it just flips the local
+        // `playing` signal that drives the toggle button's
+        // aria-label.
+        let audio_a = container_a
+            .query_selector(".attachment--voice-note audio")
+            .unwrap()
+            .expect("card A must contain an <audio> element");
+        let play_ev = web_sys::Event::new("play").unwrap();
+        audio_a.dispatch_event(&play_ev).unwrap();
         tick().await;
 
-        // Card alpha claims the slot — drives the per-card `Effect`
-        // that watches `player.active`.
-        player.claim("alpha".to_string());
-        tick().await;
-        assert_eq!(player.active.get_untracked().as_deref(), Some("alpha"));
+        let toggle_a = container_a
+            .query_selector(".attachment--voice-note .attachment__voice-toggle")
+            .unwrap()
+            .expect("card A must contain the toggle button");
+        let aria_playing = toggle_a.get_attribute("aria-label").unwrap_or_default();
+        assert!(
+            aria_playing.starts_with("pause voice note"),
+            "after the play event card A advertises pause: {aria_playing}"
+        );
 
-        // Card beta then claims; the shared signal is now `beta`.
-        // Card alpha's effect reads the new value and (in production)
-        // calls `audio.pause()` on its own element. We can't drive a
-        // real `<audio>` in the headless harness, but the claim
-        // semantics are the load-bearing half of AG-6.
-        player.claim("beta".to_string());
+        // Card B's id matches its own derived format
+        // (`vn-{hash[..12]}-{filename}`); claiming a competing id is
+        // enough to drive A's pause-effect because A's id won't
+        // match. Use B's *real* id so the test exercises the
+        // honest cross-card signal flow.
+        let beta_id = format!("vn-{}-beta.opus", &"bbbb".repeat(16)[..12]);
+        player.claim(beta_id.clone());
         tick().await;
-        assert_eq!(player.active.get_untracked().as_deref(), Some("beta"));
+        assert_eq!(
+            player.active.get_untracked().as_deref(),
+            Some(beta_id.as_str())
+        );
+
+        // Card A's pause-effect fired: aria-label flipped back to
+        // play form *and* the local `playing` mirror cleared. Both
+        // are what AG-6 cares about — the actual `audio.pause()`
+        // call against the real element is verified by inspection
+        // (the headless `<audio>` has nothing to pause).
+        let aria_paused = toggle_a.get_attribute("aria-label").unwrap_or_default();
+        assert!(
+            aria_paused.starts_with("play voice note"),
+            "after a competing claim card A flips back to play: {aria_paused}"
+        );
 
-        // Releasing a non-active id is a no-op (defensive against a
-        // stale paused-card racing a fresh claim).
+        // `release_if_active` only clears when the active id matches
+        // — defensive against a stale paused-card racing a fresh
+        // claim from somebody else.
         player.release_if_active("alpha");
-        assert_eq!(player.active.get_untracked().as_deref(), Some("beta"));
+        assert_eq!(
+            player.active.get_untracked().as_deref(),
+            Some(beta_id.as_str())
+        );
     }
 }

From adfd584477120cb290077e9e14ace62027806b28 Mon Sep 17 00:00:00 2001
From: Noah <noahcorona231@gmail.com>
Date: Sat, 9 May 2026 01:34:28 -0700
Subject: [PATCH 4/4] style(phase-3b T6): fmt the voice-note browser test

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 crates/web/tests/browser.rs | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/crates/web/tests/browser.rs b/crates/web/tests/browser.rs
index 9bf3e53d..67129503 100644
--- a/crates/web/tests/browser.rs
+++ b/crates/web/tests/browser.rs
@@ -15299,10 +15299,8 @@ mod phase_3b_voice_note {
         // Two independent cards sharing one player context. The
         // mounts must outlive every assertion below — the
         // pause-watching `Effect` only runs while the card is alive.
-        let container_a =
-            mount_card(player, "aaaa".repeat(16).as_str(), "alpha.opus");
-        let _container_b =
-            mount_card(player, "bbbb".repeat(16).as_str(), "beta.opus");
+        let container_a = mount_card(player, "aaaa".repeat(16).as_str(), "alpha.opus");
+        let _container_b = mount_card(player, "bbbb".repeat(16).as_str(), "beta.opus");
         tick().await;
 
         // Drive card A into the "playing" visual state by firing a