@agent-native/core 0.169.0 → 0.170.0

package/corpus/templates/clips/desktop/src/app.tsx

@@ -404,11 +404,10 @@ const CAM_ON_KEY = "clips:camera-on";
 const MIC_ON_KEY = "clips:mic-on";
 const SYSTEM_AUDIO_KEY = "clips:system-audio";
 const READINESS_REVIEWED_KEY = "clips:readiness-reviewed";
-// The tray's rolling buffer, which the docs publish under its internal name.
-// Not `#rewind-quick-save`: that section describes pulling a pre-roll from the
-// third-party rewind.ai app, which this app does not integrate with at all.
+// The docs section for the tray's rolling buffer, published under the same
+// Rewind name the settings tab uses.
 const REWIND_DOCS_URL =
-  "https://www.agent-native.com/docs/template-clips-capture-everywhere#screen-memory";
+  "https://www.agent-native.com/docs/template-clips-capture-everywhere#rewind";
 
 // Sensible defaults so the user never has to type a URL on first launch.
 // Dev builds point at the local dev server; production builds point at the
@@ -2697,6 +2696,7 @@ export function App({
     let stopPump: (() => void) | null = null;
     let fellBackToPump = false;
     let stream: MediaStream | null = null;
+    let unlistenUnrendered: (() => void) | null = null;
 
     const startPump = (reason: string) => {
       if (cancelled || stopPump || !stream) return;
@@ -2757,11 +2757,30 @@ export function App({
           webrtcHandle = null;
           startPump(reason);
         };
+        // ICE reaching `connected` proves the transport works, nothing more.
+        // WKWebView can refuse to play the received track (no user gesture in
+        // the bubble page, or its window briefly had no on-screen area), and
+        // that failure is invisible from here — so the bubble reports it and
+        // we fall back to the pump. Without this the safety net below only
+        // ever fired on ICE failure, which is not how this breaks in practice.
+        listen("clips:bubble-webrtc-unrendered", (ev) => {
+          startCanvasFallback(
+            `bubble reported no rendered frames ${JSON.stringify(ev.payload)}`,
+          );
+        })
+          .then((u) => {
+            if (cancelled) {
+              u();
+              return;
+            }
+            unlistenUnrendered = u;
+          })
+          .catch(() => {});
         webrtcHandle = startBubbleWebrtc({
           stream: s,
           onConnected: () => {
             console.log(
-              "[clips-popover] bubble WebRTC connected — video is live",
+              "[clips-popover] bubble WebRTC transport connected — waiting for the bubble to confirm playback",
             );
           },
           onFailure: startCanvasFallback,
@@ -2806,6 +2825,10 @@ export function App({
         !!webrtcHandle,
         !!stopPump,
       );
+      if (unlistenUnrendered) {
+        unlistenUnrendered();
+        unlistenUnrendered = null;
+      }
       if (webrtcHandle) {
         webrtcHandle.stop();
         webrtcHandle = null;
@@ -3293,11 +3316,14 @@ export function App({
       // A restart hands off the already-live display stream from the take
       // it's replacing (see `discardForRestart`/`preAcquiredDisplayStream`
       // below) — it must keep recording the same screen, not re-prompt.
-      if (source === "full-screen" && !options?.resumeCapture) {
+      if (
+        (source === "full-screen" || source === "region") &&
+        !options?.resumeCapture
+      ) {
         try {
           // Must resolve before `recordingFlowActive` flips the toolbar on
-          // below — the toolbar reads the pick to place itself on the
-          // chosen screen the first time it's shown.
+          // below — the toolbar and region selector read the pick to place
+          // themselves on the chosen screen the first time they are shown.
           await pickFullscreenRecordingDisplay();
         } catch (err) {
           recordingFlowGateRef.current = false;
@@ -3835,22 +3861,25 @@ export function App({
   const showCameraRow = mode !== "screen"; // screen-only has no camera
   const showSourceRow = mode !== "camera"; // camera-only has no screen source
 
-  const pendingUploadBanner = recordingStopFinalizing ? (
-    <FinalizingUploadBanner />
-  ) : pendingUploads.length > 0 ? (
-    <PendingUploadBanner
-      uploads={pendingUploads}
-      retryingUploadId={retryingUploadId}
-      retryingUploadStatus={retryingUploadStatus}
-      exportingUploadId={exportingUploadId}
-      dismissingUploadId={dismissingUploadId}
-      onExport={exportPendingUpload}
-      onRetry={retryPendingUpload}
-      onDismiss={dismissPendingUpload}
-      onOpenFolder={openPendingUploadFolder}
-      onConnectStorage={(upload) => openVideoStorageSetup(upload.serverUrl)}
-    />
-  ) : null;
+  const pendingUploadBanner =
+    authStatus === "authed" ? (
+      recordingStopFinalizing ? (
+        <FinalizingUploadBanner />
+      ) : pendingUploads.length > 0 ? (
+        <PendingUploadBanner
+          uploads={pendingUploads}
+          retryingUploadId={retryingUploadId}
+          retryingUploadStatus={retryingUploadStatus}
+          exportingUploadId={exportingUploadId}
+          dismissingUploadId={dismissingUploadId}
+          onExport={exportPendingUpload}
+          onRetry={retryPendingUpload}
+          onDismiss={dismissPendingUpload}
+          onOpenFolder={openPendingUploadFolder}
+          onConnectStorage={(upload) => openVideoStorageSetup(upload.serverUrl)}
+        />
+      ) : null
+    ) : null;
 
   async function copyRewindAgentPrompt() {
     try {

package/corpus/templates/clips/desktop/src/lib/bubble-playback.ts

@@ -0,0 +1,68 @@
+/**
+ * When the camera bubble may declare its WebRTC video dead.
+ *
+ * WKWebView refuses to start a MediaStream-backed `<video>` that has had no
+ * user gesture in its page, and pauses one again whenever the owning window
+ * loses on-screen area. Neither shows up as an ICE failure, so the bubble's
+ * transport can be perfectly connected while the user stares at WebKit's
+ * start-playback overlay — a black circle with a white triangle. The bubble
+ * retries `play()` on a heartbeat, and uses the predicates here to decide when
+ * retrying has stopped being plausible and the popover should be asked for the
+ * canvas pump instead.
+ */
+
+/** Re-play cadence for the WKWebView pause/block trap — matches `bubble-pump.ts`. */
+export const BUBBLE_PLAY_HEARTBEAT_MS = 2000;
+
+/**
+ * How long a WebRTC track may sit without producing frames before we give up
+ * on it. Long enough to cover a slow first decode, short enough that the user
+ * is not left wondering whether the camera is broken.
+ */
+export const BUBBLE_RENDER_GRACE_MS = 2500;
+
+export type BubblePlaybackProbe = {
+  /** When the current track arrived, or `null` when there is no track yet. */
+  trackArrivedAt: number | null;
+  now: number;
+  paused: boolean;
+  /** `0` until WebKit has decoded a frame, so it is the honest render signal. */
+  videoWidth: number;
+  alreadyReported: boolean;
+};
+
+/**
+ * Whether WebRTC video is actually on screen. `videoWidth > 0` is the part
+ * that matters: a `<video>` reports `paused === false` the moment `play()`
+ * resolves, well before any frame is decoded, so "playing" alone is not proof
+ * the user can see anything.
+ */
+export function isRenderingWebrtc(
+  probe: Pick<BubblePlaybackProbe, "paused" | "videoWidth">,
+): boolean {
+  return !probe.paused && probe.videoWidth > 0;
+}
+
+/**
+ * Whether a `playing` event may give the WebRTC `<video>` the visible surface.
+ *
+ * Once the bubble has asked for the canvas pump the popover stops sending, so
+ * a later `playing` is the tail of a dead stream. Taking the surface there
+ * would park a still frame over the pump's live output. Only a fresh track
+ * clears `fallbackRequested` and re-arms this.
+ */
+export function shouldClaimWebrtcPath(input: {
+  fallbackRequested: boolean;
+  videoWidth: number;
+}): boolean {
+  if (input.fallbackRequested) return false;
+  return input.videoWidth > 0;
+}
+
+/** Whether the bubble should ask the popover to fall back to the canvas pump. */
+export function shouldReportUnrendered(probe: BubblePlaybackProbe): boolean {
+  if (probe.alreadyReported) return false;
+  if (probe.trackArrivedAt == null) return false;
+  if (isRenderingWebrtc(probe)) return false;
+  return probe.now - probe.trackArrivedAt >= BUBBLE_RENDER_GRACE_MS;
+}

package/corpus/templates/clips/desktop/src/lib/recorder.ts

@@ -1672,6 +1672,9 @@ async function saveRecordingTranscript(
         fullText: text,
         segments: transcript.segments,
         source: transcript.source ?? "whisper",
+        ...(transcript.failureReason
+          ? { failureReason: transcript.failureReason }
+          : {}),
       }),
       signal: AbortSignal.timeout(TRANSCRIPT_SAVE_TIMEOUT_MS),
     });

package/corpus/templates/clips/desktop/src/lib/transcription-capture.ts

@@ -28,6 +28,8 @@ import {
 /** Grace period after stop for whisper to emit any flushed trailing finals. */
 const WHISPER_STOP_SETTLE_MS = 1500;
 const WEB_SPEECH_STOP_SETTLE_MS = 1200;
+const WEB_SPEECH_RESTART_RETRY_BASE_MS = 400;
+const WEB_SPEECH_MAX_RESTART_ATTEMPTS = 8;
 
 function wait(ms: number): Promise<void> {
   return new Promise((resolve) => window.setTimeout(resolve, ms));
@@ -42,6 +44,10 @@ export interface CapturedTranscript {
   segments: SourcedTranscriptSegment[];
   /** Source stored with `save-browser-transcript`. */
   source?: "web-speech" | "macos-native" | "whisper";
+  /** Set when capture died partway. Text plus a reason is what tells the server
+   *  this transcript is truncated and has to be re-transcribed in the cloud;
+   *  omitting it saves a partial capture as a complete one. */
+  failureReason?: string;
 }
 
 export interface TranscriptionCapture {
@@ -170,15 +176,54 @@ async function startBrowserTranscriptionCapture(): Promise<TranscriptionCapture
   const transcriptBuffer = createWebSpeechTranscriptBuffer();
   let stopResolver: ((value: CapturedTranscript) => void) | null = null;
   let settleTimer: ReturnType<typeof window.setTimeout> | null = null;
+  let restartTimer: ReturnType<typeof window.setTimeout> | null = null;
+  let restartFailures = 0;
+  let failureReason: string | null = null;
 
   const captured = (): CapturedTranscript => ({
     text: transcriptBuffer.text(),
     segments: [],
     source: "web-speech",
+    failureReason: failureReason ?? undefined,
   });
 
+  const clearRestartTimer = () => {
+    if (restartTimer === null) return;
+    window.clearTimeout(restartTimer);
+    restartTimer = null;
+  };
+
+  // Chrome ends the recognizer on its own roughly every minute, and always
+  // throws if start() is called synchronously from inside `onend`. Nothing
+  // starts, so no further `onend` arrives — the retry has to live here or the
+  // first failure ends transcription for the rest of the recording.
+  const scheduleRestart = (delayMs: number) => {
+    if (restartTimer !== null) return;
+    restartTimer = window.setTimeout(() => {
+      restartTimer = null;
+      if (disposed || stopped || paused) return;
+      try {
+        recognition.start();
+        restartFailures = 0;
+      } catch (err) {
+        const attempt = ++restartFailures;
+        if (attempt >= WEB_SPEECH_MAX_RESTART_ATTEMPTS) {
+          failureReason =
+            "Web Speech transcription stopped mid-recording and could not be restarted.";
+          console.warn(
+            "[clips-recorder] Web Speech transcription restart failed:",
+            err,
+          );
+          return;
+        }
+        scheduleRestart(WEB_SPEECH_RESTART_RETRY_BASE_MS * attempt);
+      }
+    }, delayMs);
+  };
+
   const settleStop = () => {
     if (!stopResolver) return;
+    clearRestartTimer();
     if (settleTimer) {
       window.clearTimeout(settleTimer);
       settleTimer = null;
@@ -200,6 +245,12 @@ async function startBrowserTranscriptionCapture(): Promise<TranscriptionCapture
 
   recognition.onerror = (event) => {
     if (event.error === "no-speech" || event.error === "aborted") return;
+    // A non-benign error drops audio until `onend` restarts recognition. That
+    // restart usually succeeds, so without recording the gap here the transcript
+    // saves as complete and the server never schedules cloud transcription for
+    // the missing stretch. Deliberately not cleared by a later successful
+    // restart: recovering the engine does not recover the lost speech.
+    failureReason ??= `Web Speech transcription dropped audio after a "${event.error}" error.`;
     console.warn(
       "[clips-recorder] Web Speech transcription error:",
       event.error,
@@ -215,14 +266,7 @@ async function startBrowserTranscriptionCapture(): Promise<TranscriptionCapture
     }
     // While paused, keep the committed transcript but don't restart the engine.
     if (paused) return;
-    try {
-      recognition.start();
-    } catch (err) {
-      console.warn(
-        "[clips-recorder] Web Speech transcription restart failed:",
-        err,
-      );
-    }
+    scheduleRestart(0);
   };
 
   try {
@@ -250,6 +294,7 @@ async function startBrowserTranscriptionCapture(): Promise<TranscriptionCapture
     async cancel() {
       disposed = true;
       stopped = true;
+      clearRestartTimer();
       if (settleTimer) {
         window.clearTimeout(settleTimer);
         settleTimer = null;
@@ -273,14 +318,18 @@ async function startBrowserTranscriptionCapture(): Promise<TranscriptionCapture
     async resume() {
       if (disposed || stopped || !paused) return;
       paused = false;
+      restartFailures = 0;
       console.log("[clips-recorder] transcription resumed (web-speech)");
       try {
         recognition.start();
-      } catch (err) {
-        console.warn(
-          "[clips-recorder] Web Speech transcription resume failed:",
-          err,
-        );
+      } catch {
+        // `paused` is already false, so the recording is live through the
+        // failed start and the retry delay. A later successful retry does not
+        // recover that speech, so the gap is recorded durably and the server
+        // still schedules cloud transcription.
+        failureReason ??=
+          "Web Speech transcription dropped audio while resuming after a pause.";
+        scheduleRestart(WEB_SPEECH_RESTART_RETRY_BASE_MS);
       }
     },
     async resetTimeline() {
@@ -289,7 +338,10 @@ async function startBrowserTranscriptionCapture(): Promise<TranscriptionCapture
   };
 }
 
-export const __test = { createWebSpeechTranscriptBuffer };
+export const __test = {
+  createWebSpeechTranscriptBuffer,
+  startBrowserTranscriptionCapture,
+};
 
 /**
  * Local transcription opens a microphone capture of its own. System-only
@@ -321,6 +373,7 @@ export async function startTranscriptionCapture(
   // asynchronously. Track when those are expected to have landed so a stop
   // soon after a pause waits for them instead of dropping the last words.
   let pauseFinalsSettleUntil = 0;
+  let transitionFailure: string | null = null;
   const unlistens: UnlistenFn[] = [];
 
   const cleanup = () => {
@@ -342,6 +395,7 @@ export async function startTranscriptionCapture(
     text: transcriptFullText(lines),
     segments: transcriptSegments(lines),
     source: engine,
+    failureReason: transitionFailure ?? undefined,
   });
 
   let engine: TranscriptionEngine;
@@ -407,6 +461,7 @@ export async function startTranscriptionCapture(
       // reset it) so the next pause/resume toggle retries and converges, and
       // return early so we don't busy-loop re-applying a persistently failing
       // transition. `paused` still reflects the real engine state.
+      transitionFailure = `Local transcription ${desiredPaused ? "pause" : "resume"} failed; engine still ${paused ? "paused" : "live"}.`;
       console.warn(
         `[clips-recorder] transcription ${desiredPaused ? "pause" : "resume"} failed; engine still ${paused ? "paused" : "live"}:`,
         err,
@@ -416,6 +471,9 @@ export async function startTranscriptionCapture(
     } finally {
       transitioning = false;
     }
+    // Reached only when the transition landed, so a failure the next toggle
+    // converged on is no longer a reason to re-transcribe in the cloud.
+    transitionFailure = null;
     // Re-apply in case the desired state changed mid-transition.
     void applyAudioState();
   };

package/corpus/templates/clips/desktop/src/lib/updater.ts

@@ -96,8 +96,9 @@ async function runCheck() {
   // made "Restart to update" land on a binary that was already out of date and
   // immediately ask to restart again — every check runs against the *running*
   // version, so it re-offers the staged version until a newer one ships.
-  const staged =
-    cachedStatus.state === "downloaded" ? cachedStatus.version : null;
+  const stagedStatus =
+    cachedStatus.state === "downloaded" ? cachedStatus : null;
+  const staged = stagedStatus?.version ?? null;
 
   lastCheckStartedAt = Date.now();
   checkInFlight = (async () => {
@@ -114,7 +115,11 @@ async function runCheck() {
       }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      setStatus({ state: "error", message });
+      // A staged bundle is already on disk and `pendingUpdate` still points at
+      // it. Reporting the check failure here would replace the Restart banner
+      // with an error card that has no way back to it, and would make the next
+      // successful check re-download the same version from scratch.
+      setStatus(stagedStatus ?? { state: "error", message });
     } finally {
       checkInFlight = null;
     }

package/corpus/templates/clips/desktop/src/overlays/bubble.tsx

@@ -3,6 +3,14 @@ import { invoke } from "@tauri-apps/api/core";
 import { emit, listen } from "@tauri-apps/api/event";
 import { getCurrentWindow } from "@tauri-apps/api/window";
 import { useEffect, useRef, useState } from "react";
+
+import {
+  BUBBLE_PLAY_HEARTBEAT_MS,
+  BUBBLE_RENDER_GRACE_MS,
+  shouldClaimWebrtcPath,
+  shouldReportUnrendered,
+} from "../lib/bubble-playback";
+
 type BubbleSize = "small" | "medium";
 
 /**
@@ -41,10 +49,13 @@ type BubbleSize = "small" | "medium";
  *      feature degrades gracefully if the WebRTC handshake fails.
  *
  * The bubble always sets up BOTH receivers on mount. Whichever path
- * delivers video first wins — the other stays passive. If the
- * popover's WebRTC handshake fails (ICE timeout / failed state), it
- * stops trying and the popover starts the canvas pump instead, at
- * which point the canvas path takes over seamlessly.
+ * delivers video first wins — the other stays passive. The popover
+ * starts the canvas pump instead when the WebRTC handshake fails (ICE
+ * timeout / failed state) OR when this bubble reports that a connected
+ * track never rendered (`clips:bubble-webrtc-unrendered`; see the
+ * playback watchdog below). Both signals are needed — ICE reaching
+ * `connected` says the transport works, never that WebKit painted a
+ * frame.
  *
  * # Hover controls (Loom-style)
  *
@@ -59,16 +70,29 @@ type BubbleSize = "small" | "medium";
 export function Bubble() {
   // Dual-path rendering: <video> for WebRTC, <canvas> for the legacy
   // JPEG stream. CSS stacks them in the same circle — whichever has a
-  // stream / frames visible fills the same space. Starts with canvas
-  // hidden via `data-path="webrtc"` on the root; once a WebRTC track
-  // arrives we set it to "webrtc", and if WebRTC fails and canvas
-  // frames start arriving we flip to "canvas".
+  // stream / frames visible fills the same space. `data-path` on the root
+  // hides the loser. It flips to "webrtc" only once the <video> actually
+  // renders a frame, and to "canvas" on the first JPEG frame.
   const videoRef = useRef<HTMLVideoElement | null>(null);
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
   const firstFrameAtRef = useRef<number | null>(null);
-  // Which transport delivered the most recent usable frame. Starts as
-  // "none" — we flip to "webrtc" on ontrack, or "canvas" on the first
-  // JPEG frame, whichever lands first.
+  const firstTrackAtRef = useRef<number | null>(null);
+  // When the current WebRTC track arrived, so the playback watchdog can tell
+  // "no track yet" from "track arrived and WebKit still isn't rendering it".
+  const trackArrivedAtRef = useRef<number | null>(null);
+  // Assigned by the playback watchdog effect; called from `ontrack`, which
+  // lives in a different effect and must not own the retry policy.
+  const attemptPlayRef = useRef<() => void>(() => {});
+  // True once we've told the popover this track is dead and asked for the
+  // canvas pump. Shared across both effects: the watchdog sets it, and only a
+  // fresh track clears it, so the surface can't be handed back to a stream the
+  // popover has already stopped sending.
+  const fallbackRequestedRef = useRef(false);
+  // Which transport last put pixels on screen. Starts as "none"; the
+  // playback watchdog flips it to "webrtc" on a `playing` event with real
+  // frame dimensions, and the canvas sink flips it on the first JPEG frame.
+  // A track merely arriving is NOT enough — claiming "webrtc" there hid the
+  // canvas fallback exactly when WebKit had refused to play the video.
   const [activePath, setActivePath] = useState<"none" | "webrtc" | "canvas">(
     "none",
   );
@@ -153,6 +177,121 @@ export function Bubble() {
     }
   };
 
+  // ---- playback watchdog --------------------------------------------------
+  // WKWebView will not start a MediaStream-backed `<video>` that has had no
+  // user gesture in the page, and pauses one again whenever its window loses
+  // on-screen area. One `play()` at `ontrack` time therefore leaves the
+  // element parked behind WebKit's start-playback overlay — the black circle
+  // with a white triangle users report — and nothing ever retries it. The
+  // popover's offscreen pump video already defends itself the same way (see
+  // `bubble-pump.ts`); this is the bubble's copy of that defense.
+  //
+  // It also owns the `activePath` transition: only a `playing` event with real
+  // frame dimensions proves WebRTC is on screen. Flipping on `ontrack` instead
+  // hid the canvas fallback exactly when it was needed.
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video) return;
+    let stopped = false;
+    let lastFailure: string | null = null;
+
+    const attemptPlay = () => {
+      if (stopped) return;
+      if (!video.srcObject || !video.paused) return;
+      video.play().catch((err: unknown) => {
+        // Name and message, not the raw object: `console.warn` on a
+        // DOMException logs only its stack, which cannot tell NotAllowedError
+        // (playback blocked) from AbortError (load interrupted) — the two
+        // point at different bugs. Log each distinct reason once so the retry
+        // loop cannot bury the rest of the log.
+        const name = (err as { name?: string } | null)?.name ?? "unknown";
+        const message =
+          (err as { message?: string } | null)?.message ?? String(err);
+        const signature = `${name}: ${message}`;
+        if (lastFailure === signature) return;
+        lastFailure = signature;
+        console.warn("[bubble] video.play() rejected —", signature);
+      });
+    };
+    attemptPlayRef.current = attemptPlay;
+
+    const maybeClaimWebrtcPath = () => {
+      const claims = shouldClaimWebrtcPath({
+        fallbackRequested: fallbackRequestedRef.current,
+        videoWidth: video.videoWidth,
+      });
+      if (!claims) return;
+      setActivePath((current) => {
+        if (current !== "webrtc") {
+          console.log(
+            "[bubble] webrtc playback started %dx%d",
+            video.videoWidth,
+            video.videoHeight,
+          );
+        }
+        return "webrtc";
+      });
+    };
+
+    const onPlaying = () => {
+      if (stopped) return;
+      lastFailure = null;
+      maybeClaimWebrtcPath();
+    };
+
+    video.addEventListener("playing", onPlaying);
+    video.addEventListener("loadedmetadata", attemptPlay);
+    video.addEventListener("canplay", attemptPlay);
+    video.addEventListener("pause", attemptPlay);
+    document.addEventListener("visibilitychange", attemptPlay);
+
+    // Heartbeat: covers the resume cases no media event fires for (window
+    // shrunk to no visible area and back, a gesture landing on a control
+    // rather than the video). `play()` on an already-playing element is a
+    // no-op, so this is cheap. It doubles as the unrendered detector — if a
+    // track has been sitting there for BUBBLE_RENDER_GRACE_MS with no frames,
+    // tell the popover so it can start the proven canvas pump instead of
+    // leaving the user with a dead circle.
+    const heartbeat = setInterval(() => {
+      if (stopped) return;
+      attemptPlay();
+      maybeClaimWebrtcPath();
+      const unrendered = shouldReportUnrendered({
+        trackArrivedAt: trackArrivedAtRef.current,
+        now: Date.now(),
+        paused: video.paused,
+        videoWidth: video.videoWidth,
+        alreadyReported: fallbackRequestedRef.current,
+      });
+      if (!unrendered) return;
+      fallbackRequestedRef.current = true;
+      console.warn(
+        "[bubble] webrtc track is not rendering after %dms (paused=%o readyState=%d videoWidth=%d) — asking popover for the canvas pump",
+        BUBBLE_RENDER_GRACE_MS,
+        video.paused,
+        video.readyState,
+        video.videoWidth,
+      );
+      emit("clips:bubble-webrtc-unrendered", {
+        paused: video.paused,
+        readyState: video.readyState,
+        videoWidth: video.videoWidth,
+        lastPlayFailure: lastFailure,
+      }).catch(() => {});
+    }, BUBBLE_PLAY_HEARTBEAT_MS);
+
+    return () => {
+      stopped = true;
+      clearInterval(heartbeat);
+      video.removeEventListener("playing", onPlaying);
+      video.removeEventListener("loadedmetadata", attemptPlay);
+      video.removeEventListener("canplay", attemptPlay);
+      video.removeEventListener("pause", attemptPlay);
+      document.removeEventListener("visibilitychange", attemptPlay);
+      attemptPlayRef.current = () => {};
+    };
+  }, []);
+
   // ---- WebRTC receiver ----------------------------------------------------
   // Sets up a fresh RTCPeerConnection on mount, emits `bubble-ready`
   // so the popover knows to start the handshake, and renegotiates on
@@ -187,6 +326,7 @@ export function Bubble() {
     };
 
     function teardownPeer() {
+      trackArrivedAtRef.current = null;
       if (pc) {
         // Detach the incoming video <video>.srcObject BEFORE closing the
         // peer — otherwise WKWebView's media pipeline keeps the decoder
@@ -272,17 +412,19 @@ export function Bubble() {
         const incomingStream = ev.streams[0];
         if (!incomingStream) return;
         videoEl.srcObject = incomingStream;
-        videoEl.play().catch((err) => {
-          // Autoplay might be blocked in some WebKit corners —
-          // `muted` + `playsInline` in JSX should be enough, but log
-          // if it trips so we know to investigate.
-          console.warn("[bubble] video.play() rejected", err);
-        });
-        if (firstFrameAtRef.current == null) {
-          firstFrameAtRef.current = Date.now();
+        // Do NOT flip `activePath` here. A track arriving proves the
+        // transport works, not that WebKit will render it — see the
+        // playback watchdog below, which owns that transition and the
+        // fallback when playback never starts.
+        trackArrivedAtRef.current = Date.now();
+        // A fresh track is a fresh chance: re-arm the watchdog so it can both
+        // grant this one the surface and report it dead in turn.
+        fallbackRequestedRef.current = false;
+        attemptPlayRef.current();
+        if (firstTrackAtRef.current == null) {
+          firstTrackAtRef.current = Date.now();
           console.log("[bubble] first webrtc track received");
         }
-        setActivePath("webrtc");
       };
 
       try {