From 3a9113688c3b63017a71e18135c502363de14bda Mon Sep 17 00:00:00 2001
From: shivanshu11092003 <shivanshugupta1109@gmail.com>
Date: Fri, 31 Jul 2026 15:34:50 +0530
Subject: [PATCH 1/3] refactor(clips): render clean video filmstrip

---
 .../.agents/skills/video-editing/SKILL.md     |  31 ++
 templates/clips/AGENTS.md                     |   1 +
 templates/clips/actions/generate-filmstrip.ts | 154 +++++++++
 .../actions/get-recording-player-data.ts      |   6 +
 .../actions/lib/ensure-recording-filmstrip.ts | 242 ++++++++++++++
 .../actions/lib/ensure-seekable-video.ts      |  14 +-
 .../app/components/editor/editor-layout.tsx   | 164 ++++++++--
 .../clips/app/components/editor/waveform.tsx  | 299 +++++++++++++-----
 .../clips/app/lib/video-filmstrip.test.ts     |  31 ++
 templates/clips/app/lib/video-filmstrip.ts    | 262 +++++++++++++++
 ...hows-video-frames-behind-the-waveform-g.md |   6 +
 templates/clips/server/db/schema.ts           |  10 +
 .../server/lib/video-filmstrip-sprite.test.ts |  82 +++++
 .../server/lib/video-filmstrip-sprite.ts      | 207 ++++++++++++
 templates/clips/server/lib/video-remux.ts     |  17 +-
 templates/clips/server/plugins/db.ts          |   6 +
 16 files changed, 1428 insertions(+), 104 deletions(-)
 create mode 100644 templates/clips/actions/generate-filmstrip.ts
 create mode 100644 templates/clips/actions/lib/ensure-recording-filmstrip.ts
 create mode 100644 templates/clips/app/lib/video-filmstrip.test.ts
 create mode 100644 templates/clips/app/lib/video-filmstrip.ts
 create mode 100644 templates/clips/changelog/2026-07-31-editor-timeline-now-shows-video-frames-behind-the-waveform-g.md
 create mode 100644 templates/clips/server/lib/video-filmstrip-sprite.test.ts
 create mode 100644 templates/clips/server/lib/video-filmstrip-sprite.ts

diff --git a/templates/clips/.agents/skills/video-editing/SKILL.md b/templates/clips/.agents/skills/video-editing/SKILL.md
index 460fe6d786..5d9394c28f 100644
--- a/templates/clips/.agents/skills/video-editing/SKILL.md
+++ b/templates/clips/.agents/skills/video-editing/SKILL.md
@@ -229,6 +229,37 @@ downsamples to a 2000-point peaks array. Peaks are cached in
 recompute. The editor reads the cache first and falls back to computing only
 when the key is missing or corrupted.
 
+### Timeline filmstrip
+
+The trim track shows video frames behind the waveform. Two paths, and the order
+matters:
+
+1. **Sprite (preferred).** `generate-filmstrip` runs one ffmpeg pass
+   (`fps` → `scale` → `pad` → `tile`) into a single JPEG grid, uploads it, and
+   stores the URL plus grid geometry on the recording. The editor renders cells
+   with CSS `background-position` — one cached image request, no video decoding
+   in the browser.
+2. **Browser extraction (fallback).** `extractFilmstripThumbnails()` seeks a
+   detached `<video>` once per frame. Only used when there is no sprite, which
+   means hosts without ffmpeg and local/dev media the server cannot fetch.
+
+Three traps this design exists to avoid:
+
+- **Pass the proxied URL.** Frame extraction must use `getWaveformMediaUrl()`,
+  never `recording.videoUrl` — reading pixels back out of a cross-origin video
+  taints the canvas and `toDataURL` throws, so provider media silently yields no
+  filmstrip at all.
+- **Both paths sample cell midpoints,** not `0 … duration` endpoints. The strip
+  renders N equal cells, so cell `i` must show the middle of the slot it
+  occupies or every thumbnail sits up to half a cell from the time beneath it.
+- **Cell count comes from the geometry,** `trackWidth / (height × aspect)`, not
+  from the sprite's frame count. Rendering all 40 frames across an unzoomed
+  track makes each cell portrait, and `object-cover` then shows a narrow centre
+  slice of each frame instead of a recognisable thumbnail.
+
+The filmstrip never replaces the waveform — peaks still draw on top of a scrim,
+because frames say nothing about the audio.
+
 ### Keyboard shortcuts (editor scope)
 
 - **Space** — play / pause (even while focused in the editor area)
diff --git a/templates/clips/AGENTS.md b/templates/clips/AGENTS.md
index e2c8c253b6..97f796155d 100644
--- a/templates/clips/AGENTS.md
+++ b/templates/clips/AGENTS.md
@@ -92,6 +92,7 @@ Read the matching skill before deeper work in that area:
 | `move-recording` | Move `id` or `ids` to a folder or root |
 | `archive-`, `trash-`, `restore-recording` | Lifecycle |
 | `reprocess-recording` | Repair unseekable/frozen media |
+| `generate-filmstrip` | Editor timeline frame sprite; `all` backfills |
 | `request-transcript`, `cleanup-transcript` | Transcribe; `force`/`regenerate` |
 | `regenerate-title`, `-summary`, `-chapters` | AI metadata |
 | `trim-`, `split-recording`, `remove-silences`, `remove-filler-words` | Edits |
diff --git a/templates/clips/actions/generate-filmstrip.ts b/templates/clips/actions/generate-filmstrip.ts
new file mode 100644
index 0000000000..7a9359ebed
--- /dev/null
+++ b/templates/clips/actions/generate-filmstrip.ts
@@ -0,0 +1,154 @@
+/**
+ * Generate editor-timeline filmstrip sprites for stored recordings.
+ *
+ * The editor shows video frames behind the waveform so a trim range can be
+ * found visually. Generating them server-side with one ffmpeg pass replaces
+ * per-frame decoding in the browser, which cannot read cross-origin media at
+ * all and needs one seek per frame.
+ *
+ * Non-destructive and idempotent: a recording whose sprite already matches its
+ * current media is skipped, and any failure leaves the row untouched so the
+ * editor keeps its browser-side fallback.
+ *
+ * Usage:
+ *   pnpm action generate-filmstrip --id=<recordingId>
+ *   pnpm action generate-filmstrip --id=<recordingId> --force
+ *   pnpm action generate-filmstrip --all --limit=20
+ */
+
+import { defineAction } from "@agent-native/core";
+import { and, desc, eq, isNotNull, isNull } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  getCurrentOwnerEmail,
+  ownerEmailMatches,
+} from "../server/lib/recordings.js";
+import {
+  DEFAULT_FILMSTRIP_FRAME_COUNT,
+  MAX_FILMSTRIP_FRAME_COUNT,
+} from "../server/lib/video-filmstrip-sprite.js";
+import {
+  ensureRecordingFilmstrip,
+  type EnsureFilmstripResult,
+} from "./lib/ensure-recording-filmstrip.js";
+
+const MAX_TARGETS_PER_CALL = 50;
+const DEFAULT_ALL_LIMIT = 10;
+const cliBoolean = z.preprocess((value) => {
+  if (value === "true" || value === "1") return true;
+  if (value === "false" || value === "0") return false;
+  return value;
+}, z.boolean());
+
+export default defineAction({
+  description:
+    "Generate the editor timeline filmstrip (a sprite of evenly-spaced video frames) for one or more of the caller's recordings, so the editor can show frames behind the waveform without decoding video in the browser. Pass `id` for one clip, `ids` for several, or `all: true` to backfill clips that have no filmstrip yet. Recordings whose sprite already matches their current media are skipped unless `force` is true. Requires ffmpeg on the server; without it this reports `skipped-no-ffmpeg` and the editor falls back to browser-side extraction.",
+  schema: z.object({
+    id: z
+      .string()
+      .optional()
+      .describe("A single recording id to generate a filmstrip for."),
+    ids: z
+      .array(z.string())
+      .optional()
+      .describe("Several recording ids to process in one call."),
+    all: cliBoolean
+      .optional()
+      .describe(
+        "Backfill the caller's ready clips that have no filmstrip yet, most recent first, up to `limit`.",
+      ),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_TARGETS_PER_CALL)
+      .optional()
+      .describe(
+        `Max clips to process when using \`all\` (default ${DEFAULT_ALL_LIMIT}).`,
+      ),
+    frameCount: z.coerce
+      .number()
+      .int()
+      .min(4)
+      .max(MAX_FILMSTRIP_FRAME_COUNT)
+      .optional()
+      .describe(
+        `How many frames to sample across the clip (default ${DEFAULT_FILMSTRIP_FRAME_COUNT}). More frames means finer scrubbing detail and a larger sprite.`,
+      ),
+    force: cliBoolean
+      .optional()
+      .describe("Regenerate even when a current filmstrip already exists."),
+  }),
+  run: async (args) => {
+    const db = getDb();
+    const ownerEmail = getCurrentOwnerEmail();
+
+    let targetIds: string[] = [];
+    if (args.id) targetIds.push(args.id);
+    if (args.ids?.length) targetIds.push(...args.ids.filter(Boolean));
+
+    if (args.all) {
+      const rows = await db
+        .select({ id: schema.recordings.id })
+        .from(schema.recordings)
+        .where(
+          and(
+            ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+            eq(schema.recordings.status, "ready"),
+            isNotNull(schema.recordings.videoUrl),
+            // Backfill means "has none yet"; use `force` to redo existing ones.
+            isNull(schema.recordings.filmstripUrl),
+          ),
+        )
+        .orderBy(desc(schema.recordings.createdAt))
+        .limit(args.limit ?? DEFAULT_ALL_LIMIT);
+      targetIds.push(...rows.map((r) => r.id));
+    }
+
+    // De-dupe while preserving order, and bound the batch so one call can't run
+    // unboundedly under the hosted foreground budget.
+    targetIds = Array.from(new Set(targetIds)).slice(0, MAX_TARGETS_PER_CALL);
+
+    if (targetIds.length === 0) {
+      return {
+        ok: true,
+        processed: 0,
+        changed: 0,
+        results: [] as EnsureFilmstripResult[],
+        message:
+          "No recordings to process. Pass id / ids, or all: true to backfill clips without a filmstrip.",
+      };
+    }
+
+    const results: EnsureFilmstripResult[] = [];
+    for (const recordingId of targetIds) {
+      try {
+        results.push(
+          await ensureRecordingFilmstrip({
+            recordingId,
+            ownerEmail,
+            frameCount: args.frameCount,
+            force: Boolean(args.force),
+          }),
+        );
+      } catch (err) {
+        console.warn("[generate-filmstrip] failed for", recordingId, err);
+        results.push({
+          recordingId,
+          status: "failed-ffmpeg",
+          changed: false,
+          detail: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    const changed = results.filter((r) => r.changed).length;
+    console.log(
+      `Processed ${results.length} recording(s); ${changed} filmstrip(s) generated.`,
+    );
+
+    return { ok: true, processed: results.length, changed, results };
+  },
+});
diff --git a/templates/clips/actions/get-recording-player-data.ts b/templates/clips/actions/get-recording-player-data.ts
index 2c9d221c05..0592f64e2a 100644
--- a/templates/clips/actions/get-recording-player-data.ts
+++ b/templates/clips/actions/get-recording-player-data.ts
@@ -314,6 +314,12 @@ export default defineAction({
         description: rec.description,
         thumbnailUrl: rec.thumbnailUrl,
         animatedThumbnailUrl: rec.animatedThumbnailUrl,
+        filmstripUrl: rec.filmstripUrl ?? null,
+        filmstripFrameCount: rec.filmstripFrameCount ?? 0,
+        filmstripColumns: rec.filmstripColumns ?? 0,
+        filmstripRows: rec.filmstripRows ?? 0,
+        filmstripFrameWidth: rec.filmstripFrameWidth ?? 0,
+        filmstripFrameHeight: rec.filmstripFrameHeight ?? 0,
         sourceAppName: rec.sourceAppName,
         sourceWindowTitle: rec.sourceWindowTitle,
         durationMs: rec.durationMs,
diff --git a/templates/clips/actions/lib/ensure-recording-filmstrip.ts b/templates/clips/actions/lib/ensure-recording-filmstrip.ts
new file mode 100644
index 0000000000..448b5f547e
--- /dev/null
+++ b/templates/clips/actions/lib/ensure-recording-filmstrip.ts
@@ -0,0 +1,242 @@
+/**
+ * Generate and attach a timeline filmstrip sprite to a stored recording.
+ *
+ * This is the sibling of `ensure-seekable-video.ts` and follows the same shape:
+ * re-fetch the stored provider media, run one ffmpeg pass, upload the result,
+ * and point the recording row at it. Nothing here is destructive — a recording
+ * without a sprite still renders a filmstrip, because the editor falls back to
+ * extracting frames in the browser.
+ *
+ * Local/dev media (relative `/api/video/...` URLs backed by application_state)
+ * is skipped rather than special-cased: there is no absolute URL to fetch
+ * server-side, and the browser fallback already covers that environment.
+ */
+
+import {
+  readAppState,
+  writeAppState,
+} from "@agent-native/core/application-state";
+import { uploadFile } from "@agent-native/core/file-upload";
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "../../server/db/index.js";
+import { ownerEmailMatches } from "../../server/lib/recordings.js";
+import {
+  DEFAULT_FILMSTRIP_FRAME_COUNT,
+  generateFilmstripSprite,
+  type FilmstripSpriteGrid,
+} from "../../server/lib/video-filmstrip-sprite.js";
+import { isLoomRecordingSource } from "../../shared/loom.js";
+import {
+  fetchProviderBytes,
+  isRemoteProviderUrl,
+} from "./ensure-seekable-video.js";
+
+export type EnsureFilmstripStatus =
+  | "generated"
+  | "already-generated"
+  | "not-found"
+  | "skipped-not-ready"
+  | "skipped-no-media"
+  | "skipped-local-media"
+  | "skipped-no-duration"
+  | "skipped-no-ffmpeg"
+  | "skipped-fetch-failed"
+  | "skipped-too-large"
+  | "skipped-upload-failed"
+  | "failed-ffmpeg"
+  | "failed-empty-output";
+
+export interface EnsureFilmstripResult {
+  recordingId: string;
+  status: EnsureFilmstripStatus;
+  changed: boolean;
+  filmstripUrl?: string | null;
+  grid?: FilmstripSpriteGrid;
+  detail?: string;
+}
+
+/** application_state key recording which media a sprite was generated from. */
+export function filmstripMarkerKey(recordingId: string): string {
+  return `recording-filmstrip-${recordingId}`;
+}
+
+async function isAlreadyGenerated(
+  recordingId: string,
+  videoUrl: string,
+): Promise<boolean> {
+  const marker = await readAppState(filmstripMarkerKey(recordingId)).catch(
+    () => null,
+  );
+  return Boolean(
+    marker &&
+    typeof marker === "object" &&
+    (marker as { videoUrl?: unknown }).videoUrl === videoUrl,
+  );
+}
+
+/**
+ * Ensure one recording has a filmstrip sprite. Owner-scoped: pass the resolved
+ * owner email so the lookup can only touch that owner's rows.
+ */
+export async function ensureRecordingFilmstrip(params: {
+  recordingId: string;
+  ownerEmail: string;
+  frameCount?: number;
+  force?: boolean;
+}): Promise<EnsureFilmstripResult> {
+  const {
+    recordingId,
+    ownerEmail,
+    frameCount = DEFAULT_FILMSTRIP_FRAME_COUNT,
+    force = false,
+  } = params;
+  const db = getDb();
+
+  const [rec] = await db
+    .select({
+      id: schema.recordings.id,
+      status: schema.recordings.status,
+      videoUrl: schema.recordings.videoUrl,
+      durationMs: schema.recordings.durationMs,
+      filmstripUrl: schema.recordings.filmstripUrl,
+      sourceAppName: schema.recordings.sourceAppName,
+    })
+    .from(schema.recordings)
+    .where(
+      and(
+        eq(schema.recordings.id, recordingId),
+        ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+      ),
+    );
+
+  if (!rec) return { recordingId, status: "not-found", changed: false };
+  if (rec.status !== "ready") {
+    return { recordingId, status: "skipped-not-ready", changed: false };
+  }
+  if (isLoomRecordingSource(rec)) {
+    return { recordingId, status: "skipped-local-media", changed: false };
+  }
+  if (!rec.videoUrl) {
+    return { recordingId, status: "skipped-no-media", changed: false };
+  }
+  if (!isRemoteProviderUrl(rec.videoUrl)) {
+    return {
+      recordingId,
+      status: "skipped-local-media",
+      changed: false,
+      filmstripUrl: rec.filmstripUrl,
+    };
+  }
+  if (rec.durationMs <= 0) {
+    return { recordingId, status: "skipped-no-duration", changed: false };
+  }
+
+  if (
+    !force &&
+    rec.filmstripUrl &&
+    (await isAlreadyGenerated(recordingId, rec.videoUrl))
+  ) {
+    return {
+      recordingId,
+      status: "already-generated",
+      changed: false,
+      filmstripUrl: rec.filmstripUrl,
+    };
+  }
+
+  const fetched = await fetchProviderBytes(rec.videoUrl);
+  if (!fetched.ok) {
+    return { recordingId, status: fetched.reason, changed: false };
+  }
+
+  const sprite = await generateFilmstripSprite({
+    mediaBytes: fetched.bytes,
+    durationMs: rec.durationMs,
+    frameCount,
+  });
+
+  if (sprite.status !== "generated" || !sprite.sprite) {
+    return {
+      recordingId,
+      status: sprite.status,
+      changed: false,
+      filmstripUrl: rec.filmstripUrl,
+      detail: sprite.detail,
+    };
+  }
+
+  const upload = await uploadFile({
+    data: sprite.sprite.bytes,
+    filename: `${recordingId}-filmstrip-${Date.now()}.jpg`,
+    mimeType: "image/jpeg",
+    ownerEmail,
+    stableUrl: true,
+    recordAsset: false,
+  }).catch((err) => {
+    console.warn("[ensure-recording-filmstrip] sprite upload failed", {
+      recordingId,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  });
+
+  if (!upload?.url) {
+    return {
+      recordingId,
+      status: "skipped-upload-failed",
+      changed: false,
+      filmstripUrl: rec.filmstripUrl,
+    };
+  }
+
+  const { grid } = sprite.sprite;
+  const updated = await db
+    .update(schema.recordings)
+    .set({
+      filmstripUrl: upload.url,
+      filmstripFrameCount: grid.frameCount,
+      filmstripColumns: grid.columns,
+      filmstripRows: grid.rows,
+      filmstripFrameWidth: grid.frameWidth,
+      filmstripFrameHeight: grid.frameHeight,
+      updatedAt: new Date().toISOString(),
+    })
+    .where(
+      and(
+        eq(schema.recordings.id, recordingId),
+        ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+        // Don't attach a sprite generated from media the row no longer points at.
+        eq(schema.recordings.videoUrl, rec.videoUrl),
+      ),
+    )
+    .returning({
+      id: schema.recordings.id,
+      filmstripUrl: schema.recordings.filmstripUrl,
+    });
+
+  if (updated.length !== 1 || updated[0]?.filmstripUrl !== upload.url) {
+    return {
+      recordingId,
+      status: "skipped-upload-failed",
+      changed: false,
+      filmstripUrl: rec.filmstripUrl,
+      detail: "Recording changed while the filmstrip sprite was uploading.",
+    };
+  }
+
+  await writeAppState(filmstripMarkerKey(recordingId), {
+    recordingId,
+    videoUrl: rec.videoUrl,
+    at: new Date().toISOString(),
+  });
+  await writeAppState("refresh-signal", { ts: Date.now() });
+
+  return {
+    recordingId,
+    status: "generated",
+    changed: true,
+    filmstripUrl: upload.url,
+    grid,
+  };
+}
diff --git a/templates/clips/actions/lib/ensure-seekable-video.ts b/templates/clips/actions/lib/ensure-seekable-video.ts
index 2b1ae92ef7..c62d237ed2 100644
--- a/templates/clips/actions/lib/ensure-seekable-video.ts
+++ b/templates/clips/actions/lib/ensure-seekable-video.ts
@@ -95,14 +95,22 @@ async function isAlreadyMarked(
   );
 }
 
-function isRemoteProviderUrl(videoUrl: string | null | undefined): boolean {
+export function isRemoteProviderUrl(
+  videoUrl: string | null | undefined,
+): boolean {
   return typeof videoUrl === "string" && /^https:\/\//i.test(videoUrl.trim());
 }
 
-async function fetchProviderBytes(
+/**
+ * Download stored provider media for server-side processing. Shared with the
+ * filmstrip sprite path — both need the same size cap and timeout, and both
+ * report the same two failure reasons rather than an empty buffer.
+ */
+export async function fetchProviderBytes(
   videoUrl: string,
 ): Promise<
-  { ok: true; bytes: Uint8Array } | { ok: false; reason: EnsureSeekableStatus }
+  | { ok: true; bytes: Uint8Array }
+  | { ok: false; reason: "skipped-fetch-failed" | "skipped-too-large" }
 > {
   const controller = new AbortController();
   const timeout = setTimeout(
diff --git a/templates/clips/app/components/editor/editor-layout.tsx b/templates/clips/app/components/editor/editor-layout.tsx
index d3ecceb113..b8de378626 100644
--- a/templates/clips/app/components/editor/editor-layout.tsx
+++ b/templates/clips/app/components/editor/editor-layout.tsx
@@ -58,6 +58,11 @@ import {
   type EditsJson,
 } from "@/lib/timestamp-mapping";
 import { cn } from "@/lib/utils";
+import {
+  extractFilmstripThumbnails,
+  type FilmstripFrame,
+  type FilmstripSprite,
+} from "@/lib/video-filmstrip";
 import { computePeaks, type WaveformPeaks } from "@/lib/waveform-peaks";
 
 import { ChaptersEditor } from "./chapters-editor";
@@ -76,7 +81,7 @@ export interface EditorLayoutProps {
   className?: string;
 }
 
-const WAVEFORM_HEIGHT = 120;
+const WAVEFORM_HEIGHT = 100;
 const MIN_TIMELINE_ZOOM = 1;
 const MAX_TIMELINE_ZOOM = 50;
 
@@ -244,10 +249,20 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
     return () => ro.disconnect();
   }, []);
 
-  const totalWidth = Math.max(
-    viewportWidth,
-    Math.floor(viewportWidth * Math.max(1, zoom)),
-  );
+  const baseTrackWidth = useMemo(() => {
+    if (durationMs <= 0 || viewportWidth <= 0) return viewportWidth;
+    const durationSec = durationMs / 1000;
+    // Scale timeline track width proportionally with duration so long videos scale & scroll
+    const durationScaledPx = Math.round(durationSec * 14);
+    return Math.max(viewportWidth, durationScaledPx);
+  }, [durationMs, viewportWidth]);
+
+  const totalWidth = useMemo(() => {
+    return Math.max(
+      baseTrackWidth,
+      Math.floor(baseTrackWidth * Math.max(1, zoom)),
+    );
+  }, [baseTrackWidth, zoom]);
 
   const calculateAnchoredScrollLeft = useCallback(
     (
@@ -255,8 +270,8 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
       anchor?: { anchorRatio?: number; viewportX?: number },
     ) => {
       const nextTotalWidth = Math.max(
-        viewportWidth,
-        Math.floor(viewportWidth * Math.max(1, nextZoom)),
+        baseTrackWidth,
+        Math.floor(baseTrackWidth * Math.max(1, nextZoom)),
       );
       const maxScrollLeft = Math.max(0, nextTotalWidth - viewportWidth);
       const anchorMs = selectionRange
@@ -277,7 +292,7 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
       const anchorX = anchorRatio * nextTotalWidth;
       return Math.max(0, Math.min(maxScrollLeft, anchorX - viewportX));
     },
-    [durationMs, playheadMs, selectionRange, viewportWidth],
+    [baseTrackWidth, durationMs, playheadMs, selectionRange, viewportWidth],
   );
 
   const setAnchoredZoom = useCallback(
@@ -319,8 +334,8 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
       viewportX: number,
     ) => {
       const sourceTotalWidth = Math.max(
-        viewportWidth,
-        Math.floor(viewportWidth * Math.max(1, sourceZoom)),
+        baseTrackWidth,
+        Math.floor(baseTrackWidth * Math.max(1, sourceZoom)),
       );
       return Math.max(
         0,
@@ -390,7 +405,7 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
       el.removeEventListener("gesturechange", handleGestureChange);
       el.removeEventListener("gestureend", handleGestureEnd);
     };
-  }, [scrollLeft, setAnchoredZoom, viewportWidth, zoom]);
+  }, [baseTrackWidth, scrollLeft, setAnchoredZoom, viewportWidth, zoom]);
 
   // Sync the <video> to play state.
   useEffect(() => {
@@ -498,6 +513,85 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
     };
   }, [recordingId, waveformMediaUrl]);
 
+  // Filmstrip drawn behind the waveform. A server-generated sprite is one
+  // cached image request and is preferred; browser extraction is the fallback
+  // for hosts without ffmpeg and for local/dev media the server can't fetch.
+  const filmstripSprite = useMemo<FilmstripSprite | null>(() => {
+    const url = recording?.filmstripUrl;
+    const frameCount = Number(recording?.filmstripFrameCount ?? 0);
+    const columns = Number(recording?.filmstripColumns ?? 0);
+    if (!url || frameCount <= 0 || columns <= 0) return null;
+    return {
+      url,
+      frameCount,
+      columns,
+      rows: Number(recording?.filmstripRows ?? 1) || 1,
+      frameWidth: Number(recording?.filmstripFrameWidth ?? 0) || 160,
+      frameHeight: Number(recording?.filmstripFrameHeight ?? 0) || 90,
+    };
+  }, [
+    recording?.filmstripUrl,
+    recording?.filmstripFrameCount,
+    recording?.filmstripColumns,
+    recording?.filmstripRows,
+    recording?.filmstripFrameWidth,
+    recording?.filmstripFrameHeight,
+  ]);
+
+  const [filmstripFrames, setFilmstripFrames] = useState<FilmstripFrame[]>([]);
+
+  // Cells should read as video frames, so aim for one per `height * aspect` of
+  // track. Bucketed so ordinary window resizing does not re-extract, and based
+  // on the unzoomed width — a zoomed fallback strip stretches, which is one of
+  // the reasons the server sprite is the preferred path.
+  const filmstripFrameCount = useMemo(() => {
+    const bucketedWidth = Math.max(240, Math.round(viewportWidth / 120) * 120);
+    const cellWidth = WAVEFORM_HEIGHT * (16 / 9);
+    return Math.min(48, Math.max(6, Math.round(bucketedWidth / cellWidth)));
+  }, [viewportWidth]);
+
+  useEffect(() => {
+    // A sprite already covers the whole clip — don't decode the video again.
+    if (filmstripSprite) return;
+    if (!waveformMediaUrl || durationMs <= 0) return;
+    let cancelled = false;
+    // `waveformMediaUrl`, not `videoUrl`: reading frames back out of a
+    // cross-origin video taints the canvas, so provider media must come
+    // through the same-origin proxy first.
+    extractFilmstripThumbnails({
+      videoUrl: waveformMediaUrl,
+      durationMs,
+      frameCount: filmstripFrameCount,
+    })
+      .then((result) => {
+        if (cancelled) return;
+        if (result.status !== "ok") {
+          console.warn("[editor] filmstrip extraction failed", {
+            recordingId,
+            status: result.status,
+            detail: result.detail,
+          });
+        }
+        setFilmstripFrames(result.frames);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        console.warn("[editor] filmstrip extraction threw", {
+          recordingId,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    recordingId,
+    waveformMediaUrl,
+    durationMs,
+    filmstripFrameCount,
+    filmstripSprite,
+  ]);
+
   // --- actions ------------------------------------------------------------
   const trim = useActionMutation("trim-recording");
   const split = useActionMutation("split-recording");
@@ -550,12 +644,22 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
       ) {
         e.preventDefault();
         undo.mutate({ recordingId });
-      } else if (e.key.toLowerCase() === "i") {
+      } else if (
+        !e.ctrlKey &&
+        !e.metaKey &&
+        !e.altKey &&
+        e.key.toLowerCase() === "i"
+      ) {
         setSelectionRange((r) => ({
           startMs: playheadMs,
           endMs: r?.endMs && r.endMs > playheadMs ? r.endMs : playheadMs + 1000,
         }));
-      } else if (e.key.toLowerCase() === "o") {
+      } else if (
+        !e.ctrlKey &&
+        !e.metaKey &&
+        !e.altKey &&
+        e.key.toLowerCase() === "o"
+      ) {
         setSelectionRange((r) => ({
           startMs:
             r?.startMs && r.startMs < playheadMs
@@ -563,7 +667,12 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
               : Math.max(0, playheadMs - 1000),
           endMs: playheadMs,
         }));
-      } else if (e.key.toLowerCase() === "x") {
+      } else if (
+        !e.ctrlKey &&
+        !e.metaKey &&
+        !e.altKey &&
+        e.key.toLowerCase() === "x"
+      ) {
         // Cut: trim the current selection range
         const range = selectionRange;
         if (range) {
@@ -582,7 +691,12 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
               toast.error(err?.message ?? t("editorLayout.cutFailed")),
             );
         }
-      } else if (e.key.toLowerCase() === "s") {
+      } else if (
+        !e.ctrlKey &&
+        !e.metaKey &&
+        !e.altKey &&
+        e.key.toLowerCase() === "s"
+      ) {
         // Split at playhead
         e.preventDefault();
         split
@@ -693,6 +807,8 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
             <div className="relative min-w-0 overflow-hidden">
               <Waveform
                 peaks={peaks}
+                sprite={filmstripSprite}
+                frames={filmstripFrames}
                 width={viewportWidth}
                 height={WAVEFORM_HEIGHT}
                 zoom={zoom}
@@ -717,14 +833,16 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
                     transform: `translateX(${-scrollLeft}px)`,
                   }}
                 >
-                  <TrimHandles
-                    width={totalWidth}
-                    height={WAVEFORM_HEIGHT}
-                    value={effectiveSelection}
-                    onChange={setSelectionRange}
-                    durationMs={durationMs}
-                    splitPoints={splitPoints}
-                  />
+                  {(selectionRange || !playing) && (
+                    <TrimHandles
+                      width={totalWidth}
+                      height={WAVEFORM_HEIGHT}
+                      value={effectiveSelection}
+                      onChange={setSelectionRange}
+                      durationMs={durationMs}
+                      splitPoints={splitPoints}
+                    />
+                  )}
                 </div>
               </div>
             </div>
diff --git a/templates/clips/app/components/editor/waveform.tsx b/templates/clips/app/components/editor/waveform.tsx
index ce2bceb318..7092df72b9 100644
--- a/templates/clips/app/components/editor/waveform.tsx
+++ b/templates/clips/app/components/editor/waveform.tsx
@@ -1,11 +1,16 @@
 import { useEffect, useMemo, useRef } from "react";
 
 import { cn } from "@/lib/utils";
+import type { FilmstripFrame, FilmstripSprite } from "@/lib/video-filmstrip";
 import type { WaveformPeaks } from "@/lib/waveform-peaks";
 
 export interface WaveformProps {
   /** Peaks computed via `computePeaks()`. */
   peaks: WaveformPeaks | null;
+  /** Server-generated filmstrip sprite. Preferred over `frames` when present. */
+  sprite?: FilmstripSprite | null;
+  /** Browser-extracted frame thumbnails — the fallback when there's no sprite. */
+  frames?: FilmstripFrame[];
   /** Width in px of the viewport (the scroll container). */
   width: number;
   /** Height in px. */
@@ -49,10 +54,11 @@ const getBrandColorAlpha = (alpha: number) => {
   return v ? `hsl(${v} / ${alpha})` : `rgba(15, 23, 42, ${alpha})`;
 };
 
-const getWaveColor = () => getBrandColorAlpha(0.55);
-const getWaveBg = () => getBrandColorAlpha(0.12);
-const EXCLUDED_FILL = "rgba(15, 23, 42, 0.72)";
-const EXCLUDED_STROKE = "rgba(148, 163, 184, 0.45)";
+const getWaveColor = () => getBrandColorAlpha(0.85);
+const getWaveBg = () => getBrandColorAlpha(0.08);
+const EXCLUDED_FILL = "rgba(15, 23, 42, 0.65)";
+const EXCLUDED_STROKE = "rgba(148, 163, 184, 0.4)";
+const EMPTY_FRAMES: FilmstripFrame[] = [];
 const VISUAL_TARGET_PEAK = 0.78;
 const VISUAL_MAX_GAIN = 24;
 const VISUAL_GAIN_PERCENTILE = 0.95;
@@ -80,9 +86,28 @@ function computeVisualGain(samples: number[]): number {
   return Math.min(VISUAL_MAX_GAIN, VISUAL_TARGET_PEAK / reference);
 }
 
+function drawPillBar(
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+) {
+  const radius = Math.min(width / 2, height / 2);
+  ctx.beginPath();
+  if (typeof ctx.roundRect === "function") {
+    ctx.roundRect(x, y, width, height, radius);
+  } else {
+    ctx.rect(x, y, width, height);
+  }
+  ctx.fill();
+}
+
 /** Canvas-rendered waveform. Supports up to 50x zoom with horizontal scroll. */
 export function Waveform({
   peaks,
+  sprite,
+  frames = EMPTY_FRAMES,
   width,
   height = 120,
   zoom = 1,
@@ -100,8 +125,48 @@ export function Waveform({
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
   const scrollRef = useRef<HTMLDivElement | null>(null);
 
-  // The total drawable width (scrolls horizontally). zoom=1 fits exactly.
-  const totalWidth = Math.max(width, Math.floor(width * Math.max(1, zoom)));
+  const baseTrackWidth = useMemo(() => {
+    if (durationMs <= 0 || width <= 0) return width;
+    const durationSec = durationMs / 1000;
+    // Scale timeline track width proportionally with duration so long videos don't squish
+    const durationScaledPx = Math.round(durationSec * 14);
+    return Math.max(width, durationScaledPx);
+  }, [durationMs, width]);
+
+  // The total drawable width (scrolls horizontally). Scales with duration and zoom.
+  const totalWidth = Math.max(
+    baseTrackWidth,
+    Math.floor(baseTrackWidth * Math.max(1, zoom)),
+  );
+
+  // A sprite has a fixed frame count, but the track needs however many cells
+  // fit at the video's aspect — otherwise cells go portrait and each thumbnail
+  // shows a narrow centre slice. Pick the cell count from the geometry, then
+  // map each cell to the sprite frame nearest its midpoint.
+  const spriteCells = useMemo(() => {
+    if (!sprite?.url || sprite.frameCount <= 0 || sprite.columns <= 0)
+      return [];
+    const aspect =
+      sprite.frameHeight > 0 ? sprite.frameWidth / sprite.frameHeight : 16 / 9;
+    const cellWidth = Math.max(24, height * aspect);
+    const count = Math.max(
+      1,
+      Math.min(sprite.frameCount, Math.round(totalWidth / cellWidth)),
+    );
+    return Array.from({ length: count }, (_, i) => {
+      const frame = Math.min(
+        sprite.frameCount - 1,
+        Math.floor(((i + 0.5) * sprite.frameCount) / count),
+      );
+      return {
+        key: `${i}-${frame}`,
+        column: frame % sprite.columns,
+        row: Math.floor(frame / sprite.columns),
+      };
+    });
+  }, [sprite, totalWidth, height]);
+
+  const hasImagery = spriteCells.length > 0 || frames.length > 0;
 
   useEffect(() => {
     const el = scrollRef.current;
@@ -112,7 +177,7 @@ export function Waveform({
     }
   }, [scrollLeft, totalWidth, width]);
 
-  // Re-draw whenever peaks, size, or excluded ranges change.
+  // Re-draw whenever peaks, imagery, size, or excluded ranges change.
   useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -126,74 +191,73 @@ export function Waveform({
     if (!ctx) return;
     ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
 
-    // Background
-    ctx.fillStyle = getWaveBg();
-    ctx.fillRect(0, 0, totalWidth, height);
-
     const hasPeaks = Boolean(
       peaks?.bucketCount &&
       peaks.peaks.some((value) => Math.abs(value) > 0.0001),
     );
 
-    if (peaks && hasPeaks) {
-      // Map each x pixel to a bucket range. Use a visual-only auto-gain so
-      // quiet microphone recordings still read clearly in the trim track.
-      const mid = height / 2;
-      const visualGain = computeVisualGain(peaks.peaks);
-      ctx.strokeStyle = getWaveColor();
-      ctx.lineWidth = 1;
-      ctx.beginPath();
-      const bucketsPerPx = peaks.bucketCount / totalWidth;
-      for (let x = 0; x < totalWidth; x++) {
-        const startBucket = Math.floor(x * bucketsPerPx);
-        const endBucket = Math.max(
-          startBucket + 1,
-          Math.floor((x + 1) * bucketsPerPx),
-        );
-        let min = 0;
-        let max = 0;
-        for (let b = startBucket; b < endBucket && b < peaks.bucketCount; b++) {
-          const lo = peaks.peaks[b * 2];
-          const hi = peaks.peaks[b * 2 + 1];
-          if (lo < min) min = lo;
-          if (hi > max) max = hi;
-        }
-        let topY = mid + clampSample(min * visualGain) * mid * 0.95;
-        let botY = mid + clampSample(max * visualGain) * mid * 0.95;
-        if (
-          Math.max(Math.abs(min), Math.abs(max)) > VISUAL_SILENCE_FLOOR &&
-          botY - topY < 2
-        ) {
-          const centerY = (topY + botY) / 2;
-          topY = centerY - 1;
-          botY = centerY + 1;
+    // Canvas background & audio visualization
+    ctx.clearRect(0, 0, totalWidth, height);
+    if (!hasImagery) {
+      ctx.fillStyle = getWaveBg();
+      ctx.fillRect(0, 0, totalWidth, height);
+
+      const barWidth = 3;
+      const barGap = 1.5;
+      const step = barWidth + barGap;
+      const barCount = Math.floor(totalWidth / step);
+      const maxWaveHeight = Math.min(height * 0.5, 52);
+      const minBarHeight = 3;
+      const midY = height / 2;
+
+      if (peaks && hasPeaks) {
+        const visualGain = computeVisualGain(peaks.peaks);
+        const bucketsPerBar = peaks.bucketCount / barCount;
+
+        for (let i = 0; i < barCount; i++) {
+          const x = i * step;
+          const startBucket = Math.floor(i * bucketsPerBar);
+          const endBucket = Math.max(
+            startBucket + 1,
+            Math.floor((i + 1) * bucketsPerBar),
+          );
+
+          let maxAmp = 0;
+          for (let b = startBucket; b < endBucket && b < peaks.bucketCount; b++) {
+            const lo = Math.abs(peaks.peaks[b * 2] ?? 0);
+            const hi = Math.abs(peaks.peaks[b * 2 + 1] ?? 0);
+            if (lo > maxAmp) maxAmp = lo;
+            if (hi > maxAmp) maxAmp = hi;
+          }
+
+          const scaledAmp = clampSample(maxAmp * visualGain);
+          const barHeight = Math.max(minBarHeight, scaledAmp * maxWaveHeight);
+          const topY = midY - barHeight / 2;
+
+          ctx.fillStyle =
+            maxAmp > VISUAL_SILENCE_FLOOR
+              ? getWaveColor()
+              : getBrandColorAlpha(0.2);
+
+          drawPillBar(ctx, x, topY, barWidth, barHeight);
         }
-        ctx.moveTo(x + 0.5, topY);
-        ctx.lineTo(x + 0.5, botY);
-      }
-      ctx.stroke();
-    } else {
-      const mid = height / 2;
-      ctx.strokeStyle = getBrandColorAlpha(0.2);
-      ctx.lineWidth = 1;
-      ctx.setLineDash([3, 6]);
-      ctx.beginPath();
-      ctx.moveTo(0, mid);
-      ctx.lineTo(totalWidth, mid);
-      ctx.stroke();
-      ctx.setLineDash([]);
-
-      if (activityRanges.length) {
-        const blockHeight = Math.max(18, Math.min(32, height * 0.32));
-        const top = mid - blockHeight / 2;
-        ctx.fillStyle = getBrandColorAlpha(0.24);
-        for (const range of activityRanges) {
-          const xStart =
-            (Math.max(0, range.startMs) / Math.max(durationMs, 1)) * totalWidth;
-          const xEnd =
-            (Math.min(durationMs, range.endMs) / Math.max(durationMs, 1)) *
-            totalWidth;
-          ctx.fillRect(xStart, top, Math.max(2, xEnd - xStart), blockHeight);
+      } else {
+        // Idle state without imagery
+        for (let i = 0; i < barCount; i++) {
+          const x = i * step;
+          const barMs = (i / Math.max(1, barCount)) * durationMs;
+          const inActivity = activityRanges.some(
+            (r) => barMs >= r.startMs && barMs <= r.endMs,
+          );
+
+          const barHeight = inActivity ? 12 : minBarHeight;
+          const topY = midY - barHeight / 2;
+
+          ctx.fillStyle = inActivity
+            ? getWaveColor()
+            : getBrandColorAlpha(0.2);
+
+          drawPillBar(ctx, x, topY, barWidth, barHeight);
         }
       }
     }
@@ -248,6 +312,7 @@ export function Waveform({
     }
   }, [
     peaks,
+    hasImagery,
     totalWidth,
     height,
     excludedRanges,
@@ -257,15 +322,56 @@ export function Waveform({
     activityRanges,
   ]);
 
-  const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {
+  const scrubRef = useRef<{ pointerId: number; startX: number } | null>(null);
+
+  const seekToEvent = (
+    e: React.PointerEvent<HTMLDivElement> | React.MouseEvent<HTMLDivElement>,
+  ) => {
     if (!onSeek) return;
-    const rect = e.currentTarget.getBoundingClientRect();
-    const scroll = scrollRef.current?.scrollLeft ?? 0;
+    const el = scrollRef.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const scroll = el.scrollLeft;
     const x = e.clientX - rect.left + scroll;
     const ms = Math.max(0, Math.min(durationMs, (x / totalWidth) * durationMs));
     onSeek(ms);
   };
 
+  const handlePointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+    if (!onSeek || e.button !== 0) return;
+    const el = scrollRef.current;
+    if (!el) return;
+    // A pointerdown on this element's own horizontal scrollbar still targets
+    // the element. Capturing there would turn the drag that pans a zoomed
+    // track into a scrub, leaving no way to reach the rest of the timeline.
+    if (e.clientY - el.getBoundingClientRect().top >= el.clientHeight) return;
+    scrubRef.current = { pointerId: e.pointerId, startX: e.clientX };
+    // Touch keeps the browser's native pan; a tap still seeks on pointerup.
+    if (e.pointerType === "touch") return;
+    el.setPointerCapture(e.pointerId);
+    seekToEvent(e);
+  };
+
+  const handlePointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
+    const scrub = scrubRef.current;
+    if (!scrub || scrub.pointerId !== e.pointerId) return;
+    if (e.pointerType === "touch") return;
+    seekToEvent(e);
+  };
+
+  const handlePointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
+    const scrub = scrubRef.current;
+    if (!scrub || scrub.pointerId !== e.pointerId) return;
+    scrubRef.current = null;
+    const el = scrollRef.current;
+    if (el?.hasPointerCapture(e.pointerId)) {
+      el.releasePointerCapture(e.pointerId);
+    }
+    if (e.pointerType === "touch" && Math.abs(e.clientX - scrub.startX) < 8) {
+      seekToEvent(e);
+    }
+  };
+
   const handleScroll = () => {
     const el = scrollRef.current;
     if (!el) return;
@@ -287,10 +393,55 @@ export function Waveform({
       )}
       style={{ width, height }}
       onScroll={handleScroll}
-      onClick={handleClick}
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+      onPointerCancel={handlePointerUp}
     >
       <div className="relative" style={{ width: totalWidth, height }}>
-        <canvas ref={canvasRef} />
+        {spriteCells.length > 0 && sprite ? (
+          <div className="absolute inset-0 flex overflow-hidden pointer-events-none">
+            {spriteCells.map((cell) => (
+              <div
+                key={cell.key}
+                className="h-full animate-in fade-in duration-500"
+                style={{
+                  width: `${100 / spriteCells.length}%`,
+                  backgroundImage: `url(${sprite.url})`,
+                  // Percentage sizing maps one grid cell onto one element box,
+                  // so percentage positioning addresses cells exactly.
+                  backgroundSize: `${sprite.columns * 100}% ${sprite.rows * 100}%`,
+                  backgroundPosition: `${
+                    sprite.columns > 1
+                      ? (cell.column * 100) / (sprite.columns - 1)
+                      : 0
+                  }% ${
+                    sprite.rows > 1 ? (cell.row * 100) / (sprite.rows - 1) : 0
+                  }%`,
+                  backgroundRepeat: "no-repeat",
+                }}
+              />
+            ))}
+          </div>
+        ) : (
+          frames.length > 0 && (
+            <div className="absolute inset-0 flex overflow-hidden pointer-events-none">
+              {frames.map((frame) => (
+                <img
+                  key={frame.timeMs}
+                  src={frame.dataUrl}
+                  alt=""
+                  className="h-full object-cover animate-in fade-in duration-500"
+                  style={{ width: `${100 / frames.length}%` }}
+                />
+              ))}
+            </div>
+          )
+        )}
+        <canvas
+          ref={canvasRef}
+          className="absolute inset-0 pointer-events-none"
+        />
         <div
           className="absolute top-0 h-full w-[2px] pointer-events-none"
           style={{
diff --git a/templates/clips/app/lib/video-filmstrip.test.ts b/templates/clips/app/lib/video-filmstrip.test.ts
new file mode 100644
index 0000000000..133ddefa9f
--- /dev/null
+++ b/templates/clips/app/lib/video-filmstrip.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+
+import { calculateFilmstripTimestamps } from "./video-filmstrip";
+
+describe("calculateFilmstripTimestamps", () => {
+  it("samples the midpoint of each cell so frames line up with their slot", () => {
+    // 5 cells of 2000ms across a 10s clip -> midpoints, not 0..10000 endpoints.
+    expect(calculateFilmstripTimestamps(10000, 5)).toEqual([
+      1000, 3000, 5000, 7000, 9000,
+    ]);
+  });
+
+  it("returns one timestamp per requested frame", () => {
+    expect(calculateFilmstripTimestamps(60_000, 24)).toHaveLength(24);
+  });
+
+  it("never samples past the end of the clip", () => {
+    const timestamps = calculateFilmstripTimestamps(5000, 8);
+    for (const ms of timestamps) {
+      expect(ms).toBeLessThanOrEqual(5000);
+      expect(ms).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it("handles edge cases gracefully", () => {
+    expect(calculateFilmstripTimestamps(0, 5)).toEqual([0]);
+    expect(calculateFilmstripTimestamps(1000, 0)).toEqual([0]);
+    // A single cell spans the whole clip, so its midpoint is the middle.
+    expect(calculateFilmstripTimestamps(1000, 1)).toEqual([500]);
+  });
+});
diff --git a/templates/clips/app/lib/video-filmstrip.ts b/templates/clips/app/lib/video-filmstrip.ts
new file mode 100644
index 0000000000..6f6ddc6c96
--- /dev/null
+++ b/templates/clips/app/lib/video-filmstrip.ts
@@ -0,0 +1,262 @@
+/**
+ * Client-side video filmstrip frame extraction — the fallback for when the
+ * server has no ffmpeg to generate a sprite (see
+ * `server/lib/video-filmstrip-sprite.ts`, which is the preferred path).
+ *
+ * Two constraints this file exists to hold:
+ *
+ * 1. Sampling is at cell midpoints, not endpoints. The strip renders N equal
+ *    cells spanning the clip, so cell `i` must show the frame at its midpoint;
+ *    endpoint sampling puts every thumbnail up to half a cell away from the
+ *    time underneath it.
+ * 2. A blank frame is kept, not dropped. Dropping desynchronises every cell
+ *    after it, and a genuinely black moment is indistinguishable from a seek
+ *    that never decoded. All-blank is reported as a failure instead.
+ *
+ * The caller must pass a same-origin URL (`getWaveformMediaUrl`). Reading
+ * pixels back out of a cross-origin video taints the canvas and `toDataURL`
+ * throws, so a provider URL must be proxied before it reaches this function.
+ */
+
+import { canvasHasVisibleContent } from "./thumbnail-capture";
+
+export interface FilmstripFrame {
+  timeMs: number;
+  dataUrl: string;
+  /** Probed as blank. Kept so cells stay aligned with their time slots. */
+  blank: boolean;
+}
+
+/**
+ * A server-generated filmstrip sprite: one image holding `frameCount` frames in
+ * a `columns` x `rows` grid, each cell `frameWidth` x `frameHeight`. Frames are
+ * cell midpoints across the clip, matching this module's sampling.
+ */
+export interface FilmstripSprite {
+  url: string;
+  frameCount: number;
+  columns: number;
+  rows: number;
+  frameWidth: number;
+  frameHeight: number;
+}
+
+export type FilmstripStatus =
+  | "ok"
+  | "skipped-no-window"
+  | "skipped-no-media"
+  | "failed-metadata"
+  | "failed-canvas"
+  | "failed-all-frames-blank";
+
+export interface FilmstripResult {
+  status: FilmstripStatus;
+  frames: FilmstripFrame[];
+  /** Intrinsic aspect (w/h) so callers can size cells to match the video. */
+  aspectRatio: number | null;
+  detail?: string;
+}
+
+export interface ExtractFilmstripOptions {
+  videoUrl: string;
+  durationMs: number;
+  frameCount?: number;
+  frameWidth?: number;
+  quality?: number;
+}
+
+const METADATA_TIMEOUT_MS = 10_000;
+const SEEK_TIMEOUT_MS = 2_000;
+const FRAME_PRESENT_TIMEOUT_MS = 120;
+
+/**
+ * Midpoints of `frameCount` equal cells spanning `durationMs`. See the file
+ * header for why these are midpoints rather than `0 … durationMs` inclusive.
+ */
+export function calculateFilmstripTimestamps(
+  durationMs: number,
+  frameCount: number = 20,
+): number[] {
+  if (durationMs <= 0 || frameCount <= 0) return [0];
+
+  const cell = durationMs / frameCount;
+  const timestamps: number[] = [];
+  for (let i = 0; i < frameCount; i++) {
+    timestamps.push(Math.min(durationMs, Math.round((i + 0.5) * cell)));
+  }
+  return timestamps;
+}
+
+type MetadataOutcome = "ok" | "error" | "timeout";
+
+function awaitMetadata(video: HTMLVideoElement): Promise<MetadataOutcome> {
+  if (video.readyState >= HTMLMediaElement.HAVE_METADATA) {
+    return Promise.resolve("ok");
+  }
+  return new Promise<MetadataOutcome>((resolve) => {
+    const settle = (outcome: MetadataOutcome) => {
+      clearTimeout(timer);
+      video.removeEventListener("loadedmetadata", onLoaded);
+      video.removeEventListener("error", onError);
+      resolve(outcome);
+    };
+    const onLoaded = () => settle("ok");
+    const onError = () => settle("error");
+    const timer = setTimeout(() => settle("timeout"), METADATA_TIMEOUT_MS);
+
+    video.addEventListener("loadedmetadata", onLoaded);
+    video.addEventListener("error", onError);
+  });
+}
+
+/** Resolves once the seek completed, or on timeout. */
+function awaitSeek(video: HTMLVideoElement, timeSec: number): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const settle = () => {
+      clearTimeout(timer);
+      video.removeEventListener("seeked", onSeeked);
+      resolve();
+    };
+    const onSeeked = () => settle();
+    const timer = setTimeout(settle, SEEK_TIMEOUT_MS);
+
+    video.addEventListener("seeked", onSeeked);
+    video.currentTime = timeSec;
+  });
+}
+
+/**
+ * `seeked` fires when the seek lands, which is not the same as the new frame
+ * having been presented for compositing. Without this wait the canvas often
+ * captures the previous frame, or nothing at all.
+ */
+function awaitPresentedFrame(video: HTMLVideoElement): Promise<void> {
+  const withFrameCallback = video as HTMLVideoElement & {
+    requestVideoFrameCallback?: (cb: () => void) => number;
+  };
+  if (typeof withFrameCallback.requestVideoFrameCallback !== "function") {
+    return new Promise<void>((resolve) =>
+      setTimeout(resolve, FRAME_PRESENT_TIMEOUT_MS),
+    );
+  }
+  return new Promise<void>((resolve) => {
+    let settled = false;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    withFrameCallback.requestVideoFrameCallback?.(settle);
+    setTimeout(settle, FRAME_PRESENT_TIMEOUT_MS);
+  });
+}
+
+export async function extractFilmstripThumbnails(
+  options: ExtractFilmstripOptions,
+): Promise<FilmstripResult> {
+  const {
+    videoUrl,
+    durationMs,
+    frameCount = 20,
+    frameWidth = 160,
+    quality = 0.72,
+  } = options;
+
+  if (typeof window === "undefined") {
+    return { status: "skipped-no-window", frames: [], aspectRatio: null };
+  }
+  if (!videoUrl || durationMs <= 0) {
+    return { status: "skipped-no-media", frames: [], aspectRatio: null };
+  }
+
+  const video = document.createElement("video");
+  // Deliberately no `crossOrigin`: the caller passes a same-origin URL, and
+  // requesting CORS mode on media the proxy already made same-origin only
+  // adds a way for the load to fail.
+  video.muted = true;
+  video.preload = "auto";
+  video.src = videoUrl;
+
+  try {
+    const metadata = await awaitMetadata(video);
+    if (metadata !== "ok") {
+      return {
+        status: "failed-metadata",
+        frames: [],
+        aspectRatio: null,
+        detail:
+          metadata === "timeout"
+            ? `Video metadata did not load within ${METADATA_TIMEOUT_MS}ms`
+            : "Video failed to load",
+      };
+    }
+
+    const intrinsicWidth = video.videoWidth;
+    const intrinsicHeight = video.videoHeight;
+    const aspectRatio =
+      intrinsicWidth > 0 && intrinsicHeight > 0
+        ? intrinsicWidth / intrinsicHeight
+        : null;
+
+    const canvas = document.createElement("canvas");
+    canvas.width = frameWidth;
+    canvas.height = Math.max(
+      1,
+      Math.round(frameWidth / (aspectRatio ?? 16 / 9)),
+    );
+    const ctx = canvas.getContext("2d");
+    if (!ctx) {
+      return {
+        status: "failed-canvas",
+        frames: [],
+        aspectRatio,
+        detail: "Could not acquire a 2d canvas context",
+      };
+    }
+
+    const frames: FilmstripFrame[] = [];
+    let blankCount = 0;
+
+    for (const timeMs of calculateFilmstripTimestamps(durationMs, frameCount)) {
+      await awaitSeek(video, timeMs / 1000);
+      await awaitPresentedFrame(video);
+
+      ctx.drawImage(video, 0, 0, canvas.width, canvas.height);
+      const blank = !canvasHasVisibleContent(canvas);
+      if (blank) blankCount++;
+
+      let dataUrl: string;
+      try {
+        dataUrl = canvas.toDataURL("image/jpeg", quality);
+      } catch (err) {
+        // The only realistic cause is a tainted canvas, i.e. the caller passed
+        // a cross-origin URL. Report it rather than returning a short strip.
+        return {
+          status: "failed-canvas",
+          frames: [],
+          aspectRatio,
+          detail: `Canvas read failed (cross-origin media?): ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        };
+      }
+
+      frames.push({ timeMs, dataUrl, blank });
+    }
+
+    if (frames.length > 0 && blankCount === frames.length) {
+      return {
+        status: "failed-all-frames-blank",
+        frames: [],
+        aspectRatio,
+        detail: `All ${frames.length} sampled frames probed as blank`,
+      };
+    }
+
+    return { status: "ok", frames, aspectRatio };
+  } finally {
+    video.pause();
+    video.removeAttribute("src");
+    video.load();
+  }
+}
diff --git a/templates/clips/changelog/2026-07-31-editor-timeline-now-shows-video-frames-behind-the-waveform-g.md b/templates/clips/changelog/2026-07-31-editor-timeline-now-shows-video-frames-behind-the-waveform-g.md
new file mode 100644
index 0000000000..9dd780cd4e
--- /dev/null
+++ b/templates/clips/changelog/2026-07-31-editor-timeline-now-shows-video-frames-behind-the-waveform-g.md
@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-31
+---
+
+Editor timeline now shows video frames behind the waveform, generated server-side as a single sprite image
diff --git a/templates/clips/server/db/schema.ts b/templates/clips/server/db/schema.ts
index 212b0ef363..1802a4193c 100644
--- a/templates/clips/server/db/schema.ts
+++ b/templates/clips/server/db/schema.ts
@@ -146,6 +146,16 @@ export const recordings = table("recordings", {
   thumbnailUrl: text("thumbnail_url"),
   animatedThumbnailUrl: text("animated_thumbnail_url"),
 
+  // Editor timeline filmstrip: one sprite image plus the grid geometry needed
+  // to address a cell. Null means "not generated yet", which is why the editor
+  // still has a browser-side extraction fallback.
+  filmstripUrl: text("filmstrip_url"),
+  filmstripFrameCount: integer("filmstrip_frame_count").notNull().default(0),
+  filmstripColumns: integer("filmstrip_columns").notNull().default(0),
+  filmstripRows: integer("filmstrip_rows").notNull().default(0),
+  filmstripFrameWidth: integer("filmstrip_frame_width").notNull().default(0),
+  filmstripFrameHeight: integer("filmstrip_frame_height").notNull().default(0),
+
   durationMs: integer("duration_ms").notNull().default(0),
   videoUrl: text("video_url"),
   videoFormat: text("video_format", { enum: ["webm", "mp4"] })
diff --git a/templates/clips/server/lib/video-filmstrip-sprite.test.ts b/templates/clips/server/lib/video-filmstrip-sprite.test.ts
new file mode 100644
index 0000000000..40dde925f3
--- /dev/null
+++ b/templates/clips/server/lib/video-filmstrip-sprite.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  MAX_FILMSTRIP_FRAME_COUNT,
+  filmstripGrid,
+  filmstripSpriteFilter,
+} from "./video-filmstrip-sprite.js";
+
+const grid = (frameCount: number, columns = 10) =>
+  filmstripGrid({ frameCount, columns, frameWidth: 160, frameHeight: 90 });
+
+describe("filmstripGrid", () => {
+  it("lays frames out into rows of at most `columns`", () => {
+    expect(grid(40)).toEqual({
+      frameCount: 40,
+      columns: 10,
+      rows: 4,
+      frameWidth: 160,
+      frameHeight: 90,
+    });
+  });
+
+  it("never leaves an empty trailing row", () => {
+    expect(grid(41).rows).toBe(5);
+    expect(grid(40).rows).toBe(4);
+  });
+
+  it("narrows the grid when there are fewer frames than columns", () => {
+    const small = grid(7);
+    expect(small.columns).toBe(7);
+    expect(small.rows).toBe(1);
+  });
+
+  it("clamps to a decodable sprite size", () => {
+    expect(grid(10_000).frameCount).toBe(MAX_FILMSTRIP_FRAME_COUNT);
+  });
+
+  it("always produces at least one cell", () => {
+    expect(grid(0).frameCount).toBe(1);
+    expect(grid(5, 0).columns).toBe(1);
+  });
+});
+
+describe("filmstripSpriteFilter", () => {
+  it("seeks half a cell in so each tile is its slot's midpoint", () => {
+    // 5 cells across 10s => 2s cells => first sample at 1s.
+    const { seekSeconds } = filmstripSpriteFilter({
+      durationMs: 10_000,
+      grid: grid(5),
+    });
+    expect(Number(seekSeconds)).toBeCloseTo(1, 6);
+  });
+
+  it("samples at frameCount / duration so the frames span the clip", () => {
+    const { filter } = filmstripSpriteFilter({
+      durationMs: 10_000,
+      grid: grid(5),
+    });
+    expect(filter).toContain("fps=0.500000");
+  });
+
+  it("pads each cell to an exact size so the grid geometry needs no probe", () => {
+    const { filter } = filmstripSpriteFilter({
+      durationMs: 60_000,
+      grid: grid(40),
+    });
+    expect(filter).toContain(
+      "scale=160:90:force_original_aspect_ratio=decrease",
+    );
+    expect(filter).toContain("pad=160:90:-1:-1:color=black");
+    expect(filter).toContain("tile=10x4");
+  });
+
+  it("keeps the filter stages in decode order", () => {
+    const { filter } = filmstripSpriteFilter({
+      durationMs: 30_000,
+      grid: grid(12, 4),
+    });
+    const stages = filter.split(",").map((stage) => stage.split("=")[0]);
+    expect(stages).toEqual(["fps", "scale", "pad", "tile"]);
+  });
+});
diff --git a/templates/clips/server/lib/video-filmstrip-sprite.ts b/templates/clips/server/lib/video-filmstrip-sprite.ts
new file mode 100644
index 0000000000..1e5d82f383
--- /dev/null
+++ b/templates/clips/server/lib/video-filmstrip-sprite.ts
@@ -0,0 +1,207 @@
+/**
+ * Generate a filmstrip sprite — one JPEG holding a grid of evenly-spaced video
+ * frames — so the editor timeline renders thumbnails as a single cached image
+ * request instead of decoding the video in the browser.
+ *
+ * Why a sprite rather than per-frame files: one ffmpeg pass, one upload, one
+ * HTTP request, and the grid geometry is enough for CSS `background-position`
+ * to address any cell. The browser fallback in `app/lib/video-filmstrip.ts`
+ * needs one seek per frame and cannot read cross-origin media at all.
+ *
+ * Three constraints worth keeping in mind:
+ *
+ *   - Cells are padded to an exact size (`force_original_aspect_ratio=decrease`
+ *     plus `pad`) so the returned grid geometry is exact without probing the
+ *     source. Letterboxed bars on odd aspect ratios are the deliberate cost of
+ *     not having to decode the output to learn its dimensions.
+ *   - Sampling starts half a cell in, matching the browser fallback: cell `i`
+ *     shows the midpoint of the time slot it occupies, not its leading edge.
+ *   - Input arrives as bytes and is written to a temp file, like every other
+ *     ffmpeg path here. That means the whole file is buffered in memory by the
+ *     caller, which is the practical ceiling on this approach for long
+ *     recordings on small hosts.
+ */
+
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { isFfmpegAvailable, runFfmpeg, withRemuxSlot } from "./video-remux.js";
+
+const SPRITE_TIMEOUT_MS = 90_000;
+
+export const DEFAULT_FILMSTRIP_FRAME_COUNT = 40;
+// A sprite is decoded whole by the browser, so cap the grid: 120 cells at the
+// default size is already a ~1600x1080 image.
+export const MAX_FILMSTRIP_FRAME_COUNT = 120;
+export const DEFAULT_FILMSTRIP_FRAME_WIDTH = 160;
+export const DEFAULT_FILMSTRIP_FRAME_HEIGHT = 90;
+export const DEFAULT_FILMSTRIP_COLUMNS = 10;
+
+export type FilmstripSpriteStatus =
+  | "generated"
+  | "skipped-no-ffmpeg"
+  | "skipped-no-duration"
+  | "skipped-no-media"
+  | "failed-ffmpeg"
+  | "failed-empty-output";
+
+/** Everything the UI needs to address one cell of the sprite. */
+export interface FilmstripSpriteGrid {
+  frameCount: number;
+  columns: number;
+  rows: number;
+  frameWidth: number;
+  frameHeight: number;
+}
+
+export interface FilmstripSpriteResult {
+  status: FilmstripSpriteStatus;
+  /** Present only when `status === "generated"`. */
+  sprite?: { bytes: Uint8Array; grid: FilmstripSpriteGrid };
+  detail?: string;
+}
+
+export interface GenerateFilmstripSpriteInput {
+  mediaBytes: Uint8Array;
+  durationMs: number;
+  frameCount?: number;
+  frameWidth?: number;
+  frameHeight?: number;
+  columns?: number;
+}
+
+/**
+ * Lay `frameCount` cells out into a grid no wider than `columns`. Exported so
+ * callers can compute the same geometry the sprite will have without
+ * regenerating it.
+ */
+export function filmstripGrid(input: {
+  frameCount: number;
+  columns: number;
+  frameWidth: number;
+  frameHeight: number;
+}): FilmstripSpriteGrid {
+  const frameCount = Math.min(
+    MAX_FILMSTRIP_FRAME_COUNT,
+    Math.max(1, Math.floor(input.frameCount)),
+  );
+  const columns = Math.max(1, Math.min(input.columns, frameCount));
+  return {
+    frameCount,
+    columns,
+    rows: Math.ceil(frameCount / columns),
+    frameWidth: input.frameWidth,
+    frameHeight: input.frameHeight,
+  };
+}
+
+/**
+ * Build the ffmpeg filter chain that samples `frameCount` frames across
+ * `durationMs` and tiles them into `grid`. Exported for tests: the sampling
+ * offset and rate are the parts most likely to drift from the browser
+ * fallback's expectations.
+ */
+export function filmstripSpriteFilter(input: {
+  durationMs: number;
+  grid: FilmstripSpriteGrid;
+}): { seekSeconds: string; filter: string } {
+  const { durationMs, grid } = input;
+  const cellMs = durationMs / grid.frameCount;
+  const fps = grid.frameCount / (durationMs / 1000);
+
+  return {
+    // Half a cell in, so each tile is the midpoint of its slot.
+    seekSeconds: (cellMs / 2 / 1000).toFixed(6),
+    filter: [
+      `fps=${fps.toFixed(6)}`,
+      `scale=${grid.frameWidth}:${grid.frameHeight}:force_original_aspect_ratio=decrease`,
+      `pad=${grid.frameWidth}:${grid.frameHeight}:-1:-1:color=black`,
+      `tile=${grid.columns}x${grid.rows}`,
+    ].join(","),
+  };
+}
+
+export async function generateFilmstripSprite(
+  input: GenerateFilmstripSpriteInput,
+): Promise<FilmstripSpriteResult> {
+  const {
+    mediaBytes,
+    durationMs,
+    frameCount = DEFAULT_FILMSTRIP_FRAME_COUNT,
+    frameWidth = DEFAULT_FILMSTRIP_FRAME_WIDTH,
+    frameHeight = DEFAULT_FILMSTRIP_FRAME_HEIGHT,
+    columns = DEFAULT_FILMSTRIP_COLUMNS,
+  } = input;
+
+  if (mediaBytes.byteLength === 0) {
+    return { status: "skipped-no-media" };
+  }
+  if (!Number.isFinite(durationMs) || durationMs <= 0) {
+    return { status: "skipped-no-duration" };
+  }
+  if (!isFfmpegAvailable()) {
+    return {
+      status: "skipped-no-ffmpeg",
+      detail:
+        "No ffmpeg binary available; the editor falls back to browser-side frame extraction.",
+    };
+  }
+
+  const grid = filmstripGrid({ frameCount, columns, frameWidth, frameHeight });
+  const { seekSeconds, filter } = filmstripSpriteFilter({ durationMs, grid });
+
+  const dir = await mkdtemp(join(tmpdir(), "clips-filmstrip-"));
+  const inputPath = join(dir, "input.media");
+  const outputPath = join(dir, "sprite.jpg");
+
+  try {
+    await writeFile(inputPath, mediaBytes);
+    await withRemuxSlot(() =>
+      runFfmpeg(
+        [
+          "-hide_banner",
+          "-loglevel",
+          "error",
+          "-nostdin",
+          "-y",
+          // Input seeking: cheap, and puts the first sample at a cell midpoint.
+          "-ss",
+          seekSeconds,
+          "-i",
+          inputPath,
+          "-an",
+          "-sn",
+          "-vf",
+          filter,
+          // The tile filter emits the finished grid as a single frame.
+          "-frames:v",
+          "1",
+          "-q:v",
+          "4",
+          "-f",
+          "image2",
+          outputPath,
+        ],
+        { timeoutMs: SPRITE_TIMEOUT_MS, label: "filmstrip sprite" },
+      ),
+    );
+
+    const bytes = new Uint8Array(await readFile(outputPath));
+    if (bytes.byteLength === 0) {
+      return {
+        status: "failed-empty-output",
+        detail: "ffmpeg reported success but wrote an empty sprite",
+      };
+    }
+
+    return { status: "generated", sprite: { bytes, grid } };
+  } catch (err) {
+    return {
+      status: "failed-ffmpeg",
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
+  }
+}
diff --git a/templates/clips/server/lib/video-remux.ts b/templates/clips/server/lib/video-remux.ts
index 82f0641644..ba09a7d506 100644
--- a/templates/clips/server/lib/video-remux.ts
+++ b/templates/clips/server/lib/video-remux.ts
@@ -125,7 +125,11 @@ function startsWithMagic(bytes: Uint8Array, magic: number[]): boolean {
   return true;
 }
 
-async function runFfmpeg(args: string[]): Promise<void> {
+export async function runFfmpeg(
+  args: string[],
+  options: { timeoutMs?: number; label?: string } = {},
+): Promise<void> {
+  const { timeoutMs = REMUX_TIMEOUT_MS, label = "remux" } = options;
   await new Promise<void>((resolve, reject) => {
     const child = spawn(ffmpegCommand(), args, {
       stdio: ["ignore", "ignore", "pipe"],
@@ -133,8 +137,8 @@ async function runFfmpeg(args: string[]): Promise<void> {
     let stderr = "";
     const timeout = setTimeout(() => {
       child.kill("SIGKILL");
-      reject(new Error(`ffmpeg remux timed out\n${stderr}`));
-    }, REMUX_TIMEOUT_MS);
+      reject(new Error(`ffmpeg ${label} timed out\n${stderr}`));
+    }, timeoutMs);
 
     child.stderr?.on("data", (chunk: Buffer) => {
       stderr = (stderr + chunk.toString("utf8")).slice(-STDERR_LIMIT);
@@ -244,7 +248,12 @@ export async function probeHasAudioStream(
   }
 }
 
-async function withRemuxSlot<T>(fn: () => Promise<T>): Promise<T> {
+/**
+ * Bound concurrent ffmpeg invocations process-wide. Every ffmpeg caller must go
+ * through this, including non-remux jobs — the limit protects the box, not the
+ * remux path specifically.
+ */
+export async function withRemuxSlot<T>(fn: () => Promise<T>): Promise<T> {
   if (activeRemuxes >= MAX_CONCURRENT_REMUXES) {
     await new Promise<void>((resolve) => remuxWaiters.push(resolve));
   }
diff --git a/templates/clips/server/plugins/db.ts b/templates/clips/server/plugins/db.ts
index 62dd5cfee7..28cf80d08f 100644
--- a/templates/clips/server/plugins/db.ts
+++ b/templates/clips/server/plugins/db.ts
@@ -193,6 +193,12 @@ const migrations = runMigrations(
       description TEXT NOT NULL DEFAULT '',
       thumbnail_url TEXT,
       animated_thumbnail_url TEXT,
+      filmstrip_url TEXT,
+      filmstrip_frame_count INTEGER NOT NULL DEFAULT 0,
+      filmstrip_columns INTEGER NOT NULL DEFAULT 0,
+      filmstrip_rows INTEGER NOT NULL DEFAULT 0,
+      filmstrip_frame_width INTEGER NOT NULL DEFAULT 0,
+      filmstrip_frame_height INTEGER NOT NULL DEFAULT 0,
       duration_ms INTEGER NOT NULL DEFAULT 0,
       video_url TEXT,
       video_format TEXT NOT NULL DEFAULT 'webm',

From 0640287add1b1cb09928fade92746b790f346695 Mon Sep 17 00:00:00 2001
From: shivanshu11092003 <shivanshugupta1109@gmail.com>
Date: Fri, 31 Jul 2026 16:09:07 +0530
Subject: [PATCH 2/3] fix(clips): render clean video filmstrip

---
 templates/clips/actions/generate-filmstrip.ts  | 18 +++++++++---------
 .../actions/lib/ensure-recording-filmstrip.ts  |  8 ++++++++
 .../app/components/editor/editor-layout.tsx    | 17 ++++++++++++++---
 .../server/lib/recording-media-cleanup.ts      |  2 ++
 4 files changed, 33 insertions(+), 12 deletions(-)

diff --git a/templates/clips/actions/generate-filmstrip.ts b/templates/clips/actions/generate-filmstrip.ts
index 7a9359ebed..4f8e4f9662 100644
--- a/templates/clips/actions/generate-filmstrip.ts
+++ b/templates/clips/actions/generate-filmstrip.ts
@@ -90,18 +90,18 @@ export default defineAction({
     if (args.ids?.length) targetIds.push(...args.ids.filter(Boolean));
 
     if (args.all) {
+      const conditions = [
+        ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+        eq(schema.recordings.status, "ready"),
+        isNotNull(schema.recordings.videoUrl),
+      ];
+      if (!args.force) {
+        conditions.push(isNull(schema.recordings.filmstripUrl));
+      }
       const rows = await db
         .select({ id: schema.recordings.id })
         .from(schema.recordings)
-        .where(
-          and(
-            ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
-            eq(schema.recordings.status, "ready"),
-            isNotNull(schema.recordings.videoUrl),
-            // Backfill means "has none yet"; use `force` to redo existing ones.
-            isNull(schema.recordings.filmstripUrl),
-          ),
-        )
+        .where(and(...conditions))
         .orderBy(desc(schema.recordings.createdAt))
         .limit(args.limit ?? DEFAULT_ALL_LIMIT);
       targetIds.push(...rows.map((r) => r.id));
diff --git a/templates/clips/actions/lib/ensure-recording-filmstrip.ts b/templates/clips/actions/lib/ensure-recording-filmstrip.ts
index 448b5f547e..19d46239da 100644
--- a/templates/clips/actions/lib/ensure-recording-filmstrip.ts
+++ b/templates/clips/actions/lib/ensure-recording-filmstrip.ts
@@ -20,6 +20,7 @@ import { uploadFile } from "@agent-native/core/file-upload";
 import { and, eq } from "drizzle-orm";
 
 import { getDb, schema } from "../../server/db/index.js";
+import { deleteRecordingMediaObjects } from "../../server/lib/recording-media-cleanup.js";
 import { ownerEmailMatches } from "../../server/lib/recordings.js";
 import {
   DEFAULT_FILMSTRIP_FRAME_COUNT,
@@ -225,6 +226,13 @@ export async function ensureRecordingFilmstrip(params: {
     };
   }
 
+  if (rec.filmstripUrl && rec.filmstripUrl !== upload.url) {
+    await deleteRecordingMediaObjects({
+      id: recordingId,
+      filmstripUrl: rec.filmstripUrl,
+    }).catch(() => {});
+  }
+
   await writeAppState(filmstripMarkerKey(recordingId), {
     recordingId,
     videoUrl: rec.videoUrl,
diff --git a/templates/clips/app/components/editor/editor-layout.tsx b/templates/clips/app/components/editor/editor-layout.tsx
index b8de378626..2bc590ecee 100644
--- a/templates/clips/app/components/editor/editor-layout.tsx
+++ b/templates/clips/app/components/editor/editor-layout.tsx
@@ -540,6 +540,10 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
 
   const [filmstripFrames, setFilmstripFrames] = useState<FilmstripFrame[]>([]);
 
+  useEffect(() => {
+    setFilmstripFrames([]);
+  }, [recordingId]);
+
   // Cells should read as video frames, so aim for one per `height * aspect` of
   // track. Bucketed so ordinary window resizing does not re-extract, and based
   // on the unzoomed width — a zoomed fallback strip stretches, which is one of
@@ -552,8 +556,15 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
 
   useEffect(() => {
     // A sprite already covers the whole clip — don't decode the video again.
-    if (filmstripSprite) return;
-    if (!waveformMediaUrl || durationMs <= 0) return;
+    if (filmstripSprite) {
+      setFilmstripFrames([]);
+      return;
+    }
+    if (!waveformMediaUrl || durationMs <= 0) {
+      setFilmstripFrames([]);
+      return;
+    }
+    setFilmstripFrames([]);
     let cancelled = false;
     // `waveformMediaUrl`, not `videoUrl`: reading frames back out of a
     // cross-origin video taints the canvas, so provider media must come
@@ -833,7 +844,7 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
                     transform: `translateX(${-scrollLeft}px)`,
                   }}
                 >
-                  {(selectionRange || !playing) && (
+                  {durationMs > 0 && (
                     <TrimHandles
                       width={totalWidth}
                       height={WAVEFORM_HEIGHT}
diff --git a/templates/clips/server/lib/recording-media-cleanup.ts b/templates/clips/server/lib/recording-media-cleanup.ts
index d31dded317..4c3e81093a 100644
--- a/templates/clips/server/lib/recording-media-cleanup.ts
+++ b/templates/clips/server/lib/recording-media-cleanup.ts
@@ -7,6 +7,7 @@ interface RecordingMediaUrls {
   videoUrl?: string | null;
   thumbnailUrl?: string | null;
   animatedThumbnailUrl?: string | null;
+  filmstripUrl?: string | null;
 }
 
 export interface RecordingMediaCleanupResult {
@@ -25,6 +26,7 @@ export function recordingMediaUrls(recording: RecordingMediaUrls): string[] {
     recording.videoUrl,
     recording.thumbnailUrl,
     recording.animatedThumbnailUrl,
+    recording.filmstripUrl,
   ];
   return [...new Set(urls.filter((url): url is string => Boolean(url)))];
 }

From 83b458c8a5b1334a42a81d839af5594a5aae9323 Mon Sep 17 00:00:00 2001
From: shivanshu11092003 <shivanshugupta1109@gmail.com>
Date: Fri, 31 Jul 2026 16:28:11 +0530
Subject: [PATCH 3/3] fix(clips): render clean video filmstrip

---
 scripts/i18n-raw-literal-baseline.txt         |  1 -
 .../actions/lib/ensure-recording-filmstrip.ts | 10 ++++++-
 .../app/components/editor/editor-layout.tsx   |  4 +--
 .../clips/app/components/editor/waveform.tsx  | 27 +++++++++++++------
 4 files changed, 30 insertions(+), 12 deletions(-)

diff --git a/scripts/i18n-raw-literal-baseline.txt b/scripts/i18n-raw-literal-baseline.txt
index a570296494..81b51da80f 100644
--- a/scripts/i18n-raw-literal-baseline.txt
+++ b/scripts/i18n-raw-literal-baseline.txt
@@ -6,7 +6,6 @@ packages/docs/app/components/blocks/comparison.tsx|A side-by-side comparison of
 packages/docs/app/components/blocks/steps.tsx|A numbered step-by-step procedure with circled step numbers.
 packages/docs/app/components/blocks/steps.tsx|Step title
 packages/docs/app/components/docBlocks.tsx|| Extract
-templates/clips/app/components/editor/waveform.tsx|VISUAL_SILENCE_FLOOR && botY - topY
 templates/clips/app/components/recorder/storage-setup-card.tsx|AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO
 templates/clips/app/components/workspace/notifications-list.tsx|["formatDate"], formatRelativeTime: ReturnType
 templates/crm/app/components/crm/CreateCrmRecordDialog.tsx|This record lives in the local-authoritative Native SQL CRM. You can connect or mirror another CRM separately.
diff --git a/templates/clips/actions/lib/ensure-recording-filmstrip.ts b/templates/clips/actions/lib/ensure-recording-filmstrip.ts
index 19d46239da..e35e25f1e7 100644
--- a/templates/clips/actions/lib/ensure-recording-filmstrip.ts
+++ b/templates/clips/actions/lib/ensure-recording-filmstrip.ts
@@ -17,7 +17,7 @@ import {
   writeAppState,
 } from "@agent-native/core/application-state";
 import { uploadFile } from "@agent-native/core/file-upload";
-import { and, eq } from "drizzle-orm";
+import { and, eq, isNull } from "drizzle-orm";
 
 import { getDb, schema } from "../../server/db/index.js";
 import { deleteRecordingMediaObjects } from "../../server/lib/recording-media-cleanup.js";
@@ -209,6 +209,10 @@ export async function ensureRecordingFilmstrip(params: {
         ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
         // Don't attach a sprite generated from media the row no longer points at.
         eq(schema.recordings.videoUrl, rec.videoUrl),
+        // Ensure no concurrent job modified filmstripUrl in the interim.
+        rec.filmstripUrl
+          ? eq(schema.recordings.filmstripUrl, rec.filmstripUrl)
+          : isNull(schema.recordings.filmstripUrl),
       ),
     )
     .returning({
@@ -217,6 +221,10 @@ export async function ensureRecordingFilmstrip(params: {
     });
 
   if (updated.length !== 1 || updated[0]?.filmstripUrl !== upload.url) {
+    await deleteRecordingMediaObjects({
+      id: recordingId,
+      filmstripUrl: upload.url,
+    }).catch(() => {});
     return {
       recordingId,
       status: "skipped-upload-failed",
diff --git a/templates/clips/app/components/editor/editor-layout.tsx b/templates/clips/app/components/editor/editor-layout.tsx
index 2bc590ecee..4b1b7f62e3 100644
--- a/templates/clips/app/components/editor/editor-layout.tsx
+++ b/templates/clips/app/components/editor/editor-layout.tsx
@@ -252,8 +252,8 @@ export function EditorLayout({ recordingId, className }: EditorLayoutProps) {
   const baseTrackWidth = useMemo(() => {
     if (durationMs <= 0 || viewportWidth <= 0) return viewportWidth;
     const durationSec = durationMs / 1000;
-    // Scale timeline track width proportionally with duration so long videos scale & scroll
-    const durationScaledPx = Math.round(durationSec * 14);
+    // Scale timeline track width proportionally with duration so long videos scale & scroll (bounded to safe max allocation)
+    const durationScaledPx = Math.min(8192, Math.round(durationSec * 14));
     return Math.max(viewportWidth, durationScaledPx);
   }, [durationMs, viewportWidth]);
 
diff --git a/templates/clips/app/components/editor/waveform.tsx b/templates/clips/app/components/editor/waveform.tsx
index 7092df72b9..47d557f579 100644
--- a/templates/clips/app/components/editor/waveform.tsx
+++ b/templates/clips/app/components/editor/waveform.tsx
@@ -64,6 +64,9 @@ const VISUAL_MAX_GAIN = 24;
 const VISUAL_GAIN_PERCENTILE = 0.95;
 const VISUAL_SILENCE_FLOOR = 0.001;
 
+const MAX_BASE_TRACK_WIDTH = 8192;
+const MAX_CANVAS_PIXELS_WIDTH = 4096;
+
 function clampSample(value: number): number {
   return Math.max(-1, Math.min(1, value));
 }
@@ -128,8 +131,11 @@ export function Waveform({
   const baseTrackWidth = useMemo(() => {
     if (durationMs <= 0 || width <= 0) return width;
     const durationSec = durationMs / 1000;
-    // Scale timeline track width proportionally with duration so long videos don't squish
-    const durationScaledPx = Math.round(durationSec * 14);
+    // Scale timeline track width proportionally with duration so long videos don't squish (bounded to safe max allocation)
+    const durationScaledPx = Math.min(
+      MAX_BASE_TRACK_WIDTH,
+      Math.round(durationSec * 14),
+    );
     return Math.max(width, durationScaledPx);
   }, [durationMs, width]);
 
@@ -182,7 +188,10 @@ export function Waveform({
     const canvas = canvasRef.current;
     if (!canvas) return;
     const dpr = window.devicePixelRatio || 1;
-    canvas.width = Math.floor(totalWidth * dpr);
+    canvas.width = Math.min(
+      MAX_CANVAS_PIXELS_WIDTH,
+      Math.floor(totalWidth * dpr),
+    );
     canvas.height = Math.floor(height * dpr);
     canvas.style.width = `${totalWidth}px`;
     canvas.style.height = `${height}px`;
@@ -223,7 +232,11 @@ export function Waveform({
           );
 
           let maxAmp = 0;
-          for (let b = startBucket; b < endBucket && b < peaks.bucketCount; b++) {
+          for (
+            let b = startBucket;
+            b < endBucket && b < peaks.bucketCount;
+            b++
+          ) {
             const lo = Math.abs(peaks.peaks[b * 2] ?? 0);
             const hi = Math.abs(peaks.peaks[b * 2 + 1] ?? 0);
             if (lo > maxAmp) maxAmp = lo;
@@ -253,9 +266,7 @@ export function Waveform({
           const barHeight = inActivity ? 12 : minBarHeight;
           const topY = midY - barHeight / 2;
 
-          ctx.fillStyle = inActivity
-            ? getWaveColor()
-            : getBrandColorAlpha(0.2);
+          ctx.fillStyle = inActivity ? getWaveColor() : getBrandColorAlpha(0.2);
 
           drawPillBar(ctx, x, topY, barWidth, barHeight);
         }
@@ -325,7 +336,7 @@ export function Waveform({
   const scrubRef = useRef<{ pointerId: number; startX: number } | null>(null);
 
   const seekToEvent = (
-    e: React.PointerEvent<HTMLDivElement> | React.MouseEvent<HTMLDivElement>,
+    e: React.PointerEvent<HTMLDivElement> | React.MouseEvent<HTMLDivElement>, // i18n-ignore
   ) => {
     if (!onSeek) return;
     const el = scrollRef.current;