@agent-native/core 0.137.7 → 0.138.0

package/corpus/templates/clips/app/components/player/video-player.tsx

@@ -28,6 +28,7 @@ import {
 } from "@/components/ui/dropdown-menu";
 import { Spinner } from "@/components/ui/spinner";
 import { useMseVideoSource } from "@/hooks/use-mse-video-source";
+import { usePlaybackPosition } from "@/hooks/use-playback-position";
 import {
   parsePlaybackSpeed,
   readPlaybackSpeedPreference,
@@ -265,9 +266,12 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
       [videoUrl],
     );
     const videoRef = useRef<HTMLVideoElement | null>(null);
+    const [playbackVideoEl, setPlaybackVideoEl] =
+      useState<HTMLVideoElement | null>(null);
     const setVideoNode = useCallback(
       (el: HTMLVideoElement | null) => {
         videoRef.current = el;
+        setPlaybackVideoEl(el);
         onVideoElementChange?.(el);
       },
       [onVideoElementChange],
@@ -408,6 +412,50 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
       () => embedProvider === "loom" || isLoomEmbedUrl(activeVideoSrc),
       [activeVideoSrc, embedProvider],
     );
+    const restorePlaybackPosition = useCallback(
+      (positionMs: number) => {
+        const v = videoRef.current;
+        if (!v || (startMs && startMs > 0)) return;
+        if (hasPlaybackStarted && !autoPlay) return;
+        if (!autoPlay && isPlayPending) return;
+        if (!autoPlay && v.currentTime > 0.5) return;
+
+        const visibleMs = clampSeek(
+          skipExcludedRange(positionMs, excludedRanges, resolvedDurationMs),
+          v,
+          resolvedDurationMs,
+        );
+        if (visibleMs <= 0) return;
+
+        try {
+          initialVisibleFrameSeekedRef.current = true;
+          v.currentTime = visibleMs / 1000;
+          setCurrentMs(visibleMs);
+          setCanPlay(true);
+          setIsPreparing(false);
+          onTimeUpdate?.(visibleMs, resolvedDurationMs);
+        } catch (error) {
+          console.warn("[clips] playback position restore failed", error);
+        }
+      },
+      [
+        autoPlay,
+        excludedRanges,
+        hasPlaybackStarted,
+        isPlayPending,
+        onTimeUpdate,
+        resolvedDurationMs,
+        startMs,
+      ],
+    );
+    usePlaybackPosition({
+      recordingId,
+      videoEl: playbackVideoEl,
+      durationMs,
+      explicitStartMs: startMs,
+      allowRestoreWhilePlaying: autoPlay,
+      onRestore: restorePlaybackPosition,
+    });
     // Clips stores exactly one `videoUrl` per recording (no alternate-format
     // fallback to select between), and every browser MediaRecorder-based
     // recording is stored as `webm` — which Safari (desktop and iOS) cannot
@@ -1291,11 +1339,12 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
           ? "loading"
           : "ready"
         : null;
-    const centerOverlayLabel = isPlayPending
-      ? "Starting playback"
-      : isBuffering
-        ? "Buffering"
-        : "Preparing clip";
+    const centerOverlayLabel =
+      isPlayPending && !hasPlaybackStarted
+        ? "Starting playback"
+        : isPlayPending || isBuffering
+          ? "Buffering"
+          : "Preparing clip";
 
     return (
       <div

package/corpus/templates/clips/app/components/recorder/pre-record-panel.tsx

@@ -14,6 +14,16 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
 import { CaptureInstallInlineLink } from "@/components/capture-install-options";
 import { ImportMenu } from "@/components/import-menu";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
 import { Button } from "@/components/ui/button";
 import {
   Collapsible,
@@ -426,6 +436,35 @@ export function PreRecordPanel({
     );
   }, [micId, micLabel, mics, t]);
 
+  const [micWarningOpen, setMicWarningOpen] = useState(false);
+
+  const buildStartOpts = useCallback(
+    () => ({
+      // If the user toggled off the camera inside screen+camera mode,
+      // downgrade to screen-only so the recorder engine doesn't try
+      // to acquire a webcam stream.
+      mode: (mode === "screen+camera" && !needsCamera
+        ? "screen"
+        : mode) as RecordingMode,
+      displaySurface: normalizeDisplaySurfaceForRuntime(displaySurface),
+      micDeviceId: micId === "default" ? null : micId,
+      micDeviceLabel:
+        micId === "default" || micId === NO_MIC_DEVICE_ID
+          ? null
+          : selectedMicLabel,
+      cameraDeviceId: needsCamera && cameraId !== "default" ? cameraId : null,
+    }),
+    [mode, needsCamera, displaySurface, micId, selectedMicLabel, cameraId],
+  );
+
+  const handleStartClick = useCallback(() => {
+    if (micId === NO_MIC_DEVICE_ID) {
+      setMicWarningOpen(true);
+      return;
+    }
+    onStart(buildStartOpts());
+  }, [micId, buildStartOpts, onStart]);
+
   const selectedCameraLabel = useMemo(() => {
     if (!needsCamera) return null;
     if (cameraId === "default") return t("preRecord.defaultCamera");
@@ -893,24 +932,7 @@ export function PreRecordPanel({
           )}
           <Button
             disabled={startDisabled}
-            onClick={() =>
-              onStart({
-                // If the user toggled off the camera inside screen+camera mode,
-                // downgrade to screen-only so the recorder engine doesn't try
-                // to acquire a webcam stream.
-                mode:
-                  mode === "screen+camera" && !needsCamera ? "screen" : mode,
-                displaySurface:
-                  normalizeDisplaySurfaceForRuntime(displaySurface),
-                micDeviceId: micId === "default" ? null : micId,
-                micDeviceLabel:
-                  micId === "default" || micId === NO_MIC_DEVICE_ID
-                    ? null
-                    : selectedMicLabel,
-                cameraDeviceId:
-                  needsCamera && cameraId !== "default" ? cameraId : null,
-              })
-            }
+            onClick={handleStartClick}
             className={cn("h-12", onCancel ? "flex-1" : "w-full")}
           >
             {t("preRecord.startRecording")}
@@ -943,6 +965,31 @@ export function PreRecordPanel({
           </>
         )}
       </div>
+
+      <AlertDialog open={micWarningOpen} onOpenChange={setMicWarningOpen}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>
+              {t("preRecord.micOffConfirmTitle")}
+            </AlertDialogTitle>
+            <AlertDialogDescription>
+              {t("preRecord.micOffConfirmDescription")}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>{t("common.cancel")}</AlertDialogCancel>
+            <AlertDialogAction
+              onClick={(event) => {
+                event.preventDefault();
+                setMicWarningOpen(false);
+                onStart(buildStartOpts());
+              }}
+            >
+              {t("preRecord.startWithoutMic")}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
     </div>
   );
 }

package/corpus/templates/clips/app/hooks/use-playback-position.ts

@@ -0,0 +1,188 @@
+import { useEffect, useRef } from "react";
+
+import {
+  getPlaybackPosition,
+  savePlaybackPosition,
+} from "@/lib/playback-position";
+
+const SAVE_INTERVAL_MS = 5_000;
+const MIN_POSITION_MS = 50;
+const COMPLETION_TAIL_MS = 1_500;
+
+export interface UsePlaybackPositionOptions {
+  recordingId: string;
+  videoEl: HTMLVideoElement | null;
+  durationMs: number;
+  explicitStartMs?: number;
+  allowRestoreWhilePlaying?: boolean;
+  onRestore?: (positionMs: number) => void;
+}
+
+/**
+ * Persists the latest native-video position for the current viewer. This is
+ * separate from view analytics so the recording owner can resume without
+ * becoming one of the clip's counted viewers.
+ */
+export function usePlaybackPosition({
+  recordingId,
+  videoEl,
+  durationMs,
+  explicitStartMs,
+  allowRestoreWhilePlaying = false,
+  onRestore,
+}: UsePlaybackPositionOptions) {
+  const durationMsRef = useRef(durationMs);
+  const onRestoreRef = useRef(onRestore);
+
+  durationMsRef.current = durationMs;
+  onRestoreRef.current = onRestore;
+
+  useEffect(() => {
+    if (!videoEl || !recordingId) return;
+
+    const controller = new AbortController();
+    let cancelled = false;
+    let playbackStarted = false;
+    let restoreApplied = false;
+    let saveInFlight = false;
+    let pendingSave: { positionMs: number; keepalive: boolean } | null = null;
+    let lastSavedPositionMs = -1;
+    let lastSavedAt = -SAVE_INTERVAL_MS;
+    let removePendingRestoreListeners: (() => void) | null = null;
+
+    const readPositionMs = (): number | null => {
+      const seconds = videoEl.currentTime;
+      if (!Number.isFinite(seconds) || seconds < 0 || seconds >= 1e7) {
+        return null;
+      }
+      return Math.floor(seconds * 1000);
+    };
+
+    const persist = (keepalive: boolean) => {
+      const positionMs = readPositionMs();
+      if (
+        positionMs === null ||
+        (!playbackStarted && positionMs < MIN_POSITION_MS)
+      ) {
+        return;
+      }
+
+      const now = Date.now();
+      if (!keepalive && now - lastSavedAt < SAVE_INTERVAL_MS) {
+        return;
+      }
+
+      if (saveInFlight) {
+        pendingSave = { positionMs, keepalive };
+        return;
+      }
+
+      saveInFlight = true;
+      lastSavedPositionMs = positionMs;
+      lastSavedAt = now;
+      void savePlaybackPosition(recordingId, positionMs, { keepalive })
+        .catch((error) => {
+          if (!cancelled) {
+            console.warn("[clips] playback position save failed", error);
+          }
+        })
+        .finally(() => {
+          saveInFlight = false;
+          if (!pendingSave) return;
+          const next = pendingSave;
+          pendingSave = null;
+          persist(next.keepalive);
+        });
+    };
+
+    const restore = (positionMs: number) => {
+      if (cancelled || restoreApplied || explicitStartMs) return;
+      if (positionMs <= 0) return;
+      const duration = durationMsRef.current;
+      if (duration > 0 && positionMs >= duration - COMPLETION_TAIL_MS) {
+        return;
+      }
+      if (
+        playbackStarted &&
+        !allowRestoreWhilePlaying &&
+        readPositionMs() !== 0
+      ) {
+        return;
+      }
+
+      restoreApplied = true;
+      onRestoreRef.current?.(positionMs);
+    };
+
+    const restoreWhenReady = (positionMs: number) => {
+      if (videoEl.readyState >= 1) {
+        restore(positionMs);
+        return;
+      }
+
+      const apply = () => {
+        removePendingRestoreListeners?.();
+        removePendingRestoreListeners = null;
+        restore(positionMs);
+      };
+      videoEl.addEventListener("loadedmetadata", apply);
+      videoEl.addEventListener("loadeddata", apply);
+      removePendingRestoreListeners = () => {
+        videoEl.removeEventListener("loadedmetadata", apply);
+        videoEl.removeEventListener("loadeddata", apply);
+      };
+    };
+
+    const onPlay = () => {
+      playbackStarted = true;
+    };
+    const onTimeUpdate = () => {
+      if (playbackStarted) persist(false);
+    };
+    const onPause = () => persist(true);
+    const onSeeked = () => persist(true);
+    const onEnded = () => persist(true);
+    const onPageHide = () => persist(true);
+    const onVisibilityChange = () => {
+      if (document.visibilityState === "hidden") persist(true);
+    };
+
+    videoEl.addEventListener("play", onPlay);
+    videoEl.addEventListener("timeupdate", onTimeUpdate);
+    videoEl.addEventListener("pause", onPause);
+    videoEl.addEventListener("seeked", onSeeked);
+    videoEl.addEventListener("ended", onEnded);
+    window.addEventListener("pagehide", onPageHide);
+    document.addEventListener("visibilitychange", onVisibilityChange);
+
+    if (!explicitStartMs) {
+      void getPlaybackPosition(recordingId, { signal: controller.signal })
+        .then((positionMs) => {
+          if (positionMs !== null) restoreWhenReady(positionMs);
+        })
+        .catch((error) => {
+          if (
+            !cancelled &&
+            (error as { name?: string })?.name !== "AbortError"
+          ) {
+            console.warn("[clips] playback position load failed", error);
+          }
+        });
+    }
+
+    return () => {
+      persist(true);
+      cancelled = true;
+      controller.abort();
+      removePendingRestoreListeners?.();
+      removePendingRestoreListeners = null;
+      videoEl.removeEventListener("play", onPlay);
+      videoEl.removeEventListener("timeupdate", onTimeUpdate);
+      videoEl.removeEventListener("pause", onPause);
+      videoEl.removeEventListener("seeked", onSeeked);
+      videoEl.removeEventListener("ended", onEnded);
+      window.removeEventListener("pagehide", onPageHide);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [allowRestoreWhilePlaying, explicitStartMs, recordingId, videoEl]);
+}

package/corpus/templates/clips/app/hooks/use-view-tracking.ts

@@ -1,27 +1,9 @@
 import { appBasePath } from "@agent-native/core/client/api-path";
 import { useEffect, useRef } from "react";
 
-import { clampCompletionPct } from "../../shared/view-analytics";
-
-const SESSION_KEY = "clips-view-session-id";
+import { getViewerSessionId } from "@/lib/viewer-session";
 
-function getSessionId(): string {
-  if (typeof window === "undefined") return "server";
-  try {
-    let id = localStorage.getItem(SESSION_KEY);
-    if (!id) {
-      id =
-        "s-" +
-        Date.now().toString(36) +
-        "-" +
-        Math.random().toString(36).slice(2, 8);
-      localStorage.setItem(SESSION_KEY, id);
-    }
-    return id;
-  } catch {
-    return "s-" + Math.random().toString(36).slice(2, 8);
-  }
-}
+import { clampCompletionPct } from "../../shared/view-analytics";
 
 function createViewSessionId(recordingId: string): string {
   return [
@@ -118,7 +100,7 @@ export function useViewTracking(opts: UseViewTrackingOpts) {
           recordingId,
           kind: "view-start",
           timestampMs: 0,
-          sessionId: getSessionId(),
+          sessionId: getViewerSessionId(),
           viewSessionId: viewSessionRef.current,
           totalWatchMs: 0,
           completedPct: 0,
@@ -130,7 +112,7 @@ export function useViewTracking(opts: UseViewTrackingOpts) {
     }
 
     const video = videoEl;
-    const sessionId = getSessionId();
+    const sessionId = getViewerSessionId();
     viewSessionRef.current = createViewSessionId(recordingId);
     let progressTimer: ReturnType<typeof setInterval> | null = null;
 
@@ -243,7 +225,7 @@ export function useViewTracking(opts: UseViewTrackingOpts) {
         body: JSON.stringify({
           recordingId: recordingIdRef.current,
           kind: "cta-click",
-          sessionId: getSessionId(),
+          sessionId: getViewerSessionId(),
         }),
       }).catch(() => {});
     },
@@ -255,7 +237,7 @@ export function useViewTracking(opts: UseViewTrackingOpts) {
         body: JSON.stringify({
           recordingId: recordingIdRef.current,
           kind: "reaction",
-          sessionId: getSessionId(),
+          sessionId: getViewerSessionId(),
           payload: { emoji },
         }),
       }).catch(() => {});

package/corpus/templates/clips/app/i18n/en-US.ts

@@ -1274,6 +1274,10 @@ All notable user-facing changes to Clips are documented here. Open it any time f
     cameraOff: "Camera off",
     includeCameraAria: "Include camera in this recording",
     startRecording: "Start recording",
+    micOffConfirmTitle: "Record without a microphone?",
+    micOffConfirmDescription:
+      "Your mic is off, so this recording won't capture any audio. Turn it on before starting if you want narration.",
+    startWithoutMic: "Start anyway",
     uploadVideo: "Upload video",
     importLoom: "Import Loom",
     importing: "Importing...",

package/corpus/templates/clips/app/lib/playback-position.ts

@@ -0,0 +1,99 @@
+import {
+  callAction,
+  tryCallActionKeepalive,
+} from "@agent-native/core/client/hooks";
+
+import { getViewerSessionId } from "./viewer-session";
+
+export interface PlaybackPositionRecord {
+  recordingId: string;
+  viewerKey: string;
+  viewerEmail: string | null;
+  positionMs: number;
+  updatedAt: string | null;
+}
+
+interface PlaybackPositionActionResult {
+  playbackPosition: PlaybackPositionRecord | null;
+}
+
+function parsePlaybackPosition(payload: unknown): number | null {
+  if (
+    !payload ||
+    typeof payload !== "object" ||
+    !("playbackPosition" in payload)
+  ) {
+    throw new Error("Invalid playback position response");
+  }
+  const playbackPosition = (payload as { playbackPosition?: unknown })
+    .playbackPosition;
+  if (playbackPosition === null) return null;
+  if (typeof playbackPosition !== "object") {
+    throw new Error("Invalid playback position payload");
+  }
+  const positionMs = (playbackPosition as { positionMs?: unknown }).positionMs;
+  if (
+    typeof positionMs !== "number" ||
+    !Number.isFinite(positionMs) ||
+    positionMs < 0
+  ) {
+    throw new Error("Invalid playback position payload");
+  }
+  return positionMs;
+}
+
+export async function getPlaybackPosition(
+  recordingId: string,
+  options: {
+    sessionId?: string;
+    signal?: AbortSignal;
+  } = {},
+): Promise<number | null> {
+  const sessionId = options.sessionId ?? getViewerSessionId();
+  const payload = await callAction<PlaybackPositionActionResult>(
+    "get-playback-position",
+    { recordingId, sessionId },
+    { method: "GET", signal: options.signal },
+  );
+  return parsePlaybackPosition(payload);
+}
+
+export async function savePlaybackPosition(
+  recordingId: string,
+  positionMs: number,
+  options: {
+    sessionId?: string;
+    signal?: AbortSignal;
+    keepalive?: boolean;
+  } = {},
+): Promise<void> {
+  const sessionId = options.sessionId ?? getViewerSessionId();
+  const params = { recordingId, positionMs, sessionId };
+
+  if (options.keepalive) {
+    const request = tryCallActionKeepalive<PlaybackPositionActionResult>(
+      "save-playback-position",
+      params,
+      { signal: options.signal },
+    );
+    if (!request.accepted) {
+      throw new Error(
+        `Failed to save playback position during unload (${request.reason})`,
+      );
+    }
+    const payload = await request.completion;
+    if (parsePlaybackPosition(payload) === null) {
+      throw new Error("Invalid playback position payload");
+    }
+    return;
+  }
+
+  const payload = await callAction<PlaybackPositionActionResult>(
+    "save-playback-position",
+    params,
+    { signal: options.signal },
+  );
+  if (parsePlaybackPosition(payload) === null) {
+    throw new Error("Invalid playback position payload");
+  }
+}

package/corpus/templates/clips/app/lib/viewer-session.ts

@@ -0,0 +1,29 @@
+const VIEWER_SESSION_STORAGE_KEY = "clips-view-session-id";
+let inMemoryViewerSessionId: string | null = null;
+
+function fallbackSessionId(): string {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function getViewerSessionId(): string {
+  if (typeof window === "undefined") {
+    if (inMemoryViewerSessionId) return inMemoryViewerSessionId;
+    inMemoryViewerSessionId = fallbackSessionId();
+    return inMemoryViewerSessionId;
+  }
+
+  try {
+    const existing = window.localStorage.getItem(VIEWER_SESSION_STORAGE_KEY);
+    if (existing) return existing;
+    const next =
+      typeof window.crypto?.randomUUID === "function"
+        ? window.crypto.randomUUID()
+        : fallbackSessionId();
+    window.localStorage.setItem(VIEWER_SESSION_STORAGE_KEY, next);
+    return next;
+  } catch {
+    if (inMemoryViewerSessionId) return inMemoryViewerSessionId;
+    inMemoryViewerSessionId = fallbackSessionId();
+    return inMemoryViewerSessionId;
+  }
+}

package/corpus/templates/clips/changelog/2026-08-05-clip-buffering-now-uses-buffering-copy-after-playback.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-05
+---
+
+Clip buffering now shows buffering copy after playback starts.

package/corpus/templates/clips/changelog/2026-08-05-clips-remembers-your-playback-position-when-you-reopen-a-cli.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-05
+---
+
+Clips remembers your playback position when you reopen a clip.

package/corpus/templates/clips/desktop/package.json

@@ -18,6 +18,7 @@
     "test": "vitest --run"
   },
   "dependencies": {
+    "@radix-ui/react-alert-dialog": "^1.1.23",
     "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-tooltip": "^1.2.8",
     "@sentry/browser": "10.62.0",