@hienlh/ppm 0.21.0 → 0.22.0

package/src/web/components/remote-desktop/remote-desktop-view-style.ts

@@ -0,0 +1,145 @@
+/**
+ * How the remote screen is fitted into the viewer — RustDesk's `ViewStyle`, ported.
+ *
+ * `adaptive` is the default there and here, and it is deliberately the one mode that computes
+ * *nothing*: the canvas keeps `max-w-full max-h-full` and the browser fits it, which is the
+ * behaviour the viewer has always had. Only `original` and `custom` need an explicit CSS size,
+ * and neither needs to know the viewport — they are a function of the capture's own pixel size,
+ * so there is no ResizeObserver anywhere in this feature.
+ *
+ * Input mapping needs no changes for any of this: `fractionFromPoint` reads the canvas's
+ * `getBoundingClientRect()`, so a canvas sized to 40% or 300% still maps a click to the right
+ * host pixel, and a scrolled container is already accounted for (the rect is viewport-relative).
+ */
+
+export type ViewStyle = "adaptive" | "original" | "custom";
+
+/** RustDesk's default too — the only mode that always shows the whole remote screen. */
+export const DEFAULT_VIEW_STYLE: ViewStyle = "adaptive";
+
+/** Order the picker lists them in, matching RustDesk's menu. */
+export const VIEW_STYLE_ORDER: readonly ViewStyle[] = ["original", "adaptive", "custom"];
+
+export const VIEW_STYLE_LABELS: Record<ViewStyle, string> = {
+  original: "Scale original",
+  adaptive: "Scale adaptive",
+  custom: "Scale custom",
+};
+
+/** 25%–300%. Below a quarter the picture is unusable and above 3x a 4K capture would ask the
+ *  browser for a 12K-wide layer, which is where compositing starts failing outright. */
+/* Bounds and slider mapping ported from RustDesk's `custom_scale_base.dart` +
+ * `consts.dart` (`kScaleCustomMinPercent` … `kDebounceCustomScaleDuration`), because the
+ * obvious implementation of this control is wrong in a way that is only obvious once built:
+ * the range is 5%–1000%, so a *linear* slider puts 100% at 9.5% of the track — the one value
+ * users actually want sits pinned against the left stop and cannot be hit. RustDesk's slider
+ * is piecewise-linear around a pivot: the first third of the track covers 5%→100% and the
+ * remaining two thirds cover 100%→1000%, with a detent that snaps back to exactly 100%. */
+export const CUSTOM_SCALE_MIN_PERCENT = 5;
+export const CUSTOM_SCALE_MAX_PERCENT = 1000;
+export const CUSTOM_SCALE_PIVOT_PERCENT = 100;
+/** 100% sits one third along the track. */
+export const CUSTOM_SCALE_PIVOT_POS = 1 / 3;
+/** Snap window around the pivot, in normalised track units (~0.6%). */
+export const CUSTOM_SCALE_DETENT = 0.006;
+/** The +/- buttons move one percentage point, matching RustDesk's `nudgeScale(±1)`. */
+export const CUSTOM_SCALE_NUDGE_PERCENT = 1;
+/** Committing on every slider tick would respawn nothing (this is pure CSS) but would write the
+ *  device pref hundreds of times per drag. RustDesk debounces by the same 300ms. */
+export const CUSTOM_SCALE_DEBOUNCE_MS = 300;
+
+export const CUSTOM_SCALE_MIN = CUSTOM_SCALE_MIN_PERCENT / 100;
+export const CUSTOM_SCALE_MAX = CUSTOM_SCALE_MAX_PERCENT / 100;
+export const DEFAULT_CUSTOM_SCALE = 1;
+
+/** Normalised track position [0,1] → percent. Piecewise around the pivot; see the note above. */
+export function scalePosToPercent(pos: number): number {
+  if (!Number.isFinite(pos) || pos <= 0) return CUSTOM_SCALE_MIN_PERCENT;
+  if (pos >= 1) return CUSTOM_SCALE_MAX_PERCENT;
+  if (pos <= CUSTOM_SCALE_PIVOT_POS) {
+    const q = pos / CUSTOM_SCALE_PIVOT_POS;
+    return clampScalePercent(Math.round(
+      CUSTOM_SCALE_MIN_PERCENT + q * (CUSTOM_SCALE_PIVOT_PERCENT - CUSTOM_SCALE_MIN_PERCENT),
+    ));
+  }
+  const q = (pos - CUSTOM_SCALE_PIVOT_POS) / (1 - CUSTOM_SCALE_PIVOT_POS);
+  return clampScalePercent(Math.round(
+    CUSTOM_SCALE_PIVOT_PERCENT + q * (CUSTOM_SCALE_MAX_PERCENT - CUSTOM_SCALE_PIVOT_PERCENT),
+  ));
+}
+
+/** Percent → normalised track position. Inverse of `scalePosToPercent`. */
+export function scalePercentToPos(percent: number): number {
+  const p = clampScalePercent(percent);
+  if (p <= CUSTOM_SCALE_PIVOT_PERCENT) {
+    const q = (p - CUSTOM_SCALE_MIN_PERCENT) / (CUSTOM_SCALE_PIVOT_PERCENT - CUSTOM_SCALE_MIN_PERCENT);
+    return q * CUSTOM_SCALE_PIVOT_POS;
+  }
+  const q = (p - CUSTOM_SCALE_PIVOT_PERCENT) / (CUSTOM_SCALE_MAX_PERCENT - CUSTOM_SCALE_PIVOT_PERCENT);
+  return CUSTOM_SCALE_PIVOT_POS + q * (1 - CUSTOM_SCALE_PIVOT_POS);
+}
+
+/** Snap a dragged position onto the pivot when it lands close, so 100% is reachable exactly. */
+export function snapScalePos(pos: number): number {
+  if (!Number.isFinite(pos)) return CUSTOM_SCALE_PIVOT_POS;
+  if (Math.abs(pos - CUSTOM_SCALE_PIVOT_POS) <= CUSTOM_SCALE_DETENT) return CUSTOM_SCALE_PIVOT_POS;
+  return Math.min(Math.max(pos, 0), 1);
+}
+
+export function clampScalePercent(percent: number): number {
+  if (!Number.isFinite(percent)) return CUSTOM_SCALE_PIVOT_PERCENT;
+  return Math.min(Math.max(Math.round(percent), CUSTOM_SCALE_MIN_PERCENT), CUSTOM_SCALE_MAX_PERCENT);
+}
+
+/** Coerce a stored or wire value into a real mode. Same `Object.hasOwn` reasoning as
+ *  `parsePresetId`: a prototype-walking check would let `"toString"` through. */
+export function parseViewStyle(value: unknown): ViewStyle {
+  return typeof value === "string" && Object.hasOwn(VIEW_STYLE_LABELS, value)
+    ? value as ViewStyle
+    : DEFAULT_VIEW_STYLE;
+}
+
+/** Clamp to the supported range, falling back to 1 for anything that is not a real number.
+ *
+ *  Strict about the type rather than coercing: `Number(null)` is **0**, which is finite, so a
+ *  coercing check would quietly turn a missing value into the 25% floor — a remote screen at
+ *  quarter size looks like a rendering bug, not a default. And `width: NaNpx` is dropped
+ *  silently, so a NaN that got this far would collapse the canvas to nothing with no error. */
+export function clampCustomScale(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_CUSTOM_SCALE;
+  return Math.min(Math.max(value, CUSTOM_SCALE_MIN), CUSTOM_SCALE_MAX);
+}
+
+/** One step up or down for a +/- button: one percentage point, as RustDesk's `nudgeScale`. */
+export function stepCustomScale(current: number, direction: 1 | -1): number {
+  const next = clampScalePercent(Math.round(clampCustomScale(current) * 100) + direction * CUSTOM_SCALE_NUDGE_PERCENT);
+  return next / 100;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/**
+ * CSS pixel size to give the canvas, or **null** to leave it to the stylesheet (adaptive).
+ *
+ * `natural` is the capture's own size (`canvas.width`/`canvas.height`, which the decoder sets
+ * from the decoded frame) — not the element's rendered box, which is what this decides.
+ * Returns null for a capture that has no size yet, so the first paint before any frame has
+ * arrived does not pin the canvas to 0x0.
+ */
+export function canvasCssSize(style: ViewStyle, customScale: number, natural: Size): Size | null {
+  if (style === "adaptive") return null;
+  if (natural.width <= 0 || natural.height <= 0) return null;
+  const scale = style === "original" ? 1 : clampCustomScale(customScale);
+  return { width: Math.round(natural.width * scale), height: Math.round(natural.height * scale) };
+}
+
+/** What to show on a compact control. Adaptive has no meaningful percentage (it is whatever
+ *  fits), so it is named rather than measured. */
+export function viewStyleShortLabel(style: ViewStyle, customScale: number): string {
+  if (style === "adaptive") return "Fit";
+  if (style === "original") return "1:1";
+  return `${Math.round(clampCustomScale(customScale) * 100)}%`;
+}

package/src/web/components/remote-desktop/remote-desktop-window-content.tsx

@@ -5,8 +5,8 @@
  * `RemoteDesktopWarningGate`, so the connection hook (and its session nonce) only runs once the
  * user has read the warning.
  */
-import { useCallback, useRef } from "react";
-import { RotateCw, MonitorX, Gauge } from "@/lib/icons";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { RotateCw, MonitorX } from "@/lib/icons";
 import type { WindowContentProps } from "@/components/floating-window/window-content-registry";
 import { useWindowStore } from "@/components/floating-window/window-store";
 import { useSettingsStore } from "@/stores/settings-store";
@@ -17,6 +17,13 @@ import { RemoteDesktopStatsOverlay } from "./remote-desktop-stats-overlay";
 import { RemoteDesktopWarningGate } from "./remote-desktop-warning-gate";
 import { RemoteDesktopReadinessGate } from "./remote-desktop-readiness-gate";
 import { useRemoteDesktopDisplayChoice } from "./use-remote-desktop-display-choice";
+import { RemoteDesktopClipboardNotice } from "./remote-desktop-clipboard-notice";
+import { useRemoteDesktopReadiness } from "./use-remote-desktop-readiness";
+import { RemoteDesktopToolbar } from "./remote-desktop-toolbar";
+import { canvasCssSize } from "./remote-desktop-view-style";
+import { useRemoteDesktopRecorder } from "./use-remote-desktop-recorder";
+import { saveCanvasScreenshot } from "./remote-desktop-recording";
+import { RemoteDesktopCustomQualityDialog } from "./remote-desktop-custom-quality-dialog";
 
 export default function RemoteDesktopWindowContent({ id }: WindowContentProps) {
   const closeWindow = useWindowStore((s) => s.close);
@@ -33,12 +40,53 @@ export default function RemoteDesktopWindowContent({ id }: WindowContentProps) {
 function RemoteDesktopViewer() {
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
   const display = useRemoteDesktopDisplayChoice();
-  const { connState, errorMessage, decoderStatus, decoderErrorMessage, sendMessage, reconnect, getFrameCount, getTotalBytes } =
-    useRemoteDesktopConnection(canvasRef, { displayId: display.displayId });
+  const {
+    connState, errorMessage, decoderStatus, decoderErrorMessage, sendMessage, reconnect,
+    getFrameCount, getTotalBytes, frameSize, quality, setQuality, setCustomQuality,
+    showCursor, setShowCursor,
+    codec, setCodec, audioOn, setAudioOn, getAudioTracks,
+    privacyOn, privacyError, setPrivacyOn,
+    hostModeId, hostOriginalModeId, resolutionError, setHostMode,
+    pendingHostClipboard, clearHostClipboard, sendClipboard, requestHostClipboard,
+  } = useRemoteDesktopConnection(canvasRef, { displayId: display.displayId });
   const statsVisible = useSettingsStore((s) => s.remoteDesktopStatsVisible);
   const toggleStats = useSettingsStore((s) => s.toggleRemoteDesktopStatsVisible);
+  const viewStyle = useSettingsStore((s) => s.remoteDesktopViewStyle);
+  const customScale = useSettingsStore((s) => s.remoteDesktopCustomScale);
+  const setViewStyle = useSettingsStore((s) => s.setRemoteDesktopViewStyle);
+  const setCustomScale = useSettingsStore((s) => s.setRemoteDesktopCustomScale);
+  const clipboardSync = useSettingsStore((s) => s.remoteDesktopClipboardSync);
+  const qualityChoice = useSettingsStore((s) => s.remoteDesktopQuality);
+  const customPercent = useSettingsStore((s) => s.remoteDesktopCustomQualityPercent);
+  const customFps = useSettingsStore((s) => s.remoteDesktopCustomFps);
+  const customMore = useSettingsStore((s) => s.remoteDesktopCustomQualityMore);
+  const setCustomMore = useSettingsStore((s) => s.setRemoteDesktopCustomQualityMore);
+  const [customQualityOpen, setCustomQualityOpen] = useState(false);
+  const setClipboardSync = useSettingsStore((s) => s.setRemoteDesktopClipboardSync);
+  // One fetch, no polling: this is read only to explain a clipboard that cannot work. The
+  // readiness *gate* above already cleared, so nothing here is allowed to block the viewer.
+  const { caps } = useRemoteDesktopReadiness(false);
+  const [pasteAttempted, setPasteAttempted] = useState(false);
 
-  useRemoteInputCapture(canvasRef, sendMessage, connState === "streaming");
+  // Stable object: `useRemoteInputCapture` lists it as an effect dependency, so a fresh literal
+  // per render would re-bind every canvas listener on every render.
+  //
+  // Undefined with sync off, which is the whole implementation of the toggle: the hook then
+  // stops exempting Ctrl+V from `preventDefault` and forwards it as an ordinary keystroke, so
+  // the host pastes its *own* clipboard and no text crosses the connection either way.
+  const clipboardHooks = useMemo(() => (clipboardSync ? {
+    onPasteText: (text: string, shift: boolean) => { setPasteAttempted(true); sendClipboard(text, true, shift); },
+    onCopyCombo: requestHostClipboard,
+  } : undefined), [clipboardSync, sendClipboard, requestHostClipboard]);
+
+  useRemoteInputCapture(canvasRef, sendMessage, connState === "streaming", clipboardHooks);
+
+  // The recorder muxes the session audio in when it is playing, so one file carries both.
+  const recorder = useRemoteDesktopRecorder(canvasRef, getAudioTracks);
+
+  // null in `adaptive` (and before the first frame): the canvas keeps its `max-*-full` classes
+  // and the browser fits it, which is the path this viewer has always been on.
+  const cssSize = canvasCssSize(viewStyle, customScale, frameSize);
 
   const overlayMessage = decoderStatus === "unsupported"
     ? decoderErrorMessage
@@ -56,37 +104,80 @@ function RemoteDesktopViewer() {
       data-testid="remote-desktop-window"
       data-conn-state={connState}
     >
-      <canvas ref={canvasRef} data-testid="remote-desktop-canvas" className="max-h-full max-w-full outline-none" />
+      {/* The scroll container is a child rather than this root, because the overlays below are
+          absolutely positioned against the root — inside a scroller they would scroll away with
+          the picture. `m-auto` on the canvas rather than `justify-center` on the box: centring
+          an oversized child with `justify-content` puts half the overflow *before* the scroll
+          origin, where no scrollbar can reach it (the top-left of a 1:1 3440×1440 capture in a
+          small window). Auto margins collapse to 0 when the child overflows, so both work. */}
+      <div className={cn("flex h-full w-full", cssSize ? "overflow-auto" : "overflow-hidden")}>
+        <canvas
+          ref={canvasRef}
+          data-testid="remote-desktop-canvas"
+          data-view-style={viewStyle}
+          className={cn("m-auto outline-none", !cssSize && "max-h-full max-w-full")}
+          style={cssSize ? { width: cssSize.width, height: cssSize.height } : undefined}
+        />
+      </div>
       <RemoteDesktopStatsOverlay canvasRef={canvasRef} getFrameCount={getFrameCount} getTotalBytes={getTotalBytes} />
-      {/* Multi-monitor hosts: pick which display to stream. Left of the stats toggle, same
-          corner cluster; a single-display host renders nothing here. */}
-      {display.displays.length > 1 && (
-        <select
-          value={display.current?.id ?? ""}
-          onChange={(e) => display.select(e.target.value)}
-          aria-label="Display"
-          className="absolute right-8 top-1 z-40 h-6 max-w-[45%] rounded bg-black/40 px-1.5 text-xs text-white/80 hover:bg-black/60"
-          data-testid="remote-desktop-display-select"
-        >
-          {display.displays.map((d) => (
-            <option key={d.id} value={d.id}>{d.label}{d.primary ? " (main)" : ""} · {d.width}×{d.height}</option>
-          ))}
-        </select>
-      )}
-      {/* Small corner toggle for the stats overlay above — top-right so it never collides with
-          the overlay itself (top-left) or the window's own title bar/controls above this body. */}
-      <button
-        type="button"
-        onClick={toggleStats}
-        aria-label="Toggle stats overlay"
-        aria-pressed={statsVisible}
-        className={cn(
-          "absolute right-1 top-1 z-40 flex size-6 items-center justify-center rounded bg-black/40 text-white/70 hover:bg-black/60 hover:text-white",
-          statsVisible && "bg-primary/70 text-primary-foreground hover:bg-primary/80",
-        )}
-      >
-        <Gauge className="size-3.5" />
-      </button>
+      <RemoteDesktopToolbar
+        displays={display.displays}
+        currentDisplayId={display.current?.id}
+        onSelectDisplay={display.select}
+        quality={quality}
+        qualityChoice={qualityChoice}
+        onSetQuality={setQuality}
+        onOpenCustomQuality={() => setCustomQualityOpen(true)}
+        codecs={caps?.encoders ?? []}
+        codec={codec}
+        onSetCodec={setCodec}
+        hostModes={caps?.resolutions?.modes ?? []}
+        hostModeId={hostModeId}
+        hostOriginalModeId={hostOriginalModeId}
+        onSetHostMode={setHostMode}
+        canResizeHost={caps?.inputReady ?? false}
+        resolutionError={resolutionError}
+        viewStyle={viewStyle}
+        customScale={customScale}
+        onSetViewStyle={setViewStyle}
+        onSetCustomScale={setCustomScale}
+        showCursor={showCursor}
+        onSetShowCursor={setShowCursor}
+        audioOn={audioOn}
+        audioReason={caps && !caps.audio.available ? caps.audio.reason : null}
+        onSetAudioOn={setAudioOn}
+        privacyOn={privacyOn}
+        privacyReason={privacyError ?? (caps && !caps.privacy.available ? caps.privacy.reason : null)}
+        privacyCanBlank={caps?.privacy?.canBlank ?? false}
+        onSetPrivacyOn={setPrivacyOn}
+        recording={recorder.recording}
+        recordingElapsedSec={recorder.elapsedSec}
+        recordingSupported={recorder.supported}
+        onToggleRecording={recorder.toggle}
+        onScreenshot={() => void saveCanvasScreenshot(canvasRef.current)}
+        clipboardEnabled={clipboardSync}
+        onSetClipboardEnabled={setClipboardSync}
+        statsVisible={statsVisible}
+        onToggleStats={toggleStats}
+      />
+      {/* Only after a real paste attempt: a host with no clipboard tool is not worth a warning
+          until the user actually reaches for it. */}
+      <RemoteDesktopClipboardNotice
+        pendingText={pendingHostClipboard}
+        onDismiss={clearHostClipboard}
+        missingToolAction={pasteAttempted && caps && !caps.clipboard.available ? caps.clipboard.action : null}
+        onDismissMissingTool={() => setPasteAttempted(false)}
+      />
+      <RemoteDesktopCustomQualityDialog
+        open={customQualityOpen}
+        onOpenChange={setCustomQualityOpen}
+        percent={customPercent}
+        fps={customFps}
+        more={customMore}
+        onSetMore={setCustomMore}
+        onCommit={setCustomQuality}
+        frameSize={frameSize}
+      />
       {overlayMessage && (
         <div className="absolute inset-0 flex flex-col items-center justify-center gap-3 bg-black/70 text-sm text-white">
           <MonitorX className="size-6 opacity-70" />

package/src/web/components/remote-desktop/use-h264-canvas-decoder.ts

@@ -46,6 +46,13 @@ export interface UseH264CanvasDecoderResult {
    *  last `reset()`. Ref-backed, not React state — read it from a poll (e.g. the stats overlay),
    *  not a render dependency, so every decoded frame doesn't force a re-render. */
   getFrameCount: () => number;
+  /** Pixel size of the decoded picture — what `canvas.width`/`height` were last set to, 0×0
+   *  before the first frame. Real state rather than a ref (unlike the counter above) because
+   *  the `original`/`custom` scale modes size the *element* from it, and it changes once per
+   *  rung rather than once per frame. Deliberately kept across a `reset()`: a rung switch
+   *  respawns the host encoder, and blanking this mid-switch would collapse the canvas to
+   *  nothing for ~400ms before the new resolution arrives. */
+  frameSize: { width: number; height: number };
 }
 
 export function useH264CanvasDecoder(
@@ -53,6 +60,7 @@ export function useH264CanvasDecoder(
 ): UseH264CanvasDecoderResult {
   const [status, setStatus] = useState<DecoderStatus>("idle");
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [frameSize, setFrameSize] = useState({ width: 0, height: 0 });
   const decoderRef = useRef<VideoDecoder | null>(null);
   const ctxRef = useRef<CanvasRenderingContext2D | null>(null);
   const decodedAnyKeyRef = useRef(false);
@@ -97,6 +105,8 @@ export function useH264CanvasDecoder(
           if (canvas.width !== frame.displayWidth || canvas.height !== frame.displayHeight) {
             canvas.width = frame.displayWidth;
             canvas.height = frame.displayHeight;
+            // Inside the size guard, so this is one setState per resolution change, not per frame.
+            setFrameSize({ width: frame.displayWidth, height: frame.displayHeight });
           }
           if (!ctxRef.current) ctxRef.current = canvas.getContext("2d");
           ctxRef.current?.drawImage(frame, 0, 0, canvas.width, canvas.height);
@@ -171,5 +181,6 @@ export function useH264CanvasDecoder(
     decodeAccessUnit,
     reset,
     getFrameCount,
+    frameSize,
   };
 }

package/src/web/components/remote-desktop/use-opus-audio-player.ts

@@ -0,0 +1,148 @@
+/**
+ * Plays the host's audio: Opus packets → `AudioDecoder` → scheduled into one `AudioContext`.
+ *
+ * The sibling of `use-h264-canvas-decoder.ts`, and it needs no new platform support: every
+ * browser that has `VideoDecoder` (which the viewer already hard-requires) has `AudioDecoder`.
+ *
+ * Scheduling is one `AudioBufferSourceNode` per decoded 20 ms frame against a running cursor,
+ * rather than an `AudioWorklet` ring buffer. That is 50 nodes a second, which the audio thread
+ * does not notice, and it avoids a separate worklet module — the thing a worklet would buy is
+ * sample-accurate underrun handling, and this player wants the opposite: on an underrun it
+ * should jump back to "now" and carry on, because a remote desktop's audio has to stay in sync
+ * with the picture rather than play every sample late.
+ *
+ * `TARGET_LEAD_MS` is that resync threshold in both directions. Too small and every network
+ * hiccup is a gap; too large and the audio lags the video visibly. 120 ms sits above the ~40 ms
+ * the host's Ogg pages arrive in with room for one missed page.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** How far ahead of the clock the next frame is scheduled. Also the resync window: a cursor
+ *  further behind than this has fallen off and is snapped forward. */
+const TARGET_LEAD_MS = 120;
+/** Beyond this the client is scheduling audio it will not hear for a noticeable time, which
+ *  means the host is producing faster than realtime (a resumed suspended sink) — drop to the
+ *  target rather than building a queue that can only be heard late. */
+const MAX_LEAD_MS = 400;
+
+export type AudioPlayerStatus = "idle" | "playing" | "unsupported";
+
+export interface UseOpusAudioPlayerResult {
+  status: AudioPlayerStatus;
+  /** Configure for a stream; safe to call again when the host restarts its encoder. */
+  configure: (channels: number, sampleRate: number) => Promise<void>;
+  /** Feed one Opus packet. Ignored until `configure` has run. */
+  decodePacket: (packet: Uint8Array) => void;
+  /** Tear the decoder and the context down. */
+  reset: () => void;
+  /** Tracks for the recorder to mux in, empty while idle. */
+  getTracks: () => MediaStreamTrack[];
+}
+
+export function useOpusAudioPlayer(): UseOpusAudioPlayerResult {
+  const ctxRef = useRef<AudioContext | null>(null);
+  const decoderRef = useRef<AudioDecoder | null>(null);
+  const destRef = useRef<MediaStreamAudioDestinationNode | null>(null);
+  /** When the next frame should start, in the context's own clock. */
+  const cursorRef = useRef(0);
+  const timestampRef = useRef(0);
+  const [status, setStatus] = useState<AudioPlayerStatus>("idle");
+
+  const reset = useCallback(() => {
+    try { decoderRef.current?.close(); } catch { /* already closed */ }
+    decoderRef.current = null;
+    destRef.current = null;
+    // The context is closed too, not just disconnected: a suspended AudioContext still holds
+    // an audio device open, which on some hosts keeps the sink awake for the whole session.
+    const ctx = ctxRef.current;
+    ctxRef.current = null;
+    if (ctx) void ctx.close().catch(() => {});
+    cursorRef.current = 0;
+    timestampRef.current = 0;
+    setStatus((s) => (s === "unsupported" ? s : "idle"));
+  }, []);
+
+  const play = useCallback((data: AudioData) => {
+    const ctx = ctxRef.current;
+    if (!ctx) { data.close(); return; }
+    const frames = data.numberOfFrames;
+    const channels = data.numberOfChannels;
+    const buffer = ctx.createBuffer(channels, frames, data.sampleRate);
+    // `copyTo` per plane: the decoder hands back planar f32, which is exactly what an
+    // AudioBuffer channel wants, so there is no interleaving to undo.
+    for (let ch = 0; ch < channels; ch++) {
+      const plane = new Float32Array(frames);
+      data.copyTo(plane, { planeIndex: ch, format: "f32-planar" });
+      buffer.copyToChannel(plane, ch);
+    }
+    data.close();
+
+    const now = ctx.currentTime;
+    const lead = (cursorRef.current - now) * 1000;
+    // Underrun (the cursor is in the past) or a runaway queue: snap back to the target lead.
+    // Without this the first case plays everything late forever and the second drifts further
+    // behind the picture with every packet.
+    if (lead < 0 || lead > MAX_LEAD_MS) cursorRef.current = now + TARGET_LEAD_MS / 1000;
+
+    const source = ctx.createBufferSource();
+    source.buffer = buffer;
+    source.connect(ctx.destination);
+    if (destRef.current) source.connect(destRef.current);
+    source.start(cursorRef.current);
+    cursorRef.current += buffer.duration;
+  }, []);
+
+  const configure = useCallback(async (channels: number, sampleRate: number) => {
+    if (typeof AudioDecoder === "undefined" || typeof AudioContext === "undefined") {
+      setStatus("unsupported");
+      return;
+    }
+    reset();
+    const ctx = new AudioContext({ sampleRate, latencyHint: "interactive" });
+    ctxRef.current = ctx;
+    // Autoplay policy: a context created without a user gesture starts suspended, and
+    // `resume()` only succeeds once the page has one. The toggle that turns audio on *is* a
+    // click, so by the time this runs there has been one.
+    if (ctx.state === "suspended") await ctx.resume().catch(() => {});
+    destRef.current = ctx.createMediaStreamDestination();
+
+    const decoder = new AudioDecoder({
+      output: play,
+      // A decode error is one bad packet, not a dead stream: Opus frames are independent, so
+      // the next one decodes fine. Resetting instead of closing keeps the stream alive.
+      error: () => { try { decoderRef.current?.reset(); } catch { /* gone */ } },
+    });
+    try {
+      decoder.configure({ codec: "opus", sampleRate, numberOfChannels: channels });
+    } catch {
+      setStatus("unsupported");
+      return;
+    }
+    decoderRef.current = decoder;
+    cursorRef.current = 0;
+    timestampRef.current = 0;
+    setStatus("playing");
+  }, [play, reset]);
+
+  const decodePacket = useCallback((packet: Uint8Array) => {
+    const decoder = decoderRef.current;
+    if (!decoder || decoder.state !== "configured") return;
+    // Timestamps have to advance monotonically or the decoder rejects the chunk, and the host
+    // sends no per-packet pts — so they are counted here at the one frame duration the encoder
+    // is pinned to (`-frame_duration 20`).
+    const timestamp = timestampRef.current;
+    timestampRef.current += 20_000;
+    try {
+      decoder.decode(new EncodedAudioChunk({ type: "key", timestamp, data: packet }));
+    } catch { /* a chunk the decoder refused; the next one is independent */ }
+  }, []);
+
+  const getTracks = useCallback(
+    () => (destRef.current ? destRef.current.stream.getAudioTracks() : []),
+    [],
+  );
+
+  useEffect(() => () => reset(), [reset]);
+
+  return { status, configure, decodePacket, reset, getTracks };
+}