From 3f0fe8850a53d337ebf5c97353f200e6a762baac Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 00:44:55 +0530
Subject: [PATCH 01/36] feat: give split operations a scene title, source and
 group

Split ops existed in the type union but nothing used them. They become
scene boundaries: an optional title names the scene, source records
whether a person, the AI or shot detection placed it, and groupId lets a
batch of ops (e.g. applied suggestions) undo as one step. The route
rejects a split at or past the end of the video, since that would make an
empty scene; a split at 0 is allowed and only names the first scene.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/types/edit-operation.ts            | 46 ++++++++++++-------
 .../src/lib/validation/edit-operation.test.ts | 20 ++++++++
 server/src/lib/validation/edit-operation.ts   |  6 +++
 server/src/routes/operations.ts               |  6 ++-
 server/src/types/edit-operation.ts            | 46 ++++++++++++-------
 5 files changed, 91 insertions(+), 33 deletions(-)

diff --git a/client/src/types/edit-operation.ts b/client/src/types/edit-operation.ts
index ecdfa4c..150cf9d 100644
--- a/client/src/types/edit-operation.ts
+++ b/client/src/types/edit-operation.ts
@@ -1,32 +1,46 @@
+/**
+ * Fields every operation shares. `groupId` ties together ops created by one
+ * user action (e.g. applying a batch of suggested scenes) so undo/redo can
+ * treat them as a single step.
+ */
+type OperationBase = {
+  id: string;
+  createdAt: number;
+  groupId?: string;
+};
+
+/** Where a scene boundary came from -- shown in the UI, never changes behavior. */
+export type SplitSource = "manual" | "ai" | "shot";
+
 export type EditOperation =
-  | {
-      id: string;
+  | (OperationBase & {
       type: "cut";
       start: number;
       end: number;
       reason?: string;
-      createdAt: number;
-    }
-  | {
-      id: string;
+    })
+  | (OperationBase & {
       type: "trim";
       start: number;
       end: number;
-      createdAt: number;
-    }
-  | {
-      id: string;
+    })
+  | (OperationBase & {
+      /**
+       * A scene boundary in source time. Splits don't change what's
+       * rendered; they divide the episode into named scenes that cuts,
+       * cards and transitions attach to.
+       */
       type: "split";
       timestamp: number;
-      createdAt: number;
-    }
-  | {
-      id: string;
+      title?: string;
+      source?: SplitSource;
+    })
+  | (OperationBase & {
       type: "caption";
       text: string;
       start: number;
       end: number;
-      createdAt: number;
-    };
+    });
 
 export type CutOperation = Extract<EditOperation, { type: "cut" }>;
+export type SplitOperation = Extract<EditOperation, { type: "split" }>;
diff --git a/server/src/lib/validation/edit-operation.test.ts b/server/src/lib/validation/edit-operation.test.ts
index bcfd8c3..167da60 100644
--- a/server/src/lib/validation/edit-operation.test.ts
+++ b/server/src/lib/validation/edit-operation.test.ts
@@ -77,4 +77,24 @@ describe("editOperationSchema", () => {
     const result = editOperationSchema.safeParse({ id: "1", type: "cut", start: 0, timestamp: 5, createdAt: 0 });
     expect(result.success).toBe(false);
   });
+
+  it("accepts a split with a scene title, source and group", () => {
+    expect(
+      editOperationSchema.safeParse({
+        id: "1",
+        type: "split",
+        timestamp: 42.5,
+        title: "Pricing",
+        source: "ai",
+        groupId: "g1",
+        createdAt: 0,
+      }).success
+    ).toBe(true);
+  });
+
+  it("rejects an over-long scene title and an unknown split source", () => {
+    const base = { id: "1", type: "split", timestamp: 3, createdAt: 0 };
+    expect(editOperationSchema.safeParse({ ...base, title: "x".repeat(81) }).success).toBe(false);
+    expect(editOperationSchema.safeParse({ ...base, source: "robot" }).success).toBe(false);
+  });
 });
diff --git a/server/src/lib/validation/edit-operation.ts b/server/src/lib/validation/edit-operation.ts
index 8978889..05b3060 100644
--- a/server/src/lib/validation/edit-operation.ts
+++ b/server/src/lib/validation/edit-operation.ts
@@ -15,6 +15,7 @@ export const editOperationSchema = z.discriminatedUnion("type", [
     end: z.number().nonnegative(),
     reason: z.string().max(500).optional(),
     createdAt: z.number(),
+    groupId: z.string().min(1).max(100).optional(),
   }),
   z.object({
     id: z.string().min(1),
@@ -22,12 +23,16 @@ export const editOperationSchema = z.discriminatedUnion("type", [
     start: z.number().nonnegative(),
     end: z.number().nonnegative(),
     createdAt: z.number(),
+    groupId: z.string().min(1).max(100).optional(),
   }),
   z.object({
     id: z.string().min(1),
     type: z.literal("split"),
     timestamp: z.number().nonnegative(),
+    title: z.string().trim().max(80).optional(),
+    source: z.enum(["manual", "ai", "shot"]).optional(),
     createdAt: z.number(),
+    groupId: z.string().min(1).max(100).optional(),
   }),
   z.object({
     id: z.string().min(1),
@@ -36,5 +41,6 @@ export const editOperationSchema = z.discriminatedUnion("type", [
     start: z.number().nonnegative(),
     end: z.number().nonnegative(),
     createdAt: z.number(),
+    groupId: z.string().min(1).max(100).optional(),
   }),
 ]);
diff --git a/server/src/routes/operations.ts b/server/src/routes/operations.ts
index ed7002b..1fa4850 100644
--- a/server/src/routes/operations.ts
+++ b/server/src/routes/operations.ts
@@ -25,10 +25,14 @@ operationsRoute.post("/:id/operations", async (c) => {
     return errorResponse(c, "INVALID_OPERATION", "end must be after start.", 400);
   }
 
-  const project = await prisma.project.findUnique({ where: { id: projectId }, select: { id: true } });
+  const project = await prisma.project.findUnique({ where: { id: projectId }, select: { id: true, duration: true } });
   if (!project) {
     return errorResponse(c, "NOT_FOUND", "Project not found.", 404);
   }
+  // A split at 0 only names the first scene; one at or past the end would make an empty scene.
+  if (op.type === "split" && project.duration && op.timestamp >= project.duration) {
+    return errorResponse(c, "INVALID_OPERATION", "Split must fall inside the video.", 400);
+  }
 
   // Client generates the id (needed so undo/redo can address the exact row);
   // upsert so a redo that restores a previously-undone op is idempotent.
diff --git a/server/src/types/edit-operation.ts b/server/src/types/edit-operation.ts
index ecdfa4c..150cf9d 100644
--- a/server/src/types/edit-operation.ts
+++ b/server/src/types/edit-operation.ts
@@ -1,32 +1,46 @@
+/**
+ * Fields every operation shares. `groupId` ties together ops created by one
+ * user action (e.g. applying a batch of suggested scenes) so undo/redo can
+ * treat them as a single step.
+ */
+type OperationBase = {
+  id: string;
+  createdAt: number;
+  groupId?: string;
+};
+
+/** Where a scene boundary came from -- shown in the UI, never changes behavior. */
+export type SplitSource = "manual" | "ai" | "shot";
+
 export type EditOperation =
-  | {
-      id: string;
+  | (OperationBase & {
       type: "cut";
       start: number;
       end: number;
       reason?: string;
-      createdAt: number;
-    }
-  | {
-      id: string;
+    })
+  | (OperationBase & {
       type: "trim";
       start: number;
       end: number;
-      createdAt: number;
-    }
-  | {
-      id: string;
+    })
+  | (OperationBase & {
+      /**
+       * A scene boundary in source time. Splits don't change what's
+       * rendered; they divide the episode into named scenes that cuts,
+       * cards and transitions attach to.
+       */
       type: "split";
       timestamp: number;
-      createdAt: number;
-    }
-  | {
-      id: string;
+      title?: string;
+      source?: SplitSource;
+    })
+  | (OperationBase & {
       type: "caption";
       text: string;
       start: number;
       end: number;
-      createdAt: number;
-    };
+    });
 
 export type CutOperation = Extract<EditOperation, { type: "cut" }>;
+export type SplitOperation = Extract<EditOperation, { type: "split" }>;

From 04232702099999a2ec2879e4ecd516ba1c868c8f Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 00:44:55 +0530
Subject: [PATCH 02/36] feat(client): undo history as steps, not single
 operations

Undo used to pop the last operation, so removing 40 filler words took 40
undos, and restoring a cut or renaming anything couldn't be undone at
all. History is now a stack of steps, each recording the ops it added and
removed: bulk actions (filler words, long pauses, cutting a speaker)
commit one step, restores are undoable, and replacing an op -- how a
scene gets renamed, since ops are never mutated -- swaps back on undo.
After a reload the steps are rebuilt from the persisted ops, grouping by
groupId.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/components/editor/AiToolsPanel.tsx |  16 +-
 .../src/components/transcript/SpeakersBar.tsx |  15 +-
 client/src/stores/timeline-store.ts           | 195 ++++++++++++------
 3 files changed, 147 insertions(+), 79 deletions(-)

diff --git a/client/src/components/editor/AiToolsPanel.tsx b/client/src/components/editor/AiToolsPanel.tsx
index 22ce033..8dc368b 100644
--- a/client/src/components/editor/AiToolsPanel.tsx
+++ b/client/src/components/editor/AiToolsPanel.tsx
@@ -19,7 +19,7 @@ export function AiToolsPanel() {
   const setSilenceGaps = useTranscriptStore((s) => s.setSilenceGaps);
 
   const projectId = useProjectStore((s) => s.id);
-  const addCut = useTimelineStore((s) => s.addCut);
+  const addCuts = useTimelineStore((s) => s.addCuts);
 
   const allWords = useMemo(
     () => transcript?.segments.flatMap((seg) => seg.words) ?? [],
@@ -43,11 +43,11 @@ export function AiToolsPanel() {
 
   const handleRemoveFillerWords = () => {
     const fillerWordIdSet = new Set(fillerWordIds);
-    for (const word of allWords) {
-      if (fillerWordIdSet.has(word.id)) {
-        addCut(padCutStart(word.start, allWords), word.end, "filler word");
-      }
-    }
+    addCuts(
+      allWords
+        .filter((word) => fillerWordIdSet.has(word.id))
+        .map((word) => ({ start: padCutStart(word.start, allWords), end: word.end, reason: "filler word" }))
+    );
     setFillerWordIds([]);
   };
 
@@ -58,9 +58,7 @@ export function AiToolsPanel() {
 
   const handleRemoveSilences = () => {
     if (!silenceGaps) return;
-    for (const gap of silenceGaps) {
-      addCut(gap.start, gap.end, "long pause");
-    }
+    addCuts(silenceGaps.map((gap) => ({ start: gap.start, end: gap.end, reason: "long pause" })));
     setSilenceGaps(null);
   };
 
diff --git a/client/src/components/transcript/SpeakersBar.tsx b/client/src/components/transcript/SpeakersBar.tsx
index b9beeea..1f86405 100644
--- a/client/src/components/transcript/SpeakersBar.tsx
+++ b/client/src/components/transcript/SpeakersBar.tsx
@@ -112,7 +112,7 @@ export function SpeakersBar() {
   const transcript = useTranscriptStore((s) => s.transcript);
   const setTranscript = useTranscriptStore((s) => s.setTranscript);
   const operations = useTimelineStore((s) => s.operations);
-  const addCut = useTimelineStore((s) => s.addCut);
+  const addCuts = useTimelineStore((s) => s.addCuts);
   const removeOperations = useTimelineStore((s) => s.removeOperations);
 
   const [job, setJob] = useState<Job | null>(null);
@@ -197,11 +197,14 @@ export function SpeakersBar() {
   const segmentsOf = (name: string) => transcript.segments.filter((s) => s.speaker === name && s.words.length > 0);
 
   const cutAll = (name: string) => {
-    for (const segment of segmentsOf(name)) {
-      if (isFullyCut(segment.words, cuts)) continue;
-      const { start, end } = wordSpanBounds(segment.words, { start: segment.start, end: segment.end });
-      addCut(padCutStart(start, allWords), end, `speaker: ${name}`);
-    }
+    addCuts(
+      segmentsOf(name)
+        .filter((segment) => !isFullyCut(segment.words, cuts))
+        .map((segment) => {
+          const { start, end } = wordSpanBounds(segment.words, { start: segment.start, end: segment.end });
+          return { start: padCutStart(start, allWords), end, reason: `speaker: ${name}` };
+        })
+    );
   };
 
   const restoreAll = (name: string) => {
diff --git a/client/src/stores/timeline-store.ts b/client/src/stores/timeline-store.ts
index 1607386..fd90fe3 100644
--- a/client/src/stores/timeline-store.ts
+++ b/client/src/stores/timeline-store.ts
@@ -1,19 +1,34 @@
 import { create } from "zustand";
-import type { CutOperation, EditOperation } from "@/types/edit-operation";
+import type { CutOperation, EditOperation, SplitOperation } from "@/types/edit-operation";
+
+/**
+ * One undoable step: the operations it added and the ones it removed.
+ * Most steps only add (a cut, a split); replacing an op -- e.g. renaming a
+ * scene, since ops are never mutated in place -- removes the old version
+ * and adds the new one, and undo swaps them back.
+ */
+type HistoryEntry = { added: EditOperation[]; removed: EditOperation[] };
 
 type TimelineStore = {
   projectId: string | null;
   operations: EditOperation[];
-  redoStack: EditOperation[];
+  undoStack: HistoryEntry[];
+  redoStack: HistoryEntry[];
 
   addCut: (start: number, end: number, reason?: string) => void;
+  /** Several cuts as one undo step (e.g. "Remove all filler words"). */
+  addCuts: (cuts: { start: number; end: number; reason?: string }[]) => void;
+  /** Adds a scene boundary at a source time; callers snap it off words first (lib/timeline/scenes.ts). */
+  addSplit: (timestamp: number, title?: string) => void;
+  /** Adds several operations as one undo step (they share a groupId). */
+  addOperations: (ops: EditOperation[]) => void;
+  /** Swaps one operation for a new version of it, as one undo step. */
+  replaceOperation: (operationId: string, next: EditOperation) => void;
   /**
    * Removes specific operations by id, regardless of where they sit in
-   * history -- unlike undo/redo (which only ever act on the top of the
-   * stack), this lets a user restore one particular cut word/segment/
-   * sentence directly. Clears the redo stack, same as addCut: once history
-   * has been edited out of order like this, replaying old undo()s no
-   * longer has a well-defined meaning.
+   * history -- this lets a user restore one particular cut word/segment/
+   * sentence directly. It's its own undo step, so an accidental restore
+   * can be undone too.
    */
   removeOperations: (operationIds: string[]) => void;
   undo: () => void;
@@ -41,60 +56,112 @@ function deleteOperation(projectId: string | null, operationId: string) {
   );
 }
 
-export const useTimelineStore = create<TimelineStore>((set, get) => ({
-  projectId: null,
-  operations: [],
-  redoStack: [],
-
-  addCut: (start, end, reason) => {
-    if (end <= start) return;
-    const op: CutOperation = {
-      id: crypto.randomUUID(),
-      type: "cut",
-      start,
-      end,
-      reason,
-      createdAt: Date.now(),
-    };
-    set((s) => ({ operations: [...s.operations, op], redoStack: [] }));
-    persistOperation(get().projectId, op);
-  },
-
-  removeOperations: (operationIds) => {
-    const idSet = new Set(operationIds);
-    const { operations, projectId } = get();
-    const toRemove = operations.filter((op) => idSet.has(op.id));
-    if (toRemove.length === 0) return;
-    set((s) => ({ operations: s.operations.filter((op) => !idSet.has(op.id)), redoStack: [] }));
-    for (const op of toRemove) deleteOperation(projectId, op.id);
-  },
-
-  undo: () => {
-    const { operations, projectId } = get();
-    if (operations.length === 0) return;
-    const last = operations[operations.length - 1];
-    set((s) => ({
-      operations: s.operations.slice(0, -1),
-      redoStack: [...s.redoStack, last],
-    }));
-    deleteOperation(projectId, last.id);
-  },
-
-  redo: () => {
-    const { redoStack, projectId } = get();
-    if (redoStack.length === 0) return;
-    const op = redoStack[redoStack.length - 1];
-    set((s) => ({
-      operations: [...s.operations, op],
-      redoStack: s.redoStack.slice(0, -1),
-    }));
-    persistOperation(projectId, op);
-  },
-
-  hydrate: (projectId, operations) => set({ projectId, operations, redoStack: [] }),
-
-  reset: () => set({ projectId: null, operations: [], redoStack: [] }),
-
-  cuts: () =>
-    get().operations.filter((op): op is CutOperation => op.type === "cut"),
-}));
+function makeCut(start: number, end: number, reason?: string): CutOperation {
+  return { id: crypto.randomUUID(), type: "cut", start, end, reason, createdAt: Date.now() };
+}
+
+/**
+ * Rebuilds undo history from persisted ops, so undo still works after a
+ * reload: each op is its own step, except ops sharing a groupId, which
+ * undo together. Replacements can't be reconstructed (the old version is
+ * gone), so after a reload undoing a rename removes the scene boundary --
+ * the same thing undoing the original split would have done.
+ */
+function historyFromOperations(operations: EditOperation[]): HistoryEntry[] {
+  const entries: HistoryEntry[] = [];
+  for (const op of operations) {
+    const last = entries[entries.length - 1];
+    if (op.groupId && last?.added[0]?.groupId === op.groupId) {
+      last.added.push(op);
+    } else {
+      entries.push({ added: [op], removed: [] });
+    }
+  }
+  return entries;
+}
+
+export const useTimelineStore = create<TimelineStore>((set, get) => {
+  /** Applies a step's changes (or their inverse) to state and the server. */
+  const apply = (added: EditOperation[], removed: EditOperation[]) => {
+    const removedIds = new Set(removed.map((op) => op.id));
+    set((s) => ({ operations: [...s.operations.filter((op) => !removedIds.has(op.id)), ...added] }));
+    const { projectId } = get();
+    for (const op of removed) deleteOperation(projectId, op.id);
+    for (const op of added) persistOperation(projectId, op);
+  };
+
+  const commit = (entry: HistoryEntry) => {
+    if (entry.added.length === 0 && entry.removed.length === 0) return;
+    apply(entry.added, entry.removed);
+    set((s) => ({ undoStack: [...s.undoStack, entry], redoStack: [] }));
+  };
+
+  return {
+    projectId: null,
+    operations: [],
+    undoStack: [],
+    redoStack: [],
+
+    addCut: (start, end, reason) => {
+      if (end <= start) return;
+      commit({ added: [makeCut(start, end, reason)], removed: [] });
+    },
+
+    addCuts: (cuts) => {
+      const valid = cuts.filter((c) => c.end > c.start);
+      if (valid.length === 1) get().addCut(valid[0].start, valid[0].end, valid[0].reason);
+      else get().addOperations(valid.map((c) => makeCut(c.start, c.end, c.reason)));
+    },
+
+    addSplit: (timestamp, title) => {
+      const op: SplitOperation = {
+        id: crypto.randomUUID(),
+        type: "split",
+        timestamp,
+        source: "manual",
+        createdAt: Date.now(),
+        ...(title ? { title } : {}),
+      };
+      commit({ added: [op], removed: [] });
+    },
+
+    addOperations: (ops) => {
+      if (ops.length === 0) return;
+      const groupId = crypto.randomUUID();
+      commit({ added: ops.map((op) => ({ ...op, groupId })), removed: [] });
+    },
+
+    replaceOperation: (operationId, next) => {
+      const current = get().operations.find((op) => op.id === operationId);
+      if (!current) return;
+      commit({ added: [next], removed: [current] });
+    },
+
+    removeOperations: (operationIds) => {
+      const idSet = new Set(operationIds);
+      const toRemove = get().operations.filter((op) => idSet.has(op.id));
+      commit({ added: [], removed: toRemove });
+    },
+
+    undo: () => {
+      const entry = get().undoStack.at(-1);
+      if (!entry) return;
+      apply(entry.removed, entry.added);
+      set((s) => ({ undoStack: s.undoStack.slice(0, -1), redoStack: [...s.redoStack, entry] }));
+    },
+
+    redo: () => {
+      const entry = get().redoStack.at(-1);
+      if (!entry) return;
+      apply(entry.added, entry.removed);
+      set((s) => ({ redoStack: s.redoStack.slice(0, -1), undoStack: [...s.undoStack, entry] }));
+    },
+
+    hydrate: (projectId, operations) =>
+      set({ projectId, operations, undoStack: historyFromOperations(operations), redoStack: [] }),
+
+    reset: () => set({ projectId: null, operations: [], undoStack: [], redoStack: [] }),
+
+    cuts: () => get().operations.filter((op): op is CutOperation => op.type === "cut"),
+  };
+});

From 551a55fd2dc01857cef17168f651bc4d7935aebd Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 00:44:55 +0530
Subject: [PATCH 03/36] feat(client): derive scenes from split operations

Scenes are computed, never stored: the ranges between split points, with
their position on the edited timeline so a fully cut scene collapses to
zero width but stays listed for restoring. New splits snap to the middle
of the nearest gap between words, so a boundary -- and later a card or
transition placed on it -- never lands inside a word.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/lib/timeline/scenes.test.ts | 108 +++++++++++++++++++
 client/src/lib/timeline/scenes.ts      | 142 +++++++++++++++++++++++++
 client/src/lib/timeline/useScenes.ts   |  41 +++++++
 3 files changed, 291 insertions(+)
 create mode 100644 client/src/lib/timeline/scenes.test.ts
 create mode 100644 client/src/lib/timeline/scenes.ts
 create mode 100644 client/src/lib/timeline/useScenes.ts

diff --git a/client/src/lib/timeline/scenes.test.ts b/client/src/lib/timeline/scenes.test.ts
new file mode 100644
index 0000000..3c1e84b
--- /dev/null
+++ b/client/src/lib/timeline/scenes.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import { buildScenes, gapBefore, sceneAt, snapToWordGap, sortedSplits } from "@/lib/timeline/scenes";
+import { computePlayableRanges } from "@/lib/timeline/cuts";
+import type { CutOperation, EditOperation } from "@/types/edit-operation";
+
+const split = (id: string, timestamp: number, extra: Partial<EditOperation> = {}): EditOperation =>
+  ({ id, type: "split", timestamp, createdAt: 0, ...extra }) as EditOperation;
+const cut = (id: string, start: number, end: number): CutOperation => ({ id, type: "cut", start, end, createdAt: 0 });
+
+describe("buildScenes", () => {
+  it("is one scene covering the whole video when there are no splits", () => {
+    const ranges = computePlayableRanges(100, []);
+    expect(buildScenes(100, [], ranges)).toEqual([
+      {
+        id: "scene-start",
+        splitId: null,
+        index: 0,
+        title: "Scene 1",
+        source: null,
+        start: 0,
+        end: 100,
+        editedStart: 0,
+        editedEnd: 100,
+      },
+    ]);
+  });
+
+  it("divides at splits in time order and keeps their titles", () => {
+    const ops = [split("b", 60, { title: "Pricing" } as Partial<EditOperation>), split("a", 20)];
+    const scenes = buildScenes(100, ops, computePlayableRanges(100, []));
+    expect(scenes.map((s) => [s.title, s.start, s.end, s.splitId])).toEqual([
+      ["Scene 1", 0, 20, null],
+      ["Scene 2", 20, 60, "a"],
+      ["Pricing", 60, 100, "b"],
+    ]);
+  });
+
+  it("places scenes on the edited timeline, with a fully cut scene collapsing to zero width", () => {
+    const cuts = [cut("c1", 0, 10), cut("c2", 20, 60)];
+    const ops: EditOperation[] = [...cuts, split("a", 20), split("b", 60)];
+    const scenes = buildScenes(100, ops, computePlayableRanges(100, cuts));
+    expect(scenes.map((s) => [s.editedStart, s.editedEnd])).toEqual([
+      [0, 10],
+      [10, 10],
+      [10, 50],
+    ]);
+  });
+
+  it("uses a split at 0 only to name the first scene", () => {
+    const ops = [split("open", 0, { title: "Intro" } as Partial<EditOperation>), split("a", 30)];
+    const scenes = buildScenes(100, ops, computePlayableRanges(100, []));
+    expect(scenes.map((s) => [s.title, s.start, s.splitId])).toEqual([
+      ["Intro", 0, "open"],
+      ["Scene 2", 30, "a"],
+    ]);
+  });
+
+  it("ignores splits at or outside the video's ends", () => {
+    const ops = [split("a", 0), split("b", 100), split("c", 150)];
+    expect(buildScenes(100, ops, computePlayableRanges(100, []))).toHaveLength(1);
+  });
+});
+
+describe("sortedSplits", () => {
+  it("drops a near-duplicate split, keeping the earlier-created one", () => {
+    const ops = [
+      split("late", 30.02, { createdAt: 5 } as Partial<EditOperation>),
+      split("early", 30, { createdAt: 1 } as Partial<EditOperation>),
+    ];
+    expect(sortedSplits(ops, 100).map((s) => s.id)).toEqual(["early"]);
+  });
+});
+
+describe("sceneAt", () => {
+  it("finds the scene containing a source time", () => {
+    const scenes = buildScenes(100, [split("a", 40)], computePlayableRanges(100, []));
+    expect(sceneAt(scenes, 10)?.index).toBe(0);
+    expect(sceneAt(scenes, 40)?.index).toBe(1);
+    expect(sceneAt(scenes, 100)?.index).toBe(1);
+  });
+});
+
+describe("snapToWordGap", () => {
+  const words = [
+    { start: 1, end: 2 },
+    { start: 2.4, end: 3 },
+    { start: 4, end: 5 },
+  ];
+
+  it("leaves a time that is already between words alone", () => {
+    expect(snapToWordGap(3.5, words)).toBe(3.5);
+  });
+
+  it("moves a time inside a word to the middle of the nearer gap", () => {
+    expect(snapToWordGap(2.5, words)).toBeCloseTo(2.2); // closer to the start of "2.4-3"
+    expect(snapToWordGap(2.9, words)).toBeCloseTo(3.5); // closer to its end
+  });
+
+  it("returns the time unchanged with no words", () => {
+    expect(snapToWordGap(7, [])).toBe(7);
+  });
+});
+
+describe("gapBefore", () => {
+  it("is the midpoint between the previous word's end and this word's start", () => {
+    expect(gapBefore(4, [{ start: 1, end: 3 }, { start: 4, end: 5 }])).toBe(3.5);
+  });
+});
diff --git a/client/src/lib/timeline/scenes.ts b/client/src/lib/timeline/scenes.ts
new file mode 100644
index 0000000..383e8f7
--- /dev/null
+++ b/client/src/lib/timeline/scenes.ts
@@ -0,0 +1,142 @@
+import type { EditOperation, SplitOperation, SplitSource } from "@/types/edit-operation";
+import type { PlayableRange } from "@/types/timeline";
+import { sourceTimeToEditedTime } from "@/lib/timeline/cuts";
+
+/** Two splits closer than this are the same boundary (double-click, AI + manual). */
+const SPLIT_DEDUPE_SECONDS = 0.05;
+
+/**
+ * A stretch of the source between two scene boundaries (split operations).
+ * Scenes are derived, never stored: the split ops are the source of truth,
+ * so undo/redo and persistence need nothing new.
+ */
+export type Scene = {
+  /** The split op that starts this scene, or "scene-start" for the first one. */
+  id: string;
+  /** null for the first scene, which starts at 0 without a split. */
+  splitId: string | null;
+  index: number;
+  title: string;
+  source: SplitSource | null;
+  /** Source time. */
+  start: number;
+  end: number;
+  /** Position on the edited (cuts-removed) timeline. */
+  editedStart: number;
+  editedEnd: number;
+};
+
+export function defaultSceneTitle(index: number): string {
+  return `Scene ${index + 1}`;
+}
+
+/** Split ops inside (0, duration), sorted, with near-duplicates dropped (the earliest-created wins). */
+export function sortedSplits(operations: EditOperation[], duration: number): SplitOperation[] {
+  const splits = operations
+    .filter((op): op is SplitOperation => op.type === "split")
+    .filter((op) => op.timestamp > 0 && op.timestamp < duration)
+    .sort((a, b) => a.timestamp - b.timestamp || a.createdAt - b.createdAt);
+
+  const result: SplitOperation[] = [];
+  for (const split of splits) {
+    const last = result[result.length - 1];
+    if (last && split.timestamp - last.timestamp < SPLIT_DEDUPE_SECONDS) continue;
+    result.push(split);
+  }
+  return result;
+}
+
+/**
+ * Divides [0, duration] into scenes at every split. A scene whose source
+ * range was cut entirely is still returned (editedStart === editedEnd), so
+ * the scene list can offer to restore it.
+ */
+export function buildScenes(
+  duration: number,
+  operations: EditOperation[],
+  playableRanges: PlayableRange[]
+): Scene[] {
+  if (duration <= 0) return [];
+  const splits = sortedSplits(operations, duration);
+  const bounds = [0, ...splits.map((s) => s.timestamp), duration];
+  const opening = openingSplit(operations);
+
+  return bounds.slice(0, -1).map((start, i) => {
+    const end = bounds[i + 1];
+    const split = i === 0 ? opening : splits[i - 1];
+    return {
+      id: split?.id ?? "scene-start",
+      splitId: split?.id ?? null,
+      index: i,
+      title: split?.title?.trim() || defaultSceneTitle(i),
+      source: split?.source ?? null,
+      start,
+      end,
+      editedStart: sourceTimeToEditedTime(start, playableRanges),
+      editedEnd: sourceTimeToEditedTime(end, playableRanges),
+    };
+  });
+}
+
+/**
+ * A split at exactly 0 isn't a boundary -- the first scene always starts
+ * there -- it only carries the first scene's title, so that scene can be
+ * renamed like any other. The latest one wins.
+ */
+function openingSplit(operations: EditOperation[]): SplitOperation | null {
+  const openings = operations.filter((op): op is SplitOperation => op.type === "split" && op.timestamp === 0);
+  return openings.sort((a, b) => a.createdAt - b.createdAt).at(-1) ?? null;
+}
+
+/** The scene containing this source time (the last scene for t >= duration). */
+export function sceneAt(scenes: Scene[], sourceTime: number): Scene | null {
+  for (const scene of scenes) {
+    if (sourceTime < scene.end) return scene;
+  }
+  return scenes[scenes.length - 1] ?? null;
+}
+
+/**
+ * Moves a time off any word it falls inside, to the middle of the nearest
+ * gap between words, so a scene boundary never splits a word -- which
+ * would later put a transition or card in the middle of speech. Times
+ * already in a gap (or with no words at all) come back unchanged.
+ */
+export function snapToWordGap(time: number, words: { start: number; end: number }[]): number {
+  if (words.length === 0) return time;
+  const sorted = [...words].sort((a, b) => a.start - b.start);
+
+  const inside = sorted.findIndex((w) => time > w.start && time < w.end);
+  if (inside === -1) return time;
+
+  const word = sorted[inside];
+  const previousEnd = inside > 0 ? sorted[inside - 1].end : 0;
+  const nextStart = inside < sorted.length - 1 ? sorted[inside + 1].start : word.end;
+  const before = (previousEnd + word.start) / 2;
+  const after = (word.end + nextStart) / 2;
+  return time - word.start <= word.end - time ? before : after;
+}
+
+/**
+ * Scene block colors, cycled by index. Full class names so Tailwind's
+ * scanner keeps them (same approach as lib/transcript/speakers.ts).
+ */
+const SCENE_COLORS = [
+  { block: "border-sky-500 bg-sky-500/20", dot: "bg-sky-500" },
+  { block: "border-amber-500 bg-amber-500/20", dot: "bg-amber-500" },
+  { block: "border-emerald-500 bg-emerald-500/20", dot: "bg-emerald-500" },
+  { block: "border-violet-500 bg-violet-500/20", dot: "bg-violet-500" },
+];
+
+export function sceneColor(index: number): { block: string; dot: string } {
+  return SCENE_COLORS[index % SCENE_COLORS.length];
+}
+
+/** Midpoint of the gap just before a word (where "split before this sentence" lands). */
+export function gapBefore(wordStart: number, words: { start: number; end: number }[]): number {
+  let previousEnd = 0;
+  for (const w of words) {
+    if (w.end <= wordStart && w.end > previousEnd) previousEnd = w.end;
+  }
+  return (previousEnd + wordStart) / 2;
+}
diff --git a/client/src/lib/timeline/useScenes.ts b/client/src/lib/timeline/useScenes.ts
new file mode 100644
index 0000000..001138b
--- /dev/null
+++ b/client/src/lib/timeline/useScenes.ts
@@ -0,0 +1,41 @@
+import { useCallback, useMemo } from "react";
+import { usePlayerStore } from "@/stores/player-store";
+import { useTimelineStore } from "@/stores/timeline-store";
+import { useTranscriptStore } from "@/stores/transcript-store";
+import { computePlayableRanges } from "@/lib/timeline/cuts";
+import { buildScenes, snapToWordGap, type Scene } from "@/lib/timeline/scenes";
+import type { CutOperation } from "@/types/edit-operation";
+
+/** Minimum distance from an existing boundary (or either end) for a new split. */
+const MIN_SCENE_SECONDS = 0.5;
+
+/** The project's scenes plus the split action, derived from the timeline store. */
+export function useScenes(): {
+  scenes: Scene[];
+  /** Splits at a source time (snapped off words); returns false if too close to an existing boundary. */
+  splitAt: (sourceTime: number) => boolean;
+} {
+  const duration = usePlayerStore((s) => s.duration);
+  const operations = useTimelineStore((s) => s.operations);
+  const addSplit = useTimelineStore((s) => s.addSplit);
+  const transcript = useTranscriptStore((s) => s.transcript);
+
+  const scenes = useMemo(() => {
+    const cuts = operations.filter((op): op is CutOperation => op.type === "cut");
+    return buildScenes(duration, operations, computePlayableRanges(duration, cuts));
+  }, [duration, operations]);
+
+  const splitAt = useCallback(
+    (sourceTime: number) => {
+      const words = transcript?.segments.flatMap((s) => s.words) ?? [];
+      const t = snapToWordGap(sourceTime, words);
+      const boundaries = [0, duration, ...scenes.map((s) => s.start)];
+      if (boundaries.some((b) => Math.abs(b - t) < MIN_SCENE_SECONDS)) return false;
+      addSplit(t);
+      return true;
+    },
+    [transcript, duration, scenes, addSplit]
+  );
+
+  return { scenes, splitAt };
+}

From e270cda8bd73eb1a3e634cb90f69f3868d3f1cbb Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 00:44:55 +0530
Subject: [PATCH 04/36] feat(client): Scenes panel, scene strip and split
 shortcuts

Split at the playhead (S or the timeline button) or before any sentence
in the transcript. Scenes show as named blocks above the timeline and as
markers inline in the transcript; the Scenes panel renames, jumps to,
cuts, restores and merges them. Cmd/Ctrl+Z and Shift+Cmd/Ctrl+Z now
undo and redo from anywhere outside a text field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/components/editor/EditorLayout.tsx |   2 +
 .../src/components/editor/EditorSidebar.tsx   |   7 +-
 client/src/components/editor/ScenesPanel.tsx  | 144 ++++++++++++++++++
 .../components/editor/useEditorShortcuts.ts   |  33 ++++
 client/src/components/timeline/Timeline.tsx   |  52 ++++++-
 .../components/transcript/TranscriptPanel.tsx |  91 +++++++----
 6 files changed, 297 insertions(+), 32 deletions(-)
 create mode 100644 client/src/components/editor/ScenesPanel.tsx
 create mode 100644 client/src/components/editor/useEditorShortcuts.ts

diff --git a/client/src/components/editor/EditorLayout.tsx b/client/src/components/editor/EditorLayout.tsx
index ca5c5fe..c61a4e8 100644
--- a/client/src/components/editor/EditorLayout.tsx
+++ b/client/src/components/editor/EditorLayout.tsx
@@ -10,6 +10,7 @@ import { ExportButton } from "@/components/editor/ExportButton";
 import { ProjectNameField } from "@/components/editor/ProjectNameField";
 import { GithubLink } from "@/components/GithubLink";
 import { usePlayerStore } from "@/stores/player-store";
+import { useEditorShortcuts } from "@/components/editor/useEditorShortcuts";
 
 export function EditorLayout({ videoUrl }: { videoUrl: string }) {
   // Matches the preview's aspect box to the source video's own aspect ratio
@@ -18,6 +19,7 @@ export function EditorLayout({ videoUrl }: { videoUrl: string }) {
   // editor for non-16:9 video that the actual ffmpeg export never had,
   // since export doesn't touch aspect ratio at all.
   const aspectRatio = usePlayerStore((s) => s.aspectRatio);
+  useEditorShortcuts();
 
   return (
     <div className="flex h-screen flex-col gap-3 p-3">
diff --git a/client/src/components/editor/EditorSidebar.tsx b/client/src/components/editor/EditorSidebar.tsx
index 670fcbb..49e6d6e 100644
--- a/client/src/components/editor/EditorSidebar.tsx
+++ b/client/src/components/editor/EditorSidebar.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useEffect, useRef, useState } from "react";
-import { AudioLines, BookOpenText, Captions, ChevronLeft, Clapperboard, ChevronRight, ImagePlus, SlidersHorizontal, Sliders, Wand2 } from "lucide-react";
+import { AudioLines, BookOpenText, Captions, ChevronLeft, Clapperboard, ChevronRight, Film, ImagePlus, SlidersHorizontal, Sliders, Wand2 } from "lucide-react";
 import { AiToolsPanel } from "@/components/editor/AiToolsPanel";
 import { FiltersPanel } from "@/components/editor/FiltersPanel";
 import { PropertiesPanel } from "@/components/editor/PropertiesPanel";
@@ -10,11 +10,13 @@ import { CaptionsPanel } from "@/components/editor/CaptionsPanel";
 import { AudioPanel } from "@/components/editor/AudioPanel";
 import { PublishPanel } from "@/components/editor/PublishPanel";
 import { ClipsPanel } from "@/components/editor/ClipsPanel";
+import { ScenesPanel } from "@/components/editor/ScenesPanel";
 
-type PanelId = "captions" | "audio" | "publish" | "clips" | "ai" | "filters" | "properties" | "elements";
+type PanelId = "captions" | "scenes" | "audio" | "publish" | "clips" | "ai" | "filters" | "properties" | "elements";
 
 const TABS: { id: PanelId; label: string; icon: typeof Wand2 }[] = [
   { id: "captions", label: "Captions", icon: Captions },
+  { id: "scenes", label: "Scenes", icon: Film },
   { id: "audio", label: "Audio", icon: AudioLines },
   { id: "publish", label: "Publish", icon: BookOpenText },
   { id: "clips", label: "Clips", icon: Clapperboard },
@@ -109,6 +111,7 @@ export function EditorSidebar() {
       </div>
       <div className="flex-1 overflow-y-auto p-3">
         {activePanel === "captions" && <CaptionsPanel />}
+        {activePanel === "scenes" && <ScenesPanel />}
         {activePanel === "audio" && <AudioPanel />}
         {activePanel === "publish" && <PublishPanel />}
         {activePanel === "clips" && <ClipsPanel />}
diff --git a/client/src/components/editor/ScenesPanel.tsx b/client/src/components/editor/ScenesPanel.tsx
new file mode 100644
index 0000000..dde71b7
--- /dev/null
+++ b/client/src/components/editor/ScenesPanel.tsx
@@ -0,0 +1,144 @@
+"use client";
+
+import { useMemo } from "react";
+import { Merge, Play, RotateCcw, Scissors, Trash2 } from "lucide-react";
+import { usePlayerStore } from "@/stores/player-store";
+import { useTimelineStore } from "@/stores/timeline-store";
+import { useScenes } from "@/lib/timeline/useScenes";
+import { sceneAt, sceneColor, type Scene } from "@/lib/timeline/scenes";
+import { cutsOverlapping } from "@/lib/timeline/cuts";
+import { formatTimecode } from "@/lib/timeline/format";
+import { Button } from "@/components/ui/button";
+import type { CutOperation } from "@/types/edit-operation";
+
+/**
+ * Lists the episode's scenes -- stretches between split points -- so you
+ * can name them, jump to them, drop a whole scene, or merge it back into
+ * the one before. Everything here is ordinary edit operations (splits and
+ * cuts), so it all goes through undo/redo.
+ */
+export function ScenesPanel() {
+  const currentTime = usePlayerStore((s) => s.currentTime);
+  const seek = usePlayerStore((s) => s.seek);
+  const operations = useTimelineStore((s) => s.operations);
+  const addSplit = useTimelineStore((s) => s.addSplit);
+  const addCut = useTimelineStore((s) => s.addCut);
+  const replaceOperation = useTimelineStore((s) => s.replaceOperation);
+  const removeOperations = useTimelineStore((s) => s.removeOperations);
+  const { scenes, splitAt } = useScenes();
+
+  const cuts = useMemo(() => operations.filter((op): op is CutOperation => op.type === "cut"), [operations]);
+  const activeScene = sceneAt(scenes, currentTime);
+
+  const rename = (scene: Scene, title: string) => {
+    const split = operations.find((op) => op.id === scene.splitId);
+    if (split?.type === "split") {
+      replaceOperation(split.id, { ...split, id: crypto.randomUUID(), title, createdAt: Date.now() });
+    } else if (scene.index === 0) {
+      addSplit(0, title);
+    }
+  };
+
+  const restore = (scene: Scene) => removeOperations(cutsOverlapping(scene.start, scene.end, cuts).map((c) => c.id));
+
+  return (
+    <div className="flex flex-col gap-3 text-xs">
+      <div className="flex flex-col gap-1.5">
+        <Button size="sm" onClick={() => splitAt(currentTime)}>
+          <Scissors className="size-3.5" />
+          Split scene at playhead
+        </Button>
+        <p className="text-muted-foreground">
+          Or press <kbd className="rounded border border-border px-1 font-mono">S</kbd>. Splits land between words, never
+          inside one.
+        </p>
+      </div>
+
+      {scenes.length <= 1 ? (
+        <p className="rounded-lg border border-dashed border-border p-3 text-muted-foreground">
+          The whole episode is one scene. Split it at each topic change to name sections and drop whole segments at
+          once.
+        </p>
+      ) : (
+        <ol className="flex flex-col gap-1.5">
+          {scenes.map((scene) => {
+            const kept = scene.editedEnd - scene.editedStart;
+            const fullyCut = kept <= 0;
+            const partlyCut = !fullyCut && kept < scene.end - scene.start - 0.05;
+            const active = activeScene?.id === scene.id;
+            return (
+              <li
+                key={scene.id}
+                className={`group flex flex-col gap-1 rounded-lg border p-2 transition-colors ${
+                  active ? "border-primary bg-primary/5" : "border-border"
+                } ${fullyCut ? "opacity-60" : ""}`}
+              >
+                <div className="flex items-center gap-1.5">
+                  <span className={`size-2 shrink-0 rounded-full ${sceneColor(scene.index).dot}`} />
+                  <input
+                    key={scene.title}
+                    defaultValue={scene.title}
+                    maxLength={80}
+                    aria-label="Scene name"
+                    onKeyDown={(e) => {
+                      if (e.key === "Enter") e.currentTarget.blur();
+                      if (e.key === "Escape") {
+                        e.currentTarget.value = scene.title;
+                        e.currentTarget.blur();
+                      }
+                    }}
+                    onBlur={(e) => {
+                      const title = e.target.value.trim();
+                      if (title && title !== scene.title) rename(scene, title);
+                      else e.target.value = scene.title;
+                    }}
+                    className={`min-w-0 flex-1 rounded border border-transparent bg-transparent px-1 py-0.5 font-medium hover:border-border focus:border-primary focus:outline-none ${
+                      fullyCut ? "line-through" : ""
+                    }`}
+                  />
+                  <Button variant="ghost" size="icon-xs" onClick={() => seek(scene.start)} title="Jump to scene">
+                    <Play className="size-3" />
+                  </Button>
+                </div>
+                <div className="flex items-center justify-between gap-2 pl-3.5 text-muted-foreground">
+                  <span className="font-mono tabular-nums">
+                    {formatTimecode(scene.start)} · {formatTimecode(kept)}
+                    {partlyCut && <span className="text-destructive/80"> (trimmed)</span>}
+                  </span>
+                  <span className="flex gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 focus-within:opacity-100">
+                    {scene.index > 0 && scene.splitId && (
+                      <Button
+                        variant="ghost"
+                        size="icon-xs"
+                        onClick={() => removeOperations([scene.splitId!])}
+                        title="Merge into previous scene"
+                      >
+                        <Merge className="size-3" />
+                      </Button>
+                    )}
+                    {fullyCut || partlyCut ? (
+                      <Button variant="ghost" size="icon-xs" onClick={() => restore(scene)} title="Restore scene">
+                        <RotateCcw className="size-3" />
+                      </Button>
+                    ) : null}
+                    {!fullyCut && (
+                      <Button
+                        variant="ghost"
+                        size="icon-xs"
+                        className="hover:text-destructive"
+                        onClick={() => addCut(scene.start, scene.end, `scene: ${scene.title}`)}
+                        title="Cut this whole scene"
+                      >
+                        <Trash2 className="size-3" />
+                      </Button>
+                    )}
+                  </span>
+                </div>
+              </li>
+            );
+          })}
+        </ol>
+      )}
+    </div>
+  );
+}
diff --git a/client/src/components/editor/useEditorShortcuts.ts b/client/src/components/editor/useEditorShortcuts.ts
new file mode 100644
index 0000000..25b2331
--- /dev/null
+++ b/client/src/components/editor/useEditorShortcuts.ts
@@ -0,0 +1,33 @@
+import { useEffect } from "react";
+import { usePlayerStore } from "@/stores/player-store";
+import { useTimelineStore } from "@/stores/timeline-store";
+import { useScenes } from "@/lib/timeline/useScenes";
+
+function isTyping(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  return target.isContentEditable || ["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName);
+}
+
+/** Editor-wide keys: S splits a scene at the playhead, Cmd/Ctrl+Z undoes, Shift+Cmd/Ctrl+Z redoes. */
+export function useEditorShortcuts() {
+  const undo = useTimelineStore((s) => s.undo);
+  const redo = useTimelineStore((s) => s.redo);
+  const { splitAt } = useScenes();
+
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (isTyping(e.target)) return;
+      const mod = e.metaKey || e.ctrlKey;
+      if (mod && e.key.toLowerCase() === "z") {
+        e.preventDefault();
+        if (e.shiftKey) redo();
+        else undo();
+      } else if (!mod && !e.altKey && e.key.toLowerCase() === "s") {
+        e.preventDefault();
+        splitAt(usePlayerStore.getState().currentTime);
+      }
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [undo, redo, splitAt]);
+}
diff --git a/client/src/components/timeline/Timeline.tsx b/client/src/components/timeline/Timeline.tsx
index 2dd5617..5cbbe7a 100644
--- a/client/src/components/timeline/Timeline.tsx
+++ b/client/src/components/timeline/Timeline.tsx
@@ -16,6 +16,9 @@ import { useWaveform } from "@/lib/timeline/useWaveform";
 import { DEFAULT_INTERVAL_SECONDS, MIN_INTERVAL_SECONDS, useThumbnails } from "@/lib/timeline/useThumbnails";
 import { Button } from "@/components/ui/button";
 import { Waveform } from "@/components/timeline/Waveform";
+import { useScenes } from "@/lib/timeline/useScenes";
+import { sceneColor } from "@/lib/timeline/scenes";
+import { Scissors } from "lucide-react";
 import type { CutOperation } from "@/types/edit-operation";
 
 /** Zoom is relative to "fit" (1x = whole timeline visible, no scrolling). */
@@ -47,7 +50,9 @@ export function Timeline() {
   const operations = useTimelineStore((s) => s.operations);
   const undo = useTimelineStore((s) => s.undo);
   const redo = useTimelineStore((s) => s.redo);
+  const undoStack = useTimelineStore((s) => s.undoStack);
   const redoStack = useTimelineStore((s) => s.redoStack);
+  const { scenes, splitAt } = useScenes();
 
   const cuts = useMemo(
     () => operations.filter((op): op is CutOperation => op.type === "cut"),
@@ -129,11 +134,22 @@ export function Timeline() {
             variant="outline"
             size="xs"
             onClick={undo}
-            disabled={operations.length === 0}
+            disabled={undoStack.length === 0}
+            title="Undo (⌘Z)"
           >
             Undo
           </Button>
-          <Button variant="outline" size="xs" onClick={redo} disabled={redoStack.length === 0}>
+          <Button
+            variant="outline"
+            size="xs"
+            onClick={() => splitAt(currentTime)}
+            disabled={duration <= 0}
+            title="Split into a new scene at the playhead (S)"
+          >
+            <Scissors className="size-3" />
+            Split
+          </Button>
+          <Button variant="outline" size="xs" onClick={redo} disabled={redoStack.length === 0} title="Redo (⇧⌘Z)">
             Redo
           </Button>
           <div className="mx-1 flex items-center gap-0.5">
@@ -154,6 +170,31 @@ export function Timeline() {
           className="flex flex-col gap-2"
           style={{ width: trackWidth > 0 ? `${trackWidth}px` : "100%" }}
         >
+          {scenes.length > 1 && editedDuration > 0 && (
+            <div className="relative h-5 w-full">
+              {scenes.map((scene) => {
+                const width = scene.editedEnd - scene.editedStart;
+                if (width <= 0) return null;
+                return (
+                  <button
+                    key={scene.id}
+                    type="button"
+                    onClick={() => seek(scene.start)}
+                    title={`${scene.title} (${formatTimecode(width)})`}
+                    className={`absolute top-0 h-full truncate rounded-sm border-l-2 px-1.5 text-left text-[0.65rem] leading-5 text-foreground hover:brightness-125 ${
+                      sceneColor(scene.index).block
+                    }`}
+                    style={{
+                      left: `${(scene.editedStart / editedDuration) * 100}%`,
+                      width: `${(width / editedDuration) * 100}%`,
+                    }}
+                  >
+                    {scene.title}
+                  </button>
+                );
+              })}
+            </div>
+          )}
           <div
             ref={trackRef}
             onClick={handleTrackClick}
@@ -189,6 +230,13 @@ export function Timeline() {
                 />
               );
             })}
+            {scenes.slice(1).map((scene) => (
+              <div
+                key={scene.id}
+                className="pointer-events-none absolute top-0 h-full w-px bg-foreground/70"
+                style={{ left: `${(scene.editedStart / editedDuration) * 100}%` }}
+              />
+            ))}
             <div
               className="pointer-events-none absolute top-0 h-full w-0.5 bg-primary"
               style={{ left: `${playheadPosition}%` }}
diff --git a/client/src/components/transcript/TranscriptPanel.tsx b/client/src/components/transcript/TranscriptPanel.tsx
index 81c2131..c87b48a 100644
--- a/client/src/components/transcript/TranscriptPanel.tsx
+++ b/client/src/components/transcript/TranscriptPanel.tsx
@@ -1,7 +1,7 @@
 "use client";
 
-import { useMemo, useState } from "react";
-import { RotateCcw, Search, X } from "lucide-react";
+import { Fragment, useMemo, useState } from "react";
+import { RotateCcw, Scissors, Search, X } from "lucide-react";
 import { useTranscriptStore } from "@/stores/transcript-store";
 import { useTimelineStore } from "@/stores/timeline-store";
 import { usePlayerStore } from "@/stores/player-store";
@@ -13,6 +13,8 @@ import { SpeakersBar } from "@/components/transcript/SpeakersBar";
 import { listSpeakers, speakerColor } from "@/lib/transcript/speakers";
 import { splitIntoSentences } from "@/lib/timeline/sentences";
 import { cutsOverlapping, isWordCut, isFullyCut, padCutStart, wordSpanBounds } from "@/lib/timeline/cuts";
+import { gapBefore, sceneColor, type Scene } from "@/lib/timeline/scenes";
+import { useScenes } from "@/lib/timeline/useScenes";
 import { formatTimecode } from "@/lib/timeline/format";
 import type { CutOperation } from "@/types/edit-operation";
 import type { TranscriptSegment } from "@/types/transcript";
@@ -47,6 +49,17 @@ export function TranscriptPanel() {
     [transcript]
   );
   const fillerWordIdSet = useMemo(() => new Set(fillerWordIds), [fillerWordIds]);
+
+  const { scenes, splitAt } = useScenes();
+  /** The scene that starts right before each word, keyed by word id -- where the inline scene markers go. */
+  const sceneStartsByWordId = useMemo(() => {
+    const byWord = new Map<string, Scene>();
+    for (const scene of scenes.slice(1)) {
+      const word = allWords.find((w) => w.start >= scene.start);
+      if (word && !byWord.has(word.id)) byWord.set(word.id, scene);
+    }
+    return byWord;
+  }, [scenes, allWords]);
   const existingSpeakers = useMemo(() => listSpeakers(transcript), [transcript]);
 
   if (!transcript) return null;
@@ -232,33 +245,46 @@ export function TranscriptPanel() {
                           const matchesSearch =
                             query.trim().length > 0 &&
                             word.text.toLowerCase().includes(query.trim().toLowerCase());
+                          const sceneStart = sceneStartsByWordId.get(word.id);
                           return (
-                            <span
-                              key={word.id}
-                              onClick={(e) => {
-                                if (cut) {
-                                  handleRestore(word.start, word.end);
-                                  return;
-                                }
-                                seek(word.start);
-                                handleWordClick(word.id, e);
-                              }}
-                              title={cut ? "Click to restore" : undefined}
-                              className={[
-                                "cursor-pointer rounded px-0.5 transition-colors",
-                                cut
-                                  ? "text-muted-foreground/50 line-through decoration-destructive/70 hover:bg-muted/60"
-                                  : "",
-                                selected ? "bg-accent/30" : "",
-                                active && !cut ? "bg-primary/25" : "",
-                                filler && !cut
-                                  ? "underline decoration-dotted decoration-muted-foreground underline-offset-4"
-                                  : "",
-                                matchesSearch ? "ring-1 ring-accent/70" : "",
-                              ].join(" ")}
-                            >
-                              {word.text}{" "}
-                            </span>
+                            <Fragment key={word.id}>
+                              {sceneStart && (
+                                <button
+                                  type="button"
+                                  onClick={() => seek(sceneStart.start)}
+                                  title="Scene starts here -- rename or remove it in the Scenes panel"
+                                  className="mx-0.5 inline-flex -translate-y-px items-center gap-1 rounded-full border border-border px-1.5 align-middle text-[0.65rem] leading-4 text-muted-foreground hover:text-foreground"
+                                >
+                                  <span className={`size-1.5 rounded-full ${sceneColor(sceneStart.index).dot}`} />
+                                  {sceneStart.title}
+                                </button>
+                              )}
+                              <span
+                                onClick={(e) => {
+                                  if (cut) {
+                                    handleRestore(word.start, word.end);
+                                    return;
+                                  }
+                                  seek(word.start);
+                                  handleWordClick(word.id, e);
+                                }}
+                                title={cut ? "Click to restore" : undefined}
+                                className={[
+                                  "cursor-pointer rounded px-0.5 transition-colors",
+                                  cut
+                                    ? "text-muted-foreground/50 line-through decoration-destructive/70 hover:bg-muted/60"
+                                    : "",
+                                  selected ? "bg-accent/30" : "",
+                                  active && !cut ? "bg-primary/25" : "",
+                                  filler && !cut
+                                    ? "underline decoration-dotted decoration-muted-foreground underline-offset-4"
+                                    : "",
+                                  matchesSearch ? "ring-1 ring-accent/70" : "",
+                                ].join(" ")}
+                              >
+                                {word.text}{" "}
+                              </span>
+                            </Fragment>
                           );
                         })}
                         {sentenceFullyCut ? (
@@ -278,6 +304,15 @@ export function TranscriptPanel() {
                             <X className="size-3" />
                           </button>
                         )}
+                        {!sceneStartsByWordId.has(sentence.words[0].id) && (
+                          <button
+                            onClick={() => splitAt(gapBefore(sentence.start, allWords))}
+                            className="hidden size-4 -translate-y-px items-center justify-center rounded text-muted-foreground hover:text-foreground group-hover/sentence:inline-flex"
+                            title="Start a new scene at this sentence"
+                          >
+                            <Scissors className="size-3" />
+                          </button>
+                        )}
                       </span>
                     );
                   })}

From 3def289baf844e65e688ebfb06d449e6bdc59ecb Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 00:58:47 +0530
Subject: [PATCH 05/36] fix(render): stop dropping footage after every cut on
 ffmpeg 9

Cuts are joined with a chain of 30ms xfades. On ffmpeg 9 (9.0.2, the
current Homebrew ffmpeg-full the Mac app uses), xfade discards the second
input's frames before its offset instead of holding them, so every
segment after a cut started late: a 2s + 10s join rendered 10.0s long,
with the second segment's first ~2s missing, and the loss compounded
with each cut. Audio (acrossfade) was unaffected, so exports also drifted
out of sync.

Pinning each trimmed segment to the source's frame rate with fps= makes
the join land where the offset says: the same join renders 11.98s, and a
three-segment export's frames match the source at every segment start.
The render now always probes the source's rate (probeVideoStream), which
also provides the size the logo and caption layout needed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 server/src/lib/ffmpeg/plan.test.ts  | 11 ++++++++---
 server/src/lib/ffmpeg/plan.ts       | 19 ++++++++++++++++++-
 server/src/lib/ffmpeg/probe.test.ts | 16 ++++++++++++++++
 server/src/lib/ffmpeg/probe.ts      | 29 +++++++++++++++++++++++++----
 server/src/lib/ffmpeg/render-job.ts | 17 ++++++++---------
 5 files changed, 75 insertions(+), 17 deletions(-)
 create mode 100644 server/src/lib/ffmpeg/probe.test.ts

diff --git a/server/src/lib/ffmpeg/plan.test.ts b/server/src/lib/ffmpeg/plan.test.ts
index 1bd27e2..156958e 100644
--- a/server/src/lib/ffmpeg/plan.test.ts
+++ b/server/src/lib/ffmpeg/plan.test.ts
@@ -8,9 +8,14 @@ const baseArgs = {
   outputPath: "/data/out.mp4",
   playableRanges: [{ start: 0, end: 10 }],
   filterId: "none",
+  frameRate: "30000/1001",
 };
 
 describe("buildRenderArgs: validation", () => {
+  it("rejects a frame rate that isn't a plain number or ratio", () => {
+    expect(() => buildRenderArgs({ ...baseArgs, frameRate: "30,drawtext=x" })).toThrow(/Invalid frame rate/);
+  });
+
   it("throws when the entire video has been cut (no playable ranges)", () => {
     expect(() => buildRenderArgs({ ...baseArgs, playableRanges: [] })).toThrow(/entire video has been cut/);
   });
@@ -52,7 +57,7 @@ describe("buildRenderArgs: basic structure", () => {
   it("trims a single range and maps it straight to [outv]/[outa]", () => {
     const argv = buildRenderArgs(baseArgs);
     const filterComplex = argv[argv.indexOf("-filter_complex") + 1];
-    expect(filterComplex).toContain("[0:v]trim=start=0.000:end=10.000,setpts=PTS-STARTPTS[v0]");
+    expect(filterComplex).toContain("[0:v]trim=start=0.000:end=10.000,setpts=PTS-STARTPTS,fps=30000/1001[v0]");
     expect(filterComplex).toContain("[0:a]atrim=start=0.000:end=10.000,asetpts=PTS-STARTPTS[a0]");
     expect(filterComplex).toContain("[v0]null[outv]");
     expect(filterComplex).toContain("[a0]anull[outa]");
@@ -67,8 +72,8 @@ describe("buildRenderArgs: basic structure", () => {
       ],
     });
     const filterComplex = argv[argv.indexOf("-filter_complex") + 1];
-    expect(filterComplex).toContain("[0:v]trim=start=0.000:end=3.000,setpts=PTS-STARTPTS[v0]");
-    expect(filterComplex).toContain("[0:v]trim=start=5.000:end=8.000,setpts=PTS-STARTPTS[v1]");
+    expect(filterComplex).toContain("[0:v]trim=start=0.000:end=3.000,setpts=PTS-STARTPTS,fps=30000/1001[v0]");
+    expect(filterComplex).toContain("[0:v]trim=start=5.000:end=8.000,setpts=PTS-STARTPTS,fps=30000/1001[v1]");
     // Both 3s segments comfortably fit the default 0.03s crossfade: offset
     // is the first segment's own length (3.0) minus that 0.03s.
     expect(filterComplex).toContain("[v0][v1]xfade=transition=fade:duration=0.030:offset=2.970[outv]");
diff --git a/server/src/lib/ffmpeg/plan.ts b/server/src/lib/ffmpeg/plan.ts
index b955e7e..7c4f980 100644
--- a/server/src/lib/ffmpeg/plan.ts
+++ b/server/src/lib/ffmpeg/plan.ts
@@ -263,6 +263,12 @@ export function buildRenderArgs(args: {
    * callers pass the output size as videoWidth/videoHeight.
    */
   reframe?: { width: number; height: number; cropX: number };
+  /**
+   * The source's frame rate as ffprobe reports it ("30000/1001", from
+   * probe.ts#probeVideoStream). Every segment is pinned to it before the
+   * xfade joins -- see the comment where it's applied.
+   */
+  frameRate: string;
 }): string[] {
   const {
     inputPath,
@@ -282,13 +288,24 @@ export function buildRenderArgs(args: {
     audioFilter,
     metadataPath,
     reframe,
+    frameRate,
   } = args;
 
   assertValidRanges(playableRanges);
+  if (!/^\d{1,6}(\/\d{1,6})?$/.test(frameRate)) throw new Error(`Invalid frame rate: ${frameRate}`);
 
+  // fps= pins each trimmed segment to the source's frame rate. Without it,
+  // xfade on ffmpeg 9 drops the start of every segment after a join: the
+  // second input's frames before `offset` are consumed and discarded instead
+  // of being held until the transition, so each cut silently lost footage
+  // (measured on 9.0.2: a 2s + 10s join came out 10.0s long, the second
+  // segment starting ~2s late). With an explicit rate on both inputs the
+  // join lands where the offset says (11.98s, correct frames).
   const filterChains: string[] = [];
   playableRanges.forEach((r, i) => {
-    filterChains.push(`[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS[v${i}]`);
+    filterChains.push(
+      `[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS,fps=${frameRate}[v${i}]`
+    );
   });
 
   if (playableRanges.length === 1) {
diff --git a/server/src/lib/ffmpeg/probe.test.ts b/server/src/lib/ffmpeg/probe.test.ts
new file mode 100644
index 0000000..325703d
--- /dev/null
+++ b/server/src/lib/ffmpeg/probe.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { normalizeFrameRate } from "@/lib/ffmpeg/probe";
+
+describe("normalizeFrameRate", () => {
+  it("keeps ffprobe's rational rate as-is", () => {
+    expect(normalizeFrameRate("30000/1001")).toBe("30000/1001");
+    expect(normalizeFrameRate("25/1")).toBe("25/1");
+  });
+
+  it("falls back to 30 for a missing, zero or implausible rate", () => {
+    expect(normalizeFrameRate(undefined)).toBe("30");
+    expect(normalizeFrameRate("0/0")).toBe("30");
+    expect(normalizeFrameRate("90000/1")).toBe("30");
+    expect(normalizeFrameRate("30;evil")).toBe("30");
+  });
+});
diff --git a/server/src/lib/ffmpeg/probe.ts b/server/src/lib/ffmpeg/probe.ts
index 359c6f4..bdcce9d 100644
--- a/server/src/lib/ffmpeg/probe.ts
+++ b/server/src/lib/ffmpeg/probe.ts
@@ -17,7 +17,18 @@ export class FfprobeNotFoundError extends Error {
  * The binary defaults to `ffprobe` on PATH, overridable with FFPROBE_PATH --
  * mirrors FFMPEG_PATH in ffmpeg/run.ts.
  */
-export function probeVideoDimensions(inputPath: string): Promise<{ width: number; height: number }> {
+export async function probeVideoDimensions(inputPath: string): Promise<{ width: number; height: number }> {
+  const { width, height } = await probeVideoStream(inputPath);
+  return { width, height };
+}
+
+/**
+ * Width, height and frame rate of the first video stream. The rate is
+ * ffprobe's r_frame_rate as a rational string ("30000/1001"), passed to
+ * ffmpeg as-is so every segment of a render runs at exactly the source's
+ * rate (lib/ffmpeg/plan.ts).
+ */
+export function probeVideoStream(inputPath: string): Promise<{ width: number; height: number; fps: string }> {
   const binary = process.env.FFPROBE_PATH || "ffprobe";
   const args = [
     "-v",
@@ -25,7 +36,7 @@ export function probeVideoDimensions(inputPath: string): Promise<{ width: number
     "-select_streams",
     "v:0",
     "-show_entries",
-    "stream=width,height",
+    "stream=width,height,r_frame_rate",
     "-of",
     "json",
     inputPath,
@@ -44,13 +55,15 @@ export function probeVideoDimensions(inputPath: string): Promise<{ width: number
         return;
       }
       try {
-        const parsed = JSON.parse(stdout) as { streams?: { width?: number; height?: number }[] };
+        const parsed = JSON.parse(stdout) as {
+          streams?: { width?: number; height?: number; r_frame_rate?: string }[];
+        };
         const stream = parsed.streams?.[0];
         if (!stream?.width || !stream?.height) {
           reject(new Error(`ffprobe returned no video stream dimensions for ${inputPath}.`));
           return;
         }
-        resolve({ width: stream.width, height: stream.height });
+        resolve({ width: stream.width, height: stream.height, fps: normalizeFrameRate(stream.r_frame_rate) });
       } catch {
         reject(new Error(`Could not parse ffprobe output for ${inputPath}.`));
       }
@@ -58,6 +71,14 @@ export function probeVideoDimensions(inputPath: string): Promise<{ width: number
   });
 }
 
+/** A usable "num/den" rate, or 30 when ffprobe reports none (or 0/0, as it does for some still images). */
+export function normalizeFrameRate(rate: string | undefined): string {
+  const match = rate?.match(/^(\d{1,6})\/(\d{1,6})$/);
+  if (!match || Number(match[1]) === 0 || Number(match[2]) === 0) return "30";
+  const fps = Number(match[1]) / Number(match[2]);
+  return fps > 0 && fps <= 240 ? `${match[1]}/${match[2]}` : "30";
+}
+
 /**
  * Reads a media file's container duration in seconds via ffprobe -- used to
  * plan transcription chunks over the extracted audio track.
diff --git a/server/src/lib/ffmpeg/render-job.ts b/server/src/lib/ffmpeg/render-job.ts
index 82f7152..2ee037f 100644
--- a/server/src/lib/ffmpeg/render-job.ts
+++ b/server/src/lib/ffmpeg/render-job.ts
@@ -22,7 +22,7 @@ import {
 } from "@/lib/ffmpeg/audio-filters";
 import { parseStoredAudioSettings } from "@/lib/validation/audio-settings";
 import { runFfmpeg, runFfmpegCapturingStderr } from "@/lib/ffmpeg/run";
-import { probeVideoDimensions } from "@/lib/ffmpeg/probe";
+import { probeVideoStream } from "@/lib/ffmpeg/probe";
 import { generateCaptions, splitCuesForShorts } from "@/lib/captions/generate";
 import { toAssKaraoke, toSrt } from "@/lib/captions/format";
 import { DEFAULT_CAPTION_STYLE, type CaptionStyle } from "@/lib/captions/style";
@@ -196,14 +196,12 @@ export async function runRenderJob(
     const captionStyle = clip ? shortsCaptionStyle(project.captionStyleJson) : options.captionStyle;
     const useKaraoke = burnInCaptions && captionStyle?.wordHighlight === true;
 
-    // Needed to size the logo overlay relative to the frame, and to convert
-    // force_style's fontSize/margin from percent-of-frame into the literal
-    // output pixels it actually requires (see ffmpeg/plan.ts) -- skip the
-    // probe when neither applies. The karaoke .ass path doesn't need this:
-    // it scales itself via PlayResX/Y instead (see lib/captions/format.ts).
-    // A clip's output size is known up front; no probe needed.
-    const needsVideoDimensions = !clipFrame && (useLogo || (burnInCaptions && !useKaraoke));
-    const videoDimensions = clipFrame ?? (needsVideoDimensions ? await probeVideoDimensions(inputPath) : undefined);
+    // Every video render needs the source's frame rate (see ffmpeg/plan.ts).
+    // The same probe gives its size, which sizes the logo overlay and
+    // converts force_style's percent-of-frame font size/margin into output
+    // pixels. A clip's output size is known up front, so it's used instead.
+    const sourceStream = isVideo ? await probeVideoStream(inputPath) : undefined;
+    const videoDimensions = clipFrame ?? sourceStream;
 
     if (burnInCaptions) {
       if (!project.transcript) throw new Error("Captions were requested but this project has no transcript.");
@@ -268,6 +266,7 @@ export async function runRenderJob(
           audioFilter,
           metadataPath,
           reframe: clip && clipFrame ? { ...clipFrame, cropX: clip.cropX } : undefined,
+          frameRate: sourceStream!.fps,
         })
       : buildAudioOnlyRenderArgs({ inputPath, outputPath, playableRanges, audioFilter, format, metadataPath });
     await runFfmpeg(args);

From 036b493f07f26b4735eb585d91ec0818ba2ea0da Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:01:51 +0530
Subject: [PATCH 06/36] fix(render): pad segments so a short one can't end the
 export early

Each trimmed segment is a whole number of frames, so it can come out up
to a frame shorter than the length the xfade offsets assume. When the
stream joined so far runs out before its next join's transition ends,
ffmpeg 9 ends that join there and every segment after it is lost --
measured: a 5s + 10s + 2s chain rendered 14.9s with the last segment
missing.

Every segment but the last now gets 0.1s of cloned frames (tpad). xfade
drops the first input's frames after the transition, so the padding
never reaches the output: a four-segment export now renders 15.88s video
against 15.91s audio (within a frame), and the same three-segment chain
renders all 16.95s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 server/src/lib/ffmpeg/plan.test.ts |  4 +++-
 server/src/lib/ffmpeg/plan.ts      | 14 +++++++++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/server/src/lib/ffmpeg/plan.test.ts b/server/src/lib/ffmpeg/plan.test.ts
index 156958e..bfbd447 100644
--- a/server/src/lib/ffmpeg/plan.test.ts
+++ b/server/src/lib/ffmpeg/plan.test.ts
@@ -72,7 +72,9 @@ describe("buildRenderArgs: basic structure", () => {
       ],
     });
     const filterComplex = argv[argv.indexOf("-filter_complex") + 1];
-    expect(filterComplex).toContain("[0:v]trim=start=0.000:end=3.000,setpts=PTS-STARTPTS,fps=30000/1001[v0]");
+    expect(filterComplex).toContain(
+      "[0:v]trim=start=0.000:end=3.000,setpts=PTS-STARTPTS,fps=30000/1001,tpad=stop_mode=clone:stop_duration=0.1[v0]"
+    );
     expect(filterComplex).toContain("[0:v]trim=start=5.000:end=8.000,setpts=PTS-STARTPTS,fps=30000/1001[v1]");
     // Both 3s segments comfortably fit the default 0.03s crossfade: offset
     // is the first segment's own length (3.0) minus that 0.03s.
diff --git a/server/src/lib/ffmpeg/plan.ts b/server/src/lib/ffmpeg/plan.ts
index 7c4f980..132af5f 100644
--- a/server/src/lib/ffmpeg/plan.ts
+++ b/server/src/lib/ffmpeg/plan.ts
@@ -30,6 +30,9 @@ import type { VideoProperties } from "@/types/video-properties";
  */
 const CUT_CROSSFADE_SECONDS = 0.03;
 
+/** Cloned frames after each segment but the last; see buildRenderArgs. */
+const SEGMENT_TAIL_PAD = "tpad=stop_mode=clone:stop_duration=0.1";
+
 /** Percent of frame width/height, not raw pixels -- see lib/video/logo.ts. */
 function clampPaddingPercent(v: number): number {
   return Math.min(LOGO_PADDING_MAX_PERCENT, Math.max(LOGO_PADDING_MIN_PERCENT, v));
@@ -301,10 +304,19 @@ export function buildRenderArgs(args: {
   // (measured on 9.0.2: a 2s + 10s join came out 10.0s long, the second
   // segment starting ~2s late). With an explicit rate on both inputs the
   // join lands where the offset says (11.98s, correct frames).
+  //
+  // tpad= then pads every segment but the last with a few cloned frames. A
+  // segment is a whole number of frames, so it can end up to a frame short
+  // of the length the offsets assume; when the stream built so far runs out
+  // before its join's transition finishes, ffmpeg 9 ends the join there and
+  // everything after it is lost (measured: a 5s + 10s + 2s chain came out
+  // 14.9s, the last segment gone). xfade discards the first input's frames
+  // after the transition, so the padding never reaches the output.
   const filterChains: string[] = [];
   playableRanges.forEach((r, i) => {
+    const pad = i < playableRanges.length - 1 ? `,${SEGMENT_TAIL_PAD}` : "";
     filterChains.push(
-      `[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS,fps=${frameRate}[v${i}]`
+      `[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS,fps=${frameRate}${pad}[v${i}]`
     );
   });
 

From c69354fa9e60de34203f753cfeb9bd5d976a3d17 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:25:07 +0530
Subject: [PATCH 07/36] feat: add a card operation for title cards

A card is a full-screen title card inserted into the program before the
content at its source time: a scene start, 0 for an intro, the duration
for an outro. It carries a template (title, chapter, quote, outro), a
title and optional subtitle, 1-10s on screen and a solid background.

Card text is burned in through a generated ASS file, so the schema
refuses braces, backslashes and control characters -- they'd be read as
override tags or break the event line. The route rejects a card placed
past the end of the video.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/types/edit-operation.ts            | 25 +++++++++++++++
 .../src/lib/validation/edit-operation.test.ts | 31 ++++++++++++++++++
 server/src/lib/validation/edit-operation.ts   | 32 +++++++++++++++++++
 server/src/routes/operations.ts               |  4 +++
 server/src/types/edit-operation.ts            | 25 +++++++++++++++
 5 files changed, 117 insertions(+)

diff --git a/client/src/types/edit-operation.ts b/client/src/types/edit-operation.ts
index 150cf9d..62dd558 100644
--- a/client/src/types/edit-operation.ts
+++ b/client/src/types/edit-operation.ts
@@ -35,6 +35,23 @@ export type EditOperation =
       title?: string;
       source?: SplitSource;
     })
+  | (OperationBase & {
+      /**
+       * A full-screen title card inserted into the program -- time that
+       * isn't in the source. `at` is the source time it plays before:
+       * usually a scene boundary, 0 for an intro, or the source duration
+       * for an outro. See lib/timeline/program.ts for placement.
+       */
+      type: "card";
+      at: number;
+      /** Seconds on screen. */
+      duration: number;
+      template: CardTemplate;
+      title: string;
+      subtitle?: string;
+      /** '#RRGGBB' */
+      background: string;
+    })
   | (OperationBase & {
       type: "caption";
       text: string;
@@ -42,5 +59,13 @@ export type EditOperation =
       end: number;
     });
 
+export const CARD_TEMPLATES = ["title", "chapter", "quote", "outro"] as const;
+export type CardTemplate = (typeof CARD_TEMPLATES)[number];
+export const CARD_MIN_SECONDS = 1;
+export const CARD_MAX_SECONDS = 10;
+export const CARD_TITLE_MAX = 80;
+export const CARD_SUBTITLE_MAX = 120;
+
 export type CutOperation = Extract<EditOperation, { type: "cut" }>;
 export type SplitOperation = Extract<EditOperation, { type: "split" }>;
+export type CardOperation = Extract<EditOperation, { type: "card" }>;
diff --git a/server/src/lib/validation/edit-operation.test.ts b/server/src/lib/validation/edit-operation.test.ts
index 167da60..5de8ceb 100644
--- a/server/src/lib/validation/edit-operation.test.ts
+++ b/server/src/lib/validation/edit-operation.test.ts
@@ -97,4 +97,35 @@ describe("editOperationSchema", () => {
     expect(editOperationSchema.safeParse({ ...base, title: "x".repeat(81) }).success).toBe(false);
     expect(editOperationSchema.safeParse({ ...base, source: "robot" }).success).toBe(false);
   });
+
+  describe("card", () => {
+    const card = {
+      id: "c1",
+      type: "card",
+      at: 30,
+      duration: 3,
+      template: "chapter",
+      title: "Part 2: Pricing",
+      subtitle: "What it really costs",
+      background: "#101820",
+      createdAt: 0,
+    };
+
+    it("accepts a valid card", () => {
+      expect(editOperationSchema.safeParse(card).success).toBe(true);
+    });
+
+    it("rejects out-of-range durations, unknown templates and bad colors", () => {
+      expect(editOperationSchema.safeParse({ ...card, duration: 0.5 }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...card, duration: 11 }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...card, template: "spinning" }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...card, background: "red" }).success).toBe(false);
+    });
+
+    it("rejects an empty title and text that would be read as ASS override tags", () => {
+      expect(editOperationSchema.safeParse({ ...card, title: "   " }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...card, title: "{\\fs200}Big" }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...card, subtitle: "two\nlines" }).success).toBe(false);
+    });
+  });
 });
diff --git a/server/src/lib/validation/edit-operation.ts b/server/src/lib/validation/edit-operation.ts
index 05b3060..df1db89 100644
--- a/server/src/lib/validation/edit-operation.ts
+++ b/server/src/lib/validation/edit-operation.ts
@@ -1,4 +1,24 @@
 import { z } from "zod";
+import {
+  CARD_MAX_SECONDS,
+  CARD_MIN_SECONDS,
+  CARD_SUBTITLE_MAX,
+  CARD_TEMPLATES,
+  CARD_TITLE_MAX,
+} from "@/types/edit-operation";
+
+/**
+ * Card text is burned in through a generated ASS file: braces and
+ * backslashes would be read as override tags, and control characters or
+ * newlines would break the event line. The client strips these before
+ * sending; the server refuses anything that slips through.
+ */
+const cardText = (max: number) =>
+  z
+    .string()
+    .trim()
+    .max(max)
+    .refine((s) => !/[{}\\\u0000-\u001f\u007f]/.test(s), "Card text can't contain braces, backslashes or line breaks.");
 
 /**
  * Mirrors the EditOperation union in types/edit-operation.ts. The client
@@ -34,6 +54,18 @@ export const editOperationSchema = z.discriminatedUnion("type", [
     createdAt: z.number(),
     groupId: z.string().min(1).max(100).optional(),
   }),
+  z.object({
+    id: z.string().min(1),
+    type: z.literal("card"),
+    at: z.number().nonnegative(),
+    duration: z.number().min(CARD_MIN_SECONDS).max(CARD_MAX_SECONDS),
+    template: z.enum(CARD_TEMPLATES),
+    title: cardText(CARD_TITLE_MAX).pipe(z.string().min(1)),
+    subtitle: cardText(CARD_SUBTITLE_MAX).optional(),
+    background: z.string().regex(/^#[0-9a-fA-F]{6}$/),
+    createdAt: z.number(),
+    groupId: z.string().min(1).max(100).optional(),
+  }),
   z.object({
     id: z.string().min(1),
     type: z.literal("caption"),
diff --git a/server/src/routes/operations.ts b/server/src/routes/operations.ts
index 1fa4850..b42e8f8 100644
--- a/server/src/routes/operations.ts
+++ b/server/src/routes/operations.ts
@@ -33,6 +33,10 @@ operationsRoute.post("/:id/operations", async (c) => {
   if (op.type === "split" && project.duration && op.timestamp >= project.duration) {
     return errorResponse(c, "INVALID_OPERATION", "Split must fall inside the video.", 400);
   }
+  // A card at the duration is an outro; past it there's nothing to play before.
+  if (op.type === "card" && project.duration && op.at > project.duration) {
+    return errorResponse(c, "INVALID_OPERATION", "Card must be placed inside the video.", 400);
+  }
 
   // Client generates the id (needed so undo/redo can address the exact row);
   // upsert so a redo that restores a previously-undone op is idempotent.
diff --git a/server/src/types/edit-operation.ts b/server/src/types/edit-operation.ts
index 150cf9d..62dd558 100644
--- a/server/src/types/edit-operation.ts
+++ b/server/src/types/edit-operation.ts
@@ -35,6 +35,23 @@ export type EditOperation =
       title?: string;
       source?: SplitSource;
     })
+  | (OperationBase & {
+      /**
+       * A full-screen title card inserted into the program -- time that
+       * isn't in the source. `at` is the source time it plays before:
+       * usually a scene boundary, 0 for an intro, or the source duration
+       * for an outro. See lib/timeline/program.ts for placement.
+       */
+      type: "card";
+      at: number;
+      /** Seconds on screen. */
+      duration: number;
+      template: CardTemplate;
+      title: string;
+      subtitle?: string;
+      /** '#RRGGBB' */
+      background: string;
+    })
   | (OperationBase & {
       type: "caption";
       text: string;
@@ -42,5 +59,13 @@ export type EditOperation =
       end: number;
     });
 
+export const CARD_TEMPLATES = ["title", "chapter", "quote", "outro"] as const;
+export type CardTemplate = (typeof CARD_TEMPLATES)[number];
+export const CARD_MIN_SECONDS = 1;
+export const CARD_MAX_SECONDS = 10;
+export const CARD_TITLE_MAX = 80;
+export const CARD_SUBTITLE_MAX = 120;
+
 export type CutOperation = Extract<EditOperation, { type: "cut" }>;
 export type SplitOperation = Extract<EditOperation, { type: "split" }>;
+export type CardOperation = Extract<EditOperation, { type: "card" }>;

From b5fd6a4691c196fe0cba6a7c6f668d31a2dee307 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:25:07 +0530
Subject: [PATCH 08/36] feat: program timeline model for title cards

Cards add time that isn't in the source, so edited time (source minus
cuts) is no longer what plays. program.ts places each card on the edited
timeline and maps edited time to program time (edited plus cards), so
everything that already works in edited time -- captions, chapters --
shifts into program time without knowing about cards, and cuts and cards
compose. A card whose whole scene is cut goes with it, rather than
announcing the next scene; intro and outro cards always stay.

With no cards the program is exactly the playable ranges, so nothing
changes for existing projects. Duplicated across client and server like
cuts.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/lib/timeline/program.test.ts | 127 +++++++++++++++++
 client/src/lib/timeline/program.ts      | 178 ++++++++++++++++++++++++
 server/src/lib/timeline/program.test.ts | 127 +++++++++++++++++
 server/src/lib/timeline/program.ts      | 178 ++++++++++++++++++++++++
 4 files changed, 610 insertions(+)
 create mode 100644 client/src/lib/timeline/program.test.ts
 create mode 100644 client/src/lib/timeline/program.ts
 create mode 100644 server/src/lib/timeline/program.test.ts
 create mode 100644 server/src/lib/timeline/program.ts

diff --git a/client/src/lib/timeline/program.test.ts b/client/src/lib/timeline/program.test.ts
new file mode 100644
index 0000000..5f0b449
--- /dev/null
+++ b/client/src/lib/timeline/program.test.ts
@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildProgramItems,
+  cardStartTimes,
+  cardsDuration,
+  editedRangeToProgram,
+  editedToProgramTime,
+  locateProgramTime,
+  placeCards,
+} from "@/lib/timeline/program";
+import { computePlayableRanges } from "@/lib/timeline/cuts";
+import type { CardOperation, CutOperation, EditOperation } from "@/types/edit-operation";
+
+const card = (id: string, at: number, duration = 3, createdAt = 0): CardOperation => ({
+  id,
+  type: "card",
+  at,
+  duration,
+  template: "title",
+  title: id,
+  background: "#000000",
+  createdAt,
+});
+const cut = (start: number, end: number): CutOperation => ({ id: `cut-${start}`, type: "cut", start, end, createdAt: 0 });
+const split = (timestamp: number): EditOperation => ({ id: `split-${timestamp}`, type: "split", timestamp, createdAt: 0 });
+
+function program(ops: EditOperation[], duration = 100) {
+  const ranges = computePlayableRanges(
+    duration,
+    ops.filter((op): op is CutOperation => op.type === "cut")
+  );
+  const slots = placeCards(ops, ranges, duration);
+  return { ranges, slots, items: buildProgramItems(ranges, slots) };
+}
+
+describe("program without cards", () => {
+  it("is exactly the playable ranges, with no time shift", () => {
+    const { ranges, slots, items } = program([cut(10, 20), split(50)]);
+    expect(slots).toEqual([]);
+    expect(items).toEqual(ranges.map((r) => ({ kind: "source", ...r })));
+    expect(editedToProgramTime(42, slots)).toBe(42);
+  });
+});
+
+describe("placeCards", () => {
+  it("places an intro, a mid-episode card and an outro in play order", () => {
+    const { slots } = program([card("outro", 100), card("mid", 40), card("intro", 0)]);
+    expect(slots.map((s) => [s.card.id, s.editedAt, s.resumeAt])).toEqual([
+      ["intro", 0, 0],
+      ["mid", 40, 40],
+      ["outro", 100, 100],
+    ]);
+  });
+
+  it("moves a card whose moment was cut to the next kept content", () => {
+    const { slots } = program([cut(35, 45), card("mid", 40)]);
+    expect(slots[0]).toMatchObject({ editedAt: 35, resumeAt: 45 });
+  });
+
+  it("drops a card whose whole scene was cut, but keeps intro and outro", () => {
+    const { slots } = program([split(40), split(60), cut(40, 60), card("gone", 40), card("intro", 0), card("outro", 100)]);
+    expect(slots.map((s) => s.card.id)).toEqual(["intro", "outro"]);
+  });
+
+  it("keeps cards at the same moment in creation order", () => {
+    const { slots } = program([card("second", 40, 3, 2), card("first", 40, 3, 1)]);
+    expect(slots.map((s) => s.card.id)).toEqual(["first", "second"]);
+  });
+});
+
+describe("buildProgramItems", () => {
+  it("splits the source range where a card is inserted", () => {
+    const { items } = program([card("intro", 0, 2), card("mid", 40, 3), cut(80, 100), card("outro", 100, 4)]);
+    expect(items).toEqual([
+      { kind: "card", card: expect.objectContaining({ id: "intro" }) },
+      { kind: "source", start: 0, end: 40 },
+      { kind: "card", card: expect.objectContaining({ id: "mid" }) },
+      { kind: "source", start: 40, end: 80 },
+      { kind: "card", card: expect.objectContaining({ id: "outro" }) },
+    ]);
+  });
+});
+
+describe("time mapping", () => {
+  const { slots } = program([card("intro", 0, 2), card("mid", 40, 3)]);
+
+  it("shifts edited time by every card before it", () => {
+    expect(cardsDuration(slots)).toBe(5);
+    expect(editedToProgramTime(10, slots)).toBe(12);
+    expect(editedToProgramTime(50, slots)).toBe(55);
+  });
+
+  it("puts content at a card's moment after the card, and chapter markers at its start", () => {
+    expect(editedToProgramTime(40, slots)).toBe(45);
+    expect(editedToProgramTime(40, slots, { includeCardsAtPoint: false })).toBe(42);
+    expect(editedToProgramTime(0, slots, { includeCardsAtPoint: false })).toBe(0);
+  });
+
+  it("locates program time inside a card or back on the edited timeline", () => {
+    expect(locateProgramTime(1, slots)).toMatchObject({ card: { card: { id: "intro" } }, cardOffset: 1 });
+    expect(locateProgramTime(12, slots)).toMatchObject({ card: null, editedTime: 10 });
+    expect(locateProgramTime(43.5, slots)).toMatchObject({ card: { card: { id: "mid" } }, cardOffset: 1.5 });
+    expect(locateProgramTime(55, slots)).toMatchObject({ card: null, editedTime: 50 });
+  });
+
+  it("round-trips edited -> program -> edited outside cards", () => {
+    for (const t of [0.5, 20, 39.9, 40.1, 99]) {
+      expect(locateProgramTime(editedToProgramTime(t, slots), slots).editedTime).toBeCloseTo(t);
+    }
+  });
+});
+
+describe("editedRangeToProgram and cardStartTimes", () => {
+  const { slots, items } = program([card("intro", 0, 2), card("mid", 40, 3)]);
+
+  it("keeps a span that ends where a card starts from running over the card", () => {
+    expect(editedRangeToProgram(38, 40, slots)).toEqual({ start: 40, end: 42 });
+    expect(editedRangeToProgram(40, 41, slots)).toEqual({ start: 45, end: 46 });
+  });
+
+  it("lists each card's start on the program timeline", () => {
+    expect(cardStartTimes(items).map((c) => [c.card.id, c.start])).toEqual([
+      ["intro", 0],
+      ["mid", 42],
+    ]);
+  });
+});
diff --git a/client/src/lib/timeline/program.ts b/client/src/lib/timeline/program.ts
new file mode 100644
index 0000000..2219864
--- /dev/null
+++ b/client/src/lib/timeline/program.ts
@@ -0,0 +1,178 @@
+import type { CardOperation, EditOperation, SplitOperation } from "@/types/edit-operation";
+import type { PlayableRange } from "@/types/timeline";
+import { nextPlayableTime, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
+
+/**
+ * The "program" is what actually plays: the kept source ranges with title
+ * cards inserted between them. Cards add time that isn't in the source, so
+ * three clocks exist:
+ *
+ *   source time  -- the original video (transcript, cuts, splits, cards' `at`)
+ *   edited time  -- source with cuts removed (lib/timeline/cuts.ts)
+ *   program time -- edited time with cards inserted (what renders)
+ *
+ * Everything that already works in edited time (captions, chapters) shifts
+ * into program time through editedToProgramTime, so cuts and cards compose
+ * without either knowing about the other. Duplicated, not imported, across
+ * the client/server boundary like cuts.ts -- keep both copies identical.
+ */
+
+const EPSILON = 0.001;
+
+/** A card placed on the edited timeline. */
+export type CardSlot = {
+  card: CardOperation;
+  /** Edited time the card plays at (before the source content there). */
+  editedAt: number;
+  /** Source time playback resumes at once the card has played. */
+  resumeAt: number;
+};
+
+export type ProgramItem =
+  | { kind: "source"; start: number; end: number }
+  | { kind: "card"; card: CardOperation };
+
+export function cardOperations(operations: EditOperation[]): CardOperation[] {
+  return operations.filter((op): op is CardOperation => op.type === "card");
+}
+
+function splitTimes(operations: EditOperation[]): number[] {
+  return operations
+    .filter((op): op is SplitOperation => op.type === "split" && op.timestamp > 0)
+    .map((op) => op.timestamp)
+    .sort((a, b) => a - b);
+}
+
+/**
+ * Places each card on the edited timeline, in play order.
+ *
+ * A card plays before the content at its `at` time; if that moment was
+ * cut, before the next content that wasn't. A card belongs to the scene
+ * starting at `at`, so when that whole scene is cut its card goes too --
+ * otherwise cutting "Part 2" would leave its title card announcing Part 3.
+ * Intro (at 0) and outro (at the end) cards always stay.
+ */
+export function placeCards(
+  operations: EditOperation[],
+  ranges: PlayableRange[],
+  sourceDuration: number
+): CardSlot[] {
+  const splits = splitTimes(operations);
+  const editedDuration = ranges.reduce((sum, r) => sum + (r.end - r.start), 0);
+
+  const slots: CardSlot[] = [];
+  for (const card of cardOperations(operations)) {
+    const isOutro = card.at >= sourceDuration - EPSILON;
+    const isIntro = card.at <= EPSILON;
+    if (!isIntro && !isOutro) {
+      const sceneEnd = splits.find((t) => t > card.at + EPSILON) ?? sourceDuration;
+      const sceneHasContent = ranges.some((r) => r.start < sceneEnd && r.end > card.at);
+      if (!sceneHasContent) continue;
+    }
+    const resumeAt = isOutro ? null : nextPlayableTime(card.at, ranges);
+    slots.push(
+      resumeAt === null
+        ? { card, editedAt: editedDuration, resumeAt: sourceDuration }
+        : { card, editedAt: sourceTimeToEditedTime(resumeAt, ranges), resumeAt }
+    );
+  }
+  return slots.sort((a, b) => a.editedAt - b.editedAt || a.card.createdAt - b.card.createdAt);
+}
+
+export function cardsDuration(slots: CardSlot[]): number {
+  return slots.reduce((sum, s) => sum + s.card.duration, 0);
+}
+
+/**
+ * Edited time -> program time: adds the duration of every card played
+ * before it. A card sitting exactly at `editedTime` counts by default
+ * (content there starts after its card -- right for captions); pass
+ * includeCardsAtPoint: false to land at the card's own start instead
+ * (right for a chapter marker, whose chapter should include its card).
+ */
+export function editedToProgramTime(
+  editedTime: number,
+  slots: CardSlot[],
+  { includeCardsAtPoint = true }: { includeCardsAtPoint?: boolean } = {}
+): number {
+  let shift = 0;
+  for (const slot of slots) {
+    const before = slot.editedAt < editedTime - EPSILON;
+    const atPoint = Math.abs(slot.editedAt - editedTime) <= EPSILON;
+    if (before || (atPoint && includeCardsAtPoint)) shift += slot.card.duration;
+  }
+  return editedTime + shift;
+}
+
+/**
+ * Program time -> where that is: inside a card (with how far into it), or
+ * at an edited-timeline time.
+ */
+export function locateProgramTime(
+  programTime: number,
+  slots: CardSlot[]
+): { editedTime: number; card: CardSlot | null; cardOffset: number } {
+  let shift = 0;
+  for (const slot of slots) {
+    const cardStart = slot.editedAt + shift;
+    if (programTime < cardStart) break;
+    if (programTime < cardStart + slot.card.duration) {
+      return { editedTime: slot.editedAt, card: slot, cardOffset: programTime - cardStart };
+    }
+    shift += slot.card.duration;
+  }
+  return { editedTime: Math.max(0, programTime - shift), card: null, cardOffset: 0 };
+}
+
+/**
+ * The render's play order: source ranges, split wherever a card is
+ * inserted, with the cards in between. With no cards this is exactly the
+ * playable ranges.
+ */
+export function buildProgramItems(ranges: PlayableRange[], slots: CardSlot[]): ProgramItem[] {
+  const items: ProgramItem[] = [];
+  let next = 0;
+  let edited = 0;
+  for (const r of ranges) {
+    let start = r.start;
+    const rangeEditedEnd = edited + (r.end - r.start);
+    while (next < slots.length && slots[next].editedAt < rangeEditedEnd - EPSILON) {
+      const at = r.start + (slots[next].editedAt - edited);
+      if (at > start + EPSILON) items.push({ kind: "source", start, end: at });
+      start = Math.max(start, at);
+      items.push({ kind: "card", card: slots[next].card });
+      next++;
+    }
+    if (r.end > start + EPSILON) items.push({ kind: "source", start, end: r.end });
+    edited = rangeEditedEnd;
+  }
+  for (; next < slots.length; next++) items.push({ kind: "card", card: slots[next].card });
+  return items;
+}
+
+export function programItemDuration(item: ProgramItem): number {
+  return item.kind === "card" ? item.card.duration : item.end - item.start;
+}
+
+/**
+ * An edited-time span (a caption cue, a word) in program time. Its start
+ * lands after any card at that moment and its end before one, so a cue
+ * that ends right where a card begins never stays up over the card.
+ */
+export function editedRangeToProgram(start: number, end: number, slots: CardSlot[]): { start: number; end: number } {
+  return {
+    start: editedToProgramTime(start, slots),
+    end: editedToProgramTime(end, slots, { includeCardsAtPoint: false }),
+  };
+}
+
+/** Each card in the program with the program time it starts at. */
+export function cardStartTimes(items: ProgramItem[]): { start: number; card: CardOperation }[] {
+  const starts: { start: number; card: CardOperation }[] = [];
+  let t = 0;
+  for (const item of items) {
+    if (item.kind === "card") starts.push({ start: t, card: item.card });
+    t += programItemDuration(item);
+  }
+  return starts;
+}
diff --git a/server/src/lib/timeline/program.test.ts b/server/src/lib/timeline/program.test.ts
new file mode 100644
index 0000000..5f0b449
--- /dev/null
+++ b/server/src/lib/timeline/program.test.ts
@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildProgramItems,
+  cardStartTimes,
+  cardsDuration,
+  editedRangeToProgram,
+  editedToProgramTime,
+  locateProgramTime,
+  placeCards,
+} from "@/lib/timeline/program";
+import { computePlayableRanges } from "@/lib/timeline/cuts";
+import type { CardOperation, CutOperation, EditOperation } from "@/types/edit-operation";
+
+const card = (id: string, at: number, duration = 3, createdAt = 0): CardOperation => ({
+  id,
+  type: "card",
+  at,
+  duration,
+  template: "title",
+  title: id,
+  background: "#000000",
+  createdAt,
+});
+const cut = (start: number, end: number): CutOperation => ({ id: `cut-${start}`, type: "cut", start, end, createdAt: 0 });
+const split = (timestamp: number): EditOperation => ({ id: `split-${timestamp}`, type: "split", timestamp, createdAt: 0 });
+
+function program(ops: EditOperation[], duration = 100) {
+  const ranges = computePlayableRanges(
+    duration,
+    ops.filter((op): op is CutOperation => op.type === "cut")
+  );
+  const slots = placeCards(ops, ranges, duration);
+  return { ranges, slots, items: buildProgramItems(ranges, slots) };
+}
+
+describe("program without cards", () => {
+  it("is exactly the playable ranges, with no time shift", () => {
+    const { ranges, slots, items } = program([cut(10, 20), split(50)]);
+    expect(slots).toEqual([]);
+    expect(items).toEqual(ranges.map((r) => ({ kind: "source", ...r })));
+    expect(editedToProgramTime(42, slots)).toBe(42);
+  });
+});
+
+describe("placeCards", () => {
+  it("places an intro, a mid-episode card and an outro in play order", () => {
+    const { slots } = program([card("outro", 100), card("mid", 40), card("intro", 0)]);
+    expect(slots.map((s) => [s.card.id, s.editedAt, s.resumeAt])).toEqual([
+      ["intro", 0, 0],
+      ["mid", 40, 40],
+      ["outro", 100, 100],
+    ]);
+  });
+
+  it("moves a card whose moment was cut to the next kept content", () => {
+    const { slots } = program([cut(35, 45), card("mid", 40)]);
+    expect(slots[0]).toMatchObject({ editedAt: 35, resumeAt: 45 });
+  });
+
+  it("drops a card whose whole scene was cut, but keeps intro and outro", () => {
+    const { slots } = program([split(40), split(60), cut(40, 60), card("gone", 40), card("intro", 0), card("outro", 100)]);
+    expect(slots.map((s) => s.card.id)).toEqual(["intro", "outro"]);
+  });
+
+  it("keeps cards at the same moment in creation order", () => {
+    const { slots } = program([card("second", 40, 3, 2), card("first", 40, 3, 1)]);
+    expect(slots.map((s) => s.card.id)).toEqual(["first", "second"]);
+  });
+});
+
+describe("buildProgramItems", () => {
+  it("splits the source range where a card is inserted", () => {
+    const { items } = program([card("intro", 0, 2), card("mid", 40, 3), cut(80, 100), card("outro", 100, 4)]);
+    expect(items).toEqual([
+      { kind: "card", card: expect.objectContaining({ id: "intro" }) },
+      { kind: "source", start: 0, end: 40 },
+      { kind: "card", card: expect.objectContaining({ id: "mid" }) },
+      { kind: "source", start: 40, end: 80 },
+      { kind: "card", card: expect.objectContaining({ id: "outro" }) },
+    ]);
+  });
+});
+
+describe("time mapping", () => {
+  const { slots } = program([card("intro", 0, 2), card("mid", 40, 3)]);
+
+  it("shifts edited time by every card before it", () => {
+    expect(cardsDuration(slots)).toBe(5);
+    expect(editedToProgramTime(10, slots)).toBe(12);
+    expect(editedToProgramTime(50, slots)).toBe(55);
+  });
+
+  it("puts content at a card's moment after the card, and chapter markers at its start", () => {
+    expect(editedToProgramTime(40, slots)).toBe(45);
+    expect(editedToProgramTime(40, slots, { includeCardsAtPoint: false })).toBe(42);
+    expect(editedToProgramTime(0, slots, { includeCardsAtPoint: false })).toBe(0);
+  });
+
+  it("locates program time inside a card or back on the edited timeline", () => {
+    expect(locateProgramTime(1, slots)).toMatchObject({ card: { card: { id: "intro" } }, cardOffset: 1 });
+    expect(locateProgramTime(12, slots)).toMatchObject({ card: null, editedTime: 10 });
+    expect(locateProgramTime(43.5, slots)).toMatchObject({ card: { card: { id: "mid" } }, cardOffset: 1.5 });
+    expect(locateProgramTime(55, slots)).toMatchObject({ card: null, editedTime: 50 });
+  });
+
+  it("round-trips edited -> program -> edited outside cards", () => {
+    for (const t of [0.5, 20, 39.9, 40.1, 99]) {
+      expect(locateProgramTime(editedToProgramTime(t, slots), slots).editedTime).toBeCloseTo(t);
+    }
+  });
+});
+
+describe("editedRangeToProgram and cardStartTimes", () => {
+  const { slots, items } = program([card("intro", 0, 2), card("mid", 40, 3)]);
+
+  it("keeps a span that ends where a card starts from running over the card", () => {
+    expect(editedRangeToProgram(38, 40, slots)).toEqual({ start: 40, end: 42 });
+    expect(editedRangeToProgram(40, 41, slots)).toEqual({ start: 45, end: 46 });
+  });
+
+  it("lists each card's start on the program timeline", () => {
+    expect(cardStartTimes(items).map((c) => [c.card.id, c.start])).toEqual([
+      ["intro", 0],
+      ["mid", 42],
+    ]);
+  });
+});
diff --git a/server/src/lib/timeline/program.ts b/server/src/lib/timeline/program.ts
new file mode 100644
index 0000000..2219864
--- /dev/null
+++ b/server/src/lib/timeline/program.ts
@@ -0,0 +1,178 @@
+import type { CardOperation, EditOperation, SplitOperation } from "@/types/edit-operation";
+import type { PlayableRange } from "@/types/timeline";
+import { nextPlayableTime, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
+
+/**
+ * The "program" is what actually plays: the kept source ranges with title
+ * cards inserted between them. Cards add time that isn't in the source, so
+ * three clocks exist:
+ *
+ *   source time  -- the original video (transcript, cuts, splits, cards' `at`)
+ *   edited time  -- source with cuts removed (lib/timeline/cuts.ts)
+ *   program time -- edited time with cards inserted (what renders)
+ *
+ * Everything that already works in edited time (captions, chapters) shifts
+ * into program time through editedToProgramTime, so cuts and cards compose
+ * without either knowing about the other. Duplicated, not imported, across
+ * the client/server boundary like cuts.ts -- keep both copies identical.
+ */
+
+const EPSILON = 0.001;
+
+/** A card placed on the edited timeline. */
+export type CardSlot = {
+  card: CardOperation;
+  /** Edited time the card plays at (before the source content there). */
+  editedAt: number;
+  /** Source time playback resumes at once the card has played. */
+  resumeAt: number;
+};
+
+export type ProgramItem =
+  | { kind: "source"; start: number; end: number }
+  | { kind: "card"; card: CardOperation };
+
+export function cardOperations(operations: EditOperation[]): CardOperation[] {
+  return operations.filter((op): op is CardOperation => op.type === "card");
+}
+
+function splitTimes(operations: EditOperation[]): number[] {
+  return operations
+    .filter((op): op is SplitOperation => op.type === "split" && op.timestamp > 0)
+    .map((op) => op.timestamp)
+    .sort((a, b) => a - b);
+}
+
+/**
+ * Places each card on the edited timeline, in play order.
+ *
+ * A card plays before the content at its `at` time; if that moment was
+ * cut, before the next content that wasn't. A card belongs to the scene
+ * starting at `at`, so when that whole scene is cut its card goes too --
+ * otherwise cutting "Part 2" would leave its title card announcing Part 3.
+ * Intro (at 0) and outro (at the end) cards always stay.
+ */
+export function placeCards(
+  operations: EditOperation[],
+  ranges: PlayableRange[],
+  sourceDuration: number
+): CardSlot[] {
+  const splits = splitTimes(operations);
+  const editedDuration = ranges.reduce((sum, r) => sum + (r.end - r.start), 0);
+
+  const slots: CardSlot[] = [];
+  for (const card of cardOperations(operations)) {
+    const isOutro = card.at >= sourceDuration - EPSILON;
+    const isIntro = card.at <= EPSILON;
+    if (!isIntro && !isOutro) {
+      const sceneEnd = splits.find((t) => t > card.at + EPSILON) ?? sourceDuration;
+      const sceneHasContent = ranges.some((r) => r.start < sceneEnd && r.end > card.at);
+      if (!sceneHasContent) continue;
+    }
+    const resumeAt = isOutro ? null : nextPlayableTime(card.at, ranges);
+    slots.push(
+      resumeAt === null
+        ? { card, editedAt: editedDuration, resumeAt: sourceDuration }
+        : { card, editedAt: sourceTimeToEditedTime(resumeAt, ranges), resumeAt }
+    );
+  }
+  return slots.sort((a, b) => a.editedAt - b.editedAt || a.card.createdAt - b.card.createdAt);
+}
+
+export function cardsDuration(slots: CardSlot[]): number {
+  return slots.reduce((sum, s) => sum + s.card.duration, 0);
+}
+
+/**
+ * Edited time -> program time: adds the duration of every card played
+ * before it. A card sitting exactly at `editedTime` counts by default
+ * (content there starts after its card -- right for captions); pass
+ * includeCardsAtPoint: false to land at the card's own start instead
+ * (right for a chapter marker, whose chapter should include its card).
+ */
+export function editedToProgramTime(
+  editedTime: number,
+  slots: CardSlot[],
+  { includeCardsAtPoint = true }: { includeCardsAtPoint?: boolean } = {}
+): number {
+  let shift = 0;
+  for (const slot of slots) {
+    const before = slot.editedAt < editedTime - EPSILON;
+    const atPoint = Math.abs(slot.editedAt - editedTime) <= EPSILON;
+    if (before || (atPoint && includeCardsAtPoint)) shift += slot.card.duration;
+  }
+  return editedTime + shift;
+}
+
+/**
+ * Program time -> where that is: inside a card (with how far into it), or
+ * at an edited-timeline time.
+ */
+export function locateProgramTime(
+  programTime: number,
+  slots: CardSlot[]
+): { editedTime: number; card: CardSlot | null; cardOffset: number } {
+  let shift = 0;
+  for (const slot of slots) {
+    const cardStart = slot.editedAt + shift;
+    if (programTime < cardStart) break;
+    if (programTime < cardStart + slot.card.duration) {
+      return { editedTime: slot.editedAt, card: slot, cardOffset: programTime - cardStart };
+    }
+    shift += slot.card.duration;
+  }
+  return { editedTime: Math.max(0, programTime - shift), card: null, cardOffset: 0 };
+}
+
+/**
+ * The render's play order: source ranges, split wherever a card is
+ * inserted, with the cards in between. With no cards this is exactly the
+ * playable ranges.
+ */
+export function buildProgramItems(ranges: PlayableRange[], slots: CardSlot[]): ProgramItem[] {
+  const items: ProgramItem[] = [];
+  let next = 0;
+  let edited = 0;
+  for (const r of ranges) {
+    let start = r.start;
+    const rangeEditedEnd = edited + (r.end - r.start);
+    while (next < slots.length && slots[next].editedAt < rangeEditedEnd - EPSILON) {
+      const at = r.start + (slots[next].editedAt - edited);
+      if (at > start + EPSILON) items.push({ kind: "source", start, end: at });
+      start = Math.max(start, at);
+      items.push({ kind: "card", card: slots[next].card });
+      next++;
+    }
+    if (r.end > start + EPSILON) items.push({ kind: "source", start, end: r.end });
+    edited = rangeEditedEnd;
+  }
+  for (; next < slots.length; next++) items.push({ kind: "card", card: slots[next].card });
+  return items;
+}
+
+export function programItemDuration(item: ProgramItem): number {
+  return item.kind === "card" ? item.card.duration : item.end - item.start;
+}
+
+/**
+ * An edited-time span (a caption cue, a word) in program time. Its start
+ * lands after any card at that moment and its end before one, so a cue
+ * that ends right where a card begins never stays up over the card.
+ */
+export function editedRangeToProgram(start: number, end: number, slots: CardSlot[]): { start: number; end: number } {
+  return {
+    start: editedToProgramTime(start, slots),
+    end: editedToProgramTime(end, slots, { includeCardsAtPoint: false }),
+  };
+}
+
+/** Each card in the program with the program time it starts at. */
+export function cardStartTimes(items: ProgramItem[]): { start: number; card: CardOperation }[] {
+  const starts: { start: number; card: CardOperation }[] = [];
+  let t = 0;
+  for (const item of items) {
+    if (item.kind === "card") starts.push({ start: t, card: item.card });
+    t += programItemDuration(item);
+  }
+  return starts;
+}

From 9bac2e2f6453bcb53c6c2bc9d87a47bc3c32a148 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:25:07 +0530
Subject: [PATCH 09/36] feat(server): lay out title card text and write it as
 ASS

layout.ts turns a card into positioned lines as percentages of the frame
(shared with the client preview, so both place the same card the same
way at any size), picks dark or light text from the background's
luminance, and fades the text in and out. ass.ts writes every card's
text into one ASS file timed on the program timeline, with the output
size as its script resolution.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 server/src/lib/captions/format.ts  |  4 +-
 server/src/lib/cards/ass.ts        | 74 +++++++++++++++++++++++++
 server/src/lib/cards/cards.test.ts | 77 ++++++++++++++++++++++++++
 server/src/lib/cards/layout.ts     | 88 ++++++++++++++++++++++++++++++
 4 files changed, 241 insertions(+), 2 deletions(-)
 create mode 100644 server/src/lib/cards/ass.ts
 create mode 100644 server/src/lib/cards/cards.test.ts
 create mode 100644 server/src/lib/cards/layout.ts

diff --git a/server/src/lib/captions/format.ts b/server/src/lib/captions/format.ts
index 0fa0889..4197ca7 100644
--- a/server/src/lib/captions/format.ts
+++ b/server/src/lib/captions/format.ts
@@ -44,14 +44,14 @@ export function toVtt(cues: CaptionCue[]): string {
   return `WEBVTT\n\n${body}`;
 }
 
-function assTimestamp(seconds: number): string {
+export function assTimestamp(seconds: number): string {
   const { h, m, s, ms } = splitTime(seconds);
   // ASS wants centiseconds (2 digits), not milliseconds (3).
   return `${h}:${pad(m)}:${pad(s)}.${pad(Math.floor(ms / 10))}`;
 }
 
 /** Strips characters that would break the {\...} override-tag syntax if they appeared in transcript text. */
-function escapeAssText(text: string): string {
+export function escapeAssText(text: string): string {
   return text.replace(/[{}\\]/g, "");
 }
 
diff --git a/server/src/lib/cards/ass.ts b/server/src/lib/cards/ass.ts
new file mode 100644
index 0000000..05e6242
--- /dev/null
+++ b/server/src/lib/cards/ass.ts
@@ -0,0 +1,74 @@
+import { assTimestamp, escapeAssText } from "@/lib/captions/format";
+import { hexToAssColor } from "@/lib/captions/style";
+import {
+  CARD_FONT,
+  CARD_SECONDARY_OPACITY,
+  CARD_TEXT_FADE_SECONDS,
+  CARD_TEXT_WIDTH_PERCENT,
+  cardTextColor,
+  layoutCard,
+  type CardLine,
+} from "@/lib/cards/layout";
+import type { CardOperation } from "@/types/edit-operation";
+
+/** Numpad alignment for each anchor: bottom-center, top-center, center. */
+const ALIGNMENT: Record<CardLine["anchor"], number> = { above: 2, below: 8, center: 5 };
+
+/**
+ * One .ass file with the text of every title card, timed on the program
+ * timeline, burned in over the rendered program in a single subtitles pass
+ * (the cards' solid backgrounds come from ffmpeg's color source -- see
+ * lib/ffmpeg/plan.ts). PlayResX/Y is the output size, so lib/cards/layout.ts's
+ * percentages land where the preview puts them.
+ *
+ * Card text was already refused at the API if it held braces, backslashes
+ * or control characters; escapeAssText strips them again here anyway, since
+ * a stray brace would be read as an override tag.
+ */
+export function toCardsAss(
+  cards: { start: number; card: CardOperation }[],
+  frame: { width: number; height: number }
+): string {
+  const { width, height } = frame;
+  const marginH = Math.round((width * (100 - CARD_TEXT_WIDTH_PERCENT)) / 200);
+  const secondaryAlpha = Math.round((1 - CARD_SECONDARY_OPACITY) * 255)
+    .toString(16)
+    .padStart(2, "0")
+    .toUpperCase();
+
+  const events = cards.flatMap(({ start, card }) => {
+    const color = hexToAssColor(cardTextColor(card.background)).replace("&H00", "&H");
+    const fadeMs = Math.round(Math.min(CARD_TEXT_FADE_SECONDS, card.duration / 4) * 1000);
+    return layoutCard(card).map((line) => {
+      const x = Math.round(width / 2);
+      const y = Math.round((line.yPercent / 100) * height);
+      const size = Math.round((line.sizePercent / 100) * height);
+      const tags = [
+        `\\an${ALIGNMENT[line.anchor]}`,
+        `\\pos(${x},${y})`,
+        `\\fs${size}`,
+        `\\b${line.bold ? 1 : 0}`,
+        `\\i${line.italic ? 1 : 0}`,
+        `\\c${color}&`,
+        ...(line.secondary ? [`\\alpha&H${secondaryAlpha}&`] : []),
+        `\\fad(${fadeMs},${fadeMs})`,
+      ].join("");
+      return `Dialogue: 0,${assTimestamp(start)},${assTimestamp(start + card.duration)},Card,,0,0,0,,{${tags}}${escapeAssText(line.text)}`;
+    });
+  });
+
+  return `[Script Info]
+ScriptType: v4.00+
+WrapStyle: 0
+PlayResX: ${width}
+PlayResY: ${height}
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+Style: Card,${CARD_FONT},${Math.round(height * 0.08)},&H00FFFFFF,&H00FFFFFF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,0,0,5,${marginH},${marginH},0,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+${events.join("\n")}
+`;
+}
diff --git a/server/src/lib/cards/cards.test.ts b/server/src/lib/cards/cards.test.ts
new file mode 100644
index 0000000..6c9f162
--- /dev/null
+++ b/server/src/lib/cards/cards.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { toCardsAss } from "@/lib/cards/ass";
+import { cardTextColor, cardTextOpacity, layoutCard } from "@/lib/cards/layout";
+import type { CardOperation } from "@/types/edit-operation";
+
+const card: CardOperation = {
+  id: "c1",
+  type: "card",
+  at: 0,
+  duration: 3,
+  template: "chapter",
+  title: "Pricing",
+  subtitle: "Part 2",
+  background: "#111418",
+  createdAt: 0,
+};
+
+describe("layoutCard", () => {
+  it("puts a chapter's kicker above the title, uppercased", () => {
+    expect(layoutCard(card).map((l) => [l.text, l.anchor])).toEqual([
+      ["PART 2", "above"],
+      ["Pricing", "below"],
+    ]);
+  });
+
+  it("centers a lone title when there's no subtitle", () => {
+    expect(layoutCard({ template: "title", title: "Welcome" })).toEqual([
+      expect.objectContaining({ text: "Welcome", anchor: "center", yPercent: 50 }),
+    ]);
+  });
+
+  it("quotes a quote and attributes it", () => {
+    expect(layoutCard({ template: "quote", title: "Ship it", subtitle: "Ada" }).map((l) => l.text)).toEqual([
+      "“Ship it”",
+      "— Ada",
+    ]);
+  });
+});
+
+describe("cardTextColor", () => {
+  it("uses white on dark backgrounds and near-black on light ones", () => {
+    expect(cardTextColor("#111418")).toBe("#FFFFFF");
+    expect(cardTextColor("#F5F0E6")).toBe("#111111");
+  });
+});
+
+describe("cardTextOpacity", () => {
+  it("fades in, holds, and fades out", () => {
+    expect(cardTextOpacity(0, 3)).toBe(0);
+    expect(cardTextOpacity(1.5, 3)).toBe(1);
+    expect(cardTextOpacity(3, 3)).toBe(0);
+  });
+});
+
+describe("toCardsAss", () => {
+  const ass = toCardsAss([{ start: 12.5, card }], { width: 1920, height: 1080 });
+
+  it("uses the output size as the script resolution", () => {
+    expect(ass).toContain("PlayResX: 1920\nPlayResY: 1080");
+  });
+
+  it("times each line to the card's slot on the program timeline", () => {
+    const events = ass.split("\n").filter((l) => l.startsWith("Dialogue:"));
+    expect(events).toHaveLength(2);
+    for (const e of events) expect(e).toContain("0:00:12.50,0:00:15.50");
+  });
+
+  it("positions lines as percentages of the frame, in white on a dark card", () => {
+    expect(ass).toContain("\\an8\\pos(960,497)\\fs86\\b1");
+    expect(ass).toContain("\\c&HFFFFFF&");
+  });
+
+  it("strips override-tag characters from card text", () => {
+    const out = toCardsAss([{ start: 0, card: { ...card, title: "a{\\fs999}b" } }], { width: 1920, height: 1080 });
+    expect(out).toContain("}afs999b");
+  });
+});
diff --git a/server/src/lib/cards/layout.ts b/server/src/lib/cards/layout.ts
new file mode 100644
index 0000000..f2aac23
--- /dev/null
+++ b/server/src/lib/cards/layout.ts
@@ -0,0 +1,88 @@
+import type { CardOperation } from "@/types/edit-operation";
+
+/**
+ * Where each line of a title card goes, as percentages of the frame, so
+ * the HTML preview (CardPreview.tsx, in cqh units) and the burned-in ASS
+ * (lib/cards/ass.ts, against PlayResX/Y = the output size) lay out the
+ * same card the same way at any resolution. Duplicated, not imported,
+ * across the client/server boundary -- keep both copies identical.
+ *
+ * `anchor` says which edge of the text block sits on `yPercent`: a title
+ * anchored "above" a line grows upward as it wraps, and a subtitle
+ * anchored "below" grows downward, so the two never overlap.
+ */
+export type CardLine = {
+  text: string;
+  /** Font size, percent of frame height. */
+  sizePercent: number;
+  anchor: "above" | "below" | "center";
+  yPercent: number;
+  bold: boolean;
+  italic: boolean;
+  /** Secondary lines render slightly faded. */
+  secondary: boolean;
+};
+
+export const CARD_FONT = "Arial";
+/** Text wraps inside this much of the frame width. */
+export const CARD_TEXT_WIDTH_PERCENT = 80;
+/** Card text fades in and out over this long (the background cuts in). */
+export const CARD_TEXT_FADE_SECONDS = 0.25;
+export const CARD_SECONDARY_OPACITY = 0.8;
+
+export function layoutCard(card: Pick<CardOperation, "template" | "title" | "subtitle">): CardLine[] {
+  const title = card.title.trim();
+  const subtitle = card.subtitle?.trim() ?? "";
+  const line = (text: string, sizePercent: number, anchor: CardLine["anchor"], yPercent: number, rest: Partial<CardLine> = {}): CardLine => ({
+    text,
+    sizePercent,
+    anchor,
+    yPercent,
+    bold: false,
+    italic: false,
+    secondary: false,
+    ...rest,
+  });
+
+  switch (card.template) {
+    case "chapter":
+      return subtitle
+        ? [
+            line(subtitle.toUpperCase(), 3.5, "above", 44, { bold: true, secondary: true }),
+            line(title, 8, "below", 46, { bold: true }),
+          ]
+        : [line(title, 8, "center", 50, { bold: true })];
+    case "quote":
+      return [
+        line(`“${title}”`, 6, subtitle ? "above" : "center", subtitle ? 55 : 50, { italic: true }),
+        ...(subtitle ? [line(`— ${subtitle}`, 3.5, "below", 59, { secondary: true })] : []),
+      ];
+    case "outro":
+    case "title":
+    default: {
+      const size = card.template === "outro" ? 7 : 8;
+      return subtitle
+        ? [line(title, size, "above", 52, { bold: true }), line(subtitle, 4, "below", 55, { secondary: true })]
+        : [line(title, size, "center", 50, { bold: true })];
+    }
+  }
+}
+
+/** Dark text on light backgrounds, white on dark (WCAG relative luminance). */
+export function cardTextColor(background: string): string {
+  const channel = (i: number) => {
+    const c = parseInt(background.slice(i, i + 2), 16) / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  const luminance = 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
+  return luminance > 0.4 ? "#111111" : "#FFFFFF";
+}
+
+/** Opacity of card text `offset` seconds into a card lasting `duration`. */
+export function cardTextOpacity(offset: number, duration: number): number {
+  const fade = Math.min(CARD_TEXT_FADE_SECONDS, duration / 4);
+  return Math.max(0, Math.min(1, offset / fade, (duration - offset) / fade));
+}
+
+/** Preset backgrounds offered in the card editor. */
+export const CARD_BACKGROUNDS = ["#111418", "#1E3A5F", "#7C2D12", "#14532D", "#F5F0E6", "#FFFFFF"] as const;

From 22923075e099da4bd82254c688e07a6f07be3303 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:25:07 +0530
Subject: [PATCH 10/36] feat(server): render title cards into exports

Each card becomes an ffmpeg color source at the source's size and frame
rate, joined into the same xfade chain as the cuts, with silence for its
duration on the audio side; the cards' text is burned in over the whole
program in one subtitles pass, before captions and the logo. With cards
present, segments are normalized to one pixel and audio format so they
can join, and color grading moves onto each footage segment so a preset
doesn't recolor the cards. Projects without cards render the same graph
as before.

Captions and embedded chapters move onto the program timeline; a chapter
that starts where a card plays starts with the card. MP3/WAV exports get
the cards' silence so chapters stay in sync. Clips skip cards.

Verified with ffmpeg 9.0.2 on a synthetic clip with an intro, a cut, a
chapter card and an outro: every card and segment lands where the program
model says (video 23.857s, audio 23.850s), and a beep every second lands
at its predicted time before and after each card.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 server/src/lib/ffmpeg/plan.test.ts    |  82 +++++++++++++
 server/src/lib/ffmpeg/plan.ts         | 166 ++++++++++++++++++++------
 server/src/lib/ffmpeg/render-job.ts   |  58 +++++++--
 server/src/lib/publishing/chapters.ts |  17 +++
 4 files changed, 278 insertions(+), 45 deletions(-)

diff --git a/server/src/lib/ffmpeg/plan.test.ts b/server/src/lib/ffmpeg/plan.test.ts
index bfbd447..114744c 100644
--- a/server/src/lib/ffmpeg/plan.test.ts
+++ b/server/src/lib/ffmpeg/plan.test.ts
@@ -342,3 +342,85 @@ describe("reframe", () => {
     expect(() => buildRenderArgs({ ...baseArgs, reframe: { width: 1080.5, height: 1920, cropX: 0.5 } })).toThrow();
   });
 });
+
+describe("title cards", () => {
+  const card = {
+    id: "c1",
+    type: "card" as const,
+    at: 0,
+    duration: 3,
+    template: "title" as const,
+    title: "Welcome",
+    background: "#1e3a5f",
+    createdAt: 0,
+  };
+  const program = [
+    { kind: "card" as const, card },
+    { kind: "source" as const, start: 0, end: 10 },
+    { kind: "source" as const, start: 20, end: 30 },
+  ];
+  const cardFrame = { width: 1920, height: 1080, textPath: "/data/cards.ass" };
+  const graph = (extra: Partial<Parameters<typeof buildRenderArgs>[0]> = {}) => {
+    const args = buildRenderArgs({ ...baseArgs, program, cardFrame, ...extra });
+    return args[args.indexOf("-filter_complex") + 1];
+  };
+
+  it("generates each card as a solid-color segment at the source's size and frame rate", () => {
+    expect(graph()).toContain(
+      "color=c=0x1E3A5F:s=1920x1080:r=30000/1001:d=3.000,format=yuv420p,setsar=1,tpad=stop_mode=clone:stop_duration=0.1[v0]"
+    );
+  });
+
+  it("normalizes source segments so they can join the cards", () => {
+    expect(graph()).toContain(
+      "[0:v]trim=start=0.000:end=10.000,setpts=PTS-STARTPTS,fps=30000/1001,format=yuv420p,setsar=1,tpad=stop_mode=clone:stop_duration=0.1[v1]"
+    );
+  });
+
+  it("offsets each join by the durations before it, cards included", () => {
+    const g = graph();
+    expect(g).toContain("[v0][v1]xfade=transition=fade:duration=0.030:offset=2.970[vx1]");
+    expect(g).toContain("[vx1][v2]xfade=transition=fade:duration=0.030:offset=12.940[outv]");
+  });
+
+  it("gives cards silence in a shared audio format", () => {
+    const g = graph();
+    expect(g).toContain(
+      "anullsrc=r=48000:cl=stereo,atrim=duration=3.000,aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo[a0]"
+    );
+    expect(g).toContain(
+      "[0:a]atrim=start=0.000:end=10.000,asetpts=PTS-STARTPTS,aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo[a1]"
+    );
+  });
+
+  it("grades only the footage, then burns card text in before captions", () => {
+    const g = graph({
+      filterId: "bw",
+      srtPath: "/data/subs.srt",
+      captionStyle: DEFAULT_CAPTION_STYLE,
+      videoHeight: 1080,
+      videoWidth: 1920,
+    });
+    expect(g).not.toContain("[outv]hue");
+    expect(g).toContain("[0:v]trim=start=0.000:end=10.000,setpts=PTS-STARTPTS,hue=s=0");
+    expect(g.split(";").find((chain) => chain.startsWith("color="))).not.toContain("hue");
+    expect(g.indexOf("subtitles=filename='/data/cards.ass'[carded]")).toBeLessThan(
+      g.indexOf("subtitles=filename='/data/subs.srt'")
+    );
+    expect(g).toMatch(/\[carded\]subtitles=filename='\/data\/subs\.srt'/);
+  });
+
+  it("refuses cards without the frame to generate them at, and bad values", () => {
+    expect(() => buildRenderArgs({ ...baseArgs, program })).toThrow(/frame size/);
+    expect(() => buildRenderArgs({ ...baseArgs, program, cardFrame: { ...cardFrame, width: 0 } })).toThrow(
+      /frame size/
+    );
+    const badColor = [{ kind: "card" as const, card: { ...card, background: "red" } }, program[1]];
+    expect(() => buildRenderArgs({ ...baseArgs, program: badColor, cardFrame })).toThrow(/background color/);
+  });
+
+  it("adds card silence to audio-only exports", () => {
+    const args = buildAudioOnlyRenderArgs({ ...baseArgs, program, format: "mp3" });
+    expect(args[args.indexOf("-filter_complex") + 1]).toContain("anullsrc=r=48000:cl=stereo,atrim=duration=3.000");
+  });
+});
diff --git a/server/src/lib/ffmpeg/plan.ts b/server/src/lib/ffmpeg/plan.ts
index 132af5f..6ed928f 100644
--- a/server/src/lib/ffmpeg/plan.ts
+++ b/server/src/lib/ffmpeg/plan.ts
@@ -1,4 +1,5 @@
 import type { PlayableRange } from "@/types/timeline";
+import type { ProgramItem } from "@/lib/timeline/program";
 import { getFfmpegFilter } from "@/lib/ffmpeg/filters";
 import { buildPropertiesFilter } from "@/lib/ffmpeg/properties";
 import { buildForceStyle, type CaptionStyle } from "@/lib/captions/style";
@@ -78,6 +79,56 @@ function assertValidRanges(playableRanges: PlayableRange[]): void {
   }
 }
 
+/**
+ * What to render, in order: the program (lib/timeline/program.ts) when the
+ * project has title cards, otherwise just the playable ranges. Validated
+ * here since card durations and colors end up in the filtergraph.
+ */
+function resolveItems(playableRanges: PlayableRange[], program?: ProgramItem[]): ProgramItem[] {
+  if (!program) {
+    assertValidRanges(playableRanges);
+    return playableRanges.map((r) => ({ kind: "source", start: r.start, end: r.end }));
+  }
+  assertValidRanges(program.flatMap((item) => (item.kind === "source" ? [item] : [])));
+  for (const item of program) {
+    if (item.kind !== "card") continue;
+    const { duration, background } = item.card;
+    if (!Number.isFinite(duration) || duration <= 0 || duration > 60) throw new Error("Invalid card duration.");
+    if (!/^#[0-9a-fA-F]{6}$/.test(background)) throw new Error("Invalid card background color.");
+  }
+  return program;
+}
+
+function assertValidCardFrame(frame: { width: number; height: number }): void {
+  const { width, height } = frame;
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0 || width > 8192 || height > 8192) {
+    throw new Error(`Invalid card frame size: ${width}x${height}`);
+  }
+}
+
+function itemDuration(item: ProgramItem): number {
+  return item.kind === "card" ? item.card.duration : item.end - item.start;
+}
+
+const hasCards = (items: ProgramItem[]) => items.some((item) => item.kind === "card");
+
+/**
+ * Cards join the source through xfade/acrossfade, which need identical
+ * frame size, rate, pixel format and timebase (video) and sample format,
+ * rate and layout (audio) on both sides. A generated color source never
+ * matches a decoded file on its own, so when cards are present every
+ * segment is normalized to these. Without cards the graph is left exactly
+ * as it always was.
+ */
+const CARD_AUDIO_FORMAT = "aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo";
+/**
+ * The rate comes from fps= (sources) and the color source's own r= (cards),
+ * which also gives both the same 1/rate timebase. Don't add settb here:
+ * measured on ffmpeg 9, forcing another timebase after fps= brings back
+ * the dropped-footage join the fps= fix exists for.
+ */
+const CARD_VIDEO_FORMAT = "format=yuv420p,setsar=1";
+
 /**
  * Crossfade length at each join: entry i is the fade between range i-1 and
  * range i (entry 0 is unused). Each is clamped to at most half of either
@@ -85,27 +136,29 @@ function assertValidRanges(playableRanges: PlayableRange[]): void {
  * between two nearby cuts can't make the transition eat more than that
  * sliver. Shared by the video and audio graphs so they stay in sync.
  */
-function computeCrossfades(playableRanges: PlayableRange[]): number[] {
-  return playableRanges.map((r, i) => {
-    if (i === 0) return 0;
-    const previous = playableRanges[i - 1];
-    return Math.min(CUT_CROSSFADE_SECONDS, (previous.end - previous.start) / 2, (r.end - r.start) / 2);
-  });
+function computeCrossfades(durations: number[]): number[] {
+  return durations.map((d, i) => (i === 0 ? 0 : Math.min(CUT_CROSSFADE_SECONDS, durations[i - 1] / 2, d / 2)));
 }
 
-/** atrim + acrossfade chains ending in [outa]: the edited program's audio, before any cleanup. */
-function buildAudioEditChains(playableRanges: PlayableRange[]): string[] {
-  const chains = playableRanges.map(
-    (r, i) => `[0:a]atrim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},asetpts=PTS-STARTPTS[a${i}]`
+/**
+ * atrim + acrossfade chains ending in [outa]: the edited program's audio,
+ * before any cleanup. Cards contribute silence for their duration.
+ */
+function buildAudioEditChains(items: ProgramItem[]): string[] {
+  const normalize = hasCards(items) ? `,${CARD_AUDIO_FORMAT}` : "";
+  const chains = items.map((item, i) =>
+    item.kind === "source"
+      ? `[0:a]atrim=start=${item.start.toFixed(3)}:end=${item.end.toFixed(3)},asetpts=PTS-STARTPTS${normalize}[a${i}]`
+      : `anullsrc=r=48000:cl=stereo,atrim=duration=${item.card.duration.toFixed(3)}${normalize}[a${i}]`
   );
-  if (playableRanges.length === 1) {
+  if (items.length === 1) {
     chains.push("[a0]anull[outa]");
     return chains;
   }
-  const crossfades = computeCrossfades(playableRanges);
+  const crossfades = computeCrossfades(items.map(itemDuration));
   let label = "a0";
-  for (let i = 1; i < playableRanges.length; i++) {
-    const next = i === playableRanges.length - 1 ? "outa" : `ax${i}`;
+  for (let i = 1; i < items.length; i++) {
+    const next = i === items.length - 1 ? "outa" : `ax${i}`;
     chains.push(`[${label}][a${i}]acrossfade=d=${crossfades[i].toFixed(3)}[${next}]`);
     label = next;
   }
@@ -121,11 +174,13 @@ function buildAudioEditChains(playableRanges: PlayableRange[]): string[] {
 export function buildLoudnessAnalysisArgs(args: {
   inputPath: string;
   playableRanges: PlayableRange[];
+  /** With title cards: the program, whose cards add silence (see resolveItems). */
+  program?: ProgramItem[];
   /** From audio-filters.ts#buildLoudnessAnalysisChain. */
   analysisChain: string;
 }): string[] {
-  assertValidRanges(args.playableRanges);
-  const chains = [...buildAudioEditChains(args.playableRanges), `[outa]${args.analysisChain}[analysis]`];
+  const items = resolveItems(args.playableRanges, args.program);
+  const chains = [...buildAudioEditChains(items), `[outa]${args.analysisChain}[analysis]`];
   return ["-i", args.inputPath, "-filter_complex", chains.join(";"), "-map", "[analysis]", "-f", "null", "-"];
 }
 
@@ -152,13 +207,15 @@ export function buildAudioOnlyRenderArgs(args: {
   inputPath: string;
   outputPath: string;
   playableRanges: PlayableRange[];
+  /** With title cards: the program, so cards become silence and chapters stay in sync. */
+  program?: ProgramItem[];
   audioFilter?: string | null;
   format?: "m4a" | "mp3" | "wav";
   metadataPath?: string;
 }): string[] {
-  assertValidRanges(args.playableRanges);
+  const items = resolveItems(args.playableRanges, args.program);
   const format = args.format ?? "m4a";
-  const chains = buildAudioEditChains(args.playableRanges);
+  const chains = buildAudioEditChains(items);
   let label = "[outa]";
   if (args.audioFilter) {
     chains.push(`[outa]${args.audioFilter}[cleana]`);
@@ -272,6 +329,14 @@ export function buildRenderArgs(args: {
    * xfade joins -- see the comment where it's applied.
    */
   frameRate: string;
+  /**
+   * The program with title cards (lib/timeline/program.ts), plus what the
+   * card segments need to match the source: its frame size and the .ass
+   * file with every card's text (lib/cards/ass.ts). Omit for a project
+   * without cards.
+   */
+  program?: ProgramItem[];
+  cardFrame?: { width: number; height: number; textPath: string };
 }): string[] {
   const {
     inputPath,
@@ -292,10 +357,19 @@ export function buildRenderArgs(args: {
     metadataPath,
     reframe,
     frameRate,
+    program,
+    cardFrame,
   } = args;
 
-  assertValidRanges(playableRanges);
+  const items = resolveItems(playableRanges, program);
   if (!/^\d{1,6}(\/\d{1,6})?$/.test(frameRate)) throw new Error(`Invalid frame rate: ${frameRate}`);
+  const withCards = hasCards(items);
+  if (withCards && !cardFrame) throw new Error("Title cards need the source's frame size.");
+  if (cardFrame) assertValidCardFrame(cardFrame);
+
+  const presetFilter = getFfmpegFilter(filterId);
+  const propertiesFilter = properties ? buildPropertiesFilter(properties) : null;
+  const colorFilter = [presetFilter, propertiesFilter].filter(Boolean).join(",");
 
   // fps= pins each trimmed segment to the source's frame rate. Without it,
   // xfade on ffmpeg 9 drops the start of every segment after a join: the
@@ -313,14 +387,32 @@ export function buildRenderArgs(args: {
   // 14.9s, the last segment gone). xfade discards the first input's frames
   // after the transition, so the padding never reaches the output.
   const filterChains: string[] = [];
-  playableRanges.forEach((r, i) => {
-    const pad = i < playableRanges.length - 1 ? `,${SEGMENT_TAIL_PAD}` : "";
-    filterChains.push(
-      `[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS,fps=${frameRate}${pad}[v${i}]`
-    );
+  items.forEach((item, i) => {
+    const pad = i < items.length - 1 ? `,${SEGMENT_TAIL_PAD}` : "";
+    if (!withCards) {
+      const r = item as Extract<ProgramItem, { kind: "source" }>;
+      filterChains.push(
+        `[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS,fps=${frameRate}${pad}[v${i}]`
+      );
+      return;
+    }
+    // With cards, color grading is applied per source segment so the cards
+    // keep their exact chosen color (a black-and-white preset shouldn't
+    // turn a blue card grey).
+    if (item.kind === "source") {
+      const grade = colorFilter ? `,${colorFilter}` : "";
+      filterChains.push(
+        `[0:v]trim=start=${item.start.toFixed(3)}:end=${item.end.toFixed(3)},setpts=PTS-STARTPTS${grade},fps=${frameRate},${CARD_VIDEO_FORMAT}${pad}[v${i}]`
+      );
+    } else {
+      const color = item.card.background.slice(1).toUpperCase();
+      filterChains.push(
+        `color=c=0x${color}:s=${cardFrame!.width}x${cardFrame!.height}:r=${frameRate}:d=${item.card.duration.toFixed(3)},${CARD_VIDEO_FORMAT}${pad}[v${i}]`
+      );
+    }
   });
 
-  if (playableRanges.length === 1) {
+  if (items.length === 1) {
     filterChains.push(`[v0]null[outv]`);
   } else {
     // Chain xfade pairwise across every cut instead of a plain concat.
@@ -331,14 +423,15 @@ export function buildRenderArgs(args: {
     // the filter's documented options, since offset math like this is easy
     // to get subtly wrong. The audio side uses the same crossfade lengths
     // (see buildAudioEditChains).
-    const crossfades = computeCrossfades(playableRanges);
+    const durations = items.map(itemDuration);
+    const crossfades = computeCrossfades(durations);
     let videoLabel = "v0";
-    let cumulativeDuration = playableRanges[0].end - playableRanges[0].start;
-    for (let i = 1; i < playableRanges.length; i++) {
-      const segmentDuration = playableRanges[i].end - playableRanges[i].start;
+    let cumulativeDuration = durations[0];
+    for (let i = 1; i < items.length; i++) {
+      const segmentDuration = durations[i];
       const crossfade = crossfades[i];
       const offset = (cumulativeDuration - crossfade).toFixed(3);
-      const nextVideoLabel = i === playableRanges.length - 1 ? "outv" : `vx${i}`;
+      const nextVideoLabel = i === items.length - 1 ? "outv" : `vx${i}`;
       filterChains.push(
         `[${videoLabel}][v${i}]xfade=transition=fade:duration=${crossfade.toFixed(3)}:offset=${offset}[${nextVideoLabel}]`
       );
@@ -347,7 +440,7 @@ export function buildRenderArgs(args: {
     }
   }
 
-  filterChains.push(...buildAudioEditChains(playableRanges));
+  filterChains.push(...buildAudioEditChains(items));
   let audioOutLabel = "[outa]";
   if (audioFilter) {
     filterChains.push(`[outa]${audioFilter}[cleana]`);
@@ -355,10 +448,7 @@ export function buildRenderArgs(args: {
   }
 
   let videoOutLabel = "[outv]";
-  const presetFilter = getFfmpegFilter(filterId);
-  const propertiesFilter = properties ? buildPropertiesFilter(properties) : null;
-  const colorFilter = [presetFilter, propertiesFilter].filter(Boolean).join(",");
-  if (colorFilter) {
+  if (colorFilter && !withCards) {
     filterChains.push(`[outv]${colorFilter}[filtered]`);
     videoOutLabel = "[filtered]";
   }
@@ -368,6 +458,12 @@ export function buildRenderArgs(args: {
     videoOutLabel = "[reframed]";
   }
 
+  // Card text sits above the footage and below captions and the logo.
+  if (withCards) {
+    filterChains.push(`${videoOutLabel}subtitles=filename='${escapeSubtitlesPath(cardFrame!.textPath)}'[carded]`);
+    videoOutLabel = "[carded]";
+  }
+
   if (srtPath) {
     // force_style's FontSize/MarginV are literal, un-scaled output pixels
     // -- verified empirically that ffmpeg's `original_size` option does
diff --git a/server/src/lib/ffmpeg/render-job.ts b/server/src/lib/ffmpeg/render-job.ts
index 2ee037f..0fa0126 100644
--- a/server/src/lib/ffmpeg/render-job.ts
+++ b/server/src/lib/ffmpeg/render-job.ts
@@ -5,7 +5,7 @@ import { prisma } from "@/lib/db/client";
 import { resolveInDataDir, statAsset } from "@/lib/storage/local";
 import { computePlayableRanges } from "@/lib/timeline/cuts";
 import { buildAudioOnlyRenderArgs, buildLoudnessAnalysisArgs, buildRenderArgs } from "@/lib/ffmpeg/plan";
-import { resolveChapters, toFfmetadata } from "@/lib/publishing/chapters";
+import { resolveProgramChapters, toFfmetadata } from "@/lib/publishing/chapters";
 import { clipAsCuts } from "@/lib/clips/clips";
 import { captionStyleSchema } from "@/lib/validation/caption-style";
 import { CLIP_ASPECTS, CLIP_OUTPUT_SIZE, type ClipAspect } from "@/types/clips";
@@ -23,6 +23,17 @@ import {
 import { parseStoredAudioSettings } from "@/lib/validation/audio-settings";
 import { runFfmpeg, runFfmpegCapturingStderr } from "@/lib/ffmpeg/run";
 import { probeVideoStream } from "@/lib/ffmpeg/probe";
+import {
+  buildProgramItems,
+  cardStartTimes,
+  cardsDuration,
+  editedRangeToProgram,
+  placeCards,
+  type CardSlot,
+  type ProgramItem,
+} from "@/lib/timeline/program";
+import { toCardsAss } from "@/lib/cards/ass";
+import type { CaptionCue } from "@/lib/captions/generate";
 import { generateCaptions, splitCuesForShorts } from "@/lib/captions/generate";
 import { toAssKaraoke, toSrt } from "@/lib/captions/format";
 import { DEFAULT_CAPTION_STYLE, type CaptionStyle } from "@/lib/captions/style";
@@ -63,7 +74,8 @@ export async function resolveLoudnessGain(
   inputPath: string,
   playableRanges: PlayableRange[],
   audioSettings: AudioSettings,
-  jobId: string
+  jobId: string,
+  program?: ProgramItem[]
 ): Promise<number | undefined> {
   const target = loudnessTargetLufs(audioSettings);
   if (target === null) return undefined;
@@ -71,7 +83,7 @@ export async function resolveLoudnessGain(
   const measure = async (gainDb?: number) => {
     const analysisChain = buildLoudnessAnalysisChain(audioSettings, gainDb)!;
     const stderr = await runFfmpegCapturingStderr(
-      buildLoudnessAnalysisArgs({ inputPath, playableRanges, analysisChain })
+      buildLoudnessAnalysisArgs({ inputPath, playableRanges, program, analysisChain })
     );
     return parseMeasuredLoudness(stderr);
   };
@@ -125,6 +137,16 @@ function toClipAspect(value: string): ClipAspect {
   return (CLIP_ASPECTS as readonly string[]).includes(value) ? (value as ClipAspect) : "9:16";
 }
 
+/** Caption cues moved from edited time onto the program timeline, around any title cards. */
+function cuesToProgramTime(cues: CaptionCue[], slots: CardSlot[]): CaptionCue[] {
+  if (slots.length === 0) return cues;
+  return cues.map((cue) => ({
+    ...cue,
+    ...editedRangeToProgram(cue.start, cue.end, slots),
+    words: cue.words.map((w) => ({ ...w, ...editedRangeToProgram(w.start, w.end, slots) })),
+  }));
+}
+
 export const EXPORT_MIME_TYPES: Record<ExportFormat, string> = {
   mp4: "video/mp4",
   mp3: "audio/mpeg",
@@ -164,13 +186,15 @@ export async function runRenderJob(
 
     // A clip is rendered as the project with everything outside it cut too,
     // so the project's own edits still apply inside the clip.
+    const operations = project.editOperations.map((op) => JSON.parse(op.dataJson) as EditOperation);
     const cuts = [
-      ...project.editOperations
-        .map((op) => JSON.parse(op.dataJson) as EditOperation)
-        .filter((op): op is CutOperation => op.type === "cut"),
+      ...operations.filter((op): op is CutOperation => op.type === "cut"),
       ...(clip ? clipAsCuts(clip, project.duration) : []),
     ];
     const playableRanges = computePlayableRanges(project.duration, cuts);
+    // Title cards play in full exports only: a clip is a standalone excerpt.
+    const cardSlots = clip ? [] : placeCards(operations, playableRanges, project.duration);
+    const program = cardSlots.length > 0 ? buildProgramItems(playableRanges, cardSlots) : undefined;
 
     const inputPath = resolveInDataDir(originalAsset.filePath);
     const outputRelativePath = path.posix.join(
@@ -203,13 +227,21 @@ export async function runRenderJob(
     const sourceStream = isVideo ? await probeVideoStream(inputPath) : undefined;
     const videoDimensions = clipFrame ?? sourceStream;
 
+    // Title cards are generated at the source's own size so they join it seamlessly.
+    let cardFrame: { width: number; height: number; textPath: string } | undefined;
+    if (program && sourceStream) {
+      const textPath = resolveInDataDir(path.posix.join("projects", project.id, "render", `${jobId}.cards.ass`));
+      await writeFile(textPath, toCardsAss(cardStartTimes(program), sourceStream), "utf-8");
+      cardFrame = { width: sourceStream.width, height: sourceStream.height, textPath };
+    }
+
     if (burnInCaptions) {
       if (!project.transcript) throw new Error("Captions were requested but this project has no transcript.");
       const transcript: Transcript = {
         id: project.transcript.id,
         segments: JSON.parse(project.transcript.segmentsJson),
       };
-      const sentenceCues = generateCaptions(transcript, cuts, project.duration);
+      const sentenceCues = cuesToProgramTime(generateCaptions(transcript, cuts, project.duration), cardSlots);
       const cues = clip ? splitCuesForShorts(sentenceCues) : sentenceCues;
       const subtitleExt = useKaraoke ? "ass" : "srt";
       const subtitleRelativePath = path.posix.join("projects", project.id, "render", `${jobId}.${subtitleExt}`);
@@ -227,7 +259,7 @@ export async function runRenderJob(
     const audioSettings = parseStoredAudioSettings(project.audioSettingsJson);
     const audioFilter = buildAudioFilterChain(
       audioSettings,
-      await resolveLoudnessGain(inputPath, playableRanges, audioSettings, jobId)
+      await resolveLoudnessGain(inputPath, playableRanges, audioSettings, jobId, program)
     );
 
     // Episode title + chapter markers, embedded so podcast apps and players
@@ -242,7 +274,11 @@ export async function runRenderJob(
       metadataPath = resolveInDataDir(path.posix.join("projects", project.id, "render", `${jobId}.ffmeta`));
       await writeFile(
         metadataPath,
-        toFfmetadata(resolveChapters(chapters, playableRanges), getEditedDuration(playableRanges), project.name),
+        toFfmetadata(
+          resolveProgramChapters(chapters, playableRanges, cardSlots),
+          getEditedDuration(playableRanges) + cardsDuration(cardSlots),
+          project.name
+        ),
         "utf-8"
       );
     }
@@ -267,8 +303,10 @@ export async function runRenderJob(
           metadataPath,
           reframe: clip && clipFrame ? { ...clipFrame, cropX: clip.cropX } : undefined,
           frameRate: sourceStream!.fps,
+          program,
+          cardFrame,
         })
-      : buildAudioOnlyRenderArgs({ inputPath, outputPath, playableRanges, audioFilter, format, metadataPath });
+      : buildAudioOnlyRenderArgs({ inputPath, outputPath, playableRanges, program, audioFilter, format, metadataPath });
     await runFfmpeg(args);
 
     const stats = await statAsset(outputRelativePath);
diff --git a/server/src/lib/publishing/chapters.ts b/server/src/lib/publishing/chapters.ts
index b7ccbf7..47dd777 100644
--- a/server/src/lib/publishing/chapters.ts
+++ b/server/src/lib/publishing/chapters.ts
@@ -8,6 +8,7 @@ import {
   type ResolvedChapter,
 } from "@/types/publishing";
 import type { PlayableRange } from "@/types/timeline";
+import { editedToProgramTime, type CardSlot } from "@/lib/timeline/program";
 
 /**
  * Chapter rules shared by AI output and user edits. Pure functions only, so
@@ -95,6 +96,22 @@ export function resolveChapters(chapters: Chapter[], ranges: PlayableRange[]): R
   return resolved;
 }
 
+/**
+ * resolveChapters, then onto the program timeline around any title cards.
+ * A chapter starting where a card plays starts with that card, so the
+ * marker shows the card rather than jumping past it.
+ */
+export function resolveProgramChapters(
+  chapters: Chapter[],
+  ranges: PlayableRange[],
+  slots: CardSlot[]
+): ResolvedChapter[] {
+  return resolveChapters(chapters, ranges).map((c) => ({
+    ...c,
+    start: c.start === 0 ? 0 : editedToProgramTime(c.start, slots, { includeCardsAtPoint: false }),
+  }));
+}
+
 /** "00:00 Intro" lines for a YouTube description or show notes. */
 export function toYoutubeChapters(chapters: ResolvedChapter[], totalSeconds: number): string {
   const longForm = totalSeconds >= 3600;

From 2997c189753b46eb9cae85a7e989cc7c2c304c5b Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:25:07 +0530
Subject: [PATCH 11/36] feat(server): chapters and transcript export on program
 time

The Publish panel's chapters, YouTube chapter list and the exported
transcript's timestamps now include title cards, so they match what the
export actually plays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 server/src/routes/publishing.ts | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/server/src/routes/publishing.ts b/server/src/routes/publishing.ts
index 66910dc..c6b4717 100644
--- a/server/src/routes/publishing.ts
+++ b/server/src/routes/publishing.ts
@@ -4,12 +4,13 @@ import { logger } from "@/lib/logger";
 import { prisma } from "@/lib/db/client";
 import { errorResponse } from "@/lib/http";
 import { computePlayableRanges, getEditedDuration } from "@/lib/timeline/cuts";
+import { cardsDuration, editedRangeToProgram, placeCards } from "@/lib/timeline/program";
 import { buildEditedSentences, formatTranscript } from "@/lib/publishing/edited-transcript";
 import {
   chaptersFromPicks,
   cleanChapterTitle,
   minChapterSeconds,
-  resolveChapters,
+  resolveProgramChapters,
   toYoutubeChapters,
 } from "@/lib/publishing/chapters";
 import { generateChapterPicks, generateShowNotes } from "@/lib/ai/publishing";
@@ -32,16 +33,22 @@ async function loadEditedProject(id: string) {
   if (project.duration === null) return fail("NO_DURATION", "This project's video duration isn't known yet.", 400);
 
   const transcript: Transcript = { id: project.transcript.id, segments: JSON.parse(project.transcript.segmentsJson) };
-  const cuts = project.editOperations
-    .map((op) => JSON.parse(op.dataJson) as EditOperation)
-    .filter((op): op is CutOperation => op.type === "cut");
+  const operations = project.editOperations.map((op) => JSON.parse(op.dataJson) as EditOperation);
+  const cuts = operations.filter((op): op is CutOperation => op.type === "cut");
   const ranges = computePlayableRanges(project.duration, cuts);
+  const cardSlots = placeCards(operations, ranges, project.duration);
   return {
     ok: true as const,
     project,
     ranges,
-    editedDuration: getEditedDuration(ranges),
-    sentences: buildEditedSentences(transcript, cuts, project.duration),
+    cardSlots,
+    // What the export will run for, title cards included.
+    programDuration: getEditedDuration(ranges) + cardsDuration(cardSlots),
+    // Timestamps as heard in the export, title cards included.
+    sentences: buildEditedSentences(transcript, cuts, project.duration).map((sentence) => ({
+      ...sentence,
+      ...editedRangeToProgram(sentence.start, sentence.end, cardSlots),
+    })),
     chapters: project.publishingMeta?.chaptersJson ? (JSON.parse(project.publishingMeta.chaptersJson) as Chapter[]) : [],
     showNotes: project.publishingMeta?.showNotesJson
       ? (JSON.parse(project.publishingMeta.showNotesJson) as ShowNotes)
@@ -52,11 +59,11 @@ async function loadEditedProject(id: string) {
 type Loaded = Extract<Awaited<ReturnType<typeof loadEditedProject>>, { ok: true }>;
 
 function publishingResponse(c: Context, loaded: Loaded, chapters: Chapter[], showNotes: ShowNotes | null) {
-  const resolved = resolveChapters(chapters, loaded.ranges);
+  const resolved = resolveProgramChapters(chapters, loaded.ranges, loaded.cardSlots);
   return c.json({
     success: true,
     chapters: resolved,
-    youtubeChapters: toYoutubeChapters(resolved, loaded.editedDuration),
+    youtubeChapters: toYoutubeChapters(resolved, loaded.programDuration),
     showNotes,
   });
 }
@@ -88,7 +95,7 @@ publishingRoute.post("/:id/publishing/chapters", async (c) => {
   }
 
   try {
-    const minGap = minChapterSeconds(loaded.editedDuration);
+    const minGap = minChapterSeconds(loaded.programDuration);
     const picks = await generateChapterPicks(loaded.sentences, minGap);
     const chapters = chaptersFromPicks(picks, loaded.sentences, minGap);
     await saveMeta(id, { chaptersJson: JSON.stringify(chapters) });

From 7b786f999a424db05a64c7900ce1e93bdb305c70 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:25:07 +0530
Subject: [PATCH 12/36] feat(client): preview title cards in the player

The preview can't insert frames into a <video>, so useCardPlayback pauses
the video where a card plays, shows CardPreview on a clock of its own
(same layout percentages as the export, in cqh units), then resumes;
cards at the same moment play back to back, and outros play once the
last kept range ends. The scrubber and timecode run on program time.
Paused exactly where a card plays, the playhead sits at the card's start,
since the card is still ahead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../components/video-player/CardPreview.tsx   |  57 ++++++++
 .../components/video-player/VideoPlayer.tsx   |  73 ++++++----
 .../video-player/useCardPlayback.ts           | 137 ++++++++++++++++++
 client/src/lib/cards/layout.ts                |  88 +++++++++++
 client/src/lib/timeline/useProgram.ts         |  67 +++++++++
 client/src/stores/player-store.ts             |  18 ++-
 6 files changed, 414 insertions(+), 26 deletions(-)
 create mode 100644 client/src/components/video-player/CardPreview.tsx
 create mode 100644 client/src/components/video-player/useCardPlayback.ts
 create mode 100644 client/src/lib/cards/layout.ts
 create mode 100644 client/src/lib/timeline/useProgram.ts

diff --git a/client/src/components/video-player/CardPreview.tsx b/client/src/components/video-player/CardPreview.tsx
new file mode 100644
index 0000000..ac5094d
--- /dev/null
+++ b/client/src/components/video-player/CardPreview.tsx
@@ -0,0 +1,57 @@
+import type { CSSProperties } from "react";
+import {
+  CARD_FONT,
+  CARD_SECONDARY_OPACITY,
+  CARD_TEXT_WIDTH_PERCENT,
+  cardTextColor,
+  cardTextOpacity,
+  layoutCard,
+  type CardLine,
+} from "@/lib/cards/layout";
+import type { CardOperation } from "@/types/edit-operation";
+
+/**
+ * A title card over the player, laid out from the same percentages the
+ * export burns in (lib/cards/layout.ts): sizes in `cqh` against the player's
+ * aspect-matched container, like the caption preview. `elapsed` drives the
+ * text fade; omit it for a static preview (the card editor).
+ */
+export function CardPreview({ card, elapsed }: { card: CardOperation; elapsed?: number }) {
+  const color = cardTextColor(card.background);
+  const opacity = elapsed === undefined ? 1 : cardTextOpacity(elapsed, card.duration);
+
+  const position = (line: CardLine): CSSProperties => {
+    switch (line.anchor) {
+      case "above":
+        return { bottom: `${100 - line.yPercent}%` };
+      case "below":
+        return { top: `${line.yPercent}%` };
+      default:
+        return { top: `${line.yPercent}%`, transform: "translateY(-50%)" };
+    }
+  };
+
+  return (
+    <div className="pointer-events-none absolute inset-0" style={{ backgroundColor: card.background }}>
+      {layoutCard(card).map((line, i) => (
+        <div
+          key={i}
+          className="absolute text-center leading-[1.15]"
+          style={{
+            ...position(line),
+            left: `${(100 - CARD_TEXT_WIDTH_PERCENT) / 2}%`,
+            width: `${CARD_TEXT_WIDTH_PERCENT}%`,
+            fontFamily: CARD_FONT,
+            fontSize: `${line.sizePercent}cqh`,
+            fontWeight: line.bold ? 700 : 400,
+            fontStyle: line.italic ? "italic" : "normal",
+            color,
+            opacity: opacity * (line.secondary ? CARD_SECONDARY_OPACITY : 1),
+          }}
+        >
+          {line.text}
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/client/src/components/video-player/VideoPlayer.tsx b/client/src/components/video-player/VideoPlayer.tsx
index 1c62e2b..201f47c 100644
--- a/client/src/components/video-player/VideoPlayer.tsx
+++ b/client/src/components/video-player/VideoPlayer.tsx
@@ -3,26 +3,21 @@
 import { useEffect, useId, useRef, useState, type CSSProperties } from "react";
 import { Maximize, Minimize, Pause, Play, Volume2, VolumeX } from "lucide-react";
 import { usePlayerStore } from "@/stores/player-store";
-import { useTimelineStore } from "@/stores/timeline-store";
 import { useTranscriptStore } from "@/stores/transcript-store";
 import { useProjectStore } from "@/stores/project-store";
 import { useCaptionStyleStore } from "@/stores/caption-style-store";
 import { CAPTION_MARGIN_V_PERCENT, type CaptionPosition } from "@/lib/captions/style";
-import {
-  computePlayableRanges,
-  editedTimeToSourceTime,
-  getEditedDuration,
-  isCut,
-  nextPlayableTime,
-  sourceTimeToEditedTime,
-} from "@/lib/timeline/cuts";
+import { editedTimeToSourceTime, isCut, nextPlayableTime, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
+import { locateProgramTime } from "@/lib/timeline/program";
+import { programPlayhead, useProgram } from "@/lib/timeline/useProgram";
+import { useCardPlayback } from "@/components/video-player/useCardPlayback";
+import { CardPreview } from "@/components/video-player/CardPreview";
 import { generateCaptions } from "@/lib/captions/generate";
 import { formatTimecode } from "@/lib/timeline/format";
 import { getFilterPreset } from "@/lib/video/filters";
 import { buildPropertiesCss, buildPropertiesSvgValues } from "@/lib/video/properties";
 import { logoPositionToCss } from "@/lib/video/logo";
 import { CropOverlay } from "@/components/video-player/CropOverlay";
-import type { CutOperation } from "@/types/edit-operation";
 
 /**
  * Approximates libass's numpad-alignment vertical placement (see
@@ -96,13 +91,20 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
     }
   };
 
-  const operations = useTimelineStore((s) => s.operations);
-  const cuts = operations.filter((op): op is CutOperation => op.type === "cut");
-  const playableRanges = computePlayableRanges(duration, cuts);
-  const editedDuration = getEditedDuration(playableRanges);
+  const program = useProgram();
+  const { cuts, ranges: playableRanges, editedDuration } = program;
   const editedCurrentTime =
     editedDuration > 0 ? sourceTimeToEditedTime(currentTime, playableRanges) : 0;
-  const playheadPosition = editedDuration > 0 ? (editedCurrentTime / editedDuration) * 100 : 0;
+
+  // Title cards: the player shows them over a paused video (useCardPlayback),
+  // and the scrubber/timecode run on program time, cards included.
+  const card = usePlayerStore((s) => s.card);
+  const setCard = usePlayerStore((s) => s.setCard);
+  const cardDraft = usePlayerStore((s) => s.cardDraft);
+  const activeCard = card ? program.slots.find((s) => s.card.id === card.id)?.card : undefined;
+  const cardPlayback = useCardPlayback(videoRef, program);
+  const programTime = programPlayhead(program, currentTime, card);
+  const playheadPosition = program.duration > 0 ? (programTime / program.duration) * 100 : 0;
 
   const transcript = useTranscriptStore((s) => s.transcript);
   const captionCues = transcript && duration > 0 ? generateCaptions(transcript, cuts, duration) : [];
@@ -115,23 +117,31 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
   const togglePlay = () => {
     const video = videoRef.current;
     if (!video) return;
+    if (cardPlayback.togglePlay()) return;
     if (video.paused) video.play();
     else video.pause();
   };
 
   const handleScrubberClick = (e: React.MouseEvent<HTMLDivElement>) => {
-    if (!scrubberRef.current || editedDuration <= 0) return;
+    if (!scrubberRef.current || program.duration <= 0) return;
     const rect = scrubberRef.current.getBoundingClientRect();
     const ratio = Math.min(Math.max((e.clientX - rect.left) / rect.width, 0), 1);
-    seek(editedTimeToSourceTime(ratio * editedDuration, playableRanges));
+    const target = locateProgramTime(ratio * program.duration, program.slots);
+    if (target.card) {
+      seek(target.card.resumeAt);
+      setCard({ id: target.card.card.id, elapsed: target.cardOffset });
+    } else {
+      seek(editedTimeToSourceTime(target.editedTime, playableRanges));
+    }
   };
 
   // Handle imperative seeks requested elsewhere (transcript click, timeline click).
   useEffect(() => {
     if (seekTarget === null || !videoRef.current) return;
     videoRef.current.currentTime = seekTarget;
+    cardPlayback.noteSeek(seekTarget);
     clearSeekTarget();
-  }, [seekTarget, clearSeekTarget]);
+  }, [seekTarget, clearSeekTarget, cardPlayback]);
 
   // A blob-URL video can reach readyState >= HAVE_METADATA (and fire its
   // loadedmetadata event) before React finishes attaching the listener on
@@ -213,11 +223,13 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
       if (playableRanges.length > 0 && isCut(metadata.mediaTime, playableRanges)) {
         const next = nextPlayableTime(metadata.mediaTime, playableRanges);
         if (next === null) {
-          video.pause();
+          if (!cardPlayback.handleEnd()) video.pause();
         } else {
           pendingSeekTarget = next;
           video.currentTime = next;
         }
+      } else {
+        cardPlayback.handleFrame(metadata.mediaTime, video.paused);
       }
       handle = video.requestVideoFrameCallback(onFrame);
     };
@@ -226,7 +238,7 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
     return () => {
       if (handle !== null) video.cancelVideoFrameCallback(handle);
     };
-  }, [playableRanges]);
+  }, [playableRanges, cardPlayback]);
 
   const supportsVideoFrameCallback =
     typeof HTMLVideoElement !== "undefined" && "requestVideoFrameCallback" in HTMLVideoElement.prototype;
@@ -242,10 +254,12 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
     if (isCut(video.currentTime, playableRanges)) {
       const next = nextPlayableTime(video.currentTime, playableRanges);
       if (next === null) {
-        video.pause();
+        if (!cardPlayback.handleEnd()) video.pause();
       } else {
         video.currentTime = next;
       }
+    } else {
+      cardPlayback.handleFrame(video.currentTime, video.paused);
     }
   };
 
@@ -290,7 +304,14 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
           onLoadedMetadata={(e) => handleDurationKnown(e.currentTarget)}
           onTimeUpdate={handleTimeUpdate}
           onPlay={() => setIsPlaying(true)}
-          onPause={() => setIsPlaying(false)}
+          onPause={() => {
+            if (cardPlayback.ignorePauseRef.current) {
+              cardPlayback.ignorePauseRef.current = false;
+              return;
+            }
+            setIsPlaying(false);
+          }}
+          onEnded={() => cardPlayback.handleEnd()}
           data-playing={isPlaying}
         />
         <CropOverlay />
@@ -303,7 +324,9 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
             style={logoPositionToCss(logoPosition, logoPaddingX, logoPaddingY, logoOpacity)}
           />
         )}
-        {burnInCaptions && activeCue && (
+        {activeCard && <CardPreview card={activeCard} elapsed={card?.elapsed} />}
+        {cardDraft && <CardPreview card={cardDraft} />}
+        {burnInCaptions && activeCue && !activeCard && !cardDraft && (
           <div
             className="pointer-events-none absolute inset-x-0 flex justify-center px-4"
             style={CAPTION_VERTICAL_STYLE[captionStyle.position]}
@@ -344,7 +367,7 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
         <button
           type="button"
           onClick={togglePlay}
-          disabled={editedDuration <= 0}
+          disabled={program.duration <= 0}
           className="flex size-6 shrink-0 items-center justify-center rounded text-white hover:bg-white/10 disabled:pointer-events-none disabled:opacity-50"
         >
           {isPlaying ? <Pause className="size-3.5" /> : <Play className="size-3.5" />}
@@ -360,7 +383,7 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
           />
         </div>
         <span className="font-mono text-xs tabular-nums text-white/70">
-          {formatTimecode(editedCurrentTime)} / {formatTimecode(editedDuration)}
+          {formatTimecode(programTime)} / {formatTimecode(program.duration)}
         </span>
         <button
           type="button"
diff --git a/client/src/components/video-player/useCardPlayback.ts b/client/src/components/video-player/useCardPlayback.ts
new file mode 100644
index 0000000..953c93a
--- /dev/null
+++ b/client/src/components/video-player/useCardPlayback.ts
@@ -0,0 +1,137 @@
+import { useCallback, useEffect, useMemo, useRef, type RefObject } from "react";
+import { usePlayerStore } from "@/stores/player-store";
+import type { CardSlot } from "@/lib/timeline/program";
+import type { Program } from "@/lib/timeline/useProgram";
+
+const EPSILON = 0.001;
+
+/**
+ * Plays title cards in the preview. The export renders cards as real frames
+ * (lib/ffmpeg/plan.ts); the preview can't insert frames into a <video>, so
+ * when playback crosses the moment a card plays before, it pauses the video
+ * on that moment, shows the card (CardPreview) on a clock of its own, then
+ * resumes. Cards at the same moment play back to back; outro cards play
+ * once the last kept range ends.
+ *
+ * The player store's `card` is the source of truth, so the timeline can
+ * also open a card directly (clicking its block).
+ */
+export function useCardPlayback(videoRef: RefObject<HTMLVideoElement | null>, program: Program) {
+  const card = usePlayerStore((s) => s.card);
+  const isPlaying = usePlayerStore((s) => s.isPlaying);
+  const setCard = usePlayerStore((s) => s.setCard);
+  const setIsPlaying = usePlayerStore((s) => s.setIsPlaying);
+
+  /** Source time of the last frame seen while playing; -1 so an intro card at 0 plays on the first frame. */
+  const lastTimeRef = useRef(-1);
+  /** Set when we pause the video ourselves, so onPause doesn't read it as the user stopping. */
+  const ignorePauseRef = useRef(false);
+  const outroPlayedRef = useRef(false);
+
+  const { slots, editedDuration } = program;
+  const isOutro = useCallback((s: CardSlot) => s.editedAt >= editedDuration - EPSILON, [editedDuration]);
+
+  const start = useCallback(
+    (slot: CardSlot) => {
+      const video = videoRef.current;
+      if (video && !video.paused) {
+        ignorePauseRef.current = true;
+        video.pause();
+      }
+      if (video && !isOutro(slot)) video.currentTime = slot.resumeAt;
+      setCard({ id: slot.card.id, elapsed: 0 });
+      setIsPlaying(true);
+    },
+    [videoRef, isOutro, setCard, setIsPlaying]
+  );
+
+  /** Called for every presented frame while playing. True when a card took over. */
+  const handleFrame = useCallback(
+    (mediaTime: number, paused: boolean): boolean => {
+      if (usePlayerStore.getState().card) return true;
+      if (paused) return false;
+      const last = lastTimeRef.current;
+      lastTimeRef.current = mediaTime;
+      const crossed = slots.find(
+        (s) => !isOutro(s) && s.resumeAt > last + EPSILON / 2 && s.resumeAt <= mediaTime + EPSILON
+      );
+      if (crossed) {
+        start(crossed);
+        return true;
+      }
+      return false;
+    },
+    [slots, isOutro, start]
+  );
+
+  /** Called when playback runs off the end of the last kept range. True when an outro took over. */
+  const handleEnd = useCallback((): boolean => {
+    if (usePlayerStore.getState().card) return true;
+    if (outroPlayedRef.current) return false;
+    const outro = slots.find(isOutro);
+    if (!outro) return false;
+    outroPlayedRef.current = true;
+    start(outro);
+    return true;
+  }, [slots, isOutro, start]);
+
+  /** A seek resets what counts as "crossed": a card exactly at the target plays when playback starts. */
+  const noteSeek = useCallback((target: number) => {
+    lastTimeRef.current = target - EPSILON;
+    outroPlayedRef.current = false;
+  }, []);
+
+  /** Play/pause while a card shows only runs or stops the card's clock. True when handled. */
+  const togglePlay = useCallback((): boolean => {
+    if (!usePlayerStore.getState().card) return false;
+    setIsPlaying(!usePlayerStore.getState().isPlaying);
+    return true;
+  }, [setIsPlaying]);
+
+  // The card clock. Finishing a card moves to the next one at the same
+  // moment, or resumes the video (stops, after the last outro).
+  useEffect(() => {
+    if (!card || !isPlaying) return;
+    const slot = slots.find((s) => s.card.id === card.id);
+    if (!slot) {
+      setCard(null);
+      return;
+    }
+    let frame = 0;
+    let previous = performance.now();
+    let elapsed = card.elapsed;
+    const tick = (now: number) => {
+      elapsed += (now - previous) / 1000;
+      previous = now;
+      if (elapsed < slot.card.duration) {
+        setCard({ id: card.id, elapsed });
+        frame = requestAnimationFrame(tick);
+        return;
+      }
+      const samePoint = slots.filter((s) => Math.abs(s.editedAt - slot.editedAt) <= EPSILON);
+      const next = samePoint[samePoint.indexOf(slot) + 1];
+      if (next) {
+        setCard({ id: next.card.id, elapsed: 0 });
+        return;
+      }
+      setCard(null);
+      lastTimeRef.current = slot.resumeAt;
+      if (isOutro(slot)) {
+        setIsPlaying(false);
+      } else {
+        videoRef.current?.play();
+      }
+    };
+    frame = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame);
+    // card.elapsed is read once per start; re-running on every tick would restart the clock.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [card?.id, isPlaying, slots, isOutro, setCard, setIsPlaying, videoRef]);
+
+  // Stable across renders: VideoPlayer's frame-callback effect depends on
+  // this, and re-registering it every render would reset its seek guard.
+  return useMemo(
+    () => ({ handleFrame, handleEnd, noteSeek, togglePlay, ignorePauseRef }),
+    [handleFrame, handleEnd, noteSeek, togglePlay]
+  );
+}
diff --git a/client/src/lib/cards/layout.ts b/client/src/lib/cards/layout.ts
new file mode 100644
index 0000000..f2aac23
--- /dev/null
+++ b/client/src/lib/cards/layout.ts
@@ -0,0 +1,88 @@
+import type { CardOperation } from "@/types/edit-operation";
+
+/**
+ * Where each line of a title card goes, as percentages of the frame, so
+ * the HTML preview (CardPreview.tsx, in cqh units) and the burned-in ASS
+ * (lib/cards/ass.ts, against PlayResX/Y = the output size) lay out the
+ * same card the same way at any resolution. Duplicated, not imported,
+ * across the client/server boundary -- keep both copies identical.
+ *
+ * `anchor` says which edge of the text block sits on `yPercent`: a title
+ * anchored "above" a line grows upward as it wraps, and a subtitle
+ * anchored "below" grows downward, so the two never overlap.
+ */
+export type CardLine = {
+  text: string;
+  /** Font size, percent of frame height. */
+  sizePercent: number;
+  anchor: "above" | "below" | "center";
+  yPercent: number;
+  bold: boolean;
+  italic: boolean;
+  /** Secondary lines render slightly faded. */
+  secondary: boolean;
+};
+
+export const CARD_FONT = "Arial";
+/** Text wraps inside this much of the frame width. */
+export const CARD_TEXT_WIDTH_PERCENT = 80;
+/** Card text fades in and out over this long (the background cuts in). */
+export const CARD_TEXT_FADE_SECONDS = 0.25;
+export const CARD_SECONDARY_OPACITY = 0.8;
+
+export function layoutCard(card: Pick<CardOperation, "template" | "title" | "subtitle">): CardLine[] {
+  const title = card.title.trim();
+  const subtitle = card.subtitle?.trim() ?? "";
+  const line = (text: string, sizePercent: number, anchor: CardLine["anchor"], yPercent: number, rest: Partial<CardLine> = {}): CardLine => ({
+    text,
+    sizePercent,
+    anchor,
+    yPercent,
+    bold: false,
+    italic: false,
+    secondary: false,
+    ...rest,
+  });
+
+  switch (card.template) {
+    case "chapter":
+      return subtitle
+        ? [
+            line(subtitle.toUpperCase(), 3.5, "above", 44, { bold: true, secondary: true }),
+            line(title, 8, "below", 46, { bold: true }),
+          ]
+        : [line(title, 8, "center", 50, { bold: true })];
+    case "quote":
+      return [
+        line(`“${title}”`, 6, subtitle ? "above" : "center", subtitle ? 55 : 50, { italic: true }),
+        ...(subtitle ? [line(`— ${subtitle}`, 3.5, "below", 59, { secondary: true })] : []),
+      ];
+    case "outro":
+    case "title":
+    default: {
+      const size = card.template === "outro" ? 7 : 8;
+      return subtitle
+        ? [line(title, size, "above", 52, { bold: true }), line(subtitle, 4, "below", 55, { secondary: true })]
+        : [line(title, size, "center", 50, { bold: true })];
+    }
+  }
+}
+
+/** Dark text on light backgrounds, white on dark (WCAG relative luminance). */
+export function cardTextColor(background: string): string {
+  const channel = (i: number) => {
+    const c = parseInt(background.slice(i, i + 2), 16) / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  const luminance = 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
+  return luminance > 0.4 ? "#111111" : "#FFFFFF";
+}
+
+/** Opacity of card text `offset` seconds into a card lasting `duration`. */
+export function cardTextOpacity(offset: number, duration: number): number {
+  const fade = Math.min(CARD_TEXT_FADE_SECONDS, duration / 4);
+  return Math.max(0, Math.min(1, offset / fade, (duration - offset) / fade));
+}
+
+/** Preset backgrounds offered in the card editor. */
+export const CARD_BACKGROUNDS = ["#111418", "#1E3A5F", "#7C2D12", "#14532D", "#F5F0E6", "#FFFFFF"] as const;
diff --git a/client/src/lib/timeline/useProgram.ts b/client/src/lib/timeline/useProgram.ts
new file mode 100644
index 0000000..0f7823c
--- /dev/null
+++ b/client/src/lib/timeline/useProgram.ts
@@ -0,0 +1,67 @@
+import { useMemo } from "react";
+import { usePlayerStore } from "@/stores/player-store";
+import { useTimelineStore } from "@/stores/timeline-store";
+import { computePlayableRanges, getEditedDuration, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
+import {
+  buildProgramItems,
+  cardsDuration,
+  editedToProgramTime,
+  placeCards,
+  type CardSlot,
+  type ProgramItem,
+} from "@/lib/timeline/program";
+import type { CutOperation } from "@/types/edit-operation";
+import type { PlayableRange } from "@/types/timeline";
+
+export type Program = {
+  cuts: CutOperation[];
+  ranges: PlayableRange[];
+  slots: CardSlot[];
+  items: ProgramItem[];
+  editedDuration: number;
+  /** Edited duration plus every card: what the export runs for. */
+  duration: number;
+};
+
+/** The project's program (lib/timeline/program.ts), derived from the timeline store. */
+export function useProgram(): Program {
+  const sourceDuration = usePlayerStore((s) => s.duration);
+  const operations = useTimelineStore((s) => s.operations);
+
+  return useMemo(() => {
+    const cuts = operations.filter((op): op is CutOperation => op.type === "cut");
+    const ranges = computePlayableRanges(sourceDuration, cuts);
+    const slots = sourceDuration > 0 ? placeCards(operations, ranges, sourceDuration) : [];
+    const editedDuration = getEditedDuration(ranges);
+    return {
+      cuts,
+      ranges,
+      slots,
+      items: buildProgramItems(ranges, slots),
+      editedDuration,
+      duration: editedDuration + cardsDuration(slots),
+    };
+  }, [operations, sourceDuration]);
+}
+
+/**
+ * Where the playhead is on the program timeline: inside the card on screen,
+ * or at the source time the <video> is on.
+ */
+export function programPlayhead(
+  program: Program,
+  sourceTime: number,
+  card: { id: string; elapsed: number } | null
+): number {
+  if (card) {
+    let t = 0;
+    for (const item of program.items) {
+      if (item.kind === "card" && item.card.id === card.id) return t + card.elapsed;
+      t += item.kind === "card" ? item.card.duration : item.end - item.start;
+    }
+  }
+  const edited = program.editedDuration > 0 ? sourceTimeToEditedTime(sourceTime, program.ranges) : 0;
+  // Paused exactly where a card plays (e.g. at 0 with an intro): the card
+  // is still ahead, so the playhead sits at its start rather than past it.
+  return editedToProgramTime(edited, program.slots, { includeCardsAtPoint: false });
+}
diff --git a/client/src/stores/player-store.ts b/client/src/stores/player-store.ts
index d29a06f..7698d12 100644
--- a/client/src/stores/player-store.ts
+++ b/client/src/stores/player-store.ts
@@ -1,4 +1,5 @@
 import { create } from "zustand";
+import type { CardOperation } from "@/types/edit-operation";
 
 type PlayerStore = {
   currentTime: number;
@@ -17,6 +18,14 @@ type PlayerStore = {
    * video that the exported file never had).
    */
   aspectRatio: number | null;
+  /**
+   * The title card on screen, and how far into it playback is. While a
+   * card shows, the <video> is paused on the frame after it and
+   * `isPlaying` means "the card's clock is running" (useCardPlayback.ts).
+   */
+  card: { id: string; elapsed: number } | null;
+  /** A card being edited in the Scenes panel, previewed over the player until the editor closes. */
+  cardDraft: CardOperation | null;
 
   setDuration: (duration: number) => void;
   setCurrentTime: (time: number) => void;
@@ -25,6 +34,8 @@ type PlayerStore = {
   clearSeekTarget: () => void;
   setVideoElement: (el: HTMLVideoElement | null) => void;
   setAspectRatio: (ratio: number | null) => void;
+  setCard: (card: { id: string; elapsed: number } | null) => void;
+  setCardDraft: (card: CardOperation | null) => void;
 };
 
 export const usePlayerStore = create<PlayerStore>((set) => ({
@@ -34,12 +45,17 @@ export const usePlayerStore = create<PlayerStore>((set) => ({
   seekTarget: null,
   videoElement: null,
   aspectRatio: null,
+  card: null,
+  cardDraft: null,
 
   setDuration: (duration) => set({ duration }),
   setCurrentTime: (time) => set({ currentTime: time }),
   setIsPlaying: (playing) => set({ isPlaying: playing }),
-  seek: (time) => set({ seekTarget: time }),
+  // Seeking anywhere leaves whatever card was showing.
+  seek: (time) => set({ seekTarget: time, card: null }),
   clearSeekTarget: () => set({ seekTarget: null }),
   setVideoElement: (videoElement) => set({ videoElement }),
   setAspectRatio: (aspectRatio) => set({ aspectRatio }),
+  setCard: (card) => set({ card }),
+  setCardDraft: (cardDraft) => set({ cardDraft }),
 }));

From f795827658b0f85ad8ba5d7b5bcaf478c645c17d Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:25:07 +0530
Subject: [PATCH 13/36] feat(client): show title cards on the timeline

The track is laid out on program time: footage with each card as a block
in its own color between it. Clicking a card opens it in the player;
scene blocks start at their card, and pause markers and scene boundaries
are placed around cards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/components/timeline/Timeline.tsx | 176 ++++++++++++--------
 1 file changed, 111 insertions(+), 65 deletions(-)

diff --git a/client/src/components/timeline/Timeline.tsx b/client/src/components/timeline/Timeline.tsx
index 5cbbe7a..3d24d32 100644
--- a/client/src/components/timeline/Timeline.tsx
+++ b/client/src/components/timeline/Timeline.tsx
@@ -5,21 +5,18 @@ import { usePlayerStore } from "@/stores/player-store";
 import { useProjectStore } from "@/stores/project-store";
 import { useTimelineStore } from "@/stores/timeline-store";
 import { useTranscriptStore } from "@/stores/transcript-store";
-import {
-  computePlayableRanges,
-  editedTimeToSourceTime,
-  getEditedDuration,
-  sourceTimeToEditedTime,
-} from "@/lib/timeline/cuts";
+import { editedTimeToSourceTime, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
+import { editedToProgramTime, locateProgramTime, programItemDuration } from "@/lib/timeline/program";
+import { programPlayhead, useProgram } from "@/lib/timeline/useProgram";
 import { formatTimecode } from "@/lib/timeline/format";
 import { useWaveform } from "@/lib/timeline/useWaveform";
 import { DEFAULT_INTERVAL_SECONDS, MIN_INTERVAL_SECONDS, useThumbnails } from "@/lib/timeline/useThumbnails";
+import { cardTextColor } from "@/lib/cards/layout";
 import { Button } from "@/components/ui/button";
 import { Waveform } from "@/components/timeline/Waveform";
 import { useScenes } from "@/lib/timeline/useScenes";
 import { sceneColor } from "@/lib/timeline/scenes";
 import { Scissors } from "lucide-react";
-import type { CutOperation } from "@/types/edit-operation";
 
 /** Zoom is relative to "fit" (1x = whole timeline visible, no scrolling). */
 const MIN_ZOOM = 1;
@@ -37,7 +34,9 @@ export function Timeline() {
 
   const duration = usePlayerStore((s) => s.duration);
   const currentTime = usePlayerStore((s) => s.currentTime);
+  const card = usePlayerStore((s) => s.card);
   const seek = usePlayerStore((s) => s.seek);
+  const setCard = usePlayerStore((s) => s.setCard);
 
   const silenceGaps = useTranscriptStore((s) => s.silenceGaps);
 
@@ -47,36 +46,35 @@ export function Timeline() {
   // existed fall back to decoding the video's own audio.
   const audioBuffer = useWaveform(audioUrl ?? videoUrl);
 
-  const operations = useTimelineStore((s) => s.operations);
   const undo = useTimelineStore((s) => s.undo);
   const redo = useTimelineStore((s) => s.redo);
   const undoStack = useTimelineStore((s) => s.undoStack);
   const redoStack = useTimelineStore((s) => s.redoStack);
   const { scenes, splitAt } = useScenes();
 
-  const cuts = useMemo(
-    () => operations.filter((op): op is CutOperation => op.type === "cut"),
-    [operations]
-  );
-  const playableRanges = useMemo(
-    () => computePlayableRanges(duration, cuts),
-    [duration, cuts]
-  );
-  const editedDuration = getEditedDuration(playableRanges);
-  const editedCurrentTime =
-    editedDuration > 0 ? sourceTimeToEditedTime(currentTime, playableRanges) : 0;
-  const playheadPosition = editedDuration > 0 ? (editedCurrentTime / editedDuration) * 100 : 0;
+  // Everything on the track is laid out on program time: kept footage with
+  // title cards in between (lib/timeline/program.ts).
+  const program = useProgram();
+  const { cuts, ranges: playableRanges, slots } = program;
+  const totalDuration = program.duration;
+  const programTime = programPlayhead(program, currentTime, card);
+  const playheadPosition = totalDuration > 0 ? (programTime / totalDuration) * 100 : 0;
+  /** Percent across the track of a source time (after any card at that moment unless noted). */
+  const percentAt = (sourceTime: number, includeCardsAtPoint = true) =>
+    (editedToProgramTime(sourceTimeToEditedTime(sourceTime, playableRanges), slots, { includeCardsAtPoint }) /
+      totalDuration) *
+    100;
 
   // Establish the "fit the whole timeline, no scrolling" baseline (zoom 1x) once we
-  // know both the edited duration and the scroll container's actual width. Only set
+  // know both the program duration and the scroll container's actual width. Only set
   // once per video -- re-measuring on every edit would reset the user's zoom level.
   useEffect(() => {
-    if (fitPxPerSecond !== null || editedDuration <= 0 || !scrollContainerRef.current) return;
-    setFitPxPerSecond(scrollContainerRef.current.clientWidth / editedDuration);
-  }, [editedDuration, fitPxPerSecond]);
+    if (fitPxPerSecond !== null || totalDuration <= 0 || !scrollContainerRef.current) return;
+    setFitPxPerSecond(scrollContainerRef.current.clientWidth / totalDuration);
+  }, [totalDuration, fitPxPerSecond]);
 
   const pxPerSecond = fitPxPerSecond !== null ? fitPxPerSecond * zoom : 0;
-  const trackWidth = pxPerSecond > 0 ? editedDuration * pxPerSecond : 0;
+  const trackWidth = pxPerSecond > 0 ? totalDuration * pxPerSecond : 0;
 
   // Denser thumbnails as you zoom in -- targets a roughly constant on-screen
   // thumbnail width instead of the same fixed set of images stretching
@@ -91,27 +89,57 @@ export function Timeline() {
       : DEFAULT_INTERVAL_SECONDS;
   const thumbnails = useThumbnails(videoUrl, duration, cuts, thumbnailIntervalSeconds);
 
+  /**
+   * Thumbnails are grabbed per playable range; a card inserted mid-range
+   * splits it into two source items, so each item shows its share of its
+   * range's filmstrip.
+   */
+  const itemThumbnails = useMemo(
+    () =>
+      program.items.map((item) => {
+        if (item.kind === "card") return [];
+        const rangeIndex = playableRanges.findIndex((r) => item.start >= r.start - 0.001 && item.start < r.end);
+        const range = playableRanges[rangeIndex];
+        const strip = thumbnails[rangeIndex];
+        if (!range || !strip) return [];
+        const length = range.end - range.start;
+        const from = Math.floor(((item.start - range.start) / length) * strip.length);
+        const to = Math.ceil(((item.end - range.start) / length) * strip.length);
+        return strip.slice(from, Math.max(from + 1, to));
+      }),
+    [program.items, playableRanges, thumbnails]
+  );
+
   // Keep the playhead in view as it moves during playback, and when zoom changes.
   useEffect(() => {
     const container = scrollContainerRef.current;
     if (!container || pxPerSecond <= 0) return;
-    const playheadPx = editedCurrentTime * pxPerSecond;
+    const playheadPx = programTime * pxPerSecond;
     const visibleLeft = container.scrollLeft;
     const visibleRight = visibleLeft + container.clientWidth;
     if (playheadPx < visibleLeft || playheadPx > visibleRight) {
       container.scrollTo({ left: Math.max(0, playheadPx - container.clientWidth / 2), behavior: "smooth" });
     }
-  }, [editedCurrentTime, pxPerSecond]);
+  }, [programTime, pxPerSecond]);
 
   const handleZoomIn = () => setZoom((z) => Math.min(MAX_ZOOM, z * ZOOM_STEP));
   const handleZoomOut = () => setZoom((z) => Math.max(MIN_ZOOM, z / ZOOM_STEP));
 
+  /** Shows a card in the player, paused on its first frame. */
+  const openCard = (cardId: string, elapsed = 0) => {
+    const slot = slots.find((s) => s.card.id === cardId);
+    if (!slot) return;
+    seek(slot.resumeAt);
+    setCard({ id: cardId, elapsed });
+  };
+
   const handleTrackClick = (e: React.MouseEvent<HTMLDivElement>) => {
-    if (!trackRef.current || editedDuration <= 0) return;
+    if (!trackRef.current || totalDuration <= 0) return;
     const rect = trackRef.current.getBoundingClientRect();
     const ratio = Math.min(Math.max((e.clientX - rect.left) / rect.width, 0), 1);
-    const sourceTime = editedTimeToSourceTime(ratio * editedDuration, playableRanges);
-    seek(sourceTime);
+    const target = locateProgramTime(ratio * totalDuration, slots);
+    if (target.card) openCard(target.card.card.id, target.cardOffset);
+    else seek(editedTimeToSourceTime(target.editedTime, playableRanges));
   };
 
   return (
@@ -120,7 +148,7 @@ export function Timeline() {
         <div className="flex items-baseline gap-2">
           <span className="text-[0.8rem] text-muted-foreground">Timeline</span>
           <span className="font-mono text-xs tabular-nums text-muted-foreground">
-            {formatTimecode(editedCurrentTime)} / {formatTimecode(editedDuration)}
+            {formatTimecode(programTime)} / {formatTimecode(totalDuration)}
             {cuts.length > 0 && (
               <span className="text-destructive/80">
                 {" "}
@@ -170,24 +198,23 @@ export function Timeline() {
           className="flex flex-col gap-2"
           style={{ width: trackWidth > 0 ? `${trackWidth}px` : "100%" }}
         >
-          {scenes.length > 1 && editedDuration > 0 && (
+          {scenes.length > 1 && totalDuration > 0 && (
             <div className="relative h-5 w-full">
               {scenes.map((scene) => {
-                const width = scene.editedEnd - scene.editedStart;
-                if (width <= 0) return null;
+                if (scene.editedEnd - scene.editedStart <= 0) return null;
+                // A scene's block starts at its card, so the card reads as part of the scene.
+                const left = scene.index === 0 ? 0 : percentAt(scene.start, false);
+                const right = percentAt(scene.end, false);
                 return (
                   <button
                     key={scene.id}
                     type="button"
                     onClick={() => seek(scene.start)}
-                    title={`${scene.title} (${formatTimecode(width)})`}
+                    title={`${scene.title} (${formatTimecode(scene.editedEnd - scene.editedStart)})`}
                     className={`absolute top-0 h-full truncate rounded-sm border-l-2 px-1.5 text-left text-[0.65rem] leading-5 text-foreground hover:brightness-125 ${
                       sceneColor(scene.index).block
                     }`}
-                    style={{
-                      left: `${(scene.editedStart / editedDuration) * 100}%`,
-                      width: `${(width / editedDuration) * 100}%`,
-                    }}
+                    style={{ left: `${left}%`, width: `${(scene.index === scenes.length - 1 ? 100 : right) - left}%` }}
                   >
                     {scene.title}
                   </button>
@@ -200,32 +227,49 @@ export function Timeline() {
             onClick={handleTrackClick}
             className="relative flex h-24 w-full cursor-pointer overflow-hidden rounded-md border border-border bg-muted p-1.5"
           >
-            {playableRanges.map((r, i) => (
-              <div
-                key={i}
-                style={{ width: `${((r.end - r.start) / editedDuration) * 100}%` }}
-                className="flex h-full overflow-hidden rounded-sm border-r border-background bg-secondary last:border-r-0"
-                title={`${r.start.toFixed(1)}s – ${r.end.toFixed(1)}s`}
-              >
-                {thumbnails[i]?.map((src, k) => (
-                  <img
-                    key={k}
-                    src={src}
-                    alt=""
-                    className="h-full flex-1 border-r border-background/70 object-cover last:border-r-0"
-                    draggable={false}
-                  />
-                ))}
-              </div>
-            ))}
+            {program.items.map((item, i) =>
+              item.kind === "card" ? (
+                <div
+                  key={`card-${item.card.id}`}
+                  style={{
+                    width: `${(item.card.duration / totalDuration) * 100}%`,
+                    backgroundColor: item.card.background,
+                    color: cardTextColor(item.card.background),
+                  }}
+                  className={`flex h-full items-center justify-center overflow-hidden rounded-sm border-r border-background px-1 text-center text-[0.65rem] leading-tight font-semibold last:border-r-0 ${
+                    card?.id === item.card.id ? "ring-2 ring-primary ring-inset" : ""
+                  }`}
+                  title={`Title card: ${item.card.title} (${item.card.duration}s)`}
+                >
+                  <span className="line-clamp-3">{item.card.title}</span>
+                </div>
+              ) : (
+                <div
+                  key={`src-${i}-${item.start}`}
+                  style={{ width: `${((item.end - item.start) / totalDuration) * 100}%` }}
+                  className="flex h-full overflow-hidden rounded-sm border-r border-background bg-secondary last:border-r-0"
+                  title={`${item.start.toFixed(1)}s – ${item.end.toFixed(1)}s`}
+                >
+                  {itemThumbnails[i]?.map((src, k) => (
+                    <img
+                      key={k}
+                      src={src}
+                      alt=""
+                      className="h-full flex-1 border-r border-background/70 object-cover last:border-r-0"
+                      draggable={false}
+                    />
+                  ))}
+                </div>
+              )
+            )}
             {silenceGaps?.map((gap, i) => {
-              const left = (sourceTimeToEditedTime(gap.start, playableRanges) / editedDuration) * 100;
-              const right = (sourceTimeToEditedTime(gap.end, playableRanges) / editedDuration) * 100;
+              const left = percentAt(gap.start);
+              const right = percentAt(gap.end, false);
               return (
                 <div
                   key={i}
                   className="pointer-events-none absolute top-0 h-full bg-muted-foreground/50"
-                  style={{ left: `${left}%`, width: `${right - left}%` }}
+                  style={{ left: `${left}%`, width: `${Math.max(0, right - left)}%` }}
                   title={`Long pause: ${(gap.end - gap.start).toFixed(1)}s`}
                 />
               );
@@ -234,7 +278,7 @@ export function Timeline() {
               <div
                 key={scene.id}
                 className="pointer-events-none absolute top-0 h-full w-px bg-foreground/70"
-                style={{ left: `${(scene.editedStart / editedDuration) * 100}%` }}
+                style={{ left: `${percentAt(scene.start, false)}%` }}
               />
             ))}
             <div
@@ -242,15 +286,17 @@ export function Timeline() {
               style={{ left: `${playheadPosition}%` }}
             />
           </div>
-          {audioBuffer && editedDuration > 0 && (
+          {audioBuffer && totalDuration > 0 && (
             <div className="flex h-12 w-full overflow-hidden rounded-md border border-border bg-muted p-1.5">
-              {playableRanges.map((r, i) => (
+              {program.items.map((item, i) => (
                 <div
                   key={i}
-                  style={{ width: `${((r.end - r.start) / editedDuration) * 100}%` }}
+                  style={{ width: `${(programItemDuration(item) / totalDuration) * 100}%` }}
                   className="h-full border-r border-background last:border-r-0"
                 >
-                  <Waveform buffer={audioBuffer} start={r.start} end={r.end} pxPerSecond={pxPerSecond} />
+                  {item.kind === "source" && (
+                    <Waveform buffer={audioBuffer} start={item.start} end={item.end} pxPerSecond={pxPerSecond} />
+                  )}
                 </div>
               ))}
             </div>

From 4674424450253cd05e72435856936a9a3e03c142 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:25:07 +0530
Subject: [PATCH 14/36] feat(client): add and edit title cards from the Scenes
 panel

Each scene gets an intro/title card button, and there's an Outro
section. The editor offers the four templates, title and subtitle, a 1-
10s duration and preset or custom colors; changes preview live over the
player and save as one undo step when you close it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/components/editor/CardEditor.tsx  | 160 +++++++++++++++++++
 client/src/components/editor/ScenesPanel.tsx | 107 +++++++++++--
 2 files changed, 258 insertions(+), 9 deletions(-)
 create mode 100644 client/src/components/editor/CardEditor.tsx

diff --git a/client/src/components/editor/CardEditor.tsx b/client/src/components/editor/CardEditor.tsx
new file mode 100644
index 0000000..abde709
--- /dev/null
+++ b/client/src/components/editor/CardEditor.tsx
@@ -0,0 +1,160 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { usePlayerStore } from "@/stores/player-store";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { CARD_BACKGROUNDS } from "@/lib/cards/layout";
+import {
+  CARD_MAX_SECONDS,
+  CARD_MIN_SECONDS,
+  CARD_SUBTITLE_MAX,
+  CARD_TEMPLATES,
+  CARD_TITLE_MAX,
+  type CardOperation,
+  type CardTemplate,
+} from "@/types/edit-operation";
+
+const TEMPLATE_LABELS: Record<CardTemplate, string> = {
+  title: "Title",
+  chapter: "Chapter",
+  quote: "Quote",
+  outro: "Outro",
+};
+
+const SUBTITLE_PLACEHOLDER: Record<CardTemplate, string> = {
+  title: "Subtitle (optional)",
+  chapter: "Label above, e.g. Part 2",
+  quote: "Who said it (optional)",
+  outro: "e.g. Subscribe for more",
+};
+
+/** Card text goes into an ASS file at export: no override-tag characters or line breaks (the API refuses them too). */
+function cleanCardText(text: string): string {
+  return Array.from(text)
+    .filter((ch) => {
+      const code = ch.charCodeAt(0);
+      return code >= 0x20 && code !== 0x7f && !"{}\\".includes(ch);
+    })
+    .join("");
+}
+
+/**
+ * Edits one title card. Changes stay in a local draft, previewed live over
+ * the player (player store's cardDraft), and are saved as a single
+ * operation replacement -- one undo step -- when the editor is closed.
+ */
+export function CardEditor({
+  card,
+  onSave,
+  onDelete,
+  onClose,
+}: {
+  card: CardOperation;
+  onSave: (next: CardOperation) => void;
+  onDelete: () => void;
+  onClose: () => void;
+}) {
+  const [draft, setDraft] = useState(card);
+  const setCardDraft = usePlayerStore((s) => s.setCardDraft);
+
+  useEffect(() => {
+    setCardDraft(draft);
+  }, [draft, setCardDraft]);
+  useEffect(() => () => setCardDraft(null), [setCardDraft]);
+
+  const update = (patch: Partial<CardOperation>) => setDraft((d) => ({ ...d, ...patch }));
+  const title = draft.title.trim();
+  const changed = JSON.stringify(draft) !== JSON.stringify(card);
+
+  const done = () => {
+    if (changed && title) {
+      const subtitle = draft.subtitle?.trim();
+      onSave({ ...draft, title, subtitle: subtitle || undefined });
+    }
+    onClose();
+  };
+
+  return (
+    <div className="flex flex-col gap-2.5 rounded-md border border-border bg-muted/40 p-2.5">
+      <div className="grid grid-cols-4 gap-1">
+        {CARD_TEMPLATES.map((template) => (
+          <button
+            key={template}
+            type="button"
+            onClick={() => update({ template })}
+            className={`rounded border px-1 py-1 text-[0.7rem] ${
+              draft.template === template
+                ? "border-primary bg-primary/15 text-primary"
+                : "border-border text-muted-foreground hover:text-foreground"
+            }`}
+          >
+            {TEMPLATE_LABELS[template]}
+          </button>
+        ))}
+      </div>
+      <Input
+        autoFocus
+        value={draft.title}
+        maxLength={CARD_TITLE_MAX}
+        placeholder="Title"
+        aria-label="Card title"
+        onChange={(e) => update({ title: cleanCardText(e.target.value) })}
+        onKeyDown={(e) => e.key === "Enter" && done()}
+        className="h-8 text-xs"
+      />
+      <Input
+        value={draft.subtitle ?? ""}
+        maxLength={CARD_SUBTITLE_MAX}
+        placeholder={SUBTITLE_PLACEHOLDER[draft.template]}
+        aria-label="Card subtitle"
+        onChange={(e) => update({ subtitle: cleanCardText(e.target.value) })}
+        onKeyDown={(e) => e.key === "Enter" && done()}
+        className="h-8 text-xs"
+      />
+      <label className="flex items-center gap-2 text-muted-foreground">
+        <span className="w-14 shrink-0">Duration</span>
+        <input
+          type="range"
+          min={CARD_MIN_SECONDS}
+          max={CARD_MAX_SECONDS}
+          step={0.5}
+          value={draft.duration}
+          onChange={(e) => update({ duration: Number(e.target.value) })}
+          className="min-w-0 flex-1 accent-primary"
+        />
+        <span className="w-8 text-right font-mono tabular-nums">{draft.duration}s</span>
+      </label>
+      <div className="flex items-center gap-1.5">
+        <span className="w-14 shrink-0 text-muted-foreground">Color</span>
+        {CARD_BACKGROUNDS.map((color) => (
+          <button
+            key={color}
+            type="button"
+            onClick={() => update({ background: color })}
+            title={color}
+            className={`size-5 rounded-full border ${
+              draft.background.toUpperCase() === color ? "ring-2 ring-primary ring-offset-1 ring-offset-card" : "border-border"
+            }`}
+            style={{ backgroundColor: color }}
+          />
+        ))}
+        <input
+          type="color"
+          value={draft.background}
+          onChange={(e) => update({ background: e.target.value.toUpperCase() })}
+          aria-label="Custom card color"
+          className="size-5 cursor-pointer rounded-full border border-border bg-transparent p-0"
+        />
+      </div>
+      <div className="flex justify-between">
+        <Button variant="ghost" size="xs" className="text-destructive hover:text-destructive" onClick={onDelete}>
+          Delete card
+        </Button>
+        <Button size="xs" onClick={done} disabled={!title}>
+          Done
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/client/src/components/editor/ScenesPanel.tsx b/client/src/components/editor/ScenesPanel.tsx
index dde71b7..659b9ef 100644
--- a/client/src/components/editor/ScenesPanel.tsx
+++ b/client/src/components/editor/ScenesPanel.tsx
@@ -1,7 +1,7 @@
 "use client";
 
-import { useMemo } from "react";
-import { Merge, Play, RotateCcw, Scissors, Trash2 } from "lucide-react";
+import { useMemo, useState } from "react";
+import { Merge, Play, RotateCcw, Scissors, Trash2, Type } from "lucide-react";
 import { usePlayerStore } from "@/stores/player-store";
 import { useTimelineStore } from "@/stores/timeline-store";
 import { useScenes } from "@/lib/timeline/useScenes";
@@ -9,13 +9,18 @@ import { sceneAt, sceneColor, type Scene } from "@/lib/timeline/scenes";
 import { cutsOverlapping } from "@/lib/timeline/cuts";
 import { formatTimecode } from "@/lib/timeline/format";
 import { Button } from "@/components/ui/button";
-import type { CutOperation } from "@/types/edit-operation";
+import { CardEditor } from "@/components/editor/CardEditor";
+import { CARD_BACKGROUNDS } from "@/lib/cards/layout";
+import type { CardOperation, CardTemplate, CutOperation } from "@/types/edit-operation";
+
+/** A card at a scene's start (within this) belongs to that scene. */
+const CARD_MATCH_SECONDS = 0.05;
 
 /**
  * Lists the episode's scenes -- stretches between split points -- so you
  * can name them, jump to them, drop a whole scene, or merge it back into
- * the one before. Everything here is ordinary edit operations (splits and
- * cuts), so it all goes through undo/redo.
+ * the one before, and give it a title card. Everything here is ordinary
+ * edit operations (splits, cuts, cards), so it all goes through undo/redo.
  */
 export function ScenesPanel() {
   const currentTime = usePlayerStore((s) => s.currentTime);
@@ -25,11 +30,68 @@ export function ScenesPanel() {
   const addCut = useTimelineStore((s) => s.addCut);
   const replaceOperation = useTimelineStore((s) => s.replaceOperation);
   const removeOperations = useTimelineStore((s) => s.removeOperations);
+  const addOperations = useTimelineStore((s) => s.addOperations);
+  const duration = usePlayerStore((s) => s.duration);
+  const setCard = usePlayerStore((s) => s.setCard);
   const { scenes, splitAt } = useScenes();
+  const [editingCardId, setEditingCardId] = useState<string | null>(null);
 
   const cuts = useMemo(() => operations.filter((op): op is CutOperation => op.type === "cut"), [operations]);
+  const cards = useMemo(
+    () =>
+      operations
+        .filter((op): op is CardOperation => op.type === "card")
+        .sort((a, b) => a.createdAt - b.createdAt),
+    [operations]
+  );
+  const cardsAt = (at: number) => cards.filter((c) => Math.abs(c.at - at) <= CARD_MATCH_SECONDS);
+  const outroCards = cards.filter((c) => c.at >= duration - CARD_MATCH_SECONDS);
   const activeScene = sceneAt(scenes, currentTime);
 
+  const addCard = (at: number, template: CardTemplate, title: string) => {
+    const card: CardOperation = {
+      id: crypto.randomUUID(),
+      type: "card",
+      at,
+      duration: 3,
+      template,
+      title,
+      background: CARD_BACKGROUNDS[0],
+      createdAt: Date.now(),
+    };
+    addOperations([card]);
+    setCard(null);
+    setEditingCardId(card.id);
+  };
+
+  const cardList = (list: CardOperation[]) =>
+    list.map((card) =>
+      editingCardId === card.id ? (
+        <CardEditor
+          key={card.id}
+          card={card}
+          onSave={(next) => replaceOperation(card.id, { ...next, id: crypto.randomUUID() })}
+          onDelete={() => {
+            removeOperations([card.id]);
+            setEditingCardId(null);
+          }}
+          onClose={() => setEditingCardId(null)}
+        />
+      ) : (
+        <button
+          key={card.id}
+          type="button"
+          onClick={() => setEditingCardId(card.id)}
+          className="flex items-center gap-2 rounded-md border border-border px-2 py-1.5 text-left hover:bg-muted/60"
+          title="Edit title card"
+        >
+          <span className="size-3.5 shrink-0 rounded-sm border border-border" style={{ backgroundColor: card.background }} />
+          <span className="min-w-0 flex-1 truncate">{card.title}</span>
+          <span className="font-mono text-muted-foreground tabular-nums">{card.duration}s</span>
+        </button>
+      )
+    );
+
   const rename = (scene: Scene, title: string) => {
     const split = operations.find((op) => op.id === scene.splitId);
     if (split?.type === "split") {
@@ -54,12 +116,13 @@ export function ScenesPanel() {
         </p>
       </div>
 
-      {scenes.length <= 1 ? (
+      {scenes.length <= 1 && (
         <p className="rounded-lg border border-dashed border-border p-3 text-muted-foreground">
-          The whole episode is one scene. Split it at each topic change to name sections and drop whole segments at
-          once.
+          The whole episode is one scene. Split it at each topic change to name sections, drop whole segments at once,
+          and open each one with a title card.
         </p>
-      ) : (
+      )}
+      {scenes.length > 0 && (
         <ol className="flex flex-col gap-1.5">
           {scenes.map((scene) => {
             const kept = scene.editedEnd - scene.editedStart;
@@ -106,6 +169,16 @@ export function ScenesPanel() {
                     {partlyCut && <span className="text-destructive/80"> (trimmed)</span>}
                   </span>
                   <span className="flex gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 focus-within:opacity-100">
+                    <Button
+                      variant="ghost"
+                      size="icon-xs"
+                      onClick={() =>
+                        addCard(scene.index === 0 ? 0 : scene.start, scene.index === 0 ? "title" : "chapter", scene.title)
+                      }
+                      title={scene.index === 0 ? "Add an intro card" : "Add a title card before this scene"}
+                    >
+                      <Type className="size-3" />
+                    </Button>
                     {scene.index > 0 && scene.splitId && (
                       <Button
                         variant="ghost"
@@ -134,11 +207,27 @@ export function ScenesPanel() {
                     )}
                   </span>
                 </div>
+                {cardsAt(scene.index === 0 ? 0 : scene.start).length > 0 && (
+                  <div className="flex flex-col gap-1 pl-3.5">{cardList(cardsAt(scene.index === 0 ? 0 : scene.start))}</div>
+                )}
               </li>
             );
           })}
         </ol>
       )}
+
+      {duration > 0 && (
+        <div className="flex flex-col gap-1.5">
+          <div className="flex items-center justify-between">
+            <span className="text-muted-foreground">Outro</span>
+            <Button variant="ghost" size="xs" onClick={() => addCard(duration, "outro", "Thanks for listening")}>
+              <Type className="size-3" />
+              Add outro card
+            </Button>
+          </div>
+          {cardList(outroCards)}
+        </div>
+      )}
     </div>
   );
 }

From d7cac4215cbdd3c9b4de2ebb94fc95d018809ece Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:25:14 +0530
Subject: [PATCH 15/36] docs: document scenes, title cards and the ffmpeg 9
 xfade rules

Records the three clocks (source, edited, program), how cards render and
preview, and the frame-rate and padding rules the render graph needs on
ffmpeg 9, so nobody removes them as noise.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 claude.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/claude.md b/claude.md
index ad7e49d..7ea0f9e 100644
--- a/claude.md
+++ b/claude.md
@@ -634,6 +634,40 @@ it; `plan.ts` then crops/scales to the clip frame, and captions are
 re-cut into 3-4 word Shorts cues laid out for that frame (the ASS script
 resolution must match the output aspect, or libass stretches glyphs).
 
+## Scenes and title cards
+
+Scenes are derived, never stored: the ranges between `split` operations
+(`lib/timeline/scenes.ts`); a split at exactly 0 only names the first
+scene. New splits snap to the middle of a gap between words.
+
+A `card` operation inserts a full-screen title card (template, title,
+subtitle, 1-10s, solid color) before the content at its source time `at`
+-- a scene start, 0 for an intro, the duration for an outro. Cards add
+time that isn't in the source, so there are three clocks: source, edited
+(cuts removed, `cuts.ts`) and **program** (edited plus cards,
+`lib/timeline/program.ts`, duplicated client/server). Code that already
+works in edited time (captions, chapters, transcript export) shifts into
+program time through `editedToProgramTime`, so cuts and cards compose
+without knowing about each other. A card whose whole scene is cut is
+dropped with it. Clips skip cards.
+
+Rendering: each card is an ffmpeg `color` source at the source's size and
+frame rate, joined with the same xfade chain as cuts; all card text is
+one generated `.ass` file (`lib/cards/ass.ts`) burned in over the program
+before captions and the logo. User text only ever reaches ffmpeg inside
+that file, and the API refuses braces, backslashes and control
+characters. The preview can't insert frames into a `<video>`, so
+`useCardPlayback.ts` pauses the video where a card plays, shows
+`CardPreview` (same layout percentages, `lib/cards/layout.ts`) on its own
+clock, then resumes.
+
+**ffmpeg 9 xfade gotchas** (`plan.ts`, measured on 9.0.2): every segment
+must be pinned to the source's frame rate with `fps=` (without it xfade
+drops the start of each later segment), must not get a `settb` after
+that (brings the bug back), and every segment but the last is padded
+with `tpad` clone frames (a segment a frame short of its computed length
+otherwise ends the whole chain at that join).
+
 ---
 
 # 13. Architecture (local-first)

From 9cff45d9e1c0c54c228f0a9621af6720a22cefe5 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:43:16 +0530
Subject: [PATCH 16/36] feat: add a transition operation

A transition styles how the scene starting at its time joins what plays
before it: dip to black, dip to white, or crossfade with the scene's
title card. At 0 it fades the episode in; at the end, out. 0.2-2s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/types/edit-operation.ts            | 24 +++++++++++++++++++
 .../src/lib/validation/edit-operation.test.ts | 16 +++++++++++++
 server/src/lib/validation/edit-operation.ts   | 12 ++++++++++
 server/src/routes/operations.ts               |  3 +++
 server/src/types/edit-operation.ts            | 24 +++++++++++++++++++
 5 files changed, 79 insertions(+)

diff --git a/client/src/types/edit-operation.ts b/client/src/types/edit-operation.ts
index 62dd558..4856e39 100644
--- a/client/src/types/edit-operation.ts
+++ b/client/src/types/edit-operation.ts
@@ -52,6 +52,19 @@ export type EditOperation =
       /** '#RRGGBB' */
       background: string;
     })
+  | (OperationBase & {
+      /**
+       * How the scene starting at `at` is joined to what plays before it
+       * (its card, if it has one, included). At 0 it fades the episode in;
+       * at the source duration it fades the episode out. Transitions never
+       * change the program's length -- see lib/timeline/program.ts.
+       */
+      type: "transition";
+      at: number;
+      kind: TransitionKind;
+      /** Seconds for the whole transition (a dip spends half going out, half coming in). */
+      duration: number;
+    })
   | (OperationBase & {
       type: "caption";
       text: string;
@@ -66,6 +79,17 @@ export const CARD_MAX_SECONDS = 10;
 export const CARD_TITLE_MAX = 80;
 export const CARD_SUBTITLE_MAX = 120;
 
+/**
+ * dipBlack/dipWhite fade out to a color and back in; crossfade blends
+ * straight into or out of a title card (it needs a card: blending two
+ * stretches of footage that follow each other in the source shows nothing).
+ */
+export const TRANSITION_KINDS = ["dipBlack", "dipWhite", "crossfade"] as const;
+export type TransitionKind = (typeof TRANSITION_KINDS)[number];
+export const TRANSITION_MIN_SECONDS = 0.2;
+export const TRANSITION_MAX_SECONDS = 2;
+
 export type CutOperation = Extract<EditOperation, { type: "cut" }>;
 export type SplitOperation = Extract<EditOperation, { type: "split" }>;
 export type CardOperation = Extract<EditOperation, { type: "card" }>;
+export type TransitionOperation = Extract<EditOperation, { type: "transition" }>;
diff --git a/server/src/lib/validation/edit-operation.test.ts b/server/src/lib/validation/edit-operation.test.ts
index 5de8ceb..6acd5b6 100644
--- a/server/src/lib/validation/edit-operation.test.ts
+++ b/server/src/lib/validation/edit-operation.test.ts
@@ -128,4 +128,20 @@ describe("editOperationSchema", () => {
       expect(editOperationSchema.safeParse({ ...card, subtitle: "two\nlines" }).success).toBe(false);
     });
   });
+
+  describe("transition", () => {
+    const transition = { id: "t1", type: "transition", at: 30, kind: "dipBlack", duration: 1, createdAt: 0 };
+
+    it("accepts each kind", () => {
+      for (const kind of ["dipBlack", "dipWhite", "crossfade"]) {
+        expect(editOperationSchema.safeParse({ ...transition, kind }).success).toBe(true);
+      }
+    });
+
+    it("rejects unknown kinds and out-of-range durations", () => {
+      expect(editOperationSchema.safeParse({ ...transition, kind: "wipe" }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...transition, duration: 0.1 }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...transition, duration: 5 }).success).toBe(false);
+    });
+  });
 });
diff --git a/server/src/lib/validation/edit-operation.ts b/server/src/lib/validation/edit-operation.ts
index df1db89..1cd6655 100644
--- a/server/src/lib/validation/edit-operation.ts
+++ b/server/src/lib/validation/edit-operation.ts
@@ -5,6 +5,9 @@ import {
   CARD_SUBTITLE_MAX,
   CARD_TEMPLATES,
   CARD_TITLE_MAX,
+  TRANSITION_KINDS,
+  TRANSITION_MAX_SECONDS,
+  TRANSITION_MIN_SECONDS,
 } from "@/types/edit-operation";
 
 /**
@@ -66,6 +69,15 @@ export const editOperationSchema = z.discriminatedUnion("type", [
     createdAt: z.number(),
     groupId: z.string().min(1).max(100).optional(),
   }),
+  z.object({
+    id: z.string().min(1),
+    type: z.literal("transition"),
+    at: z.number().nonnegative(),
+    kind: z.enum(TRANSITION_KINDS),
+    duration: z.number().min(TRANSITION_MIN_SECONDS).max(TRANSITION_MAX_SECONDS),
+    createdAt: z.number(),
+    groupId: z.string().min(1).max(100).optional(),
+  }),
   z.object({
     id: z.string().min(1),
     type: z.literal("caption"),
diff --git a/server/src/routes/operations.ts b/server/src/routes/operations.ts
index b42e8f8..a433f7c 100644
--- a/server/src/routes/operations.ts
+++ b/server/src/routes/operations.ts
@@ -37,6 +37,9 @@ operationsRoute.post("/:id/operations", async (c) => {
   if (op.type === "card" && project.duration && op.at > project.duration) {
     return errorResponse(c, "INVALID_OPERATION", "Card must be placed inside the video.", 400);
   }
+  if (op.type === "transition" && project.duration && op.at > project.duration) {
+    return errorResponse(c, "INVALID_OPERATION", "Transition must be placed inside the video.", 400);
+  }
 
   // Client generates the id (needed so undo/redo can address the exact row);
   // upsert so a redo that restores a previously-undone op is idempotent.
diff --git a/server/src/types/edit-operation.ts b/server/src/types/edit-operation.ts
index 62dd558..4856e39 100644
--- a/server/src/types/edit-operation.ts
+++ b/server/src/types/edit-operation.ts
@@ -52,6 +52,19 @@ export type EditOperation =
       /** '#RRGGBB' */
       background: string;
     })
+  | (OperationBase & {
+      /**
+       * How the scene starting at `at` is joined to what plays before it
+       * (its card, if it has one, included). At 0 it fades the episode in;
+       * at the source duration it fades the episode out. Transitions never
+       * change the program's length -- see lib/timeline/program.ts.
+       */
+      type: "transition";
+      at: number;
+      kind: TransitionKind;
+      /** Seconds for the whole transition (a dip spends half going out, half coming in). */
+      duration: number;
+    })
   | (OperationBase & {
       type: "caption";
       text: string;
@@ -66,6 +79,17 @@ export const CARD_MAX_SECONDS = 10;
 export const CARD_TITLE_MAX = 80;
 export const CARD_SUBTITLE_MAX = 120;
 
+/**
+ * dipBlack/dipWhite fade out to a color and back in; crossfade blends
+ * straight into or out of a title card (it needs a card: blending two
+ * stretches of footage that follow each other in the source shows nothing).
+ */
+export const TRANSITION_KINDS = ["dipBlack", "dipWhite", "crossfade"] as const;
+export type TransitionKind = (typeof TRANSITION_KINDS)[number];
+export const TRANSITION_MIN_SECONDS = 0.2;
+export const TRANSITION_MAX_SECONDS = 2;
+
 export type CutOperation = Extract<EditOperation, { type: "cut" }>;
 export type SplitOperation = Extract<EditOperation, { type: "split" }>;
 export type CardOperation = Extract<EditOperation, { type: "card" }>;
+export type TransitionOperation = Extract<EditOperation, { type: "transition" }>;

From 357a3415c71bd4060f0fea610ef385da809dbcdb Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:43:16 +0530
Subject: [PATCH 17/36] feat: place transitions in the program model

Transitions are placed like cards: one per moment (the latest wins),
following the scene's content if its start was cut, and dropped with the
scene if it's cut entirely. Footage is split at a transition inside a
kept range so it has a join to live on, and every join at the moment --
into a card and out of it -- gets the style. A crossfade needs a card on
one side; between two stretches of footage that follow each other in the
source it would show nothing, so it falls back to a cut.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/lib/timeline/program.test.ts |  67 ++++++++++
 client/src/lib/timeline/program.ts      | 157 ++++++++++++++++++++++--
 server/src/lib/timeline/program.test.ts |  67 ++++++++++
 server/src/lib/timeline/program.ts      | 157 ++++++++++++++++++++++--
 4 files changed, 432 insertions(+), 16 deletions(-)

diff --git a/client/src/lib/timeline/program.test.ts b/client/src/lib/timeline/program.test.ts
index 5f0b449..c761430 100644
--- a/client/src/lib/timeline/program.test.ts
+++ b/client/src/lib/timeline/program.test.ts
@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest";
 import {
+  buildProgram,
   buildProgramItems,
+  isPlainProgram,
   cardStartTimes,
   cardsDuration,
   editedRangeToProgram,
@@ -22,6 +24,12 @@ const card = (id: string, at: number, duration = 3, createdAt = 0): CardOperatio
   createdAt,
 });
 const cut = (start: number, end: number): CutOperation => ({ id: `cut-${start}`, type: "cut", start, end, createdAt: 0 });
+const transition = (
+  at: number,
+  kind: "dipBlack" | "dipWhite" | "crossfade",
+  duration = 1,
+  createdAt = 0
+): EditOperation => ({ id: `t-${at}-${createdAt}`, type: "transition", at, kind, duration, createdAt });
 const split = (timestamp: number): EditOperation => ({ id: `split-${timestamp}`, type: "split", timestamp, createdAt: 0 });
 
 function program(ops: EditOperation[], duration = 100) {
@@ -125,3 +133,62 @@ describe("editedRangeToProgram and cardStartTimes", () => {
     ]);
   });
 });
+
+describe("transitions", () => {
+  const build = (ops: EditOperation[], duration = 100) => {
+    const ranges = computePlayableRanges(
+      duration,
+      ops.filter((op): op is CutOperation => op.type === "cut")
+    );
+    return buildProgram(ops, ranges, duration);
+  };
+
+  it("leaves a project without cards or transitions plain", () => {
+    expect(isPlainProgram(build([cut(10, 20), split(50)]))).toBe(true);
+  });
+
+  it("splits footage at a mid-range transition so it has a join to live on", () => {
+    const p = build([split(40), transition(40, "dipBlack")]);
+    expect(p.items).toEqual([
+      { kind: "source", start: 0, end: 40 },
+      { kind: "source", start: 40, end: 100 },
+    ]);
+    expect(p.joins).toEqual([{ kind: "dip", color: "black", seconds: 1 }]);
+  });
+
+  it("styles both joins around a card at the transition's moment", () => {
+    const p = build([split(40), card("mid", 40), transition(40, "crossfade", 0.8)]);
+    expect(p.items.map((i) => i.kind)).toEqual(["source", "card", "source"]);
+    expect(p.joins).toEqual([
+      { kind: "crossfade", seconds: 0.8 },
+      { kind: "crossfade", seconds: 0.8 },
+    ]);
+  });
+
+  it("falls back to a cut for a crossfade between two stretches of footage", () => {
+    expect(build([split(40), transition(40, "crossfade")]).joins).toEqual([{ kind: "cut" }]);
+  });
+
+  it("turns transitions at the ends into fades in and out", () => {
+    const p = build([transition(0, "dipBlack", 1.5), transition(100, "dipWhite", 2)]);
+    expect(p.fadeIn).toEqual({ color: "black", seconds: 1.5 });
+    expect(p.fadeOut).toEqual({ color: "white", seconds: 2 });
+    expect(isPlainProgram(p)).toBe(false);
+  });
+
+  it("keeps only the latest transition at a moment, and drops one whose scene is cut", () => {
+    const latest = build([split(40), transition(40, "dipBlack", 1, 1), transition(40, "dipWhite", 1, 2)]);
+    expect(latest.joins).toEqual([{ kind: "dip", color: "white", seconds: 1 }]);
+    const gone = build([split(40), split(60), cut(40, 60), transition(40, "dipBlack")]);
+    expect(gone.joins.every((j) => j.kind === "cut")).toBe(true);
+  });
+
+  it("applies at the next kept content when the transition's moment was cut", () => {
+    const p = build([split(40), cut(35, 45), transition(40, "dipBlack")]);
+    expect(p.items).toEqual([
+      { kind: "source", start: 0, end: 35 },
+      { kind: "source", start: 45, end: 100 },
+    ]);
+    expect(p.joins[0]).toMatchObject({ kind: "dip" });
+  });
+});
diff --git a/client/src/lib/timeline/program.ts b/client/src/lib/timeline/program.ts
index 2219864..fb82434 100644
--- a/client/src/lib/timeline/program.ts
+++ b/client/src/lib/timeline/program.ts
@@ -1,4 +1,4 @@
-import type { CardOperation, EditOperation, SplitOperation } from "@/types/edit-operation";
+import type { CardOperation, EditOperation, SplitOperation, TransitionOperation } from "@/types/edit-operation";
 import type { PlayableRange } from "@/types/timeline";
 import { nextPlayableTime, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
 
@@ -126,27 +126,38 @@ export function locateProgramTime(
 
 /**
  * The render's play order: source ranges, split wherever a card is
- * inserted, with the cards in between. With no cards this is exactly the
- * playable ranges.
+ * inserted (and at any extra edited times in `splitAt`, so a transition in
+ * the middle of a kept range gets a join to live on), with the cards in
+ * between. With no cards or splits this is exactly the playable ranges.
  */
-export function buildProgramItems(ranges: PlayableRange[], slots: CardSlot[]): ProgramItem[] {
+export function buildProgramItems(ranges: PlayableRange[], slots: CardSlot[], splitAt: number[] = []): ProgramItem[] {
+  // Stable sort keeps cards in slot order; a split at a card's moment adds nothing.
+  const events: { editedAt: number; card?: CardOperation }[] = [
+    ...slots.map((s) => ({ editedAt: s.editedAt, card: s.card })),
+    ...splitAt.map((editedAt) => ({ editedAt })),
+  ].sort((a, b) => a.editedAt - b.editedAt);
+
   const items: ProgramItem[] = [];
   let next = 0;
   let edited = 0;
   for (const r of ranges) {
     let start = r.start;
     const rangeEditedEnd = edited + (r.end - r.start);
-    while (next < slots.length && slots[next].editedAt < rangeEditedEnd - EPSILON) {
-      const at = r.start + (slots[next].editedAt - edited);
+    while (next < events.length && events[next].editedAt < rangeEditedEnd - EPSILON) {
+      const at = r.start + (events[next].editedAt - edited);
       if (at > start + EPSILON) items.push({ kind: "source", start, end: at });
       start = Math.max(start, at);
-      items.push({ kind: "card", card: slots[next].card });
+      const card = events[next].card;
+      if (card) items.push({ kind: "card", card });
       next++;
     }
     if (r.end > start + EPSILON) items.push({ kind: "source", start, end: r.end });
     edited = rangeEditedEnd;
   }
-  for (; next < slots.length; next++) items.push({ kind: "card", card: slots[next].card });
+  for (; next < events.length; next++) {
+    const card = events[next].card;
+    if (card) items.push({ kind: "card", card });
+  }
   return items;
 }
 
@@ -176,3 +187,133 @@ export function cardStartTimes(items: ProgramItem[]): { start: number; card: Car
   }
   return starts;
 }
+
+/** A fade from/to a solid color, `seconds` long. */
+export type Fade = { color: "black" | "white"; seconds: number };
+
+/**
+ * How two consecutive program items are joined. "cut" is the usual 30ms
+ * declick crossfade; a dip fades the first item out to a color and the
+ * next in from it (half the seconds each); a crossfade blends into or out
+ * of a title card. None of them change the program's length.
+ */
+export type Join =
+  | { kind: "cut" }
+  | { kind: "dip"; color: "black" | "white"; seconds: number }
+  | { kind: "crossfade"; seconds: number };
+
+/** A transition placed on the edited timeline, at the start of its scene's content. */
+export type TransitionMarker = { transition: TransitionOperation; editedAt: number };
+
+const fadeColor = (t: TransitionOperation): "black" | "white" => (t.kind === "dipWhite" ? "white" : "black");
+
+/**
+ * Places transitions like cards (placeCards): one per moment (the latest
+ * wins), dropped with their scene if it's cut entirely. A transition at 0
+ * fades the episode in and one at the end fades it out.
+ */
+export function placeTransitions(
+  operations: EditOperation[],
+  ranges: PlayableRange[],
+  sourceDuration: number
+): { markers: TransitionMarker[]; fadeIn: Fade | null; fadeOut: Fade | null } {
+  const latest = new Map<number, TransitionOperation>();
+  for (const op of operations) {
+    if (op.type !== "transition") continue;
+    const key = Math.round(op.at * 1000);
+    const current = latest.get(key);
+    if (!current || op.createdAt >= current.createdAt) latest.set(key, op);
+  }
+
+  const splits = splitTimes(operations);
+  const markers: TransitionMarker[] = [];
+  let fadeIn: Fade | null = null;
+  let fadeOut: Fade | null = null;
+  for (const transition of latest.values()) {
+    const fade = { color: fadeColor(transition), seconds: transition.duration };
+    if (transition.at <= EPSILON) {
+      fadeIn = fade;
+      continue;
+    }
+    if (transition.at >= sourceDuration - EPSILON) {
+      fadeOut = fade;
+      continue;
+    }
+    const sceneEnd = splits.find((t) => t > transition.at + EPSILON) ?? sourceDuration;
+    if (!ranges.some((r) => r.start < sceneEnd && r.end > transition.at)) continue;
+    const resumeAt = nextPlayableTime(transition.at, ranges);
+    if (resumeAt === null) continue;
+    markers.push({ transition, editedAt: sourceTimeToEditedTime(resumeAt, ranges) });
+  }
+  return { markers: markers.sort((a, b) => a.editedAt - b.editedAt), fadeIn, fadeOut };
+}
+
+/**
+ * The join style between each pair of consecutive items (entry i joins
+ * items[i] and items[i+1]). Every join at a transition's moment gets it --
+ * with a card there, that's both the join into the card and out of it. A
+ * crossfade needs a card on one side; between two stretches of footage it
+ * falls back to a plain cut.
+ */
+export function resolveJoins(items: ProgramItem[], markers: TransitionMarker[]): Join[] {
+  const joins: Join[] = [];
+  let edited = 0;
+  for (let i = 0; i < items.length - 1; i++) {
+    const item = items[i];
+    if (item.kind === "source") edited += item.end - item.start;
+    const marker = markers.find((m) => Math.abs(m.editedAt - edited) <= EPSILON);
+    if (!marker) {
+      joins.push({ kind: "cut" });
+      continue;
+    }
+    const { kind, duration } = marker.transition;
+    if (kind === "crossfade") {
+      const touchesCard = item.kind === "card" || items[i + 1].kind === "card";
+      joins.push(touchesCard ? { kind: "crossfade", seconds: duration } : { kind: "cut" });
+    } else {
+      joins.push({ kind: "dip", color: fadeColor(marker.transition), seconds: duration });
+    }
+  }
+  return joins;
+}
+
+/** Everything that plays, and how it's stitched together. */
+export type Program = {
+  slots: CardSlot[];
+  items: ProgramItem[];
+  joins: Join[];
+  fadeIn: Fade | null;
+  fadeOut: Fade | null;
+};
+
+export function buildProgram(operations: EditOperation[], ranges: PlayableRange[], sourceDuration: number): Program {
+  const slots = placeCards(operations, ranges, sourceDuration);
+  const { markers, fadeIn, fadeOut } = placeTransitions(operations, ranges, sourceDuration);
+  const items = buildProgramItems(
+    ranges,
+    slots,
+    markers.map((m) => m.editedAt)
+  );
+  return { slots, items, joins: resolveJoins(items, markers), fadeIn, fadeOut };
+}
+
+/** True when the program is just the playable ranges, cut together as always. */
+export function isPlainProgram(program: Program): boolean {
+  return (
+    program.slots.length === 0 &&
+    !program.fadeIn &&
+    !program.fadeOut &&
+    program.joins.every((j) => j.kind === "cut")
+  );
+}
+
+/** Program time at which each item starts (entry i+1 is also where join i happens). */
+export function itemStartTimes(items: ProgramItem[]): number[] {
+  const starts: number[] = [];
+  let t = 0;
+  for (const item of items) {
+    starts.push(t);
+    t += programItemDuration(item);
+  }
+  return starts;
+}
diff --git a/server/src/lib/timeline/program.test.ts b/server/src/lib/timeline/program.test.ts
index 5f0b449..c761430 100644
--- a/server/src/lib/timeline/program.test.ts
+++ b/server/src/lib/timeline/program.test.ts
@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest";
 import {
+  buildProgram,
   buildProgramItems,
+  isPlainProgram,
   cardStartTimes,
   cardsDuration,
   editedRangeToProgram,
@@ -22,6 +24,12 @@ const card = (id: string, at: number, duration = 3, createdAt = 0): CardOperatio
   createdAt,
 });
 const cut = (start: number, end: number): CutOperation => ({ id: `cut-${start}`, type: "cut", start, end, createdAt: 0 });
+const transition = (
+  at: number,
+  kind: "dipBlack" | "dipWhite" | "crossfade",
+  duration = 1,
+  createdAt = 0
+): EditOperation => ({ id: `t-${at}-${createdAt}`, type: "transition", at, kind, duration, createdAt });
 const split = (timestamp: number): EditOperation => ({ id: `split-${timestamp}`, type: "split", timestamp, createdAt: 0 });
 
 function program(ops: EditOperation[], duration = 100) {
@@ -125,3 +133,62 @@ describe("editedRangeToProgram and cardStartTimes", () => {
     ]);
   });
 });
+
+describe("transitions", () => {
+  const build = (ops: EditOperation[], duration = 100) => {
+    const ranges = computePlayableRanges(
+      duration,
+      ops.filter((op): op is CutOperation => op.type === "cut")
+    );
+    return buildProgram(ops, ranges, duration);
+  };
+
+  it("leaves a project without cards or transitions plain", () => {
+    expect(isPlainProgram(build([cut(10, 20), split(50)]))).toBe(true);
+  });
+
+  it("splits footage at a mid-range transition so it has a join to live on", () => {
+    const p = build([split(40), transition(40, "dipBlack")]);
+    expect(p.items).toEqual([
+      { kind: "source", start: 0, end: 40 },
+      { kind: "source", start: 40, end: 100 },
+    ]);
+    expect(p.joins).toEqual([{ kind: "dip", color: "black", seconds: 1 }]);
+  });
+
+  it("styles both joins around a card at the transition's moment", () => {
+    const p = build([split(40), card("mid", 40), transition(40, "crossfade", 0.8)]);
+    expect(p.items.map((i) => i.kind)).toEqual(["source", "card", "source"]);
+    expect(p.joins).toEqual([
+      { kind: "crossfade", seconds: 0.8 },
+      { kind: "crossfade", seconds: 0.8 },
+    ]);
+  });
+
+  it("falls back to a cut for a crossfade between two stretches of footage", () => {
+    expect(build([split(40), transition(40, "crossfade")]).joins).toEqual([{ kind: "cut" }]);
+  });
+
+  it("turns transitions at the ends into fades in and out", () => {
+    const p = build([transition(0, "dipBlack", 1.5), transition(100, "dipWhite", 2)]);
+    expect(p.fadeIn).toEqual({ color: "black", seconds: 1.5 });
+    expect(p.fadeOut).toEqual({ color: "white", seconds: 2 });
+    expect(isPlainProgram(p)).toBe(false);
+  });
+
+  it("keeps only the latest transition at a moment, and drops one whose scene is cut", () => {
+    const latest = build([split(40), transition(40, "dipBlack", 1, 1), transition(40, "dipWhite", 1, 2)]);
+    expect(latest.joins).toEqual([{ kind: "dip", color: "white", seconds: 1 }]);
+    const gone = build([split(40), split(60), cut(40, 60), transition(40, "dipBlack")]);
+    expect(gone.joins.every((j) => j.kind === "cut")).toBe(true);
+  });
+
+  it("applies at the next kept content when the transition's moment was cut", () => {
+    const p = build([split(40), cut(35, 45), transition(40, "dipBlack")]);
+    expect(p.items).toEqual([
+      { kind: "source", start: 0, end: 35 },
+      { kind: "source", start: 45, end: 100 },
+    ]);
+    expect(p.joins[0]).toMatchObject({ kind: "dip" });
+  });
+});
diff --git a/server/src/lib/timeline/program.ts b/server/src/lib/timeline/program.ts
index 2219864..fb82434 100644
--- a/server/src/lib/timeline/program.ts
+++ b/server/src/lib/timeline/program.ts
@@ -1,4 +1,4 @@
-import type { CardOperation, EditOperation, SplitOperation } from "@/types/edit-operation";
+import type { CardOperation, EditOperation, SplitOperation, TransitionOperation } from "@/types/edit-operation";
 import type { PlayableRange } from "@/types/timeline";
 import { nextPlayableTime, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
 
@@ -126,27 +126,38 @@ export function locateProgramTime(
 
 /**
  * The render's play order: source ranges, split wherever a card is
- * inserted, with the cards in between. With no cards this is exactly the
- * playable ranges.
+ * inserted (and at any extra edited times in `splitAt`, so a transition in
+ * the middle of a kept range gets a join to live on), with the cards in
+ * between. With no cards or splits this is exactly the playable ranges.
  */
-export function buildProgramItems(ranges: PlayableRange[], slots: CardSlot[]): ProgramItem[] {
+export function buildProgramItems(ranges: PlayableRange[], slots: CardSlot[], splitAt: number[] = []): ProgramItem[] {
+  // Stable sort keeps cards in slot order; a split at a card's moment adds nothing.
+  const events: { editedAt: number; card?: CardOperation }[] = [
+    ...slots.map((s) => ({ editedAt: s.editedAt, card: s.card })),
+    ...splitAt.map((editedAt) => ({ editedAt })),
+  ].sort((a, b) => a.editedAt - b.editedAt);
+
   const items: ProgramItem[] = [];
   let next = 0;
   let edited = 0;
   for (const r of ranges) {
     let start = r.start;
     const rangeEditedEnd = edited + (r.end - r.start);
-    while (next < slots.length && slots[next].editedAt < rangeEditedEnd - EPSILON) {
-      const at = r.start + (slots[next].editedAt - edited);
+    while (next < events.length && events[next].editedAt < rangeEditedEnd - EPSILON) {
+      const at = r.start + (events[next].editedAt - edited);
       if (at > start + EPSILON) items.push({ kind: "source", start, end: at });
       start = Math.max(start, at);
-      items.push({ kind: "card", card: slots[next].card });
+      const card = events[next].card;
+      if (card) items.push({ kind: "card", card });
       next++;
     }
     if (r.end > start + EPSILON) items.push({ kind: "source", start, end: r.end });
     edited = rangeEditedEnd;
   }
-  for (; next < slots.length; next++) items.push({ kind: "card", card: slots[next].card });
+  for (; next < events.length; next++) {
+    const card = events[next].card;
+    if (card) items.push({ kind: "card", card });
+  }
   return items;
 }
 
@@ -176,3 +187,133 @@ export function cardStartTimes(items: ProgramItem[]): { start: number; card: Car
   }
   return starts;
 }
+
+/** A fade from/to a solid color, `seconds` long. */
+export type Fade = { color: "black" | "white"; seconds: number };
+
+/**
+ * How two consecutive program items are joined. "cut" is the usual 30ms
+ * declick crossfade; a dip fades the first item out to a color and the
+ * next in from it (half the seconds each); a crossfade blends into or out
+ * of a title card. None of them change the program's length.
+ */
+export type Join =
+  | { kind: "cut" }
+  | { kind: "dip"; color: "black" | "white"; seconds: number }
+  | { kind: "crossfade"; seconds: number };
+
+/** A transition placed on the edited timeline, at the start of its scene's content. */
+export type TransitionMarker = { transition: TransitionOperation; editedAt: number };
+
+const fadeColor = (t: TransitionOperation): "black" | "white" => (t.kind === "dipWhite" ? "white" : "black");
+
+/**
+ * Places transitions like cards (placeCards): one per moment (the latest
+ * wins), dropped with their scene if it's cut entirely. A transition at 0
+ * fades the episode in and one at the end fades it out.
+ */
+export function placeTransitions(
+  operations: EditOperation[],
+  ranges: PlayableRange[],
+  sourceDuration: number
+): { markers: TransitionMarker[]; fadeIn: Fade | null; fadeOut: Fade | null } {
+  const latest = new Map<number, TransitionOperation>();
+  for (const op of operations) {
+    if (op.type !== "transition") continue;
+    const key = Math.round(op.at * 1000);
+    const current = latest.get(key);
+    if (!current || op.createdAt >= current.createdAt) latest.set(key, op);
+  }
+
+  const splits = splitTimes(operations);
+  const markers: TransitionMarker[] = [];
+  let fadeIn: Fade | null = null;
+  let fadeOut: Fade | null = null;
+  for (const transition of latest.values()) {
+    const fade = { color: fadeColor(transition), seconds: transition.duration };
+    if (transition.at <= EPSILON) {
+      fadeIn = fade;
+      continue;
+    }
+    if (transition.at >= sourceDuration - EPSILON) {
+      fadeOut = fade;
+      continue;
+    }
+    const sceneEnd = splits.find((t) => t > transition.at + EPSILON) ?? sourceDuration;
+    if (!ranges.some((r) => r.start < sceneEnd && r.end > transition.at)) continue;
+    const resumeAt = nextPlayableTime(transition.at, ranges);
+    if (resumeAt === null) continue;
+    markers.push({ transition, editedAt: sourceTimeToEditedTime(resumeAt, ranges) });
+  }
+  return { markers: markers.sort((a, b) => a.editedAt - b.editedAt), fadeIn, fadeOut };
+}
+
+/**
+ * The join style between each pair of consecutive items (entry i joins
+ * items[i] and items[i+1]). Every join at a transition's moment gets it --
+ * with a card there, that's both the join into the card and out of it. A
+ * crossfade needs a card on one side; between two stretches of footage it
+ * falls back to a plain cut.
+ */
+export function resolveJoins(items: ProgramItem[], markers: TransitionMarker[]): Join[] {
+  const joins: Join[] = [];
+  let edited = 0;
+  for (let i = 0; i < items.length - 1; i++) {
+    const item = items[i];
+    if (item.kind === "source") edited += item.end - item.start;
+    const marker = markers.find((m) => Math.abs(m.editedAt - edited) <= EPSILON);
+    if (!marker) {
+      joins.push({ kind: "cut" });
+      continue;
+    }
+    const { kind, duration } = marker.transition;
+    if (kind === "crossfade") {
+      const touchesCard = item.kind === "card" || items[i + 1].kind === "card";
+      joins.push(touchesCard ? { kind: "crossfade", seconds: duration } : { kind: "cut" });
+    } else {
+      joins.push({ kind: "dip", color: fadeColor(marker.transition), seconds: duration });
+    }
+  }
+  return joins;
+}
+
+/** Everything that plays, and how it's stitched together. */
+export type Program = {
+  slots: CardSlot[];
+  items: ProgramItem[];
+  joins: Join[];
+  fadeIn: Fade | null;
+  fadeOut: Fade | null;
+};
+
+export function buildProgram(operations: EditOperation[], ranges: PlayableRange[], sourceDuration: number): Program {
+  const slots = placeCards(operations, ranges, sourceDuration);
+  const { markers, fadeIn, fadeOut } = placeTransitions(operations, ranges, sourceDuration);
+  const items = buildProgramItems(
+    ranges,
+    slots,
+    markers.map((m) => m.editedAt)
+  );
+  return { slots, items, joins: resolveJoins(items, markers), fadeIn, fadeOut };
+}
+
+/** True when the program is just the playable ranges, cut together as always. */
+export function isPlainProgram(program: Program): boolean {
+  return (
+    program.slots.length === 0 &&
+    !program.fadeIn &&
+    !program.fadeOut &&
+    program.joins.every((j) => j.kind === "cut")
+  );
+}
+
+/** Program time at which each item starts (entry i+1 is also where join i happens). */
+export function itemStartTimes(items: ProgramItem[]): number[] {
+  const starts: number[] = [];
+  let t = 0;
+  for (const item of items) {
+    starts.push(t);
+    t += programItemDuration(item);
+  }
+  return starts;
+}

From 2229e2dcfdfc3e871396d448070ef98408921771 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:43:16 +0530
Subject: [PATCH 18/36] feat(server): render transitions without changing the
 program's length

Captions and chapters are placed on program time, so a transition that
ate time would knock everything after it out of sync. A dip instead fades
each side's own edge to the color (audio fades too, capped at 0.3s since
speech sits right by scene boundaries) and keeps the usual 30ms join; a
crossfade's overlap is added to the card it blends with, so the footage
around it keeps its timing. The video and audio graphs now share one
per-item layout (render length, join overlap, edge fades) so they can't
drift apart. Projects with no cards or transitions render the same graph.

Verified with ffmpeg 9.0.2: a synthetic clip with a fade in, a white dip,
a crossfaded card and a fade out renders 22.99s (20s + 3s card, as
without transitions) and a beep every second lands at its predicted time
throughout, including right after the crossfaded card.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 server/src/lib/ffmpeg/plan.test.ts  | 102 ++++++++++++-
 server/src/lib/ffmpeg/plan.ts       | 229 ++++++++++++++++++++--------
 server/src/lib/ffmpeg/render-job.ts |  22 +--
 3 files changed, 281 insertions(+), 72 deletions(-)

diff --git a/server/src/lib/ffmpeg/plan.test.ts b/server/src/lib/ffmpeg/plan.test.ts
index 114744c..1dd1cae 100644
--- a/server/src/lib/ffmpeg/plan.test.ts
+++ b/server/src/lib/ffmpeg/plan.test.ts
@@ -354,11 +354,13 @@ describe("title cards", () => {
     background: "#1e3a5f",
     createdAt: 0,
   };
-  const program = [
+  const items = [
     { kind: "card" as const, card },
     { kind: "source" as const, start: 0, end: 10 },
     { kind: "source" as const, start: 20, end: 30 },
   ];
+  const cuts = [{ kind: "cut" as const }, { kind: "cut" as const }];
+  const program = { items, joins: cuts, fadeIn: null, fadeOut: null };
   const cardFrame = { width: 1920, height: 1080, textPath: "/data/cards.ass" };
   const graph = (extra: Partial<Parameters<typeof buildRenderArgs>[0]> = {}) => {
     const args = buildRenderArgs({ ...baseArgs, program, cardFrame, ...extra });
@@ -415,7 +417,7 @@ describe("title cards", () => {
     expect(() => buildRenderArgs({ ...baseArgs, program, cardFrame: { ...cardFrame, width: 0 } })).toThrow(
       /frame size/
     );
-    const badColor = [{ kind: "card" as const, card: { ...card, background: "red" } }, program[1]];
+    const badColor = { ...program, items: [{ kind: "card" as const, card: { ...card, background: "red" } }, items[1], items[2]] };
     expect(() => buildRenderArgs({ ...baseArgs, program: badColor, cardFrame })).toThrow(/background color/);
   });
 
@@ -424,3 +426,99 @@ describe("title cards", () => {
     expect(args[args.indexOf("-filter_complex") + 1]).toContain("anullsrc=r=48000:cl=stereo,atrim=duration=3.000");
   });
 });
+
+describe("transitions", () => {
+  const card = {
+    id: "c1",
+    type: "card" as const,
+    at: 10,
+    duration: 3,
+    template: "title" as const,
+    title: "Part 2",
+    background: "#111418",
+    createdAt: 0,
+  };
+  const footage = [
+    { kind: "source" as const, start: 0, end: 10 },
+    { kind: "source" as const, start: 10, end: 20 },
+  ];
+  const graphOf = (args: string[]) => args[args.indexOf("-filter_complex") + 1];
+
+  it("dips by fading each side's own edge, keeping the usual join and timing", () => {
+    const g = graphOf(
+      buildRenderArgs({
+        ...baseArgs,
+        program: { items: footage, joins: [{ kind: "dip", color: "white", seconds: 1 }], fadeIn: null, fadeOut: null },
+      })
+    );
+    expect(g).toContain("fps=30000/1001,fade=t=out:st=9.500:d=0.500:color=white,tpad=");
+    expect(g).toContain("fps=30000/1001,fade=t=in:st=0:d=0.500:color=white[v1]");
+    expect(g).toContain("[v0][v1]xfade=transition=fade:duration=0.030:offset=9.970[outv]");
+    expect(g).toContain("asetpts=PTS-STARTPTS,afade=t=out:st=9.700:d=0.300[a0]");
+    expect(g).toContain("asetpts=PTS-STARTPTS,afade=t=in:st=0:d=0.300[a1]");
+  });
+
+  it("crossfades into and out of a card by growing the card, so the footage keeps its timing", () => {
+    const g = graphOf(
+      buildRenderArgs({
+        ...baseArgs,
+        cardFrame: { width: 1920, height: 1080, textPath: "/data/cards.ass" },
+        program: {
+          items: [footage[0], { kind: "card" as const, card }, footage[1]],
+          joins: [
+            { kind: "crossfade", seconds: 0.8 },
+            { kind: "crossfade", seconds: 0.8 },
+          ],
+          fadeIn: null,
+          fadeOut: null,
+        },
+      })
+    );
+    // 3s card + 0.8s blended in on each side.
+    expect(g).toContain(":d=4.600,format=yuv420p,setsar=1,tpad=");
+    expect(g).toContain("[v0][v1]xfade=transition=fade:duration=0.800:offset=9.200[vx1]");
+    // The footage after the card starts 13s in, exactly as without the blend.
+    expect(g).toContain("[vx1][v2]xfade=transition=fade:duration=0.800:offset=13.000[outv]");
+    expect(g).toContain("anullsrc=r=48000:cl=stereo,atrim=duration=4.600");
+    expect(g).toContain("[a0][a1]acrossfade=d=0.800[ax1]");
+  });
+
+  it("fades the episode in from and out to a color", () => {
+    const g = graphOf(
+      buildRenderArgs({
+        ...baseArgs,
+        program: {
+          items: footage,
+          joins: [{ kind: "cut" }],
+          fadeIn: { color: "black", seconds: 1.5 },
+          fadeOut: { color: "black", seconds: 2 },
+        },
+      })
+    );
+    expect(g).toContain("fade=t=in:st=0:d=1.500:color=black");
+    expect(g).toContain("fade=t=out:st=8.000:d=2.000:color=black[v1]");
+    expect(g).toContain("afade=t=in:st=0:d=1.000");
+    expect(g).toContain("afade=t=out:st=9.000:d=1.000[a1]");
+  });
+
+  it("never lets a transition take more than half of a short segment", () => {
+    const g = graphOf(
+      buildRenderArgs({
+        ...baseArgs,
+        program: {
+          items: [{ kind: "source" as const, start: 0, end: 0.6 }, footage[1]],
+          joins: [{ kind: "dip", color: "black", seconds: 2 }],
+          fadeIn: null,
+          fadeOut: null,
+        },
+      })
+    );
+    expect(g).toContain("fade=t=out:st=0.300:d=0.300:color=black");
+  });
+
+  it("refuses a program whose joins don't match its items", () => {
+    expect(() =>
+      buildRenderArgs({ ...baseArgs, program: { items: footage, joins: [], fadeIn: null, fadeOut: null } })
+    ).toThrow(/joins/);
+  });
+});
diff --git a/server/src/lib/ffmpeg/plan.ts b/server/src/lib/ffmpeg/plan.ts
index 6ed928f..b620698 100644
--- a/server/src/lib/ffmpeg/plan.ts
+++ b/server/src/lib/ffmpeg/plan.ts
@@ -1,5 +1,5 @@
 import type { PlayableRange } from "@/types/timeline";
-import type { ProgramItem } from "@/lib/timeline/program";
+import type { Fade, Join, ProgramItem } from "@/lib/timeline/program";
 import { getFfmpegFilter } from "@/lib/ffmpeg/filters";
 import { buildPropertiesFilter } from "@/lib/ffmpeg/properties";
 import { buildForceStyle, type CaptionStyle } from "@/lib/captions/style";
@@ -80,24 +80,10 @@ function assertValidRanges(playableRanges: PlayableRange[]): void {
 }
 
 /**
- * What to render, in order: the program (lib/timeline/program.ts) when the
- * project has title cards, otherwise just the playable ranges. Validated
- * here since card durations and colors end up in the filtergraph.
+ * What to render when it's more than the playable ranges cut together: the
+ * program from lib/timeline/program.ts (cards, transitions, fades).
  */
-function resolveItems(playableRanges: PlayableRange[], program?: ProgramItem[]): ProgramItem[] {
-  if (!program) {
-    assertValidRanges(playableRanges);
-    return playableRanges.map((r) => ({ kind: "source", start: r.start, end: r.end }));
-  }
-  assertValidRanges(program.flatMap((item) => (item.kind === "source" ? [item] : [])));
-  for (const item of program) {
-    if (item.kind !== "card") continue;
-    const { duration, background } = item.card;
-    if (!Number.isFinite(duration) || duration <= 0 || duration > 60) throw new Error("Invalid card duration.");
-    if (!/^#[0-9a-fA-F]{6}$/.test(background)) throw new Error("Invalid card background color.");
-  }
-  return program;
-}
+export type RenderProgram = { items: ProgramItem[]; joins: Join[]; fadeIn: Fade | null; fadeOut: Fade | null };
 
 function assertValidCardFrame(frame: { width: number; height: number }): void {
   const { width, height } = frame;
@@ -106,11 +92,141 @@ function assertValidCardFrame(frame: { width: number; height: number }): void {
   }
 }
 
-function itemDuration(item: ProgramItem): number {
-  return item.kind === "card" ? item.card.duration : item.end - item.start;
+const assertSeconds = (seconds: number, what: string) => {
+  if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 60) throw new Error(`Invalid ${what} length.`);
+};
+const assertColor = (color: string) => {
+  if (color !== "black" && color !== "white") throw new Error("Invalid transition color.");
+};
+
+/** Longest audio fade at a dip between items: speech sits right next to scene boundaries. */
+const DIP_AUDIO_MAX_SECONDS = 0.3;
+/** Longest audio fade at the very start or end of the episode. */
+const EDGE_AUDIO_MAX_SECONDS = 1;
+
+type ItemFade = { color: "black" | "white"; seconds: number; audioSeconds: number };
+
+/**
+ * Everything the video and audio graphs need to agree on, per item: how
+ * long it renders, how much of it overlaps the item before, and any fade
+ * at its edges. Shared so the two graphs stay in sync.
+ */
+type Layout = {
+  items: ProgramItem[];
+  withCards: boolean;
+  /** Seconds each item renders for; a card grows by any crossfade into or out of it. */
+  lengths: number[];
+  /** Overlap of the join from item i-1 into item i (entry 0 unused). */
+  overlaps: number[];
+  fadeIns: (ItemFade | null)[];
+  fadeOuts: (ItemFade | null)[];
+};
+
+/**
+ * Lays out what to render. Without a program that's the playable ranges
+ * with the usual 30ms joins -- the graph every project without cards or
+ * transitions has always had.
+ *
+ * Transitions never change the program's length: a dip fades each side's
+ * own edge and keeps the usual join, and a crossfade's overlap is added to
+ * the card it blends with, so the footage around it keeps its timing.
+ */
+function layoutProgram(playableRanges: PlayableRange[], program?: RenderProgram): Layout {
+  if (!program) assertValidRanges(playableRanges);
+  const items: ProgramItem[] =
+    program?.items ?? playableRanges.map((r) => ({ kind: "source", start: r.start, end: r.end }));
+  const joins: Join[] = program?.joins ?? items.slice(1).map(() => ({ kind: "cut" }));
+  if (program) {
+    assertValidRanges(items.flatMap((item) => (item.kind === "source" ? [item] : [])));
+    if (joins.length !== items.length - 1) throw new Error("Program joins don't match its items.");
+    for (const item of items) {
+      if (item.kind !== "card") continue;
+      assertSeconds(item.card.duration, "card");
+      if (!/^#[0-9a-fA-F]{6}$/.test(item.card.background)) throw new Error("Invalid card background color.");
+    }
+    for (const join of joins) {
+      if (join.kind === "cut") continue;
+      assertSeconds(join.seconds, "transition");
+      if (join.kind === "dip") assertColor(join.color);
+    }
+    for (const fade of [program.fadeIn, program.fadeOut]) {
+      if (!fade) continue;
+      assertSeconds(fade.seconds, "fade");
+      assertColor(fade.color);
+    }
+  }
+
+  const logical = items.map((item) => (item.kind === "card" ? item.card.duration : item.end - item.start));
+  const lengths = [...logical];
+  const overlaps = logical.map(() => 0);
+  const fadeIns: (ItemFade | null)[] = logical.map(() => null);
+  const fadeOuts: (ItemFade | null)[] = logical.map(() => null);
+
+  joins.forEach((join, j) => {
+    const i = j + 1;
+    const room = Math.min(logical[i - 1], logical[i]) / 2;
+    if (join.kind === "crossfade") {
+      const overlap = Math.min(join.seconds, room);
+      overlaps[i] = overlap;
+      // Grow the card side so the footage keeps its timing (the next card, if both are).
+      if (items[i].kind === "card") lengths[i] += overlap;
+      else lengths[i - 1] += overlap;
+      return;
+    }
+    overlaps[i] = Math.min(CUT_CROSSFADE_SECONDS, room);
+    if (join.kind === "dip") {
+      const seconds = Math.min(join.seconds / 2, room);
+      const fade = { color: join.color, seconds, audioSeconds: Math.min(seconds, DIP_AUDIO_MAX_SECONDS) };
+      fadeOuts[i - 1] = fade;
+      fadeIns[i] = fade;
+    }
+  });
+  const edge = (fade: Fade | null, length: number): ItemFade | null => {
+    if (!fade) return null;
+    const seconds = Math.min(fade.seconds, length / 2);
+    return { color: fade.color, seconds, audioSeconds: Math.min(seconds, EDGE_AUDIO_MAX_SECONDS) };
+  };
+  if (items.length > 0) {
+    fadeIns[0] = edge(program?.fadeIn ?? null, logical[0]);
+    const last = items.length - 1;
+    fadeOuts[last] = edge(program?.fadeOut ?? null, logical[last]) ?? fadeOuts[last];
+  }
+
+  return {
+    items,
+    withCards: items.some((item) => item.kind === "card"),
+    lengths,
+    overlaps,
+    fadeIns,
+    fadeOuts,
+  };
+}
+
+/** fade= filters for item i's edges, appended to its video chain. */
+function videoFades(layout: Layout, i: number): string {
+  const parts: string[] = [];
+  const fadeIn = layout.fadeIns[i];
+  const fadeOut = layout.fadeOuts[i];
+  if (fadeIn) parts.push(`fade=t=in:st=0:d=${fadeIn.seconds.toFixed(3)}:color=${fadeIn.color}`);
+  if (fadeOut) {
+    const start = layout.lengths[i] - fadeOut.seconds;
+    parts.push(`fade=t=out:st=${start.toFixed(3)}:d=${fadeOut.seconds.toFixed(3)}:color=${fadeOut.color}`);
+  }
+  return parts.map((p) => `,${p}`).join("");
 }
 
-const hasCards = (items: ProgramItem[]) => items.some((item) => item.kind === "card");
+/** afade= filters for item i's edges, appended to its audio chain. */
+function audioFades(layout: Layout, i: number): string {
+  const parts: string[] = [];
+  const fadeIn = layout.fadeIns[i];
+  const fadeOut = layout.fadeOuts[i];
+  if (fadeIn) parts.push(`afade=t=in:st=0:d=${fadeIn.audioSeconds.toFixed(3)}`);
+  if (fadeOut) {
+    const start = layout.lengths[i] - fadeOut.audioSeconds;
+    parts.push(`afade=t=out:st=${start.toFixed(3)}:d=${fadeOut.audioSeconds.toFixed(3)}`);
+  }
+  return parts.map((p) => `,${p}`).join("");
+}
 
 /**
  * Cards join the source through xfade/acrossfade, which need identical
@@ -129,37 +245,29 @@ const CARD_AUDIO_FORMAT = "aformat=sample_fmts=fltp:sample_rates=48000:channel_l
  */
 const CARD_VIDEO_FORMAT = "format=yuv420p,setsar=1";
 
-/**
- * Crossfade length at each join: entry i is the fade between range i-1 and
- * range i (entry 0 is unused). Each is clamped to at most half of either
- * adjacent segment's own (pre-join) length, so a short surviving sliver
- * between two nearby cuts can't make the transition eat more than that
- * sliver. Shared by the video and audio graphs so they stay in sync.
- */
-function computeCrossfades(durations: number[]): number[] {
-  return durations.map((d, i) => (i === 0 ? 0 : Math.min(CUT_CROSSFADE_SECONDS, durations[i - 1] / 2, d / 2)));
-}
-
 /**
  * atrim + acrossfade chains ending in [outa]: the edited program's audio,
- * before any cleanup. Cards contribute silence for their duration.
+ * before any cleanup. Cards contribute silence for their render length.
+ * Join overlaps come from the layout, which also clamps each one to at most
+ * half of either neighbour, so a short sliver between two nearby cuts
+ * can't be eaten by a transition.
  */
-function buildAudioEditChains(items: ProgramItem[]): string[] {
-  const normalize = hasCards(items) ? `,${CARD_AUDIO_FORMAT}` : "";
+function buildAudioEditChains(layout: Layout): string[] {
+  const { items, lengths, overlaps } = layout;
+  const normalize = layout.withCards ? `,${CARD_AUDIO_FORMAT}` : "";
   const chains = items.map((item, i) =>
     item.kind === "source"
-      ? `[0:a]atrim=start=${item.start.toFixed(3)}:end=${item.end.toFixed(3)},asetpts=PTS-STARTPTS${normalize}[a${i}]`
-      : `anullsrc=r=48000:cl=stereo,atrim=duration=${item.card.duration.toFixed(3)}${normalize}[a${i}]`
+      ? `[0:a]atrim=start=${item.start.toFixed(3)}:end=${item.end.toFixed(3)},asetpts=PTS-STARTPTS${normalize}${audioFades(layout, i)}[a${i}]`
+      : `anullsrc=r=48000:cl=stereo,atrim=duration=${lengths[i].toFixed(3)}${normalize}${audioFades(layout, i)}[a${i}]`
   );
   if (items.length === 1) {
     chains.push("[a0]anull[outa]");
     return chains;
   }
-  const crossfades = computeCrossfades(items.map(itemDuration));
   let label = "a0";
   for (let i = 1; i < items.length; i++) {
     const next = i === items.length - 1 ? "outa" : `ax${i}`;
-    chains.push(`[${label}][a${i}]acrossfade=d=${crossfades[i].toFixed(3)}[${next}]`);
+    chains.push(`[${label}][a${i}]acrossfade=d=${overlaps[i].toFixed(3)}[${next}]`);
     label = next;
   }
   return chains;
@@ -174,13 +282,13 @@ function buildAudioEditChains(items: ProgramItem[]): string[] {
 export function buildLoudnessAnalysisArgs(args: {
   inputPath: string;
   playableRanges: PlayableRange[];
-  /** With title cards: the program, whose cards add silence (see resolveItems). */
-  program?: ProgramItem[];
+  /** With cards or transitions: the program, so the measured audio is what ships. */
+  program?: RenderProgram;
   /** From audio-filters.ts#buildLoudnessAnalysisChain. */
   analysisChain: string;
 }): string[] {
-  const items = resolveItems(args.playableRanges, args.program);
-  const chains = [...buildAudioEditChains(items), `[outa]${args.analysisChain}[analysis]`];
+  const layout = layoutProgram(args.playableRanges, args.program);
+  const chains = [...buildAudioEditChains(layout), `[outa]${args.analysisChain}[analysis]`];
   return ["-i", args.inputPath, "-filter_complex", chains.join(";"), "-map", "[analysis]", "-f", "null", "-"];
 }
 
@@ -207,15 +315,15 @@ export function buildAudioOnlyRenderArgs(args: {
   inputPath: string;
   outputPath: string;
   playableRanges: PlayableRange[];
-  /** With title cards: the program, so cards become silence and chapters stay in sync. */
-  program?: ProgramItem[];
+  /** With cards or transitions: the program, so cards become silence and chapters stay in sync. */
+  program?: RenderProgram;
   audioFilter?: string | null;
   format?: "m4a" | "mp3" | "wav";
   metadataPath?: string;
 }): string[] {
-  const items = resolveItems(args.playableRanges, args.program);
+  const layout = layoutProgram(args.playableRanges, args.program);
   const format = args.format ?? "m4a";
-  const chains = buildAudioEditChains(items);
+  const chains = buildAudioEditChains(layout);
   let label = "[outa]";
   if (args.audioFilter) {
     chains.push(`[outa]${args.audioFilter}[cleana]`);
@@ -335,7 +443,7 @@ export function buildRenderArgs(args: {
    * file with every card's text (lib/cards/ass.ts). Omit for a project
    * without cards.
    */
-  program?: ProgramItem[];
+  program?: RenderProgram;
   cardFrame?: { width: number; height: number; textPath: string };
 }): string[] {
   const {
@@ -361,9 +469,9 @@ export function buildRenderArgs(args: {
     cardFrame,
   } = args;
 
-  const items = resolveItems(playableRanges, program);
+  const layout = layoutProgram(playableRanges, program);
+  const { items, lengths, overlaps, withCards } = layout;
   if (!/^\d{1,6}(\/\d{1,6})?$/.test(frameRate)) throw new Error(`Invalid frame rate: ${frameRate}`);
-  const withCards = hasCards(items);
   if (withCards && !cardFrame) throw new Error("Title cards need the source's frame size.");
   if (cardFrame) assertValidCardFrame(cardFrame);
 
@@ -389,10 +497,11 @@ export function buildRenderArgs(args: {
   const filterChains: string[] = [];
   items.forEach((item, i) => {
     const pad = i < items.length - 1 ? `,${SEGMENT_TAIL_PAD}` : "";
+    const fades = videoFades(layout, i);
     if (!withCards) {
       const r = item as Extract<ProgramItem, { kind: "source" }>;
       filterChains.push(
-        `[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS,fps=${frameRate}${pad}[v${i}]`
+        `[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS,fps=${frameRate}${fades}${pad}[v${i}]`
       );
       return;
     }
@@ -402,12 +511,12 @@ export function buildRenderArgs(args: {
     if (item.kind === "source") {
       const grade = colorFilter ? `,${colorFilter}` : "";
       filterChains.push(
-        `[0:v]trim=start=${item.start.toFixed(3)}:end=${item.end.toFixed(3)},setpts=PTS-STARTPTS${grade},fps=${frameRate},${CARD_VIDEO_FORMAT}${pad}[v${i}]`
+        `[0:v]trim=start=${item.start.toFixed(3)}:end=${item.end.toFixed(3)},setpts=PTS-STARTPTS${grade},fps=${frameRate},${CARD_VIDEO_FORMAT}${fades}${pad}[v${i}]`
       );
     } else {
       const color = item.card.background.slice(1).toUpperCase();
       filterChains.push(
-        `color=c=0x${color}:s=${cardFrame!.width}x${cardFrame!.height}:r=${frameRate}:d=${item.card.duration.toFixed(3)},${CARD_VIDEO_FORMAT}${pad}[v${i}]`
+        `color=c=0x${color}:s=${cardFrame!.width}x${cardFrame!.height}:r=${frameRate}:d=${lengths[i].toFixed(3)},${CARD_VIDEO_FORMAT}${fades}${pad}[v${i}]`
       );
     }
   });
@@ -421,15 +530,13 @@ export function buildRenderArgs(args: {
     // each pair is joined (this is the standard idiom for chaining more
     // than one xfade) -- verified against a real ffmpeg render, not just
     // the filter's documented options, since offset math like this is easy
-    // to get subtly wrong. The audio side uses the same crossfade lengths
-    // (see buildAudioEditChains).
-    const durations = items.map(itemDuration);
-    const crossfades = computeCrossfades(durations);
+    // to get subtly wrong. The audio side uses the same overlaps (see
+    // buildAudioEditChains), both from layoutProgram.
     let videoLabel = "v0";
-    let cumulativeDuration = durations[0];
+    let cumulativeDuration = lengths[0];
     for (let i = 1; i < items.length; i++) {
-      const segmentDuration = durations[i];
-      const crossfade = crossfades[i];
+      const segmentDuration = lengths[i];
+      const crossfade = overlaps[i];
       const offset = (cumulativeDuration - crossfade).toFixed(3);
       const nextVideoLabel = i === items.length - 1 ? "outv" : `vx${i}`;
       filterChains.push(
@@ -440,7 +547,7 @@ export function buildRenderArgs(args: {
     }
   }
 
-  filterChains.push(...buildAudioEditChains(items));
+  filterChains.push(...buildAudioEditChains(layout));
   let audioOutLabel = "[outa]";
   if (audioFilter) {
     filterChains.push(`[outa]${audioFilter}[cleana]`);
diff --git a/server/src/lib/ffmpeg/render-job.ts b/server/src/lib/ffmpeg/render-job.ts
index 0fa0126..e87bc05 100644
--- a/server/src/lib/ffmpeg/render-job.ts
+++ b/server/src/lib/ffmpeg/render-job.ts
@@ -22,15 +22,15 @@ import {
 } from "@/lib/ffmpeg/audio-filters";
 import { parseStoredAudioSettings } from "@/lib/validation/audio-settings";
 import { runFfmpeg, runFfmpegCapturingStderr } from "@/lib/ffmpeg/run";
+import type { RenderProgram } from "@/lib/ffmpeg/plan";
 import { probeVideoStream } from "@/lib/ffmpeg/probe";
 import {
-  buildProgramItems,
+  buildProgram,
   cardStartTimes,
   cardsDuration,
   editedRangeToProgram,
-  placeCards,
+  isPlainProgram,
   type CardSlot,
-  type ProgramItem,
 } from "@/lib/timeline/program";
 import { toCardsAss } from "@/lib/cards/ass";
 import type { CaptionCue } from "@/lib/captions/generate";
@@ -75,7 +75,7 @@ export async function resolveLoudnessGain(
   playableRanges: PlayableRange[],
   audioSettings: AudioSettings,
   jobId: string,
-  program?: ProgramItem[]
+  program?: RenderProgram
 ): Promise<number | undefined> {
   const target = loudnessTargetLufs(audioSettings);
   if (target === null) return undefined;
@@ -192,9 +192,13 @@ export async function runRenderJob(
       ...(clip ? clipAsCuts(clip, project.duration) : []),
     ];
     const playableRanges = computePlayableRanges(project.duration, cuts);
-    // Title cards play in full exports only: a clip is a standalone excerpt.
-    const cardSlots = clip ? [] : placeCards(operations, playableRanges, project.duration);
-    const program = cardSlots.length > 0 ? buildProgramItems(playableRanges, cardSlots) : undefined;
+    // Title cards and transitions play in full exports only: a clip is a standalone excerpt.
+    const built = clip ? null : buildProgram(operations, playableRanges, project.duration);
+    const cardSlots = built?.slots ?? [];
+    const program: RenderProgram | undefined =
+      built && !isPlainProgram(built)
+        ? { items: built.items, joins: built.joins, fadeIn: built.fadeIn, fadeOut: built.fadeOut }
+        : undefined;
 
     const inputPath = resolveInDataDir(originalAsset.filePath);
     const outputRelativePath = path.posix.join(
@@ -229,9 +233,9 @@ export async function runRenderJob(
 
     // Title cards are generated at the source's own size so they join it seamlessly.
     let cardFrame: { width: number; height: number; textPath: string } | undefined;
-    if (program && sourceStream) {
+    if (program && cardSlots.length > 0 && sourceStream) {
       const textPath = resolveInDataDir(path.posix.join("projects", project.id, "render", `${jobId}.cards.ass`));
-      await writeFile(textPath, toCardsAss(cardStartTimes(program), sourceStream), "utf-8");
+      await writeFile(textPath, toCardsAss(cardStartTimes(program.items), sourceStream), "utf-8");
       cardFrame = { width: sourceStream.width, height: sourceStream.height, textPath };
     }
 

From e088d68c9d68c5eaa5735b5628da1844a2bdd1f5 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:43:16 +0530
Subject: [PATCH 19/36] feat(client): preview transitions over the player

transition-look.ts works out, for a program time, what color and/or
title card to lay over the player and how opaque, with the render's
timing and clamping. TransitionOverlay applies it from its own animation-
frame loop through refs, so fades are smooth without re-rendering the
editor every frame. Card and transition layers now sit under the logo,
as in the export.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../video-player/TransitionOverlay.tsx        | 61 +++++++++++++++++
 .../components/video-player/VideoPlayer.tsx   |  7 +-
 .../src/lib/timeline/transition-look.test.ts  | 68 +++++++++++++++++++
 client/src/lib/timeline/transition-look.ts    | 63 +++++++++++++++++
 client/src/lib/timeline/useProgram.ts         | 19 ++++--
 5 files changed, 210 insertions(+), 8 deletions(-)
 create mode 100644 client/src/components/video-player/TransitionOverlay.tsx
 create mode 100644 client/src/lib/timeline/transition-look.test.ts
 create mode 100644 client/src/lib/timeline/transition-look.ts

diff --git a/client/src/components/video-player/TransitionOverlay.tsx b/client/src/components/video-player/TransitionOverlay.tsx
new file mode 100644
index 0000000..e53228c
--- /dev/null
+++ b/client/src/components/video-player/TransitionOverlay.tsx
@@ -0,0 +1,61 @@
+import { useEffect, useRef, useState, type RefObject } from "react";
+import { usePlayerStore } from "@/stores/player-store";
+import { transitionLookAt } from "@/lib/timeline/transition-look";
+import { programPlayhead, type Program } from "@/lib/timeline/useProgram";
+import { CardPreview } from "@/components/video-player/CardPreview";
+import type { CardOperation } from "@/types/edit-operation";
+
+/**
+ * Previews transitions over the player: a color layer for dips and the
+ * episode's fade in/out, and a fading title card for crossfades. Driven by
+ * its own animation-frame loop reading the video's live time, and styled
+ * through refs, so fades are smooth without re-rendering the editor every
+ * frame (the store's currentTime only updates a few times a second).
+ * Audio fades aren't previewed; the export applies them.
+ */
+export function TransitionOverlay({
+  videoRef,
+  program,
+}: {
+  videoRef: RefObject<HTMLVideoElement | null>;
+  program: Program;
+}) {
+  const colorRef = useRef<HTMLDivElement>(null);
+  const cardRef = useRef<HTMLDivElement>(null);
+  const [fadingCard, setFadingCard] = useState<CardOperation | null>(null);
+  const fadingCardIdRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    let frame = 0;
+    const tick = () => {
+      const video = videoRef.current;
+      if (video) {
+        const t = programPlayhead(program, video.currentTime, usePlayerStore.getState().card);
+        const look = transitionLookAt(program, t);
+        if (colorRef.current) {
+          colorRef.current.style.opacity = String(look.color?.opacity ?? 0);
+          if (look.color) colorRef.current.style.backgroundColor = look.color.color;
+        }
+        const cardId = look.card?.card.id ?? null;
+        if (cardId !== fadingCardIdRef.current) {
+          fadingCardIdRef.current = cardId;
+          setFadingCard(look.card?.card ?? null);
+        }
+        if (cardRef.current) cardRef.current.style.opacity = String(look.card?.opacity ?? 0);
+      }
+      frame = requestAnimationFrame(tick);
+    };
+    frame = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame);
+  }, [videoRef, program]);
+
+  return (
+    <>
+      <div ref={cardRef} className="pointer-events-none absolute inset-0" style={{ opacity: 0 }}>
+        {/* elapsed 0 hides the text: the export's card text only starts once the blend is done. */}
+        {fadingCard && <CardPreview card={fadingCard} elapsed={0} />}
+      </div>
+      <div ref={colorRef} className="pointer-events-none absolute inset-0" style={{ opacity: 0 }} />
+    </>
+  );
+}
diff --git a/client/src/components/video-player/VideoPlayer.tsx b/client/src/components/video-player/VideoPlayer.tsx
index 201f47c..a6df3c2 100644
--- a/client/src/components/video-player/VideoPlayer.tsx
+++ b/client/src/components/video-player/VideoPlayer.tsx
@@ -12,6 +12,7 @@ import { locateProgramTime } from "@/lib/timeline/program";
 import { programPlayhead, useProgram } from "@/lib/timeline/useProgram";
 import { useCardPlayback } from "@/components/video-player/useCardPlayback";
 import { CardPreview } from "@/components/video-player/CardPreview";
+import { TransitionOverlay } from "@/components/video-player/TransitionOverlay";
 import { generateCaptions } from "@/lib/captions/generate";
 import { formatTimecode } from "@/lib/timeline/format";
 import { getFilterPreset } from "@/lib/video/filters";
@@ -315,6 +316,10 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
           data-playing={isPlaying}
         />
         <CropOverlay />
+        {/* Under the logo, like the export: the watermark stays on top of cards and transitions. */}
+        {activeCard && <CardPreview card={activeCard} elapsed={card?.elapsed} />}
+        <TransitionOverlay videoRef={videoRef} program={program} />
+        {cardDraft && <CardPreview card={cardDraft} />}
         {logoUrl && (
           <img
             src={logoUrl}
@@ -324,8 +329,6 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
             style={logoPositionToCss(logoPosition, logoPaddingX, logoPaddingY, logoOpacity)}
           />
         )}
-        {activeCard && <CardPreview card={activeCard} elapsed={card?.elapsed} />}
-        {cardDraft && <CardPreview card={cardDraft} />}
         {burnInCaptions && activeCue && !activeCard && !cardDraft && (
           <div
             className="pointer-events-none absolute inset-x-0 flex justify-center px-4"
diff --git a/client/src/lib/timeline/transition-look.test.ts b/client/src/lib/timeline/transition-look.test.ts
new file mode 100644
index 0000000..21ce753
--- /dev/null
+++ b/client/src/lib/timeline/transition-look.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { transitionLookAt } from "@/lib/timeline/transition-look";
+import type { ProgramItem } from "@/lib/timeline/program";
+import type { CardOperation } from "@/types/edit-operation";
+
+const card: CardOperation = {
+  id: "c1",
+  type: "card",
+  at: 10,
+  duration: 3,
+  template: "title",
+  title: "Part 2",
+  background: "#111418",
+  createdAt: 0,
+};
+const footage: ProgramItem[] = [
+  { kind: "source", start: 0, end: 10 },
+  { kind: "source", start: 10, end: 20 },
+];
+
+describe("transitionLookAt", () => {
+  it("shows nothing with plain cuts", () => {
+    expect(transitionLookAt({ items: footage, joins: [{ kind: "cut" }], fadeIn: null, fadeOut: null }, 10)).toEqual({
+      color: null,
+      card: null,
+    });
+  });
+
+  it("dips to full color at the join and back out over half the length each side", () => {
+    const program = {
+      items: footage,
+      joins: [{ kind: "dip" as const, color: "white" as const, seconds: 1 }],
+      fadeIn: null,
+      fadeOut: null,
+    };
+    expect(transitionLookAt(program, 10).color).toEqual({ color: "white", opacity: 1 });
+    expect(transitionLookAt(program, 9.75).color?.opacity).toBeCloseTo(0.5);
+    expect(transitionLookAt(program, 10.25).color?.opacity).toBeCloseTo(0.5);
+    expect(transitionLookAt(program, 9).color).toBeNull();
+  });
+
+  it("fades a card in before it and out after it for a crossfade", () => {
+    const program = {
+      items: [footage[0], { kind: "card" as const, card }, footage[1]],
+      joins: [
+        { kind: "crossfade" as const, seconds: 1 },
+        { kind: "crossfade" as const, seconds: 1 },
+      ],
+      fadeIn: null,
+      fadeOut: null,
+    };
+    expect(transitionLookAt(program, 9.5).card?.opacity).toBeCloseTo(0.5);
+    expect(transitionLookAt(program, 13.25).card?.opacity).toBeCloseTo(0.75);
+    expect(transitionLookAt(program, 11).card).toBeNull();
+  });
+
+  it("fades the episode in and out", () => {
+    const program = {
+      items: footage,
+      joins: [{ kind: "cut" as const }],
+      fadeIn: { color: "black" as const, seconds: 2 },
+      fadeOut: { color: "black" as const, seconds: 2 },
+    };
+    expect(transitionLookAt(program, 0).color?.opacity).toBe(1);
+    expect(transitionLookAt(program, 1).color?.opacity).toBeCloseTo(0.5);
+    expect(transitionLookAt(program, 19).color?.opacity).toBeCloseTo(0.5);
+  });
+});
diff --git a/client/src/lib/timeline/transition-look.ts b/client/src/lib/timeline/transition-look.ts
new file mode 100644
index 0000000..4e2618b
--- /dev/null
+++ b/client/src/lib/timeline/transition-look.ts
@@ -0,0 +1,63 @@
+import { itemStartTimes, programItemDuration, type Fade, type Join, type ProgramItem } from "@/lib/timeline/program";
+import type { CardOperation } from "@/types/edit-operation";
+
+/**
+ * What the preview should lay over the player at a program time to show
+ * transitions: a solid color at some opacity (a dip, or the episode fading
+ * in/out), and/or a title card at some opacity (a crossfade into or out of
+ * it). Mirrors the render's timing (lib/ffmpeg/plan.ts#layoutProgram),
+ * including clamping each transition to half of the items it touches.
+ */
+export type TransitionLook = {
+  color: { color: "black" | "white"; opacity: number } | null;
+  card: { card: CardOperation; opacity: number } | null;
+};
+
+export function transitionLookAt(
+  program: { items: ProgramItem[]; joins: Join[]; fadeIn: Fade | null; fadeOut: Fade | null },
+  programTime: number
+): TransitionLook {
+  const { items, joins, fadeIn, fadeOut } = program;
+  const look: TransitionLook = { color: null, card: null };
+  if (items.length === 0) return look;
+
+  const lengths = items.map(programItemDuration);
+  const starts = itemStartTimes(items);
+  const total = starts[starts.length - 1] + lengths[lengths.length - 1];
+  const t = programTime;
+
+  const showColor = (color: "black" | "white", opacity: number) => {
+    const o = Math.max(0, Math.min(1, opacity));
+    if (!look.color || o > look.color.opacity) look.color = { color, opacity: o };
+  };
+
+  if (fadeIn) {
+    const seconds = Math.min(fadeIn.seconds, lengths[0] / 2);
+    if (t < seconds) showColor(fadeIn.color, 1 - t / seconds);
+  }
+  if (fadeOut) {
+    const seconds = Math.min(fadeOut.seconds, lengths[lengths.length - 1] / 2);
+    if (t > total - seconds) showColor(fadeOut.color, (t - (total - seconds)) / seconds);
+  }
+
+  joins.forEach((join, j) => {
+    if (join.kind === "cut") return;
+    const at = starts[j + 1];
+    const room = Math.min(lengths[j], lengths[j + 1]) / 2;
+    if (join.kind === "dip") {
+      const half = Math.min(join.seconds / 2, room);
+      const distance = Math.abs(t - at);
+      if (distance < half) showColor(join.color, 1 - distance / half);
+      return;
+    }
+    const seconds = Math.min(join.seconds, room);
+    const before = items[j];
+    const after = items[j + 1];
+    if (after.kind === "card" && t >= at - seconds && t < at) {
+      look.card = { card: after.card, opacity: (t - (at - seconds)) / seconds };
+    } else if (before.kind === "card" && t >= at && t < at + seconds) {
+      look.card = { card: before.card, opacity: 1 - (t - at) / seconds };
+    }
+  });
+  return look;
+}
diff --git a/client/src/lib/timeline/useProgram.ts b/client/src/lib/timeline/useProgram.ts
index 0f7823c..9eca952 100644
--- a/client/src/lib/timeline/useProgram.ts
+++ b/client/src/lib/timeline/useProgram.ts
@@ -3,11 +3,12 @@ import { usePlayerStore } from "@/stores/player-store";
 import { useTimelineStore } from "@/stores/timeline-store";
 import { computePlayableRanges, getEditedDuration, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
 import {
-  buildProgramItems,
+  buildProgram,
   cardsDuration,
   editedToProgramTime,
-  placeCards,
   type CardSlot,
+  type Fade,
+  type Join,
   type ProgramItem,
 } from "@/lib/timeline/program";
 import type { CutOperation } from "@/types/edit-operation";
@@ -18,6 +19,10 @@ export type Program = {
   ranges: PlayableRange[];
   slots: CardSlot[];
   items: ProgramItem[];
+  /** How items[i] joins items[i + 1]. */
+  joins: Join[];
+  fadeIn: Fade | null;
+  fadeOut: Fade | null;
   editedDuration: number;
   /** Edited duration plus every card: what the export runs for. */
   duration: number;
@@ -31,15 +36,17 @@ export function useProgram(): Program {
   return useMemo(() => {
     const cuts = operations.filter((op): op is CutOperation => op.type === "cut");
     const ranges = computePlayableRanges(sourceDuration, cuts);
-    const slots = sourceDuration > 0 ? placeCards(operations, ranges, sourceDuration) : [];
+    const program =
+      sourceDuration > 0
+        ? buildProgram(operations, ranges, sourceDuration)
+        : { slots: [], items: [], joins: [], fadeIn: null, fadeOut: null };
     const editedDuration = getEditedDuration(ranges);
     return {
       cuts,
       ranges,
-      slots,
-      items: buildProgramItems(ranges, slots),
+      ...program,
       editedDuration,
-      duration: editedDuration + cardsDuration(slots),
+      duration: editedDuration + cardsDuration(program.slots),
     };
   }, [operations, sourceDuration]);
 }

From a446127f59ad8a9019657100bf2ff6a539d60d27 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:43:16 +0530
Subject: [PATCH 20/36] feat(client): pick transitions per scene and show them
 on the timeline

Each scene gets a Transition in picker (crossfade offered once it has a
title card), the first scene a Fade in and the outro a Fade out, each
with a length. On the timeline a diamond marks each transition and a
wedge each episode fade.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/components/editor/ScenesPanel.tsx  | 25 +++++-
 .../components/editor/TransitionPicker.tsx    | 89 +++++++++++++++++++
 client/src/components/timeline/Timeline.tsx   | 30 ++++++-
 3 files changed, 142 insertions(+), 2 deletions(-)
 create mode 100644 client/src/components/editor/TransitionPicker.tsx

diff --git a/client/src/components/editor/ScenesPanel.tsx b/client/src/components/editor/ScenesPanel.tsx
index 659b9ef..05431ad 100644
--- a/client/src/components/editor/ScenesPanel.tsx
+++ b/client/src/components/editor/ScenesPanel.tsx
@@ -10,8 +10,9 @@ import { cutsOverlapping } from "@/lib/timeline/cuts";
 import { formatTimecode } from "@/lib/timeline/format";
 import { Button } from "@/components/ui/button";
 import { CardEditor } from "@/components/editor/CardEditor";
+import { TransitionPicker } from "@/components/editor/TransitionPicker";
 import { CARD_BACKGROUNDS } from "@/lib/cards/layout";
-import type { CardOperation, CardTemplate, CutOperation } from "@/types/edit-operation";
+import type { CardOperation, CardTemplate, CutOperation, TransitionOperation } from "@/types/edit-operation";
 
 /** A card at a scene's start (within this) belongs to that scene. */
 const CARD_MATCH_SECONDS = 0.05;
@@ -45,6 +46,15 @@ export function ScenesPanel() {
     [operations]
   );
   const cardsAt = (at: number) => cards.filter((c) => Math.abs(c.at - at) <= CARD_MATCH_SECONDS);
+  const transitions = useMemo(
+    () =>
+      operations
+        .filter((op): op is TransitionOperation => op.type === "transition")
+        .sort((a, b) => a.createdAt - b.createdAt),
+    [operations]
+  );
+  /** The transition in effect at a moment: the latest one there. */
+  const transitionAt = (at: number) => transitions.filter((t) => Math.abs(t.at - at) <= CARD_MATCH_SECONDS).at(-1);
   const outroCards = cards.filter((c) => c.at >= duration - CARD_MATCH_SECONDS);
   const activeScene = sceneAt(scenes, currentTime);
 
@@ -210,6 +220,18 @@ export function ScenesPanel() {
                 {cardsAt(scene.index === 0 ? 0 : scene.start).length > 0 && (
                   <div className="flex flex-col gap-1 pl-3.5">{cardList(cardsAt(scene.index === 0 ? 0 : scene.start))}</div>
                 )}
+                <div className="pl-3.5">
+                  {scene.index === 0 ? (
+                    <TransitionPicker label="Fade in" at={0} edge="in" current={transitionAt(0)} />
+                  ) : (
+                    <TransitionPicker
+                      label="Transition in"
+                      at={scene.start}
+                      current={transitionAt(scene.start)}
+                      canCrossfade={cardsAt(scene.start).length > 0}
+                    />
+                  )}
+                </div>
               </li>
             );
           })}
@@ -226,6 +248,7 @@ export function ScenesPanel() {
             </Button>
           </div>
           {cardList(outroCards)}
+          <TransitionPicker label="Fade out" at={duration} edge="out" current={transitionAt(duration)} />
         </div>
       )}
     </div>
diff --git a/client/src/components/editor/TransitionPicker.tsx b/client/src/components/editor/TransitionPicker.tsx
new file mode 100644
index 0000000..a07fa7c
--- /dev/null
+++ b/client/src/components/editor/TransitionPicker.tsx
@@ -0,0 +1,89 @@
+"use client";
+
+import { useTimelineStore } from "@/stores/timeline-store";
+import type { TransitionKind, TransitionOperation } from "@/types/edit-operation";
+
+const DURATIONS = [0.5, 1, 1.5, 2];
+const selectClass =
+  "h-6 rounded border border-border bg-transparent px-1 text-[0.7rem] text-foreground focus:border-primary focus:outline-none";
+
+/**
+ * Picks the transition at one moment: into a scene (dip or, when the scene
+ * has a title card, crossfade), or the episode's fade in (at 0) / fade out
+ * (at the end), which only dip. One operation per moment; choosing "None"
+ * removes it. Every change is one undo step.
+ */
+export function TransitionPicker({
+  label,
+  at,
+  current,
+  edge,
+  canCrossfade = false,
+}: {
+  label: string;
+  at: number;
+  current: TransitionOperation | undefined;
+  /** The episode's start or end: dips only, worded as fades. */
+  edge?: "in" | "out";
+  canCrossfade?: boolean;
+}) {
+  const addOperations = useTimelineStore((s) => s.addOperations);
+  const replaceOperation = useTimelineStore((s) => s.replaceOperation);
+  const removeOperations = useTimelineStore((s) => s.removeOperations);
+
+  const save = (kind: TransitionKind | "none", duration: number) => {
+    if (kind === "none") {
+      if (current) removeOperations([current.id]);
+      return;
+    }
+    const next: TransitionOperation = {
+      id: crypto.randomUUID(),
+      type: "transition",
+      at,
+      kind,
+      duration,
+      createdAt: Date.now(),
+    };
+    if (current) replaceOperation(current.id, next);
+    else addOperations([next]);
+  };
+
+  const kind = current?.kind ?? "none";
+  const duration = current?.duration ?? 1;
+  const toward = edge === "in" ? "from" : edge === "out" ? "to" : "via";
+
+  return (
+    <label className="flex items-center gap-1.5 text-muted-foreground">
+      <span className="shrink-0">{label}</span>
+      <select
+        value={kind === "crossfade" && !canCrossfade ? "none" : kind}
+        onChange={(e) => save(e.target.value as TransitionKind | "none", duration)}
+        className={`${selectClass} min-w-0 flex-1`}
+        aria-label={label}
+      >
+        <option value="none">None</option>
+        <option value="dipBlack">{edge ? `Fade ${toward} black` : "Dip to black"}</option>
+        <option value="dipWhite">{edge ? `Fade ${toward} white` : "Dip to white"}</option>
+        {!edge && (
+          <option value="crossfade" disabled={!canCrossfade}>
+            {canCrossfade ? "Crossfade with card" : "Crossfade (needs a title card)"}
+          </option>
+        )}
+      </select>
+      {current && (
+        <select
+          value={duration}
+          onChange={(e) => save(current.kind, Number(e.target.value))}
+          className={selectClass}
+          aria-label={`${label} length`}
+        >
+          {DURATIONS.map((d) => (
+            <option key={d} value={d}>
+              {d}s
+            </option>
+          ))}
+        </select>
+      )}
+    </label>
+  );
+}
diff --git a/client/src/components/timeline/Timeline.tsx b/client/src/components/timeline/Timeline.tsx
index 3d24d32..c68cccf 100644
--- a/client/src/components/timeline/Timeline.tsx
+++ b/client/src/components/timeline/Timeline.tsx
@@ -6,7 +6,7 @@ import { useProjectStore } from "@/stores/project-store";
 import { useTimelineStore } from "@/stores/timeline-store";
 import { useTranscriptStore } from "@/stores/transcript-store";
 import { editedTimeToSourceTime, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
-import { editedToProgramTime, locateProgramTime, programItemDuration } from "@/lib/timeline/program";
+import { editedToProgramTime, itemStartTimes, locateProgramTime, programItemDuration } from "@/lib/timeline/program";
 import { programPlayhead, useProgram } from "@/lib/timeline/useProgram";
 import { formatTimecode } from "@/lib/timeline/format";
 import { useWaveform } from "@/lib/timeline/useWaveform";
@@ -59,6 +59,7 @@ export function Timeline() {
   const totalDuration = program.duration;
   const programTime = programPlayhead(program, currentTime, card);
   const playheadPosition = totalDuration > 0 ? (programTime / totalDuration) * 100 : 0;
+  const itemStarts = useMemo(() => itemStartTimes(program.items), [program.items]);
   /** Percent across the track of a source time (after any card at that moment unless noted). */
   const percentAt = (sourceTime: number, includeCardsAtPoint = true) =>
     (editedToProgramTime(sourceTimeToEditedTime(sourceTime, playableRanges), slots, { includeCardsAtPoint }) /
@@ -274,6 +275,33 @@ export function Timeline() {
                 />
               );
             })}
+            {/* Transitions: a diamond on each styled join, a wedge where the episode fades in or out. */}
+            {program.joins.map((join, j) => {
+              if (join.kind === "cut") return null;
+              const at = itemStarts[j + 1];
+              const label =
+                join.kind === "crossfade" ? "Crossfade" : join.color === "white" ? "Dip to white" : "Dip to black";
+              return (
+                <div
+                  key={`join-${j}`}
+                  className="pointer-events-none absolute top-1 size-2.5 -translate-x-1/2 rotate-45 rounded-[2px] border border-background bg-primary"
+                  style={{ left: `${(at / totalDuration) * 100}%` }}
+                  title={`${label} (${join.seconds}s)`}
+                />
+              );
+            })}
+            {program.fadeIn && (
+              <div
+                className="pointer-events-none absolute top-0 left-0 h-full bg-gradient-to-r from-black/70 to-transparent"
+                style={{ width: `${(program.fadeIn.seconds / totalDuration) * 100}%` }}
+              />
+            )}
+            {program.fadeOut && (
+              <div
+                className="pointer-events-none absolute top-0 right-0 h-full bg-gradient-to-l from-black/70 to-transparent"
+                style={{ width: `${(program.fadeOut.seconds / totalDuration) * 100}%` }}
+              />
+            )}
             {scenes.slice(1).map((scene) => (
               <div
                 key={scene.id}

From ade1badb760fab1f2a9830f6cddfac8fd28ee5d7 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 01:43:16 +0530
Subject: [PATCH 21/36] docs: document transitions and why they keep program
 length

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 claude.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/claude.md b/claude.md
index 7ea0f9e..4313035 100644
--- a/claude.md
+++ b/claude.md
@@ -661,6 +661,19 @@ characters. The preview can't insert frames into a `<video>`, so
 `CardPreview` (same layout percentages, `lib/cards/layout.ts`) on its own
 clock, then resumes.
 
+A `transition` operation styles the join into the scene starting at its
+`at` (both joins around that scene's card, if it has one): dip to black,
+dip to white, or crossfade (only with a card -- between two stretches of
+footage that follow each other in the source it shows nothing, so it
+falls back to a cut). At 0 it fades the episode in, at the end it fades
+it out. **Transitions never change the program's length**, so captions
+and chapters need no adjusting: a dip fades each side's own edge
+(`fade`/`afade`, audio capped at 0.3s next to speech) and keeps the
+usual join, and a crossfade's overlap is added to the card's rendered
+length (`plan.ts#layoutProgram`). The preview draws them with
+`TransitionOverlay` from the pure `transition-look.ts`, on its own
+animation-frame loop; audio fades aren't previewed.
+
 **ffmpeg 9 xfade gotchas** (`plan.ts`, measured on 9.0.2): every segment
 must be pinned to the source's frame rate with `fps=` (without it xfade
 drops the start of each later segment), must not get a `settb` after

From 673a85a510adfb38f8a4ed61b42955f15ea95119 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:00:19 +0530
Subject: [PATCH 22/36] feat(server): a media library for B-roll

Projects can now hold many images and video clips alongside their main
video. Uploads are raw bodies like the main upload, stored under a unique
prefix (camera files often share names), and probed on the way in --
anything ffmpeg can't read is refused now rather than at export. Asset
gains nullable name/width/height/duration columns (an additive migration,
applied at startup). A file can't be deleted while B-roll uses it, so an
export never references a missing file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../migration.sql                             |   5 +
 server/prisma/schema.prisma                   |   9 +-
 server/src/index.ts                           |   2 +
 server/src/lib/storage/local.test.ts          |   2 +-
 server/src/lib/storage/local.ts               |   6 +-
 server/src/routes/media.ts                    | 140 ++++++++++++++++++
 6 files changed, 159 insertions(+), 5 deletions(-)
 create mode 100644 server/prisma/migrations/20260926000000_add_media_metadata/migration.sql
 create mode 100644 server/src/routes/media.ts

diff --git a/server/prisma/migrations/20260926000000_add_media_metadata/migration.sql b/server/prisma/migrations/20260926000000_add_media_metadata/migration.sql
new file mode 100644
index 0000000..45ced7f
--- /dev/null
+++ b/server/prisma/migrations/20260926000000_add_media_metadata/migration.sql
@@ -0,0 +1,5 @@
+-- AlterTable
+ALTER TABLE "Asset" ADD COLUMN "name" TEXT;
+ALTER TABLE "Asset" ADD COLUMN "width" INTEGER;
+ALTER TABLE "Asset" ADD COLUMN "height" INTEGER;
+ALTER TABLE "Asset" ADD COLUMN "duration" REAL;
diff --git a/server/prisma/schema.prisma b/server/prisma/schema.prisma
index 5d39da5..b07268a 100644
--- a/server/prisma/schema.prisma
+++ b/server/prisma/schema.prisma
@@ -97,13 +97,20 @@ model Asset {
   projectId String
   project   Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
 
-  /// "original" | "proxy" | "audio" | "thumbnail" | "render"
+  /// "original" | "proxy" | "audio" | "thumbnail" | "render" | "logo" | "media"
   kind String
   /// Path relative to DATA_DIR, e.g. "projects/{id}/original/video.mp4"
   filePath String
   mimeType String
   sizeBytes Int
 
+  /// Media library (B-roll) only: the uploaded file's name, pixel size, and
+  /// length in seconds for video.
+  name     String?
+  width    Int?
+  height   Int?
+  duration Float?
+
   createdAt DateTime @default(now())
 
   @@index([projectId])
diff --git a/server/src/index.ts b/server/src/index.ts
index c9df6c2..1c4e201 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -17,6 +17,7 @@ import { renderRoute } from "@/routes/render";
 import { settingsRoute } from "@/routes/settings";
 import { publishingRoute } from "@/routes/publishing";
 import { speakersRoute } from "@/routes/speakers";
+import { mediaRoute } from "@/routes/media";
 import { clipsRoute } from "@/routes/clips";
 import { prisma } from "@/lib/db/client";
 import { getMaxUploadBytes } from "@/lib/limits";
@@ -40,6 +41,7 @@ app.route("/api/projects", renderRoute);
 app.route("/api/projects", publishingRoute);
 app.route("/api/projects", speakersRoute);
 app.route("/api/projects", clipsRoute);
+app.route("/api/projects", mediaRoute);
 app.route("/api/settings", settingsRoute);
 
 // Serves the built Vite client (server-bundle/client-dist in the packaged
diff --git a/server/src/lib/storage/local.test.ts b/server/src/lib/storage/local.test.ts
index 509a49d..d3ed551 100644
--- a/server/src/lib/storage/local.test.ts
+++ b/server/src/lib/storage/local.test.ts
@@ -69,7 +69,7 @@ describe("storage/local (real fs, temp DATA_DIR)", () => {
   it("ensureProjectDirs creates every asset-kind subdirectory", async () => {
     await ensureProjectDirs("project1");
     const kinds = await readdir(path.join(getDataDir(), "projects", "project1"));
-    expect(kinds.sort()).toEqual(["audio", "logo", "original", "proxy", "render", "thumbnail"]);
+    expect(kinds.sort()).toEqual(["audio", "logo", "media", "original", "proxy", "render", "thumbnail"]);
   });
 
   it("deleteProjectDir removes the whole project directory", async () => {
diff --git a/server/src/lib/storage/local.ts b/server/src/lib/storage/local.ts
index 31d7092..d30aa4d 100644
--- a/server/src/lib/storage/local.ts
+++ b/server/src/lib/storage/local.ts
@@ -38,7 +38,7 @@ function assertSafeProjectId(projectId: string): void {
   }
 }
 
-export type AssetKind = "original" | "proxy" | "audio" | "thumbnail" | "render" | "logo";
+export type AssetKind = "original" | "proxy" | "audio" | "thumbnail" | "render" | "logo" | "media";
 
 function projectRelativeDir(projectId: string, kind: AssetKind): string {
   assertSafeProjectId(projectId);
@@ -46,13 +46,13 @@ function projectRelativeDir(projectId: string, kind: AssetKind): string {
 }
 
 /** Strip any path components / unsafe characters from a client-supplied filename. */
-function sanitizeFilename(filename: string): string {
+export function sanitizeFilename(filename: string): string {
   const base = path.basename(filename).replace(/[^a-zA-Z0-9._-]/g, "_");
   return base.length > 0 ? base : "file";
 }
 
 export async function ensureProjectDirs(projectId: string): Promise<void> {
-  const kinds: AssetKind[] = ["original", "proxy", "audio", "thumbnail", "render", "logo"];
+  const kinds: AssetKind[] = ["original", "proxy", "audio", "thumbnail", "render", "logo", "media"];
   await Promise.all(
     kinds.map((kind) => mkdir(resolveInDataDir(projectRelativeDir(projectId, kind)), { recursive: true }))
   );
diff --git a/server/src/routes/media.ts b/server/src/routes/media.ts
new file mode 100644
index 0000000..95d0c27
--- /dev/null
+++ b/server/src/routes/media.ts
@@ -0,0 +1,140 @@
+import { randomUUID } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { Hono } from "hono";
+import { prisma } from "@/lib/db/client";
+import { resolveInDataDir, sanitizeFilename, writeAssetStream } from "@/lib/storage/local";
+import { errorResponse } from "@/lib/http";
+import { getMaxUploadBytes } from "@/lib/limits";
+import { logger } from "@/lib/logger";
+import { probeDuration, probeVideoStream } from "@/lib/ffmpeg/probe";
+import type { EditOperation } from "@/types/edit-operation";
+
+export const mediaRoute = new Hono();
+
+/** Still images are small; B-roll video can be as large as any upload. */
+const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
+/** Raster formats ffmpeg decodes as a looped input (no SVG decoder -- see routes/logo.ts). */
+const IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/webp"]);
+
+type Asset = Awaited<ReturnType<typeof prisma.asset.findFirstOrThrow>>;
+
+function toMediaItem(projectId: string, asset: Asset) {
+  return {
+    id: asset.id,
+    name: asset.name ?? "media",
+    type: asset.mimeType.startsWith("image/") ? ("image" as const) : ("video" as const),
+    mimeType: asset.mimeType,
+    sizeBytes: asset.sizeBytes,
+    width: asset.width,
+    height: asset.height,
+    duration: asset.duration,
+    url: `/api/projects/${projectId}/media/${asset.id}/file`,
+  };
+}
+
+/** The project's media library: images and video clips to use as B-roll. */
+mediaRoute.get("/:id/media", async (c) => {
+  const id = c.req.param("id");
+  const assets = await prisma.asset.findMany({ where: { projectId: id, kind: "media" }, orderBy: { createdAt: "asc" } });
+  return c.json({ success: true, media: assets.map((a) => toMediaItem(id, a)) });
+});
+
+/**
+ * POST /api/projects/:id/media?filename=clip.mp4 -- raw body, like the main
+ * upload, so video streams straight to disk. Each file is stored under a
+ * unique prefix (a library holds many files, often with the same camera
+ * names), probed for its size and length, and refused if ffmpeg can't read
+ * it -- better now than at export time.
+ */
+mediaRoute.post("/:id/media", async (c) => {
+  const id = c.req.param("id");
+  const project = await prisma.project.findUnique({ where: { id }, select: { id: true } });
+  if (!project) return errorResponse(c, "NOT_FOUND", "Project not found.", 404);
+
+  const filename = c.req.query("filename");
+  if (!filename) return errorResponse(c, "MISSING_FILENAME", "A ?filename= query param is required.", 400);
+
+  const contentType = c.req.header("content-type") ?? "";
+  const isImage = IMAGE_TYPES.has(contentType);
+  if (!isImage && !contentType.startsWith("video/")) {
+    return errorResponse(c, "INVALID_FILE_TYPE", "Use a PNG, JPG or WEBP image, or a video file.", 400);
+  }
+
+  const contentLength = Number(c.req.header("content-length"));
+  if (!Number.isFinite(contentLength) || contentLength <= 0) {
+    return errorResponse(c, "MISSING_CONTENT_LENGTH", "A Content-Length header is required.", 400);
+  }
+  const maxBytes = isImage ? MAX_IMAGE_BYTES : getMaxUploadBytes();
+  if (contentLength > maxBytes) {
+    return errorResponse(c, "FILE_TOO_LARGE", `File exceeds the ${Math.round(maxBytes / (1024 * 1024))}MB limit.`, 413);
+  }
+  const body = c.req.raw.body;
+  if (!body) return errorResponse(c, "EMPTY_FILE", "The uploaded file is empty.", 400);
+
+  const storedName = `${randomUUID().slice(0, 8)}-${sanitizeFilename(filename)}`;
+  const { relativePath, absolutePath, sizeBytes } = await writeAssetStream(id, "media", storedName, body);
+
+  let dimensions: { width: number; height: number };
+  let duration: number | null = null;
+  try {
+    dimensions = await probeVideoStream(absolutePath);
+    if (!isImage) duration = await probeDuration(absolutePath);
+  } catch (err) {
+    logger.warn(`Media upload for ${id} couldn't be read:`, err);
+    await rm(absolutePath, { force: true });
+    return errorResponse(c, "UNREADABLE_MEDIA", "That file couldn't be read as an image or video.", 400);
+  }
+
+  const asset = await prisma.asset.create({
+    data: {
+      projectId: id,
+      kind: "media",
+      filePath: relativePath,
+      mimeType: contentType,
+      sizeBytes,
+      name: filename.slice(0, 200),
+      width: dimensions.width,
+      height: dimensions.height,
+      duration,
+    },
+  });
+  return c.json({ success: true, media: toMediaItem(id, asset) }, 201);
+});
+
+/** Serves a media file; Bun handles Range requests, so video seeks in the preview. */
+mediaRoute.get("/:id/media/:assetId/file", async (c) => {
+  const asset = await prisma.asset.findFirst({
+    where: { id: c.req.param("assetId"), projectId: c.req.param("id"), kind: "media" },
+  });
+  if (!asset) return errorResponse(c, "NOT_FOUND", "Media not found.", 404);
+  return new Response(Bun.file(resolveInDataDir(asset.filePath)), {
+    headers: { "Content-Type": asset.mimeType, "Accept-Ranges": "bytes" },
+  });
+});
+
+/**
+ * Deletes a media file -- unless B-roll on the timeline still uses it, so
+ * an export can never reference a missing file. The response lists how many
+ * uses to remove first.
+ */
+mediaRoute.delete("/:id/media/:assetId", async (c) => {
+  const projectId = c.req.param("id");
+  const assetId = c.req.param("assetId");
+  const asset = await prisma.asset.findFirst({ where: { id: assetId, projectId, kind: "media" } });
+  if (!asset) return errorResponse(c, "NOT_FOUND", "Media not found.", 404);
+
+  const ops = await prisma.editOperation.findMany({ where: { projectId, type: "overlay" } });
+  const uses = ops.filter((op) => (JSON.parse(op.dataJson) as EditOperation & { assetId?: string }).assetId === assetId);
+  if (uses.length > 0) {
+    return errorResponse(
+      c,
+      "MEDIA_IN_USE",
+      `This file is used as B-roll ${uses.length === 1 ? "once" : `${uses.length} times`} -- remove that first.`,
+      409
+    );
+  }
+
+  await prisma.asset.delete({ where: { id: asset.id } });
+  await rm(resolveInDataDir(asset.filePath), { force: true });
+  return c.json({ success: true });
+});

From b827b1d98d0c2baffcc537230d7f219b58cd2731 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:00:19 +0530
Subject: [PATCH 23/36] feat: add an overlay operation for B-roll

An overlay shows a media-library file over the footage from start to end
in source time, so it follows cuts, either full screen or picture-in-
picture in a corner, optionally from an offset into a clip. The route
checks the file is in this project's library and the range is inside the
video; asset ids must be plain ids.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/types/edit-operation.ts            | 23 +++++++++++++++++++
 .../src/lib/validation/edit-operation.test.ts | 15 ++++++++++++
 server/src/lib/validation/edit-operation.ts   | 14 +++++++++++
 server/src/routes/operations.ts               | 11 ++++++++-
 server/src/types/edit-operation.ts            | 23 +++++++++++++++++++
 5 files changed, 85 insertions(+), 1 deletion(-)

diff --git a/client/src/types/edit-operation.ts b/client/src/types/edit-operation.ts
index 4856e39..fca20a5 100644
--- a/client/src/types/edit-operation.ts
+++ b/client/src/types/edit-operation.ts
@@ -65,6 +65,23 @@ export type EditOperation =
       /** Seconds for the whole transition (a dip spends half going out, half coming in). */
       duration: number;
     })
+  | (OperationBase & {
+      /**
+       * B-roll: an image or video from the project's media library shown
+       * over the footage from `start` to `end` (source time, so it follows
+       * cuts), full screen or picture-in-picture. The footage's audio keeps
+       * playing; the B-roll's own audio is not used.
+       */
+      type: "overlay";
+      assetId: string;
+      start: number;
+      end: number;
+      mode: OverlayMode;
+      /** Picture-in-picture only. */
+      corner?: OverlayCorner;
+      /** Seconds into a video asset to start from. */
+      offset?: number;
+    })
   | (OperationBase & {
       type: "caption";
       text: string;
@@ -89,7 +106,13 @@ export type TransitionKind = (typeof TRANSITION_KINDS)[number];
 export const TRANSITION_MIN_SECONDS = 0.2;
 export const TRANSITION_MAX_SECONDS = 2;
 
+export const OVERLAY_MODES = ["full", "pip"] as const;
+export type OverlayMode = (typeof OVERLAY_MODES)[number];
+export const OVERLAY_CORNERS = ["top-left", "top-right", "bottom-left", "bottom-right"] as const;
+export type OverlayCorner = (typeof OVERLAY_CORNERS)[number];
+
 export type CutOperation = Extract<EditOperation, { type: "cut" }>;
 export type SplitOperation = Extract<EditOperation, { type: "split" }>;
 export type CardOperation = Extract<EditOperation, { type: "card" }>;
 export type TransitionOperation = Extract<EditOperation, { type: "transition" }>;
+export type OverlayOperation = Extract<EditOperation, { type: "overlay" }>;
diff --git a/server/src/lib/validation/edit-operation.test.ts b/server/src/lib/validation/edit-operation.test.ts
index 6acd5b6..8cde1a0 100644
--- a/server/src/lib/validation/edit-operation.test.ts
+++ b/server/src/lib/validation/edit-operation.test.ts
@@ -144,4 +144,19 @@ describe("editOperationSchema", () => {
       expect(editOperationSchema.safeParse({ ...transition, duration: 5 }).success).toBe(false);
     });
   });
+
+  describe("overlay", () => {
+    const overlay = { id: "o1", type: "overlay", assetId: "cmabc123", start: 10, end: 15, mode: "pip", corner: "top-right", createdAt: 0 };
+
+    it("accepts full-screen and picture-in-picture B-roll", () => {
+      expect(editOperationSchema.safeParse(overlay).success).toBe(true);
+      expect(editOperationSchema.safeParse({ ...overlay, mode: "full", corner: undefined, offset: 2.5 }).success).toBe(true);
+    });
+
+    it("rejects unknown modes and corners, and asset ids that aren't plain ids", () => {
+      expect(editOperationSchema.safeParse({ ...overlay, mode: "split" }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...overlay, corner: "middle" }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...overlay, assetId: "../../etc/passwd" }).success).toBe(false);
+    });
+  });
 });
diff --git a/server/src/lib/validation/edit-operation.ts b/server/src/lib/validation/edit-operation.ts
index 1cd6655..5251dd1 100644
--- a/server/src/lib/validation/edit-operation.ts
+++ b/server/src/lib/validation/edit-operation.ts
@@ -5,6 +5,8 @@ import {
   CARD_SUBTITLE_MAX,
   CARD_TEMPLATES,
   CARD_TITLE_MAX,
+  OVERLAY_CORNERS,
+  OVERLAY_MODES,
   TRANSITION_KINDS,
   TRANSITION_MAX_SECONDS,
   TRANSITION_MIN_SECONDS,
@@ -78,6 +80,18 @@ export const editOperationSchema = z.discriminatedUnion("type", [
     createdAt: z.number(),
     groupId: z.string().min(1).max(100).optional(),
   }),
+  z.object({
+    id: z.string().min(1),
+    type: z.literal("overlay"),
+    assetId: z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/),
+    start: z.number().nonnegative(),
+    end: z.number().nonnegative(),
+    mode: z.enum(OVERLAY_MODES),
+    corner: z.enum(OVERLAY_CORNERS).optional(),
+    offset: z.number().nonnegative().optional(),
+    createdAt: z.number(),
+    groupId: z.string().min(1).max(100).optional(),
+  }),
   z.object({
     id: z.string().min(1),
     type: z.literal("caption"),
diff --git a/server/src/routes/operations.ts b/server/src/routes/operations.ts
index a433f7c..3353f65 100644
--- a/server/src/routes/operations.ts
+++ b/server/src/routes/operations.ts
@@ -21,7 +21,7 @@ operationsRoute.post("/:id/operations", async (c) => {
   }
 
   const op = parsed.data;
-  if ((op.type === "cut" || op.type === "trim") && op.end <= op.start) {
+  if ((op.type === "cut" || op.type === "trim" || op.type === "overlay") && op.end <= op.start) {
     return errorResponse(c, "INVALID_OPERATION", "end must be after start.", 400);
   }
 
@@ -40,6 +40,15 @@ operationsRoute.post("/:id/operations", async (c) => {
   if (op.type === "transition" && project.duration && op.at > project.duration) {
     return errorResponse(c, "INVALID_OPERATION", "Transition must be placed inside the video.", 400);
   }
+  if (op.type === "overlay") {
+    if (project.duration && op.end > project.duration + 0.01) {
+      return errorResponse(c, "INVALID_OPERATION", "B-roll must end inside the video.", 400);
+    }
+    const asset = await prisma.asset.findFirst({ where: { id: op.assetId, projectId, kind: "media" } });
+    if (!asset) {
+      return errorResponse(c, "INVALID_OPERATION", "That media file isn't in this project's library.", 400);
+    }
+  }
 
   // Client generates the id (needed so undo/redo can address the exact row);
   // upsert so a redo that restores a previously-undone op is idempotent.
diff --git a/server/src/types/edit-operation.ts b/server/src/types/edit-operation.ts
index 4856e39..fca20a5 100644
--- a/server/src/types/edit-operation.ts
+++ b/server/src/types/edit-operation.ts
@@ -65,6 +65,23 @@ export type EditOperation =
       /** Seconds for the whole transition (a dip spends half going out, half coming in). */
       duration: number;
     })
+  | (OperationBase & {
+      /**
+       * B-roll: an image or video from the project's media library shown
+       * over the footage from `start` to `end` (source time, so it follows
+       * cuts), full screen or picture-in-picture. The footage's audio keeps
+       * playing; the B-roll's own audio is not used.
+       */
+      type: "overlay";
+      assetId: string;
+      start: number;
+      end: number;
+      mode: OverlayMode;
+      /** Picture-in-picture only. */
+      corner?: OverlayCorner;
+      /** Seconds into a video asset to start from. */
+      offset?: number;
+    })
   | (OperationBase & {
       type: "caption";
       text: string;
@@ -89,7 +106,13 @@ export type TransitionKind = (typeof TRANSITION_KINDS)[number];
 export const TRANSITION_MIN_SECONDS = 0.2;
 export const TRANSITION_MAX_SECONDS = 2;
 
+export const OVERLAY_MODES = ["full", "pip"] as const;
+export type OverlayMode = (typeof OVERLAY_MODES)[number];
+export const OVERLAY_CORNERS = ["top-left", "top-right", "bottom-left", "bottom-right"] as const;
+export type OverlayCorner = (typeof OVERLAY_CORNERS)[number];
+
 export type CutOperation = Extract<EditOperation, { type: "cut" }>;
 export type SplitOperation = Extract<EditOperation, { type: "split" }>;
 export type CardOperation = Extract<EditOperation, { type: "card" }>;
 export type TransitionOperation = Extract<EditOperation, { type: "transition" }>;
+export type OverlayOperation = Extract<EditOperation, { type: "overlay" }>;

From 83662bb4716186321ac5640b6a545516a5c29d48 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:00:19 +0530
Subject: [PATCH 24/36] feat: place B-roll on the program timeline

B-roll maps through cuts (a partly cut range shortens it, a fully cut
one drops it) and past title cards like a caption does, starting after a
card at its start and ending before one at its end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/lib/timeline/program.test.ts | 35 ++++++++++++++++++
 client/src/lib/timeline/program.ts      | 49 ++++++++++++++++++++++++-
 server/src/lib/timeline/program.test.ts | 35 ++++++++++++++++++
 server/src/lib/timeline/program.ts      | 49 ++++++++++++++++++++++++-
 4 files changed, 164 insertions(+), 4 deletions(-)

diff --git a/client/src/lib/timeline/program.test.ts b/client/src/lib/timeline/program.test.ts
index c761430..ca1f694 100644
--- a/client/src/lib/timeline/program.test.ts
+++ b/client/src/lib/timeline/program.test.ts
@@ -3,6 +3,7 @@ import {
   buildProgram,
   buildProgramItems,
   isPlainProgram,
+  placeOverlays,
   cardStartTimes,
   cardsDuration,
   editedRangeToProgram,
@@ -192,3 +193,37 @@ describe("transitions", () => {
     expect(p.joins[0]).toMatchObject({ kind: "dip" });
   });
 });
+
+describe("placeOverlays", () => {
+  const overlay = (id: string, start: number, end: number): EditOperation => ({
+    id,
+    type: "overlay",
+    assetId: "a1",
+    start,
+    end,
+    mode: "full",
+    createdAt: 0,
+  });
+  const place = (ops: EditOperation[]) => {
+    const ranges = computePlayableRanges(
+      100,
+      ops.filter((op): op is CutOperation => op.type === "cut")
+    );
+    return placeOverlays(ops, ranges, placeCards(ops, ranges, 100)).map((p) => [p.overlay.id, p.start, p.end]);
+  };
+
+  it("maps B-roll through cuts and past earlier cards", () => {
+    expect(place([cut(0, 10), card("intro", 0, 2), overlay("b", 20, 25)])).toEqual([["b", 12, 17]]);
+  });
+
+  it("shortens B-roll whose range was partly cut, and drops it when cut entirely", () => {
+    expect(place([cut(22, 24), overlay("part", 20, 25), overlay("gone", 50, 55), cut(49, 56)])).toEqual([
+      ["part", 20, 23],
+    ]);
+  });
+
+  it("doesn't run over a card at its start or end", () => {
+    expect(place([card("mid", 40, 3), overlay("b", 40, 45)])).toEqual([["b", 43, 48]]);
+    expect(place([card("mid", 40, 3), overlay("b", 35, 40)])).toEqual([["b", 35, 40]]);
+  });
+});
diff --git a/client/src/lib/timeline/program.ts b/client/src/lib/timeline/program.ts
index fb82434..724ada4 100644
--- a/client/src/lib/timeline/program.ts
+++ b/client/src/lib/timeline/program.ts
@@ -1,4 +1,10 @@
-import type { CardOperation, EditOperation, SplitOperation, TransitionOperation } from "@/types/edit-operation";
+import type {
+  CardOperation,
+  EditOperation,
+  OverlayOperation,
+  SplitOperation,
+  TransitionOperation,
+} from "@/types/edit-operation";
 import type { PlayableRange } from "@/types/timeline";
 import { nextPlayableTime, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
 
@@ -284,8 +290,40 @@ export type Program = {
   joins: Join[];
   fadeIn: Fade | null;
   fadeOut: Fade | null;
+  overlays: PlacedOverlay[];
 };
 
+/** B-roll on the program timeline. */
+export type PlacedOverlay = { overlay: OverlayOperation; start: number; end: number };
+
+/** Shorter than this after cuts, B-roll would only flash on screen, so it's dropped. */
+const MIN_OVERLAY_SECONDS = 0.1;
+
+/**
+ * Places B-roll on the program timeline. Its source range follows cuts:
+ * cutting part of it shortens it, cutting all of it drops it. It starts
+ * after a card at its start moment and ends before one at its end, like a
+ * caption, so it never covers a title card at its edges.
+ */
+export function placeOverlays(
+  operations: EditOperation[],
+  ranges: PlayableRange[],
+  slots: CardSlot[]
+): PlacedOverlay[] {
+  return operations
+    .filter((op): op is OverlayOperation => op.type === "overlay")
+    .map((overlay) => ({
+      overlay,
+      ...editedRangeToProgram(
+        sourceTimeToEditedTime(overlay.start, ranges),
+        sourceTimeToEditedTime(overlay.end, ranges),
+        slots
+      ),
+    }))
+    .filter((p) => p.end - p.start >= MIN_OVERLAY_SECONDS)
+    .sort((a, b) => a.start - b.start || a.overlay.createdAt - b.overlay.createdAt);
+}
+
 export function buildProgram(operations: EditOperation[], ranges: PlayableRange[], sourceDuration: number): Program {
   const slots = placeCards(operations, ranges, sourceDuration);
   const { markers, fadeIn, fadeOut } = placeTransitions(operations, ranges, sourceDuration);
@@ -294,7 +332,14 @@ export function buildProgram(operations: EditOperation[], ranges: PlayableRange[
     slots,
     markers.map((m) => m.editedAt)
   );
-  return { slots, items, joins: resolveJoins(items, markers), fadeIn, fadeOut };
+  return {
+    slots,
+    items,
+    joins: resolveJoins(items, markers),
+    fadeIn,
+    fadeOut,
+    overlays: placeOverlays(operations, ranges, slots),
+  };
 }
 
 /** True when the program is just the playable ranges, cut together as always. */
diff --git a/server/src/lib/timeline/program.test.ts b/server/src/lib/timeline/program.test.ts
index c761430..ca1f694 100644
--- a/server/src/lib/timeline/program.test.ts
+++ b/server/src/lib/timeline/program.test.ts
@@ -3,6 +3,7 @@ import {
   buildProgram,
   buildProgramItems,
   isPlainProgram,
+  placeOverlays,
   cardStartTimes,
   cardsDuration,
   editedRangeToProgram,
@@ -192,3 +193,37 @@ describe("transitions", () => {
     expect(p.joins[0]).toMatchObject({ kind: "dip" });
   });
 });
+
+describe("placeOverlays", () => {
+  const overlay = (id: string, start: number, end: number): EditOperation => ({
+    id,
+    type: "overlay",
+    assetId: "a1",
+    start,
+    end,
+    mode: "full",
+    createdAt: 0,
+  });
+  const place = (ops: EditOperation[]) => {
+    const ranges = computePlayableRanges(
+      100,
+      ops.filter((op): op is CutOperation => op.type === "cut")
+    );
+    return placeOverlays(ops, ranges, placeCards(ops, ranges, 100)).map((p) => [p.overlay.id, p.start, p.end]);
+  };
+
+  it("maps B-roll through cuts and past earlier cards", () => {
+    expect(place([cut(0, 10), card("intro", 0, 2), overlay("b", 20, 25)])).toEqual([["b", 12, 17]]);
+  });
+
+  it("shortens B-roll whose range was partly cut, and drops it when cut entirely", () => {
+    expect(place([cut(22, 24), overlay("part", 20, 25), overlay("gone", 50, 55), cut(49, 56)])).toEqual([
+      ["part", 20, 23],
+    ]);
+  });
+
+  it("doesn't run over a card at its start or end", () => {
+    expect(place([card("mid", 40, 3), overlay("b", 40, 45)])).toEqual([["b", 43, 48]]);
+    expect(place([card("mid", 40, 3), overlay("b", 35, 40)])).toEqual([["b", 35, 40]]);
+  });
+});
diff --git a/server/src/lib/timeline/program.ts b/server/src/lib/timeline/program.ts
index fb82434..724ada4 100644
--- a/server/src/lib/timeline/program.ts
+++ b/server/src/lib/timeline/program.ts
@@ -1,4 +1,10 @@
-import type { CardOperation, EditOperation, SplitOperation, TransitionOperation } from "@/types/edit-operation";
+import type {
+  CardOperation,
+  EditOperation,
+  OverlayOperation,
+  SplitOperation,
+  TransitionOperation,
+} from "@/types/edit-operation";
 import type { PlayableRange } from "@/types/timeline";
 import { nextPlayableTime, sourceTimeToEditedTime } from "@/lib/timeline/cuts";
 
@@ -284,8 +290,40 @@ export type Program = {
   joins: Join[];
   fadeIn: Fade | null;
   fadeOut: Fade | null;
+  overlays: PlacedOverlay[];
 };
 
+/** B-roll on the program timeline. */
+export type PlacedOverlay = { overlay: OverlayOperation; start: number; end: number };
+
+/** Shorter than this after cuts, B-roll would only flash on screen, so it's dropped. */
+const MIN_OVERLAY_SECONDS = 0.1;
+
+/**
+ * Places B-roll on the program timeline. Its source range follows cuts:
+ * cutting part of it shortens it, cutting all of it drops it. It starts
+ * after a card at its start moment and ends before one at its end, like a
+ * caption, so it never covers a title card at its edges.
+ */
+export function placeOverlays(
+  operations: EditOperation[],
+  ranges: PlayableRange[],
+  slots: CardSlot[]
+): PlacedOverlay[] {
+  return operations
+    .filter((op): op is OverlayOperation => op.type === "overlay")
+    .map((overlay) => ({
+      overlay,
+      ...editedRangeToProgram(
+        sourceTimeToEditedTime(overlay.start, ranges),
+        sourceTimeToEditedTime(overlay.end, ranges),
+        slots
+      ),
+    }))
+    .filter((p) => p.end - p.start >= MIN_OVERLAY_SECONDS)
+    .sort((a, b) => a.start - b.start || a.overlay.createdAt - b.overlay.createdAt);
+}
+
 export function buildProgram(operations: EditOperation[], ranges: PlayableRange[], sourceDuration: number): Program {
   const slots = placeCards(operations, ranges, sourceDuration);
   const { markers, fadeIn, fadeOut } = placeTransitions(operations, ranges, sourceDuration);
@@ -294,7 +332,14 @@ export function buildProgram(operations: EditOperation[], ranges: PlayableRange[
     slots,
     markers.map((m) => m.editedAt)
   );
-  return { slots, items, joins: resolveJoins(items, markers), fadeIn, fadeOut };
+  return {
+    slots,
+    items,
+    joins: resolveJoins(items, markers),
+    fadeIn,
+    fadeOut,
+    overlays: placeOverlays(operations, ranges, slots),
+  };
 }
 
 /** True when the program is just the playable ranges, cut together as always. */

From c2ff1581dc63987b14ab4afba102058e93110a3e Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:00:19 +0530
Subject: [PATCH 25/36] feat(server): composite B-roll into exports

Each file is an extra ffmpeg input: an image looped for its slot, a clip
trimmed from its offset that holds its last frame if it runs short. It's
scaled to fill the frame or to a 32%-wide inset in its corner, shifted to
its program start, and overlaid only for its slot -- after the join and
grade, before any clip reframe, card text, captions and the logo, whose
input indices move past the B-roll. File paths only appear as -i
arguments, never inside the filtergraph. B-roll audio is never used.

Verified with ffmpeg 9.0.2: a 2s clip over a 4s slot and a picture-in-
picture image, around a cut and an intro card, land at their predicted
program times; the clip holds its last frame, and audio sync is
unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 server/src/lib/ffmpeg/plan.test.ts  |  68 ++++++++++++++++++
 server/src/lib/ffmpeg/plan.ts       | 105 +++++++++++++++++++++++++++-
 server/src/lib/ffmpeg/render-job.ts |  25 ++++++-
 3 files changed, 194 insertions(+), 4 deletions(-)

diff --git a/server/src/lib/ffmpeg/plan.test.ts b/server/src/lib/ffmpeg/plan.test.ts
index 1dd1cae..9d50435 100644
--- a/server/src/lib/ffmpeg/plan.test.ts
+++ b/server/src/lib/ffmpeg/plan.test.ts
@@ -522,3 +522,71 @@ describe("transitions", () => {
     ).toThrow(/joins/);
   });
 });
+
+describe("B-roll", () => {
+  const frame = { width: 1920, height: 1080 };
+  const video = {
+    path: "/data/media/clip.mp4",
+    image: false,
+    start: 12,
+    end: 17,
+    offset: 2,
+    mode: "full" as const,
+    corner: "top-right" as const,
+  };
+  const image = { ...video, path: "/data/media/photo.png", image: true, mode: "pip" as const, start: 30, end: 34 };
+  const render = (extra: Partial<Parameters<typeof buildRenderArgs>[0]> = {}) =>
+    buildRenderArgs({ ...baseArgs, broll: { frame, overlays: [video, image] }, ...extra });
+  const graphOf = (args: string[]) => args[args.indexOf("-filter_complex") + 1];
+
+  it("adds each file as an input after the source, looping images for their slot", () => {
+    const args = render();
+    expect(args.slice(0, 11)).toEqual([
+      "-y",
+      "-i",
+      "/data/in.mp4",
+      "-i",
+      "/data/media/clip.mp4",
+      "-loop",
+      "1",
+      "-t",
+      "4.500",
+      "-i",
+      "/data/media/photo.png",
+    ]);
+  });
+
+  it("trims video B-roll from its offset, holds its last frame, and fills the frame when full screen", () => {
+    expect(graphOf(render())).toContain(
+      "[1:v]trim=start=2.000:duration=5.000,setpts=PTS-STARTPTS,tpad=stop_mode=clone:stop_duration=5.000,scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080,setsar=1,setpts=PTS-STARTPTS+12.000/TB[broll0]"
+    );
+  });
+
+  it("shows each piece only in its slot, picture-in-picture in its corner", () => {
+    const g = graphOf(render());
+    expect(g).toContain("[outv][broll0]overlay=x=0:y=0:enable='between(t,12.000,17.000)':eof_action=pass[brolled0]");
+    expect(g).toContain("[2:v]scale=614:-2,setsar=1,setpts=PTS-STARTPTS+30.000/TB[broll1]");
+    expect(g).toContain(
+      "[brolled0][broll1]overlay=x=main_w-overlay_w-44:y=44:enable='between(t,30.000,34.000)':eof_action=pass[brolled1]"
+    );
+  });
+
+  it("shifts the logo and metadata inputs past the B-roll", () => {
+    const args = render({
+      logoPath: "/data/logo.png",
+      logoPosition: "bottom-right",
+      videoWidth: 1920,
+      videoHeight: 1080,
+      metadataPath: "/data/meta.ffmeta",
+    });
+    expect(graphOf(args)).toContain("[3:v]format=rgba");
+    expect(args[args.indexOf("-map_metadata") + 1]).toBe("4");
+  });
+
+  it("refuses bad timing or modes", () => {
+    expect(() => buildRenderArgs({ ...baseArgs, broll: { frame, overlays: [{ ...video, end: 12 }] } })).toThrow(/timing/);
+    expect(() =>
+      buildRenderArgs({ ...baseArgs, broll: { frame, overlays: [{ ...video, mode: "zoom" as "full" }] } })
+    ).toThrow(/mode/);
+  });
+});
diff --git a/server/src/lib/ffmpeg/plan.ts b/server/src/lib/ffmpeg/plan.ts
index b620698..122939b 100644
--- a/server/src/lib/ffmpeg/plan.ts
+++ b/server/src/lib/ffmpeg/plan.ts
@@ -1,5 +1,6 @@
 import type { PlayableRange } from "@/types/timeline";
 import type { Fade, Join, ProgramItem } from "@/lib/timeline/program";
+import { OVERLAY_CORNERS, type OverlayCorner, type OverlayMode } from "@/types/edit-operation";
 import { getFfmpegFilter } from "@/lib/ffmpeg/filters";
 import { buildPropertiesFilter } from "@/lib/ffmpeg/properties";
 import { buildForceStyle, type CaptionStyle } from "@/lib/captions/style";
@@ -345,6 +346,85 @@ export function buildAudioOnlyRenderArgs(args: {
   ];
 }
 
+/** One piece of B-roll to composite: a media file shown from `start` to `end` of the program. */
+export type RenderOverlay = {
+  /** Absolute path, already resolved inside DATA_DIR. */
+  path: string;
+  image: boolean;
+  start: number;
+  end: number;
+  /** Seconds into a video to start from. */
+  offset: number;
+  mode: OverlayMode;
+  corner: OverlayCorner;
+};
+
+/** Picture-in-picture width and inset, as fractions of the frame. */
+const PIP_WIDTH_FRACTION = 0.32;
+const PIP_INSET_FRACTION = 0.04;
+
+const even = (n: number) => Math.max(2, Math.round(n / 2) * 2);
+
+function assertValidOverlay(o: RenderOverlay): void {
+  if (!o.path) throw new Error("B-roll has no file.");
+  if (![o.start, o.end, o.offset].every(Number.isFinite) || o.start < 0 || o.end <= o.start || o.offset < 0) {
+    throw new Error("Invalid B-roll timing.");
+  }
+  if (o.mode !== "full" && o.mode !== "pip") throw new Error("Invalid B-roll mode.");
+  if (!(OVERLAY_CORNERS as readonly string[]).includes(o.corner)) throw new Error("Invalid B-roll corner.");
+}
+
+/**
+ * Input args and filter chains that composite B-roll onto `inputLabel`.
+ * Each file is an extra input (index firstInput + i): an image is looped
+ * for its slot, a video is trimmed from its offset and holds its last
+ * frame if it runs short. Each is scaled for its mode, shifted to its
+ * program start, and overlaid only between its start and end. Every value
+ * is a validated number or a fixed keyword; file paths only ever appear as
+ * -i arguments, never inside the filtergraph.
+ */
+function buildOverlayChains(
+  overlays: RenderOverlay[],
+  frame: { width: number; height: number },
+  inputLabel: string,
+  firstInput: number
+): { inputs: string[]; chains: string[]; outLabel: string } {
+  const { width, height } = frame;
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+    throw new Error(`Invalid B-roll frame size: ${width}x${height}`);
+  }
+  const pipWidth = even(width * PIP_WIDTH_FRACTION);
+  const inset = even(Math.min(width, height) * PIP_INSET_FRACTION);
+
+  const inputs: string[] = [];
+  const chains: string[] = [];
+  let label = inputLabel;
+  overlays.forEach((o, i) => {
+    assertValidOverlay(o);
+    const length = o.end - o.start;
+    const input = firstInput + i;
+    inputs.push(...(o.image ? ["-loop", "1", "-t", (length + 0.5).toFixed(3)] : []), "-i", o.path);
+
+    const scale =
+      o.mode === "full"
+        ? `scale=${width}:${height}:force_original_aspect_ratio=increase,crop=${width}:${height},setsar=1`
+        : `scale=${pipWidth}:-2,setsar=1`;
+    const source = o.image
+      ? `[${input}:v]${scale}`
+      : `[${input}:v]trim=start=${o.offset.toFixed(3)}:duration=${length.toFixed(3)},setpts=PTS-STARTPTS,tpad=stop_mode=clone:stop_duration=${length.toFixed(3)},${scale}`;
+    chains.push(`${source},setpts=PTS-STARTPTS+${o.start.toFixed(3)}/TB[broll${i}]`);
+
+    const x = o.mode === "full" ? "0" : o.corner.endsWith("left") ? String(inset) : `main_w-overlay_w-${inset}`;
+    const y = o.mode === "full" ? "0" : o.corner.startsWith("top") ? String(inset) : `main_h-overlay_h-${inset}`;
+    const next = `[brolled${i}]`;
+    chains.push(
+      `${label}[broll${i}]overlay=x=${x}:y=${y}:enable='between(t,${o.start.toFixed(3)},${o.end.toFixed(3)})':eof_action=pass${next}`
+    );
+    label = next;
+  });
+  return { inputs, chains, outLabel: label };
+}
+
 /**
  * Crop to the target aspect ratio (full height, sliding horizontally by
  * cropX, when the source is wider; full width, centered vertically, when it
@@ -445,6 +525,12 @@ export function buildRenderArgs(args: {
    */
   program?: RenderProgram;
   cardFrame?: { width: number; height: number; textPath: string };
+  /**
+   * B-roll to composite, on the program timeline, and the source frame
+   * size it's laid out on (applied before any reframe, so a clip crops
+   * B-roll with the footage).
+   */
+  broll?: { frame: { width: number; height: number }; overlays: RenderOverlay[] };
 }): string[] {
   const {
     inputPath,
@@ -467,6 +553,7 @@ export function buildRenderArgs(args: {
     frameRate,
     program,
     cardFrame,
+    broll,
   } = args;
 
   const layout = layoutProgram(playableRanges, program);
@@ -560,6 +647,17 @@ export function buildRenderArgs(args: {
     videoOutLabel = "[filtered]";
   }
 
+  // B-roll sits above the footage (ungraded, like the cards) and below
+  // card text, captions and the logo.
+  const brollInputs: string[] = [];
+  if (broll && broll.overlays.length > 0) {
+    const built = buildOverlayChains(broll.overlays, broll.frame, videoOutLabel, 1);
+    filterChains.push(...built.chains);
+    brollInputs.push(...built.inputs);
+    videoOutLabel = built.outLabel;
+  }
+  const logoInput = 1 + (broll?.overlays.length ?? 0);
+
   if (reframe) {
     filterChains.push(`${videoOutLabel}${buildReframeFilter(reframe)}[reframed]`);
     videoOutLabel = "[reframed]";
@@ -621,19 +719,20 @@ export function buildRenderArgs(args: {
     const maxLogoHeight = Math.round(videoHeight * LOGO_MAX_HEIGHT_FRACTION);
     const scaleFactor = `min(1,min(${maxLogoWidth}/iw,${maxLogoHeight}/ih))`;
     filterChains.push(
-      `[1:v]format=rgba,scale=w='trunc(iw*${scaleFactor}/2)*2':h='trunc(ih*${scaleFactor}/2)*2',colorchannelmixer=aa=${opacityFraction}[logosrc]`
+      `[${logoInput}:v]format=rgba,scale=w='trunc(iw*${scaleFactor}/2)*2':h='trunc(ih*${scaleFactor}/2)*2',colorchannelmixer=aa=${opacityFraction}[logosrc]`
     );
     filterChains.push(`${videoOutLabel}[logosrc]overlay=x=${x}:y=${y}[logoed]`);
     videoOutLabel = "[logoed]";
   }
 
-  // The metadata file is the last input: after the source and, if present, the logo.
-  const metadataInputIndex = String(logoPath && logoPosition ? 2 : 1);
+  // The metadata file is the last input: after the source, any B-roll and the logo.
+  const metadataInputIndex = String(logoPath && logoPosition ? logoInput + 1 : logoInput);
 
   return [
     "-y",
     "-i",
     inputPath,
+    ...brollInputs,
     ...(logoPath && logoPosition ? ["-i", logoPath] : []),
     ...(metadataPath ? ["-i", metadataPath] : []),
     "-filter_complex",
diff --git a/server/src/lib/ffmpeg/render-job.ts b/server/src/lib/ffmpeg/render-job.ts
index e87bc05..c57f98c 100644
--- a/server/src/lib/ffmpeg/render-job.ts
+++ b/server/src/lib/ffmpeg/render-job.ts
@@ -22,7 +22,7 @@ import {
 } from "@/lib/ffmpeg/audio-filters";
 import { parseStoredAudioSettings } from "@/lib/validation/audio-settings";
 import { runFfmpeg, runFfmpegCapturingStderr } from "@/lib/ffmpeg/run";
-import type { RenderProgram } from "@/lib/ffmpeg/plan";
+import type { RenderOverlay, RenderProgram } from "@/lib/ffmpeg/plan";
 import { probeVideoStream } from "@/lib/ffmpeg/probe";
 import {
   buildProgram,
@@ -30,6 +30,7 @@ import {
   cardsDuration,
   editedRangeToProgram,
   isPlainProgram,
+  placeOverlays,
   type CardSlot,
 } from "@/lib/timeline/program";
 import { toCardsAss } from "@/lib/cards/ass";
@@ -233,6 +234,24 @@ export async function runRenderJob(
 
     // Title cards are generated at the source's own size so they join it seamlessly.
     let cardFrame: { width: number; height: number; textPath: string } | undefined;
+    // B-roll plays in clips too (it's part of the edit inside the clip's range).
+    const placedOverlays = built?.overlays ?? placeOverlays(operations, playableRanges, []);
+    const brollOverlays: RenderOverlay[] = placedOverlays.flatMap(({ overlay, start, end }) => {
+      const asset = project.assets.find((a) => a.id === overlay.assetId && a.kind === "media");
+      if (!asset) return [];
+      return [
+        {
+          path: resolveInDataDir(asset.filePath),
+          image: asset.mimeType.startsWith("image/"),
+          start,
+          end,
+          offset: overlay.offset ?? 0,
+          mode: overlay.mode,
+          corner: overlay.corner ?? "bottom-right",
+        },
+      ];
+    });
+
     if (program && cardSlots.length > 0 && sourceStream) {
       const textPath = resolveInDataDir(path.posix.join("projects", project.id, "render", `${jobId}.cards.ass`));
       await writeFile(textPath, toCardsAss(cardStartTimes(program.items), sourceStream), "utf-8");
@@ -309,6 +328,10 @@ export async function runRenderJob(
           frameRate: sourceStream!.fps,
           program,
           cardFrame,
+          broll:
+            sourceStream && brollOverlays.length > 0
+              ? { frame: { width: sourceStream.width, height: sourceStream.height }, overlays: brollOverlays }
+              : undefined,
         })
       : buildAudioOnlyRenderArgs({ inputPath, outputPath, playableRanges, program, audioFilter, format, metadataPath });
     await runFfmpeg(args);

From accb65128fc87e315eaabed56d7dc66784b03e13 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:00:19 +0530
Subject: [PATCH 26/36] feat(client): Media panel to upload and place B-roll

Upload images and clips (with progress), then add one as B-roll: over
the words selected in the transcript, or from the playhead. The panel
lists the B-roll in use, where full screen / picture-in-picture and the
corner can be changed; each change is one undo step. Deleting a file
that's in use shows why it can't be removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/components/editor/EditorHydrator.tsx  |   3 +
 .../src/components/editor/EditorSidebar.tsx   |   7 +-
 client/src/components/editor/MediaPanel.tsx   | 288 ++++++++++++++++++
 client/src/stores/media-store.ts              |  61 ++++
 client/src/types/media.ts                     |  13 +
 5 files changed, 370 insertions(+), 2 deletions(-)
 create mode 100644 client/src/components/editor/MediaPanel.tsx
 create mode 100644 client/src/stores/media-store.ts
 create mode 100644 client/src/types/media.ts

diff --git a/client/src/components/editor/EditorHydrator.tsx b/client/src/components/editor/EditorHydrator.tsx
index 1c90dca..b925b01 100644
--- a/client/src/components/editor/EditorHydrator.tsx
+++ b/client/src/components/editor/EditorHydrator.tsx
@@ -5,6 +5,7 @@ import { useProjectStore } from "@/stores/project-store";
 import { useTranscriptStore } from "@/stores/transcript-store";
 import { useTimelineStore } from "@/stores/timeline-store";
 import { useCaptionStyleStore } from "@/stores/caption-style-store";
+import { useMediaStore } from "@/stores/media-store";
 import { EditorLayout } from "@/components/editor/EditorLayout";
 import type { Transcript } from "@/types/transcript";
 import type { EditOperation } from "@/types/edit-operation";
@@ -44,12 +45,14 @@ export function EditorHydrator({
   const setTranscript = useTranscriptStore((s) => s.setTranscript);
   const hydrateTimeline = useTimelineStore((s) => s.hydrate);
   const hydrateCaptionStyle = useCaptionStyleStore((s) => s.hydrate);
+  const loadMedia = useMediaStore((s) => s.load);
 
   useEffect(() => {
     hydrateProject(project);
     setTranscript(transcript);
     hydrateTimeline(project.id, operations);
     hydrateCaptionStyle(project.id, project.burnInCaptions, project.captionStyle);
+    void loadMedia(project.id);
     // Only re-hydrate when navigating to a different project.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [project.id]);
diff --git a/client/src/components/editor/EditorSidebar.tsx b/client/src/components/editor/EditorSidebar.tsx
index 49e6d6e..ad57deb 100644
--- a/client/src/components/editor/EditorSidebar.tsx
+++ b/client/src/components/editor/EditorSidebar.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useEffect, useRef, useState } from "react";
-import { AudioLines, BookOpenText, Captions, ChevronLeft, Clapperboard, ChevronRight, Film, ImagePlus, SlidersHorizontal, Sliders, Wand2 } from "lucide-react";
+import { AudioLines, BookOpenText, Captions, ChevronLeft, Clapperboard, ChevronRight, Film, Images, ImagePlus, SlidersHorizontal, Sliders, Wand2 } from "lucide-react";
 import { AiToolsPanel } from "@/components/editor/AiToolsPanel";
 import { FiltersPanel } from "@/components/editor/FiltersPanel";
 import { PropertiesPanel } from "@/components/editor/PropertiesPanel";
@@ -11,12 +11,14 @@ import { AudioPanel } from "@/components/editor/AudioPanel";
 import { PublishPanel } from "@/components/editor/PublishPanel";
 import { ClipsPanel } from "@/components/editor/ClipsPanel";
 import { ScenesPanel } from "@/components/editor/ScenesPanel";
+import { MediaPanel } from "@/components/editor/MediaPanel";
 
-type PanelId = "captions" | "scenes" | "audio" | "publish" | "clips" | "ai" | "filters" | "properties" | "elements";
+type PanelId = "captions" | "scenes" | "media" | "audio" | "publish" | "clips" | "ai" | "filters" | "properties" | "elements";
 
 const TABS: { id: PanelId; label: string; icon: typeof Wand2 }[] = [
   { id: "captions", label: "Captions", icon: Captions },
   { id: "scenes", label: "Scenes", icon: Film },
+  { id: "media", label: "Media", icon: Images },
   { id: "audio", label: "Audio", icon: AudioLines },
   { id: "publish", label: "Publish", icon: BookOpenText },
   { id: "clips", label: "Clips", icon: Clapperboard },
@@ -112,6 +114,7 @@ export function EditorSidebar() {
       <div className="flex-1 overflow-y-auto p-3">
         {activePanel === "captions" && <CaptionsPanel />}
         {activePanel === "scenes" && <ScenesPanel />}
+        {activePanel === "media" && <MediaPanel />}
         {activePanel === "audio" && <AudioPanel />}
         {activePanel === "publish" && <PublishPanel />}
         {activePanel === "clips" && <ClipsPanel />}
diff --git a/client/src/components/editor/MediaPanel.tsx b/client/src/components/editor/MediaPanel.tsx
new file mode 100644
index 0000000..dc2627b
--- /dev/null
+++ b/client/src/components/editor/MediaPanel.tsx
@@ -0,0 +1,288 @@
+"use client";
+
+import { useMemo, useRef, useState } from "react";
+import { Film, ImageIcon, Plus, Trash2, Upload, X } from "lucide-react";
+import { useMediaStore } from "@/stores/media-store";
+import { usePlayerStore } from "@/stores/player-store";
+import { useTimelineStore } from "@/stores/timeline-store";
+import { useTranscriptStore } from "@/stores/transcript-store";
+import { formatTimecode } from "@/lib/timeline/format";
+import { Button } from "@/components/ui/button";
+import {
+  OVERLAY_CORNERS,
+  type OverlayCorner,
+  type OverlayMode,
+  type OverlayOperation,
+} from "@/types/edit-operation";
+import type { MediaItem } from "@/types/media";
+
+/** How long new B-roll lasts when there's no transcript selection to cover. */
+const DEFAULT_IMAGE_SECONDS = 4;
+const DEFAULT_VIDEO_SECONDS = 5;
+
+const CORNER_LABELS: Record<OverlayCorner, string> = {
+  "top-left": "Top left",
+  "top-right": "Top right",
+  "bottom-left": "Bottom left",
+  "bottom-right": "Bottom right",
+};
+
+type Upload = { name: string; progress: number; error?: string };
+
+function MediaThumb({ item, className }: { item: MediaItem; className: string }) {
+  return item.type === "image" ? (
+    <img src={item.url} alt="" className={className} draggable={false} />
+  ) : (
+    // #t= makes the browser show a frame from just into the clip rather than a black first frame.
+    <video src={`${item.url}#t=0.5`} muted preload="metadata" className={className} />
+  );
+}
+
+/**
+ * The media library: upload images and clips, then lay them over the
+ * footage as B-roll -- over the words selected in the transcript, or from
+ * the playhead. Each use is an overlay operation, so it follows cuts and
+ * goes through undo/redo; the library refuses to delete a file in use.
+ */
+export function MediaPanel() {
+  const items = useMediaStore((s) => s.items);
+  const upload = useMediaStore((s) => s.upload);
+  const remove = useMediaStore((s) => s.remove);
+  const operations = useTimelineStore((s) => s.operations);
+  const addOperations = useTimelineStore((s) => s.addOperations);
+  const replaceOperation = useTimelineStore((s) => s.replaceOperation);
+  const removeOperations = useTimelineStore((s) => s.removeOperations);
+  const currentTime = usePlayerStore((s) => s.currentTime);
+  const duration = usePlayerStore((s) => s.duration);
+  const seek = usePlayerStore((s) => s.seek);
+  const transcript = useTranscriptStore((s) => s.transcript);
+  const selectedWordIds = useTranscriptStore((s) => s.selectedWordIds);
+  const clearSelection = useTranscriptStore((s) => s.clearSelection);
+
+  const fileInput = useRef<HTMLInputElement>(null);
+  const [uploads, setUploads] = useState<Upload[]>([]);
+  const [error, setError] = useState<string | null>(null);
+
+  const mediaById = useMemo(() => new Map(items.map((m) => [m.id, m])), [items]);
+  const overlays = useMemo(
+    () =>
+      operations
+        .filter((op): op is OverlayOperation => op.type === "overlay")
+        .sort((a, b) => a.start - b.start),
+    [operations]
+  );
+  const selection = useMemo(() => {
+    if (selectedWordIds.length === 0 || !transcript) return null;
+    const ids = new Set(selectedWordIds);
+    const words = transcript.segments.flatMap((s) => s.words).filter((w) => ids.has(w.id));
+    if (words.length === 0) return null;
+    return { start: Math.min(...words.map((w) => w.start)), end: Math.max(...words.map((w) => w.end)) };
+  }, [selectedWordIds, transcript]);
+
+  const handleFiles = async (files: FileList | null) => {
+    if (!files) return;
+    setError(null);
+    for (const file of Array.from(files)) {
+      setUploads((u) => [...u, { name: file.name, progress: 0 }]);
+      const update = (patch: Partial<Upload>) =>
+        setUploads((u) => u.map((x) => (x.name === file.name ? { ...x, ...patch } : x)));
+      try {
+        await upload(file, (progress) => update({ progress }));
+        setUploads((u) => u.filter((x) => x.name !== file.name));
+      } catch (err) {
+        update({ error: err instanceof Error ? err.message : "Upload failed." });
+      }
+    }
+  };
+
+  const addBroll = (item: MediaItem) => {
+    const range = selection ?? {
+      start: currentTime,
+      end: Math.min(
+        duration,
+        currentTime +
+          (item.type === "video" ? Math.min(DEFAULT_VIDEO_SECONDS, item.duration ?? DEFAULT_VIDEO_SECONDS) : DEFAULT_IMAGE_SECONDS)
+      ),
+    };
+    if (range.end - range.start < 0.2) {
+      setError("Move the playhead earlier -- there's no room for B-roll before the end.");
+      return;
+    }
+    const op: OverlayOperation = {
+      id: crypto.randomUUID(),
+      type: "overlay",
+      assetId: item.id,
+      start: range.start,
+      end: range.end,
+      mode: "full",
+      createdAt: Date.now(),
+    };
+    addOperations([op]);
+    if (selection) clearSelection();
+    setError(null);
+  };
+
+  const update = (op: OverlayOperation, patch: { mode?: OverlayMode; corner?: OverlayCorner }) =>
+    replaceOperation(op.id, { ...op, ...patch, id: crypto.randomUUID() });
+
+  const deleteMedia = async (item: MediaItem) => {
+    try {
+      await remove(item.id);
+      setError(null);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Couldn't delete that file.");
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-3 text-xs">
+      <input
+        ref={fileInput}
+        type="file"
+        multiple
+        accept="image/png,image/jpeg,image/webp,video/*"
+        className="hidden"
+        onChange={(e) => {
+          void handleFiles(e.target.files);
+          e.target.value = "";
+        }}
+      />
+      <Button size="sm" onClick={() => fileInput.current?.click()}>
+        <Upload className="size-3.5" />
+        Upload images or clips
+      </Button>
+      <p className="text-muted-foreground">
+        {selection
+          ? `Adding covers the ${selectedWordIds.length} selected word${selectedWordIds.length === 1 ? "" : "s"} (${formatTimecode(selection.start)}–${formatTimecode(selection.end)}).`
+          : "Adding starts at the playhead. Select words in the transcript to cover exactly them."}
+      </p>
+
+      {uploads.map((u) => (
+        <div key={u.name} className="flex items-center gap-2 rounded-md border border-border p-2">
+          <span className="min-w-0 flex-1 truncate">{u.name}</span>
+          {u.error ? (
+            <>
+              <span className="text-destructive">{u.error}</span>
+              <button type="button" onClick={() => setUploads((x) => x.filter((y) => y !== u))} title="Dismiss">
+                <X className="size-3" />
+              </button>
+            </>
+          ) : (
+            <span className="font-mono tabular-nums text-muted-foreground">{Math.round(u.progress * 100)}%</span>
+          )}
+        </div>
+      ))}
+      {error && <p className="rounded-md bg-destructive/10 p-2 text-destructive">{error}</p>}
+
+      {items.length === 0 ? (
+        <p className="rounded-lg border border-dashed border-border p-3 text-muted-foreground">
+          No media yet. Upload product shots, screen recordings or photos to cut away to while the conversation keeps
+          playing.
+        </p>
+      ) : (
+        <div className="grid grid-cols-2 gap-2">
+          {items.map((item) => (
+            <div key={item.id} className="group relative overflow-hidden rounded-md border border-border">
+              <MediaThumb item={item} className="aspect-video w-full bg-muted object-cover" />
+              <div className="flex items-center gap-1 px-1.5 py-1">
+                {item.type === "image" ? (
+                  <ImageIcon className="size-3 shrink-0 text-muted-foreground" />
+                ) : (
+                  <Film className="size-3 shrink-0 text-muted-foreground" />
+                )}
+                <span className="min-w-0 flex-1 truncate" title={item.name}>
+                  {item.name}
+                </span>
+                {item.duration !== null && (
+                  <span className="font-mono text-muted-foreground tabular-nums">{formatTimecode(item.duration)}</span>
+                )}
+              </div>
+              <div className="absolute inset-x-0 top-0 flex justify-between p-1 opacity-0 transition-opacity group-hover:opacity-100 focus-within:opacity-100">
+                <Button size="xs" onClick={() => addBroll(item)} title="Use as B-roll">
+                  <Plus className="size-3" />
+                  Add
+                </Button>
+                <Button
+                  variant="secondary"
+                  size="icon-xs"
+                  onClick={() => void deleteMedia(item)}
+                  title="Delete from library"
+                  className="hover:text-destructive"
+                >
+                  <Trash2 className="size-3" />
+                </Button>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {overlays.length > 0 && (
+        <div className="flex flex-col gap-1.5">
+          <span className="text-muted-foreground">B-roll on the timeline</span>
+          {overlays.map((op) => {
+            const item = mediaById.get(op.assetId);
+            return (
+              <div key={op.id} className="flex flex-col gap-1.5 rounded-md border border-border p-1.5">
+                <div className="flex items-center gap-2">
+                  <button type="button" onClick={() => seek(op.start)} title="Jump to it" className="shrink-0">
+                    {item ? (
+                      <MediaThumb item={item} className="h-8 w-14 rounded-sm bg-muted object-cover" />
+                    ) : (
+                      <span className="block h-8 w-14 rounded-sm bg-muted" />
+                    )}
+                  </button>
+                  <div className="min-w-0 flex-1">
+                    <div className="truncate">{item?.name ?? "Missing file"}</div>
+                    <div className="font-mono text-muted-foreground tabular-nums">
+                      {formatTimecode(op.start)}–{formatTimecode(op.end)}
+                    </div>
+                  </div>
+                  <Button
+                    variant="ghost"
+                    size="icon-xs"
+                    onClick={() => removeOperations([op.id])}
+                    title="Remove this B-roll"
+                    className="hover:text-destructive"
+                  >
+                    <X className="size-3" />
+                  </Button>
+                </div>
+                <div className="flex items-center gap-1">
+                  {(["full", "pip"] as const).map((mode) => (
+                    <button
+                      key={mode}
+                      type="button"
+                      onClick={() => op.mode !== mode && update(op, { mode })}
+                      className={`rounded border px-1.5 py-0.5 text-[0.7rem] ${
+                        op.mode === mode
+                          ? "border-primary bg-primary/15 text-primary"
+                          : "border-border text-muted-foreground hover:text-foreground"
+                      }`}
+                    >
+                      {mode === "full" ? "Full screen" : "Picture in picture"}
+                    </button>
+                  ))}
+                  {op.mode === "pip" && (
+                    <select
+                      value={op.corner ?? "bottom-right"}
+                      onChange={(e) => update(op, { corner: e.target.value as OverlayCorner })}
+                      aria-label="Corner"
+                      className="h-6 min-w-0 flex-1 rounded border border-border bg-transparent px-1 text-[0.7rem] focus:border-primary focus:outline-none"
+                    >
+                      {OVERLAY_CORNERS.map((c) => (
+                        <option key={c} value={c}>
+                          {CORNER_LABELS[c]}
+                        </option>
+                      ))}
+                    </select>
+                  )}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/client/src/stores/media-store.ts b/client/src/stores/media-store.ts
new file mode 100644
index 0000000..ffa2443
--- /dev/null
+++ b/client/src/stores/media-store.ts
@@ -0,0 +1,61 @@
+import { create } from "zustand";
+import type { MediaItem } from "@/types/media";
+
+type ApiError = { success: false; error: { message: string } };
+
+type MediaStore = {
+  projectId: string | null;
+  items: MediaItem[];
+  load: (projectId: string) => Promise<void>;
+  /** Uploads one file (raw body, like the main video upload), reporting progress 0-1. */
+  upload: (file: File, onProgress: (fraction: number) => void) => Promise<MediaItem>;
+  /** Throws with the server's message, e.g. when B-roll still uses the file. */
+  remove: (id: string) => Promise<void>;
+};
+
+/** The project's media library: images and clips used as B-roll. */
+export const useMediaStore = create<MediaStore>((set, get) => ({
+  projectId: null,
+  items: [],
+
+  load: async (projectId) => {
+    set({ projectId, items: [] });
+    const res = await fetch(`/api/projects/${projectId}/media`);
+    const data: { success: true; media: MediaItem[] } | ApiError = await res.json();
+    if (data.success && get().projectId === projectId) set({ items: data.media });
+  },
+
+  upload: (file, onProgress) =>
+    new Promise((resolve, reject) => {
+      const { projectId } = get();
+      if (!projectId) return reject(new Error("No project loaded."));
+      const xhr = new XMLHttpRequest();
+      xhr.open("POST", `/api/projects/${projectId}/media?filename=${encodeURIComponent(file.name)}`);
+      xhr.setRequestHeader("Content-Type", file.type || "application/octet-stream");
+      xhr.upload.onprogress = (e) => {
+        if (e.lengthComputable) onProgress(e.loaded / e.total);
+      };
+      xhr.onload = () => {
+        let data: { success: true; media: MediaItem } | ApiError;
+        try {
+          data = JSON.parse(xhr.responseText);
+        } catch {
+          return reject(new Error("Upload failed."));
+        }
+        if (!data.success) return reject(new Error(data.error.message));
+        set((s) => ({ items: [...s.items, data.media] }));
+        resolve(data.media);
+      };
+      xhr.onerror = () => reject(new Error("Upload failed -- is the server running?"));
+      xhr.send(file);
+    }),
+
+  remove: async (id) => {
+    const { projectId } = get();
+    if (!projectId) return;
+    const res = await fetch(`/api/projects/${projectId}/media/${id}`, { method: "DELETE" });
+    const data: { success: true } | ApiError = await res.json();
+    if (!data.success) throw new Error(data.error.message);
+    set((s) => ({ items: s.items.filter((m) => m.id !== id) }));
+  },
+}));
diff --git a/client/src/types/media.ts b/client/src/types/media.ts
new file mode 100644
index 0000000..fd2857a
--- /dev/null
+++ b/client/src/types/media.ts
@@ -0,0 +1,13 @@
+/** A file in the project's media library (GET /api/projects/:id/media). */
+export type MediaItem = {
+  id: string;
+  name: string;
+  type: "image" | "video";
+  mimeType: string;
+  sizeBytes: number;
+  width: number | null;
+  height: number | null;
+  /** Seconds, for video. */
+  duration: number | null;
+  url: string;
+};

From af27d7f97ebe09b166336584255a68ee1e92944c Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:00:19 +0530
Subject: [PATCH 27/36] feat(client): preview B-roll in the player and on the
 timeline

BrollLayer shows B-roll for its slot, laid out like the export, from its
own animation-frame loop; a clip's position follows the program (offset
plus time into the slot, holding its last frame) and is re-seeked only
when it drifts. A B-roll lane under the timeline shows each piece.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/components/timeline/Timeline.tsx   | 16 ++++
 .../components/video-player/BrollLayer.tsx    | 95 +++++++++++++++++++
 .../components/video-player/VideoPlayer.tsx   |  4 +-
 client/src/lib/timeline/useProgram.ts         |  5 +-
 4 files changed, 118 insertions(+), 2 deletions(-)
 create mode 100644 client/src/components/video-player/BrollLayer.tsx

diff --git a/client/src/components/timeline/Timeline.tsx b/client/src/components/timeline/Timeline.tsx
index c68cccf..87051b4 100644
--- a/client/src/components/timeline/Timeline.tsx
+++ b/client/src/components/timeline/Timeline.tsx
@@ -314,6 +314,22 @@ export function Timeline() {
               style={{ left: `${playheadPosition}%` }}
             />
           </div>
+          {program.overlays.length > 0 && totalDuration > 0 && (
+            <div className="relative h-4 w-full rounded-sm bg-muted/60" aria-label="B-roll">
+              {program.overlays.map(({ overlay, start, end }) => (
+                <button
+                  key={overlay.id}
+                  type="button"
+                  onClick={() => seek(overlay.start)}
+                  title={`B-roll, ${overlay.mode === "full" ? "full screen" : "picture in picture"} (${formatTimecode(end - start)})`}
+                  className={`absolute top-0.5 h-3 rounded-sm border hover:brightness-125 ${
+                    overlay.mode === "full" ? "border-sky-400 bg-sky-500/60" : "border-sky-400 bg-sky-500/25"
+                  }`}
+                  style={{ left: `${(start / totalDuration) * 100}%`, width: `${((end - start) / totalDuration) * 100}%` }}
+                />
+              ))}
+            </div>
+          )}
           {audioBuffer && totalDuration > 0 && (
             <div className="flex h-12 w-full overflow-hidden rounded-md border border-border bg-muted p-1.5">
               {program.items.map((item, i) => (
diff --git a/client/src/components/video-player/BrollLayer.tsx b/client/src/components/video-player/BrollLayer.tsx
new file mode 100644
index 0000000..1c1b304
--- /dev/null
+++ b/client/src/components/video-player/BrollLayer.tsx
@@ -0,0 +1,95 @@
+import { useEffect, useMemo, useRef, useState, type CSSProperties, type RefObject } from "react";
+import { usePlayerStore } from "@/stores/player-store";
+import { useMediaStore } from "@/stores/media-store";
+import { programPlayhead, type Program } from "@/lib/timeline/useProgram";
+import type { PlacedOverlay } from "@/lib/timeline/program";
+import type { OverlayCorner } from "@/types/edit-operation";
+
+/** Must match PIP_WIDTH_FRACTION / PIP_INSET_FRACTION in the server's lib/ffmpeg/plan.ts. */
+const PIP_WIDTH_PERCENT = 32;
+const PIP_INSET_PERCENT = 4;
+/** How far a B-roll video may drift from where it should be before it's re-seeked. */
+const MAX_DRIFT_SECONDS = 0.25;
+
+function pipStyle(corner: OverlayCorner): CSSProperties {
+  const inset = `${PIP_INSET_PERCENT}cqmin`;
+  return {
+    width: `${PIP_WIDTH_PERCENT}%`,
+    ...(corner.startsWith("top") ? { top: inset } : { bottom: inset }),
+    ...(corner.endsWith("left") ? { left: inset } : { right: inset }),
+  };
+}
+
+/**
+ * Shows B-roll over the player for its slot on the program timeline, laid
+ * out like the export (full frame, cropped to fill, or picture-in-picture
+ * in a corner). A video's position follows the program -- offset plus time
+ * into the slot, holding its last frame if it runs short -- re-seeked only
+ * when it drifts, and it plays and pauses with the editor. Muted: the
+ * footage's audio is what plays.
+ */
+export function BrollLayer({ videoRef, program }: { videoRef: RefObject<HTMLVideoElement | null>; program: Program }) {
+  const media = useMediaStore((s) => s.items);
+  const mediaById = useMemo(() => new Map(media.map((m) => [m.id, m])), [media]);
+  const [active, setActive] = useState<PlacedOverlay[]>([]);
+  const activeKeyRef = useRef("");
+  const videoEls = useRef(new Map<string, HTMLVideoElement>());
+
+  useEffect(() => {
+    let frame = 0;
+    const tick = () => {
+      const video = videoRef.current;
+      if (video) {
+        const { card, isPlaying } = usePlayerStore.getState();
+        const t = programPlayhead(program, video.currentTime, card);
+        const now = program.overlays.filter((o) => t >= o.start && t < o.end);
+        const key = now.map((o) => o.overlay.id).join("|");
+        if (key !== activeKeyRef.current) {
+          activeKeyRef.current = key;
+          setActive(now);
+        }
+        for (const placed of now) {
+          const el = videoEls.current.get(placed.overlay.id);
+          if (!el || Number.isNaN(el.duration)) continue;
+          const target = Math.min((placed.overlay.offset ?? 0) + (t - placed.start), Math.max(0, el.duration - 0.05));
+          if (Math.abs(el.currentTime - target) > MAX_DRIFT_SECONDS) el.currentTime = target;
+          const shouldPlay = isPlaying && target < el.duration - 0.05;
+          if (shouldPlay && el.paused) void el.play().catch(() => {});
+          if (!shouldPlay && !el.paused) el.pause();
+        }
+      }
+      frame = requestAnimationFrame(tick);
+    };
+    frame = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame);
+  }, [videoRef, program]);
+
+  return (
+    <>
+      {active.map(({ overlay }) => {
+        const item = mediaById.get(overlay.assetId);
+        if (!item) return null;
+        const style: CSSProperties =
+          overlay.mode === "full" ? { inset: 0, width: "100%", height: "100%" } : pipStyle(overlay.corner ?? "bottom-right");
+        const className = `pointer-events-none absolute ${overlay.mode === "full" ? "object-cover" : "h-auto rounded-sm shadow-lg"}`;
+        return item.type === "image" ? (
+          <img key={overlay.id} src={item.url} alt="" className={className} style={style} draggable={false} />
+        ) : (
+          <video
+            key={overlay.id}
+            ref={(el) => {
+              if (el) videoEls.current.set(overlay.id, el);
+              else videoEls.current.delete(overlay.id);
+            }}
+            src={item.url}
+            muted
+            playsInline
+            preload="auto"
+            className={className}
+            style={style}
+          />
+        );
+      })}
+    </>
+  );
+}
diff --git a/client/src/components/video-player/VideoPlayer.tsx b/client/src/components/video-player/VideoPlayer.tsx
index a6df3c2..97bc8e3 100644
--- a/client/src/components/video-player/VideoPlayer.tsx
+++ b/client/src/components/video-player/VideoPlayer.tsx
@@ -13,6 +13,7 @@ import { programPlayhead, useProgram } from "@/lib/timeline/useProgram";
 import { useCardPlayback } from "@/components/video-player/useCardPlayback";
 import { CardPreview } from "@/components/video-player/CardPreview";
 import { TransitionOverlay } from "@/components/video-player/TransitionOverlay";
+import { BrollLayer } from "@/components/video-player/BrollLayer";
 import { generateCaptions } from "@/lib/captions/generate";
 import { formatTimecode } from "@/lib/timeline/format";
 import { getFilterPreset } from "@/lib/video/filters";
@@ -316,7 +317,8 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
           data-playing={isPlaying}
         />
         <CropOverlay />
-        {/* Under the logo, like the export: the watermark stays on top of cards and transitions. */}
+        {/* B-roll, cards and transitions sit under the logo and captions, like the export. */}
+        <BrollLayer videoRef={videoRef} program={program} />
         {activeCard && <CardPreview card={activeCard} elapsed={card?.elapsed} />}
         <TransitionOverlay videoRef={videoRef} program={program} />
         {cardDraft && <CardPreview card={cardDraft} />}
diff --git a/client/src/lib/timeline/useProgram.ts b/client/src/lib/timeline/useProgram.ts
index 9eca952..97425a8 100644
--- a/client/src/lib/timeline/useProgram.ts
+++ b/client/src/lib/timeline/useProgram.ts
@@ -9,6 +9,7 @@ import {
   type CardSlot,
   type Fade,
   type Join,
+  type PlacedOverlay,
   type ProgramItem,
 } from "@/lib/timeline/program";
 import type { CutOperation } from "@/types/edit-operation";
@@ -23,6 +24,8 @@ export type Program = {
   joins: Join[];
   fadeIn: Fade | null;
   fadeOut: Fade | null;
+  /** B-roll on the program timeline. */
+  overlays: PlacedOverlay[];
   editedDuration: number;
   /** Edited duration plus every card: what the export runs for. */
   duration: number;
@@ -39,7 +42,7 @@ export function useProgram(): Program {
     const program =
       sourceDuration > 0
         ? buildProgram(operations, ranges, sourceDuration)
-        : { slots: [], items: [], joins: [], fadeIn: null, fadeOut: null };
+        : { slots: [], items: [], joins: [], fadeIn: null, fadeOut: null, overlays: [] };
     const editedDuration = getEditedDuration(ranges);
     return {
       cuts,

From 037fd96432e30dfb975138d2680a3530caaea464 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:00:19 +0530
Subject: [PATCH 28/36] docs: document the media library, B-roll and its
 endpoints

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 claude.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/claude.md b/claude.md
index 4313035..f8416fa 100644
--- a/claude.md
+++ b/claude.md
@@ -674,6 +674,16 @@ length (`plan.ts#layoutProgram`). The preview draws them with
 `TransitionOverlay` from the pure `transition-look.ts`, on its own
 animation-frame loop; audio fades aren't previewed.
 
+**B-roll**: `media` assets (many per project, stored under a unique
+prefix, with name/size/length columns) placed by `overlay` operations:
+an asset shown from `start` to `end` in source time (so it follows cuts),
+full screen (scaled to fill, cropped) or picture-in-picture (32% wide,
+4% inset, a chosen corner). Placed on program time like captions
+(`program.ts#placeOverlays`), composited as extra ffmpeg inputs after the
+join and grade, before any clip reframe, card text, captions and logo --
+an image looped for its slot, a video trimmed from its offset holding its
+last frame. B-roll audio is never used. It plays in clips too.
+
 **ffmpeg 9 xfade gotchas** (`plan.ts`, measured on 9.0.2): every segment
 must be pinned to the source's frame rate with `fps=` (without it xfade
 drops the start of each later segment), must not get a `settb` after
@@ -948,6 +958,10 @@ GET    /api/projects/:id/clips
 POST   /api/projects/:id/clips/highlights        (GPT-5.6 Luna picks; replaces earlier AI picks)
 POST   /api/projects/:id/clips                   PATCH/DELETE /api/projects/:id/clips/:clipId
 (render a clip: POST /api/projects/:id/render with {clipId})
+
+GET    /api/projects/:id/media                    (media library: images and clips for B-roll)
+POST   /api/projects/:id/media?filename=          (raw body, image/png|jpeg|webp or video/*; probed, refused if unreadable)
+GET    /api/projects/:id/media/:assetId/file      DELETE /api/projects/:id/media/:assetId (409 while B-roll uses it)
 ```
 
 (No `POST /api/projects/:id/ai/edit` — the free-text AI command bar this

From 0671430a473fd4c04668d5d1205285bb419c59b4 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:11:01 +0530
Subject: [PATCH 29/36] feat(server): detect shot changes in the background

Scene suggestions land better on a visual cut (a multicam switch, a
screen share starting), so ffmpeg scores frames at 320px wide and
reports every frame over the scene threshold; near-duplicates within a
second merge and the very ends are dropped. It runs as a 'shots'
TranscriptionJob that stores its times in a new resultJson column (an
additive migration), reading the 720p proxy when there is one. On a
synthetic clip with cuts at 5s and 10s it finds exactly those, none on
continuous footage, and scans a 14-minute file in under two seconds.

The transcribe and speaker routes refused to start while any job was
running; they now only wait for jobs that rewrite the transcript, so
shot detection doesn't block them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../migration.sql                             |  2 +
 server/prisma/schema.prisma                   |  3 +
 server/src/lib/ffmpeg/shots.ts                | 81 +++++++++++++++++++
 server/src/lib/jobs.ts                        |  5 ++
 server/src/routes/speakers.ts                 |  4 +-
 server/src/routes/transcribe.ts               |  4 +-
 6 files changed, 97 insertions(+), 2 deletions(-)
 create mode 100644 server/prisma/migrations/20260926010000_add_job_result/migration.sql
 create mode 100644 server/src/lib/ffmpeg/shots.ts
 create mode 100644 server/src/lib/jobs.ts

diff --git a/server/prisma/migrations/20260926010000_add_job_result/migration.sql b/server/prisma/migrations/20260926010000_add_job_result/migration.sql
new file mode 100644
index 0000000..a873825
--- /dev/null
+++ b/server/prisma/migrations/20260926010000_add_job_result/migration.sql
@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "TranscriptionJob" ADD COLUMN "resultJson" TEXT;
diff --git a/server/prisma/schema.prisma b/server/prisma/schema.prisma
index b07268a..cc3be13 100644
--- a/server/prisma/schema.prisma
+++ b/server/prisma/schema.prisma
@@ -153,12 +153,15 @@ model TranscriptionJob {
   project   Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
 
   /// "transcribe" (Whisper words) | "diarize" (speaker detection, see lib/ai/diarization-job.ts)
+  /// | "shots" (shot-change detection, see lib/ffmpeg/shots.ts)
   kind            String @default("transcribe")
   /// "queued" | "processing" | "completed" | "failed"
   status          String @default("queued")
   totalChunks     Int    @default(0)
   completedChunks Int    @default(0)
   error           String?
+  /// "shots" jobs: the detected shot-change times (source seconds), as a JSON array.
+  resultJson      String?
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
diff --git a/server/src/lib/ffmpeg/shots.ts b/server/src/lib/ffmpeg/shots.ts
new file mode 100644
index 0000000..89b3642
--- /dev/null
+++ b/server/src/lib/ffmpeg/shots.ts
@@ -0,0 +1,81 @@
+import { prisma } from "@/lib/db/client";
+import { logger } from "@/lib/logger";
+import { resolveInDataDir } from "@/lib/storage/local";
+import { runFfmpegCapturingStderr } from "@/lib/ffmpeg/run";
+
+/**
+ * Shot-change detection: where the picture cuts (camera switches in a
+ * multicam podcast, a screen share starting). Used to land AI-suggested
+ * scene boundaries on a visual cut instead of mid-shot.
+ */
+
+/** ffmpeg's scene score (0-1) above which a frame counts as a new shot. */
+const SCENE_THRESHOLD = 0.35;
+/** Frames are scored at this width: plenty for spotting a cut, and several times faster than 720p. */
+const ANALYSIS_WIDTH = 320;
+/** Two changes closer than this are one cut (a flash, a fast pan). */
+const MIN_SHOT_SECONDS = 1;
+
+/** Argv that prints a showinfo line for every frame scoring above the threshold. No output file. */
+export function buildShotDetectionArgs(inputPath: string): string[] {
+  return [
+    "-hide_banner",
+    "-nostats",
+    "-i",
+    inputPath,
+    "-an",
+    "-vf",
+    `scale=${ANALYSIS_WIDTH}:-2,select='gt(scene,${SCENE_THRESHOLD})',showinfo`,
+    "-f",
+    "null",
+    "-",
+  ];
+}
+
+/**
+ * Shot-change times from showinfo's stderr, in order, with near-duplicates
+ * merged and anything too close to either end of the video dropped.
+ */
+export function parseShotTimes(stderr: string, duration: number): number[] {
+  const times = [...stderr.matchAll(/\bpts_time:\s*([0-9]+(?:\.[0-9]+)?)/g)]
+    .map((m) => Number(m[1]))
+    .filter((t) => Number.isFinite(t) && t >= MIN_SHOT_SECONDS && t <= duration - MIN_SHOT_SECONDS)
+    .sort((a, b) => a - b);
+  const shots: number[] = [];
+  for (const t of times) {
+    if (shots.length === 0 || t - shots[shots.length - 1] >= MIN_SHOT_SECONDS) shots.push(t);
+  }
+  return shots;
+}
+
+/**
+ * Runs one shot-detection job to completion, storing the times on the job
+ * row. Reads the 720p proxy when there is one (it decodes far faster than
+ * a 4K original and cuts in the same places).
+ */
+export async function runShotJob(jobId: string): Promise<void> {
+  try {
+    const job = await prisma.transcriptionJob.update({ where: { id: jobId }, data: { status: "processing" } });
+    const project = await prisma.project.findUniqueOrThrow({
+      where: { id: job.projectId },
+      include: { assets: true },
+    });
+    const video =
+      project.assets.find((a) => a.kind === "proxy") ?? project.assets.find((a) => a.kind === "original");
+    if (!video) throw new Error("No video for this project.");
+    if (project.duration === null) throw new Error("Video duration isn't known yet -- open the project once first.");
+
+    const stderr = await runFfmpegCapturingStderr(buildShotDetectionArgs(resolveInDataDir(video.filePath)));
+    const shots = parseShotTimes(stderr, project.duration);
+    await prisma.transcriptionJob.update({
+      where: { id: jobId },
+      data: { status: "completed", resultJson: JSON.stringify(shots), error: null },
+    });
+  } catch (err) {
+    logger.error(`Shot detection job ${jobId} failed:`, err);
+    await prisma.transcriptionJob.update({
+      where: { id: jobId },
+      data: { status: "failed", error: err instanceof Error ? err.message : "Shot detection failed." },
+    });
+  }
+}
diff --git a/server/src/lib/jobs.ts b/server/src/lib/jobs.ts
new file mode 100644
index 0000000..2865c1d
--- /dev/null
+++ b/server/src/lib/jobs.ts
@@ -0,0 +1,5 @@
+/**
+ * TranscriptionJob kinds that rewrite the transcript, and so must never
+ * run at the same time. Shot detection ("shots") only reads the video.
+ */
+export const TRANSCRIPT_JOB_KINDS = ["transcribe", "diarize"];
diff --git a/server/src/routes/speakers.ts b/server/src/routes/speakers.ts
index 40f5a53..3f626ca 100644
--- a/server/src/routes/speakers.ts
+++ b/server/src/routes/speakers.ts
@@ -2,6 +2,7 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { prisma } from "@/lib/db/client";
 import { errorResponse } from "@/lib/http";
+import { TRANSCRIPT_JOB_KINDS } from "@/lib/jobs";
 import { runDiarizationJob } from "@/lib/ai/diarization-job";
 import type { Transcript } from "@/types/transcript";
 
@@ -21,7 +22,8 @@ speakersRoute.post("/:id/speakers/detect", async (c) => {
   }
   // Transcription and speaker detection both rewrite the transcript -- never run them concurrently.
   const running = await prisma.transcriptionJob.findFirst({
-    where: { projectId: id, status: { in: ["queued", "processing"] } },
+    // Only jobs that rewrite the transcript conflict; shot detection only reads the video.
+    where: { projectId: id, kind: { in: TRANSCRIPT_JOB_KINDS }, status: { in: ["queued", "processing"] } },
   });
   if (running) {
     return errorResponse(c, "ALREADY_RUNNING", "This project's transcript is already being processed.", 409);
diff --git a/server/src/routes/transcribe.ts b/server/src/routes/transcribe.ts
index 8797e79..0360499 100644
--- a/server/src/routes/transcribe.ts
+++ b/server/src/routes/transcribe.ts
@@ -2,6 +2,7 @@ import { Hono } from "hono";
 import { prisma } from "@/lib/db/client";
 import { runTranscriptionJob } from "@/lib/ai/transcription-job";
 import { errorResponse } from "@/lib/http";
+import { TRANSCRIPT_JOB_KINDS } from "@/lib/jobs";
 
 export const transcribeRoute = new Hono();
 
@@ -20,7 +21,8 @@ transcribeRoute.post("/:id/transcribe", async (c) => {
   }
 
   const running = await prisma.transcriptionJob.findFirst({
-    where: { projectId: id, status: { in: ["queued", "processing"] } },
+    // Only jobs that rewrite the transcript conflict; shot detection only reads the video.
+    where: { projectId: id, kind: { in: TRANSCRIPT_JOB_KINDS }, status: { in: ["queued", "processing"] } },
   });
   if (running) {
     return errorResponse(c, "ALREADY_TRANSCRIBING", "This project's transcript is already being processed.", 409);

From cf486aab1ac6e55669a41308fb28e7b936ea9ab2 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:11:01 +0530
Subject: [PATCH 30/36] feat(server): suggest scenes with AI, for review

gpt-4o-mini reads the edited transcript and returns the sentences where
topics change, with titles -- sentence indices only, like chapters,
schema-validated. scenesFromPicks turns them into boundaries: whole
sentences, the first scene at 0 (a first pick near the start names it),
at least 45s apart, placed in the silence before the sentence, or on a
detected shot change within 1.5s that isn't inside a word. The route
only returns suggestions; nothing is applied server-side.

The prompt spells out the sentence range and asks for the last scene
late in the episode: without that, gpt-4o-mini put every scene in the
first 90 seconds of a 14-minute transcript.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 server/src/index.ts                   |   2 +
 server/src/lib/ai/publishing.ts       |   4 +-
 server/src/lib/ai/scenes.ts           |  50 +++++++++++
 server/src/lib/scenes/suggest.test.ts | 125 ++++++++++++++++++++++++++
 server/src/lib/scenes/suggest.ts      | 114 +++++++++++++++++++++++
 server/src/routes/scenes.ts           | 105 ++++++++++++++++++++++
 6 files changed, 398 insertions(+), 2 deletions(-)
 create mode 100644 server/src/lib/ai/scenes.ts
 create mode 100644 server/src/lib/scenes/suggest.test.ts
 create mode 100644 server/src/lib/scenes/suggest.ts
 create mode 100644 server/src/routes/scenes.ts

diff --git a/server/src/index.ts b/server/src/index.ts
index 1c4e201..6e4016b 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -18,6 +18,7 @@ import { settingsRoute } from "@/routes/settings";
 import { publishingRoute } from "@/routes/publishing";
 import { speakersRoute } from "@/routes/speakers";
 import { mediaRoute } from "@/routes/media";
+import { scenesRoute } from "@/routes/scenes";
 import { clipsRoute } from "@/routes/clips";
 import { prisma } from "@/lib/db/client";
 import { getMaxUploadBytes } from "@/lib/limits";
@@ -42,6 +43,7 @@ app.route("/api/projects", publishingRoute);
 app.route("/api/projects", speakersRoute);
 app.route("/api/projects", clipsRoute);
 app.route("/api/projects", mediaRoute);
+app.route("/api/projects", scenesRoute);
 app.route("/api/settings", settingsRoute);
 
 // Serves the built Vite client (server-bundle/client-dist in the packaged
diff --git a/server/src/lib/ai/publishing.ts b/server/src/lib/ai/publishing.ts
index 179e465..c4ee342 100644
--- a/server/src/lib/ai/publishing.ts
+++ b/server/src/lib/ai/publishing.ts
@@ -26,14 +26,14 @@ export class PublishingAiError extends Error {
 }
 
 /** Numbered, timestamped lines, so the model can point at sentences by index. */
-function numberedTranscript(sentences: EditedSentence[]): string {
+export function numberedTranscript(sentences: EditedSentence[]): string {
   const longForm = sentences.length > 0 && sentences[sentences.length - 1].end >= 3600;
   return sentences
     .map((s, i) => `[${i}] ${formatTimestamp(s.start, longForm)} ${s.speaker ? `${s.speaker}: ` : ""}${s.text}`)
     .join("\n");
 }
 
-async function completeJson(system: string, user: string): Promise<unknown> {
+export async function completeJson(system: string, user: string): Promise<unknown> {
   const completion = await getOpenAI().chat.completions.create({
     model: "gpt-4o-mini",
     temperature: 0.2,
diff --git a/server/src/lib/ai/scenes.ts b/server/src/lib/ai/scenes.ts
new file mode 100644
index 0000000..3b5af6e
--- /dev/null
+++ b/server/src/lib/ai/scenes.ts
@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { completeJson, numberedTranscript, PublishingAiError } from "@/lib/ai/publishing";
+import type { EditedSentence } from "@/lib/publishing/edited-transcript";
+import type { ScenePick } from "@/lib/scenes/suggest";
+
+/**
+ * "Suggest scenes": the model reads the edited transcript and names the
+ * sentences where each topic starts. Like chapters (lib/ai/publishing.ts)
+ * it only returns sentence indices and titles -- never times, never edit
+ * operations -- and the response is schema-validated; lib/scenes/suggest.ts
+ * then turns it into boundaries the user reviews before anything changes.
+ * gpt-4o-mini: segmenting a transcript is structured extraction (section 4).
+ */
+
+const scenePicksSchema = z.object({
+  scenes: z
+    .array(
+      z.object({
+        sentenceIndex: z.number().int(),
+        title: z.string().min(1).max(200),
+      })
+    )
+    .max(60),
+});
+
+/** About one scene per 4-8 minutes -- finer than chapters, which run 5-8. */
+function sceneGuidance(totalSeconds: number): string {
+  const minutes = totalSeconds / 60;
+  const low = Math.max(2, Math.round(minutes / 8));
+  const high = Math.max(low, Math.round(minutes / 4));
+  return `${low}-${high}`;
+}
+
+export async function generateScenePicks(sentences: EditedSentence[], minGapSeconds: number): Promise<ScenePick[]> {
+  if (sentences.length === 0) return [];
+  const total = sentences[sentences.length - 1].end;
+  const system = [
+    "You split podcast episodes into scenes for a video editor: stretches of conversation about one topic.",
+    'Reply with JSON: {"scenes": [{"sentenceIndex": number, "title": string}]}.',
+    "sentenceIndex is the [number] of the sentence where the scene starts. The first scene starts at sentence 0.",
+    `The episode runs ${Math.round(total / 60)} minutes: sentences [0] to [${sentences.length - 1}]; the timestamp after each [number] shows where you are.`,
+    `Read to the end before answering. Your last scene must start after sentence [${Math.round(sentences.length * 0.6)}].`,
+    `Aim for ${sceneGuidance(total)} scenes spread across the WHOLE episode, from the start to the final minutes, at least ${Math.round(minGapSeconds)} seconds apart, each starting where the conversation clearly moves to a new topic.`,
+    "Titles are short (2-6 words), specific to what's discussed, in title case, with no numbering and no quotes. They appear on title cards.",
+  ].join("\n");
+  const raw = await completeJson(system, numberedTranscript(sentences));
+  const parsed = scenePicksSchema.safeParse(raw);
+  if (!parsed.success) throw new PublishingAiError("The model's scene list wasn't in the expected shape.");
+  return parsed.data.scenes;
+}
diff --git a/server/src/lib/scenes/suggest.test.ts b/server/src/lib/scenes/suggest.test.ts
new file mode 100644
index 0000000..c269e8c
--- /dev/null
+++ b/server/src/lib/scenes/suggest.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import { cleanSceneTitle, minSceneSeconds, scenesFromPicks } from "@/lib/scenes/suggest";
+import { buildShotDetectionArgs, parseShotTimes } from "@/lib/ffmpeg/shots";
+import type { EditedSentence } from "@/lib/publishing/edited-transcript";
+
+/** One sentence every 20s: words at [t, t+1] and [t+1.2, t+3]. */
+const sentences: EditedSentence[] = Array.from({ length: 10 }, (_, i) => ({
+  sourceStart: i * 20,
+  sourceEnd: i * 20 + 3,
+  start: i * 20,
+  end: i * 20 + 3,
+  text: `Sentence number ${i} about something.`,
+}));
+const words = sentences.flatMap((s) => [
+  { start: s.sourceStart, end: s.sourceStart + 1 },
+  { start: s.sourceStart + 1.2, end: s.sourceStart + 3 },
+]);
+
+describe("scenesFromPicks", () => {
+  it("names the first scene and places later boundaries in the silence before their sentence", () => {
+    const out = scenesFromPicks(
+      [
+        { sentenceIndex: 0, title: "Welcome" },
+        { sentenceIndex: 4, title: "Gear" },
+      ],
+      sentences,
+      words,
+      [],
+      30
+    );
+    expect(out).toEqual([
+      { at: 0, title: "Welcome", excerpt: "Sentence number 0 about something.", onShot: false },
+      // Previous word ends at 63, sentence starts at 80.
+      { at: 71.5, title: "Gear", excerpt: "Sentence number 4 about something.", onShot: false },
+    ]);
+  });
+
+  it("uses a first pick near the start as the opening scene's name", () => {
+    const out = scenesFromPicks(
+      [
+        { sentenceIndex: 1, title: "Welcome" },
+        { sentenceIndex: 4, title: "Gear" },
+      ],
+      sentences,
+      words,
+      [],
+      30
+    );
+    expect(out.map((s) => [s.at, s.title])).toEqual([
+      [0, "Welcome"],
+      [71.5, "Gear"],
+    ]);
+  });
+
+  it("adds an Intro when the model skips the opening, and drops scenes too close together", () => {
+    const out = scenesFromPicks(
+      [
+        { sentenceIndex: 2, title: "A" },
+        { sentenceIndex: 3, title: "Too soon" },
+        { sentenceIndex: 5, title: "B" },
+      ],
+      sentences,
+      words,
+      [],
+      30
+    );
+    expect(out.map((s) => s.title)).toEqual(["Intro", "A", "B"]);
+  });
+
+  it("moves a boundary onto a nearby shot change, but never into a word", () => {
+    const onShot = scenesFromPicks([{ sentenceIndex: 4, title: "Gear" }], sentences, words, [70.6], 30);
+    expect(onShot[1]).toMatchObject({ at: 70.6, onShot: true });
+    const inWord = scenesFromPicks([{ sentenceIndex: 4, title: "Gear" }], sentences, words, [80.5], 30);
+    expect(inWord[1]).toMatchObject({ at: 71.5, onShot: false });
+    const tooFar = scenesFromPicks([{ sentenceIndex: 4, title: "Gear" }], sentences, words, [75], 30);
+    expect(tooFar[1].onShot).toBe(false);
+  });
+
+  it("ignores out-of-range indices and empty titles", () => {
+    const out = scenesFromPicks(
+      [
+        { sentenceIndex: 99, title: "Nope" },
+        { sentenceIndex: -1, title: "Nope" },
+        { sentenceIndex: 4, title: "   " },
+      ],
+      sentences,
+      words,
+      [],
+      30
+    );
+    expect(out).toEqual([]);
+  });
+});
+
+describe("cleanSceneTitle", () => {
+  it("strips characters card text can't hold and caps the length", () => {
+    expect(cleanSceneTitle("  Pricing {\\fs99}\n talk ")).toBe("Pricing fs99 talk");
+    expect(cleanSceneTitle("x".repeat(80))).toHaveLength(60);
+  });
+});
+
+describe("minSceneSeconds", () => {
+  it("is 45s for an episode, less for a short video", () => {
+    expect(minSceneSeconds(3600)).toBe(45);
+    expect(minSceneSeconds(120)).toBe(20);
+    expect(minSceneSeconds(30)).toBe(10);
+  });
+});
+
+describe("shot detection", () => {
+  it("scores frames at low resolution and prints only the cuts", () => {
+    expect(buildShotDetectionArgs("/data/proxy.mp4")).toContain("scale=320:-2,select='gt(scene,0.35)',showinfo");
+  });
+
+  it("parses showinfo times, merging near-duplicates and dropping the very ends", () => {
+    const stderr = [
+      "[Parsed_showinfo_2 @ 0x1] n:   0 pts:   12 pts_time:0.4 duration: 1",
+      "[Parsed_showinfo_2 @ 0x1] n:   1 pts:  300 pts_time:12.012 duration: 1",
+      "[Parsed_showinfo_2 @ 0x1] n:   2 pts:  310 pts_time:12.4 duration: 1",
+      "[Parsed_showinfo_2 @ 0x1] n:   3 pts:  900 pts_time:36.5 duration: 1",
+      "[Parsed_showinfo_2 @ 0x1] n:   4 pts:  999 pts_time:59.6 duration: 1",
+    ].join("\n");
+    expect(parseShotTimes(stderr, 60)).toEqual([12.012, 36.5]);
+  });
+});
diff --git a/server/src/lib/scenes/suggest.ts b/server/src/lib/scenes/suggest.ts
new file mode 100644
index 0000000..41adcbb
--- /dev/null
+++ b/server/src/lib/scenes/suggest.ts
@@ -0,0 +1,114 @@
+import type { EditedSentence } from "@/lib/publishing/edited-transcript";
+
+/** A scene the model picked: the sentence it opens with, and a name. */
+export type ScenePick = { sentenceIndex: number; title: string };
+
+/**
+ * A suggested scene boundary, for the user to review -- never applied on
+ * its own. `at` is source time: 0 for the first scene (only naming it), else
+ * a point between words, on a shot change when one was close.
+ */
+export type SceneSuggestion = {
+  at: number;
+  title: string;
+  /** The opening sentence, so the review list can show what the scene starts with. */
+  excerpt: string;
+  /** True when `at` was moved onto a detected shot change. */
+  onShot: boolean;
+};
+
+export const SCENE_TITLE_MAX = 60;
+const MAX_SCENES = 30;
+/** A boundary moves onto a shot change at most this far away. */
+const SHOT_SNAP_SECONDS = 1.5;
+const EXCERPT_MAX = 90;
+
+/** Fewest seconds between suggested scenes: 45s, less for a short video so it can still be split. */
+export function minSceneSeconds(totalSeconds: number): number {
+  return Math.min(45, Math.max(10, totalSeconds / 6));
+}
+
+export function cleanSceneTitle(title: string): string {
+  // Titles also become card text: no control characters, braces or backslashes (see validation/edit-operation.ts).
+  const cleaned = Array.from(title)
+    .filter((ch) => {
+      const code = ch.charCodeAt(0);
+      return code >= 0x20 && code !== 0x7f && !"{}\\".includes(ch);
+    })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  return cleaned.length > SCENE_TITLE_MAX ? `${cleaned.slice(0, SCENE_TITLE_MAX - 1).trimEnd()}…` : cleaned;
+}
+
+function excerpt(text: string): string {
+  return text.length > EXCERPT_MAX ? `${text.slice(0, EXCERPT_MAX - 1).trimEnd()}…` : text;
+}
+
+/** Midpoint of the silence before a source time (after the last word ending at or before it). */
+function gapBefore(sourceTime: number, words: { start: number; end: number }[]): number {
+  let previousEnd = 0;
+  for (const w of words) {
+    if (w.end <= sourceTime && w.end > previousEnd) previousEnd = w.end;
+  }
+  return (previousEnd + sourceTime) / 2;
+}
+
+/** The shot change nearest `t` within SHOT_SNAP_SECONDS that isn't in the middle of a word. */
+function nearbyShot(t: number, shots: number[], words: { start: number; end: number }[]): number | null {
+  let best: number | null = null;
+  for (const shot of shots) {
+    const distance = Math.abs(shot - t);
+    if (distance > SHOT_SNAP_SECONDS) continue;
+    if (words.some((w) => shot > w.start && shot < w.end)) continue;
+    if (best === null || distance < Math.abs(best - t)) best = shot;
+  }
+  return best;
+}
+
+/**
+ * Turns picks (from the model or from chapters) into scene suggestions:
+ * indices checked, titles cleaned, the first scene always starting at 0
+ * (a first pick near the start names it; otherwise it's called "Intro"),
+ * scenes at least `minGapSeconds` apart on the edited timeline (the rest
+ * dropped), and each boundary placed in the silence before its sentence --
+ * or on a shot change within 1.5s, so the cut is also a visual one.
+ */
+export function scenesFromPicks(
+  picks: ScenePick[],
+  sentences: EditedSentence[],
+  words: { start: number; end: number }[],
+  shots: number[],
+  minGapSeconds: number
+): SceneSuggestion[] {
+  if (sentences.length === 0) return [];
+  const valid = picks
+    .filter((p) => Number.isInteger(p.sentenceIndex) && p.sentenceIndex >= 0 && p.sentenceIndex < sentences.length)
+    .map((p) => ({ index: p.sentenceIndex, title: cleanSceneTitle(p.title) }))
+    .filter((p) => p.title.length > 0)
+    .sort((a, b) => a.index - b.index);
+  if (valid.length === 0) return [];
+  // A first pick close to the start names the opening scene rather than being
+  // dropped as too close to it (models often skip the greeting sentence).
+  if (valid[0].index !== 0) {
+    if (sentences[valid[0].index].start < minGapSeconds) valid[0] = { ...valid[0], index: 0 };
+    else valid.unshift({ index: 0, title: "Intro" });
+  }
+
+  const suggestions: SceneSuggestion[] = [];
+  let lastStart = -Infinity;
+  for (const pick of valid) {
+    const sentence = sentences[pick.index];
+    if (pick.index > 0 && sentence.start - lastStart < minGapSeconds) continue;
+    if (pick.index === 0) {
+      suggestions.push({ at: 0, title: pick.title, excerpt: excerpt(sentence.text), onShot: false });
+    } else {
+      const gap = gapBefore(sentence.sourceStart, words);
+      const shot = nearbyShot(gap, shots, words);
+      suggestions.push({ at: shot ?? gap, title: pick.title, excerpt: excerpt(sentence.text), onShot: shot !== null });
+    }
+    lastStart = pick.index === 0 ? 0 : sentence.start;
+    if (suggestions.length >= MAX_SCENES) break;
+  }
+  return suggestions;
+}
diff --git a/server/src/routes/scenes.ts b/server/src/routes/scenes.ts
new file mode 100644
index 0000000..a3b7fac
--- /dev/null
+++ b/server/src/routes/scenes.ts
@@ -0,0 +1,105 @@
+import { Hono } from "hono";
+import { prisma } from "@/lib/db/client";
+import { errorResponse } from "@/lib/http";
+import { logger } from "@/lib/logger";
+import { runShotJob } from "@/lib/ffmpeg/shots";
+import { generateScenePicks } from "@/lib/ai/scenes";
+import { buildEditedSentences } from "@/lib/publishing/edited-transcript";
+import { minSceneSeconds, scenesFromPicks } from "@/lib/scenes/suggest";
+import type { CutOperation, EditOperation } from "@/types/edit-operation";
+import type { Transcript } from "@/types/transcript";
+
+export const scenesRoute = new Hono();
+
+type ShotJob = Awaited<ReturnType<typeof prisma.transcriptionJob.findFirstOrThrow>>;
+
+function shotJobJson(job: ShotJob) {
+  return {
+    id: job.id,
+    status: job.status,
+    shots: job.resultJson ? (JSON.parse(job.resultJson) as number[]) : null,
+    error: job.error,
+  };
+}
+
+async function latestShots(projectId: string): Promise<number[]> {
+  const job = await prisma.transcriptionJob.findFirst({
+    where: { projectId, kind: "shots", status: "completed" },
+    orderBy: { createdAt: "desc" },
+  });
+  return job?.resultJson ? (JSON.parse(job.resultJson) as number[]) : [];
+}
+
+/**
+ * POST /api/projects/:id/scenes/shots -- detects shot changes in the
+ * background (lib/ffmpeg/shots.ts). If one is already running, returns it
+ * instead of starting another. Poll GET /scenes/shots/:jobId.
+ */
+scenesRoute.post("/:id/scenes/shots", async (c) => {
+  const id = c.req.param("id");
+  const video = await prisma.asset.findFirst({ where: { projectId: id, kind: { in: ["original", "proxy"] } } });
+  if (!video) return errorResponse(c, "NO_VIDEO", "Upload a video first.", 400);
+
+  const running = await prisma.transcriptionJob.findFirst({
+    where: { projectId: id, kind: "shots", status: { in: ["queued", "processing"] } },
+  });
+  if (running) return c.json({ success: true, jobId: running.id });
+
+  const job = await prisma.transcriptionJob.create({ data: { projectId: id, kind: "shots", status: "queued" } });
+  void runShotJob(job.id);
+  return c.json({ success: true, jobId: job.id }, 202);
+});
+
+/** The most recent shot detection for this project, if any -- so the panel can show it after a reload. */
+scenesRoute.get("/:id/scenes/shots", async (c) => {
+  const job = await prisma.transcriptionJob.findFirst({
+    where: { projectId: c.req.param("id"), kind: "shots" },
+    orderBy: { createdAt: "desc" },
+  });
+  return c.json({ success: true, job: job ? shotJobJson(job) : null });
+});
+
+scenesRoute.get("/:id/scenes/shots/:jobId", async (c) => {
+  const job = await prisma.transcriptionJob.findUnique({ where: { id: c.req.param("jobId") } });
+  if (!job || job.projectId !== c.req.param("id") || job.kind !== "shots") {
+    return errorResponse(c, "NOT_FOUND", "Shot detection job not found.", 404);
+  }
+  return c.json({ success: true, job: shotJobJson(job) });
+});
+
+/**
+ * POST /api/projects/:id/scenes/suggest -- AI scene suggestions for review.
+ * Returns suggestions only; the client applies the ones the user keeps as
+ * ordinary split/card operations. Uses the latest shot detection, if any,
+ * to land boundaries on visual cuts.
+ */
+scenesRoute.post("/:id/scenes/suggest", async (c) => {
+  const id = c.req.param("id");
+  const project = await prisma.project.findUnique({
+    where: { id },
+    include: { transcript: true, editOperations: true },
+  });
+  if (!project) return errorResponse(c, "NOT_FOUND", "Project not found.", 404);
+  if (!project.transcript) return errorResponse(c, "NO_TRANSCRIPT", "Transcribe this project first.", 400);
+  if (project.duration === null) return errorResponse(c, "NO_DURATION", "Open the project once first.", 400);
+
+  const transcript: Transcript = { id: project.transcript.id, segments: JSON.parse(project.transcript.segmentsJson) };
+  const cuts = project.editOperations
+    .map((op) => JSON.parse(op.dataJson) as EditOperation)
+    .filter((op): op is CutOperation => op.type === "cut");
+  const sentences = buildEditedSentences(transcript, cuts, project.duration);
+  if (sentences.length === 0) {
+    return errorResponse(c, "NOTHING_TO_SPLIT", "There's no remaining speech to split into scenes.", 400);
+  }
+
+  const shots = await latestShots(id);
+  const minGap = minSceneSeconds(sentences[sentences.length - 1].end);
+  try {
+    const picks = await generateScenePicks(sentences, minGap);
+    const words = transcript.segments.flatMap((s) => s.words);
+    return c.json({ success: true, suggestions: scenesFromPicks(picks, sentences, words, shots, minGap), usedShots: shots.length > 0 });
+  } catch (err) {
+    logger.error("Scene suggestion failed:", err);
+    return errorResponse(c, "AI_FAILED", "Scenes couldn't be suggested. Please try again.", 502);
+  }
+});

From ba3130c002fcb94bd0487031dcf07aa6519aaa36 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:11:01 +0530
Subject: [PATCH 31/36] feat(client): review and apply scene suggestions

The Scenes panel gets Suggest scenes, From chapters (built client-side
from the Publish panel's chapters, no AI call) and shot-change
detection. Suggestions show as a review list -- keep or drop each, edit
titles, optionally add a numbered chapter card to each -- and as dashed
lines on the timeline, with detected cuts as ticks. Apply adds the kept
splits and cards as one undo step; a suggestion within a second of an
existing split renames it rather than leaving a sliver of a scene.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../components/editor/SceneSuggestions.tsx    | 216 ++++++++++++++++++
 client/src/components/editor/ScenesPanel.tsx  |   3 +
 client/src/components/timeline/Timeline.tsx   |  21 ++
 client/src/lib/scenes/suggestions.test.ts     |  67 ++++++
 client/src/lib/scenes/suggestions.ts          |  85 +++++++
 client/src/stores/scene-suggestion-store.ts   |  35 +++
 client/src/stores/timeline-store.ts           |   9 +
 7 files changed, 436 insertions(+)
 create mode 100644 client/src/components/editor/SceneSuggestions.tsx
 create mode 100644 client/src/lib/scenes/suggestions.test.ts
 create mode 100644 client/src/lib/scenes/suggestions.ts
 create mode 100644 client/src/stores/scene-suggestion-store.ts

diff --git a/client/src/components/editor/SceneSuggestions.tsx b/client/src/components/editor/SceneSuggestions.tsx
new file mode 100644
index 0000000..ad34835
--- /dev/null
+++ b/client/src/components/editor/SceneSuggestions.tsx
@@ -0,0 +1,216 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { BookOpenText, Clapperboard, Sparkles } from "lucide-react";
+import { useProjectStore } from "@/stores/project-store";
+import { usePlayerStore } from "@/stores/player-store";
+import { useTimelineStore } from "@/stores/timeline-store";
+import { useTranscriptStore } from "@/stores/transcript-store";
+import { useSceneSuggestionStore } from "@/stores/scene-suggestion-store";
+import { operationsForSuggestions, suggestionsFromChapters, type SceneSuggestion } from "@/lib/scenes/suggestions";
+import { formatTimecode } from "@/lib/timeline/format";
+import { Button } from "@/components/ui/button";
+import type { ResolvedChapter } from "@/types/publishing";
+
+type ApiError = { success: false; error: { message: string } };
+type ShotJob = { id: string; status: "queued" | "processing" | "completed" | "failed"; shots: number[] | null; error: string | null };
+
+const POLL_MS = 1500;
+
+/**
+ * Builds scenes for you, for review: AI suggestions (topic changes, landed
+ * on shot changes when detected), or scenes from the episode's chapters.
+ * Nothing changes until Apply, which adds the kept scenes -- and, if
+ * chosen, a numbered title card for each -- as one undo step.
+ */
+export function SceneSuggestions() {
+  const projectId = useProjectStore((s) => s.id);
+  const seek = usePlayerStore((s) => s.seek);
+  const operations = useTimelineStore((s) => s.operations);
+  const applyChange = useTimelineStore((s) => s.applyChange);
+  const transcript = useTranscriptStore((s) => s.transcript);
+  const { suggestions, source, shots, setSuggestions, update, clear, setShots } = useSceneSuggestionStore();
+
+  const [busy, setBusy] = useState<"suggest" | "chapters" | "shots" | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [withCards, setWithCards] = useState(true);
+  const pollRef = useRef<number | null>(null);
+
+  const pollShots = useCallback(
+    (jobId: string) => {
+      if (!projectId) return;
+      setBusy("shots");
+      const tick = async () => {
+        const res = await fetch(`/api/projects/${projectId}/scenes/shots/${jobId}`);
+        const data: { success: true; job: ShotJob } | ApiError = await res.json();
+        if (!data.success) {
+          setBusy(null);
+          setError(data.error.message);
+          return;
+        }
+        if (data.job.status === "completed") {
+          setShots(data.job.shots ?? []);
+          setBusy(null);
+        } else if (data.job.status === "failed") {
+          setError(data.job.error ?? "Shot detection failed.");
+          setBusy(null);
+        } else {
+          pollRef.current = window.setTimeout(tick, POLL_MS);
+        }
+      };
+      void tick();
+    },
+    [projectId, setShots]
+  );
+
+  // Pick up the last detection (or one still running) when the panel opens.
+  useEffect(() => {
+    if (!projectId) return;
+    let cancelled = false;
+    void (async () => {
+      const res = await fetch(`/api/projects/${projectId}/scenes/shots`);
+      const data: { success: true; job: ShotJob | null } | ApiError = await res.json();
+      if (cancelled || !data.success || !data.job) return;
+      if (data.job.status === "completed") setShots(data.job.shots ?? []);
+      else if (data.job.status === "queued" || data.job.status === "processing") pollShots(data.job.id);
+    })();
+    return () => {
+      cancelled = true;
+      if (pollRef.current !== null) window.clearTimeout(pollRef.current);
+    };
+  }, [projectId, pollShots, setShots]);
+
+  const detectShots = async () => {
+    if (!projectId) return;
+    setError(null);
+    const res = await fetch(`/api/projects/${projectId}/scenes/shots`, { method: "POST" });
+    const data: { success: true; jobId: string } | ApiError = await res.json();
+    if (data.success) pollShots(data.jobId);
+    else setError(data.error.message);
+  };
+
+  const suggest = async () => {
+    if (!projectId) return;
+    setBusy("suggest");
+    setError(null);
+    try {
+      const res = await fetch(`/api/projects/${projectId}/scenes/suggest`, { method: "POST" });
+      const data: { success: true; suggestions: SceneSuggestion[] } | ApiError = await res.json();
+      if (!data.success) setError(data.error.message);
+      else if (data.suggestions.length === 0) setError("No clear topic changes were found.");
+      else setSuggestions(data.suggestions, "ai");
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const fromChapters = async () => {
+    if (!projectId) return;
+    setBusy("chapters");
+    setError(null);
+    try {
+      const res = await fetch(`/api/projects/${projectId}/publishing`);
+      const data: { success: true; chapters: ResolvedChapter[] } | ApiError = await res.json();
+      if (!data.success) setError(data.error.message);
+      else if (data.chapters.length < 2) setError("Generate chapters in the Publish panel first.");
+      else setSuggestions(suggestionsFromChapters(data.chapters, transcript?.segments.flatMap((s) => s.words) ?? []), "manual");
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const apply = () => {
+    const kept = (suggestions ?? []).filter((s) => s.keep && s.title.trim());
+    if (kept.length === 0) return;
+    const { added, removedIds } = operationsForSuggestions(
+      kept.map((s) => ({ ...s, title: s.title.trim() })),
+      operations,
+      { withCards, source }
+    );
+    applyChange(added, removedIds);
+    clear();
+  };
+
+  const keptCount = suggestions?.filter((s) => s.keep).length ?? 0;
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="grid grid-cols-2 gap-1.5">
+        <Button variant="outline" size="sm" onClick={() => void suggest()} disabled={busy !== null || !transcript}>
+          <Sparkles className="size-3.5" />
+          {busy === "suggest" ? "Thinking…" : "Suggest scenes"}
+        </Button>
+        <Button variant="outline" size="sm" onClick={() => void fromChapters()} disabled={busy !== null}>
+          <BookOpenText className="size-3.5" />
+          From chapters
+        </Button>
+      </div>
+      <div className="flex items-center justify-between gap-2 text-muted-foreground">
+        <span>
+          {busy === "shots"
+            ? "Finding shot changes…"
+            : shots === null
+              ? "Find camera cuts to line scenes up with them."
+              : `${shots.length} shot change${shots.length === 1 ? "" : "s"} found${shots.length > 0 ? " -- suggestions snap to them" : ""}.`}
+        </span>
+        <Button variant="ghost" size="xs" onClick={() => void detectShots()} disabled={busy !== null}>
+          <Clapperboard className="size-3" />
+          {shots === null ? "Find" : "Again"}
+        </Button>
+      </div>
+      {error && <p className="rounded-md bg-destructive/10 p-2 text-destructive">{error}</p>}
+
+      {suggestions && (
+        <div className="flex flex-col gap-1.5 rounded-lg border border-primary/40 bg-primary/5 p-2">
+          <span className="font-medium">
+            {source === "ai" ? "Suggested scenes" : "Scenes from chapters"} -- review, then apply
+          </span>
+          <ol className="flex flex-col gap-1">
+            {suggestions.map((s) => (
+              <li key={s.key} className="flex items-start gap-1.5">
+                <input
+                  type="checkbox"
+                  checked={s.keep}
+                  onChange={(e) => update(s.key, { keep: e.target.checked })}
+                  aria-label={`Keep ${s.title}`}
+                  className="mt-1.5 accent-primary"
+                />
+                <div className="min-w-0 flex-1">
+                  <input
+                    value={s.title}
+                    maxLength={60}
+                    onChange={(e) => update(s.key, { title: e.target.value.replace(/[{}\\]/g, "") })}
+                    aria-label="Scene name"
+                    className="w-full rounded border border-transparent bg-transparent px-1 py-0.5 hover:border-border focus:border-primary focus:outline-none"
+                  />
+                  <button
+                    type="button"
+                    onClick={() => seek(s.at)}
+                    className="flex w-full items-baseline gap-1.5 px-1 text-left text-muted-foreground hover:text-foreground"
+                    title="Jump here"
+                  >
+                    <span className="font-mono tabular-nums">{formatTimecode(s.at)}</span>
+                    {s.onShot && <span className="rounded bg-primary/15 px-1 text-primary">on a cut</span>}
+                    {s.excerpt && <span className="truncate">{s.excerpt}</span>}
+                  </button>
+                </div>
+              </li>
+            ))}
+          </ol>
+          <label className="flex items-center gap-1.5 text-muted-foreground">
+            <input type="checkbox" checked={withCards} onChange={(e) => setWithCards(e.target.checked)} className="accent-primary" />
+            Add a numbered title card to each scene
+          </label>
+          <div className="flex justify-end gap-1.5">
+            <Button variant="ghost" size="xs" onClick={clear}>
+              Dismiss
+            </Button>
+            <Button size="xs" onClick={apply} disabled={keptCount === 0}>
+              Apply {keptCount} scene{keptCount === 1 ? "" : "s"}
+            </Button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/client/src/components/editor/ScenesPanel.tsx b/client/src/components/editor/ScenesPanel.tsx
index 05431ad..a09c015 100644
--- a/client/src/components/editor/ScenesPanel.tsx
+++ b/client/src/components/editor/ScenesPanel.tsx
@@ -11,6 +11,7 @@ import { formatTimecode } from "@/lib/timeline/format";
 import { Button } from "@/components/ui/button";
 import { CardEditor } from "@/components/editor/CardEditor";
 import { TransitionPicker } from "@/components/editor/TransitionPicker";
+import { SceneSuggestions } from "@/components/editor/SceneSuggestions";
 import { CARD_BACKGROUNDS } from "@/lib/cards/layout";
 import type { CardOperation, CardTemplate, CutOperation, TransitionOperation } from "@/types/edit-operation";
 
@@ -126,6 +127,8 @@ export function ScenesPanel() {
         </p>
       </div>
 
+      <SceneSuggestions />
+
       {scenes.length <= 1 && (
         <p className="rounded-lg border border-dashed border-border p-3 text-muted-foreground">
           The whole episode is one scene. Split it at each topic change to name sections, drop whole segments at once,
diff --git a/client/src/components/timeline/Timeline.tsx b/client/src/components/timeline/Timeline.tsx
index 87051b4..12218ff 100644
--- a/client/src/components/timeline/Timeline.tsx
+++ b/client/src/components/timeline/Timeline.tsx
@@ -15,6 +15,7 @@ import { cardTextColor } from "@/lib/cards/layout";
 import { Button } from "@/components/ui/button";
 import { Waveform } from "@/components/timeline/Waveform";
 import { useScenes } from "@/lib/timeline/useScenes";
+import { useSceneSuggestionStore } from "@/stores/scene-suggestion-store";
 import { sceneColor } from "@/lib/timeline/scenes";
 import { Scissors } from "lucide-react";
 
@@ -51,6 +52,8 @@ export function Timeline() {
   const undoStack = useTimelineStore((s) => s.undoStack);
   const redoStack = useTimelineStore((s) => s.redoStack);
   const { scenes, splitAt } = useScenes();
+  const suggestions = useSceneSuggestionStore((s) => s.suggestions);
+  const shots = useSceneSuggestionStore((s) => s.shots);
 
   // Everything on the track is laid out on program time: kept footage with
   // title cards in between (lib/timeline/program.ts).
@@ -302,6 +305,24 @@ export function Timeline() {
                 style={{ width: `${(program.fadeOut.seconds / totalDuration) * 100}%` }}
               />
             )}
+            {/* Suggestions under review (dashed) and detected shot changes (ticks) -- not edits yet. */}
+            {shots?.map((t) => (
+              <div
+                key={`shot-${t}`}
+                className="pointer-events-none absolute bottom-0 h-2 w-px bg-foreground/50"
+                style={{ left: `${percentAt(t)}%` }}
+              />
+            ))}
+            {suggestions
+              ?.filter((s) => s.keep && s.at > 0)
+              .map((s) => (
+                <div
+                  key={`suggestion-${s.key}`}
+                  className="pointer-events-none absolute top-0 h-full border-l-2 border-dashed border-primary"
+                  style={{ left: `${percentAt(s.at, false)}%` }}
+                  title={`Suggested scene: ${s.title}`}
+                />
+              ))}
             {scenes.slice(1).map((scene) => (
               <div
                 key={scene.id}
diff --git a/client/src/lib/scenes/suggestions.test.ts b/client/src/lib/scenes/suggestions.test.ts
new file mode 100644
index 0000000..06b6f90
--- /dev/null
+++ b/client/src/lib/scenes/suggestions.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { operationsForSuggestions, suggestionsFromChapters } from "@/lib/scenes/suggestions";
+import type { EditOperation } from "@/types/edit-operation";
+
+const words = [
+  { start: 0, end: 1 },
+  { start: 50, end: 51 },
+  { start: 60, end: 61 },
+];
+
+describe("suggestionsFromChapters", () => {
+  it("starts the first scene at 0 and later ones in the silence before their chapter", () => {
+    expect(
+      suggestionsFromChapters(
+        [
+          { title: "Setup", sourceStart: 60 },
+          { title: "Intro", sourceStart: 0 },
+        ],
+        words
+      ).map((s) => [s.at, s.title])
+    ).toEqual([
+      [0, "Intro"],
+      [55.5, "Setup"],
+    ]);
+  });
+});
+
+describe("operationsForSuggestions", () => {
+  const suggestions = [
+    { at: 0, title: "Welcome", excerpt: "", onShot: false },
+    { at: 55.5, title: "Setup", excerpt: "", onShot: false },
+    { at: 120, title: "Pricing", excerpt: "", onShot: true },
+  ];
+
+  it("names the first scene, splits at the rest and numbers a card for each", () => {
+    const { added, removedIds } = operationsForSuggestions(suggestions, [], { withCards: true, source: "ai" });
+    expect(removedIds).toEqual([]);
+    expect(added.map((op) => (op.type === "split" ? ["split", op.timestamp, op.title] : ["card", op.type === "card" && op.at, op.type === "card" && op.subtitle]))).toEqual([
+      ["split", 0, "Welcome"],
+      ["split", 55.5, "Setup"],
+      ["card", 55.5, "Part 2"],
+      ["split", 120, "Pricing"],
+      ["card", 120, "Part 3"],
+    ]);
+  });
+
+  it("renames an existing split nearby instead of adding a sliver, and skips cards that exist", () => {
+    const existing: EditOperation[] = [
+      { id: "old", type: "split", timestamp: 55, createdAt: 0 },
+      { id: "card", type: "card", at: 55, duration: 3, template: "title", title: "Mine", background: "#000000", createdAt: 0 },
+    ];
+    const { added, removedIds } = operationsForSuggestions(suggestions.slice(0, 2), existing, {
+      withCards: true,
+      source: "ai",
+    });
+    expect(removedIds).toEqual(["old"]);
+    expect(added).toEqual([
+      expect.objectContaining({ type: "split", timestamp: 0 }),
+      expect.objectContaining({ type: "split", timestamp: 55, title: "Setup" }),
+    ]);
+  });
+
+  it("adds no cards when they're turned off", () => {
+    const { added } = operationsForSuggestions(suggestions, [], { withCards: false, source: "manual" });
+    expect(added.every((op) => op.type === "split")).toBe(true);
+  });
+});
diff --git a/client/src/lib/scenes/suggestions.ts b/client/src/lib/scenes/suggestions.ts
new file mode 100644
index 0000000..d7ea7c4
--- /dev/null
+++ b/client/src/lib/scenes/suggestions.ts
@@ -0,0 +1,85 @@
+import { CARD_BACKGROUNDS } from "@/lib/cards/layout";
+import { gapBefore } from "@/lib/timeline/scenes";
+import type { CardOperation, EditOperation, SplitOperation, SplitSource } from "@/types/edit-operation";
+
+/**
+ * A suggested scene boundary awaiting review (from the server's
+ * lib/scenes/suggest.ts, or built from chapters here). `at` is source
+ * time; 0 only names the first scene.
+ */
+export type SceneSuggestion = {
+  at: number;
+  title: string;
+  excerpt: string;
+  onShot: boolean;
+};
+
+/** An existing split within this of a suggestion is the same boundary. */
+const SAME_BOUNDARY_SECONDS = 1;
+const TITLE_MAX = 60;
+
+/**
+ * Scenes from the episode's chapters -- no AI call: each chapter after the
+ * first starts a scene in the silence before its first word.
+ */
+export function suggestionsFromChapters(
+  chapters: { title: string; sourceStart: number }[],
+  words: { start: number; end: number }[]
+): SceneSuggestion[] {
+  return [...chapters]
+    .sort((a, b) => a.sourceStart - b.sourceStart)
+    .map((chapter, i) => ({
+      at: i === 0 ? 0 : gapBefore(chapter.sourceStart, words),
+      title: chapter.title.slice(0, TITLE_MAX),
+      excerpt: "",
+      onShot: false,
+    }));
+}
+
+/**
+ * The change that applies the kept suggestions, meant to be one undo step.
+ * A suggestion on (or within a second of) an existing split renames that
+ * boundary -- replacing the split -- rather than making a sliver of a
+ * scene; at 0 it names the first scene. With cards on, each scene after
+ * the first gets a chapter card numbered in order ("Part 2", ...), unless
+ * it already has one.
+ */
+export function operationsForSuggestions(
+  suggestions: SceneSuggestion[],
+  existing: EditOperation[],
+  { withCards, source }: { withCards: boolean; source: SplitSource }
+): { added: EditOperation[]; removedIds: string[] } {
+  const splits = existing.filter((op): op is SplitOperation => op.type === "split" && op.timestamp > 0);
+  const cards = existing.filter((op): op is CardOperation => op.type === "card");
+  const now = Date.now();
+  const ops: EditOperation[] = [];
+  const removedIds: string[] = [];
+
+  [...suggestions]
+    .sort((a, b) => a.at - b.at)
+    .forEach((suggestion, i) => {
+      const createdAt = now + i;
+      if (suggestion.at <= 0) {
+        ops.push({ id: crypto.randomUUID(), type: "split", timestamp: 0, title: suggestion.title, source, createdAt });
+        return;
+      }
+      const match = splits.find((s) => Math.abs(s.timestamp - suggestion.at) <= SAME_BOUNDARY_SECONDS);
+      const at = match ? match.timestamp : suggestion.at;
+      if (match && !removedIds.includes(match.id)) removedIds.push(match.id);
+      ops.push({ id: crypto.randomUUID(), type: "split", timestamp: at, title: suggestion.title, source, createdAt });
+      if (withCards && !cards.some((c) => Math.abs(c.at - at) <= 0.05)) {
+        ops.push({
+          id: crypto.randomUUID(),
+          type: "card",
+          at,
+          duration: 3,
+          template: "chapter",
+          title: suggestion.title,
+          subtitle: `Part ${i + 1}`,
+          background: CARD_BACKGROUNDS[0],
+          createdAt,
+        });
+      }
+    });
+  return { added: ops, removedIds };
+}
diff --git a/client/src/stores/scene-suggestion-store.ts b/client/src/stores/scene-suggestion-store.ts
new file mode 100644
index 0000000..d55433d
--- /dev/null
+++ b/client/src/stores/scene-suggestion-store.ts
@@ -0,0 +1,35 @@
+import { create } from "zustand";
+import type { SceneSuggestion } from "@/lib/scenes/suggestions";
+import type { SplitSource } from "@/types/edit-operation";
+
+export type ReviewedSuggestion = SceneSuggestion & { key: string; keep: boolean };
+
+type SceneSuggestionStore = {
+  /** Suggestions awaiting review, or null when there's nothing to review. */
+  suggestions: ReviewedSuggestion[] | null;
+  /** Where they came from, recorded on the splits they become. */
+  source: SplitSource;
+  /** Shot changes from the last detection (source seconds), or null if never run. */
+  shots: number[] | null;
+  setSuggestions: (suggestions: SceneSuggestion[], source: SplitSource) => void;
+  update: (key: string, patch: Partial<Pick<ReviewedSuggestion, "keep" | "title">>) => void;
+  clear: () => void;
+  setShots: (shots: number[] | null) => void;
+};
+
+/**
+ * Scene suggestions under review and detected shot changes: shared by the
+ * Scenes panel (review list) and the timeline (ghost markers). Nothing here
+ * is an edit until the user applies it.
+ */
+export const useSceneSuggestionStore = create<SceneSuggestionStore>((set) => ({
+  suggestions: null,
+  source: "ai",
+  shots: null,
+  setSuggestions: (suggestions, source) =>
+    set({ suggestions: suggestions.map((s, i) => ({ ...s, key: `${i}-${s.at}`, keep: true })), source }),
+  update: (key, patch) =>
+    set((state) => ({ suggestions: state.suggestions?.map((s) => (s.key === key ? { ...s, ...patch } : s)) ?? null })),
+  clear: () => set({ suggestions: null }),
+  setShots: (shots) => set({ shots }),
+}));
diff --git a/client/src/stores/timeline-store.ts b/client/src/stores/timeline-store.ts
index fd90fe3..cf5b93a 100644
--- a/client/src/stores/timeline-store.ts
+++ b/client/src/stores/timeline-store.ts
@@ -22,6 +22,8 @@ type TimelineStore = {
   addSplit: (timestamp: number, title?: string) => void;
   /** Adds several operations as one undo step (they share a groupId). */
   addOperations: (ops: EditOperation[]) => void;
+  /** Adds and removes operations together as one undo step (e.g. applying scene suggestions). */
+  applyChange: (added: EditOperation[], removedIds: string[]) => void;
   /** Swaps one operation for a new version of it, as one undo step. */
   replaceOperation: (operationId: string, next: EditOperation) => void;
   /**
@@ -131,6 +133,13 @@ export const useTimelineStore = create<TimelineStore>((set, get) => {
       commit({ added: ops.map((op) => ({ ...op, groupId })), removed: [] });
     },
 
+    applyChange: (added, removedIds) => {
+      const ids = new Set(removedIds);
+      const removed = get().operations.filter((op) => ids.has(op.id));
+      const groupId = crypto.randomUUID();
+      commit({ added: added.map((op) => ({ ...op, groupId })), removed });
+    },
+
     replaceOperation: (operationId, next) => {
       const current = get().operations.find((op) => op.id === operationId);
       if (!current) return;

From 50684679df2578f66386b6826d16d416fed03b9f Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sat, 26 Sep 2026 02:11:01 +0530
Subject: [PATCH 32/36] docs: document scenes, title cards, transitions and
 B-roll

A new Scenes, Cards & B-roll guide page, a scenes step in the podcast
workflow, status and README entries, the grouped undo, and the scene
endpoints in claude.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                      |  16 ++++++
 claude.md                      |  16 ++++++
 docs/.vitepress/config.ts      |   1 +
 docs/guide/editing-workflow.md |  10 +++-
 docs/guide/podcasting.md       |  20 +++++--
 docs/guide/scenes.md           | 102 +++++++++++++++++++++++++++++++++
 docs/status.md                 |   4 ++
 7 files changed, 160 insertions(+), 9 deletions(-)
 create mode 100644 docs/guide/scenes.md

diff --git a/README.md b/README.md
index c56b892..1729d51 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,22 @@ For podcasts:
   transcript selection; render 9:16 / 1:1 / 16:9 with a positionable crop
   and big word-by-word captions.
 
+Shaping the episode:
+
+- **Scenes** — split at the playhead (**S**) or before any sentence, then
+  name, cut or merge whole scenes. **Suggest scenes** proposes topic
+  changes for review, landed on detected camera cuts; or build scenes
+  from your chapters.
+- **Title cards** — intro, chapter, quote and outro cards between scenes,
+  previewed live and rendered into the export.
+- **Transitions** — dip to black/white, crossfade into a card, and fades
+  in and out of the episode, without shifting anything's timing.
+- **B-roll** — upload images and clips, then cover a transcript selection
+  full screen or picture-in-picture.
+
+Every edit, including bulk ones like "remove all filler words" or applying
+suggested scenes, is a single undo step (**⌘Z** / **⇧⌘Z**).
+
 AI models only ever return text and sentence picks, never timestamps or
 edits: times always come from the transcript's own word timestamps, and
 every response is validated before use. See the
diff --git a/claude.md b/claude.md
index f8416fa..b10f6fc 100644
--- a/claude.md
+++ b/claude.md
@@ -674,6 +674,18 @@ length (`plan.ts#layoutProgram`). The preview draws them with
 `TransitionOverlay` from the pure `transition-look.ts`, on its own
 animation-frame loop; audio fades aren't previewed.
 
+**Scene suggestions** are explicit buttons that only ever propose:
+"Suggest scenes" (gpt-4o-mini, sentence indices and titles only --
+`lib/ai/scenes.ts`, validated by `lib/scenes/suggest.ts`: whole
+sentences, the first scene at 0, at least 45s apart, boundaries in the
+silence before a sentence) and "From chapters" (client-side, no AI).
+Shot-change detection (`lib/ffmpeg/shots.ts`, a `shots` TranscriptionJob
+storing its times in `resultJson`) scores frames at 320px wide; a
+suggestion within 1.5s of a cut -- and not inside a word -- moves onto
+it. The user reviews the list and Apply adds the kept splits (and
+optional numbered chapter cards) as one undo step, renaming a split
+already within 1s instead of adding a sliver.
+
 **B-roll**: `media` assets (many per project, stored under a unique
 prefix, with name/size/length columns) placed by `overlay` operations:
 an asset shown from `start` to `end` in source time (so it follows cuts),
@@ -962,6 +974,10 @@ POST   /api/projects/:id/clips                   PATCH/DELETE /api/projects/:id/
 GET    /api/projects/:id/media                    (media library: images and clips for B-roll)
 POST   /api/projects/:id/media?filename=          (raw body, image/png|jpeg|webp or video/*; probed, refused if unreadable)
 GET    /api/projects/:id/media/:assetId/file      DELETE /api/projects/:id/media/:assetId (409 while B-roll uses it)
+
+POST   /api/projects/:id/scenes/shots            (202 + jobId; background shot-change detection)
+GET    /api/projects/:id/scenes/shots            (latest detection)   GET /api/projects/:id/scenes/shots/:jobId
+POST   /api/projects/:id/scenes/suggest          (gpt-4o-mini scene suggestions for review; never applied server-side)
 ```
 
 (No `POST /api/projects/:id/ai/edit` — the free-text AI command bar this
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index d7ff7e1..b59ff41 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -37,6 +37,7 @@ export default defineConfig({
             { text: "Architecture", link: "/guide/architecture" },
             { text: "Editing Workflow", link: "/guide/editing-workflow" },
             { text: "Podcast Workflow", link: "/guide/podcasting" },
+            { text: "Scenes, Cards & B-roll", link: "/guide/scenes" },
             { text: "AI-Assisted Editing", link: "/guide/ai-editing" },
             { text: "Security & Self-Hosting", link: "/guide/security" },
           ],
diff --git a/docs/guide/editing-workflow.md b/docs/guide/editing-workflow.md
index 7086bab..827a5b7 100644
--- a/docs/guide/editing-workflow.md
+++ b/docs/guide/editing-workflow.md
@@ -58,9 +58,13 @@ across the splice point rather than a hard cut, so the audio doesn't pop.
 ## Undo, redo, and restoring a specific cut
 
 Every edit is represented as an operation, applied in sequence. Undo
-reverts the latest operation; redo re-applies it. Beyond plain undo, you
-can also restore one specific previously-cut word, segment, or sentence
-directly — without having to undo everything after it.
+(**⌘Z**, or the button above the timeline) reverts the latest step; redo
+(**⇧⌘Z**) re-applies it. A step can hold many operations: removing every
+filler word, cutting everything one speaker said, or applying suggested
+scenes each undo in one go, and renaming a scene or restoring a cut can
+be undone too. Beyond plain undo, you can also restore one specific
+previously-cut word, segment, or sentence directly — without having to
+undo everything after it.
 
 The original uploaded video is never mutated for any of this — cuts are
 timeline state (which source ranges map to which timeline ranges), not
diff --git a/docs/guide/podcasting.md b/docs/guide/podcasting.md
index ec3bf1f..02035ea 100644
--- a/docs/guide/podcasting.md
+++ b/docs/guide/podcasting.md
@@ -53,7 +53,15 @@ in chunks. On a 14-minute synthetic 3-voice test conversation it
 labeled **99.9%** of words correctly. Two very similar voices can end up merged into one speaker;
 fix those by renaming, or by relabeling individual segments.
 
-## 4. Make it sound like a podcast
+## 4. Shape it into scenes
+
+Split the episode at each topic change, or let **Suggest scenes** propose
+the splits (optionally lined up with camera cuts from **Find** shot
+changes) and review them. Then give scenes title cards and transitions,
+and cover long talking stretches with B-roll from the **Media** tab. See
+[Scenes, Cards & B-roll](/guide/scenes).
+
+## 5. Make it sound like a podcast
 
 Open the **Audio** tab and click **Make podcast-ready**, or pick settings
 yourself:
@@ -70,7 +78,7 @@ playhead** renders a short **before / after** sample to listen to. The
 settings are applied when you export. Everything is off by default, so
 projects that don't use it export exactly as before.
 
-## 5. Publish
+## 6. Publish
 
 The **Publish** tab prepares everything around the episode:
 
@@ -94,7 +102,7 @@ Chapters are stored against the original recording, so cuts you make
 after generating them don't break them: a chapter whose moment you cut
 moves to the next surviving moment.
 
-## 6. Make Shorts
+## 7. Make Shorts
 
 The **Clips** tab turns the episode into short vertical clips:
 
@@ -122,10 +130,10 @@ key, and each one is a button you press:
 | --- | --- |
 | Transcription | `whisper-1` (OpenAI lists it at $0.006 per minute, about $0.36 per hour of audio) |
 | Speaker detection | `gpt-4o-transcribe-diarize` |
-| Chapters, show notes | `gpt-4o-mini` |
+| Chapters, show notes, scene suggestions | `gpt-4o-mini` |
 | Find highlights | `gpt-5.6-luna` |
 
 Costs for the other steps depend on episode length and current OpenAI
 pricing. Your OpenAI usage dashboard shows exactly what each run cost.
-Audio cleanup, rendering, captions and exports run locally with FFmpeg
-and cost nothing.
+Audio cleanup, shot-change detection, rendering, captions and exports run
+locally with FFmpeg and cost nothing.
diff --git a/docs/guide/scenes.md b/docs/guide/scenes.md
new file mode 100644
index 0000000..a9e3d5a
--- /dev/null
+++ b/docs/guide/scenes.md
@@ -0,0 +1,102 @@
+# Scenes, Cards & B-roll
+
+A raw podcast recording is one long shot. This page covers the tools that
+turn it into something that looks edited: named **scenes**, **title
+cards** between them, **transitions**, and **B-roll** cut in over the
+conversation. They all live in the **Scenes** and **Media** tabs, and
+they're all ordinary edits: undo reverts them, and none of them touch
+your original file.
+
+## Scenes
+
+A scene is a stretch of the episode between two split points, usually
+one topic. Splitting doesn't change what's exported on its own; it gives
+you named sections to work with.
+
+- **Split** at the playhead with the **S** key or the **Split** button
+  above the timeline, or hover a sentence in the transcript and click ✂
+  to start a new scene there. Splits always land in the gap between two
+  words, never inside one.
+- Scenes appear as named blocks above the timeline and as small markers
+  in the transcript.
+- In the **Scenes** tab you can rename a scene, jump to it, cut the whole
+  scene, restore it, or merge it into the one before.
+
+### Let the editor suggest scenes
+
+You don't have to split by hand:
+
+- **Suggest scenes** reads the transcript (with your cuts applied) and
+  suggests where topics change, with a short title for each. It uses
+  `gpt-4o-mini` and only returns sentence numbers and titles; the times
+  always come from the transcript.
+- **Find** (next to "shot changes") detects camera cuts in the video, such
+  as a multicam switch or a screen share starting. Suggestions within 1.5
+  seconds of a cut move onto it, so the scene change is also a visual one.
+  This runs locally with FFmpeg and costs nothing.
+- **From chapters** turns the chapters you generated in the **Publish**
+  tab into scenes, without another AI call.
+
+Suggestions are only a proposal. They appear as a list and as dashed
+lines on the timeline. Untick any you don't want, edit the titles, and
+choose whether to add a numbered title card to each. Then click
+**Apply**. Everything you apply is one step, so a single undo removes it
+all.
+
+## Title cards
+
+A title card is a full-screen slide between scenes: an intro, "Part 2:
+Pricing", a quote, an outro. Add one from a scene's **T** button (the
+first scene's is the intro) or with **Add outro card**.
+
+- Four templates: **Title**, **Chapter** (a small label above a big
+  title), **Quote** and **Outro**.
+- Title and subtitle, 1–10 seconds on screen, preset or custom
+  background colors. The text switches between dark and light to stay
+  readable, and fades in and out.
+- Edits preview live over the player. In playback the video pauses where
+  a card plays, shows it, then carries on.
+- Cards add time to the episode. Captions, chapters, show-note timestamps
+  and transcript exports all account for it.
+- If you cut a whole scene, its card goes with it.
+
+## Transitions
+
+Each scene has a **Transition in**:
+
+- **Dip to black** / **Dip to white**: fade out to the color and back in.
+- **Crossfade with card**: blend straight into and out of the scene's
+  title card (offered once the scene has one).
+
+The first scene has **Fade in** and the outro has **Fade out**, from or
+to black or white. Lengths run from 0.5 to 2 seconds, and audio fades
+gently along with the picture.
+
+Transitions never change the episode's length, so nothing after them
+drifts out of sync. A dip fades each side's own edge, and a crossfade
+makes its card slightly longer by the overlap. They're marked on the
+timeline with a diamond, and episode fades with a shaded edge.
+
+## B-roll
+
+B-roll is footage or images you cut away to while the conversation keeps
+playing: product shots, screen recordings, photos.
+
+1. In the **Media** tab, upload images (PNG, JPG, WEBP) or video clips.
+   Files ffmpeg can't read are refused right away.
+2. Select words in the transcript, then click **Add** on a file to cover
+   exactly those words. With nothing selected, it starts at the playhead.
+3. In the list below the library, switch each piece between **Full
+   screen** and **Picture in picture**, pick the corner, or remove it.
+
+B-roll follows your cuts: cutting part of its range shortens it, and
+cutting all of it removes it. A clip shorter than its slot holds its
+last frame. The B-roll's own audio isn't used. B-roll appears in exports
+and in Shorts made from that part of the episode. A library file can't
+be deleted while B-roll uses it.
+
+## Where things sit in the export
+
+From bottom to top: your footage (with its color preset), title cards and
+transitions, B-roll, card text, captions, then the logo. Cards and B-roll
+aren't affected by the color preset.
diff --git a/docs/status.md b/docs/status.md
index 4f47480..ea42926 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -24,6 +24,10 @@ The timeline shows zoomable frame thumbnails and a live-updating waveform
 | Audio cleanup | -16 / -14 LUFS loudness targets, noise reduction, speaker leveling, rumble filter, 15-second before/after preview. |
 | Publishing | AI chapters (built into MP4/MP3 exports, copyable for YouTube), AI show notes and title ideas, TXT/Markdown transcript, MP3/WAV export. |
 | Clips / Shorts | AI highlight picks or clips from a transcript selection; 9:16, 1:1 or 16:9 with a positionable crop and Shorts-style captions. |
+| Scenes | Split by hand, from chapters, or from AI suggestions (reviewed first, snapped to detected camera cuts); rename, cut or merge whole scenes. |
+| Title cards | Intro, chapter, quote and outro cards, previewed live and rendered into exports; captions and chapters account for their time. |
+| Transitions | Dips to black/white, crossfades into cards, episode fade in/out; never shift timing. |
+| B-roll | Media library of images and clips; cover a transcript selection full screen or picture-in-picture; follows cuts. |
 
 See the [Podcast Workflow](/guide/podcasting) guide for how they fit
 together.

From aaeb6d7efb2e5242ae2392ebaaa4e845eaf430e2 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sun, 27 Sep 2026 19:37:30 +0530
Subject: [PATCH 33/36] feat(server): per-scene frame padding

A `pad` operation shrinks one scene's footage and centres it on a solid
border, keyed by the scene's start like transitions. The output size
never changes, so every segment still matches for the xfade chain; the
padded scene's edges become ordinary cut joins, so the program's length
doesn't change either. Padded projects are graded per segment (as with
cards) so the border keeps its exact color, and only a validated
'#RRGGBB' ever reaches the pad filter.

program.ts changes are mirrored into the client copy, which the preview
will use next.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/lib/timeline/program.test.ts       | 46 +++++++++++++++
 client/src/lib/timeline/program.ts            | 58 +++++++++++++++++--
 client/src/types/edit-operation.ts            | 18 ++++++
 server/src/lib/ffmpeg/plan.test.ts            | 41 +++++++++++++
 server/src/lib/ffmpeg/plan.ts                 | 36 ++++++++++--
 server/src/lib/ffmpeg/render-job.ts           |  4 ++
 server/src/lib/timeline/program.test.ts       | 46 +++++++++++++++
 server/src/lib/timeline/program.ts            | 58 +++++++++++++++++--
 .../src/lib/validation/edit-operation.test.ts | 15 +++++
 server/src/lib/validation/edit-operation.ts   | 11 ++++
 server/src/routes/operations.ts               |  4 ++
 server/src/types/edit-operation.ts            | 18 ++++++
 12 files changed, 343 insertions(+), 12 deletions(-)

diff --git a/client/src/lib/timeline/program.test.ts b/client/src/lib/timeline/program.test.ts
index ca1f694..1b4d91f 100644
--- a/client/src/lib/timeline/program.test.ts
+++ b/client/src/lib/timeline/program.test.ts
@@ -4,6 +4,7 @@ import {
   buildProgramItems,
   isPlainProgram,
   placeOverlays,
+  placePads,
   cardStartTimes,
   cardsDuration,
   editedRangeToProgram,
@@ -194,6 +195,51 @@ describe("transitions", () => {
   });
 });
 
+describe("scene padding", () => {
+  const pad = (at: number, size = 10, createdAt = 0): EditOperation => ({
+    id: `pad-${at}-${createdAt}`,
+    type: "pad",
+    at,
+    size,
+    color: "#ff0000",
+    createdAt,
+  });
+  const build = (ops: EditOperation[], duration = 100) => {
+    const ranges = computePlayableRanges(
+      duration,
+      ops.filter((op): op is CutOperation => op.type === "cut")
+    );
+    return buildProgram(ops, ranges, duration);
+  };
+
+  it("pads only its own scene, splitting the footage at the scene's edges", () => {
+    const p = build([split(40), split(70), pad(40)]);
+    expect(p.items).toEqual([
+      { kind: "source", start: 0, end: 40 },
+      { kind: "source", start: 40, end: 70, pad: { scale: 0.8, color: "#ff0000" } },
+      { kind: "source", start: 70, end: 100 },
+    ]);
+    expect(p.joins).toEqual([{ kind: "cut" }, { kind: "cut" }]);
+    expect(isPlainProgram(p)).toBe(false);
+  });
+
+  it("pads the first scene with a pad at 0, and follows cuts inside the scene", () => {
+    const p = build([split(40), cut(10, 20), pad(0, 5)]);
+    expect(p.items).toEqual([
+      { kind: "source", start: 0, end: 10, pad: { scale: 0.9, color: "#ff0000" } },
+      { kind: "source", start: 20, end: 40, pad: { scale: 0.9, color: "#ff0000" } },
+      { kind: "source", start: 40, end: 100 },
+    ]);
+  });
+
+  it("keeps the latest pad at a scene and ignores one whose split is gone", () => {
+    expect(placePads([split(40), pad(40, 5, 1), pad(40, 20, 2)], 100)).toEqual([
+      { start: 40, end: 100, scale: 0.6, color: "#ff0000" },
+    ]);
+    expect(isPlainProgram(build([pad(40)]))).toBe(true);
+  });
+});
+
 describe("placeOverlays", () => {
   const overlay = (id: string, start: number, end: number): EditOperation => ({
     id,
diff --git a/client/src/lib/timeline/program.ts b/client/src/lib/timeline/program.ts
index 724ada4..8c0fcb0 100644
--- a/client/src/lib/timeline/program.ts
+++ b/client/src/lib/timeline/program.ts
@@ -2,6 +2,7 @@ import type {
   CardOperation,
   EditOperation,
   OverlayOperation,
+  PadOperation,
   SplitOperation,
   TransitionOperation,
 } from "@/types/edit-operation";
@@ -34,8 +35,11 @@ export type CardSlot = {
   resumeAt: number;
 };
 
+/** Frame padding on a stretch of footage: shrunk to `scale` of the frame, centred on `color`. */
+export type ItemPad = { scale: number; color: string };
+
 export type ProgramItem =
-  | { kind: "source"; start: number; end: number }
+  | { kind: "source"; start: number; end: number; pad?: ItemPad }
   | { kind: "card"; card: CardOperation };
 
 export function cardOperations(operations: EditOperation[]): CardOperation[] {
@@ -283,6 +287,38 @@ export function resolveJoins(items: ProgramItem[], markers: TransitionMarker[]):
   return joins;
 }
 
+/** A padded scene, in source time. */
+export type ScenePad = ItemPad & { start: number; end: number };
+
+/** A pad op belongs to the scene starting within this of its `at`. */
+const PAD_MATCH_SECONDS = 0.05;
+
+/**
+ * The padded scenes, in source time. A pad applies to the scene starting
+ * at its `at` (the latest one there wins); one whose split was removed
+ * matches no scene and is ignored.
+ */
+export function placePads(operations: EditOperation[], sourceDuration: number): ScenePad[] {
+  const starts = [0, ...splitTimes(operations)];
+  const pads: ScenePad[] = [];
+  starts.forEach((start, i) => {
+    const pad = operations
+      .filter((op): op is PadOperation => op.type === "pad" && Math.abs(op.at - start) <= PAD_MATCH_SECONDS)
+      .sort((a, b) => a.createdAt - b.createdAt)
+      .at(-1);
+    const end = starts[i + 1] ?? sourceDuration;
+    if (pad && end > start + EPSILON) {
+      pads.push({ start, end, scale: 1 - (2 * pad.size) / 100, color: pad.color });
+    }
+  });
+  return pads;
+}
+
+/** The pad covering a source time, if any. */
+export function padAt(pads: ScenePad[], time: number): ScenePad | null {
+  return pads.find((p) => time >= p.start && time < p.end) ?? null;
+}
+
 /** Everything that plays, and how it's stitched together. */
 export type Program = {
   slots: CardSlot[];
@@ -291,6 +327,7 @@ export type Program = {
   fadeIn: Fade | null;
   fadeOut: Fade | null;
   overlays: PlacedOverlay[];
+  pads: ScenePad[];
 };
 
 /** B-roll on the program timeline. */
@@ -327,11 +364,22 @@ export function placeOverlays(
 export function buildProgram(operations: EditOperation[], ranges: PlayableRange[], sourceDuration: number): Program {
   const slots = placeCards(operations, ranges, sourceDuration);
   const { markers, fadeIn, fadeOut } = placeTransitions(operations, ranges, sourceDuration);
+  const pads = placePads(operations, sourceDuration);
+  // A padded scene's edges become item boundaries, so each item is either
+  // padded or not; they join with a plain cut, like any other boundary.
+  const padEdges = pads
+    .flatMap((p) => [p.start, p.end])
+    .filter((t) => ranges.some((r) => t > r.start + EPSILON && t < r.end - EPSILON))
+    .map((t) => sourceTimeToEditedTime(t, ranges));
   const items = buildProgramItems(
     ranges,
     slots,
-    markers.map((m) => m.editedAt)
-  );
+    [...markers.map((m) => m.editedAt), ...padEdges]
+  ).map((item) => {
+    if (item.kind !== "source") return item;
+    const pad = padAt(pads, (item.start + item.end) / 2);
+    return pad ? { ...item, pad: { scale: pad.scale, color: pad.color } } : item;
+  });
   return {
     slots,
     items,
@@ -339,6 +387,7 @@ export function buildProgram(operations: EditOperation[], ranges: PlayableRange[
     fadeIn,
     fadeOut,
     overlays: placeOverlays(operations, ranges, slots),
+    pads,
   };
 }
 
@@ -348,7 +397,8 @@ export function isPlainProgram(program: Program): boolean {
     program.slots.length === 0 &&
     !program.fadeIn &&
     !program.fadeOut &&
-    program.joins.every((j) => j.kind === "cut")
+    program.joins.every((j) => j.kind === "cut") &&
+    program.items.every((item) => item.kind === "card" || !item.pad)
   );
 }
 
diff --git a/client/src/types/edit-operation.ts b/client/src/types/edit-operation.ts
index fca20a5..85015a3 100644
--- a/client/src/types/edit-operation.ts
+++ b/client/src/types/edit-operation.ts
@@ -82,6 +82,20 @@ export type EditOperation =
       /** Seconds into a video asset to start from. */
       offset?: number;
     })
+  | (OperationBase & {
+      /**
+       * Frame padding for the scene starting at `at`: the footage is shrunk
+       * by `size`% of the frame on each side and centred on a solid border.
+       * The output size never changes; cards, B-roll, captions and the logo
+       * are unaffected. See lib/timeline/program.ts#placePads.
+       */
+      type: "pad";
+      at: number;
+      /** Border width as a percent of the frame, per side. */
+      size: number;
+      /** '#RRGGBB' */
+      color: string;
+    })
   | (OperationBase & {
       type: "caption";
       text: string;
@@ -111,8 +125,12 @@ export type OverlayMode = (typeof OVERLAY_MODES)[number];
 export const OVERLAY_CORNERS = ["top-left", "top-right", "bottom-left", "bottom-right"] as const;
 export type OverlayCorner = (typeof OVERLAY_CORNERS)[number];
 
+export const PAD_MIN_PERCENT = 2;
+export const PAD_MAX_PERCENT = 25;
+
 export type CutOperation = Extract<EditOperation, { type: "cut" }>;
 export type SplitOperation = Extract<EditOperation, { type: "split" }>;
 export type CardOperation = Extract<EditOperation, { type: "card" }>;
 export type TransitionOperation = Extract<EditOperation, { type: "transition" }>;
 export type OverlayOperation = Extract<EditOperation, { type: "overlay" }>;
+export type PadOperation = Extract<EditOperation, { type: "pad" }>;
diff --git a/server/src/lib/ffmpeg/plan.test.ts b/server/src/lib/ffmpeg/plan.test.ts
index 9d50435..8d0e1f6 100644
--- a/server/src/lib/ffmpeg/plan.test.ts
+++ b/server/src/lib/ffmpeg/plan.test.ts
@@ -523,6 +523,47 @@ describe("transitions", () => {
   });
 });
 
+describe("scene padding", () => {
+  const items = [
+    { kind: "source" as const, start: 0, end: 10 },
+    { kind: "source" as const, start: 10, end: 20, pad: { scale: 0.8, color: "#ff0000" } },
+  ];
+  const program = { items, joins: [{ kind: "cut" as const }], fadeIn: null, fadeOut: null };
+  const padFrame = { width: 1920, height: 1080 };
+  const graph = (extra: Partial<Parameters<typeof buildRenderArgs>[0]> = {}) => {
+    const args = buildRenderArgs({ ...baseArgs, program, padFrame, ...extra });
+    return args[args.indexOf("-filter_complex") + 1];
+  };
+
+  it("shrinks a padded scene and pads it back out to the source's size", () => {
+    expect(graph()).toContain(
+      "[0:v]trim=start=10.000:end=20.000" +
+        ",setpts=PTS-STARTPTS,fps=30000/1001,format=yuv420p,setsar=1,scale=1536:864,pad=1920:1080:(ow-iw)/2:(oh-ih)/2:color=0xFF0000,setsar=1[v1]"
+    );
+  });
+
+  it("leaves unpadded scenes at full frame and grades per segment so the border keeps its color", () => {
+    const g = graph({ filterId: "bw" });
+    expect(g).toContain("[0:v]trim=start=0.000:end=10.000,setpts=PTS-STARTPTS,hue=s=0");
+    expect(g.split(";").find((chain) => chain.endsWith("[v0]"))).not.toContain(",pad=");
+    expect(g).not.toContain("[outv]hue");
+  });
+
+  it("refuses padding without the frame size, and bad values", () => {
+    expect(() => buildRenderArgs({ ...baseArgs, program })).toThrow(/frame size/);
+    const bad = (pad: { scale: number; color: string }) => ({
+      ...program,
+      items: [items[0], { ...items[1], pad }],
+    });
+    expect(() => buildRenderArgs({ ...baseArgs, program: bad({ scale: 0.8, color: "red" }), padFrame })).toThrow(
+      /padding color/
+    );
+    expect(() => buildRenderArgs({ ...baseArgs, program: bad({ scale: 1.2, color: "#ff0000" }), padFrame })).toThrow(
+      /padding size/
+    );
+  });
+});
+
 describe("B-roll", () => {
   const frame = { width: 1920, height: 1080 };
   const video = {
diff --git a/server/src/lib/ffmpeg/plan.ts b/server/src/lib/ffmpeg/plan.ts
index 122939b..2682802 100644
--- a/server/src/lib/ffmpeg/plan.ts
+++ b/server/src/lib/ffmpeg/plan.ts
@@ -1,5 +1,5 @@
 import type { PlayableRange } from "@/types/timeline";
-import type { Fade, Join, ProgramItem } from "@/lib/timeline/program";
+import type { Fade, ItemPad, Join, ProgramItem } from "@/lib/timeline/program";
 import { OVERLAY_CORNERS, type OverlayCorner, type OverlayMode } from "@/types/edit-operation";
 import { getFfmpegFilter } from "@/lib/ffmpeg/filters";
 import { buildPropertiesFilter } from "@/lib/ffmpeg/properties";
@@ -365,6 +365,20 @@ const PIP_INSET_FRACTION = 0.04;
 
 const even = (n: number) => Math.max(2, Math.round(n / 2) * 2);
 
+/**
+ * Scene padding: shrink the footage to `scale` of the frame and centre it
+ * on a solid border, back at the full frame size. The color is only ever
+ * a validated '#RRGGBB'.
+ */
+export function buildPadFilter(pad: ItemPad, frame: { width: number; height: number }): string {
+  if (!Number.isFinite(pad.scale) || pad.scale < 0.4 || pad.scale >= 1) throw new Error("Invalid padding size.");
+  if (!/^#[0-9a-fA-F]{6}$/.test(pad.color)) throw new Error("Invalid padding color.");
+  const w = even(frame.width * pad.scale);
+  const h = even(frame.height * pad.scale);
+  const color = pad.color.slice(1).toUpperCase();
+  return `scale=${w}:${h},pad=${frame.width}:${frame.height}:(ow-iw)/2:(oh-ih)/2:color=0x${color},setsar=1`;
+}
+
 function assertValidOverlay(o: RenderOverlay): void {
   if (!o.path) throw new Error("B-roll has no file.");
   if (![o.start, o.end, o.offset].every(Number.isFinite) || o.start < 0 || o.end <= o.start || o.offset < 0) {
@@ -525,6 +539,12 @@ export function buildRenderArgs(args: {
    */
   program?: RenderProgram;
   cardFrame?: { width: number; height: number; textPath: string };
+  /**
+   * The source's frame size, needed when a scene is padded: its footage is
+   * shrunk and padded back out to exactly this size, so every segment
+   * still matches for xfade.
+   */
+  padFrame?: { width: number; height: number };
   /**
    * B-roll to composite, on the program timeline, and the source frame
    * size it's laid out on (applied before any reframe, so a clip crops
@@ -553,6 +573,7 @@ export function buildRenderArgs(args: {
     frameRate,
     program,
     cardFrame,
+    padFrame,
     broll,
   } = args;
 
@@ -561,6 +582,12 @@ export function buildRenderArgs(args: {
   if (!/^\d{1,6}(\/\d{1,6})?$/.test(frameRate)) throw new Error(`Invalid frame rate: ${frameRate}`);
   if (withCards && !cardFrame) throw new Error("Title cards need the source's frame size.");
   if (cardFrame) assertValidCardFrame(cardFrame);
+  const withPads = items.some((item) => item.kind === "source" && item.pad);
+  if (withPads && !padFrame) throw new Error("Scene padding needs the source's frame size.");
+  if (padFrame) assertValidCardFrame(padFrame);
+  // Cards and padded scenes are graded per source segment, so a card or
+  // border keeps its exact chosen color.
+  const perSegment = withCards || withPads;
 
   const presetFilter = getFfmpegFilter(filterId);
   const propertiesFilter = properties ? buildPropertiesFilter(properties) : null;
@@ -585,7 +612,7 @@ export function buildRenderArgs(args: {
   items.forEach((item, i) => {
     const pad = i < items.length - 1 ? `,${SEGMENT_TAIL_PAD}` : "";
     const fades = videoFades(layout, i);
-    if (!withCards) {
+    if (!perSegment) {
       const r = item as Extract<ProgramItem, { kind: "source" }>;
       filterChains.push(
         `[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS,fps=${frameRate}${fades}${pad}[v${i}]`
@@ -597,8 +624,9 @@ export function buildRenderArgs(args: {
     // turn a blue card grey).
     if (item.kind === "source") {
       const grade = colorFilter ? `,${colorFilter}` : "";
+      const border = item.pad ? `,${buildPadFilter(item.pad, padFrame!)}` : "";
       filterChains.push(
-        `[0:v]trim=start=${item.start.toFixed(3)}:end=${item.end.toFixed(3)},setpts=PTS-STARTPTS${grade},fps=${frameRate},${CARD_VIDEO_FORMAT}${fades}${pad}[v${i}]`
+        `[0:v]trim=start=${item.start.toFixed(3)}:end=${item.end.toFixed(3)},setpts=PTS-STARTPTS${grade},fps=${frameRate},${CARD_VIDEO_FORMAT}${border}${fades}${pad}[v${i}]`
       );
     } else {
       const color = item.card.background.slice(1).toUpperCase();
@@ -642,7 +670,7 @@ export function buildRenderArgs(args: {
   }
 
   let videoOutLabel = "[outv]";
-  if (colorFilter && !withCards) {
+  if (colorFilter && !perSegment) {
     filterChains.push(`[outv]${colorFilter}[filtered]`);
     videoOutLabel = "[filtered]";
   }
diff --git a/server/src/lib/ffmpeg/render-job.ts b/server/src/lib/ffmpeg/render-job.ts
index c57f98c..b188c33 100644
--- a/server/src/lib/ffmpeg/render-job.ts
+++ b/server/src/lib/ffmpeg/render-job.ts
@@ -258,6 +258,9 @@ export async function runRenderJob(
       cardFrame = { width: sourceStream.width, height: sourceStream.height, textPath };
     }
 
+    const hasPads = program?.items.some((item) => item.kind === "source" && item.pad) ?? false;
+    const padFrame = hasPads && sourceStream ? { width: sourceStream.width, height: sourceStream.height } : undefined;
+
     if (burnInCaptions) {
       if (!project.transcript) throw new Error("Captions were requested but this project has no transcript.");
       const transcript: Transcript = {
@@ -328,6 +331,7 @@ export async function runRenderJob(
           frameRate: sourceStream!.fps,
           program,
           cardFrame,
+          padFrame,
           broll:
             sourceStream && brollOverlays.length > 0
               ? { frame: { width: sourceStream.width, height: sourceStream.height }, overlays: brollOverlays }
diff --git a/server/src/lib/timeline/program.test.ts b/server/src/lib/timeline/program.test.ts
index ca1f694..1b4d91f 100644
--- a/server/src/lib/timeline/program.test.ts
+++ b/server/src/lib/timeline/program.test.ts
@@ -4,6 +4,7 @@ import {
   buildProgramItems,
   isPlainProgram,
   placeOverlays,
+  placePads,
   cardStartTimes,
   cardsDuration,
   editedRangeToProgram,
@@ -194,6 +195,51 @@ describe("transitions", () => {
   });
 });
 
+describe("scene padding", () => {
+  const pad = (at: number, size = 10, createdAt = 0): EditOperation => ({
+    id: `pad-${at}-${createdAt}`,
+    type: "pad",
+    at,
+    size,
+    color: "#ff0000",
+    createdAt,
+  });
+  const build = (ops: EditOperation[], duration = 100) => {
+    const ranges = computePlayableRanges(
+      duration,
+      ops.filter((op): op is CutOperation => op.type === "cut")
+    );
+    return buildProgram(ops, ranges, duration);
+  };
+
+  it("pads only its own scene, splitting the footage at the scene's edges", () => {
+    const p = build([split(40), split(70), pad(40)]);
+    expect(p.items).toEqual([
+      { kind: "source", start: 0, end: 40 },
+      { kind: "source", start: 40, end: 70, pad: { scale: 0.8, color: "#ff0000" } },
+      { kind: "source", start: 70, end: 100 },
+    ]);
+    expect(p.joins).toEqual([{ kind: "cut" }, { kind: "cut" }]);
+    expect(isPlainProgram(p)).toBe(false);
+  });
+
+  it("pads the first scene with a pad at 0, and follows cuts inside the scene", () => {
+    const p = build([split(40), cut(10, 20), pad(0, 5)]);
+    expect(p.items).toEqual([
+      { kind: "source", start: 0, end: 10, pad: { scale: 0.9, color: "#ff0000" } },
+      { kind: "source", start: 20, end: 40, pad: { scale: 0.9, color: "#ff0000" } },
+      { kind: "source", start: 40, end: 100 },
+    ]);
+  });
+
+  it("keeps the latest pad at a scene and ignores one whose split is gone", () => {
+    expect(placePads([split(40), pad(40, 5, 1), pad(40, 20, 2)], 100)).toEqual([
+      { start: 40, end: 100, scale: 0.6, color: "#ff0000" },
+    ]);
+    expect(isPlainProgram(build([pad(40)]))).toBe(true);
+  });
+});
+
 describe("placeOverlays", () => {
   const overlay = (id: string, start: number, end: number): EditOperation => ({
     id,
diff --git a/server/src/lib/timeline/program.ts b/server/src/lib/timeline/program.ts
index 724ada4..8c0fcb0 100644
--- a/server/src/lib/timeline/program.ts
+++ b/server/src/lib/timeline/program.ts
@@ -2,6 +2,7 @@ import type {
   CardOperation,
   EditOperation,
   OverlayOperation,
+  PadOperation,
   SplitOperation,
   TransitionOperation,
 } from "@/types/edit-operation";
@@ -34,8 +35,11 @@ export type CardSlot = {
   resumeAt: number;
 };
 
+/** Frame padding on a stretch of footage: shrunk to `scale` of the frame, centred on `color`. */
+export type ItemPad = { scale: number; color: string };
+
 export type ProgramItem =
-  | { kind: "source"; start: number; end: number }
+  | { kind: "source"; start: number; end: number; pad?: ItemPad }
   | { kind: "card"; card: CardOperation };
 
 export function cardOperations(operations: EditOperation[]): CardOperation[] {
@@ -283,6 +287,38 @@ export function resolveJoins(items: ProgramItem[], markers: TransitionMarker[]):
   return joins;
 }
 
+/** A padded scene, in source time. */
+export type ScenePad = ItemPad & { start: number; end: number };
+
+/** A pad op belongs to the scene starting within this of its `at`. */
+const PAD_MATCH_SECONDS = 0.05;
+
+/**
+ * The padded scenes, in source time. A pad applies to the scene starting
+ * at its `at` (the latest one there wins); one whose split was removed
+ * matches no scene and is ignored.
+ */
+export function placePads(operations: EditOperation[], sourceDuration: number): ScenePad[] {
+  const starts = [0, ...splitTimes(operations)];
+  const pads: ScenePad[] = [];
+  starts.forEach((start, i) => {
+    const pad = operations
+      .filter((op): op is PadOperation => op.type === "pad" && Math.abs(op.at - start) <= PAD_MATCH_SECONDS)
+      .sort((a, b) => a.createdAt - b.createdAt)
+      .at(-1);
+    const end = starts[i + 1] ?? sourceDuration;
+    if (pad && end > start + EPSILON) {
+      pads.push({ start, end, scale: 1 - (2 * pad.size) / 100, color: pad.color });
+    }
+  });
+  return pads;
+}
+
+/** The pad covering a source time, if any. */
+export function padAt(pads: ScenePad[], time: number): ScenePad | null {
+  return pads.find((p) => time >= p.start && time < p.end) ?? null;
+}
+
 /** Everything that plays, and how it's stitched together. */
 export type Program = {
   slots: CardSlot[];
@@ -291,6 +327,7 @@ export type Program = {
   fadeIn: Fade | null;
   fadeOut: Fade | null;
   overlays: PlacedOverlay[];
+  pads: ScenePad[];
 };
 
 /** B-roll on the program timeline. */
@@ -327,11 +364,22 @@ export function placeOverlays(
 export function buildProgram(operations: EditOperation[], ranges: PlayableRange[], sourceDuration: number): Program {
   const slots = placeCards(operations, ranges, sourceDuration);
   const { markers, fadeIn, fadeOut } = placeTransitions(operations, ranges, sourceDuration);
+  const pads = placePads(operations, sourceDuration);
+  // A padded scene's edges become item boundaries, so each item is either
+  // padded or not; they join with a plain cut, like any other boundary.
+  const padEdges = pads
+    .flatMap((p) => [p.start, p.end])
+    .filter((t) => ranges.some((r) => t > r.start + EPSILON && t < r.end - EPSILON))
+    .map((t) => sourceTimeToEditedTime(t, ranges));
   const items = buildProgramItems(
     ranges,
     slots,
-    markers.map((m) => m.editedAt)
-  );
+    [...markers.map((m) => m.editedAt), ...padEdges]
+  ).map((item) => {
+    if (item.kind !== "source") return item;
+    const pad = padAt(pads, (item.start + item.end) / 2);
+    return pad ? { ...item, pad: { scale: pad.scale, color: pad.color } } : item;
+  });
   return {
     slots,
     items,
@@ -339,6 +387,7 @@ export function buildProgram(operations: EditOperation[], ranges: PlayableRange[
     fadeIn,
     fadeOut,
     overlays: placeOverlays(operations, ranges, slots),
+    pads,
   };
 }
 
@@ -348,7 +397,8 @@ export function isPlainProgram(program: Program): boolean {
     program.slots.length === 0 &&
     !program.fadeIn &&
     !program.fadeOut &&
-    program.joins.every((j) => j.kind === "cut")
+    program.joins.every((j) => j.kind === "cut") &&
+    program.items.every((item) => item.kind === "card" || !item.pad)
   );
 }
 
diff --git a/server/src/lib/validation/edit-operation.test.ts b/server/src/lib/validation/edit-operation.test.ts
index 8cde1a0..5f0524b 100644
--- a/server/src/lib/validation/edit-operation.test.ts
+++ b/server/src/lib/validation/edit-operation.test.ts
@@ -145,6 +145,21 @@ describe("editOperationSchema", () => {
     });
   });
 
+  describe("pad", () => {
+    const pad = { id: "p1", type: "pad", at: 30, size: 10, color: "#112233", createdAt: 0 };
+
+    it("accepts a size in range and a hex color", () => {
+      expect(editOperationSchema.safeParse(pad).success).toBe(true);
+    });
+
+    it("rejects out-of-range sizes and colors that aren't '#RRGGBB'", () => {
+      expect(editOperationSchema.safeParse({ ...pad, size: 1 }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...pad, size: 40 }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...pad, color: "red" }).success).toBe(false);
+      expect(editOperationSchema.safeParse({ ...pad, color: "#112233:x=1" }).success).toBe(false);
+    });
+  });
+
   describe("overlay", () => {
     const overlay = { id: "o1", type: "overlay", assetId: "cmabc123", start: 10, end: 15, mode: "pip", corner: "top-right", createdAt: 0 };
 
diff --git a/server/src/lib/validation/edit-operation.ts b/server/src/lib/validation/edit-operation.ts
index 5251dd1..9d207cd 100644
--- a/server/src/lib/validation/edit-operation.ts
+++ b/server/src/lib/validation/edit-operation.ts
@@ -7,6 +7,8 @@ import {
   CARD_TITLE_MAX,
   OVERLAY_CORNERS,
   OVERLAY_MODES,
+  PAD_MAX_PERCENT,
+  PAD_MIN_PERCENT,
   TRANSITION_KINDS,
   TRANSITION_MAX_SECONDS,
   TRANSITION_MIN_SECONDS,
@@ -92,6 +94,15 @@ export const editOperationSchema = z.discriminatedUnion("type", [
     createdAt: z.number(),
     groupId: z.string().min(1).max(100).optional(),
   }),
+  z.object({
+    id: z.string().min(1),
+    type: z.literal("pad"),
+    at: z.number().nonnegative(),
+    size: z.number().min(PAD_MIN_PERCENT).max(PAD_MAX_PERCENT),
+    color: z.string().regex(/^#[0-9a-fA-F]{6}$/),
+    createdAt: z.number(),
+    groupId: z.string().min(1).max(100).optional(),
+  }),
   z.object({
     id: z.string().min(1),
     type: z.literal("caption"),
diff --git a/server/src/routes/operations.ts b/server/src/routes/operations.ts
index 3353f65..5cd2e26 100644
--- a/server/src/routes/operations.ts
+++ b/server/src/routes/operations.ts
@@ -40,6 +40,10 @@ operationsRoute.post("/:id/operations", async (c) => {
   if (op.type === "transition" && project.duration && op.at > project.duration) {
     return errorResponse(c, "INVALID_OPERATION", "Transition must be placed inside the video.", 400);
   }
+  // Padding belongs to a scene, which always starts before the end.
+  if (op.type === "pad" && project.duration && op.at >= project.duration) {
+    return errorResponse(c, "INVALID_OPERATION", "Padding must be placed inside the video.", 400);
+  }
   if (op.type === "overlay") {
     if (project.duration && op.end > project.duration + 0.01) {
       return errorResponse(c, "INVALID_OPERATION", "B-roll must end inside the video.", 400);
diff --git a/server/src/types/edit-operation.ts b/server/src/types/edit-operation.ts
index fca20a5..85015a3 100644
--- a/server/src/types/edit-operation.ts
+++ b/server/src/types/edit-operation.ts
@@ -82,6 +82,20 @@ export type EditOperation =
       /** Seconds into a video asset to start from. */
       offset?: number;
     })
+  | (OperationBase & {
+      /**
+       * Frame padding for the scene starting at `at`: the footage is shrunk
+       * by `size`% of the frame on each side and centred on a solid border.
+       * The output size never changes; cards, B-roll, captions and the logo
+       * are unaffected. See lib/timeline/program.ts#placePads.
+       */
+      type: "pad";
+      at: number;
+      /** Border width as a percent of the frame, per side. */
+      size: number;
+      /** '#RRGGBB' */
+      color: string;
+    })
   | (OperationBase & {
       type: "caption";
       text: string;
@@ -111,8 +125,12 @@ export type OverlayMode = (typeof OVERLAY_MODES)[number];
 export const OVERLAY_CORNERS = ["top-left", "top-right", "bottom-left", "bottom-right"] as const;
 export type OverlayCorner = (typeof OVERLAY_CORNERS)[number];
 
+export const PAD_MIN_PERCENT = 2;
+export const PAD_MAX_PERCENT = 25;
+
 export type CutOperation = Extract<EditOperation, { type: "cut" }>;
 export type SplitOperation = Extract<EditOperation, { type: "split" }>;
 export type CardOperation = Extract<EditOperation, { type: "card" }>;
 export type TransitionOperation = Extract<EditOperation, { type: "transition" }>;
 export type OverlayOperation = Extract<EditOperation, { type: "overlay" }>;
+export type PadOperation = Extract<EditOperation, { type: "pad" }>;

From 4cf17d2ec55af95b5f3c1cf139bc31d514091059 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sun, 27 Sep 2026 19:39:12 +0530
Subject: [PATCH 34/36] feat(client): per-scene padding picker and preview

Each scene row in the Scenes panel gets a Padding size and a border
color, stored as one `pad` operation per scene, so every change is one
undo step. Merging a scene drops its padding with its boundary.

The preview shrinks the <video> and shows the border color behind it,
switched on the video's live time in an animation-frame loop (like
TransitionOverlay), so it changes exactly at the scene boundary. A
focused clip previews without padding, as clips export without it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/components/editor/PaddingPicker.tsx   | 101 ++++++++++++++++++
 client/src/components/editor/ScenesPanel.tsx  |  24 ++++-
 .../components/video-player/PaddingLayer.tsx  |  66 ++++++++++++
 .../components/video-player/VideoPlayer.tsx   |   4 +-
 client/src/lib/timeline/useProgram.ts         |   5 +-
 5 files changed, 195 insertions(+), 5 deletions(-)
 create mode 100644 client/src/components/editor/PaddingPicker.tsx
 create mode 100644 client/src/components/video-player/PaddingLayer.tsx

diff --git a/client/src/components/editor/PaddingPicker.tsx b/client/src/components/editor/PaddingPicker.tsx
new file mode 100644
index 0000000..828dbcd
--- /dev/null
+++ b/client/src/components/editor/PaddingPicker.tsx
@@ -0,0 +1,101 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { useTimelineStore } from "@/stores/timeline-store";
+import { CARD_BACKGROUNDS } from "@/lib/cards/layout";
+import type { PadOperation } from "@/types/edit-operation";
+
+const SIZES = [
+  { value: 5, label: "Small" },
+  { value: 10, label: "Medium" },
+  { value: 15, label: "Large" },
+  { value: 20, label: "Extra large" },
+];
+/** A dragged color picker fires on every move; wait for it to settle before saving. */
+const COLOR_SETTLE_MS = 400;
+const selectClass =
+  "h-6 rounded border border-border bg-transparent px-1 text-[0.7rem] text-foreground focus:border-primary focus:outline-none";
+
+/**
+ * Picks the frame padding for the scene starting at `at`: the footage
+ * shrinks by the chosen size on each side and sits on a solid border. One
+ * operation per scene; choosing "None" removes it. Every change is one
+ * undo step.
+ */
+export function PaddingPicker({ at, current }: { at: number; current: PadOperation | undefined }) {
+  const addOperations = useTimelineStore((s) => s.addOperations);
+  const replaceOperation = useTimelineStore((s) => s.replaceOperation);
+  const removeOperations = useTimelineStore((s) => s.removeOperations);
+  const [draftColor, setDraftColor] = useState<string | null>(null);
+  const settle = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => () => {
+    if (settle.current) clearTimeout(settle.current);
+  }, []);
+
+  const save = (size: number | null, color: string) => {
+    if (size === null) {
+      if (current) removeOperations([current.id]);
+      return;
+    }
+    const next: PadOperation = { id: crypto.randomUUID(), type: "pad", at, size, color, createdAt: Date.now() };
+    if (current) replaceOperation(current.id, next);
+    else addOperations([next]);
+  };
+
+  const color = draftColor ?? current?.color ?? CARD_BACKGROUNDS[0];
+
+  const pickColor = (next: string) => {
+    setDraftColor(next);
+    if (settle.current) clearTimeout(settle.current);
+    settle.current = setTimeout(() => {
+      setDraftColor(null);
+      if (current) save(current.size, next);
+    }, COLOR_SETTLE_MS);
+  };
+
+  return (
+    <div className="flex flex-col gap-1 text-muted-foreground">
+      <label className="flex items-center gap-1.5">
+        <span className="shrink-0">Padding</span>
+        <select
+          value={current?.size ?? "none"}
+          onChange={(e) => save(e.target.value === "none" ? null : Number(e.target.value), color)}
+          className={`${selectClass} min-w-0 flex-1`}
+          aria-label="Padding"
+        >
+          <option value="none">None</option>
+          {SIZES.map((s) => (
+            <option key={s.value} value={s.value}>
+              {s.label} ({s.value}%)
+            </option>
+          ))}
+        </select>
+      </label>
+      {current && (
+        <div className="flex items-center gap-1.5">
+          <span className="shrink-0">Border</span>
+          {CARD_BACKGROUNDS.map((swatch) => (
+            <button
+              key={swatch}
+              type="button"
+              onClick={() => save(current.size, swatch)}
+              title={swatch}
+              className={`size-4 rounded-full border ${
+                color.toUpperCase() === swatch ? "ring-2 ring-primary ring-offset-1 ring-offset-card" : "border-border"
+              }`}
+              style={{ backgroundColor: swatch }}
+            />
+          ))}
+          <input
+            type="color"
+            value={color}
+            onChange={(e) => pickColor(e.target.value)}
+            aria-label="Custom border color"
+            className="h-5 w-6 cursor-pointer rounded border border-border bg-transparent"
+          />
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/client/src/components/editor/ScenesPanel.tsx b/client/src/components/editor/ScenesPanel.tsx
index a09c015..8716915 100644
--- a/client/src/components/editor/ScenesPanel.tsx
+++ b/client/src/components/editor/ScenesPanel.tsx
@@ -11,9 +11,16 @@ import { formatTimecode } from "@/lib/timeline/format";
 import { Button } from "@/components/ui/button";
 import { CardEditor } from "@/components/editor/CardEditor";
 import { TransitionPicker } from "@/components/editor/TransitionPicker";
+import { PaddingPicker } from "@/components/editor/PaddingPicker";
 import { SceneSuggestions } from "@/components/editor/SceneSuggestions";
 import { CARD_BACKGROUNDS } from "@/lib/cards/layout";
-import type { CardOperation, CardTemplate, CutOperation, TransitionOperation } from "@/types/edit-operation";
+import type {
+  CardOperation,
+  CardTemplate,
+  CutOperation,
+  PadOperation,
+  TransitionOperation,
+} from "@/types/edit-operation";
 
 /** A card at a scene's start (within this) belongs to that scene. */
 const CARD_MATCH_SECONDS = 0.05;
@@ -56,6 +63,15 @@ export function ScenesPanel() {
   );
   /** The transition in effect at a moment: the latest one there. */
   const transitionAt = (at: number) => transitions.filter((t) => Math.abs(t.at - at) <= CARD_MATCH_SECONDS).at(-1);
+  const pads = useMemo(
+    () =>
+      operations
+        .filter((op): op is PadOperation => op.type === "pad")
+        .sort((a, b) => a.createdAt - b.createdAt),
+    [operations]
+  );
+  /** The padding in effect for the scene starting at a moment: the latest one there. */
+  const padsAt = (at: number) => pads.filter((p) => Math.abs(p.at - at) <= CARD_MATCH_SECONDS);
   const outroCards = cards.filter((c) => c.at >= duration - CARD_MATCH_SECONDS);
   const activeScene = sceneAt(scenes, currentTime);
 
@@ -196,7 +212,8 @@ export function ScenesPanel() {
                       <Button
                         variant="ghost"
                         size="icon-xs"
-                        onClick={() => removeOperations([scene.splitId!])}
+                        // The scene's padding goes with its boundary, or it would come back on a later split here.
+                        onClick={() => removeOperations([scene.splitId!, ...padsAt(scene.start).map((p) => p.id)])}
                         title="Merge into previous scene"
                       >
                         <Merge className="size-3" />
@@ -223,7 +240,7 @@ export function ScenesPanel() {
                 {cardsAt(scene.index === 0 ? 0 : scene.start).length > 0 && (
                   <div className="flex flex-col gap-1 pl-3.5">{cardList(cardsAt(scene.index === 0 ? 0 : scene.start))}</div>
                 )}
-                <div className="pl-3.5">
+                <div className="flex flex-col gap-1 pl-3.5">
                   {scene.index === 0 ? (
                     <TransitionPicker label="Fade in" at={0} edge="in" current={transitionAt(0)} />
                   ) : (
@@ -234,6 +251,7 @@ export function ScenesPanel() {
                       canCrossfade={cardsAt(scene.start).length > 0}
                     />
                   )}
+                  <PaddingPicker at={scene.start} current={padsAt(scene.start).at(-1)} />
                 </div>
               </li>
             );
diff --git a/client/src/components/video-player/PaddingLayer.tsx b/client/src/components/video-player/PaddingLayer.tsx
new file mode 100644
index 0000000..6ec3f5f
--- /dev/null
+++ b/client/src/components/video-player/PaddingLayer.tsx
@@ -0,0 +1,66 @@
+import { useEffect, useRef, type RefObject } from "react";
+import { useClipStore } from "@/stores/clip-store";
+import { usePlayerStore } from "@/stores/player-store";
+import { padAt } from "@/lib/timeline/program";
+import type { Program } from "@/lib/timeline/useProgram";
+
+/**
+ * Previews scene padding: shrinks the <video> about its center and shows
+ * the border color behind it, over the video's own on-screen rectangle
+ * (sized like CropOverlay, so the letterbox bars outside the frame stay
+ * uncolored). Driven by its own animation-frame loop reading the video's
+ * live time and styled through refs, like TransitionOverlay, so the
+ * padding switches exactly at the scene boundary without re-rendering.
+ * Clips skip padding in the export, so a focused clip previews without it.
+ */
+export function PaddingLayer({
+  videoRef,
+  program,
+}: {
+  videoRef: RefObject<HTMLVideoElement | null>;
+  program: Program;
+}) {
+  const frameRef = useRef<HTMLDivElement>(null);
+  const sourceRatio = usePlayerStore((s) => s.aspectRatio);
+  const clipFocused = useClipStore((s) => s.focused !== null);
+
+  useEffect(() => {
+    const video = videoRef.current;
+    if (program.pads.length === 0 || clipFocused) {
+      if (video) video.style.transform = "";
+      if (frameRef.current) frameRef.current.style.opacity = "0";
+      return;
+    }
+    let frame = 0;
+    const tick = () => {
+      const v = videoRef.current;
+      if (v) {
+        const pad = padAt(program.pads, v.currentTime);
+        v.style.transform = pad ? `scale(${pad.scale})` : "";
+        if (frameRef.current) {
+          frameRef.current.style.opacity = pad ? "1" : "0";
+          if (pad) frameRef.current.style.backgroundColor = pad.color;
+        }
+      }
+      frame = requestAnimationFrame(tick);
+    };
+    frame = requestAnimationFrame(tick);
+    return () => {
+      cancelAnimationFrame(frame);
+      if (video) video.style.transform = "";
+    };
+  }, [videoRef, program, clipFocused]);
+
+  if (!sourceRatio) return null;
+  return (
+    <div
+      ref={frameRef}
+      className="pointer-events-none absolute inset-0 m-auto"
+      style={{
+        width: `min(100cqw, calc(100cqh * ${sourceRatio}))`,
+        height: `min(100cqh, calc(100cqw / ${sourceRatio}))`,
+        opacity: 0,
+      }}
+    />
+  );
+}
diff --git a/client/src/components/video-player/VideoPlayer.tsx b/client/src/components/video-player/VideoPlayer.tsx
index 97bc8e3..30f4106 100644
--- a/client/src/components/video-player/VideoPlayer.tsx
+++ b/client/src/components/video-player/VideoPlayer.tsx
@@ -12,6 +12,7 @@ import { locateProgramTime } from "@/lib/timeline/program";
 import { programPlayhead, useProgram } from "@/lib/timeline/useProgram";
 import { useCardPlayback } from "@/components/video-player/useCardPlayback";
 import { CardPreview } from "@/components/video-player/CardPreview";
+import { PaddingLayer } from "@/components/video-player/PaddingLayer";
 import { TransitionOverlay } from "@/components/video-player/TransitionOverlay";
 import { BrollLayer } from "@/components/video-player/BrollLayer";
 import { generateCaptions } from "@/lib/captions/generate";
@@ -298,10 +299,11 @@ export function VideoPlayer({ videoUrl }: { videoUrl: string }) {
         the same way ffmpeg's PlayResY does for the export (GitHub #22).
       */}
       <div className="relative min-h-0 flex-1 overflow-hidden [container-type:size]">
+        <PaddingLayer videoRef={videoRef} program={program} />
         <video
           ref={videoRef}
           src={videoUrl}
-          className="h-full w-full object-contain"
+          className="relative h-full w-full object-contain"
           style={{ filter: filterCss }}
           onLoadedMetadata={(e) => handleDurationKnown(e.currentTarget)}
           onTimeUpdate={handleTimeUpdate}
diff --git a/client/src/lib/timeline/useProgram.ts b/client/src/lib/timeline/useProgram.ts
index 97425a8..8015e62 100644
--- a/client/src/lib/timeline/useProgram.ts
+++ b/client/src/lib/timeline/useProgram.ts
@@ -11,6 +11,7 @@ import {
   type Join,
   type PlacedOverlay,
   type ProgramItem,
+  type ScenePad,
 } from "@/lib/timeline/program";
 import type { CutOperation } from "@/types/edit-operation";
 import type { PlayableRange } from "@/types/timeline";
@@ -26,6 +27,8 @@ export type Program = {
   fadeOut: Fade | null;
   /** B-roll on the program timeline. */
   overlays: PlacedOverlay[];
+  /** Padded scenes, in source time. */
+  pads: ScenePad[];
   editedDuration: number;
   /** Edited duration plus every card: what the export runs for. */
   duration: number;
@@ -42,7 +45,7 @@ export function useProgram(): Program {
     const program =
       sourceDuration > 0
         ? buildProgram(operations, ranges, sourceDuration)
-        : { slots: [], items: [], joins: [], fadeIn: null, fadeOut: null, overlays: [] };
+        : { slots: [], items: [], joins: [], fadeIn: null, fadeOut: null, overlays: [], pads: [] };
     const editedDuration = getEditedDuration(ranges);
     return {
       cuts,

From 93ea0f6a7905289dac826884404ab2344bd04c4a Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sun, 27 Sep 2026 19:42:12 +0530
Subject: [PATCH 35/36] feat(client): press / in the transcript to start a
 scene

Splitting by playhead means scrubbing to the right spot first; in a
transcript-first editor the natural place to mark a scene boundary is
the text itself. Clicking a word now also sets a cursor before it, and
pressing / starts a new scene there -- in the gap before the word, via
the same splitAt as every other split, so the minimum-scene-length guard
and undo work unchanged. With no cursor, / splits at the playhead like S.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 client/src/components/editor/ScenesPanel.tsx    |  5 +++--
 .../src/components/editor/useEditorShortcuts.ts | 17 ++++++++++++++++-
 .../components/transcript/TranscriptPanel.tsx   | 14 ++++++++++++++
 client/src/stores/transcript-store.ts           |  7 ++++++-
 4 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/client/src/components/editor/ScenesPanel.tsx b/client/src/components/editor/ScenesPanel.tsx
index 8716915..c9c79f3 100644
--- a/client/src/components/editor/ScenesPanel.tsx
+++ b/client/src/components/editor/ScenesPanel.tsx
@@ -138,8 +138,9 @@ export function ScenesPanel() {
           Split scene at playhead
         </Button>
         <p className="text-muted-foreground">
-          Or press <kbd className="rounded border border-border px-1 font-mono">S</kbd>. Splits land between words, never
-          inside one.
+          Or press <kbd className="rounded border border-border px-1 font-mono">S</kbd>, or click a word in the
+          transcript and press <kbd className="rounded border border-border px-1 font-mono">/</kbd>. Splits land
+          between words, never inside one.
         </p>
       </div>
 
diff --git a/client/src/components/editor/useEditorShortcuts.ts b/client/src/components/editor/useEditorShortcuts.ts
index 25b2331..a4402af 100644
--- a/client/src/components/editor/useEditorShortcuts.ts
+++ b/client/src/components/editor/useEditorShortcuts.ts
@@ -1,14 +1,20 @@
 import { useEffect } from "react";
 import { usePlayerStore } from "@/stores/player-store";
 import { useTimelineStore } from "@/stores/timeline-store";
+import { useTranscriptStore } from "@/stores/transcript-store";
 import { useScenes } from "@/lib/timeline/useScenes";
+import { gapBefore } from "@/lib/timeline/scenes";
 
 function isTyping(target: EventTarget | null): boolean {
   if (!(target instanceof HTMLElement)) return false;
   return target.isContentEditable || ["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName);
 }
 
-/** Editor-wide keys: S splits a scene at the playhead, Cmd/Ctrl+Z undoes, Shift+Cmd/Ctrl+Z redoes. */
+/**
+ * Editor-wide keys: S splits a scene at the playhead, / splits right
+ * before the transcript's cursor word (or at the playhead with no cursor),
+ * Cmd/Ctrl+Z undoes, Shift+Cmd/Ctrl+Z redoes.
+ */
 export function useEditorShortcuts() {
   const undo = useTimelineStore((s) => s.undo);
   const redo = useTimelineStore((s) => s.redo);
@@ -25,6 +31,15 @@ export function useEditorShortcuts() {
       } else if (!mod && !e.altKey && e.key.toLowerCase() === "s") {
         e.preventDefault();
         splitAt(usePlayerStore.getState().currentTime);
+      } else if (!mod && !e.altKey && e.key === "/") {
+        // No shiftKey check: on some layouts "/" is itself a shifted key.
+        e.preventDefault();
+        const { transcript, caretWordId, setCaret, clearSelection } = useTranscriptStore.getState();
+        const words = transcript?.segments.flatMap((s) => s.words) ?? [];
+        const word = words.find((w) => w.id === caretWordId);
+        splitAt(word ? gapBefore(word.start, words) : usePlayerStore.getState().currentTime);
+        setCaret(null);
+        clearSelection();
       }
     };
     document.addEventListener("keydown", onKeyDown);
diff --git a/client/src/components/transcript/TranscriptPanel.tsx b/client/src/components/transcript/TranscriptPanel.tsx
index c87b48a..0014188 100644
--- a/client/src/components/transcript/TranscriptPanel.tsx
+++ b/client/src/components/transcript/TranscriptPanel.tsx
@@ -28,6 +28,8 @@ export function TranscriptPanel() {
   const toggleWordSelection = useTranscriptStore((s) => s.toggleWordSelection);
   const selectWordRange = useTranscriptStore((s) => s.selectWordRange);
   const clearSelection = useTranscriptStore((s) => s.clearSelection);
+  const caretWordId = useTranscriptStore((s) => s.caretWordId);
+  const setCaret = useTranscriptStore((s) => s.setCaret);
   const fillerWordIds = useTranscriptStore((s) => s.fillerWordIds);
   const setSegmentSpeaker = useTranscriptStore((s) => s.setSegmentSpeaker);
 
@@ -69,6 +71,7 @@ export function TranscriptPanel() {
       selectWordRange(selectedWordIds[0], wordId);
     } else {
       toggleWordSelection(wordId);
+      setCaret(wordId);
     }
   };
 
@@ -162,6 +165,11 @@ export function TranscriptPanel() {
           )}
         </div>
       </div>
+      {caretWordId && (
+        <p className="-mt-1.5 text-[0.7rem] text-muted-foreground">
+          Press <kbd className="rounded border border-border px-1 font-mono">/</kbd> to start a new scene at the cursor.
+        </p>
+      )}
       <SpeakersBar />
       <datalist id="speaker-suggestions">
         {existingSpeakers.map((name) => (
@@ -259,6 +267,12 @@ export function TranscriptPanel() {
                                   {sceneStart.title}
                                 </button>
                               )}
+                              {caretWordId === word.id && !cut && (
+                                <span
+                                  aria-hidden
+                                  className="mr-px inline-block h-[1.1em] w-0.5 translate-y-[0.2em] animate-pulse rounded-full bg-primary"
+                                />
+                              )}
                               <span
                                 onClick={(e) => {
                                   if (cut) {
diff --git a/client/src/stores/transcript-store.ts b/client/src/stores/transcript-store.ts
index 1ae3905..a64a4c0 100644
--- a/client/src/stores/transcript-store.ts
+++ b/client/src/stores/transcript-store.ts
@@ -6,6 +6,8 @@ type TranscriptStore = {
   transcript: Transcript | null;
   /** ids of words currently selected for deletion, in click order */
   selectedWordIds: string[];
+  /** The last word clicked: pressing "/" starts a new scene right before it (useEditorShortcuts). */
+  caretWordId: string | null;
   /** ids of words flagged as filler by the last detection pass */
   fillerWordIds: string[];
   detectingFillerWords: boolean;
@@ -16,6 +18,7 @@ type TranscriptStore = {
   toggleWordSelection: (wordId: string) => void;
   selectWordRange: (fromWordId: string, toWordId: string) => void;
   clearSelection: () => void;
+  setCaret: (wordId: string | null) => void;
   setFillerWordIds: (ids: string[]) => void;
   setDetectingFillerWords: (detecting: boolean) => void;
   setSilenceGaps: (gaps: SilenceGap[] | null) => void;
@@ -26,12 +29,13 @@ type TranscriptStore = {
 export const useTranscriptStore = create<TranscriptStore>((set, get) => ({
   transcript: null,
   selectedWordIds: [],
+  caretWordId: null,
   fillerWordIds: [],
   detectingFillerWords: false,
   silenceGaps: null,
 
   setTranscript: (transcript) =>
-    set({ transcript, selectedWordIds: [], fillerWordIds: [], silenceGaps: null }),
+    set({ transcript, selectedWordIds: [], caretWordId: null, fillerWordIds: [], silenceGaps: null }),
 
   toggleWordSelection: (wordId) =>
     set((s) => ({
@@ -52,6 +56,7 @@ export const useTranscriptStore = create<TranscriptStore>((set, get) => ({
   },
 
   clearSelection: () => set({ selectedWordIds: [] }),
+  setCaret: (caretWordId) => set({ caretWordId }),
 
   setFillerWordIds: (fillerWordIds) => set({ fillerWordIds }),
   setDetectingFillerWords: (detectingFillerWords) => set({ detectingFillerWords }),

From ef69351e875ccf9011d537c74b626ef541ced8e5 Mon Sep 17 00:00:00 2001
From: amide-init <aminuddin01697@gmail.com>
Date: Sun, 27 Sep 2026 19:42:37 +0530
Subject: [PATCH 36/36] docs: scene padding and slash split

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 claude.md            | 16 ++++++++++++++++
 docs/guide/scenes.md | 19 +++++++++++++++----
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/claude.md b/claude.md
index b10f6fc..acc4219 100644
--- a/claude.md
+++ b/claude.md
@@ -674,6 +674,22 @@ length (`plan.ts#layoutProgram`). The preview draws them with
 `TransitionOverlay` from the pure `transition-look.ts`, on its own
 animation-frame loop; audio fades aren't previewed.
 
+**Scene padding**: a `pad` operation (`at` = a scene start, `size`
+2-25% per side, `color` '#RRGGBB') shrinks that scene's footage and
+centres it on a solid border; the output size never changes. Scenes are
+matched and the latest pad wins like transitions
+(`program.ts#placePads`); a padded scene's edges become ordinary cut
+joins in the program, so its length doesn't change either. Rendered per
+segment after the grade (`plan.ts#buildPadFilter`: scale, then `pad`
+back to the source size, so xfade inputs still match); card, B-roll,
+caption and logo layers are unaffected, and clips skip it. Merging a
+scene removes its padding. The preview (`PaddingLayer`) scales the
+`<video>` over the border color on its own animation-frame loop.
+
+In the transcript, clicking a word sets a cursor before it and `/`
+starts a new scene there (`useEditorShortcuts`, via `gapBefore` +
+`splitAt`); with no cursor `/` splits at the playhead like `S`.
+
 **Scene suggestions** are explicit buttons that only ever propose:
 "Suggest scenes" (gpt-4o-mini, sentence indices and titles only --
 `lib/ai/scenes.ts`, validated by `lib/scenes/suggest.ts`: whole
diff --git a/docs/guide/scenes.md b/docs/guide/scenes.md
index a9e3d5a..ac9d8cd 100644
--- a/docs/guide/scenes.md
+++ b/docs/guide/scenes.md
@@ -15,8 +15,9 @@ you named sections to work with.
 
 - **Split** at the playhead with the **S** key or the **Split** button
   above the timeline, or hover a sentence in the transcript and click ✂
-  to start a new scene there. Splits always land in the gap between two
-  words, never inside one.
+  to start a new scene there. Or click any word in the transcript and
+  press **/** to start a new scene right before it. Splits always land in
+  the gap between two words, never inside one.
 - Scenes appear as named blocks above the timeline and as small markers
   in the transcript.
 - In the **Scenes** tab you can rename a scene, jump to it, cut the whole
@@ -77,6 +78,14 @@ drifts out of sync. A dip fades each side's own edge, and a crossfade
 makes its card slightly longer by the overlap. They're marked on the
 timeline with a diamond, and episode fades with a shaded edge.
 
+## Padding
+
+Each scene has a **Padding** setting: Small, Medium, Large or Extra
+large (5-20% of the frame on each side). The scene's footage shrinks and
+sits centred on a solid border. Pick the border from the swatches or any
+custom color. The video keeps its size and length, and only that scene is
+padded. Merging the scene into the one before removes its padding.
+
 ## B-roll
 
 B-roll is footage or images you cut away to while the conversation keeps
@@ -97,6 +106,8 @@ be deleted while B-roll uses it.
 
 ## Where things sit in the export
 
-From bottom to top: your footage (with its color preset), title cards and
+From bottom to top: your footage (with its color preset and any scene
+padding), title cards and
 transitions, B-roll, card text, captions, then the logo. Cards and B-roll
-aren't affected by the color preset.
+aren't affected by the color preset, and the padding border keeps its
+exact color. Clips don't include scene padding.