@agent-native/core 0.70.3 → 0.72.0

package/corpus/templates/clips/app/components/recorder/recorder-engine.ts

@@ -19,6 +19,15 @@ import {
   createCameraCompositeStream,
   type CameraCompositeHandle,
 } from "@/lib/camera-composite";
+import {
+  chunkUploadUrl,
+  pickMimeType,
+  pickMimeTypeCandidates,
+} from "@shared/recording-core";
+
+// Re-exported for existing callers; the canonical impls live in
+// @shared/recording-core and are shared with the Chrome extension recorder.
+export { pickMimeType, pickMimeTypeCandidates };
 
 export type RecordingMode = "screen" | "camera" | "screen+camera";
 export type DisplaySurface = "monitor" | "window" | "browser";
@@ -281,34 +290,6 @@ function isScreenPickerDismissal(err: unknown): boolean {
   return false;
 }
 
-/** Pick a MediaRecorder mimeType the current browser actually supports. */
-export function pickMimeTypeCandidates(): string[] {
-  // Chrome can report MP4 support but still reject the encoder configuration
-  // for some display-capture streams. Prefer the WebM combinations that are
-  // broadly supported by MediaRecorder, then fall back to MP4/Safari.
-  return [
-    "video/webm;codecs=vp8,opus",
-    "video/webm;codecs=vp9,opus",
-    "video/webm;codecs=vp8",
-    "video/webm;codecs=vp9",
-    "video/webm",
-    "video/mp4;codecs=avc1",
-    "video/mp4",
-  ];
-}
-
-export function pickMimeType(): string {
-  if (typeof MediaRecorder === "undefined") return "video/webm";
-  for (const type of pickMimeTypeCandidates()) {
-    try {
-      if (MediaRecorder.isTypeSupported(type)) return type;
-    } catch {
-      // continue
-    }
-  }
-  return "";
-}
-
 function canUseTimeslicedRecorderChunks(mimeType: string): boolean {
   // WebM chunks emitted by MediaRecorder are safe to concatenate locally before
   // compression/upload. Browser MP4 chunks are not reliably self-contained; in
@@ -1589,21 +1570,17 @@ export class RecorderEngine {
       signal?: AbortSignal;
     } = {},
   ): Promise<Record<string, unknown> | undefined> {
-    const params = new URLSearchParams();
-    params.set("index", String(index));
-    if (extra.total !== undefined) params.set("total", String(extra.total));
-    params.set("isFinal", extra.isFinal ? "1" : "0");
-    if (extra.mimeType) params.set("mimeType", extra.mimeType);
-    if (extra.durationMs !== undefined)
-      params.set("durationMs", String(Math.round(extra.durationMs)));
-    if (extra.width !== undefined) params.set("width", String(extra.width));
-    if (extra.height !== undefined) params.set("height", String(extra.height));
-    if (extra.hasAudio !== undefined)
-      params.set("hasAudio", extra.hasAudio ? "1" : "0");
-    if (extra.hasCamera !== undefined)
-      params.set("hasCamera", extra.hasCamera ? "1" : "0");
-
-    const url = `${this.opts.uploadUrl}?${params.toString()}`;
+    const url = chunkUploadUrl(this.opts.uploadUrl, {
+      index,
+      total: extra.total,
+      isFinal: extra.isFinal,
+      mimeType: extra.mimeType,
+      durationMs: extra.durationMs,
+      width: extra.width,
+      height: extra.height,
+      hasAudio: extra.hasAudio,
+      hasCamera: extra.hasCamera,
+    });
 
     const body = await blob.arrayBuffer();
     let res: Response | null = null;

package/corpus/templates/clips/app/components/recorder/recording-toolbar.tsx

@@ -25,6 +25,10 @@ export interface RecordingToolbarProps {
 
 const TOOLBAR_WIDTH = 276;
 const TOOLBAR_HEIGHT = 56;
+// Drop the toolbar just below the centered "Recording your screen…" status
+// text (which sits at the viewport's vertical center) so the controls don't
+// overlap it.
+const TOOLBAR_TOP_OFFSET = 48;
 
 function formatElapsed(ms: number): string {
   const totalSeconds = Math.max(0, Math.floor(ms / 1000));
@@ -47,7 +51,7 @@ export function RecordingToolbar({
       ? { left: 16, top: 16, corner: "tl" }
       : {
           left: Math.max(16, (window.innerWidth - TOOLBAR_WIDTH) / 2),
-          top: Math.max(16, (window.innerHeight - TOOLBAR_HEIGHT) / 2),
+          top: Math.max(16, window.innerHeight / 2 + TOOLBAR_TOP_OFFSET),
           corner: "tl",
         },
   );

package/corpus/templates/clips/app/lib/countdown-audio-cue.ts

@@ -1,3 +1,5 @@
+import { scheduleReadyChime } from "@shared/recording-audio";
+
 export interface CountdownAudioCue {
   play(): Promise<void>;
   cleanup(): void;
@@ -8,56 +10,6 @@ const noopCountdownAudioCue: CountdownAudioCue = {
   cleanup() {},
 };
 
-/**
- * A soft, modern "ready" chime: a rising two-note (D5 → A5) with a faint high
- * shimmer. Each voice has a fast attack and a smooth exponential tail so it
- * reads as a gentle confirmation rather than a harsh beep. Kept under ~380ms so
- * it lands cleanly just before capture.
- */
-function scheduleCountdownTone(ctx: AudioContext): Promise<void> {
-  return new Promise<void>((resolve) => {
-    const t0 = ctx.currentTime + 0.005;
-    const voices = [
-      { freq: 587.33, at: 0.0, dur: 0.22, peak: 0.06 }, // D5
-      { freq: 880.0, at: 0.06, dur: 0.26, peak: 0.075 }, // A5
-      { freq: 1760.0, at: 0.065, dur: 0.14, peak: 0.02 }, // A6 shimmer
-    ];
-
-    let lastStop = t0;
-    for (const voice of voices) {
-      const startAt = t0 + voice.at;
-      const stopAt = startAt + voice.dur;
-      lastStop = Math.max(lastStop, stopAt);
-
-      const oscillator = ctx.createOscillator();
-      oscillator.type = "sine";
-      oscillator.frequency.setValueAtTime(voice.freq, startAt);
-
-      const gain = ctx.createGain();
-      gain.gain.setValueAtTime(0.0001, startAt);
-      gain.gain.exponentialRampToValueAtTime(voice.peak, startAt + 0.012);
-      gain.gain.exponentialRampToValueAtTime(0.0001, stopAt);
-
-      oscillator.connect(gain);
-      gain.connect(ctx.destination);
-
-      oscillator.start(startAt);
-      oscillator.stop(stopAt + 0.02);
-    }
-
-    let resolved = false;
-    const finish = () => {
-      if (resolved) return;
-      resolved = true;
-      resolve();
-    };
-    window.setTimeout(
-      finish,
-      Math.ceil((lastStop - ctx.currentTime) * 1000) + 60,
-    );
-  });
-}
-
 export function createCountdownAudioCue(): CountdownAudioCue {
   try {
     const AudioCtx =
@@ -87,7 +39,7 @@ export function createCountdownAudioCue(): CountdownAudioCue {
       try {
         if (ctx.state !== "running") await ctx.resume();
         if (closed) return;
-        await scheduleCountdownTone(ctx);
+        await scheduleReadyChime(ctx);
       } catch (err) {
         console.warn("[recorder] countdown cue unavailable:", err);
         cleanup();

package/corpus/templates/clips/changelog/2026-06-23-dragging-the-desktop-camera-bubble-now-glides-to-a-stop-at-t.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-23
+---
+
+Dragging the desktop camera bubble now glides to a stop at the screen edge instead of jittering or snapping back

package/corpus/templates/clips/changelog/2026-06-23-public-clips-now-play-inline-in-slack-connect-a-workspac.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-06-23
+---
+
+Clips for Slack is here — connect a workspace under Settings, then paste any public clip link in Slack and it unfurls as a playable video

package/corpus/templates/clips/chrome-extension/PERMISSIONS.md

@@ -0,0 +1,72 @@
+# Permissions model
+
+This extension ships **activeTab-only**: it deliberately does **not** request the
+broad `<all_urls>` host permission, and it has **no declarative `content_scripts`**.
+
+## Why
+
+A declarative content script on `<all_urls>` (and the matching `<all_urls>` host
+permission) triggers Chrome Web Store's **broad host permission in-depth review**,
+which significantly delays publishing and updates. We avoid that.
+
+## How the overlay gets on the page
+
+When the user clicks the extension and starts a recording, the background service
+worker injects the content script into the **launch tab** with
+`chrome.scripting.executeScript({ target: { tabId }, files: ["assets/content-script.js"] })`.
+That call is authorized by the **`activeTab`** permission, which Chrome grants for
+the tab that was active when the user invoked the extension — no broad host access
+needed. The content script then mounts the overlay iframes (countdown, camera
+bubble, controls). `web_accessible_resources` stays `<all_urls>` — that is **not**
+a host permission and does not trigger the review.
+
+Declared permissions: `activeTab`, `debugger`, `offscreen`, `scripting`,
+`storage`. Host permissions: only the configured Clips app + `forms.agent-native.com`
+
+- `localhost`/`127.0.0.1`.
+
+## What this costs
+
+- The overlay (countdown, camera bubble, recording controls) lives **only on the
+  tab the recording was launched from**. It does **not** follow the user to other
+  tabs during a full-screen or multi-tab recording.
+- **Recording itself is unaffected.** Capture runs in the offscreen document via
+  `getDisplayMedia`, independent of any tab's content script — full-screen,
+  window, and other-tab content are all still captured normally. Only the on-page
+  _overlay UI_ is scoped to the launch tab.
+
+## Re-enabling cross-tab follow
+
+The full cross-tab behavior is gated behind a single flag in
+`src/background.ts`:
+
+```ts
+const CROSS_TAB_FOLLOW = false; // flip to true
+```
+
+Flipping it to `true` restores the all-tabs broadcast in `broadcastMount()` /
+`broadcastUnmount()` and the `chrome.tabs.onActivated` follow listener. To make
+that actually work you must **also** restore broad host access so the worker can
+inject into arbitrary tabs. Two options:
+
+1. **Static (simplest, but in-depth review):** re-add to `public/manifest.json`:
+   - `"<all_urls>"` in `host_permissions`, and
+   - the `content_scripts` block:
+     ```json
+     "content_scripts": [
+       {
+         "matches": ["<all_urls>"],
+         "js": ["assets/content-script.js"],
+         "run_at": "document_idle",
+         "all_frames": false
+       }
+     ],
+     ```
+
+2. **Optional (preferred — keeps the default install lean):** declare
+   `"optional_host_permissions": ["<all_urls>"]` in the manifest and call
+   `chrome.permissions.request({ origins: ["<all_urls>"] })` at runtime (e.g. from
+   a settings toggle) before enabling follow. The user grants the broad access
+   explicitly, only if they want cross-tab overlays.
+
+After any change: `pnpm build`, then re-zip `dist/`.

package/corpus/templates/clips/chrome-extension/public/manifest.json

@@ -23,16 +23,7 @@
     "https://clips.agent-native.com/*",
     "https://forms.agent-native.com/*",
     "http://localhost/*",
-    "http://127.0.0.1/*",
-    "<all_urls>"
-  ],
-  "content_scripts": [
-    {
-      "matches": ["<all_urls>"],
-      "js": ["assets/content-script.js"],
-      "run_at": "document_idle",
-      "all_frames": false
-    }
+    "http://127.0.0.1/*"
   ],
   "web_accessible_resources": [
     {

package/corpus/templates/clips/chrome-extension/src/background.ts

@@ -210,7 +210,22 @@ type OverlayPart = "bubble" | "countdown" | "toolbar" | "saving";
 let overlayPhase: OverlayPhase = "idle";
 let overlayBaseElapsedMs = 0;
 let overlayBaseEpochMs = 0;
+// Bubble during the countdown preview (any camera). During recording, the face
+// is composited into the video by the offscreen for screen+camera, so we only
+// show the on-page bubble for camera-only mode (recordingShowsBubble).
 let overlayShowsBubble = false;
+let recordingShowsBubble = false;
+// Cross-tab follow: when true, the overlay is pushed to whatever tab the user
+// switches to mid-recording. That requires "<all_urls>" + a declarative content
+// script, which triggers Chrome's broad-host in-depth review. Shipped OFF
+// (activeTab-only: the overlay lives on the launch tab the user invoked the
+// extension from). Capture is unaffected — it runs in the offscreen document via
+// getDisplayMedia regardless. See PERMISSIONS.md to re-enable.
+// Typed `boolean` (not inferred literal `false`) so the cross-tab branches below
+// don't read as unreachable code; flip the value to re-enable. See PERMISSIONS.md.
+const CROSS_TAB_FOLLOW: boolean = false;
+// The tab the recording was launched from — the only tab activeTab lets us touch.
+let overlayTabId: number | null = null;
 let countdownEndsAtMs = 0;
 
 function desiredParts(): OverlayPart[] {
@@ -221,7 +236,7 @@ function desiredParts(): OverlayPart[] {
     return overlayShowsBubble ? ["bubble", "countdown"] : ["countdown"];
   }
   if (overlayPhase === "recording" || overlayPhase === "paused") {
-    return overlayShowsBubble ? ["bubble", "toolbar"] : ["toolbar"];
+    return recordingShowsBubble ? ["bubble", "toolbar"] : ["toolbar"];
   }
   if (overlayPhase === "saving") {
     return ["saving"];
@@ -286,7 +301,9 @@ function persistOverlay(): Promise<void> {
       baseElapsedMs: overlayBaseElapsedMs,
       baseEpochMs: overlayBaseEpochMs,
       showsBubble: overlayShowsBubble,
+      recordingShowsBubble,
       countdownEndsAtMs,
+      overlayTabId,
     },
   }).catch(() => undefined);
 }
@@ -306,7 +323,9 @@ async function restoreRuntimeState(): Promise<void> {
         baseElapsedMs?: number;
         baseEpochMs?: number;
         showsBubble?: boolean;
+        recordingShowsBubble?: boolean;
         countdownEndsAtMs?: number;
+        overlayTabId?: number;
       }
     | undefined;
   if (rt && typeof rt.phase === "string" && overlayPhase === "idle") {
@@ -316,8 +335,10 @@ async function restoreRuntimeState(): Promise<void> {
     overlayBaseEpochMs =
       typeof rt.baseEpochMs === "number" ? rt.baseEpochMs : 0;
     overlayShowsBubble = Boolean(rt.showsBubble);
+    recordingShowsBubble = Boolean(rt.recordingShowsBubble);
     countdownEndsAtMs =
       typeof rt.countdownEndsAtMs === "number" ? rt.countdownEndsAtMs : 0;
+    overlayTabId = typeof rt.overlayTabId === "number" ? rt.overlayTabId : null;
   }
 
   if (overlayPhase !== "idle" && activeNativeRecording) {
@@ -386,6 +407,13 @@ function allTabs(): Promise<chrome.tabs.Tab[]> {
 }
 
 async function broadcastMount(): Promise<void> {
+  // activeTab-only: keep the overlay on the launch tab (re-ensures the injected
+  // content script too, so it survives a worker suspend). Cross-tab broadcast is
+  // gated behind CROSS_TAB_FOLLOW because it needs broad host access.
+  if (!CROSS_TAB_FOLLOW) {
+    if (overlayTabId !== null) await mountOverlayOnTab(overlayTabId);
+    return;
+  }
   const parts = desiredParts();
   const tabs = await allTabs();
   await Promise.all(
@@ -398,6 +426,11 @@ async function broadcastMount(): Promise<void> {
 }
 
 async function broadcastUnmount(): Promise<void> {
+  if (!CROSS_TAB_FOLLOW) {
+    if (overlayTabId !== null)
+      await sendTabMessage(overlayTabId, { type: "CLIPS_OVERLAY_UNMOUNT" });
+    return;
+  }
   const tabs = await allTabs();
   await Promise.all(
     tabs.map((tab) =>
@@ -413,6 +446,7 @@ function resetOverlay(): void {
   overlayBaseElapsedMs = 0;
   overlayBaseEpochMs = 0;
   overlayShowsBubble = false;
+  recordingShowsBubble = false;
   clearCountdownTimer();
   setRecordingFlag(false);
   // Bring back the toolbar popup now that we're idle again.
@@ -420,6 +454,41 @@ function resetOverlay(): void {
   void persistOverlay();
 }
 
+// ----- Pre-record camera preview --------------------------------------------
+// While the popup is open and idle, show the live face bubble on the active tab
+// (like the desktop app's pre-record bubble). The popup holds a runtime port
+// open; its disconnect (popup closed) tears the preview down.
+let previewTabId: number | null = null;
+
+async function startPreview(wantsCamera: boolean): Promise<void> {
+  await ensureRestored();
+  // Never show a preview over an active recording (the recording overlay owns
+  // the tab then). If the camera is off, make sure any preview is removed.
+  if (overlayPhase !== "idle" || !wantsCamera) {
+    await stopPreview();
+    return;
+  }
+  const tab = await queryActiveTab();
+  if (!tab || typeof tab.id !== "number") return;
+  if (previewTabId !== null && previewTabId !== tab.id) await stopPreview();
+  previewTabId = tab.id;
+  await ensureContentScript(tab.id);
+  // Injection / send fail silently on unsupported pages (chrome://, etc.).
+  await sendTabMessage(tab.id, {
+    type: "CLIPS_OVERLAY_MOUNT",
+    parts: ["bubble"],
+  });
+}
+
+async function stopPreview(): Promise<void> {
+  const tabId = previewTabId;
+  previewTabId = null;
+  if (tabId === null) return;
+  // Don't tear down a recording overlay that took over this tab.
+  if (overlayPhase !== "idle") return;
+  await sendTabMessage(tabId, { type: "CLIPS_OVERLAY_UNMOUNT" });
+}
+
 // Mirrored into chrome.storage.local so content scripts can cheaply tell whether
 // a recording is in progress without waking the service worker on every page
 // load. Content scripts can read storage.local by default; storage.session
@@ -875,6 +944,7 @@ async function armRecording(args: {
     settings.captureSurface === "camera" ? "camera" : "screen";
   const surface: "browser" | "window" | "monitor" =
     settings.captureSurface === "camera" ? "browser" : settings.captureSurface;
+  console.log("[clips-bg] arm: start", { mode, surface, tabId: tab.id });
 
   // Pre-warmed on popup open, so this is effectively instant and keeps the
   // getDisplayMedia() call close to the user's click.
@@ -882,15 +952,52 @@ async function armRecording(args: {
 
   // 1) Native "Choose what to share" picker. Do this before any network round
   //    trip so the picker stays tied to the user gesture. Throws if cancelled.
-  await sendOffscreenMessage<{ ok: boolean; width: number; height: number }>({
+  const acq = await sendOffscreenMessage<{
+    ok: boolean;
+    width: number;
+    height: number;
+  }>({
     type: "CLIPS_OFFSCREEN_ACQUIRE",
     sessionId,
     mode,
     surface,
     includeMicrophone: settings.includeMicrophone,
+    includeCamera: settings.includeCamera,
   });
+  console.log("[clips-bg] arm: acquired stream", acq);
+
+  // 2) Show the countdown overlay IMMEDIATELY — before the network round-trip —
+  //    so the 3-2-1 runs full-length and the dim/blur clears exactly when the
+  //    recorder starts. The on-page bubble shows during countdown AND recording
+  //    (the face is captured in the display; we do not composite).
+  const cameraInvolved = mode === "camera" || settings.includeCamera;
+  overlayPhase = "countdown";
+  overlayBaseElapsedMs = 0;
+  overlayBaseEpochMs = nowMs();
+  overlayShowsBubble = cameraInvolved;
+  recordingShowsBubble = cameraInvolved;
+  countdownEndsAtMs = nowMs() + COUNTDOWN_SECONDS * 1000;
+  // The recording overlay now owns this tab's bubble — hand off from any preview
+  // so the popup-close disconnect won't tear down the live recording overlay.
+  previewTabId = null;
+  setRecordingFlag(true);
+  // Clicking the icon now stops & saves immediately instead of opening the popup.
+  setActionPopup("");
+  overlayTabId = tab.id as number;
+  await mountOverlayOnTab(tab.id as number);
+  broadcastOverlayState();
+
+  const abortArming = async (): Promise<void> => {
+    await sendOffscreenMessage({
+      type: "CLIPS_OFFSCREEN_CANCEL",
+      sessionId,
+    }).catch(() => undefined);
+    resetOverlay();
+    await broadcastUnmount();
+    await chrome.action.setBadgeText({ text: "" });
+  };
 
-  // 2) Create the recording row now that we know the user picked a source.
+  // 3) Create the recording row (happens during the countdown).
   type CreatedRecording = {
     id?: string;
     uploadChunkUrl?: string;
@@ -903,23 +1010,17 @@ async function armRecording(args: {
       titleSource: tab.title ? "context" : "default",
       sourceAppName: "Chrome",
       sourceWindowTitle: tab.title ?? null,
-      hasCamera: settings.captureSurface === "camera" || settings.includeCamera,
+      hasCamera: cameraInvolved,
       hasAudio:
         settings.includeMicrophone || settings.captureSurface !== "camera",
       visibility: "public",
     });
   } catch (err) {
-    await sendOffscreenMessage({
-      type: "CLIPS_OFFSCREEN_CANCEL",
-      sessionId,
-    }).catch(() => undefined);
+    await abortArming();
     throw err;
   }
   if (!created.id || !created.uploadChunkUrl) {
-    await sendOffscreenMessage({
-      type: "CLIPS_OFFSCREEN_CANCEL",
-      sessionId,
-    }).catch(() => undefined);
+    await abortArming();
     throw new Error("Clips did not create a recording target.");
   }
 
@@ -946,35 +1047,29 @@ async function armRecording(args: {
     error: null,
   };
 
-  // 3) Enter the countdown phase and show the overlay on the launch tab. The
-  //    camera bubble shows whenever a camera is involved: as the picture-in-
-  //    picture for screen+camera, or as a live self-preview for camera-only.
-  overlayPhase = "countdown";
-  overlayBaseElapsedMs = 0;
-  overlayBaseEpochMs = nowMs();
-  overlayShowsBubble = mode === "camera" || settings.includeCamera;
-  countdownEndsAtMs = nowMs() + COUNTDOWN_SECONDS * 1000;
-  setRecordingFlag(true);
-  // Clicking the icon now stops & saves immediately instead of opening the popup.
-  setActionPopup("");
-
-  // Hand the recorder its targets plus the pre-roll delay. The offscreen document
-  // (a reliable context, unlike the suspendable worker) owns the countdown timer
-  // and reports "recording" back when the recorder actually starts — that status
-  // flip (markRecordingStarted) advances our phase, so recording begins even on
-  // pages where no overlay can be injected (chrome://, the New Tab page, etc.).
+  // 4) Start the recorder when the (already-running) countdown ends. The
+  //    offscreen owns the pre-roll timer (a reliable context, unlike the
+  //    suspendable worker) and reports "recording" back when it actually starts.
   const authToken = (await readAuthSession(settings))?.token;
+  console.log("[clips-bg] arm: created row", created.id, "auth?", !!authToken);
+  // The on-page countdown drives the actual start (it sends COUNTDOWN_DONE at
+  // "Go"). This offscreen timer is only a FALLBACK. When a camera is involved the
+  // countdown waits for the camera feed before it even shows "3" (the content
+  // script holds it, with its own 12s cap), so the fallback must be generous
+  // enough not to start the recorder mid-connect; otherwise a short pre-roll.
+  const startDelayMs = cameraInvolved ? 20000 : COUNTDOWN_SECONDS * 1000 + 1000;
   try {
     await sendOffscreenMessage({
       type: "CLIPS_OFFSCREEN_BEGIN",
       sessionId,
       recordingId: created.id,
       uploadUrl,
-      hasCamera: mode === "camera" || settings.includeCamera,
-      startDelayMs: COUNTDOWN_SECONDS * 1000,
+      hasCamera: cameraInvolved,
+      startDelayMs,
       authToken,
     });
   } catch (err) {
+    console.error("[clips-bg] arm: BEGIN failed", err);
     await cancelRecording();
     throw err;
   }
@@ -985,10 +1080,10 @@ async function armRecording(args: {
     await attachSession(session);
   }
 
-  await mountOverlayOnTab(tab.id as number);
   broadcastOverlayState();
   await chrome.action.setBadgeBackgroundColor({ color: "#e11d48" });
   await chrome.action.setBadgeText({ text: "REC" });
+  console.log("[clips-bg] arm: done — countdown, parts:", desiredParts());
 
   return { ok: true, sessionId, recordingId: created.id, native: true };
 }
@@ -998,6 +1093,7 @@ async function armRecording(args: {
 // on-page timer. Idempotent.
 async function markRecordingStarted() {
   if (overlayPhase !== "countdown") return;
+  console.log("[clips-bg] recorder started → phase=recording");
   clearCountdownTimer();
   overlayPhase = "recording";
   overlayBaseElapsedMs = 0;
@@ -1178,6 +1274,7 @@ async function finishSaving(
 
 async function stopRecording() {
   const recording = activeNativeRecording;
+  console.log("[clips-bg] stopRecording — active:", !!recording);
   if (!recording) return { ok: false, error: "No active Clips recording." };
   recording.status = "stopping";
   // Keep an overlay up: swap the recording controls/bubble for a "Saving…" card
@@ -1821,6 +1918,11 @@ chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
     try {
       response = await dispatchRuntimeMessage(message);
     } catch (err) {
+      console.error(
+        "[clips-bg] message failed:",
+        (message as { type?: unknown })?.type,
+        err,
+      );
       response = {
         ok: false,
         error: err instanceof Error ? err.message : "Could not use Clips.",
@@ -1841,6 +1943,13 @@ async function dispatchRuntimeMessage(message: unknown): Promise<unknown> {
   // Status updates streamed from the offscreen recorder.
   if (type === "CLIPS_NATIVE_STATUS") {
     const status = message as OffscreenStatusMessage;
+    console.log(
+      "[clips-bg] status:",
+      status.status,
+      status.error ?? "",
+      "phase:",
+      overlayPhase,
+    );
     if (
       activeNativeRecording &&
       activeNativeRecording.sessionId === status.sessionId
@@ -1909,6 +2018,11 @@ async function dispatchRuntimeMessage(message: unknown): Promise<unknown> {
     return { ok: true };
   }
 
+  if (type === "CLIPS_PREVIEW") {
+    await startPreview(Boolean((message as { camera?: unknown }).camera));
+    return { ok: true };
+  }
+
   switch (type) {
     case "CLIPS_POPUP_START":
       return handlePopupStart(message as PopupStartMessage);
@@ -1946,6 +2060,7 @@ async function dispatchRuntimeMessage(message: unknown): Promise<unknown> {
 // switch tabs (programmatic injection covers tabs opened before the extension
 // loaded; declared content scripts cover navigations).
 chrome.tabs.onActivated.addListener((info) => {
+  if (!CROSS_TAB_FOLLOW) return; // activeTab-only: overlay stays on the launch tab
   void (async () => {
     await ensureRestored();
     if (overlayPhase === "idle" || !activeNativeRecording) return;
@@ -1961,6 +2076,12 @@ chrome.action.onClicked.addListener(() => {
     // Await restore — the click may have woken the worker, leaving the module
     // globals empty until this resolves. Without it, Stop silently does nothing.
     await ensureRestored();
+    console.log(
+      "[clips-bg] icon clicked — phase:",
+      overlayPhase,
+      "active:",
+      !!activeNativeRecording,
+    );
     if (!activeNativeRecording) return;
     if (overlayPhase === "countdown") await cancelRecording();
     else if (overlayPhase === "recording" || overlayPhase === "paused") {
@@ -1969,6 +2090,16 @@ chrome.action.onClicked.addListener(() => {
   })();
 });
 
+// The popup opens a port for as long as it is visible; its disconnect (popup
+// closed) is our reliable signal to remove the pre-record preview bubble.
+chrome.runtime.onConnect.addListener((port) => {
+  if (port.name !== "clips-preview") return;
+  port.onDisconnect.addListener(() => {
+    void chrome.runtime.lastError;
+    void stopPreview();
+  });
+});
+
 chrome.runtime.onMessageExternal.addListener(
   (message, sender, sendResponse) => {
     void handleExternalMessage(message as ExternalMessage, sender)