@agent-native/core 0.137.8 → 0.139.0

package/corpus/templates/clips/agent-native.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "onboarding": {
+    "firstRun": {
+      "development": "off",
+      "production": "connect-and-integrations"
+    }
+  },
+  "doctor": {
+    "failOnBuild": false
+  }
+}

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/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/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/learnings.defaults.md

@@ -24,7 +24,7 @@
 ## Meetings & Dictate
 
 - When a user says **"meeting"** they mean a Meetings tab entry, not a Clips recording — _unless_ the recording is linked to a meeting (i.e. `recordings.meeting_id` is non-null), in which case both interpretations are valid and worth mentioning.
-- When suggesting how to enable transcript improvements (cleanup, summary, action items), **lead with Builder.io Connect** — it's the easiest path and requires no key. Mention a BYOK `GEMINI_API_KEY` only as a secondary fallback. The cleanup pipeline does not use direct Groq or OpenAI keys by default; it prefers Luna through Builder or OpenAI, with Gemini as the fallback.
+- When suggesting how to enable transcript improvements (cleanup, summary, action items), **lead with Builder.io Connect** — its free tier is available, it's the easiest path, and it requires no key. Mention a BYOK `GEMINI_API_KEY` only as a secondary fallback. The cleanup pipeline does not use direct Groq or OpenAI keys by default; it prefers Luna through Builder or OpenAI, with Gemini as the fallback.
 - **Per-attendee action items require attendees to actually speak in the recorded audio.** With mic + system audio capture (Meetings default) both sides are heard and tagged by source. With mic-only capture (and all Dictate dictations), remote attendees may be silent in the transcript — call this out before promising attendee-level coverage.
 
 ## Platform requirements

package/corpus/templates/clips/server/db/schema.ts

@@ -404,6 +404,24 @@ export const recordingViews = table("recording_views", {
   viewedAt: text("viewed_at").notNull().default(now()),
 });
 
+export const recordingPlaybackPositions = table(
+  "recording_playback_positions",
+  {
+    id: text("id").primaryKey(),
+    recordingId: text("recording_id").notNull(),
+    viewerKey: text("viewer_key").notNull(),
+    viewerEmail: text("viewer_email"),
+    positionMs: integer("position_ms").notNull().default(0),
+    updatedAt: text("updated_at").notNull().default(now()),
+    createdAt: text("created_at").notNull().default(now()),
+  },
+  (position) => ({
+    recordingPlaybackPositionUnique: uniqueIndex(
+      "recording_playback_positions_recording_viewer_key_unique_idx",
+    ).on(position.recordingId, position.viewerKey),
+  }),
+);
+
 // Agent views — one row per (clip, agent, time bucket). Deliberately separate
 // from `recording_viewers` / `recording_views` so no human-view count can ever
 // pick agents up by forgetting a filter: the human tables stay agent-free.