@agent-native/core 0.69.0 → 0.70.1

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

@@ -115,6 +115,7 @@ type BrowserDiagnosticsData = {
 
 type NativeRecordingStatus =
   | "recording"
+  | "paused"
   | "stopping"
   | "uploading"
   | "complete"
@@ -124,6 +125,7 @@ type NativeRecording = {
   sessionId: string;
   recordingId: string;
   clipsBaseUrl: string;
+  uploadUrl: string;
   targetTabId: number;
   targetTitle: string | null;
   targetUrl: string | null;
@@ -196,6 +198,243 @@ const sessions = new Map<string, CaptureSession>();
 const tabToSession = new Map<number, string>();
 let activeNativeRecording: NativeRecording | null = null;
 
+// ----- Loom-style in-page overlay state -------------------------------------
+// The service worker is the single source of truth for the recording phase and
+// the elapsed-time base. The phase decides which overlay "parts" each tab should
+// show; the timer base lets every overlay iframe tick the same clock locally.
+
+type CaptureMode = "screen" | "camera";
+type OverlayPhase = "idle" | "countdown" | "recording" | "paused" | "saving";
+type OverlayPart = "bubble" | "countdown" | "toolbar" | "saving";
+
+let overlayPhase: OverlayPhase = "idle";
+let overlayBaseElapsedMs = 0;
+let overlayBaseEpochMs = 0;
+let overlayShowsBubble = false;
+let countdownEndsAtMs = 0;
+
+function desiredParts(): OverlayPart[] {
+  // The on-page controls match the desktop app: a left-edge vertical pill plus
+  // the face bubble. (Both are captured in full-screen/window recordings — same
+  // tradeoff as the desktop's on-screen controls; that's the intended UX.)
+  if (overlayPhase === "countdown") {
+    return overlayShowsBubble ? ["bubble", "countdown"] : ["countdown"];
+  }
+  if (overlayPhase === "recording" || overlayPhase === "paused") {
+    return overlayShowsBubble ? ["bubble", "toolbar"] : ["toolbar"];
+  }
+  if (overlayPhase === "saving") {
+    return ["saving"];
+  }
+  return [];
+}
+
+function overlayStateForBroadcast(): {
+  phase: OverlayPhase;
+  baseElapsedMs: number;
+  baseEpochMs: number;
+  countdownEndsAtMs: number;
+} {
+  return {
+    phase: overlayPhase,
+    baseElapsedMs: overlayBaseElapsedMs,
+    baseEpochMs: overlayBaseEpochMs,
+    countdownEndsAtMs,
+  };
+}
+
+// The countdown clock lives here in the worker, not in the overlay. The overlay
+// only *visualizes* it. This is critical: on chrome:// pages (and any page where
+// the overlay can't be injected) the recorder must still start. Without this,
+// recording would silently never begin on those pages.
+const COUNTDOWN_SECONDS = 3;
+
+function clearCountdownTimer(): void {
+  countdownEndsAtMs = 0;
+}
+
+// Toggle the toolbar popup off while recording so clicking the extension icon
+// fires onClicked (immediate stop & save) instead of opening the popup.
+function setActionPopup(path: string): void {
+  try {
+    void chrome.action.setPopup({ popup: path });
+  } catch {
+    /* action API unavailable */
+  }
+}
+
+// Reaches every extension-origin overlay iframe across all tabs at once.
+function broadcastOverlayState(): void {
+  void persistOverlay();
+  try {
+    chrome.runtime.sendMessage(
+      { type: "CLIPS_OVERLAY_STATE", state: overlayStateForBroadcast() },
+      () => void chrome.runtime.lastError,
+    );
+  } catch {
+    /* no overlay listening yet */
+  }
+}
+
+// MV3 can suspend the service worker mid-recording, wiping these module vars.
+// Persist them to session storage (survives suspend/revive within the browser
+// session) and restore on worker startup so the overlay controls keep working.
+function persistOverlay(): Promise<void> {
+  return sessionStorageSet({
+    overlayRuntime: {
+      phase: overlayPhase,
+      baseElapsedMs: overlayBaseElapsedMs,
+      baseEpochMs: overlayBaseEpochMs,
+      showsBubble: overlayShowsBubble,
+      countdownEndsAtMs,
+    },
+  }).catch(() => undefined);
+}
+
+async function restoreRuntimeState(): Promise<void> {
+  const stored = await sessionStorageGet([
+    "activeNativeRecording",
+    "overlayRuntime",
+  ]);
+  const rec = stored.activeNativeRecording as NativeRecording | undefined;
+  if (rec && typeof rec.sessionId === "string" && !activeNativeRecording) {
+    activeNativeRecording = rec;
+  }
+  const rt = stored.overlayRuntime as
+    | {
+        phase?: OverlayPhase;
+        baseElapsedMs?: number;
+        baseEpochMs?: number;
+        showsBubble?: boolean;
+        countdownEndsAtMs?: number;
+      }
+    | undefined;
+  if (rt && typeof rt.phase === "string" && overlayPhase === "idle") {
+    overlayPhase = rt.phase;
+    overlayBaseElapsedMs =
+      typeof rt.baseElapsedMs === "number" ? rt.baseElapsedMs : 0;
+    overlayBaseEpochMs =
+      typeof rt.baseEpochMs === "number" ? rt.baseEpochMs : 0;
+    overlayShowsBubble = Boolean(rt.showsBubble);
+    countdownEndsAtMs =
+      typeof rt.countdownEndsAtMs === "number" ? rt.countdownEndsAtMs : 0;
+  }
+
+  if (overlayPhase !== "idle" && activeNativeRecording) {
+    // Recording survived a worker restart. The offscreen document owns the
+    // recorder + pre-roll timer, so it kept running; just restore immediate-stop
+    // mode. If the pre-roll already elapsed, assume the offscreen started the
+    // recorder so the icon click does Stop (not Discard).
+    setActionPopup("");
+    if (
+      overlayPhase === "countdown" &&
+      countdownEndsAtMs > 0 &&
+      nowMs() >= countdownEndsAtMs
+    ) {
+      overlayPhase = "recording";
+      overlayBaseEpochMs = countdownEndsAtMs;
+      countdownEndsAtMs = 0;
+    }
+  }
+}
+
+function sendTabMessage(
+  tabId: number,
+  message: Record<string, unknown>,
+): Promise<void> {
+  return new Promise((resolve) => {
+    try {
+      chrome.tabs.sendMessage(tabId, message, () => {
+        void chrome.runtime.lastError;
+        resolve();
+      });
+    } catch {
+      resolve();
+    }
+  });
+}
+
+async function ensureContentScript(tabId: number): Promise<void> {
+  const scripting = (
+    chrome as typeof chrome & {
+      scripting?: {
+        executeScript: (args: {
+          target: { tabId: number };
+          files: string[];
+        }) => Promise<unknown>;
+      };
+    }
+  ).scripting;
+  if (!scripting) return;
+  await scripting
+    .executeScript({ target: { tabId }, files: ["assets/content-script.js"] })
+    .catch(() => undefined);
+}
+
+async function mountOverlayOnTab(tabId: number): Promise<void> {
+  await ensureContentScript(tabId);
+  await sendTabMessage(tabId, {
+    type: "CLIPS_OVERLAY_MOUNT",
+    parts: desiredParts(),
+  });
+}
+
+function allTabs(): Promise<chrome.tabs.Tab[]> {
+  return new Promise((resolve) => {
+    chrome.tabs.query({}, (tabs) => resolve(tabs ?? []));
+  });
+}
+
+async function broadcastMount(): Promise<void> {
+  const parts = desiredParts();
+  const tabs = await allTabs();
+  await Promise.all(
+    tabs.map((tab) =>
+      typeof tab.id === "number"
+        ? sendTabMessage(tab.id, { type: "CLIPS_OVERLAY_MOUNT", parts })
+        : Promise.resolve(),
+    ),
+  );
+}
+
+async function broadcastUnmount(): Promise<void> {
+  const tabs = await allTabs();
+  await Promise.all(
+    tabs.map((tab) =>
+      typeof tab.id === "number"
+        ? sendTabMessage(tab.id, { type: "CLIPS_OVERLAY_UNMOUNT" })
+        : Promise.resolve(),
+    ),
+  );
+}
+
+function resetOverlay(): void {
+  overlayPhase = "idle";
+  overlayBaseElapsedMs = 0;
+  overlayBaseEpochMs = 0;
+  overlayShowsBubble = false;
+  clearCountdownTimer();
+  setRecordingFlag(false);
+  // Bring back the toolbar popup now that we're idle again.
+  setActionPopup("src/popup.html");
+  void persistOverlay();
+}
+
+// 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
+// cannot, which is why we use local here.
+function setRecordingFlag(active: boolean): void {
+  try {
+    chrome.storage.local.set(
+      { clipsRecordingActive: active },
+      () => void chrome.runtime.lastError,
+    );
+  } catch {
+    /* storage unavailable */
+  }
+}
+
 function nowIso(): string {
   return new Date().toISOString();
 }
@@ -356,14 +595,32 @@ function originOf(raw: string | null | undefined): string | null {
   }
 }
 
+// Auth lives in chrome.storage.local (not .session) so the user stays signed in
+// across extension reloads and browser restarts. It is the user's own session
+// token — treated like a cookie — and is cleared on sign-out or when invalid.
+function localStorageSet(value: Record<string, unknown>): Promise<void> {
+  return new Promise((resolve) => {
+    chrome.storage.local.set(value, () => {
+      void chrome.runtime.lastError;
+      resolve();
+    });
+  });
+}
+
+function localStorageGet(keys: string[]): Promise<Record<string, unknown>> {
+  return new Promise((resolve) => {
+    chrome.storage.local.get(keys, (value) => resolve(value ?? {}));
+  });
+}
+
 async function saveAuthSession(auth: StoredAuth): Promise<void> {
-  await sessionStorageSet({ clipsAuth: auth });
+  await localStorageSet({ clipsAuth: auth });
 }
 
 async function readAuthSession(
   settings: ExtensionSettings,
 ): Promise<StoredAuth | null> {
-  const stored = await sessionStorageGet(["clipsAuth"]);
+  const stored = await localStorageGet(["clipsAuth"]);
   const auth = stored.clipsAuth as Partial<StoredAuth> | undefined;
   if (
     !auth ||
@@ -506,23 +763,6 @@ async function postAction<T>(
   return (data ?? {}) as T;
 }
 
-function getTabMediaStreamId(tabId: number): Promise<string> {
-  return new Promise((resolve, reject) => {
-    chrome.tabCapture.getMediaStreamId({ targetTabId: tabId }, (streamId) => {
-      const error = chromeLastError();
-      if (error) {
-        reject(error);
-        return;
-      }
-      if (!streamId) {
-        reject(new Error("Chrome did not provide a tab capture stream."));
-        return;
-      }
-      resolve(streamId);
-    });
-  });
-}
-
 async function ensureOffscreenDocument(): Promise<void> {
   const path = "src/offscreen.html";
   const offscreenUrl = chrome.runtime.getURL(path);
@@ -568,38 +808,6 @@ function recordingUrl(
   return `${recording.clipsBaseUrl}/r/${encodeURIComponent(recording.recordingId)}`;
 }
 
-function buildRecordUrl(
-  settings: ExtensionSettings,
-  sessionId: string,
-  tab: ChromeTab,
-): string {
-  const recordUrl = new URL(`${settings.clipsBaseUrl}/record`);
-  const mode =
-    settings.captureSurface === "camera"
-      ? "camera"
-      : settings.includeCamera
-        ? "screen+camera"
-        : "screen";
-  const surface =
-    settings.captureSurface === "camera" ? "browser" : settings.captureSurface;
-
-  recordUrl.searchParams.set("mode", mode);
-  recordUrl.searchParams.set("surface", surface);
-  recordUrl.searchParams.set("clipsExtensionId", chrome.runtime.id);
-  recordUrl.searchParams.set("clipsCaptureSessionId", sessionId);
-  recordUrl.searchParams.set(
-    "developerLogs",
-    settings.includeDeveloperLogs ? "1" : "0",
-  );
-  recordUrl.searchParams.set(
-    "microphone",
-    settings.includeMicrophone ? "1" : "0",
-  );
-  if (tab.title) recordUrl.searchParams.set("sourceTitle", tab.title);
-  if (tab.url) recordUrl.searchParams.set("sourceUrl", tab.url);
-  return recordUrl.toString();
-}
-
 function createSession(
   sessionId: string,
   tab: ChromeTab,
@@ -650,61 +858,80 @@ async function handlePopupStart(message: PopupStartMessage) {
   }
 
   const sessionId = crypto.randomUUID();
-  if (
-    settings.captureSurface === "browser" ||
-    settings.captureSurface === "camera"
-  ) {
-    return startNativeRecording({ sessionId, tab, settings });
-  }
-
-  createSession(sessionId, tab, settings);
-  await createTab(buildRecordUrl(settings, sessionId, tab));
-
-  return { ok: true, sessionId };
+  return armRecording({ sessionId, tab, settings });
 }
 
-async function startNativeRecording(args: {
+// Arm a Loom-style in-page recording: show the native picker, create the row,
+// then hand the recorder its pre-roll delay. The MediaRecorder starts inside the
+// offscreen document after that delay, which reports "recording" back here
+// (markRecordingStarted) — reliable even when no overlay can be injected.
+async function armRecording(args: {
   sessionId: string;
   tab: ChromeTab;
   settings: ExtensionSettings;
 }) {
   const { sessionId, tab, settings } = args;
-  const streamId =
-    settings.captureSurface === "browser"
-      ? await getTabMediaStreamId(tab.id as number)
-      : undefined;
+  const mode: CaptureMode =
+    settings.captureSurface === "camera" ? "camera" : "screen";
+  const surface: "browser" | "window" | "monitor" =
+    settings.captureSurface === "camera" ? "browser" : settings.captureSurface;
+
+  // Pre-warmed on popup open, so this is effectively instant and keeps the
+  // getDisplayMedia() call close to the user's click.
   await ensureOffscreenDocument();
 
+  // 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 }>({
+    type: "CLIPS_OFFSCREEN_ACQUIRE",
+    sessionId,
+    mode,
+    surface,
+    includeMicrophone: settings.includeMicrophone,
+  });
+
+  // 2) Create the recording row now that we know the user picked a source.
   type CreatedRecording = {
     id?: string;
     uploadChunkUrl?: string;
     abortUrl?: string;
   };
-  const created = await postAction<CreatedRecording>(
-    settings,
-    "create-recording",
-    {
+  let created: CreatedRecording;
+  try {
+    created = await postAction<CreatedRecording>(settings, "create-recording", {
       title: tab.title || "Untitled recording",
       titleSource: tab.title ? "context" : "default",
       sourceAppName: "Chrome",
       sourceWindowTitle: tab.title ?? null,
       hasCamera: settings.captureSurface === "camera" || settings.includeCamera,
       hasAudio:
-        settings.includeMicrophone || settings.captureSurface === "browser",
+        settings.includeMicrophone || settings.captureSurface !== "camera",
       visibility: "public",
-    },
-  );
+    });
+  } catch (err) {
+    await sendOffscreenMessage({
+      type: "CLIPS_OFFSCREEN_CANCEL",
+      sessionId,
+    }).catch(() => undefined);
+    throw err;
+  }
   if (!created.id || !created.uploadChunkUrl) {
+    await sendOffscreenMessage({
+      type: "CLIPS_OFFSCREEN_CANCEL",
+      sessionId,
+    }).catch(() => undefined);
     throw new Error("Clips did not create a recording target.");
   }
 
   const uploadUrl = `${settings.clipsBaseUrl}${created.uploadChunkUrl}`;
   const session = createSession(sessionId, tab, settings);
   session.recordingId = created.id;
+
   activeNativeRecording = {
     sessionId,
     recordingId: created.id,
     clipsBaseUrl: settings.clipsBaseUrl,
+    uploadUrl,
     targetTabId: tab.id as number,
     targetTitle: tab.title?.trim() || null,
     targetUrl: tab.url?.trim() || null,
@@ -718,101 +945,250 @@ async function startNativeRecording(args: {
     recordingUrl: `${settings.clipsBaseUrl}/r/${encodeURIComponent(created.id)}`,
     error: null,
   };
-  await saveActiveNativeRecording();
 
+  // 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.).
+  const authToken = (await readAuthSession(settings))?.token;
   try {
-    await sendOffscreenMessage<{
-      ok: boolean;
-      recordingId: string;
-      width: number;
-      height: number;
-      hasAudio: boolean;
-      hasCamera: boolean;
-    }>({
-      type: "CLIPS_OFFSCREEN_START",
+    await sendOffscreenMessage({
+      type: "CLIPS_OFFSCREEN_BEGIN",
       sessionId,
       recordingId: created.id,
       uploadUrl,
-      streamId,
-      captureSurface: settings.captureSurface,
-      includeCamera: settings.includeCamera,
-      includeMicrophone: settings.includeMicrophone,
-      title: tab.title ?? null,
+      hasCamera: mode === "camera" || settings.includeCamera,
+      startDelayMs: COUNTDOWN_SECONDS * 1000,
+      authToken,
     });
-    await attachSession(session);
-    await chrome.action.setBadgeBackgroundColor({ color: "#e11d48" });
-    await chrome.action.setBadgeText({ text: "REC" });
-    return {
-      ok: true,
-      sessionId,
-      recordingId: created.id,
-      native: true,
-    };
   } catch (err) {
-    await deleteSession(sessionId);
-    activeNativeRecording = null;
-    await saveActiveNativeRecording();
-    await chrome.action.setBadgeText({ text: "" });
-    await postAction(settings, "trash-recording", { id: created.id }).catch(
-      () => undefined,
-    );
+    await cancelRecording();
     throw err;
   }
+  await saveActiveNativeRecording();
+
+  // Browser-tab diagnostics still attach to the launch tab only.
+  if (settings.captureSurface === "browser") {
+    await attachSession(session);
+  }
+
+  await mountOverlayOnTab(tab.id as number);
+  broadcastOverlayState();
+  await chrome.action.setBadgeBackgroundColor({ color: "#e11d48" });
+  await chrome.action.setBadgeText({ text: "REC" });
+
+  return { ok: true, sessionId, recordingId: created.id, native: true };
 }
 
-async function saveNativeDiagnostics(
-  recording: NativeRecording,
-): Promise<void> {
-  if (!recording.includeDeveloperLogs) return;
-  const session = sessions.get(recording.sessionId);
-  if (!session) return;
-  const diagnostics = snapshotSession(session);
-  await postAction(
-    {
+// Called when the offscreen recorder reports it actually started (after its
+// pre-roll countdown). Advances phase countdown -> recording and starts the
+// on-page timer. Idempotent.
+async function markRecordingStarted() {
+  if (overlayPhase !== "countdown") return;
+  clearCountdownTimer();
+  overlayPhase = "recording";
+  overlayBaseElapsedMs = 0;
+  overlayBaseEpochMs = nowMs();
+  if (activeNativeRecording) {
+    activeNativeRecording.startedAtMs = overlayBaseEpochMs;
+    activeNativeRecording.startedAt = new Date(
+      overlayBaseEpochMs,
+    ).toISOString();
+    activeNativeRecording.status = "recording";
+    await saveActiveNativeRecording();
+  }
+  await broadcastMount();
+  broadcastOverlayState();
+}
+
+// Skip the pre-roll: tell the offscreen recorder to start immediately. It will
+// report "recording", which flips our phase via markRecordingStarted.
+async function handleOverlaySkip() {
+  if (overlayPhase !== "countdown" || !activeNativeRecording) {
+    return { ok: true };
+  }
+  await sendOffscreenMessage({
+    type: "CLIPS_OFFSCREEN_START_NOW",
+    sessionId: activeNativeRecording.sessionId,
+  }).catch(() => undefined);
+  return { ok: true };
+}
+
+function handleOverlayPause() {
+  if (overlayPhase !== "recording") return { ok: true };
+  overlayBaseElapsedMs += Math.max(0, nowMs() - overlayBaseEpochMs);
+  overlayPhase = "paused";
+  if (activeNativeRecording) {
+    activeNativeRecording.status = "paused";
+    void saveActiveNativeRecording();
+    void sendOffscreenMessage({
+      type: "CLIPS_OFFSCREEN_PAUSE",
+      sessionId: activeNativeRecording.sessionId,
+    }).catch(() => undefined);
+  }
+  broadcastOverlayState();
+  return { ok: true };
+}
+
+function handleOverlayResume() {
+  if (overlayPhase !== "paused") return { ok: true };
+  overlayBaseEpochMs = nowMs();
+  overlayPhase = "recording";
+  if (activeNativeRecording) {
+    activeNativeRecording.status = "recording";
+    void saveActiveNativeRecording();
+    void sendOffscreenMessage({
+      type: "CLIPS_OFFSCREEN_RESUME",
+      sessionId: activeNativeRecording.sessionId,
+    }).catch(() => undefined);
+  }
+  broadcastOverlayState();
+  return { ok: true };
+}
+
+// Restart: discard the in-progress capture but keep the same screen selection,
+// reset the server-side chunks, then replay the countdown.
+async function handleOverlayRestart() {
+  const recording = activeNativeRecording;
+  if (!recording) return { ok: true };
+  try {
+    await sendOffscreenMessage({
+      type: "CLIPS_OFFSCREEN_RESTART",
+      sessionId: recording.sessionId,
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : "Could not restart.",
+    };
+  }
+  // If the previous take's chunks could not be cleared, do NOT re-arm with the
+  // same recordingId — finalize would otherwise assemble stale chunk keys from
+  // the aborted take into the restarted recording. Surface the failure instead.
+  const chunksReset = await resetRecordingChunks(recording);
+  if (!chunksReset) {
+    return {
+      ok: false,
+      error:
+        "Could not clear the previous take before restarting. Stop and start a new recording.",
+    };
+  }
+  overlayPhase = "countdown";
+  overlayBaseElapsedMs = 0;
+  overlayBaseEpochMs = nowMs();
+  countdownEndsAtMs = nowMs() + COUNTDOWN_SECONDS * 1000;
+  recording.status = "recording";
+  const restartAuthToken = (
+    await readAuthSession({
       clipsBaseUrl: recording.clipsBaseUrl,
       captureSurface: recording.captureSurface,
       includeCamera: recording.includeCamera,
       includeMicrophone: recording.includeMicrophone,
       includeDeveloperLogs: recording.includeDeveloperLogs,
-    },
-    "save-browser-diagnostics",
-    {
-      recordingId: recording.recordingId,
+    })
+  )?.token;
+  // Re-arm the recorder on the same (re-homed) source streams with a fresh
+  // pre-roll. The offscreen reports "recording" when it restarts.
+  try {
+    await sendOffscreenMessage({
+      type: "CLIPS_OFFSCREEN_BEGIN",
       sessionId: recording.sessionId,
-      source: "extension",
-      phase: "recording",
-      pageUrl: diagnostics.pageUrl,
-      userAgent: diagnostics.userAgent,
-      startedAt: diagnostics.startedAt,
-      endedAt: diagnostics.endedAt,
-      consoleLogs: diagnostics.consoleLogs,
-      networkRequests: diagnostics.networkRequests,
-    },
-  ).catch((err) => {
-    console.warn("[clips-extension] diagnostics save failed:", err);
-  });
+      recordingId: recording.recordingId,
+      uploadUrl: recording.uploadUrl,
+      hasCamera:
+        recording.captureSurface === "camera" || recording.includeCamera,
+      startDelayMs: COUNTDOWN_SECONDS * 1000,
+      authToken: restartAuthToken,
+    });
+  } catch (err) {
+    // Re-arming failed: tear the countdown overlay back down and report the
+    // failure instead of leaving the user on a pre-roll with no recorder.
+    recording.status = "error";
+    recording.error =
+      err instanceof Error ? err.message : "Could not restart the recorder.";
+    resetOverlay();
+    await saveActiveNativeRecording();
+    await broadcastUnmount();
+    broadcastOverlayState();
+    return { ok: false, error: recording.error };
+  }
+  await saveActiveNativeRecording();
+  await broadcastMount();
+  broadcastOverlayState();
+  return { ok: true };
 }
 
-async function clearNativeRecording(): Promise<void> {
-  activeNativeRecording = null;
-  await saveActiveNativeRecording();
-  await chrome.action.setBadgeText({ text: "" });
+async function resetRecordingChunks(
+  recording: NativeRecording,
+): Promise<boolean> {
+  const url = `${recording.clipsBaseUrl}/api/uploads/${encodeURIComponent(
+    recording.recordingId,
+  )}/reset-chunks`;
+  const headers = await authHeaders({
+    clipsBaseUrl: recording.clipsBaseUrl,
+    captureSurface: recording.captureSurface,
+    includeCamera: recording.includeCamera,
+    includeMicrophone: recording.includeMicrophone,
+    includeDeveloperLogs: recording.includeDeveloperLogs,
+  });
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    credentials: "include",
+    cache: "no-store",
+  }).catch(() => undefined);
+  return Boolean(response?.ok);
 }
 
-async function handlePopupStatus() {
-  return {
-    ok: true,
-    activeRecording: activeNativeRecording,
-  };
+// Finalize a successful save: open the clip and tear down the "Saving…" overlay.
+// Guarded + claims the phase synchronously so it runs exactly once even if both
+// the STOP response and the offscreen "complete" status race to call it (the
+// latter is the safety net when the worker was suspended mid-upload).
+async function finishSaving(
+  recording: NativeRecording,
+  recordingIdFromStatus?: string,
+): Promise<boolean> {
+  if (overlayPhase !== "saving") return false;
+  resetOverlay(); // first statement sets overlayPhase = "idle" synchronously
+  recording.status = "complete";
+  recording.error = null;
+  if (recordingIdFromStatus) recording.recordingId = recordingIdFromStatus;
+  recording.recordingUrl = recordingUrl(recording);
+  await saveNativeDiagnostics(recording);
+  await deleteSession(recording.sessionId);
+  await broadcastUnmount();
+  broadcastOverlayState();
+  await clearNativeRecording();
+  await createTab(recording.recordingUrl);
+  return true;
 }
 
-async function handlePopupStop() {
+async function stopRecording() {
   const recording = activeNativeRecording;
-  if (!recording) {
-    return { ok: false, error: "No active Clips 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
+  // so the user has feedback during the upload gap (instead of everything
+  // vanishing while the clip uploads invisibly). Mirrors the desktop Finalizing
+  // overlay. The popup stays disabled so the icon can't interrupt the save.
+  overlayPhase = "saving";
+  countdownEndsAtMs = 0;
   await saveActiveNativeRecording();
+  await broadcastMount();
+  broadcastOverlayState();
   try {
     const response = await sendOffscreenMessage<{
       ok?: boolean;
@@ -821,16 +1197,33 @@ async function handlePopupStop() {
       type: "CLIPS_OFFSCREEN_STOP",
       sessionId: recording.sessionId,
     });
-    recording.status = "complete";
-    recording.error = null;
-    if (response.result && typeof response.result.recordingId === "string") {
-      recording.recordingId = response.result.recordingId;
+    if (response.result && response.result.status === "cancelled") {
+      // Stopped during the pre-roll countdown: no media was captured. Treat it
+      // as an aborted take — discard the empty recording instead of opening a
+      // playback tab for a finished-but-empty clip.
+      await deleteSession(recording.sessionId);
+      await postAction(
+        {
+          clipsBaseUrl: recording.clipsBaseUrl,
+          captureSurface: recording.captureSurface,
+          includeCamera: recording.includeCamera,
+          includeMicrophone: recording.includeMicrophone,
+          includeDeveloperLogs: recording.includeDeveloperLogs,
+        },
+        "trash-recording",
+        { id: recording.recordingId },
+      ).catch(() => undefined);
+      resetOverlay();
+      await broadcastUnmount();
+      broadcastOverlayState();
+      await clearNativeRecording();
+      return { ok: true, cancelled: true };
     }
-    recording.recordingUrl = recordingUrl(recording);
-    await saveNativeDiagnostics(recording);
-    await deleteSession(recording.sessionId);
-    await clearNativeRecording();
-    await createTab(recording.recordingUrl);
+    const recordingId =
+      response.result && typeof response.result.recordingId === "string"
+        ? response.result.recordingId
+        : undefined;
+    await finishSaving(recording, recordingId);
     return {
       ok: true,
       recordingId: recording.recordingId,
@@ -840,14 +1233,24 @@ async function handlePopupStop() {
     recording.status = "error";
     recording.error =
       err instanceof Error ? err.message : "Could not stop recording.";
+    resetOverlay();
+    await broadcastUnmount();
+    broadcastOverlayState();
     await saveActiveNativeRecording();
     return { ok: false, error: recording.error };
   }
 }
 
-async function handlePopupCancel() {
+async function cancelRecording() {
   const recording = activeNativeRecording;
-  if (!recording) return { ok: true };
+  resetOverlay();
+  await broadcastUnmount();
+  broadcastOverlayState();
+  await chrome.action.setBadgeText({ text: "" });
+  if (!recording) {
+    await clearNativeRecording();
+    return { ok: true };
+  }
   await sendOffscreenMessage({
     type: "CLIPS_OFFSCREEN_CANCEL",
     sessionId: recording.sessionId,
@@ -868,6 +1271,60 @@ async function handlePopupCancel() {
   return { ok: true };
 }
 
+async function saveNativeDiagnostics(
+  recording: NativeRecording,
+): Promise<void> {
+  if (!recording.includeDeveloperLogs) return;
+  const session = sessions.get(recording.sessionId);
+  if (!session) return;
+  const diagnostics = snapshotSession(session);
+  await postAction(
+    {
+      clipsBaseUrl: recording.clipsBaseUrl,
+      captureSurface: recording.captureSurface,
+      includeCamera: recording.includeCamera,
+      includeMicrophone: recording.includeMicrophone,
+      includeDeveloperLogs: recording.includeDeveloperLogs,
+    },
+    "save-browser-diagnostics",
+    {
+      recordingId: recording.recordingId,
+      sessionId: recording.sessionId,
+      source: "extension",
+      phase: "recording",
+      pageUrl: diagnostics.pageUrl,
+      userAgent: diagnostics.userAgent,
+      startedAt: diagnostics.startedAt,
+      endedAt: diagnostics.endedAt,
+      consoleLogs: diagnostics.consoleLogs,
+      networkRequests: diagnostics.networkRequests,
+    },
+  ).catch((err) => {
+    console.warn("[clips-extension] diagnostics save failed:", err);
+  });
+}
+
+async function clearNativeRecording(): Promise<void> {
+  activeNativeRecording = null;
+  await saveActiveNativeRecording();
+  await chrome.action.setBadgeText({ text: "" });
+}
+
+async function handlePopupStatus() {
+  return {
+    ok: true,
+    activeRecording: activeNativeRecording,
+  };
+}
+
+async function handlePopupStop() {
+  return stopRecording();
+}
+
+async function handlePopupCancel() {
+  return cancelRecording();
+}
+
 async function handlePopupOpen() {
   const recording = activeNativeRecording;
   if (!recording) return { ok: false, error: "No active recording." };
@@ -1328,13 +1785,61 @@ async function handleExternalMessage(
   return { ok: false, error: "Unknown message." };
 }
 
-chrome.runtime.onInstalled.addListener(() => {
+chrome.runtime.onInstalled.addListener((details) => {
   void readSettings().then((settings) => storageSet(settings));
+  // Ask for camera/mic once on install so the grant is ready before the first
+  // recording (the record-time gate in the popup is the fallback).
+  if (details.reason === "install") {
+    void createTab(chrome.runtime.getURL("src/permission.html")).catch(
+      () => undefined,
+    );
+  }
 });
 
+// Restore recording/overlay state whenever the service worker (re)starts so an
+// in-progress recording survives MV3 worker suspension. Memoized so every entry
+// point can `await ensureRestored()` before reading activeNativeRecording — the
+// worker can be revived by the very event (icon click, status message) that
+// needs the state, and the module globals start out empty until restore runs.
+let restorePromise: Promise<void> | null = null;
+function ensureRestored(): Promise<void> {
+  if (!restorePromise) {
+    restorePromise = restoreRuntimeState().catch(() => undefined);
+  }
+  return restorePromise;
+}
+void ensureRestored();
+
 chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
   if (!message || typeof message !== "object") return false;
-  if ((message as { type?: unknown }).type === "CLIPS_NATIVE_STATUS") {
+  void (async () => {
+    // Critical: never read activeNativeRecording/overlayPhase before state is
+    // restored, or a freshly-woken worker drops the message (e.g. the offscreen
+    // "recording" status, or an overlay Stop click).
+    await ensureRestored();
+    let response: unknown;
+    try {
+      response = await dispatchRuntimeMessage(message);
+    } catch (err) {
+      response = {
+        ok: false,
+        error: err instanceof Error ? err.message : "Could not use Clips.",
+      };
+    }
+    try {
+      sendResponse(response);
+    } catch {
+      /* message port already closed (fire-and-forget sender) */
+    }
+  })();
+  return true;
+});
+
+async function dispatchRuntimeMessage(message: unknown): Promise<unknown> {
+  const type = (message as { type?: unknown }).type;
+
+  // Status updates streamed from the offscreen recorder.
+  if (type === "CLIPS_NATIVE_STATUS") {
     const status = message as OffscreenStatusMessage;
     if (
       activeNativeRecording &&
@@ -1349,35 +1854,119 @@ chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
           activeNativeRecording,
         );
       }
-      void saveActiveNativeRecording();
+      await saveActiveNativeRecording();
+      // The offscreen recorder finished its pre-roll and actually started —
+      // advance from countdown to recording (the reliable phase flip).
+      if (status.status === "recording" && overlayPhase === "countdown") {
+        await markRecordingStarted();
+      }
+      // Safety net: if the worker was suspended during the upload, stopRecording's
+      // await was lost — finalize here when the offscreen reports completion.
+      if (status.status === "complete" && overlayPhase === "saving") {
+        await finishSaving(
+          activeNativeRecording,
+          typeof status.recordingId === "string"
+            ? status.recordingId
+            : undefined,
+        );
+      }
+      if (status.status === "error") {
+        resetOverlay();
+        await broadcastUnmount();
+        await chrome.action.setBadgeText({ text: "" });
+      }
+    }
+    return { ok: true };
+  }
+
+  // The user stopped sharing from Chrome's native control bar.
+  if (type === "CLIPS_NATIVE_ENDED") {
+    const sessionId = (message as { sessionId?: string }).sessionId;
+    if (
+      activeNativeRecording &&
+      activeNativeRecording.sessionId === sessionId &&
+      overlayPhase !== "idle" &&
+      overlayPhase !== "saving"
+    ) {
+      return stopRecording();
     }
-    return false;
+    return { ok: true };
   }
 
-  const popupMessage = message as PopupMessage;
-  let task: Promise<unknown> | null = null;
-  if (popupMessage.type === "CLIPS_POPUP_START") {
-    task = handlePopupStart(popupMessage);
-  } else if (popupMessage.type === "CLIPS_POPUP_STATUS") {
-    task = handlePopupStatus();
-  } else if (popupMessage.type === "CLIPS_POPUP_STOP") {
-    task = handlePopupStop();
-  } else if (popupMessage.type === "CLIPS_POPUP_CANCEL") {
-    task = handlePopupCancel();
-  } else if (popupMessage.type === "CLIPS_POPUP_OPEN") {
-    task = handlePopupOpen();
-  } else if (popupMessage.type === "CLIPS_POPUP_SIGN_IN") {
-    task = handlePopupSignIn(popupMessage);
+  // Content script asking which overlay parts to show on its page.
+  if (type === "CLIPS_CONTENT_HELLO") {
+    return { ok: true, parts: desiredParts() };
   }
-  if (!task) return false;
 
-  void task.then(sendResponse).catch((err) => {
-    sendResponse({
-      ok: false,
-      error: err instanceof Error ? err.message : "Could not use Clips.",
-    });
-  });
-  return true;
+  // Overlay iframe handshake — rebroadcast the current timer/phase to it.
+  if (type === "CLIPS_OVERLAY_HELLO") {
+    broadcastOverlayState();
+    return { ok: true, state: overlayStateForBroadcast() };
+  }
+
+  if (type === "CLIPS_PREWARM") {
+    void ensureOffscreenDocument().catch(() => undefined);
+    return { ok: true };
+  }
+
+  switch (type) {
+    case "CLIPS_POPUP_START":
+      return handlePopupStart(message as PopupStartMessage);
+    case "CLIPS_POPUP_STATUS":
+      return handlePopupStatus();
+    case "CLIPS_POPUP_STOP":
+      return handlePopupStop();
+    case "CLIPS_POPUP_CANCEL":
+      return handlePopupCancel();
+    case "CLIPS_POPUP_OPEN":
+      return handlePopupOpen();
+    case "CLIPS_POPUP_SIGN_IN":
+      return handlePopupSignIn(
+        message as { settings?: Partial<ExtensionSettings> },
+      );
+    case "CLIPS_OVERLAY_COUNTDOWN_DONE":
+      // Skip button on the countdown overlay: start the recorder now.
+      return handleOverlaySkip();
+    case "CLIPS_OVERLAY_PAUSE":
+      return handleOverlayPause();
+    case "CLIPS_OVERLAY_RESUME":
+      return handleOverlayResume();
+    case "CLIPS_OVERLAY_STOP":
+      return stopRecording();
+    case "CLIPS_OVERLAY_CANCEL":
+      return cancelRecording();
+    case "CLIPS_OVERLAY_RESTART":
+      return handleOverlayRestart();
+    default:
+      return { ok: false, error: "Unknown message." };
+  }
+}
+
+// While a recording is active, keep the overlay following the user as they
+// switch tabs (programmatic injection covers tabs opened before the extension
+// loaded; declared content scripts cover navigations).
+chrome.tabs.onActivated.addListener((info) => {
+  void (async () => {
+    await ensureRestored();
+    if (overlayPhase === "idle" || !activeNativeRecording) return;
+    await mountOverlayOnTab(info.tabId);
+  })();
+});
+
+// While recording, the popup is disabled (setActionPopup("")), so clicking the
+// extension icon lands here: stop & save immediately (or discard if we're still
+// in the pre-roll countdown). When idle, the popup opens and this never fires.
+chrome.action.onClicked.addListener(() => {
+  void (async () => {
+    // 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();
+    if (!activeNativeRecording) return;
+    if (overlayPhase === "countdown") await cancelRecording();
+    else if (overlayPhase === "recording" || overlayPhase === "paused") {
+      await stopRecording();
+    }
+  })();
 });
 
 chrome.runtime.onMessageExternal.addListener(