@agent-native/core 0.88.0 → 0.90.2

package/corpus/templates/clips/desktop/src/lib/media-device-selection.ts

@@ -0,0 +1,157 @@
+export type AudioInputCandidate = Pick<
+  MediaDeviceInfo,
+  "deviceId" | "kind" | "label"
+>;
+
+export type AudioInputFallbackReason = "saved-label" | "best-concrete";
+
+export interface AudioInputFallback {
+  deviceId: string;
+  label: string;
+  reason: AudioInputFallbackReason;
+}
+
+const PSEUDO_MEDIA_DEVICE_ID_RE = /^(default|communications)$/i;
+const PHONE_MIC_LABEL_RE =
+  /\b(?:iphone|ipad|android phone|continuity|handoff|phone)\b/i;
+
+function normalizedLabel(value: string | null | undefined): string {
+  return (value ?? "")
+    .toLowerCase()
+    .replace(/\([^)]*\bdefault\b[^)]*\)/gi, "")
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+    .replace(/\s+/g, " ");
+}
+
+function labelsMatch(
+  leftValue: string | null | undefined,
+  rightValue: string | null | undefined,
+): boolean {
+  const left = normalizedLabel(leftValue);
+  const right = normalizedLabel(rightValue);
+  if (!left || !right) return false;
+  if (left === right || left.includes(right) || right.includes(left)) {
+    return true;
+  }
+  const leftTokens = left.split(" ");
+  const rightTokens = right.split(" ");
+  const [short, long] =
+    leftTokens.length <= rightTokens.length
+      ? [leftTokens, rightTokens]
+      : [rightTokens, leftTokens];
+  return short.every((token) => long.includes(token));
+}
+
+export function normalizedMediaDeviceId(
+  value: string | null | undefined,
+): string {
+  return value?.trim() ?? "";
+}
+
+export function isPseudoMediaDeviceId(
+  value: string | null | undefined,
+): boolean {
+  const id = normalizedMediaDeviceId(value);
+  return !id || PSEUDO_MEDIA_DEVICE_ID_RE.test(id);
+}
+
+export function isLikelyPhoneMicLabel(
+  label: string | null | undefined,
+): boolean {
+  return PHONE_MIC_LABEL_RE.test(label ?? "");
+}
+
+export function isSelectableAudioInputDevice(
+  device: AudioInputCandidate,
+): boolean {
+  return (
+    device.kind === "audioinput" &&
+    !isPseudoMediaDeviceId(device.deviceId) &&
+    !isLikelyPhoneMicLabel(device.label)
+  );
+}
+
+function isBuiltInMicLabel(label: string | null | undefined): boolean {
+  const normalized = normalizedLabel(label);
+  return (
+    normalized.includes("macbook") ||
+    normalized.includes("built-in") ||
+    normalized.includes("built in") ||
+    normalized.includes("internal microphone")
+  );
+}
+
+export function findAudioInputBySavedLabel(
+  devices: Iterable<AudioInputCandidate>,
+  options: {
+    savedLabel: string | null | undefined;
+    avoidDeviceIds?: Array<string | null | undefined>;
+  },
+): AudioInputFallback | null {
+  const avoid = new Set(
+    (options.avoidDeviceIds ?? [])
+      .map((id) => normalizedMediaDeviceId(id))
+      .filter(Boolean),
+  );
+  const candidates = Array.from(devices).filter(
+    (device) =>
+      isSelectableAudioInputDevice(device) && !avoid.has(device.deviceId),
+  );
+
+  const savedLabel = normalizedLabel(options.savedLabel);
+  if (savedLabel) {
+    const labelMatch = candidates.find((device) =>
+      labelsMatch(device.label, savedLabel),
+    );
+    if (labelMatch) {
+      return {
+        deviceId: labelMatch.deviceId,
+        label: labelMatch.label,
+        reason: "saved-label",
+      };
+    }
+  }
+
+  return null;
+}
+
+export function chooseFallbackAudioInput(
+  devices: Iterable<AudioInputCandidate>,
+  options: {
+    savedLabel?: string | null;
+    avoidDeviceIds?: Array<string | null | undefined>;
+  } = {},
+): AudioInputFallback | null {
+  const labelMatch = findAudioInputBySavedLabel(devices, {
+    savedLabel: options.savedLabel,
+    avoidDeviceIds: options.avoidDeviceIds,
+  });
+  if (labelMatch) return labelMatch;
+
+  const avoid = new Set(
+    (options.avoidDeviceIds ?? [])
+      .map((id) => normalizedMediaDeviceId(id))
+      .filter(Boolean),
+  );
+  const candidates = Array.from(devices).filter(
+    (device) =>
+      isSelectableAudioInputDevice(device) && !avoid.has(device.deviceId),
+  );
+
+  const best =
+    candidates.find((device) => isBuiltInMicLabel(device.label)) ??
+    candidates[0] ??
+    null;
+  return best
+    ? { deviceId: best.deviceId, label: best.label, reason: "best-concrete" }
+    : null;
+}
+
+export async function enumerateAudioInputDevices(): Promise<
+  AudioInputCandidate[]
+> {
+  if (!navigator.mediaDevices?.enumerateDevices) return [];
+  const devices = await navigator.mediaDevices.enumerateDevices();
+  return devices.filter((device) => device.kind === "audioinput");
+}

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

@@ -4,6 +4,8 @@
 
 export const MACOS_CAPTURE_PERMISSION_MESSAGE =
   "Grant the required macOS permissions below, then try again. If you just changed access, restart Clips before retrying.";
+export const MACOS_SCREEN_PERMISSION_MESSAGE =
+  "Grant Screen Recording permission in macOS Settings, then restart Clips and try again.";
 export const MACOS_SPEECH_PERMISSION_MESSAGE =
   "Grant Speech Recognition and Microphone access, then try again. If you just changed access, restart Clips before retrying.";
 

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

@@ -93,6 +93,7 @@ const DEV_SYNTHETIC_CAPTURE_FLAG = "clips:dev-synthetic-capture";
 const LEGACY_DEV_REAL_CAPTURE_FLAG = "clips:dev-real-capture";
 const LIVE_UPLOAD_CHUNK_MS = 1_000;
 const NATIVE_FULLSCREEN_SEGMENT_MS = 5 * 60_000;
+const NATIVE_FULLSCREEN_MIME_TYPE = "video/mp4";
 // GCS resumable uploads require every non-final chunk to be a multiple of
 // 256 KiB. MediaRecorder emits arbitrary blob sizes, so on the streaming path
 // we buffer raw blobs and only PUT aligned slices; the unaligned remainder is
@@ -104,6 +105,7 @@ const STREAM_CHUNK_BYTES = 15 * GCS_CHUNK_ALIGN_BYTES; // 3.75 MiB
 //  - "streaming" — server has a resumable session; flush aligned chunks live.
 //  - "buffered"  — per-blob chunks staged server-side, assembled on finalize.
 type UploadMode = "streaming" | "buffered";
+type StreamingUploadClient = "desktop-native";
 const CLOUD_CAPTURE_FRAME_RATE = 24;
 const CLOUD_CAPTURE_MAX_WIDTH = 1920;
 const CLOUD_CAPTURE_MAX_HEIGHT = 1080;
@@ -903,7 +905,11 @@ async function createServerRecording(
   hasCamera: boolean,
   hasAudio: boolean,
   titleContext?: CaptureTitleResult,
-  options?: { mimeType?: string; requestStreaming?: boolean },
+  options?: {
+    mimeType?: string;
+    requestStreaming?: boolean;
+    streamingUploadClient?: StreamingUploadClient;
+  },
 ) {
   const url = `${serverUrl.replace(/\/+$/, "")}/_agent-native/actions/create-recording`;
   console.log("[clips-recorder] POST", url, {
@@ -928,7 +934,11 @@ async function createServerRecording(
         spaceIds: [],
         visibility: "public",
         ...(options?.requestStreaming
-          ? { requestStreaming: true, mimeType: options.mimeType }
+          ? {
+              requestStreaming: true,
+              mimeType: options.mimeType,
+              streamingUploadClient: options.streamingUploadClient,
+            }
           : {}),
         ...(titleContext
           ? {
@@ -1250,6 +1260,12 @@ function decChunkBusy(): void {
 // backup-replay path when the very next attempt would land
 const CHUNK_UPLOAD_MAX_ATTEMPTS = 3;
 const CHUNK_UPLOAD_RETRY_BASE_MS = 250;
+// A hung connection (server accepts the TCP connection but never responds)
+// would otherwise stall a chunk upload — and the stop()/finalize flow that
+// awaits all in-flight chunks — indefinitely. Bound each attempt so a stall
+// is treated as a retryable failure instead.
+const CHUNK_UPLOAD_TIMEOUT_MS = 60_000;
+const FINALIZE_UPLOAD_TIMEOUT_MS = 180_000;
 
 // Only transient server responses are worth retrying inline; a 4xx (bad
 // request, auth, not found) won't fix itself on the next attempt.
@@ -1278,9 +1294,11 @@ async function uploadChunk(url: string, blob: Blob): Promise<void> {
         // need cookies.
         credentials: "include",
         body: blob,
+        signal: AbortSignal.timeout(CHUNK_UPLOAD_TIMEOUT_MS),
       });
     } catch (err) {
-      // Network-level failure (offline, connection reset, DNS) — transient.
+      // Network-level failure (offline, connection reset, DNS) or a timeout
+      // abort from AbortSignal.timeout — both transient.
       lastError = err instanceof Error ? err : new Error(String(err));
     } finally {
       decChunkBusy();
@@ -1646,6 +1664,24 @@ function showFinalizingFeedback() {
   );
 }
 
+async function claimNativeUploadOpen(recordingId: string): Promise<boolean> {
+  return invoke<boolean>("native_fullscreen_claim_upload_open", {
+    recordingId,
+  }).catch(() => true);
+}
+
+async function openNativeUploadUrl(
+  recordingId: string,
+  url: string,
+): Promise<void> {
+  if (!(await claimNativeUploadOpen(recordingId))) return;
+  try {
+    await openExternal(url);
+  } catch (err) {
+    console.error("[clips-recorder] openExternal failed:", err);
+  }
+}
+
 function abortCreatedRecordingOnCountdownCancel(
   err: unknown,
   recordingPromise: Promise<{ id: string }>,
@@ -1675,6 +1711,7 @@ async function startNativeFullscreenRecording(
   const localFolderName = localOnly ? createLocalRecordingFolderName() : "";
   const streamCleanups: Array<() => void> = [audioCue.cleanup];
   let id = "";
+  let uploadMode: UploadMode = "buffered";
   let localCameraExport: LocalRecordingExportHandle | null = null;
   let localCameraStream: MediaStream | null = null;
   let localOwnsCameraStream = false;
@@ -1689,6 +1726,7 @@ async function startNativeFullscreenRecording(
   let nativeTranscriptFailureSaved = false;
   const wantsSystemAudio = params.systemAudioOn !== false;
   const wantsRecordedAudio = wantsAudio || wantsSystemAudio;
+  let micDeviceLabel: string | null = params.micLabel || null;
   const saveTranscriptFailure = async (failureReason: string) => {
     if (!wantsRecordedAudio || nativeTranscriptFailureSaved || !id) return;
     nativeTranscriptFailureSaved = true;
@@ -1699,6 +1737,26 @@ async function startNativeFullscreenRecording(
       params.authToken,
     );
   };
+  const startNativeTranscriptionBeforeRecording = async () => {
+    if (localOnly || !wantsRecordedAudio || transcriptionCapture) return;
+    transcriptionCapture = await startTranscriptionCapture(
+      {
+        deviceId: params.micId,
+        label: micDeviceLabel,
+      },
+      wantsSystemAudio,
+      { voiceProcessing: false },
+    );
+    if (
+      wantsRecordedAudio &&
+      !transcriptionCapture &&
+      shouldSaveLocalTranscriptionStartupFailure()
+    ) {
+      void saveTranscriptFailure(
+        "macOS Speech recognition could not start for this recording. Check Speech Recognition, System Audio, and Microphone permissions, then retry transcription.",
+      );
+    }
+  };
 
   try {
     await invoke("park_popover_offscreen").catch(() => {});
@@ -1749,11 +1807,15 @@ async function startNativeFullscreenRecording(
     // be stale or empty (device list locked when picked, or a rotated deviceId
     // salt after an app update), so a one-shot getUserMedia gives the exact
     // current device name.
-    let micDeviceLabel = params.micLabel || null;
     if (wantsAudio && params.micId) {
       try {
         const probe = await navigator.mediaDevices.getUserMedia({
-          audio: { deviceId: { exact: params.micId } },
+          audio: {
+            deviceId: { exact: params.micId },
+            echoCancellation: false,
+            noiseSuppression: false,
+            autoGainControl: false,
+          },
           video: false,
         });
         const liveLabel = probe.getAudioTracks()[0]?.label?.trim();
@@ -1805,6 +1867,11 @@ async function startNativeFullscreenRecording(
         wantsCamera,
         wantsRecordedAudio,
         captureTitle,
+        {
+          mimeType: NATIVE_FULLSCREEN_MIME_TYPE,
+          requestStreaming: true,
+          streamingUploadClient: "desktop-native",
+        },
       ).finally(() => {
         console.timeEnd("[clips-recorder] createServerRecording duration");
       });
@@ -1812,6 +1879,13 @@ async function startNativeFullscreenRecording(
       // native capture as soon as it does so setup overlaps the 3-2-1.
       const warmAndId = (async () => {
         const createRes = await recordingPromise;
+        uploadMode = createRes.uploadMode;
+        id = createRes.id;
+        // Start the live transcription mic tap before SCK attaches its
+        // recording output. On macOS, opening AVAudioEngine after SCK has
+        // started writing can reconfigure the shared input device and leave
+        // SCK's microphone leg near-silent while Whisper still hears audio.
+        await startNativeTranscriptionBeforeRecording();
         await warmMic(createRes.id);
         return createRes.id;
       })();
@@ -1835,12 +1909,24 @@ async function startNativeFullscreenRecording(
       recordingId: id,
       ...captureAudioParams,
     });
-    // Capture is now live — stamp the timer baseline before any further awaits
-    // so the toolbar clock and toolbar-enable line up with the real start.
+    await transcriptionCapture?.resetTimeline().catch((err) => {
+      console.warn(
+        "[clips-recorder] transcription timeline reset failed:",
+        err,
+      );
+    });
+    // Capture is now live — after rebasing the transcript timeline, stamp the
+    // timer baseline so the toolbar clock lines up with the real start.
     startedAt = Date.now();
     localCameraExport?.start(2_000);
   } catch (err) {
     await localCameraExport?.cancel().catch(() => {});
+    await transcriptionCapture?.cancel().catch((cancelErr) => {
+      console.warn(
+        "[clips-recorder] native transcription cancel after start failure failed:",
+        cancelErr,
+      );
+    });
     // Tear down any capture started by the warm phase — on a countdown cancel
     // (or a `begin` failure) the SCStream is already running with the mic live,
     // and without this it would keep capturing after the aborted start.
@@ -2030,6 +2116,7 @@ async function startNativeFullscreenRecording(
             recordingId: id,
             authToken: params.authToken ?? "",
             cookie: params.cookie ?? "",
+            uploadMode,
             hasAudio: wantsRecordedAudio,
             hasCamera: wantsCamera,
           },
@@ -2041,6 +2128,9 @@ async function startNativeFullscreenRecording(
             new Promise<void>((resolve) => window.setTimeout(resolve, 15000)),
           ]);
           unlistenFinalized();
+          await invoke("set_recording_state", { active: false }).catch(
+            () => {},
+          );
 
           const capturedTranscript = await transcriptionCapture
             ?.stop()
@@ -2089,13 +2179,10 @@ async function startNativeFullscreenRecording(
                 authToken: params.authToken,
               })
             ) {
-              try {
-                await openExternal(
-                  `${params.serverUrl.replace(/\/+$/, "")}${viewUrl}`,
-                );
-              } catch (openErr) {
-                console.error("[clips-recorder] openExternal failed:", openErr);
-              }
+              await openNativeUploadUrl(
+                id,
+                `${params.serverUrl.replace(/\/+$/, "")}${viewUrl}`,
+              );
               return { recordingId: id, viewUrl };
             }
             await abortRecordingUpload(
@@ -2120,13 +2207,10 @@ async function startNativeFullscreenRecording(
             throw err;
           }
 
-          try {
-            await openExternal(
-              `${params.serverUrl.replace(/\/+$/, "")}${viewUrl}`,
-            );
-          } catch (err) {
-            console.error("[clips-recorder] openExternal failed:", err);
-          }
+          await openNativeUploadUrl(
+            uploadResult.recordingId,
+            `${params.serverUrl.replace(/\/+$/, "")}${viewUrl}`,
+          );
           return {
             recordingId: uploadResult.recordingId,
             viewUrl,
@@ -2245,36 +2329,12 @@ async function startNativeFullscreenRecording(
   emitState();
 
   if (!localOnly) {
-    await showRegionGuidesForRecording(true);
-    transcriptionCapture = wantsRecordedAudio
-      ? await startTranscriptionCapture(
-          {
-            deviceId: params.micId,
-            label: params.micLabel,
-          },
-          wantsSystemAudio,
-        )
-      : null;
-    // Stop/Cancel can fire during the await above — at that point stop()/cancel()
-    // ran while transcriptionCapture was still null, so it never tore this down.
-    // Cancel the freshly-started session here so it doesn't keep running.
-    if (stopped && transcriptionCapture) {
-      void transcriptionCapture.cancel().catch(() => {});
-      transcriptionCapture = null;
-    } else if (pausedAt != null && transcriptionCapture) {
+    if (pausedAt != null && transcriptionCapture) {
       // The user paused while the engine was still starting; honor it now.
       console.log(
         "[clips-recorder] native: paused during startup, pausing transcription",
       );
       void transcriptionCapture.pause().catch(() => {});
-    } else if (
-      wantsRecordedAudio &&
-      !transcriptionCapture &&
-      shouldSaveLocalTranscriptionStartupFailure()
-    ) {
-      void saveTranscriptFailure(
-        "macOS Speech recognition could not start for this recording. Check Speech Recognition, System Audio, and Microphone permissions, then retry transcription.",
-      );
     }
   }
 
@@ -2488,7 +2548,7 @@ async function startRecordingInner(
       ? getCameraStreamWithFallback(params.cameraId)
       : null;
   const audioStreamPromise: Promise<MediaStream> | null = wantsAudio
-    ? getAudioStreamWithFallback(params.micId)
+    ? getAudioStreamWithFallback(params.micId, params.micLabel)
     : null;
 
   // Use allSettled so a single rejection (e.g. user cancels the macOS screen
@@ -3350,6 +3410,7 @@ async function startRecordingInner(
       await invoke("hide_recording_chrome").catch((err) =>
         console.error(`[clips-recorder] hide_recording_chrome failed:`, err),
       );
+      await invoke("set_recording_state", { active: false }).catch(() => {});
 
       // Wait for any in-flight chunk uploads to settle before sending the
       // final chunk. Otherwise the server could finalize before the last
@@ -3411,6 +3472,7 @@ async function startRecordingInner(
           headers: { "Content-Type": "application/octet-stream" },
           credentials: "include",
           body: finalBody,
+          signal: AbortSignal.timeout(FINALIZE_UPLOAD_TIMEOUT_MS),
         });
         const bodyText = await finalRes.text().catch(() => "");
         console.log(

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

@@ -15,6 +15,7 @@ import type { UnlistenFn } from "@tauri-apps/api/event";
 import {
   appendFinalTranscript,
   onFinalTranscript,
+  resetTranscriptionTimeline,
   startTranscriptionEngine,
   stopTranscriptionEngine,
   TranscriptionEngine,
@@ -45,6 +46,8 @@ export interface TranscriptionCapture {
   pause(): Promise<void>;
   /** Restart the audio engine after a `pause()`. */
   resume(): Promise<void>;
+  /** Rebase timestamped segments to the actual recording start. */
+  resetTimeline(): Promise<void>;
 }
 
 interface SpeechRecognitionResultLike {
@@ -275,6 +278,9 @@ async function startBrowserTranscriptionCapture(): Promise<TranscriptionCapture
         );
       }
     },
+    async resetTimeline() {
+      // Web Speech does not emit timestamped segments.
+    },
   };
 }
 
@@ -286,6 +292,9 @@ export async function startTranscriptionCapture(
     label?: string | null;
   },
   captureSystem: boolean = true,
+  opts?: {
+    voiceProcessing?: boolean;
+  },
 ): Promise<TranscriptionCapture | null> {
   const lines: string[] = [];
   const segments: SourcedTranscriptSegment[] = [];
@@ -324,7 +333,11 @@ export async function startTranscriptionCapture(
       }),
     );
 
-    engine = await startTranscriptionEngine({ mic, captureSystem });
+    engine = await startTranscriptionEngine({
+      mic,
+      captureSystem,
+      voiceProcessing: opts?.voiceProcessing,
+    });
     console.log(
       `[clips-recorder] transcription started (${engine} mic${captureSystem ? "+system" : ""})`,
     );
@@ -350,7 +363,11 @@ export async function startTranscriptionCapture(
         pauseFinalsSettleUntil = Date.now() + WHISPER_STOP_SETTLE_MS;
         console.log(`[clips-recorder] transcription paused (${engine})`);
       } else {
-        engine = await startTranscriptionEngine({ mic, captureSystem });
+        engine = await startTranscriptionEngine({
+          mic,
+          captureSystem,
+          voiceProcessing: opts?.voiceProcessing,
+        });
         // stop()/cancel() can run during the await above; if it did, the new
         // engine would leak (mic/system capture stays live). Tear it down.
         if (disposed) {
@@ -421,5 +438,8 @@ export async function startTranscriptionCapture(
       desiredPaused = false;
       await applyAudioState();
     },
+    async resetTimeline() {
+      await resetTranscriptionTimeline(engine);
+    },
   };
 }

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

@@ -119,6 +119,7 @@ export async function restartTranscriptionEngine(
   engine: TranscriptionEngine,
   mic?: MicSelection,
   captureSystem: boolean = true,
+  voiceProcessing: boolean = true,
 ): Promise<void> {
   if (engine === "whisper") {
     await invoke("audio_transcription_start", {
@@ -127,12 +128,20 @@ export async function restartTranscriptionEngine(
       micDeviceId: mic?.deviceId || null,
       micDeviceLabel: mic?.label || null,
       captureSystem,
+      voiceProcessing,
+      owner: "meeting",
     });
   } else {
+    // This module is meetings-only (see file header) — always pass
+    // owner: "meeting" so a Fn/dictation press can't silently evict a
+    // meeting's native-speech fallback session (Rust-side priority rule
+    // in native_speech.rs). Dictation's own caller (voice-dictation.ts)
+    // omits `owner` and gets the "dictation" default.
     await invoke("native_speech_start", {
       locale: browserLocale(),
       micDeviceId: mic?.deviceId || null,
       micDeviceLabel: mic?.label || null,
+      owner: "meeting",
     });
   }
 }
@@ -141,10 +150,22 @@ export async function startTranscriptionEngine(opts: {
   mic?: MicSelection;
   /** Capture + transcribe system audio (whisper). Default true. */
   captureSystem?: boolean;
+  /**
+   * Enable Apple's voice-processing input mode for the Whisper mic tap. Native
+   * recordings disable this so the transcription tap does not reconfigure the
+   * shared microphone before ScreenCaptureKit opens it.
+   */
+  voiceProcessing?: boolean;
 }): Promise<TranscriptionEngine> {
   const captureSystem = opts.captureSystem ?? true;
+  const voiceProcessing = opts.voiceProcessing ?? true;
   try {
-    await restartTranscriptionEngine("whisper", opts.mic, captureSystem);
+    await restartTranscriptionEngine(
+      "whisper",
+      opts.mic,
+      captureSystem,
+      voiceProcessing,
+    );
     return "whisper";
   } catch (err) {
     console.warn(
@@ -165,6 +186,13 @@ export async function stopTranscriptionEngine(
   );
 }
 
+export async function resetTranscriptionTimeline(
+  engine: TranscriptionEngine,
+): Promise<void> {
+  if (engine !== "whisper") return;
+  await invoke("audio_transcription_reset_timeline");
+}
+
 // ---------------------------------------------------------------------------
 // Event subscriptions
 // ---------------------------------------------------------------------------

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

@@ -2,6 +2,8 @@ import { relaunch } from "@tauri-apps/plugin-process";
 import { check, Update } from "@tauri-apps/plugin-updater";
 import { useEffect, useState } from "react";
 
+declare const __CLIPS_DESKTOP_LOCAL_BUILD__: boolean;
+
 export type UpdateStatus =
   | { state: "idle" }
   | { state: "checking" }
@@ -70,6 +72,10 @@ function startUpdateLoop() {
   started = true;
   // Skip update checks in dev — there's no release endpoint to check.
   if (import.meta.env.DEV) return;
+  // Local release builds are for testing the current checkout. Do not replace
+  // them with the published auto-update channel just because package.json has
+  // a lower development version.
+  if (__CLIPS_DESKTOP_LOCAL_BUILD__) return;
   // Check 3s after launch (let the popover finish first paint), then every
   // 4 hours. Matches the cadence used by the Electron app.
   setTimeout(runCheck, 3000);