makersclaw 0.2.0 → 0.3.0

package/registry/blocks/audio-player/audio-player.jsx

@@ -0,0 +1,623 @@
+"use client";
+
+// AudioPlayer — a waveform player in the workspace theme (wavesurfer.js
+// underneath). Play, skip, speed and mute; regions (spans of the audio in
+// a tone: a topic, a speaker turn, a clip) and markers (moments: a
+// comment, a flag); a hover time readout; drag across the waveform to
+// mark a new region; keyboard throughout.
+//
+// What is ours and what is wavesurfer's: wavesurfer decodes the audio,
+// plays it and paints the waveform on its canvas. Everything drawn over
+// or around the waveform — regions, markers, the hover line, the drag
+// selection, the controls, the loading and error states — is ours, in the
+// kit and in tokens, so it follows the theme like any other block. The
+// canvas's own colours are read from the tokens at run time (colors.js).
+//
+// Client only in effect, not in import: the modules load anywhere, the
+// wavesurfer instance is created in an effect. The server (and the first
+// paint) shows the frame with a skeleton waveform.
+import { useCallback, useEffect, useId, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { Button, Empty, IconButton, Menu, Notice, Tooltip, cx } from "../../ui";
+import { useWavesurfer } from "./wavesurfer";
+import { readTokens, waveColours, watchTheme } from "./colors";
+import { RATES, clamp, cleanMarkers, cleanRegions, formatRange, formatRate, formatTime, regionAt, spokenTime } from "./time";
+
+/** A ref for the player's handle: `const player = useAudioPlayer()`, then
+ *  `<AudioPlayer playerRef={player} />` and `player.current?.seek(42)`. */
+export function useAudioPlayer() {
+  return useRef(null);
+}
+
+// Tailwind needs whole class names in the source: one per tone.
+const TONE = {
+  primary: { dot: "bg-primary", band: "bg-primary/10", active: "bg-primary/20", line: "bg-primary/60" },
+  "chart-2": { dot: "bg-chart-2", band: "bg-chart-2/10", active: "bg-chart-2/25", line: "bg-chart-2/60" },
+  "chart-3": { dot: "bg-chart-3", band: "bg-chart-3/10", active: "bg-chart-3/25", line: "bg-chart-3/60" },
+  "chart-4": { dot: "bg-chart-4", band: "bg-chart-4/10", active: "bg-chart-4/25", line: "bg-chart-4/60" },
+  "chart-5": { dot: "bg-chart-5", band: "bg-chart-5/10", active: "bg-chart-5/25", line: "bg-chart-5/60" },
+  success: { dot: "bg-success", band: "bg-success/10", active: "bg-success/20", line: "bg-success/60" },
+  warning: { dot: "bg-warning", band: "bg-warning/10", active: "bg-warning/20", line: "bg-warning/60" },
+  info: { dot: "bg-info", band: "bg-info/10", active: "bg-info/20", line: "bg-info/60" },
+  destructive: { dot: "bg-destructive", band: "bg-destructive/10", active: "bg-destructive/20", line: "bg-destructive/60" },
+  muted: { dot: "bg-muted-foreground", band: "bg-muted-foreground/10", active: "bg-muted-foreground/20", line: "bg-muted-foreground/50" },
+};
+const tone = (t, fallback = "primary") => TONE[t] ?? TONE[fallback];
+
+const WAVE_HEIGHT = 72;
+const DRAG_PX = 4; // a press that moves less than this is a click (seek)
+const MIN_REGION = 0.5; // seconds: a shorter drag is treated as a click
+const EDITABLE = /^(INPUT|TEXTAREA|SELECT)$/;
+
+// The skeleton's bars: a fixed, gentle shape (no randomness: the server
+// and the first client paint must match).
+const SKELETON = Array.from({ length: 72 }, (_, i) => 22 + Math.round(38 * Math.abs(Math.sin(i * 0.37) * Math.cos(i * 0.11))));
+
+export function AudioPlayer({
+  src,
+  peaks,
+  duration: knownDuration,
+  title,
+  description,
+  regions,
+  markers,
+  onAddMarker,
+  onRegionCreate,
+  onMarkerClick,
+  onRegionClick,
+  onActiveRegionChange,
+  onReady,
+  onPlay,
+  onPause,
+  onFinish,
+  onSeek,
+  onTimeUpdate,
+  onError,
+  rates = RATES,
+  defaultRate = 1,
+  skipSeconds = 15,
+  emptyTitle = "No recording yet",
+  emptyBody = "When there is audio to play, it shows up here.",
+  emptyAction,
+  bare = false,
+  playerRef,
+  className,
+}) {
+  const rootRef = useRef(null);
+  const waveRef = useRef(null);
+  const surfaceRef = useRef(null);
+  const tipId = useId();
+
+  // A Blob plays through an object URL, made here and revoked when it goes.
+  const isBlob = typeof Blob !== "undefined" && src instanceof Blob;
+  const [blobUrl, setBlobUrl] = useState(null);
+  useEffect(() => {
+    if (!isBlob) return setBlobUrl(null);
+    const u = URL.createObjectURL(src);
+    setBlobUrl(u);
+    return () => URL.revokeObjectURL(u);
+  }, [src, isBlob]);
+  const url = typeof src === "string" && src ? src : isBlob ? blobUrl ?? undefined : undefined;
+  const hasAudio = Boolean((typeof src === "string" && src) || isBlob || peaks);
+
+  // The instance. Every key is always passed (the hook's effect depends on
+  // the list of values; its length must not change) and none of them is a
+  // colour: colours are set after, so a theme change repaints instead of
+  // rebuilding the player.
+  const { wavesurfer: ws, isReady, isPlaying, currentTime } = useWavesurfer({
+    container: waveRef,
+    url,
+    peaks,
+    duration: knownDuration,
+    height: WAVE_HEIGHT,
+    barWidth: 2,
+    barGap: 2,
+    barRadius: 2,
+    cursorWidth: 2,
+    normalize: true,
+    interact: false,
+    hideScrollbar: true,
+    autoScroll: false,
+  });
+
+  const [duration, setDuration] = useState(knownDuration > 0 ? knownDuration : 0);
+  const [error, setError] = useState(null);
+  const [rate, setRate] = useState(defaultRate);
+  const [muted, setMuted] = useState(false);
+  const [notice, setNotice] = useState(null);
+  const [pending, setPending] = useState({ markers: [], regions: [] });
+  const [hover, setHover] = useState(null); // ratio 0..1 under the pointer
+  const [draft, setDraft] = useState(null); // { a, b } ratios while dragging a region
+  const [width, setWidth] = useState(0);
+  const drag = useRef(null);
+
+  // The latest callbacks, so the instance's listeners never go stale.
+  const cbs = useRef({});
+  cbs.current = { onReady, onPlay, onPause, onFinish, onTimeUpdate, onError };
+
+  // Settings the instance must keep across a reload (a new src).
+  const settings = useRef({ rate, muted });
+  settings.current = { rate, muted };
+
+  useEffect(() => {
+    if (!ws) return;
+    setError(null);
+    const off = [
+      ws.on("ready", (d) => {
+        setDuration(d);
+        setError(null);
+        ws.setPlaybackRate(settings.current.rate);
+        ws.setMuted(settings.current.muted);
+        cbs.current.onReady?.({ duration: d });
+      }),
+      ws.on("decode", (d) => setDuration(d)),
+      ws.on("play", () => cbs.current.onPlay?.()),
+      ws.on("pause", () => cbs.current.onPause?.()),
+      ws.on("finish", () => cbs.current.onFinish?.()),
+      ws.on("timeupdate", (t) => cbs.current.onTimeUpdate?.(t)),
+      ws.on("error", (e) => {
+        setError(e ?? new Error("The audio could not be loaded."));
+        cbs.current.onError?.(e);
+      }),
+    ];
+    return () => off.forEach((f) => f());
+  }, [ws]);
+
+  // The canvas's colours, from the tokens where the player sits; again
+  // whenever the theme or the scheme changes.
+  useEffect(() => {
+    if (!ws) return;
+    return watchTheme(rootRef.current, () => {
+      const c = waveColours(readTokens(rootRef.current, ["foreground", "muted-foreground", "primary"]));
+      const opts = Object.fromEntries(Object.entries(c).filter(([, v]) => v));
+      if (Object.keys(opts).length) ws.setOptions(opts);
+    });
+  }, [ws]);
+
+  // The waveform's width in pixels: for hiding labels that would not fit.
+  useEffect(() => {
+    const el = surfaceRef.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(([e]) => setWidth(e.contentRect.width));
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  const ready = Boolean(ws && isReady && duration > 0 && !error);
+  const shownRegions = useMemo(() => cleanRegions([...(regions ?? []), ...pending.regions], duration), [regions, pending.regions, duration]);
+  const shownMarkers = useMemo(() => cleanMarkers([...(markers ?? []), ...pending.markers], duration), [markers, pending.markers, duration]);
+  const active = ready ? regionAt(shownRegions, currentTime) : null;
+
+  // The region under the playhead, told once per change (transcript sync).
+  const lastActive = useRef(undefined);
+  useEffect(() => {
+    const id = active?.id ?? null;
+    if (lastActive.current === id) return;
+    lastActive.current = id;
+    onActiveRegionChange?.(active ?? null);
+  }, [active, onActiveRegionChange]);
+
+  // ---- actions --------------------------------------------------------------
+
+  const seek = useCallback(
+    (t) => {
+      if (!ws || !(duration > 0)) return;
+      const to = clamp(t, 0, duration);
+      ws.setTime(to);
+      onSeek?.(to);
+    },
+    [ws, duration, onSeek],
+  );
+  const skip = useCallback((d) => ws && seek(ws.getCurrentTime() + d), [ws, seek]);
+  // play() can be refused by the browser (no user gesture yet): not an error to show.
+  const quiet = (p) => p?.catch?.(() => {});
+  const toggle = useCallback(() => ready && quiet(ws.playPause()), [ready, ws]);
+  const changeRate = useCallback(
+    (r) => {
+      setRate(r);
+      ws?.setPlaybackRate(r);
+    },
+    [ws],
+  );
+  const toggleMute = useCallback(() => {
+    setMuted((m) => {
+      ws?.setMuted(!m);
+      return !m;
+    });
+  }, [ws]);
+  const playRange = useCallback(
+    (start, end) => {
+      if (!ready) return;
+      onSeek?.(start);
+      quiet(ws.play(clamp(start, 0, duration), end == null ? undefined : clamp(end, 0, duration)));
+    },
+    [ready, ws, duration, onSeek],
+  );
+  const retry = useCallback(() => {
+    if (!ws || !url) return;
+    setError(null);
+    ws.load(url).catch(() => {});
+  }, [ws, url]);
+
+  // Optimistic: the marker shows at once, dimmed, and goes if the save fails.
+  const addMarker = useCallback(async () => {
+    if (!onAddMarker || !ready) return;
+    const time = ws.getCurrentTime();
+    const temp = { id: `pending-${Date.now()}`, time, label: "Saving…", tone: "muted", pending: true };
+    setPending((p) => ({ ...p, markers: [...p.markers, temp] }));
+    setNotice(null);
+    let res;
+    try {
+      res = await onAddMarker({ time });
+    } catch (e) {
+      res = { ok: false, error: e?.message };
+    }
+    setPending((p) => ({ ...p, markers: p.markers.filter((m) => m.id !== temp.id) }));
+    if (!res?.ok) setNotice(`Couldn't add the marker at ${formatTime(time)}. ${res?.error || "Try again."}`);
+  }, [onAddMarker, ready, ws]);
+
+  const createRegion = useCallback(
+    async (start, end) => {
+      if (!onRegionCreate) return;
+      const temp = { id: `pending-${Date.now()}`, start, end, label: "Saving…", tone: "muted", pending: true };
+      setPending((p) => ({ ...p, regions: [...p.regions, temp] }));
+      setNotice(null);
+      let res;
+      try {
+        res = await onRegionCreate({ start, end });
+      } catch (e) {
+        res = { ok: false, error: e?.message };
+      }
+      setPending((p) => ({ ...p, regions: p.regions.filter((r) => r.id !== temp.id) }));
+      if (!res?.ok) setNotice(`Couldn't save the region ${formatRange(start, end)}. ${res?.error || "Try again."}`);
+    },
+    [onRegionCreate],
+  );
+
+  useImperativeHandle(
+    playerRef,
+    () => ({
+      play: () => ready && quiet(ws.play()),
+      pause: () => ws?.pause(),
+      toggle,
+      seek,
+      skip,
+      playRange,
+      playRegion: (id) => {
+        const r = shownRegions.find((x) => x.id === id);
+        if (r) playRange(r.start, r.end);
+      },
+      setRate: changeRate,
+      setMuted: (m) => {
+        setMuted(Boolean(m));
+        ws?.setMuted(Boolean(m));
+      },
+      addMarker,
+      getTime: () => ws?.getCurrentTime() ?? 0,
+      getDuration: () => duration,
+      isPlaying: () => Boolean(ws?.isPlaying()),
+      isReady: () => ready,
+    }),
+    [ready, ws, toggle, seek, skip, playRange, shownRegions, changeRate, addMarker, duration],
+  );
+
+  // ---- pointer and keys on the waveform ---------------------------------------
+
+  const ratioAt = (e) => {
+    const r = surfaceRef.current?.getBoundingClientRect();
+    return r && r.width ? clamp((e.clientX - r.left) / r.width, 0, 1) : 0;
+  };
+
+  function onPointerDown(e) {
+    if (!ready || e.button > 0) return;
+    e.currentTarget.setPointerCapture?.(e.pointerId);
+    drag.current = { x: e.clientX, start: ratioAt(e), moved: false };
+  }
+  function onPointerMove(e) {
+    const ratio = ratioAt(e);
+    if (e.pointerType !== "touch") setHover(ratio);
+    const d = drag.current;
+    if (!d) return;
+    if (!d.moved && Math.abs(e.clientX - d.x) < DRAG_PX) return;
+    d.moved = true;
+    if (onRegionCreate) setDraft({ a: d.start, b: ratio });
+    else seek(ratio * duration); // no regions to make: a drag scrubs
+  }
+  function onPointerUp(e) {
+    const d = drag.current;
+    drag.current = null;
+    if (!d) return;
+    const ratio = ratioAt(e);
+    if (!d.moved) return seek(ratio * duration);
+    if (onRegionCreate) {
+      setDraft(null);
+      const start = Math.min(d.start, ratio) * duration;
+      const end = Math.max(d.start, ratio) * duration;
+      if (end - start >= MIN_REGION) createRegion(start, end);
+      else seek(ratio * duration);
+    }
+  }
+  function onPointerCancel() {
+    drag.current = null;
+    setDraft(null);
+  }
+
+  function onSurfaceKey(e) {
+    if (!ready) return;
+    const small = 5;
+    const moves = { ArrowLeft: -small, ArrowRight: small, PageDown: -skipSeconds, PageUp: skipSeconds };
+    if (e.key in moves) {
+      e.preventDefault();
+      skip(moves[e.key]);
+    } else if (e.key === "Home") {
+      e.preventDefault();
+      seek(0);
+    } else if (e.key === "End") {
+      e.preventDefault();
+      seek(duration);
+    } else if (e.key === " " || e.key === "Enter") {
+      e.preventDefault();
+      toggle();
+    }
+  }
+
+  // Player-wide letters, like a video player: K play/pause, J/L skip, M
+  // marker. Never while typing, never with a modifier (those are the app's).
+  function onRootKey(e) {
+    if (!ready || e.metaKey || e.ctrlKey || e.altKey || e.defaultPrevented) return;
+    const t = e.target;
+    if (EDITABLE.test(t?.tagName ?? "") || t?.isContentEditable) return;
+    const k = e.key.toLowerCase();
+    if (k === "k") toggle();
+    else if (k === "j") skip(-skipSeconds);
+    else if (k === "l") skip(skipSeconds);
+    else if (k === "m" && onAddMarker) addMarker();
+    else return;
+    e.preventDefault();
+  }
+
+  // ---- render -----------------------------------------------------------------
+
+  const frame = bare ? "" : "rounded-lg border border-border bg-card p-4 sm:p-5";
+
+  if (!hasAudio) {
+    return (
+      <div className={cx(frame, className)}>
+        <Header title={title} description={description} />
+        <Empty icon="mic" title={emptyTitle} body={emptyBody} action={emptyAction} className={title || description ? "mt-4" : ""} />
+      </div>
+    );
+  }
+
+  const pct = (t) => `${(duration > 0 ? (t / duration) * 100 : 0).toFixed(3)}%`;
+  const draftSpan = draft ? { from: Math.min(draft.a, draft.b), to: Math.max(draft.a, draft.b) } : null;
+  const loading = !ready && !error;
+
+  return (
+    <div ref={rootRef} className={cx(frame, "text-card-foreground", className)} onKeyDown={onRootKey}>
+      <Header title={title} description={description} />
+
+      {/* Markers: pins above the waveform. */}
+      <div className={cx("relative h-6", (title || description) && "mt-3")}>
+        {ready
+          ? shownMarkers.map((m) => (
+              <div key={m.id} className="absolute top-0 -translate-x-1/2" style={{ left: pct(m.time) }}>
+                <Tooltip label={`${formatTime(m.time)} · ${m.label ?? "Marker"}`} delay={150}>
+                  {/* raw: a pin placed on the timeline at its moment — a kit Button cannot be positioned by time or be this small */}
+                  <button
+                    type="button"
+                    disabled={m.pending}
+                    aria-label={`${m.label ?? "Marker"}, at ${spokenTime(m.time)}`}
+                    onClick={() => {
+                      seek(m.time);
+                      onMarkerClick?.(m);
+                    }}
+                    className="group grid size-6 place-items-center rounded-full outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-default"
+                  >
+                    <span
+                      className={cx(
+                        "size-2.5 rounded-full ring-2 ring-card transition-transform duration-150 group-hover:scale-125 group-focus-visible:scale-125 motion-reduce:transition-none",
+                        tone(m.tone).dot,
+                        m.pending && "animate-pulse motion-reduce:animate-none",
+                        Math.abs(currentTime - m.time) < 0.75 && "scale-125",
+                      )}
+                    />
+                  </button>
+                </Tooltip>
+              </div>
+            ))
+          : null}
+      </div>
+
+      {/* The waveform: wavesurfer's canvas, with our layer over it. */}
+      <div className="relative" style={{ height: WAVE_HEIGHT }}>
+        <div ref={waveRef} className={cx("w-full transition-opacity duration-150 motion-reduce:transition-none", loading && "opacity-0")} />
+
+        {loading ? (
+          <div aria-hidden="true" className="pointer-events-none absolute inset-0 flex items-center gap-[2px] overflow-hidden">
+            {SKELETON.map((h, i) => (
+              <span key={i} className="w-[2px] flex-1 animate-pulse rounded-full bg-muted motion-reduce:animate-none" style={{ height: `${h}%` }} />
+            ))}
+          </div>
+        ) : null}
+
+        {error ? (
+          <div className="absolute inset-0 flex items-center">
+            <span aria-hidden="true" className="h-px w-full bg-border" />
+          </div>
+        ) : null}
+
+        {/* raw: the seek surface — a slider over a canvas; the kit Slider is a native range input and cannot host the waveform, regions or markers */}
+        <div
+          ref={surfaceRef}
+          role="slider"
+          tabIndex={ready ? 0 : -1}
+          aria-label="Seek"
+          aria-valuemin={0}
+          aria-valuemax={Math.round(duration)}
+          aria-valuenow={Math.round(currentTime)}
+          aria-valuetext={`${spokenTime(currentTime)} of ${spokenTime(duration)}`}
+          aria-disabled={!ready || undefined}
+          aria-describedby={tipId}
+          onKeyDown={onSurfaceKey}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={onPointerUp}
+          onPointerCancel={onPointerCancel}
+          onPointerLeave={() => setHover(null)}
+          className={cx(
+            "absolute inset-0 z-10 touch-pan-y rounded-md outline-none select-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-card",
+            ready ? (onRegionCreate ? "cursor-crosshair" : "cursor-pointer") : "cursor-default",
+          )}
+        >
+          {ready
+            ? shownRegions.map((r) => (
+                <span
+                  key={r.id}
+                  aria-hidden="true"
+                  className={cx("pointer-events-none absolute inset-y-0 transition-colors duration-150 motion-reduce:transition-none", active?.id === r.id ? tone(r.tone).active : tone(r.tone).band)}
+                  style={{ left: pct(r.start), width: pct(r.end - r.start) }}
+                />
+              ))
+            : null}
+          {ready
+            ? shownMarkers.map((m) => (
+                <span key={m.id} aria-hidden="true" className={cx("pointer-events-none absolute inset-y-0 w-px", tone(m.tone).line)} style={{ left: pct(m.time) }} />
+              ))
+            : null}
+
+          {draftSpan ? (
+            <span
+              aria-hidden="true"
+              className="pointer-events-none absolute inset-y-0 border-x border-primary bg-primary/15"
+              style={{ left: `${draftSpan.from * 100}%`, width: `${(draftSpan.to - draftSpan.from) * 100}%` }}
+            />
+          ) : null}
+
+          {ready && hover != null ? (
+            <>
+              <span aria-hidden="true" className="pointer-events-none absolute inset-y-0 w-px bg-foreground/40" style={{ left: `${hover * 100}%` }} />
+              <span
+                aria-hidden="true"
+                className="pointer-events-none absolute -top-1 z-30 -translate-x-1/2 -translate-y-full rounded-md bg-foreground px-1.5 py-0.5 text-xs font-medium whitespace-nowrap text-background tabular-nums shadow-sm"
+                style={{ left: `${clamp(hover * 100, 4, 96)}%` }}
+              >
+                {draftSpan ? formatRange(draftSpan.from * duration, draftSpan.to * duration) : formatTime(hover * duration)}
+              </span>
+            </>
+          ) : null}
+        </div>
+        <span id={tipId} className="sr-only">
+          {onRegionCreate ? "Click to jump, drag to mark a region. " : "Click or drag to jump. "}
+          Arrow keys move 5 seconds, Page Up and Page Down {skipSeconds}, Space plays or pauses.
+        </span>
+      </div>
+
+      {/* Regions: labels in a lane under the waveform; a click plays one. */}
+      {ready && shownRegions.length ? (
+        <div className="relative mt-1.5 h-7">
+          {shownRegions.map((r) => {
+            const px = ((r.end - r.start) / duration) * width;
+            const on = active?.id === r.id;
+            return (
+              <div key={r.id} className="absolute inset-y-0 px-px" style={{ left: pct(r.start), width: pct(r.end - r.start) }}>
+                <Tooltip label={`${r.label ?? "Region"} · ${formatRange(r.start, r.end)}`} delay={300}>
+                  {/* raw: a segment of the timeline, sized to its span — a kit Button has a fixed height and padding */}
+                  <button
+                    type="button"
+                    disabled={r.pending}
+                    aria-label={`Play ${r.label ?? "region"}, ${spokenTime(r.start)} to ${spokenTime(r.end)}`}
+                    aria-current={on || undefined}
+                    onClick={() => {
+                      playRange(r.start, r.end);
+                      onRegionClick?.(r);
+                    }}
+                    className="group flex h-7 w-full min-w-0 flex-col gap-1 rounded-sm pt-0.5 text-left outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-default"
+                  >
+                    <span className={cx("h-1 w-full rounded-full transition-opacity duration-150 motion-reduce:transition-none", tone(r.tone).dot, on ? "opacity-100" : "opacity-60 group-hover:opacity-100", r.pending && "animate-pulse motion-reduce:animate-none")} />
+                    {px >= 44 ? (
+                      <span className={cx("block w-full truncate text-xs leading-4", on ? "font-medium text-foreground" : "text-muted-foreground group-hover:text-foreground")}>{r.label ?? "Region"}</span>
+                    ) : null}
+                  </button>
+                </Tooltip>
+              </div>
+            );
+          })}
+        </div>
+      ) : null}
+
+      {error ? (
+        <Notice
+          tone="danger"
+          title="Couldn't play this recording"
+          className="mt-3"
+          action={
+            url ? (
+              <Button size="sm" variant="secondary" icon="refresh" onClick={retry}>
+                Try again
+              </Button>
+            ) : null
+          }
+        >
+          The file may be missing, or in a format this browser can't play.
+        </Notice>
+      ) : null}
+
+      {notice ? (
+        <Notice tone="danger" className="mt-3" onDismiss={() => setNotice(null)}>
+          {notice}
+        </Notice>
+      ) : null}
+
+      {/* Controls: one row on a wide screen; on a phone the transport gets
+          its own centred row and the time sits under it with the rest. */}
+      <div className="mt-3 flex flex-wrap items-center gap-x-2 gap-y-2">
+        <div className="flex w-full items-center justify-center gap-2 sm:w-auto sm:justify-start">
+          <Tooltip label={`Back ${skipSeconds}s · J`}>
+            <IconButton icon="rotate-ccw" label={`Back ${skipSeconds} seconds`} disabled={!ready} onClick={() => skip(-skipSeconds)} />
+          </Tooltip>
+          <Tooltip label={isPlaying ? "Pause · K" : "Play · K"}>
+            <IconButton icon={isPlaying ? "pause" : "play"} variant="primary" label={isPlaying ? "Pause" : "Play"} disabled={!ready} onClick={toggle} />
+          </Tooltip>
+          <Tooltip label={`Forward ${skipSeconds}s · L`}>
+            <IconButton icon="rotate-cw" label={`Forward ${skipSeconds} seconds`} disabled={!ready} onClick={() => skip(skipSeconds)} />
+          </Tooltip>
+        </div>
+
+        <p className="px-1 text-sm whitespace-nowrap text-muted-foreground tabular-nums sm:ml-1">
+          <span className="text-foreground">{formatTime(currentTime)}</span>
+          <span aria-hidden="true"> / </span>
+          <span className="sr-only"> of </span>
+          {ready || knownDuration ? formatTime(duration) : "–:––"}
+        </p>
+
+        <div className="ml-auto flex items-center gap-1">
+          {onAddMarker ? (
+            <Tooltip label="Add a marker here · M">
+              <Button size="sm" variant="quiet" icon="flag" disabled={!ready} onClick={addMarker}>
+                Marker
+              </Button>
+            </Tooltip>
+          ) : null}
+          <Menu
+            label={`Playback speed, ${formatRate(rate)}`}
+            trigger={<span className="px-1 text-sm font-medium tabular-nums">{formatRate(rate)}</span>}
+            items={[{ type: "radio", label: "Speed", value: String(rate), onValueChange: (v) => changeRate(Number(v)), options: rates.map((r) => ({ value: String(r), label: r === 1 ? "Normal" : formatRate(r) })) }]}
+          />
+          <Tooltip label={muted ? "Unmute" : "Mute"}>
+            <IconButton icon={muted ? "volume-x" : "volume"} label={muted ? "Unmute" : "Mute"} size="sm" onClick={toggleMute} aria-pressed={muted} />
+          </Tooltip>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function Header({ title, description }) {
+  if (!title && !description) return null;
+  return (
+    <div className="min-w-0">
+      {title ? <h3 className="truncate text-sm font-medium text-foreground">{title}</h3> : null}
+      {description ? <p className="mt-0.5 truncate text-xs text-muted-foreground">{description}</p> : null}
+    </div>
+  );
+}

package/registry/blocks/audio-player/block.json

@@ -0,0 +1,14 @@
+{
+  "name": "audio-player",
+  "title": "AudioPlayer",
+  "description": "A waveform audio player (wavesurfer.js) in the workspace theme: play, skip back and forward, speed, mute; regions (spans of the audio in a theme tone, labelled in a lane under the waveform, click to play one) and markers (pins at moments, click to jump); a hover time readout; drag across the waveform to mark a new region; add a marker at the playhead; keyboard like a video player (K, J, L, M, arrows). Time events and a handle (seek, play a range) for syncing a transcript.",
+  "useWhen": "A screen plays a recording: a call or meeting recording, a voice note, a podcast clip, a voicemail, a sound file on a record. The call-review block is built on it. Not for video, not for recording audio from the microphone.",
+  "tags": ["audio", "player", "waveform", "wavesurfer", "recording", "call", "voice note", "podcast", "regions", "markers", "playback", "speed", "transcript"],
+  "exports": ["AudioPlayer", "useAudioPlayer", "formatTime", "formatRange", "spokenTime", "regionAt", "TONES", "RATES"],
+  "files": ["index.js", "audio-player.jsx", "wavesurfer.js", "colors.js", "time.js"],
+  "requires": [],
+  "dependencies": {
+    "wavesurfer.js": "8.0.0",
+    "@wavesurfer/react": "1.0.12"
+  }
+}