From a55c731978f5159cb1fced747af777608f6ecde2 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Sun, 30 Aug 2026 21:03:52 -0400
Subject: [PATCH 01/19] =?UTF-8?q?feat(webv2):=20Ref2VA=20reference-extend?=
 =?UTF-8?q?=20=E2=80=94=20append=20the=20generation=20to=20an=20initial=20?=
 =?UTF-8?q?video?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Ref2VA panel gains an Initial Video section: the generated clip is
appended to the uploaded video at its End Frame cutpoint (same
extract + crossfade video_concat join as FL2VA extend; video_concat rebuilds
the soundtrack from every input, so both clips' audio survives). Continuity
comes from a linked video reference the panel derives from the clip — its
trim defaults to the last 141 frames (~5s at 24 fps, exactly on the 17n+5
grid) before the cutpoint and re-derives whenever the cutpoints change,
while remaining an ordinary reference card: trimmable, reorderable,
conditioning-selectable, counted against the 3-video cap, and badged as
linked. No frame conditioning and no backend changes; generation_mode stays
minimax_h3_ref2v with the extend-style source_video extras riding along.

State-wise, references and sourceVideo now coexist (validation still
rejects the pair on models without reference-extend, and references remain
exclusive with first/last frames). Switching FL2VA -> Ref2VA carries an
initial video over and derives its tail reference; switching back clears
references and keeps the clip for FL2VA extend. Recall restores both the
references and the source video with its recorded trim, and the linkage
re-establishes by clip identity when the recalled trims are next edited.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S4B5exWsbC2z2Uu2tA167A
---
 .../frontend/webv2/public/locales/en.json     |  2 +
 .../src/features/video/core/graph.test.ts     | 62 ++++++++++++++
 .../webv2/src/features/video/core/graph.ts    | 51 +++++++++---
 .../src/features/video/core/settings.test.ts  | 75 ++++++++++++++++-
 .../webv2/src/features/video/core/settings.ts | 81 +++++++++++++++++--
 .../webv2/src/features/video/core/types.ts    | 27 ++++++-
 .../features/video/core/videoPolicies.test.ts | 63 ++++++++++++++-
 .../src/features/video/core/videoPolicies.ts  | 33 ++++++--
 .../video/ui/VideoReferenceListField.tsx      |  5 ++
 .../src/features/video/ui/VideoWidgetView.tsx | 43 ++++++++--
 .../image-actions/executeVideoRecall.ts       | 17 ++--
 .../image-actions/videoRecall.test.ts         | 25 ++++++
 .../workbench/image-actions/videoRecall.ts    | 10 ++-
 13 files changed, 449 insertions(+), 45 deletions(-)

diff --git a/invokeai/frontend/webv2/public/locales/en.json b/invokeai/frontend/webv2/public/locales/en.json
index a98c3237249..09e35472ee4 100644
--- a/invokeai/frontend/webv2/public/locales/en.json
+++ b/invokeai/frontend/webv2/public/locales/en.json
@@ -3163,6 +3163,8 @@
       "referenceConditioningVideoAudio": "Video + audio",
       "referenceDetailMatch": "Match generation size",
       "referenceDetailMax": "Max detail (2048px, slower)",
+      "referenceExtendHelp": "The generated video is appended to this clip at its End Frame. A linked video reference samples the last ~5 seconds (141 frames) before that cutpoint for continuity — its trim re-derives whenever the cutpoints change.",
+      "referenceFromInitialVideo": "Initial video",
       "references": "References",
       "referencesHelp": "Up to 3 videos and 9 images condition the generation, in order — reordering references changes the result. A video reference can contribute its image track, its soundtrack, or both.",
       "removeReference": "Remove reference",
diff --git a/invokeai/frontend/webv2/src/features/video/core/graph.test.ts b/invokeai/frontend/webv2/src/features/video/core/graph.test.ts
index 448ed53f836..d2f4acbba91 100644
--- a/invokeai/frontend/webv2/src/features/video/core/graph.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/graph.test.ts
@@ -563,4 +563,66 @@ describe('compileVideoGraph — MiniMax H3 Ref2VA', () => {
     expect(nodesOfType(backendGraph, 'minimax_h3_reference_conditioning')).toHaveLength(0);
     expect(nodesOfType(backendGraph, 'collect')).toHaveLength(0);
   });
+
+  it('reference-extend: appends the new clip to the initial video without frame conditioning', () => {
+    const initialVideo = {
+      endFrame: 400,
+      fps: 24,
+      height: 480,
+      numFrames: 402,
+      startFrame: 10,
+      video_name: 'long.mp4',
+      width: 832,
+    };
+    const settings = {
+      ...referenceSettings,
+      references: [
+        // The linked tail reference (as the setter derives it) plus a user reference.
+        {
+          clip: { ...initialVideo, endFrame: 400, startFrame: 260 },
+          conditioning: 'video_audio' as const,
+          fromSourceVideo: true,
+          kind: 'video' as const,
+        },
+        ...referenceSettings.references,
+      ],
+      sourceVideo: initialVideo,
+    };
+    const { backendGraph } = compileVideoGraph(settings, model);
+
+    // The new clip is intermediate; the crossfade concat is the output, fed
+    // [trimmed source, new clip]; the source is retimed to H3's fixed 24 fps.
+    expect(nodeOfType(backendGraph, 'minimax_h3_latents_to_video')).toMatchObject({
+      id: 'extension_clip',
+      is_intermediate: true,
+    });
+    expect(nodeOfType(backendGraph, 'video_concat')).toMatchObject({ id: 'video_output', transition: 'crossfade' });
+    expect(nodeOfType(backendGraph, 'extract_video_range')).toMatchObject({ end_frame: -2, fps: 24, start_frame: 10 });
+    expect(hasEdge(backendGraph, 'source_video', 'video', 'source_clip_collect', 'item')).toBe(true);
+    expect(hasEdge(backendGraph, 'extension_clip', 'video', 'clips_to_join', 'item')).toBe(true);
+
+    // Continuity comes from the references — no frame conditioning, no last-frame extraction.
+    expect(nodesOfType(backendGraph, 'minimax_h3_frame_conditioning')).toHaveLength(0);
+    expect(nodesOfType(backendGraph, 'video_frame_extract')).toHaveLength(0);
+
+    // The linked reference is an ordinary first reference; the flag never reaches metadata.
+    const videoReferences = nodesOfType(backendGraph, 'minimax_h3_video_reference');
+
+    expect(videoReferences[0]).toMatchObject({ id: 'reference_1', start_frame: 260 });
+    const metadata = nodeOfType(backendGraph, 'core_metadata');
+
+    expect(metadata.generation_mode).toBe('minimax_h3_ref2v');
+    expect(metadata).toMatchObject({
+      source_video: { video_name: 'long.mp4' },
+      source_video_end_frame: 400,
+      source_video_start_frame: 10,
+    });
+    expect((metadata.minimax_h3_references as Record<string, unknown>[])[0]).toEqual({
+      conditioning: 'video_audio',
+      end_frame: 260 + 140,
+      kind: 'video',
+      start_frame: 260,
+      video_name: 'long.mp4',
+    });
+  });
 });
diff --git a/invokeai/frontend/webv2/src/features/video/core/graph.ts b/invokeai/frontend/webv2/src/features/video/core/graph.ts
index 08fc2509444..d31ac4bb66f 100644
--- a/invokeai/frontend/webv2/src/features/video/core/graph.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/graph.ts
@@ -131,7 +131,12 @@ const toTailAwareIndex = (frame: number, estimatedNumFrames: number): number =>
   return tailOffset <= 3 ? -(tailOffset + 1) : frame;
 };
 
-const addExtendScaffolding = (
+/**
+ * Trimmed source extraction + [source, new clip] crossfade join — the shared
+ * core of FL2VA/Wan extend and Ref2VA reference-extend. video_concat rebuilds
+ * the soundtrack from every input, so both clips' audio survives the join.
+ */
+const addSourceJoin = (
   graph: BackendGraphContract,
   sourceVideo: NonNullable<VideoSettings['sourceVideo']>,
   newClip: BackendInvocationContract,
@@ -147,13 +152,6 @@ const addExtendScaffolding = (
     video: { video_name: sourceVideo.video_name },
     ...(options.extractFps === undefined ? {} : { fps: options.extractFps }),
   });
-  const lastFrame = addNode(graph, {
-    frame_index: -1,
-    id: 'source_last_frame',
-    is_intermediate: true,
-    type: 'video_frame_extract',
-    use_cache: false,
-  });
   const sourceCollect = addNode(graph, { id: 'source_clip_collect', type: 'collect' });
   const clipsCollect = addNode(graph, { id: 'clips_to_join', type: 'collect' });
   const concat = addNode(graph, {
@@ -166,13 +164,32 @@ const addExtendScaffolding = (
     use_cache: false,
   });
 
-  addEdge(graph, extract, 'video', lastFrame, 'video');
   // Chained collectors keep the join order deterministic: [trimmed source, new clip].
   addEdge(graph, extract, 'video', sourceCollect, 'item');
   addEdge(graph, sourceCollect, 'collection', clipsCollect, 'collection');
   addEdge(graph, newClip, 'video', clipsCollect, 'item');
   addEdge(graph, clipsCollect, 'collection', concat, 'videos');
 
+  return { concat, extract };
+};
+
+const addExtendScaffolding = (
+  graph: BackendGraphContract,
+  sourceVideo: NonNullable<VideoSettings['sourceVideo']>,
+  newClip: BackendInvocationContract,
+  options: { extractFps?: number } = {}
+) => {
+  const { concat, extract } = addSourceJoin(graph, sourceVideo, newClip, options);
+  const lastFrame = addNode(graph, {
+    frame_index: -1,
+    id: 'source_last_frame',
+    is_intermediate: true,
+    type: 'video_frame_extract',
+    use_cache: false,
+  });
+
+  addEdge(graph, extract, 'video', lastFrame, 'video');
+
   return { concat, extract, lastFrame };
 };
 
@@ -527,6 +544,7 @@ const buildMiniMaxH3VideoGraph = (settings: VideoSettings, model: MainModelConfi
 
   let output: BackendInvocationContract;
   let extendParts: { lastFrame: BackendInvocationContract; newClip: BackendInvocationContract } | null = null;
+  let referenceExtendClip: BackendInvocationContract | null = null;
 
   if (mode === 'extend' && settings.sourceVideo && frameConditioning) {
     const newClip = addLatentsToVideo('extension_clip', true);
@@ -538,6 +556,15 @@ const buildMiniMaxH3VideoGraph = (settings: VideoSettings, model: MainModelConfi
     addEdge(graph, lastFrame, 'image', frameConditioning, 'first_image');
     output = concat;
     extendParts = { lastFrame, newClip };
+  } else if (mode === 'reference' && settings.sourceVideo) {
+    // Reference-extend: the new clip is appended to the trimmed Initial
+    // Video. Continuity comes from the references (typically the linked tail
+    // reference), not from frame conditioning, so no last frame is extracted.
+    const newClip = addLatentsToVideo('extension_clip', true);
+    const { concat } = addSourceJoin(graph, settings.sourceVideo, newClip, { extractFps: 24 });
+
+    output = concat;
+    referenceExtendClip = newClip;
   } else {
     output = addLatentsToVideo('video_output', false);
   }
@@ -567,7 +594,11 @@ const buildMiniMaxH3VideoGraph = (settings: VideoSettings, model: MainModelConfi
     height: dimensions.height,
     model,
     negativeWired: false,
-    outputs: extendParts ? [output, extendParts.newClip] : [output],
+    outputs: extendParts
+      ? [output, extendParts.newClip]
+      : referenceExtendClip
+        ? [output, referenceExtendClip]
+        : [output],
     settings,
     width: dimensions.width,
   });
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index e217bf361c3..3a73a63fa25 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -3,9 +3,11 @@ import { describe, expect, it } from 'vitest';
 import type { VideoSettings } from './types';
 
 import {
+  applyReferenceExtendSourceVideo,
   clearDeletedVideoMedia,
   cloneVideoWidgetValues,
   createVideoSourceClip,
+  deriveReferenceExtendClip,
   isVideoSettings,
   isVideoSourceClip,
   normalizeVideoSettings,
@@ -319,14 +321,16 @@ describe('references', () => {
     );
   });
 
-  it('normalization drops frame/source media when references are present', () => {
+  it('normalization drops frame media when references are present, keeping the source video', () => {
     const normalized = normalizeVideoSettings(
       createSettings({ firstFrameImage: FIRST_FRAME, references: [IMAGE_REFERENCE], sourceVideo: SOURCE_VIDEO })
     );
 
     expect(normalized?.references).toEqual([IMAGE_REFERENCE]);
     expect(normalized?.firstFrameImage).toBeNull();
-    expect(normalized?.sourceVideo).toBeNull();
+    // References + source video is the Ref2VA reference-extend shape;
+    // validation rejects the pair on models that cannot consume it.
+    expect(normalized?.sourceVideo).toEqual(SOURCE_VIDEO);
   });
 
   it('normalization drops malformed entries and enforces the caps, preserving order', () => {
@@ -378,3 +382,70 @@ describe('references', () => {
     expect(sweptVideo.references).toEqual([IMAGE_REFERENCE]);
   });
 });
+
+describe('reference-extend linkage', () => {
+  const longSource = { ...SOURCE_VIDEO, endFrame: 400, numFrames: 402, video_name: 'long.mp4' };
+
+  it('derives the tail trim: 141 frames inclusive ending at the cutpoint, clamped at 0', () => {
+    expect(deriveReferenceExtendClip(longSource)).toMatchObject({ endFrame: 400, startFrame: 260 });
+    // Shorter than the tail window: sample from the clip's own start.
+    expect(deriveReferenceExtendClip(SOURCE_VIDEO)).toMatchObject({ endFrame: 79, startFrame: 0 });
+  });
+
+  it('prepends a linked video+audio reference and re-derives it on cutpoint changes', () => {
+    const added = applyReferenceExtendSourceVideo([IMAGE_REFERENCE], longSource, 3);
+
+    expect(added).toHaveLength(2);
+    expect(added[0]).toMatchObject({
+      clip: { endFrame: 400, startFrame: 260, video_name: 'long.mp4' },
+      conditioning: 'video_audio',
+      fromSourceVideo: true,
+      kind: 'video',
+    });
+
+    // The user tunes the conditioning, then moves the cutpoint: the trim
+    // re-derives, the position and conditioning survive.
+    const tuned = added.map((entry, index) =>
+      index === 0 && entry.kind === 'video' ? { ...entry, conditioning: 'video' as const } : entry
+    );
+    const retrimmed = applyReferenceExtendSourceVideo(tuned, { ...longSource, endFrame: 300 }, 3);
+
+    expect(retrimmed[0]).toMatchObject({
+      clip: { endFrame: 300, startFrame: 160 },
+      conditioning: 'video',
+      fromSourceVideo: true,
+    });
+    expect(retrimmed[1]).toBe(added[1]);
+  });
+
+  it('clearing the initial video removes only the linked reference (identity-preserving when none)', () => {
+    const list = applyReferenceExtendSourceVideo([VIDEO_REFERENCE, IMAGE_REFERENCE], longSource, 3);
+
+    expect(applyReferenceExtendSourceVideo(list, null, 3)).toEqual([VIDEO_REFERENCE, IMAGE_REFERENCE]);
+
+    const unlinked = [VIDEO_REFERENCE, IMAGE_REFERENCE];
+
+    expect(applyReferenceExtendSourceVideo(unlinked, null, 3)).toBe(unlinked);
+  });
+
+  it('adopts an unflagged reference for the same clip instead of duplicating it (recall shape)', () => {
+    const recalled = { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'long.mp4' } };
+    const result = applyReferenceExtendSourceVideo([IMAGE_REFERENCE, recalled], longSource, 3);
+
+    expect(result).toHaveLength(2);
+    expect(result[1]).toMatchObject({
+      clip: { endFrame: 400, startFrame: 260, video_name: 'long.mp4' },
+      fromSourceVideo: true,
+    });
+  });
+
+  it('leaves a full video-reference list unchanged instead of overflowing the cap', () => {
+    const full = [
+      VIDEO_REFERENCE,
+      { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'b.mp4' } },
+      { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'c.mp4' } },
+    ];
+
+    expect(applyReferenceExtendSourceVideo(full, longSource, 3)).toBe(full);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index 9aa2152a9c1..983769957bd 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -145,7 +145,9 @@ const areAcceleratorLorasPresent = (keys: readonly string[], loras: readonly Gen
  * frame and a source video never coexist (normalization and the setters both
  * enforce it), and a last frame refines whichever mode its partner implies:
  * with a first frame it becomes FLF2V interpolation, with a source video it is
- * the destination the extension should land on.
+ * the destination the extension should land on. References always win: with a
+ * source video alongside them (Ref2VA reference-extend) the mode stays
+ * `reference` and the graph appends the new clip to the source.
  */
 export const resolveVideoMode = (
   settings: Pick<VideoSettings, 'firstFrameImage' | 'lastFrameImage' | 'sourceVideo' | 'references'>
@@ -199,16 +201,16 @@ export const normalizeVideoSettings = (values: unknown): VideoSettings | null =>
     return null;
   }
 
-  // References are mutually exclusive with every frame/source-video slot; when a stale
-  // record somehow holds both, the references win deterministically (mirroring the
-  // first-frame-beats-source rule below).
+  // References are mutually exclusive with the frame slots; when a stale
+  // record somehow holds both, the references win deterministically. A source
+  // video COEXISTS with references (Ref2VA reference-extend) — validation
+  // rejects the pair on models that cannot consume it.
   const references = sanitizeVideoReferences(values.references);
   const hasReferences = references.length > 0;
   const firstFrameImage = !hasReferences && isImageWithDims(values.firstFrameImage) ? values.firstFrameImage : null;
   // A first frame and a source video are mutually exclusive; if a stale
   // project somehow holds both, the first frame wins deterministically.
-  const sourceVideo =
-    !firstFrameImage && !hasReferences && isVideoSourceClip(values.sourceVideo) ? values.sourceVideo : null;
+  const sourceVideo = !firstFrameImage && isVideoSourceClip(values.sourceVideo) ? values.sourceVideo : null;
   const loras = Array.isArray(values.loras) ? values.loras.filter(isVideoLora) : [];
   const acceleratorLoraKeys = getStringArray(values.acceleratorLoraKeys);
   // The flag means "the accelerator LoRAs the toggle added are active": if any
@@ -294,7 +296,7 @@ export const isVideoSettings = (values: unknown): values is VideoSettings => {
     values.references.every(isVideoReferenceItem) &&
     !(
       (values.references as unknown[]).length > 0 &&
-      (values.firstFrameImage !== null || values.lastFrameImage !== null || values.sourceVideo !== null)
+      (values.firstFrameImage !== null || values.lastFrameImage !== null)
     ) &&
     Array.isArray(values.loras) &&
     values.loras.every(isVideoLora) &&
@@ -384,6 +386,71 @@ export const createVideoSourceClip = (item: {
 /** The minimum frames a trim must keep — video_concat's crossfade consumes a 2-frame tail. */
 export const MIN_VIDEO_TRIM_FRAMES = 2;
 
+/**
+ * Frames the reference-extend tail reference samples ahead of the cutpoint:
+ * ~5s of lead-in at H3's fixed 24 fps, and exactly on the 17n+5 frame grid
+ * (17*8+5) so the backend's snap-down keeps all of it.
+ */
+export const VIDEO_REFERENCE_EXTEND_TAIL_FRAMES = 141;
+
+/** The tail reference's default trim: the last `VIDEO_REFERENCE_EXTEND_TAIL_FRAMES` frames before the cutpoint. */
+export const deriveReferenceExtendClip = (sourceVideo: VideoSourceClip): VideoSourceClip => ({
+  ...sourceVideo,
+  endFrame: sourceVideo.endFrame,
+  // Deliberately unclamped by the Initial Video's START cutpoint: the
+  // reference samples the original clip for continuity, independent of which
+  // portion the extension keeps.
+  startFrame: Math.max(0, sourceVideo.endFrame - (VIDEO_REFERENCE_EXTEND_TAIL_FRAMES - 1)),
+});
+
+/**
+ * Keeps the reference list in step with the Initial Video on a reference-extend
+ * panel (pure; the setter and the model-selection transition both use it):
+ *
+ * - clearing the Initial Video removes its linked reference;
+ * - setting or re-trimming it re-derives the linked reference's default trim
+ *   (`[end - 140, end]`) — a manually tuned trim therefore holds only until
+ *   the next cutpoint change, which the section's help text says;
+ * - with no linked entry yet, an existing video reference for the same clip
+ *   is adopted (recall restores the pair without the linkage flag; adopting
+ *   avoids a duplicate), else a new one is PREPENDED — the continuity anchor
+ *   leads the request order — unless the video cap is already full, in which
+ *   case the list is returned unchanged and the extension simply runs without
+ *   a tail reference.
+ */
+export const applyReferenceExtendSourceVideo = (
+  references: VideoReferenceItem[],
+  sourceVideo: VideoSourceClip | null,
+  maxVideos: number
+): VideoReferenceItem[] => {
+  if (!sourceVideo) {
+    const kept = references.filter((entry) => !(entry.kind === 'video' && entry.fromSourceVideo === true));
+
+    return kept.length === references.length ? references : kept;
+  }
+
+  const linked: VideoReferenceItem = {
+    clip: deriveReferenceExtendClip(sourceVideo),
+    conditioning: 'video_audio',
+    fromSourceVideo: true,
+    kind: 'video',
+  };
+  const linkedIndex = references.findIndex(
+    (entry) =>
+      entry.kind === 'video' && (entry.fromSourceVideo === true || entry.clip.video_name === sourceVideo.video_name)
+  );
+
+  if (linkedIndex >= 0) {
+    return references.map((entry, index) =>
+      index === linkedIndex && entry.kind === 'video' ? { ...linked, conditioning: entry.conditioning } : entry
+    );
+  }
+
+  const videoCount = references.filter((entry) => entry.kind === 'video').length;
+
+  return videoCount >= maxVideos ? references : [linked, ...references];
+};
+
 /**
  * Clears conditioning media that no longer exists in the gallery. Returns the
  * input object untouched when nothing changes.
diff --git a/invokeai/frontend/webv2/src/features/video/core/types.ts b/invokeai/frontend/webv2/src/features/video/core/types.ts
index 09ec62cd988..b3bd80442bd 100644
--- a/invokeai/frontend/webv2/src/features/video/core/types.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/types.ts
@@ -40,7 +40,20 @@ export type VideoReferenceImageDetail = 'max' | 'match';
  * kind. A video reference reuses `VideoSourceClip` for its trim bounds.
  */
 export type VideoReferenceItem =
-  | { kind: 'video'; clip: VideoSourceClip; conditioning: VideoReferenceConditioning }
+  | {
+      kind: 'video';
+      clip: VideoSourceClip;
+      conditioning: VideoReferenceConditioning;
+      /**
+       * True on the reference the panel derives from the Initial Video in
+       * Ref2VA extend mode: it tracks that clip's identity, and its trim
+       * defaults re-derive from the cutpoint (`[end - 140, end]`, ~5s of
+       * lead-in at 24 fps) whenever the Initial Video trim changes. It is an
+       * ordinary reference otherwise — reorderable, trimmable, removable —
+       * and the flag is panel state only, never recorded in metadata.
+       */
+      fromSourceVideo?: boolean;
+    }
   | { kind: 'image'; image: ImageWithDims; detail: VideoReferenceImageDetail };
 
 export type WanTargetResolution = '480p' | '720p' | '1080p';
@@ -72,11 +85,17 @@ export interface VideoSettings {
    * either `firstFrameImage` or `sourceVideo`.
    */
   lastFrameImage: ImageWithDims | null;
-  /** The clip to extend. Mutually exclusive with `firstFrameImage`. */
+  /**
+   * The clip to extend. Mutually exclusive with `firstFrameImage`. On an
+   * FL2VA model this drives extend mode; on a Ref2VA model it coexists with
+   * `references` (reference-extend: the new clip is appended to it, and a
+   * linked tail reference provides continuity).
+   */
   sourceVideo: VideoSourceClip | null;
   /**
-   * Ref2VA references, in conditioning order (up to 3 videos and 9 images). Mutually
-   * exclusive with `firstFrameImage`/`lastFrameImage`/`sourceVideo`; only a Ref2VA
+   * Ref2VA references, in conditioning order (up to 3 videos and 9 images).
+   * Mutually exclusive with `firstFrameImage`/`lastFrameImage`; `sourceVideo`
+   * may coexist on a Ref2VA model (reference-extend). Only a Ref2VA
    * transformer consumes them — see `resolveVideoMode` and the `reference` mode.
    */
   references: VideoReferenceItem[];
diff --git a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts
index 2fe220b4cd8..5e552280a1d 100644
--- a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts
@@ -1093,7 +1093,7 @@ describe('reference mode policy', () => {
     const settings = settingsFor(model);
 
     expect(getVideoModelPolicy(model, settings).modes).toEqual(['reference']);
-    expect(getVideoModelPolicy(model, settings).references).toEqual({ maxImages: 9, maxVideos: 3 });
+    expect(getVideoModelPolicy(model, settings).references).toEqual({ extend: true, maxImages: 9, maxVideos: 3 });
     expect(getVideoModelPolicy(h3Model(), settingsFor(h3Model())).references).toBeNull();
   });
 
@@ -1247,3 +1247,64 @@ describe('H3 component-source seeding', () => {
     expect(explicit.settings.componentSourceModel?.key).toBe(componentsOnly.key);
   });
 });
+
+describe('reference-extend policy', () => {
+  const initialVideo = {
+    endFrame: 400,
+    fps: 24,
+    height: 480,
+    numFrames: 402,
+    startFrame: 0,
+    video_name: 'long.mp4',
+    width: 832,
+  };
+
+  it('accepts references alongside an initial video on ref2va, rejecting the pair elsewhere', () => {
+    const ref2va = ref2vaTransformer();
+    const combined = settingsFor(ref2va, {
+      componentSourceModel: h3Model(),
+      references: [imageReference],
+      sourceVideo: initialVideo,
+    });
+
+    expect(getVideoValidationReasons(ref2va, combined)).toEqual([]);
+
+    // FL2VA (and any non-reference model) still rejects the combination.
+    const fl2va = h3Model();
+    const reasons = getVideoValidationReasons(
+      fl2va,
+      settingsFor(fl2va, { references: [imageReference], sourceVideo: initialVideo })
+    );
+
+    expect(reasons).toContainEqual(expect.stringContaining('cannot be combined with an initial video on this model'));
+  });
+
+  it('an FL2VA -> Ref2VA switch keeps the initial video and derives its linked tail reference', () => {
+    const fl2va = h3Model();
+    const toRef = getVideoModelSelectionResult({
+      currentSettings: settingsFor(fl2va, { modelKey: fl2va.key, sourceVideo: initialVideo }),
+      model: ref2vaTransformer(),
+      models: [fl2va],
+    });
+
+    expect(toRef.settings.sourceVideo).toEqual(initialVideo);
+    expect(toRef.clearedLabels).not.toContain('Initial video');
+    expect(toRef.settings.references[0]).toMatchObject({
+      clip: { endFrame: 400, startFrame: 260, video_name: 'long.mp4' },
+      conditioning: 'video_audio',
+      fromSourceVideo: true,
+      kind: 'video',
+    });
+
+    // And back: the references (linked one included) clear; the clip stays
+    // for FL2VA's own extend mode.
+    const backToFl = getVideoModelSelectionResult({
+      currentSettings: toRef.settings,
+      model: fl2va,
+      models: [fl2va],
+    });
+
+    expect(backToFl.settings.references).toEqual([]);
+    expect(backToFl.settings.sourceVideo).toEqual(initialVideo);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts
index 8bda24cadf9..56d32118e77 100644
--- a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts
@@ -38,7 +38,12 @@ import {
   WAN_TI2V_PIXEL_MULTIPLE,
   type VideoDimensions,
 } from './dimensions';
-import { MIN_VIDEO_TRIM_FRAMES, resolveVideoMode, VIDEO_ASPECT_RATIO_IDS } from './settings';
+import {
+  applyReferenceExtendSourceVideo,
+  MIN_VIDEO_TRIM_FRAMES,
+  resolveVideoMode,
+  VIDEO_ASPECT_RATIO_IDS,
+} from './settings';
 
 // Video capabilities registry keyed by model base AND variant: unlike still-image
 // generation, Wan's variants differ structurally (which conditioning modes exist,
@@ -118,7 +123,7 @@ interface VideoVariantConfig {
   accelerator: VideoAcceleratorConfig | null;
   audioOutput: boolean;
   /** Ref2VA reference caps; present only on variants whose modes include 'reference'. */
-  references?: { maxVideos: number; maxImages: number };
+  references?: { maxVideos: number; maxImages: number; extend?: boolean };
 }
 
 export const WAN_LIGHTNING_ACCELERATOR: VideoAcceleratorConfig = {
@@ -232,7 +237,10 @@ const MINIMAX_H3_REF2VA: VideoVariantConfig = {
   ...MINIMAX_H3_FL2VA,
   accelerator: MINIMAX_H3_REF2V_TURBO_ACCELERATOR,
   modes: ['reference'],
-  references: { maxImages: 9, maxVideos: 3 },
+  // `extend` = reference-extend: an Initial Video the new clip is appended to,
+  // with a linked tail reference for continuity (no frame conditioning — the
+  // panel derives a reference from the clip instead).
+  references: { extend: true, maxImages: 9, maxVideos: 3 },
 };
 
 export const VIDEO_GENERATION: Record<
@@ -455,7 +463,7 @@ export interface VideoModelPolicy {
     negativeHelpText?: string;
   };
   /** Ref2VA reference caps; null unless the effective variant has a reference mode. */
-  references: { maxVideos: number; maxImages: number } | null;
+  references: { maxVideos: number; maxImages: number; extend?: boolean } | null;
   ui: {
     cfgVisible: boolean;
     cfgLowNoiseVisible: boolean;
@@ -1400,11 +1408,18 @@ export const getVideoModelSelectionResult = ({
     addClearedLabel(clearedLabels, 'References');
   }
 
-  if (next.sourceVideo && !modes.includes('extend')) {
+  if (next.sourceVideo && !modes.includes('extend') && !config.references?.extend) {
     next.sourceVideo = null;
     addClearedLabel(clearedLabels, 'Initial video');
   }
 
+  // Reference-extend: a surviving Initial Video (e.g. carried over from an
+  // FL2VA extend setup) gets its linked tail reference derived/re-derived, so
+  // the switch lands on a generatable panel.
+  if (config.references?.extend && next.sourceVideo) {
+    next.references = applyReferenceExtendSourceVideo(next.references, next.sourceVideo, config.references.maxVideos);
+  }
+
   if (next.firstFrameImage && !modes.includes('first-frame') && !modes.includes('first-last')) {
     next.firstFrameImage = null;
     addClearedLabel(clearedLabels, 'First frame');
@@ -1575,8 +1590,12 @@ export const getVideoValidationReasons = (model: MainModelConfig, settings: Vide
     reasons.push('A first frame and an initial video cannot be combined. Clear one of them.');
   }
 
-  if (settings.references.length > 0 && (settings.firstFrameImage || settings.lastFrameImage || settings.sourceVideo)) {
-    reasons.push('References cannot be combined with first/last frames or an initial video. Clear one side.');
+  if (settings.references.length > 0 && (settings.firstFrameImage || settings.lastFrameImage)) {
+    reasons.push('References cannot be combined with first/last frames. Clear one side.');
+  }
+
+  if (settings.references.length > 0 && settings.sourceVideo && !config.references?.extend) {
+    reasons.push('References cannot be combined with an initial video on this model. Clear one side.');
   }
 
   if (!config.modes.includes(mode)) {
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
index 438617a1c15..5af4792db69 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
@@ -150,6 +150,11 @@ const ReferenceCard = memo(function ReferenceCard({
           <HStack gap="1">
             {reference.kind === 'video' ? <FilmIcon size={12} /> : <ImagePlusIcon size={12} />}
             <MiddleTruncate flex="1" fontSize="xs" text={name} />
+            {reference.kind === 'video' && reference.fromSourceVideo === true ? (
+              <Badge flexShrink={0} size="xs" variant="outline">
+                {t('widgets.video.referenceFromInitialVideo')}
+              </Badge>
+            ) : null}
           </HStack>
           <Select
             collection={reference.kind === 'video' ? collections.conditioning : collections.detail}
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index d69ac8faffb..c5c3d7f41f8 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -8,7 +8,12 @@ import { isMainModelConfig, sanitizeBatchCount, SEED_MAX } from '@features/gener
 import { ensureModelsLoaded, useModelsSelector } from '@features/models';
 import { ModelSelect } from '@features/models/react';
 import { getVideoDurationSeconds, invertVideoAspectRatioId } from '@features/video/core/dimensions';
-import { normalizeVideoWidgetValues, resolveVideoMode, VIDEO_ASPECT_RATIO_IDS } from '@features/video/core/settings';
+import {
+  applyReferenceExtendSourceVideo,
+  normalizeVideoWidgetValues,
+  resolveVideoMode,
+  VIDEO_ASPECT_RATIO_IDS,
+} from '@features/video/core/settings';
 import {
   getAcceleratorLoraChangeResult,
   getAcceleratorToggleResult,
@@ -235,7 +240,11 @@ export const VideoWidgetView = () => {
   // video are different ways to claim the same conditioning slot, so setting
   // one clears the other. A last frame combines with either — with a first
   // frame it interpolates (FLF2V); with a source video it is the destination
-  // the extension should land on.
+  // the extension should land on. On a reference-extend panel the initial
+  // video and the references coexist — the setter keeps the linked tail
+  // reference in step with the clip and its cutpoints.
+  const referenceExtend = Boolean(policy.references?.extend);
+  const maxVideoReferences = policy.references?.maxVideos ?? 3;
   const setFirstFrame = useCallback(
     (firstFrameImage: ImageWithDims | null) =>
       patch({ firstFrameImage, ...(firstFrameImage ? { sourceVideo: null } : {}) }),
@@ -243,16 +252,28 @@ export const VideoWidgetView = () => {
   );
   const setLastFrame = useCallback((lastFrameImage: ImageWithDims | null) => patch({ lastFrameImage }), [patch]);
   const setSourceVideo = useCallback(
-    (sourceVideo: VideoSourceClip | null) => patch({ sourceVideo, ...(sourceVideo ? { firstFrameImage: null } : {}) }),
-    [patch]
+    (sourceVideo: VideoSourceClip | null) => {
+      if (referenceExtend) {
+        patch({
+          references: applyReferenceExtendSourceVideo(values.references, sourceVideo, maxVideoReferences),
+          sourceVideo,
+          ...(sourceVideo ? { firstFrameImage: null } : {}),
+        });
+        return;
+      }
+      patch({ sourceVideo, ...(sourceVideo ? { firstFrameImage: null } : {}) });
+    },
+    [maxVideoReferences, patch, referenceExtend, values.references]
   );
   const setReferences = useCallback(
     (references: VideoReferenceItem[]) =>
       patch({
         references,
-        ...(references.length > 0 ? { firstFrameImage: null, lastFrameImage: null, sourceVideo: null } : {}),
+        ...(references.length > 0
+          ? { firstFrameImage: null, lastFrameImage: null, ...(referenceExtend ? {} : { sourceVideo: null }) }
+          : {}),
       }),
-    [patch]
+    [patch, referenceExtend]
   );
   const clearReferences = useCallback(() => patch({ references: [] }), [patch]);
   const setLoras = useCallback(
@@ -321,6 +342,7 @@ export const VideoWidgetView = () => {
   const supportsLastFrame = policy.modes.includes('first-last') || policy.modes.includes('last-frame');
   const supportsExtend = policy.modes.includes('extend');
   const supportsReferences = policy.modes.includes('reference');
+  const supportsInitialVideo = supportsExtend || referenceExtend;
   const hasConditioningMedia = Boolean(values.firstFrameImage || values.lastFrameImage || values.sourceVideo);
   const derivedSourceText = dimensions ? t(`widgets.video.dimensionSource.${dimensions.source}`) : undefined;
   const derivedSizeText = dimensions
@@ -424,7 +446,7 @@ export const VideoWidgetView = () => {
       {!supportsLastFrame && values.lastFrameImage ? (
         <StaleMediaStub label={t('widgets.video.staleLastFrame')} onClear={clearLastFrame} />
       ) : null}
-      {!supportsExtend && values.sourceVideo ? (
+      {!supportsInitialVideo && values.sourceVideo ? (
         <StaleMediaStub label={t('widgets.video.staleSourceVideo')} onClear={clearSourceVideo} />
       ) : null}
       {!supportsReferences && values.references.length > 0 ? (
@@ -444,9 +466,14 @@ export const VideoWidgetView = () => {
         </GenerationSettingsSection>
       ) : null}
 
-      {supportsExtend ? (
+      {supportsInitialVideo ? (
         <GenerationSettingsSection label={t('widgets.video.initialVideo')} sectionId="video-source" defaultOpen>
           <Stack gap="3" p="2">
+            {referenceExtend ? (
+              <Text color="fg.muted" fontSize="2xs" textWrap="pretty">
+                {t('widgets.video.referenceExtendHelp')}
+              </Text>
+            ) : null}
             <VideoSourceClipField
               disabled={Boolean(values.firstFrameImage)}
               disabledReason={values.firstFrameImage ? t('widgets.video.initialVideoBlocked') : undefined}
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/executeVideoRecall.ts b/invokeai/frontend/webv2/src/workbench/image-actions/executeVideoRecall.ts
index a38ca9de502..0f968a01f70 100644
--- a/invokeai/frontend/webv2/src/workbench/image-actions/executeVideoRecall.ts
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/executeVideoRecall.ts
@@ -248,7 +248,9 @@ export const executeVideoRecall = async ({
             firstFrameImage: null,
             lastFrameImage: null,
             references,
-            sourceVideo: null,
+            // A source video recorded alongside references is reference-extend
+            // state (hydrated above) — keep it; clear only a leftover.
+            sourceVideo: result.mediaNames.sourceVideoName ? result.values.sourceVideo : null,
           };
           recalledMedia = true;
         }
@@ -267,7 +269,9 @@ export const executeVideoRecall = async ({
       const effectiveModel = result.values.model;
 
       if (effectiveModel) {
-        const modes = getVideoModelPolicy(effectiveModel, result.values).modes;
+        const policy = getVideoModelPolicy(effectiveModel, result.values);
+        const modes = policy.modes;
+        const referenceExtend = Boolean(policy.references?.extend);
         let { firstFrameImage, lastFrameImage, sourceVideo } = result.values;
         let references = result.values.references;
 
@@ -276,13 +280,16 @@ export const executeVideoRecall = async ({
           references = [];
         }
         if (references.length > 0) {
-          // References replace the frame/source slots entirely.
+          // References replace the frame slots; the source video survives only
+          // on a reference-extend panel (the new clip is appended to it).
           firstFrameImage = null;
           lastFrameImage = null;
-          sourceVideo = null;
+          if (!referenceExtend) {
+            sourceVideo = null;
+          }
         }
 
-        if (sourceVideo && !modes.includes('extend')) {
+        if (sourceVideo && !modes.includes('extend') && !(references.length > 0 && referenceExtend)) {
           sourceVideo = null;
         }
         if (firstFrameImage && !modes.includes('first-frame') && !modes.includes('first-last')) {
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/videoRecall.test.ts b/invokeai/frontend/webv2/src/workbench/image-actions/videoRecall.test.ts
index 0a2d9eed76b..f70e8b2d6c7 100644
--- a/invokeai/frontend/webv2/src/workbench/image-actions/videoRecall.test.ts
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/videoRecall.test.ts
@@ -575,4 +575,29 @@ describe('model-position recall shapes', () => {
     expect(result?.values.model?.key).toBe(install.key);
     expect(result?.values.h3TransformerModel).toBeNull();
   });
+
+  it('reports the source video alongside the references for a reference-extend recording', () => {
+    const result = buildVideoRecallSettings({
+      currentValues,
+      kind: 'all',
+      metadata: {
+        generation_mode: 'minimax_h3_ref2v',
+        minimax_h3_component_source: { key: install.key },
+        minimax_h3_references: [
+          { conditioning: 'video_audio', end_frame: 400, kind: 'video', start_frame: 260, video_name: 'long.mp4' },
+        ],
+        model: { key: checkpoint.key },
+        num_frames: 124,
+        source_video: { video_name: 'long.mp4' },
+        source_video_end_frame: 400,
+        source_video_start_frame: 10,
+      },
+      models: catalog,
+    });
+
+    expect(result?.fields).toContain('media');
+    expect(result?.mediaNames.references).toHaveLength(1);
+    expect(result?.mediaNames.sourceVideoName).toBe('long.mp4');
+    expect(result?.mediaNames.sourceVideoTrim).toEqual({ endFrame: 400, startFrame: 10 });
+  });
 });
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/videoRecall.ts b/invokeai/frontend/webv2/src/workbench/image-actions/videoRecall.ts
index a619a7ae083..b4925b468d2 100644
--- a/invokeai/frontend/webv2/src/workbench/image-actions/videoRecall.ts
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/videoRecall.ts
@@ -626,8 +626,16 @@ export const buildVideoRecallSettings = ({
   }
 
   if (references.length > 0) {
-    // References replace every frame/source slot — the modes are mutually exclusive.
+    // References replace the frame slots, but a recorded source video rides
+    // ALONGSIDE them: Ref2VA reference-extend appends the new clip to it.
     mediaNames.references = references;
+    if (media.sourceVideoName) {
+      const startFrame = getInteger(metadata, 'source_video_start_frame');
+      const endFrame = getInteger(metadata, 'source_video_end_frame');
+
+      mediaNames.sourceVideoName = media.sourceVideoName;
+      mediaNames.sourceVideoTrim = startFrame !== null && endFrame !== null ? { endFrame, startFrame } : null;
+    }
     fields.push('media');
   } else if (media.firstFrameName || media.lastFrameName || media.sourceVideoName) {
     mediaNames.firstFrameName = media.firstFrameName;

From 7fe9df04e5330079f45b0a52749548adfa78a005 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Sun, 30 Aug 2026 21:16:15 -0400
Subject: [PATCH 02/19] fix(webv2): harden reference-extend after adversarial
 review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Drop the sourceVideo <-> references rival rows from the gallery
  optimistic-rollback rules: the pair is legal on a reference-extend panel,
  and treating them as rivals made a FAILED gallery deletion permanently
  drop whichever slot the sweep had cleared.
- applyReferenceExtendSourceVideo now prefers the flagged linked entry over
  an earlier same-name reference: a flag-or-name findIndex rewrote a user's
  own hand-trimmed reference (and left a second flagged entry dangling)
  when it sat above the linked one during a source swap.
- The model-selection transition derives the linked tail reference only
  when none exists yet — it also runs on task-neutral edits (same-model
  re-selection, component changes), which reset hand-tuned trims the help
  text only promises to reset on cutpoint changes.
- Setting an Initial Video with all 3 video-reference slots occupied now
  raises a warning toast instead of silently generating an extension with
  no continuity reference.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S4B5exWsbC2z2Uu2tA167A
---
 .../frontend/webv2/public/locales/en.json     |  2 +
 .../src/features/video/core/settings.test.ts  | 20 ++++++++++
 .../webv2/src/features/video/core/settings.ts | 13 +++++--
 .../features/video/core/videoPolicies.test.ts | 16 ++++++++
 .../src/features/video/core/videoPolicies.ts  | 13 +++++--
 .../src/features/video/ui/VideoWidgetView.tsx | 20 +++++++---
 .../galleryOptimisticRollback.test.ts         | 37 +++++++++++++++++++
 .../galleryOptimisticRollback.ts              |  6 ++-
 8 files changed, 112 insertions(+), 15 deletions(-)

diff --git a/invokeai/frontend/webv2/public/locales/en.json b/invokeai/frontend/webv2/public/locales/en.json
index 09e35472ee4..c2d988db5d2 100644
--- a/invokeai/frontend/webv2/public/locales/en.json
+++ b/invokeai/frontend/webv2/public/locales/en.json
@@ -3163,6 +3163,8 @@
       "referenceConditioningVideoAudio": "Video + audio",
       "referenceDetailMatch": "Match generation size",
       "referenceDetailMax": "Max detail (2048px, slower)",
+      "referenceExtendCapFull": "No continuity reference added",
+      "referenceExtendCapFullDescription": "All 3 video reference slots are in use, so the extension has no reference sampling the initial video. Remove a video reference to add one.",
       "referenceExtendHelp": "The generated video is appended to this clip at its End Frame. A linked video reference samples the last ~5 seconds (141 frames) before that cutpoint for continuity — its trim re-derives whenever the cutpoints change.",
       "referenceFromInitialVideo": "Initial video",
       "references": "References",
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index 3a73a63fa25..2b37ce0776c 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -439,6 +439,26 @@ describe('reference-extend linkage', () => {
     });
   });
 
+  it('prefers the flagged entry over an earlier same-name reference on a source swap', () => {
+    // User: linked ref for clip A, plus their OWN hand-trimmed reference for
+    // clip B sitting above it. Swapping the Initial Video to clip B must
+    // update the FLAGGED entry — not rewrite the user's B reference.
+    const linkedA = applyReferenceExtendSourceVideo([], longSource, 3)[0];
+    const handTrimmedB = {
+      ...VIDEO_REFERENCE,
+      clip: { ...VIDEO_REFERENCE.clip, endFrame: 200, numFrames: 300, startFrame: 100, video_name: 'b.mp4' },
+    };
+    const sourceB = { ...longSource, endFrame: 290, numFrames: 300, video_name: 'b.mp4' };
+    const result = applyReferenceExtendSourceVideo([handTrimmedB, linkedA!], sourceB, 3);
+
+    expect(result[0]).toBe(handTrimmedB);
+    expect(result[1]).toMatchObject({
+      clip: { endFrame: 290, startFrame: 150, video_name: 'b.mp4' },
+      fromSourceVideo: true,
+    });
+    expect(result.filter((entry) => entry.kind === 'video' && entry.fromSourceVideo === true)).toHaveLength(1);
+  });
+
   it('leaves a full video-reference list unchanged instead of overflowing the cap', () => {
     const full = [
       VIDEO_REFERENCE,
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index 983769957bd..38b3eebdf8a 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -435,10 +435,15 @@ export const applyReferenceExtendSourceVideo = (
     fromSourceVideo: true,
     kind: 'video',
   };
-  const linkedIndex = references.findIndex(
-    (entry) =>
-      entry.kind === 'video' && (entry.fromSourceVideo === true || entry.clip.video_name === sourceVideo.video_name)
-  );
+  // The flagged entry is THE linked reference; adopt-by-name only when none
+  // exists (a recall-restored pair carries no flag). A flag-or-name findIndex
+  // would rewrite a user's own same-clip reference — hand trim and all —
+  // whenever it sat above the flagged one.
+  const flaggedIndex = references.findIndex((entry) => entry.kind === 'video' && entry.fromSourceVideo === true);
+  const linkedIndex =
+    flaggedIndex >= 0
+      ? flaggedIndex
+      : references.findIndex((entry) => entry.kind === 'video' && entry.clip.video_name === sourceVideo.video_name);
 
   if (linkedIndex >= 0) {
     return references.map((entry, index) =>
diff --git a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts
index 5e552280a1d..505c57bba19 100644
--- a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts
@@ -1296,6 +1296,22 @@ describe('reference-extend policy', () => {
       kind: 'video',
     });
 
+    // A task-neutral re-selection of the same model must NOT re-derive a
+    // hand-tuned linked trim (only cutpoint changes do, via the setter).
+    const tuned = {
+      ...toRef.settings,
+      references: toRef.settings.references.map((entry, index) =>
+        index === 0 && entry.kind === 'video' ? { ...entry, clip: { ...entry.clip, startFrame: 300 } } : entry
+      ),
+    };
+    const reselected = getVideoModelSelectionResult({
+      currentSettings: tuned,
+      model: ref2vaTransformer(),
+      models: [fl2va],
+    });
+
+    expect(reselected.settings.references[0]).toMatchObject({ clip: { startFrame: 300 } });
+
     // And back: the references (linked one included) clear; the clip stays
     // for FL2VA's own extend mode.
     const backToFl = getVideoModelSelectionResult({
diff --git a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts
index 56d32118e77..3e04ecd3cad 100644
--- a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts
@@ -1414,9 +1414,16 @@ export const getVideoModelSelectionResult = ({
   }
 
   // Reference-extend: a surviving Initial Video (e.g. carried over from an
-  // FL2VA extend setup) gets its linked tail reference derived/re-derived, so
-  // the switch lands on a generatable panel.
-  if (config.references?.extend && next.sourceVideo) {
+  // FL2VA extend setup) gets its linked tail reference derived, so the switch
+  // lands on a generatable panel. Only when none exists yet: the transition
+  // also runs on task-neutral edits (a same-model re-selection, a component
+  // change), and re-deriving there would reset a hand-tuned trim the help
+  // text only promises to reset on cutpoint changes.
+  if (
+    config.references?.extend &&
+    next.sourceVideo &&
+    !next.references.some((entry) => entry.kind === 'video' && entry.fromSourceVideo === true)
+  ) {
     next.references = applyReferenceExtendSourceVideo(next.references, next.sourceVideo, config.references.maxVideos);
   }
 
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index c5c3d7f41f8..c80189f38b8 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -254,16 +254,24 @@ export const VideoWidgetView = () => {
   const setSourceVideo = useCallback(
     (sourceVideo: VideoSourceClip | null) => {
       if (referenceExtend) {
-        patch({
-          references: applyReferenceExtendSourceVideo(values.references, sourceVideo, maxVideoReferences),
-          sourceVideo,
-          ...(sourceVideo ? { firstFrameImage: null } : {}),
-        });
+        const references = applyReferenceExtendSourceVideo(values.references, sourceVideo, maxVideoReferences);
+
+        // Unchanged identity with a clip set means the video cap is full and
+        // no same-clip entry could be adopted: the extension would run with
+        // no continuity anchor at all, which deserves more than silence.
+        if (sourceVideo && references === values.references) {
+          toaster.create({
+            description: t('widgets.video.referenceExtendCapFullDescription'),
+            title: t('widgets.video.referenceExtendCapFull'),
+            type: 'warning',
+          });
+        }
+        patch({ references, sourceVideo, ...(sourceVideo ? { firstFrameImage: null } : {}) });
         return;
       }
       patch({ sourceVideo, ...(sourceVideo ? { firstFrameImage: null } : {}) });
     },
-    [maxVideoReferences, patch, referenceExtend, values.references]
+    [maxVideoReferences, patch, referenceExtend, t, values.references]
   );
   const setReferences = useCallback(
     (references: VideoReferenceItem[]) =>
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/galleryOptimisticRollback.test.ts b/invokeai/frontend/webv2/src/workbench/image-actions/galleryOptimisticRollback.test.ts
index a9142bc4596..71b746de6c3 100644
--- a/invokeai/frontend/webv2/src/workbench/image-actions/galleryOptimisticRollback.test.ts
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/galleryOptimisticRollback.test.ts
@@ -217,6 +217,43 @@ describe('gallery optimistic rollback against the real reducer', () => {
     expect(getProjectWidgetValues(getProject(restored, projectId), 'gallery').selectedImage).toEqual(galleryItem);
   });
 
+  it('restores swept references even when an initial video occupies the panel (reference-extend pair)', () => {
+    // sourceVideo <-> references is a LEGAL pair on a Ref2VA reference-extend
+    // panel; treating them as rivals made a failed deletion permanently drop
+    // the reference the sweep removed.
+    const seeded = seedProjectWithItem();
+    const projectId = seeded.projectId;
+    const sourceClip = {
+      endFrame: 79,
+      fps: 16,
+      height: 480,
+      numFrames: 81,
+      startFrame: 0,
+      video_name: 'clip.mp4',
+      width: 832,
+    };
+    const imageReference = { detail: 'max', image: { height: 480, image_name: 'a.png', width: 832 }, kind: 'image' };
+    const state = workbenchReducer(seeded.state, {
+      projectId,
+      type: 'patchWidgetValues',
+      values: { references: [imageReference], sourceVideo: sourceClip },
+      widgetId: 'video',
+    });
+
+    const before = captureGalleryWidgetKeyValues(state.projects);
+    const afterRemoval = workbenchReducer(state, { itemKeys: ['image:a.png'], type: 'removeGalleryItems' });
+
+    expect(getProjectWidgetValues(getProject(afterRemoval, projectId), 'video').references).toEqual([]);
+
+    const entries = diffGalleryWidgetKeyValues(before, afterRemoval.projects);
+    const patches = selectRestorableGalleryWidgetPatches(entries, afterRemoval.projects);
+    const restored = applyRestorePatches(afterRemoval, patches);
+    const videoValues = getProjectWidgetValues(getProject(restored, projectId), 'video');
+
+    expect(videoValues.references).toEqual([imageReference]);
+    expect(videoValues.sourceVideo).toEqual(sourceClip);
+  });
+
   it('still restores a cleared video slot when its rival stayed empty', () => {
     const seeded = seedProjectWithItem();
     const projectId = seeded.projectId;
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/galleryOptimisticRollback.ts b/invokeai/frontend/webv2/src/workbench/image-actions/galleryOptimisticRollback.ts
index e3790d83092..c80abc882cd 100644
--- a/invokeai/frontend/webv2/src/workbench/image-actions/galleryOptimisticRollback.ts
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/galleryOptimisticRollback.ts
@@ -51,10 +51,12 @@ const EXCLUSIVE_RIVAL_FIELDS: ReadonlyArray<{ key: string; rivalKey: string; wid
   { key: 'firstFrameImage', rivalKey: 'references', widgetId: 'video' },
   { key: 'lastFrameImage', rivalKey: 'references', widgetId: 'video' },
   { key: 'sourceVideo', rivalKey: 'firstFrameImage', widgetId: 'video' },
-  { key: 'sourceVideo', rivalKey: 'references', widgetId: 'video' },
   { key: 'references', rivalKey: 'firstFrameImage', widgetId: 'video' },
   { key: 'references', rivalKey: 'lastFrameImage', widgetId: 'video' },
-  { key: 'references', rivalKey: 'sourceVideo', widgetId: 'video' },
+  // sourceVideo <-> references is deliberately NOT a rival pair: the two
+  // coexist on a Ref2VA reference-extend panel, and normalization keeps both
+  // (validation owns rejecting the pair per model). Treating them as rivals
+  // made a FAILED gallery deletion permanently drop the other slot's value.
 ];
 
 const trackedFieldKey = (projectId: string, widgetId: WidgetTypeId, key: string): string =>

From fcc2fbf7868ab8c10513c67fa3d7c0b905b031f5 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Sun, 30 Aug 2026 21:22:11 -0400
Subject: [PATCH 03/19] feat(webv2): scale the reference-extend tail window to
 the source frame rate

The 141-frame default was source-native, so a 16 fps clip sampled ~8.8 s
instead of the intended ~5 s. Treat 141-at-24fps as a duration and convert
it to source frames (16 fps -> 94, 30 fps -> 176); 24 fps sources keep
exactly 141, which stays grid-exact through the backend's 24 fps resample
and 17n+5 snap-down.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S4B5exWsbC2z2Uu2tA167A
---
 .../frontend/webv2/public/locales/en.json     |  2 +-
 .../src/features/video/core/settings.test.ts  | 13 ++++++-
 .../webv2/src/features/video/core/settings.ts | 38 +++++++++++++------
 3 files changed, 38 insertions(+), 15 deletions(-)

diff --git a/invokeai/frontend/webv2/public/locales/en.json b/invokeai/frontend/webv2/public/locales/en.json
index c2d988db5d2..ed1267fee49 100644
--- a/invokeai/frontend/webv2/public/locales/en.json
+++ b/invokeai/frontend/webv2/public/locales/en.json
@@ -3165,7 +3165,7 @@
       "referenceDetailMax": "Max detail (2048px, slower)",
       "referenceExtendCapFull": "No continuity reference added",
       "referenceExtendCapFullDescription": "All 3 video reference slots are in use, so the extension has no reference sampling the initial video. Remove a video reference to add one.",
-      "referenceExtendHelp": "The generated video is appended to this clip at its End Frame. A linked video reference samples the last ~5 seconds (141 frames) before that cutpoint for continuity — its trim re-derives whenever the cutpoints change.",
+      "referenceExtendHelp": "The generated video is appended to this clip at its End Frame. A linked video reference samples the last ~5 seconds of the clip (141 frames at 24 fps, scaled to its frame rate) before that cutpoint for continuity — its trim re-derives whenever the cutpoints change.",
       "referenceFromInitialVideo": "Initial video",
       "references": "References",
       "referencesHelp": "Up to 3 videos and 9 images condition the generation, in order — reordering references changes the result. A video reference can contribute its image track, its soundtrack, or both.",
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index 2b37ce0776c..bc0f042a6b3 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -384,14 +384,23 @@ describe('references', () => {
 });
 
 describe('reference-extend linkage', () => {
-  const longSource = { ...SOURCE_VIDEO, endFrame: 400, numFrames: 402, video_name: 'long.mp4' };
+  const longSource = { ...SOURCE_VIDEO, endFrame: 400, fps: 24, numFrames: 402, video_name: 'long.mp4' };
 
-  it('derives the tail trim: 141 frames inclusive ending at the cutpoint, clamped at 0', () => {
+  it('derives the tail trim: 141 frames at 24 fps ending at the cutpoint, clamped at 0', () => {
     expect(deriveReferenceExtendClip(longSource)).toMatchObject({ endFrame: 400, startFrame: 260 });
     // Shorter than the tail window: sample from the clip's own start.
     expect(deriveReferenceExtendClip(SOURCE_VIDEO)).toMatchObject({ endFrame: 79, startFrame: 0 });
   });
 
+  it('scales the tail window to the source frame rate — a constant duration, not a constant frame count', () => {
+    // 16 fps: round(141/24 * 16) = 94 frames of the same ~5.9 s.
+    expect(deriveReferenceExtendClip({ ...longSource, fps: 16 })).toMatchObject({ endFrame: 400, startFrame: 307 });
+    // 30 fps: round(141/24 * 30) = 176 frames.
+    expect(deriveReferenceExtendClip({ ...longSource, fps: 30 })).toMatchObject({ endFrame: 400, startFrame: 225 });
+    // A degenerate recorded rate falls back to the 24 fps window.
+    expect(deriveReferenceExtendClip({ ...longSource, fps: 0 })).toMatchObject({ endFrame: 400, startFrame: 260 });
+  });
+
   it('prepends a linked video+audio reference and re-derives it on cutpoint changes', () => {
     const added = applyReferenceExtendSourceVideo([IMAGE_REFERENCE], longSource, 3);
 
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index 38b3eebdf8a..0822cca15cd 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -387,21 +387,35 @@ export const createVideoSourceClip = (item: {
 export const MIN_VIDEO_TRIM_FRAMES = 2;
 
 /**
- * Frames the reference-extend tail reference samples ahead of the cutpoint:
- * ~5s of lead-in at H3's fixed 24 fps, and exactly on the 17n+5 frame grid
- * (17*8+5) so the backend's snap-down keeps all of it.
+ * Frames the reference-extend tail reference samples ahead of the cutpoint,
+ * expressed at 24 fps: ~5s of lead-in, and exactly on the 17n+5 frame grid
+ * (17*8+5) so the backend's 24 fps resample + snap-down keeps all of it. The
+ * window is a DURATION — `deriveReferenceExtendClip` scales it to the source
+ * clip's own frame rate, so a 16 fps source samples 94 frames of the same
+ * ~5.9 s rather than 141 frames of ~8.8 s.
  */
 export const VIDEO_REFERENCE_EXTEND_TAIL_FRAMES = 141;
 
-/** The tail reference's default trim: the last `VIDEO_REFERENCE_EXTEND_TAIL_FRAMES` frames before the cutpoint. */
-export const deriveReferenceExtendClip = (sourceVideo: VideoSourceClip): VideoSourceClip => ({
-  ...sourceVideo,
-  endFrame: sourceVideo.endFrame,
-  // Deliberately unclamped by the Initial Video's START cutpoint: the
-  // reference samples the original clip for continuity, independent of which
-  // portion the extension keeps.
-  startFrame: Math.max(0, sourceVideo.endFrame - (VIDEO_REFERENCE_EXTEND_TAIL_FRAMES - 1)),
-});
+const VIDEO_REFERENCE_EXTEND_TAIL_FPS = 24;
+
+/** The tail reference's default trim: the `VIDEO_REFERENCE_EXTEND_TAIL_FRAMES`-at-24fps window before the cutpoint, in source frames. */
+export const deriveReferenceExtendClip = (sourceVideo: VideoSourceClip): VideoSourceClip => {
+  const fps =
+    Number.isFinite(sourceVideo.fps) && sourceVideo.fps > 0 ? sourceVideo.fps : VIDEO_REFERENCE_EXTEND_TAIL_FPS;
+  const tailFrames = Math.max(
+    1,
+    Math.round((VIDEO_REFERENCE_EXTEND_TAIL_FRAMES / VIDEO_REFERENCE_EXTEND_TAIL_FPS) * fps)
+  );
+
+  return {
+    ...sourceVideo,
+    endFrame: sourceVideo.endFrame,
+    // Deliberately unclamped by the Initial Video's START cutpoint: the
+    // reference samples the original clip for continuity, independent of
+    // which portion the extension keeps.
+    startFrame: Math.max(0, sourceVideo.endFrame - (tailFrames - 1)),
+  };
+};
 
 /**
  * Keeps the reference list in step with the Initial Video on a reference-extend

From b76d981fbe36594a21cf2104f02322c22d6e7b96 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Sun, 30 Aug 2026 23:13:45 -0400
Subject: [PATCH 04/19] fix(webv2): budget the reference-extend tail window
 against the frame count

The parent scaled the tail window to the source frame rate, fixing the ~8.8s
a 16 fps clip sampled. The window is still bounded by a second rule it does
not account for, and that one costs the frames continuity actually depends on.

Three backend rules bound a video reference, and every one of them discards
from the END -- the frames adjacent to the cutpoint. normalize_reference_video_frames
resamples onto H3's fixed 24 fps and truncates to the GENERATED frame count
keeping the FRONT (frames[:num_frames]); encode_reference_video then snaps what
survives DOWN to the 17n+5 grid. So a 141-frame window against the 124-frame
default keeps 124 frames -- the right count, shifted 17 frames (0.7s) off the
seam. The window is now min(TAIL, numFrames), the smaller bound winning.

The fps conversion rounds UP rather than to nearest. Overshooting is free: the
truncation cuts the window back to exactly numFrames and the snap -- both
already on the 17n+5 grid -- then keeps it whole. Undershooting lands OFF the
grid and the snap eats up to 16 frames. Rounding to nearest lost 17 frames at
23.976 fps (NTSC film) at every frame count on offer, and 17 at 16 fps at the
124-frame default. A test runs all three backend rules over 12 source rates x
all 16 frame choices and asserts the kept count equals the budget exactly.

Two defects found by adversarial review of the first cut, both created by
making the window depend on the frame count:

- The frame count is snapped BEFORE the window is derived. Deriving first let
  a Wan panel's count (as low as 5) size the window for a 90-frame H3
  generation, under the 13 frames sample_text_conditioning_frames needs --
  Generate failed outright with a ValueError.
- The frame-count application re-derives instead of shrinking to fit. The
  Frames number input emits a value per keystroke, unclamped, so typing "345"
  arrives as 3 -- and a shrink-only rule pinned the window at a 3-frame budget
  for the rest of the session, silently. Re-deriving is idempotent, so
  keystrokes and slider drags leave no trace.

Separately, the linked tail reference is APPENDED rather than prepended.
Request order is rotary order: build_ref2va_packed_sequence lays the reference
blocks out in order, each advancing a shared clock, and the generated rows
start at the position the LAST block left behind. The reference the model
continues from is the final one, so the continuity anchor belongs at the end --
with a single reference this changed nothing, which is why it went unnoticed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../frontend/webv2/public/locales/en.json     |   2 +-
 .../src/features/video/core/settings.test.ts  | 133 +++++++++++++----
 .../webv2/src/features/video/core/settings.ts | 140 ++++++++++++++----
 .../webv2/src/features/video/core/types.ts    |   9 +-
 .../features/video/core/videoPolicies.test.ts |  28 +++-
 .../src/features/video/core/videoPolicies.ts  |  34 ++++-
 .../src/features/video/ui/VideoWidgetView.tsx |  29 +++-
 7 files changed, 298 insertions(+), 77 deletions(-)

diff --git a/invokeai/frontend/webv2/public/locales/en.json b/invokeai/frontend/webv2/public/locales/en.json
index ed1267fee49..237b1037031 100644
--- a/invokeai/frontend/webv2/public/locales/en.json
+++ b/invokeai/frontend/webv2/public/locales/en.json
@@ -3165,7 +3165,7 @@
       "referenceDetailMax": "Max detail (2048px, slower)",
       "referenceExtendCapFull": "No continuity reference added",
       "referenceExtendCapFullDescription": "All 3 video reference slots are in use, so the extension has no reference sampling the initial video. Remove a video reference to add one.",
-      "referenceExtendHelp": "The generated video is appended to this clip at its End Frame. A linked video reference samples the last ~5 seconds of the clip (141 frames at 24 fps, scaled to its frame rate) before that cutpoint for continuity — its trim re-derives whenever the cutpoints change.",
+      "referenceExtendHelp": "The generated video is appended to this clip at its End Frame. A linked video reference samples up to the last ~5 seconds before that cutpoint for continuity — never more than the generated clip's own length, since the model discards the overrun at the seam. Its trim re-derives whenever the cutpoints or the frame count change.",
       "referenceFromInitialVideo": "Initial video",
       "references": "References",
       "referencesHelp": "Up to 3 videos and 9 images condition the generation, in order — reordering references changes the result. A video reference can contribute its image track, its soundtrack, or both.",
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index bc0f042a6b3..24cb085fff1 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -2,8 +2,10 @@ import { describe, expect, it } from 'vitest';
 
 import type { VideoSettings } from './types';
 
+import { MINIMAX_H3_NUM_FRAMES_CHOICES } from './dimensions';
 import {
   applyReferenceExtendSourceVideo,
+  applyReferenceExtendNumFrames,
   clearDeletedVideoMedia,
   cloneVideoWidgetValues,
   createVideoSourceClip,
@@ -384,28 +386,71 @@ describe('references', () => {
 });
 
 describe('reference-extend linkage', () => {
-  const longSource = { ...SOURCE_VIDEO, endFrame: 400, fps: 24, numFrames: 402, video_name: 'long.mp4' };
-
-  it('derives the tail trim: 141 frames at 24 fps ending at the cutpoint, clamped at 0', () => {
-    expect(deriveReferenceExtendClip(longSource)).toMatchObject({ endFrame: 400, startFrame: 260 });
+  // H3 generates at a fixed 24 fps; SOURCE_VIDEO runs at 16, so the two rates
+  // are exercised separately.
+  const longSource = { ...SOURCE_VIDEO, endFrame: 400, numFrames: 402, video_name: 'long.mp4' };
+  const source24 = { ...longSource, fps: 24 };
+  // The panel's default; every choice is on the 17n+5 grid.
+  const FRAMES = 141;
+
+  it('derives the tail trim: the window ending at the cutpoint, clamped at 0', () => {
+    expect(deriveReferenceExtendClip(source24, FRAMES)).toMatchObject({ endFrame: 400, startFrame: 260 });
     // Shorter than the tail window: sample from the clip's own start.
-    expect(deriveReferenceExtendClip(SOURCE_VIDEO)).toMatchObject({ endFrame: 79, startFrame: 0 });
+    expect(deriveReferenceExtendClip({ ...SOURCE_VIDEO, fps: 24 }, FRAMES)).toMatchObject({
+      endFrame: 79,
+      startFrame: 0,
+    });
+  });
+
+  it('budgets the window against the generated frame count', () => {
+    // `normalize_reference_video_frames` truncates a reference to the generated
+    // frame count keeping the FRONT, so a window longer than the generation
+    // loses its tail — the frames at the seam. It must never outrun the count.
+    expect(deriveReferenceExtendClip(source24, 124)).toMatchObject({ endFrame: 400, startFrame: 277 });
+    expect(deriveReferenceExtendClip(source24, 90)).toMatchObject({ endFrame: 400, startFrame: 311 });
+    // Above the tail window the budget stops binding: ~5s of lead-in is the cap.
+    expect(deriveReferenceExtendClip(source24, 345)).toMatchObject({ endFrame: 400, startFrame: 260 });
+  });
+
+  it('lands the window ON the 17n+5 grid the backend keeps, at every source rate', () => {
+    // The real test of the window: run it through ALL THREE backend rules.
+    // `resample_video_frame_repeats` onto 24 fps, `frames[:num_frames]`, then
+    // `snap_reference_num_frames` DOWN to 17n+5 — every one of which cuts the
+    // seam end. Rounding the fps conversion DOWN satisfied the first two and
+    // failed the third, losing 17 frames at 23.976 fps at every frame count.
+    const resample = (n: number, fps: number) => Math.floor((n * 24) / fps + 0.5);
+    const snapDown = (n: number) => Math.max(1, Math.floor((n - 5) / 17)) * 17 + 5;
+
+    for (const fps of [10, 12, 15, 16, 18, 20, 23.976, 24, 25, 29.97, 30, 60]) {
+      for (const numFrames of MINIMAX_H3_NUM_FRAMES_CHOICES) {
+        const clip = deriveReferenceExtendClip({ ...longSource, fps }, numFrames);
+        const budget = Math.min(141, numFrames);
+        const kept = snapDown(Math.min(resample(clip.endFrame - clip.startFrame + 1, fps), numFrames));
+
+        expect({ fps, kept, numFrames }).toEqual({ fps, kept: budget, numFrames });
+      }
+    }
   });
 
-  it('scales the tail window to the source frame rate — a constant duration, not a constant frame count', () => {
-    // 16 fps: round(141/24 * 16) = 94 frames of the same ~5.9 s.
-    expect(deriveReferenceExtendClip({ ...longSource, fps: 16 })).toMatchObject({ endFrame: 400, startFrame: 307 });
-    // 30 fps: round(141/24 * 30) = 176 frames.
-    expect(deriveReferenceExtendClip({ ...longSource, fps: 30 })).toMatchObject({ endFrame: 400, startFrame: 225 });
-    // A degenerate recorded rate falls back to the 24 fps window.
-    expect(deriveReferenceExtendClip({ ...longSource, fps: 0 })).toMatchObject({ endFrame: 400, startFrame: 260 });
+  it('converts the window into the source clip fps', () => {
+    // 141 frames of 24 fps material is 94 frames of a 16 fps clip — the same
+    // 5.875s of wall time, which is what the tail window actually means.
+    expect(deriveReferenceExtendClip(longSource, FRAMES)).toMatchObject({ endFrame: 400, startFrame: 307 });
+    // A clip whose probe recorded no usable rate falls back to a no-op
+    // conversion rather than collapsing to the 2-frame floor.
+    expect(deriveReferenceExtendClip({ ...longSource, fps: 0 }, FRAMES)).toMatchObject({ startFrame: 260 });
+    expect(deriveReferenceExtendClip({ ...longSource, fps: -30 }, FRAMES)).toMatchObject({ startFrame: 260 });
   });
 
-  it('prepends a linked video+audio reference and re-derives it on cutpoint changes', () => {
-    const added = applyReferenceExtendSourceVideo([IMAGE_REFERENCE], longSource, 3);
+  it('appends a linked video+audio reference and re-derives it on cutpoint changes', () => {
+    // Appended, not prepended: request order is rotary order and the generated
+    // rows continue from the LAST reference block, so the continuity anchor
+    // has to be the final entry.
+    const added = applyReferenceExtendSourceVideo([IMAGE_REFERENCE], source24, 3, FRAMES);
 
     expect(added).toHaveLength(2);
-    expect(added[0]).toMatchObject({
+    expect(added[0]).toBe(IMAGE_REFERENCE);
+    expect(added[1]).toMatchObject({
       clip: { endFrame: 400, startFrame: 260, video_name: 'long.mp4' },
       conditioning: 'video_audio',
       fromSourceVideo: true,
@@ -415,31 +460,31 @@ describe('reference-extend linkage', () => {
     // The user tunes the conditioning, then moves the cutpoint: the trim
     // re-derives, the position and conditioning survive.
     const tuned = added.map((entry, index) =>
-      index === 0 && entry.kind === 'video' ? { ...entry, conditioning: 'video' as const } : entry
+      index === 1 && entry.kind === 'video' ? { ...entry, conditioning: 'video' as const } : entry
     );
-    const retrimmed = applyReferenceExtendSourceVideo(tuned, { ...longSource, endFrame: 300 }, 3);
+    const retrimmed = applyReferenceExtendSourceVideo(tuned, { ...source24, endFrame: 300 }, 3, FRAMES);
 
-    expect(retrimmed[0]).toMatchObject({
+    expect(retrimmed[1]).toMatchObject({
       clip: { endFrame: 300, startFrame: 160 },
       conditioning: 'video',
       fromSourceVideo: true,
     });
-    expect(retrimmed[1]).toBe(added[1]);
+    expect(retrimmed[0]).toBe(added[0]);
   });
 
   it('clearing the initial video removes only the linked reference (identity-preserving when none)', () => {
-    const list = applyReferenceExtendSourceVideo([VIDEO_REFERENCE, IMAGE_REFERENCE], longSource, 3);
+    const list = applyReferenceExtendSourceVideo([VIDEO_REFERENCE, IMAGE_REFERENCE], source24, 3, FRAMES);
 
-    expect(applyReferenceExtendSourceVideo(list, null, 3)).toEqual([VIDEO_REFERENCE, IMAGE_REFERENCE]);
+    expect(applyReferenceExtendSourceVideo(list, null, 3, FRAMES)).toEqual([VIDEO_REFERENCE, IMAGE_REFERENCE]);
 
     const unlinked = [VIDEO_REFERENCE, IMAGE_REFERENCE];
 
-    expect(applyReferenceExtendSourceVideo(unlinked, null, 3)).toBe(unlinked);
+    expect(applyReferenceExtendSourceVideo(unlinked, null, 3, FRAMES)).toBe(unlinked);
   });
 
   it('adopts an unflagged reference for the same clip instead of duplicating it (recall shape)', () => {
     const recalled = { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'long.mp4' } };
-    const result = applyReferenceExtendSourceVideo([IMAGE_REFERENCE, recalled], longSource, 3);
+    const result = applyReferenceExtendSourceVideo([IMAGE_REFERENCE, recalled], source24, 3, FRAMES);
 
     expect(result).toHaveLength(2);
     expect(result[1]).toMatchObject({
@@ -452,13 +497,13 @@ describe('reference-extend linkage', () => {
     // User: linked ref for clip A, plus their OWN hand-trimmed reference for
     // clip B sitting above it. Swapping the Initial Video to clip B must
     // update the FLAGGED entry — not rewrite the user's B reference.
-    const linkedA = applyReferenceExtendSourceVideo([], longSource, 3)[0];
+    const linkedA = applyReferenceExtendSourceVideo([], source24, 3, FRAMES)[0];
     const handTrimmedB = {
       ...VIDEO_REFERENCE,
       clip: { ...VIDEO_REFERENCE.clip, endFrame: 200, numFrames: 300, startFrame: 100, video_name: 'b.mp4' },
     };
-    const sourceB = { ...longSource, endFrame: 290, numFrames: 300, video_name: 'b.mp4' };
-    const result = applyReferenceExtendSourceVideo([handTrimmedB, linkedA!], sourceB, 3);
+    const sourceB = { ...source24, endFrame: 290, numFrames: 300, video_name: 'b.mp4' };
+    const result = applyReferenceExtendSourceVideo([handTrimmedB, linkedA!], sourceB, 3, FRAMES);
 
     expect(result[0]).toBe(handTrimmedB);
     expect(result[1]).toMatchObject({
@@ -475,6 +520,40 @@ describe('reference-extend linkage', () => {
       { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'c.mp4' } },
     ];
 
-    expect(applyReferenceExtendSourceVideo(full, longSource, 3)).toBe(full);
+    expect(applyReferenceExtendSourceVideo(full, source24, 3, FRAMES)).toBe(full);
+  });
+
+  it('applyReferenceExtendNumFrames re-derives the window and is idempotent', () => {
+    const linked = applyReferenceExtendSourceVideo([IMAGE_REFERENCE], source24, 3, FRAMES);
+
+    expect(linked[1]).toMatchObject({ clip: { startFrame: 260 } });
+
+    const at124 = applyReferenceExtendNumFrames(linked, 124);
+
+    expect(at124[1]).toMatchObject({ clip: { endFrame: 400, startFrame: 277 }, fromSourceVideo: true });
+    expect(at124[0]).toBe(linked[0]);
+    // Idempotent, and identity-preserving when nothing moves.
+    expect(applyReferenceExtendNumFrames(at124, 124)).toBe(at124);
+    expect(applyReferenceExtendNumFrames(linked, FRAMES)).toBe(linked);
+  });
+
+  it('applyReferenceExtendNumFrames does not ratchet: the window re-widens', () => {
+    // The Frames number input emits a value per keystroke, unclamped, so typing
+    // "345" arrives as 3, then 34, then 345. A shrink-only rule would pin the
+    // window at the 3-frame budget for the rest of the session.
+    const linked = applyReferenceExtendSourceVideo([], source24, 3, 345);
+    const typed = [3, 34, 345].reduce(applyReferenceExtendNumFrames, linked);
+
+    expect(typed[0]).toMatchObject({ clip: { endFrame: 400, startFrame: 260 } });
+    // And a slider dragged down and back up ends where it started.
+    expect([90, 124, 345].reduce(applyReferenceExtendNumFrames, linked)[0]).toMatchObject({
+      clip: { startFrame: 260 },
+    });
+  });
+
+  it('applyReferenceExtendNumFrames leaves unlinked references alone', () => {
+    const unlinked = [VIDEO_REFERENCE, IMAGE_REFERENCE];
+
+    expect(applyReferenceExtendNumFrames(unlinked, 90)).toBe(unlinked);
   });
 });
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index 0822cca15cd..de4da8cca4d 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -26,6 +26,8 @@ import type {
   WanTargetResolution,
 } from './types';
 
+import { MINIMAX_H3_FPS } from './dimensions';
+
 const isRecord = (value: unknown): value is Record<string, unknown> => Boolean(value) && typeof value === 'object';
 
 const hasFiniteNumber = (record: Record<string, unknown>, key: string): boolean =>
@@ -387,34 +389,99 @@ export const createVideoSourceClip = (item: {
 export const MIN_VIDEO_TRIM_FRAMES = 2;
 
 /**
- * Frames the reference-extend tail reference samples ahead of the cutpoint,
- * expressed at 24 fps: ~5s of lead-in, and exactly on the 17n+5 frame grid
- * (17*8+5) so the backend's 24 fps resample + snap-down keeps all of it. The
- * window is a DURATION — `deriveReferenceExtendClip` scales it to the source
- * clip's own frame rate, so a 16 fps source samples 94 frames of the same
- * ~5.9 s rather than 141 frames of ~8.8 s.
+ * The MAXIMUM lead-in the reference-extend tail reference samples ahead of the
+ * cutpoint, expressed at 24 fps: ~5s, and exactly on the 17n+5 frame grid
+ * (17*8+5) so the backend's 24 fps resample + snap-down keeps all of it.
+ *
+ * The window is a DURATION — `deriveReferenceExtendClip` scales it to the
+ * source clip's own frame rate, so a 16 fps source samples 94 frames of the
+ * same ~5.9 s rather than 141 frames of ~8.8 s. It is also a CEILING, not a
+ * fixed size: the generated frame count is the other bound, and the smaller of
+ * the two wins.
  */
 export const VIDEO_REFERENCE_EXTEND_TAIL_FRAMES = 141;
 
-const VIDEO_REFERENCE_EXTEND_TAIL_FPS = 24;
+/**
+ * The tail reference's default trim: the frames right before the cutpoint,
+ * sized so the backend keeps ALL of them.
+ *
+ * Three backend rules bound the window, and every one of them discards from
+ * the END — the frames adjacent to the cutpoint, the only ones continuity
+ * depends on. `normalize_reference_video_frames` resamples onto H3's fixed
+ * 24 fps and truncates to the GENERATED frame count keeping the FRONT
+ * (`frames[:num_frames]`); `encode_reference_video` then snaps what survives
+ * DOWN to the `17n + 5` grid the video VAE encodes without padding.
+ *
+ * The budget is therefore `min(TAIL, numFrames)` frames of 24 fps material,
+ * and both of those sit ON that grid already (141 = 17*8+5; every frame choice
+ * is 90 + 17i). The conversion into the source clip's own frame space rounds
+ * UP: overshooting is free, because the truncation cuts the window back to
+ * exactly `numFrames` and the snap then keeps it whole, while undershooting
+ * lands OFF the grid and the snap eats up to 16 frames at the seam. Rounding
+ * down looks safer and is not — it cost 17 frames at 23.976 fps (NTSC film) at
+ * every frame count on offer, and 17 at 16 fps at the 124-frame default.
+ */
+export const deriveReferenceExtendClip = (sourceVideo: VideoSourceClip, numFrames: number): VideoSourceClip => ({
+  ...sourceVideo,
+  endFrame: sourceVideo.endFrame,
+  // Deliberately unclamped by the Initial Video's START cutpoint: the
+  // reference samples the original clip for continuity, independent of which
+  // portion the extension keeps.
+  startFrame: referenceExtendStartFrame(sourceVideo, numFrames),
+});
 
-/** The tail reference's default trim: the `VIDEO_REFERENCE_EXTEND_TAIL_FRAMES`-at-24fps window before the cutpoint, in source frames. */
-export const deriveReferenceExtendClip = (sourceVideo: VideoSourceClip): VideoSourceClip => {
-  const fps =
-    Number.isFinite(sourceVideo.fps) && sourceVideo.fps > 0 ? sourceVideo.fps : VIDEO_REFERENCE_EXTEND_TAIL_FPS;
-  const tailFrames = Math.max(
-    1,
-    Math.round((VIDEO_REFERENCE_EXTEND_TAIL_FRAMES / VIDEO_REFERENCE_EXTEND_TAIL_FPS) * fps)
-  );
+/** The tail window's start index — see `deriveReferenceExtendClip`. */
+const referenceExtendStartFrame = (clip: VideoSourceClip, numFrames: number): number => {
+  const budget = Number.isFinite(numFrames)
+    ? Math.min(VIDEO_REFERENCE_EXTEND_TAIL_FRAMES, Math.trunc(numFrames))
+    : VIDEO_REFERENCE_EXTEND_TAIL_FRAMES;
+  // A clip whose probe recorded no usable rate: the backend resamples at the
+  // rate it probes, so 24 — a no-op conversion — is the only safe assumption.
+  // A zero or negative rate would otherwise collapse the window to the 2-frame
+  // floor, which is below the 13 frames text conditioning needs.
+  const fps = Number.isFinite(clip.fps) && clip.fps > 0 ? clip.fps : MINIMAX_H3_FPS;
+  const tail = Math.max(MIN_VIDEO_TRIM_FRAMES, Math.ceil((budget * fps) / MINIMAX_H3_FPS));
+
+  return Math.max(0, clip.endFrame - (tail - 1));
+};
 
-  return {
-    ...sourceVideo,
-    endFrame: sourceVideo.endFrame,
-    // Deliberately unclamped by the Initial Video's START cutpoint: the
-    // reference samples the original clip for continuity, independent of
-    // which portion the extension keeps.
-    startFrame: Math.max(0, sourceVideo.endFrame - (tailFrames - 1)),
-  };
+/**
+ * Re-derives the linked tail reference's window for a generated frame count.
+ *
+ * The window is a function of that count, so a frame-count change has to move
+ * it. This RE-DERIVES rather than shrinks-to-fit: a shrink-only rule ratchets.
+ * The Frames number input emits a value per keystroke, unclamped, so typing
+ * "345" passes through 3 — and a shrink-only window would collapse to 3 frames
+ * and never come back, silently, for the rest of the session. Dragging the
+ * slider down and back up does the same. Re-deriving is idempotent in
+ * `numFrames`, so the values a keystroke or a drag passes through leave no
+ * trace.
+ *
+ * The cost is that a hand-tuned linked trim resets on a frame-count change as
+ * well as on a cutpoint change — the same bargain the section's help text
+ * already describes, and the backend leaves no alternative: a window that does
+ * not fit the budget loses its seam end.
+ */
+export const applyReferenceExtendNumFrames = (
+  references: VideoReferenceItem[],
+  numFrames: number
+): VideoReferenceItem[] => {
+  let changed = false;
+  const next = references.map((entry) => {
+    if (entry.kind !== 'video' || entry.fromSourceVideo !== true) {
+      return entry;
+    }
+    const startFrame = referenceExtendStartFrame(entry.clip, numFrames);
+
+    if (startFrame === entry.clip.startFrame) {
+      return entry;
+    }
+    changed = true;
+
+    return { ...entry, clip: { ...entry.clip, startFrame } };
+  });
+
+  return changed ? next : references;
 };
 
 /**
@@ -423,19 +490,28 @@ export const deriveReferenceExtendClip = (sourceVideo: VideoSourceClip): VideoSo
  *
  * - clearing the Initial Video removes its linked reference;
  * - setting or re-trimming it re-derives the linked reference's default trim
- *   (`[end - 140, end]`) — a manually tuned trim therefore holds only until
- *   the next cutpoint change, which the section's help text says;
+ *   (the tail window ending on the cutpoint) — a manually tuned trim
+ *   therefore holds only until the next cutpoint change, which the section's
+ *   help text says;
  * - with no linked entry yet, an existing video reference for the same clip
  *   is adopted (recall restores the pair without the linkage flag; adopting
- *   avoids a duplicate), else a new one is PREPENDED — the continuity anchor
- *   leads the request order — unless the video cap is already full, in which
- *   case the list is returned unchanged and the extension simply runs without
- *   a tail reference.
+ *   avoids a duplicate), else a new one is APPENDED — unless the video cap is
+ *   already full, in which case the list is returned unchanged and the
+ *   extension simply runs without a tail reference.
+ *
+ * Appended, not prepended, because request order IS rotary order:
+ * `build_ref2va_packed_sequence` lays the reference blocks out in order, each
+ * advancing a shared clock, and the generated rows then start at the position
+ * the LAST block left behind. The reference the model continues from is
+ * therefore the final one, so the continuity anchor belongs at the end. (The
+ * entry stays reorderable and keeps its place on a re-derive; only the
+ * default position is fixed here.)
  */
 export const applyReferenceExtendSourceVideo = (
   references: VideoReferenceItem[],
   sourceVideo: VideoSourceClip | null,
-  maxVideos: number
+  maxVideos: number,
+  numFrames: number
 ): VideoReferenceItem[] => {
   if (!sourceVideo) {
     const kept = references.filter((entry) => !(entry.kind === 'video' && entry.fromSourceVideo === true));
@@ -444,7 +520,7 @@ export const applyReferenceExtendSourceVideo = (
   }
 
   const linked: VideoReferenceItem = {
-    clip: deriveReferenceExtendClip(sourceVideo),
+    clip: deriveReferenceExtendClip(sourceVideo, numFrames),
     conditioning: 'video_audio',
     fromSourceVideo: true,
     kind: 'video',
@@ -467,7 +543,7 @@ export const applyReferenceExtendSourceVideo = (
 
   const videoCount = references.filter((entry) => entry.kind === 'video').length;
 
-  return videoCount >= maxVideos ? references : [linked, ...references];
+  return videoCount >= maxVideos ? references : [...references, linked];
 };
 
 /**
diff --git a/invokeai/frontend/webv2/src/features/video/core/types.ts b/invokeai/frontend/webv2/src/features/video/core/types.ts
index b3bd80442bd..6758cae4b67 100644
--- a/invokeai/frontend/webv2/src/features/video/core/types.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/types.ts
@@ -47,10 +47,11 @@ export type VideoReferenceItem =
       /**
        * True on the reference the panel derives from the Initial Video in
        * Ref2VA extend mode: it tracks that clip's identity, and its trim
-       * defaults re-derive from the cutpoint (`[end - 140, end]`, ~5s of
-       * lead-in at 24 fps) whenever the Initial Video trim changes. It is an
-       * ordinary reference otherwise — reorderable, trimmable, removable —
-       * and the flag is panel state only, never recorded in metadata.
+       * defaults re-derive from the cutpoint (up to ~5s of lead-in at 24 fps,
+       * capped at the generated frame count so the backend keeps the whole
+       * window) whenever the Initial Video trim or the frame count changes.
+       * It is an ordinary reference otherwise — reorderable, trimmable,
+       * removable — and the flag is panel state only, never in metadata.
        */
       fromSourceVideo?: boolean;
     }
diff --git a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts
index 505c57bba19..5435c605456 100644
--- a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.test.ts
@@ -1279,6 +1279,28 @@ describe('reference-extend policy', () => {
     expect(reasons).toContainEqual(expect.stringContaining('cannot be combined with an initial video on this model'));
   });
 
+  it('a Wan -> Ref2VA switch snaps the frame count BEFORE sizing the tail window', () => {
+    // Wan's grid starts at 5 frames. Deriving the window before the snap sized
+    // it for that count, and the repair only ever shrank — so the panel landed
+    // on a 90-frame H3 generation with a 5-frame anchor, below the 13 frames
+    // `sample_text_conditioning_frames` needs. Generate failed outright.
+    for (const wanFrames of [5, 9, 21, 81]) {
+      const wan = wanModel('i2v-14b');
+      const toRef = getVideoModelSelectionResult({
+        currentSettings: settingsFor(wan, { modelKey: wan.key, numFrames: wanFrames, sourceVideo: initialVideo }),
+        model: ref2vaTransformer(),
+        models: [wan],
+      });
+      const linked = toRef.settings.references.find(
+        (entry) => entry.kind === 'video' && entry.fromSourceVideo === true
+      );
+
+      expect(toRef.settings.numFrames).toBe(90);
+      // 90 frames of 24 fps material off a 24 fps clip, whatever Wan was on.
+      expect(linked).toMatchObject({ clip: { endFrame: 400, startFrame: 311 } });
+    }
+  });
+
   it('an FL2VA -> Ref2VA switch keeps the initial video and derives its linked tail reference', () => {
     const fl2va = h3Model();
     const toRef = getVideoModelSelectionResult({
@@ -1289,8 +1311,12 @@ describe('reference-extend policy', () => {
 
     expect(toRef.settings.sourceVideo).toEqual(initialVideo);
     expect(toRef.clearedLabels).not.toContain('Initial video');
+    // The window is budgeted against the frame count the switch lands on
+    // (H3's 124-frame default, snapped AFTER the derivation): a reference
+    // longer than the generation is truncated at its seam end.
+    expect(toRef.settings.numFrames).toBe(124);
     expect(toRef.settings.references[0]).toMatchObject({
-      clip: { endFrame: 400, startFrame: 260, video_name: 'long.mp4' },
+      clip: { endFrame: 400, startFrame: 277, video_name: 'long.mp4' },
       conditioning: 'video_audio',
       fromSourceVideo: true,
       kind: 'video',
diff --git a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts
index 3e04ecd3cad..873d77622ed 100644
--- a/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/videoPolicies.ts
@@ -40,6 +40,7 @@ import {
 } from './dimensions';
 import {
   applyReferenceExtendSourceVideo,
+  applyReferenceExtendNumFrames,
   MIN_VIDEO_TRIM_FRAMES,
   resolveVideoMode,
   VIDEO_ASPECT_RATIO_IDS,
@@ -1413,6 +1414,18 @@ export const getVideoModelSelectionResult = ({
     addClearedLabel(clearedLabels, 'Initial video');
   }
 
+  // The frame count is snapped BEFORE the tail reference is derived: the window
+  // is budgeted against it, and deriving first left a Wan panel's count (as low
+  // as 5) sizing a window for a 90-frame H3 generation — under the 13 frames
+  // text conditioning needs, so Generate failed outright.
+  const snappedFrames = snapVideoNumFrames(model, next.numFrames);
+  const framesChanged = snappedFrames !== next.numFrames;
+
+  if (framesChanged) {
+    next.numFrames = snappedFrames;
+    addClearedLabel(clearedLabels, 'Frames');
+  }
+
   // Reference-extend: a surviving Initial Video (e.g. carried over from an
   // FL2VA extend setup) gets its linked tail reference derived, so the switch
   // lands on a generatable panel. Only when none exists yet: the transition
@@ -1424,7 +1437,19 @@ export const getVideoModelSelectionResult = ({
     next.sourceVideo &&
     !next.references.some((entry) => entry.kind === 'video' && entry.fromSourceVideo === true)
   ) {
-    next.references = applyReferenceExtendSourceVideo(next.references, next.sourceVideo, config.references.maxVideos);
+    next.references = applyReferenceExtendSourceVideo(
+      next.references,
+      next.sourceVideo,
+      config.references.maxVideos,
+      next.numFrames
+    );
+  }
+
+  // A tail reference carried in from another model keeps a window budgeted for
+  // that model's frame count. Only when the count actually moved: otherwise a
+  // task-neutral re-selection would reset a hand-tuned trim.
+  if (config.references?.extend && framesChanged) {
+    next.references = applyReferenceExtendNumFrames(next.references, next.numFrames);
   }
 
   if (next.firstFrameImage && !modes.includes('first-frame') && !modes.includes('first-last')) {
@@ -1449,13 +1474,6 @@ export const getVideoModelSelectionResult = ({
     addClearedLabel(clearedLabels, 'Target resolution');
   }
 
-  const snappedFrames = snapVideoNumFrames(model, next.numFrames);
-
-  if (snappedFrames !== next.numFrames) {
-    next.numFrames = snappedFrames;
-    addClearedLabel(clearedLabels, 'Frames');
-  }
-
   const clampedFps =
     config.fps.editable && Number.isFinite(next.fps)
       ? Math.min(config.fps.max, Math.max(config.fps.min, Math.round(next.fps)))
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index c80189f38b8..4aa586b2dfe 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -10,6 +10,7 @@ import { ModelSelect } from '@features/models/react';
 import { getVideoDurationSeconds, invertVideoAspectRatioId } from '@features/video/core/dimensions';
 import {
   applyReferenceExtendSourceVideo,
+  applyReferenceExtendNumFrames,
   normalizeVideoWidgetValues,
   resolveVideoMode,
   VIDEO_ASPECT_RATIO_IDS,
@@ -214,7 +215,6 @@ export const VideoWidgetView = () => {
       cfgScale: (cfgScale: number) => patch({ cfgScale }),
       cfgScaleLowNoise: (cfgScaleLowNoise: number) => patch({ cfgScaleLowNoise }),
       fps: (fps: number) => patch({ fps }),
-      numFrames: (numFrames: number) => patch({ numFrames }),
       randomizeSeed: (details: { checked: boolean }) => patch({ shouldRandomizeSeed: details.checked }),
       seed: ({ valueAsNumber }: NumberInput.ValueChangeDetails) =>
         Number.isFinite(valueAsNumber) && patch({ seed: valueAsNumber }),
@@ -251,10 +251,31 @@ export const VideoWidgetView = () => {
     [patch]
   );
   const setLastFrame = useCallback((lastFrameImage: ImageWithDims | null) => patch({ lastFrameImage }), [patch]);
+  // Not part of `set`: that object is memoized on `patch` alone so the field
+  // setters keep the children's `memo` intact, and this one has to track the
+  // reference list. The linked tail reference's window is budgeted against the
+  // generated frame count — the backend discards an ill-fitting window at its
+  // SEAM end — so the count and the window move together. The re-derive is
+  // idempotent: this fires once per keystroke of the Frames input, unclamped,
+  // so typing "345" arrives as 3, then 34, then 345.
+  const setNumFrames = useCallback(
+    (numFrames: number) =>
+      patch(
+        referenceExtend
+          ? { numFrames, references: applyReferenceExtendNumFrames(values.references, numFrames) }
+          : { numFrames }
+      ),
+    [patch, referenceExtend, values.references]
+  );
   const setSourceVideo = useCallback(
     (sourceVideo: VideoSourceClip | null) => {
       if (referenceExtend) {
-        const references = applyReferenceExtendSourceVideo(values.references, sourceVideo, maxVideoReferences);
+        const references = applyReferenceExtendSourceVideo(
+          values.references,
+          sourceVideo,
+          maxVideoReferences,
+          values.numFrames
+        );
 
         // Unchanged identity with a clip set means the video cap is full and
         // no same-clip entry could be adopted: the extension would run with
@@ -271,7 +292,7 @@ export const VideoWidgetView = () => {
       }
       patch({ sourceVideo, ...(sourceVideo ? { firstFrameImage: null } : {}) });
     },
-    [maxVideoReferences, patch, referenceExtend, t, values.references]
+    [maxVideoReferences, patch, referenceExtend, t, values.numFrames, values.references]
   );
   const setReferences = useCallback(
     (references: VideoReferenceItem[]) =>
@@ -530,7 +551,7 @@ export const VideoWidgetView = () => {
               min={framesSlider.min}
               step={framesSlider.step}
               value={values.numFrames}
-              onChange={set.numFrames}
+              onChange={setNumFrames}
             />
           </Field>
           {policy.ui.fpsVisible ? (

From afb6899dc2f6b91ad3302c75f3dd410396c6d7a9 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Sun, 30 Aug 2026 23:30:37 -0400
Subject: [PATCH 05/19] fix(webv2): anchor the linked tail window's start to
 the clip end

`toTailAwareIndex` sends a near-the-end bound out as a NEGATIVE index the
backend resolves against the clip's REAL frame count, and leaves anything
further back POSITIVE, taken from the panel's ESTIMATE (duration x fps). That
split is right for a hand-picked trim, whose start is an absolute position the
estimate must not drift.

The linked tail window straddles it: the cutpoint end goes negative while the
start, a tail-length back, stays positive -- so what the backend extracts is
`tail + (real - estimate)` frames, not `tail`. The length is a budget the
backend enforces by discarding the overrun at the SEAM, so an inexact estimate
put back exactly the frames the budget exists to protect. It also meant an
estimate that overshot by more than `tail - 1` walked the start past the end
and raised, a margin that shrank with the frame-rate-scaled window (140 frames
flat before, as low as 29 for an 8 fps source).

The linked entry's start is not an absolute pick -- it is defined as `tail - 1`
frames before the cutpoint -- so it now rides the same negative anchor and the
window keeps its exact length at any real count. Two cases stay absolute: a
start the clip's own beginning already clamped to 0, and a cutpoint far enough
from the end that both bounds already share the estimate.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../src/features/video/core/graph.test.ts     | 31 +++++++-
 .../webv2/src/features/video/core/graph.ts    | 77 ++++++++++++++-----
 2 files changed, 89 insertions(+), 19 deletions(-)

diff --git a/invokeai/frontend/webv2/src/features/video/core/graph.test.ts b/invokeai/frontend/webv2/src/features/video/core/graph.test.ts
index d2f4acbba91..3b3fa422301 100644
--- a/invokeai/frontend/webv2/src/features/video/core/graph.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/graph.test.ts
@@ -557,6 +557,30 @@ describe('compileVideoGraph — MiniMax H3 Ref2VA', () => {
     );
   });
 
+  it('reference-extend: only the linked tail window is anchored to the clip end', () => {
+    const linked = (clip: Record<string, unknown>, flag = true) => ({
+      clip: { fps: 24, height: 480, numFrames: 402, video_name: 'long.mp4', width: 832, ...clip },
+      conditioning: 'video_audio' as const,
+      ...(flag ? { fromSourceVideo: true } : {}),
+      kind: 'video' as const,
+    });
+    const startOf = (reference: unknown) =>
+      nodeOfType(
+        compileVideoGraph({ ...referenceSettings, references: [reference] } as never, model).backendGraph,
+        'minimax_h3_video_reference'
+      ).start_frame;
+
+    // A user's own reference keeps an absolute start: their trim is a position,
+    // not a length, and re-anchoring it would drift with the estimate.
+    expect(startOf(linked({ endFrame: 400, startFrame: 260 }, false))).toBe(260);
+    // A start the clip's own beginning clamped stays 0 — true at any real count.
+    expect(startOf(linked({ endFrame: 400, startFrame: 0 }))).toBe(0);
+    // A cutpoint far enough from the end that BOTH bounds keep the estimate.
+    expect(startOf(linked({ endFrame: 300, startFrame: 160 }))).toBe(160);
+    // The tail case: end went negative, so the start follows it.
+    expect(startOf(linked({ endFrame: 400, startFrame: 260 }))).toBe(-142);
+  });
+
   it('fl2va graphs are unchanged by the ref2va machinery', () => {
     const { backendGraph } = compileVideoGraph(settingsFor(componentSource), componentSource);
 
@@ -608,7 +632,12 @@ describe('compileVideoGraph — MiniMax H3 Ref2VA', () => {
     // The linked reference is an ordinary first reference; the flag never reaches metadata.
     const videoReferences = nodesOfType(backendGraph, 'minimax_h3_video_reference');
 
-    expect(videoReferences[0]).toMatchObject({ id: 'reference_1', start_frame: 260 });
+    // Both bounds ride the SAME negative anchor, so the extracted window keeps
+    // its exact length whatever the clip's real frame count turns out to be.
+    // A positive start would have made it `tail + (real - estimate)` frames,
+    // and the overrun is discarded at the seam.
+    expect(videoReferences[0]).toMatchObject({ end_frame: -2, id: 'reference_1', start_frame: -142 });
+    expect((videoReferences[0].end_frame as number) - (videoReferences[0].start_frame as number)).toBe(140);
     const metadata = nodeOfType(backendGraph, 'core_metadata');
 
     expect(metadata.generation_mode).toBe('minimax_h3_ref2v');
diff --git a/invokeai/frontend/webv2/src/features/video/core/graph.ts b/invokeai/frontend/webv2/src/features/video/core/graph.ts
index d31ac4bb66f..bca9256bad3 100644
--- a/invokeai/frontend/webv2/src/features/video/core/graph.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/graph.ts
@@ -66,24 +66,7 @@ const addReferenceNodes = (
 ): BackendInvocationContract => {
   let chain: BackendInvocationContract | null = null;
   references.forEach((reference, index) => {
-    const node =
-      reference.kind === 'image'
-        ? addNode(graph, {
-            detail: reference.detail,
-            id: `reference_${index + 1}`,
-            image: toImageField(reference.image),
-            type: 'minimax_h3_image_reference',
-          })
-        : addNode(graph, {
-            conditioning: reference.conditioning,
-            // Same estimate-overshoot protection as the extend path: tail-window bounds
-            // compile as negative indices the backend resolves against the REAL count.
-            end_frame: toTailAwareIndex(reference.clip.endFrame, reference.clip.numFrames),
-            id: `reference_${index + 1}`,
-            start_frame: toTailAwareIndex(reference.clip.startFrame, reference.clip.numFrames),
-            type: 'minimax_h3_video_reference',
-            video: { video_name: reference.clip.video_name },
-          });
+    const node = addReferenceNode(graph, reference, index);
     const collect = addNode(graph, { id: `reference_collect_${index + 1}`, type: 'collect' });
 
     if (chain) {
@@ -100,6 +83,64 @@ const addReferenceNodes = (
   return chain;
 };
 
+const addReferenceNode = (
+  graph: BackendGraphContract,
+  reference: VideoReferenceItem,
+  index: number
+): BackendInvocationContract => {
+  if (reference.kind === 'image') {
+    return addNode(graph, {
+      detail: reference.detail,
+      id: `reference_${index + 1}`,
+      image: toImageField(reference.image),
+      type: 'minimax_h3_image_reference',
+    });
+  }
+  // Same estimate-overshoot protection as the extend path: tail-window bounds
+  // compile as negative indices the backend resolves against the REAL count.
+  const endFrame = toTailAwareIndex(reference.clip.endFrame, reference.clip.numFrames);
+
+  return addNode(graph, {
+    conditioning: reference.conditioning,
+    end_frame: endFrame,
+    id: `reference_${index + 1}`,
+    start_frame: toReferenceStartIndex(reference, endFrame),
+    type: 'minimax_h3_video_reference',
+    video: { video_name: reference.clip.video_name },
+  });
+};
+
+/**
+ * A video reference's start bound, measured from the same end as its other bound.
+ *
+ * `toTailAwareIndex` sends a near-the-end bound out NEGATIVE, resolved against
+ * the clip's REAL frame count, and leaves anything further back POSITIVE, taken
+ * from the panel's ESTIMATE. That split is right for a hand-picked trim, whose
+ * start is an absolute position the estimate must not drift — but the linked
+ * tail window straddles it: the cutpoint end goes negative while the start,
+ * ~124 frames back, stays positive, so what the backend extracts is
+ * `tail + (real - estimate)` frames rather than `tail`. That length is a budget
+ * the backend enforces by discarding the overrun at the SEAM (see
+ * `deriveReferenceExtendClip`), so it has to survive an inexact estimate.
+ *
+ * The linked entry's start is not an absolute pick — it is defined as
+ * `tail - 1` frames before the cutpoint — so it rides the same negative anchor
+ * and the window keeps its length whatever the real count turns out to be. Two
+ * cases stay absolute: a start the clip's own beginning already clamped to 0
+ * ("sample from the top" is true at any real count), and a cutpoint far enough
+ * from the end that the end bound stayed positive, where both bounds already
+ * share the estimate.
+ */
+const toReferenceStartIndex = (reference: Extract<VideoReferenceItem, { kind: 'video' }>, endIndex: number): number => {
+  const { clip } = reference;
+
+  if (reference.fromSourceVideo !== true || clip.startFrame === 0 || endIndex >= 0) {
+    return toTailAwareIndex(clip.startFrame, clip.numFrames);
+  }
+
+  return endIndex - (clip.endFrame - clip.startFrame);
+};
+
 const addPromptAndSeedNodes = (graph: BackendGraphContract) => ({
   negativePrompt: addNode(graph, { id: 'negative_prompt', type: 'string' }),
   positivePrompt: addNode(graph, { id: 'positive_prompt', type: 'string' }),

From e36562f41334628a4091db55f6575deff053786e Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Sun, 30 Aug 2026 23:38:40 -0400
Subject: [PATCH 06/19] fix(webv2): pin the reference-extend continuity anchor
 last

Request order is rotary order: build_ref2va_packed_sequence lays the reference
blocks out in order, each advancing a shared clock, and the generated rows
start at the position the LAST block left behind. The linked tail reference
only anchors anything if it IS that block -- an image dropped after the Initial
Video wedges a whole rotary slot between the initial video's tail and the first
generated frame, and the model continues from the image instead. Two ordinary
actions in the wrong order were enough, with nothing in the UI to say so.

The anchor's position is now derived like its trim: last, always.
`pinReferenceExtendAnchor` runs in the reference field's single setter, so it
covers add, remove, retrim and drag alike, and on the adopt path where a
recalled entry is claimed in place.

The video cap is enforced at both doors rather than only one. The add-video
button was already gated; the Initial Video field now disables itself when the
video slots are full and no anchor exists yet, since setting a clip there has
to place one. With an anchor already present the drop only re-derives it in
place, so it stays available -- swapping the initial video keeps working.

And `sanitizeVideoReferences` overflows videos from the FRONT. It keeps the
first N of each kind, which for videos is now exactly backwards: with the
anchor pinned last, tail-dropping discards the one entry the extension depends
on. An over-cap list should no longer reach it from the UI at all, so this is
the guard for a stale or hand-edited project record. Images have no ordering
role and keep the front.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../frontend/webv2/public/locales/en.json     |  1 +
 .../src/features/video/core/settings.test.ts  | 53 +++++++++++++++-
 .../webv2/src/features/video/core/settings.ts | 62 +++++++++++++++----
 .../src/features/video/ui/VideoWidgetView.tsx | 33 ++++++++--
 4 files changed, 129 insertions(+), 20 deletions(-)

diff --git a/invokeai/frontend/webv2/public/locales/en.json b/invokeai/frontend/webv2/public/locales/en.json
index 237b1037031..6df1b51204d 100644
--- a/invokeai/frontend/webv2/public/locales/en.json
+++ b/invokeai/frontend/webv2/public/locales/en.json
@@ -3110,6 +3110,7 @@
       "initialFrames": "Start & End Images",
       "initialVideo": "Initial Video",
       "initialVideoBlocked": "Clear the first frame to extend a video instead.",
+      "initialVideoCapBlocked": "All 3 video reference slots are in use, so there is no room for the continuity reference this clip needs. Remove a video reference first.",
       "lastFrame": "Last Frame",
       "lastFrameExtendHelp": "Optional destination: the extension ends on this image.",
       "lastFrameHelp": "Optional: the video ends on this image (interpolates from the first frame).",
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index 24cb085fff1..be775970d81 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -6,6 +6,7 @@ import { MINIMAX_H3_NUM_FRAMES_CHOICES } from './dimensions';
 import {
   applyReferenceExtendSourceVideo,
   applyReferenceExtendNumFrames,
+  pinReferenceExtendAnchor,
   clearDeletedVideoMedia,
   cloneVideoWidgetValues,
   createVideoSourceClip,
@@ -336,6 +337,7 @@ describe('references', () => {
   });
 
   it('normalization drops malformed entries and enforces the caps, preserving order', () => {
+    // Videos over the cap overflow from the FRONT — see the over-cap test below.
     const tooMany = [
       ...Array.from({ length: 4 }, (_, index) => ({
         ...VIDEO_REFERENCE,
@@ -347,13 +349,33 @@ describe('references', () => {
     const normalized = normalizeVideoSettings(createSettings({ references: tooMany as never }));
 
     expect(normalized?.references.map((entry) => (entry.kind === 'video' ? entry.clip.video_name : 'img'))).toEqual([
-      'v0.mp4',
       'v1.mp4',
       'v2.mp4',
+      'v3.mp4',
       'img',
     ]);
   });
 
+  it('an over-cap video list overflows from the front, keeping the continuity anchor', () => {
+    // The anchor is last, so dropping from the tail would discard exactly the
+    // entry the extension depends on. Reachable only from a stale record.
+    const tooMany = [
+      IMAGE_REFERENCE,
+      ...Array.from({ length: 5 }, (_unused, index) => ({
+        ...VIDEO_REFERENCE,
+        clip: { ...VIDEO_REFERENCE.clip, video_name: `v${index}.mp4` },
+      })),
+    ];
+    const normalized = normalizeVideoSettings(createSettings({ references: tooMany as never }));
+
+    expect(normalized?.references.map((entry) => (entry.kind === 'video' ? entry.clip.video_name : 'img'))).toEqual([
+      'img',
+      'v2.mp4',
+      'v3.mp4',
+      'v4.mp4',
+    ]);
+  });
+
   it('isVideoSettings rejects references combined with frame media', () => {
     expect(isVideoSettings(createSettings({ firstFrameImage: FIRST_FRAME, references: [IMAGE_REFERENCE] }))).toBe(
       false
@@ -551,6 +573,35 @@ describe('reference-extend linkage', () => {
     });
   });
 
+  it('pins the continuity anchor last, whatever the add or drag order', () => {
+    // Request order is rotary order: the generated frames continue from the
+    // LAST reference block. An image added after the Initial Video would
+    // otherwise take a rotary slot between the initial video's tail and the
+    // first generated frame.
+    const linked = applyReferenceExtendSourceVideo([], source24, 3, FRAMES);
+    const anchor = linked[0]!;
+
+    expect(pinReferenceExtendAnchor([anchor, IMAGE_REFERENCE])).toEqual([IMAGE_REFERENCE, anchor]);
+    expect(pinReferenceExtendAnchor([IMAGE_REFERENCE, VIDEO_REFERENCE, anchor])).toEqual([
+      IMAGE_REFERENCE,
+      VIDEO_REFERENCE,
+      anchor,
+    ]);
+    // Identity-preserving when already last, and when there is no anchor.
+    const settled = [IMAGE_REFERENCE, anchor];
+
+    expect(pinReferenceExtendAnchor(settled)).toBe(settled);
+    const none = [IMAGE_REFERENCE, VIDEO_REFERENCE];
+
+    expect(pinReferenceExtendAnchor(none)).toBe(none);
+
+    // Adopting a recalled entry re-pins it rather than leaving it in place.
+    const recalled = { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'long.mp4' } };
+    const adopted = applyReferenceExtendSourceVideo([recalled, IMAGE_REFERENCE], source24, 3, FRAMES);
+
+    expect(adopted[1]).toMatchObject({ fromSourceVideo: true, kind: 'video' });
+  });
+
   it('applyReferenceExtendNumFrames leaves unlinked references alone', () => {
     const unlinked = [VIDEO_REFERENCE, IMAGE_REFERENCE];
 
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index de4da8cca4d..da3d3eb07fc 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -101,28 +101,36 @@ export const isVideoReferenceItem = (value: unknown): value is VideoReferenceIte
   return false;
 };
 
-/** Drops invalid entries and enforces the per-kind caps, preserving order. */
+/**
+ * Drops invalid entries and enforces the per-kind caps, preserving order.
+ *
+ * An over-cap list should never reach here — both add paths are gated on the
+ * cap and the Initial Video field disables itself when the video slots are
+ * full — so this is the guard for a stale or hand-edited project record.
+ *
+ * Videos overflow from the FRONT. Request order is rotary order and the
+ * generated frames continue from the LAST reference block, so on a
+ * reference-extend panel the final video is the continuity anchor: dropping
+ * from the tail would discard exactly the entry the extension depends on.
+ * Images carry no ordering role and keep the front.
+ */
 const sanitizeVideoReferences = (value: unknown): VideoReferenceItem[] => {
   if (!Array.isArray(value)) {
     return [];
   }
+  const valid = value.filter((entry) => isVideoReferenceItem(entry));
+  let videosToDrop = Math.max(0, valid.filter((entry) => entry.kind === 'video').length - VIDEO_REFERENCE_MAX_VIDEOS);
   const result: VideoReferenceItem[] = [];
-  let videos = 0;
   let images = 0;
-  for (const entry of value) {
-    if (!isVideoReferenceItem(entry)) {
-      continue;
-    }
+  for (const entry of valid) {
     if (entry.kind === 'image') {
       if (images >= VIDEO_REFERENCE_MAX_IMAGES) {
         continue;
       }
       images += 1;
-    } else {
-      if (videos >= VIDEO_REFERENCE_MAX_VIDEOS) {
-        continue;
-      }
-      videos += 1;
+    } else if (videosToDrop > 0) {
+      videosToDrop -= 1;
+      continue;
     }
     result.push(entry);
   }
@@ -484,6 +492,32 @@ export const applyReferenceExtendNumFrames = (
   return changed ? next : references;
 };
 
+/**
+ * Moves the linked tail reference to the end of the list.
+ *
+ * Request order is rotary order: `build_ref2va_packed_sequence` lays the
+ * reference blocks out in order, each advancing a shared clock, and the
+ * generated rows start at the position the LAST block left behind. The
+ * continuity anchor only anchors anything if it IS that block — an image
+ * dropped afterwards wedges itself (a whole rotary slot) between the initial
+ * video's tail and the first generated frame, and the model continues from the
+ * image instead.
+ *
+ * Add order and drag order must not decide that, so the anchor's position is
+ * derived like its trim: last, always. Identity-preserving when it is already
+ * last, or when there is no anchor.
+ */
+export const pinReferenceExtendAnchor = (references: VideoReferenceItem[]): VideoReferenceItem[] => {
+  const index = references.findIndex((entry) => entry.kind === 'video' && entry.fromSourceVideo === true);
+
+  if (index < 0 || index === references.length - 1) {
+    return references;
+  }
+  const pinned = references[index]!;
+
+  return [...references.slice(0, index), ...references.slice(index + 1), pinned];
+};
+
 /**
  * Keeps the reference list in step with the Initial Video on a reference-extend
  * panel (pure; the setter and the model-selection transition both use it):
@@ -536,8 +570,10 @@ export const applyReferenceExtendSourceVideo = (
       : references.findIndex((entry) => entry.kind === 'video' && entry.clip.video_name === sourceVideo.video_name);
 
   if (linkedIndex >= 0) {
-    return references.map((entry, index) =>
-      index === linkedIndex && entry.kind === 'video' ? { ...linked, conditioning: entry.conditioning } : entry
+    return pinReferenceExtendAnchor(
+      references.map((entry, index) =>
+        index === linkedIndex && entry.kind === 'video' ? { ...linked, conditioning: entry.conditioning } : entry
+      )
     );
   }
 
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index 4aa586b2dfe..483196894e1 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -11,6 +11,7 @@ import { getVideoDurationSeconds, invertVideoAspectRatioId } from '@features/vid
 import {
   applyReferenceExtendSourceVideo,
   applyReferenceExtendNumFrames,
+  pinReferenceExtendAnchor,
   normalizeVideoWidgetValues,
   resolveVideoMode,
   VIDEO_ASPECT_RATIO_IDS,
@@ -294,14 +295,21 @@ export const VideoWidgetView = () => {
     },
     [maxVideoReferences, patch, referenceExtend, t, values.numFrames, values.references]
   );
+  // The single choke point for every list edit the reference field makes — add,
+  // remove, retrim, reorder — so pinning the continuity anchor here covers all
+  // of them. Request order is rotary order and the generation continues from
+  // the LAST reference, so the anchor's position is derived, not user-set.
   const setReferences = useCallback(
-    (references: VideoReferenceItem[]) =>
+    (references: VideoReferenceItem[]) => {
+      const next = referenceExtend ? pinReferenceExtendAnchor(references) : references;
+
       patch({
-        references,
-        ...(references.length > 0
+        references: next,
+        ...(next.length > 0
           ? { firstFrameImage: null, lastFrameImage: null, ...(referenceExtend ? {} : { sourceVideo: null }) }
           : {}),
-      }),
+      });
+    },
     [patch, referenceExtend]
   );
   const clearReferences = useCallback(() => patch({ references: [] }), [patch]);
@@ -372,6 +380,13 @@ export const VideoWidgetView = () => {
   const supportsExtend = policy.modes.includes('extend');
   const supportsReferences = policy.modes.includes('reference');
   const supportsInitialVideo = supportsExtend || referenceExtend;
+  // Setting an Initial Video on a reference-extend panel has to place a linked
+  // tail reference, which needs a free video slot. With an anchor already
+  // present the drop only re-derives it in place, so it stays available.
+  const initialVideoCapBlocked =
+    referenceExtend &&
+    !values.references.some((entry) => entry.kind === 'video' && entry.fromSourceVideo === true) &&
+    values.references.filter((entry) => entry.kind === 'video').length >= maxVideoReferences;
   const hasConditioningMedia = Boolean(values.firstFrameImage || values.lastFrameImage || values.sourceVideo);
   const derivedSourceText = dimensions ? t(`widgets.video.dimensionSource.${dimensions.source}`) : undefined;
   const derivedSizeText = dimensions
@@ -504,8 +519,14 @@ export const VideoWidgetView = () => {
               </Text>
             ) : null}
             <VideoSourceClipField
-              disabled={Boolean(values.firstFrameImage)}
-              disabledReason={values.firstFrameImage ? t('widgets.video.initialVideoBlocked') : undefined}
+              disabled={Boolean(values.firstFrameImage) || initialVideoCapBlocked}
+              disabledReason={
+                values.firstFrameImage
+                  ? t('widgets.video.initialVideoBlocked')
+                  : initialVideoCapBlocked
+                    ? t('widgets.video.initialVideoCapBlocked')
+                    : undefined
+              }
               sourceVideo={values.sourceVideo}
               onChange={setSourceVideo}
             />

From e479c7517cbfec6d19ecc89f45b06b4a0a234c88 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 07:49:26 -0400
Subject: [PATCH 07/19] fix(webv2): give the seed randomize switch an id of its
 own

Clicking the randomize-seed toggle in the Video panel moved focus to the Seed
text field and never toggled anything. The Upscale panel had the same bug.

Chakra's `Field.Root` hands its single `ids.control` to EVERY control nested
inside it, and both panels' seed rows put three controls in one `Field` -- the
seed NumberInput, the shuffle button and the switch. The switch's hidden input
therefore claimed the same id as the seed input:

    seedId=_r_0_  swId=_r_0_  collision=true
    switchLabelFor=_r_0_      focusedSeed=true  fired=0

`Switch.Root` renders a `<label>`, and `label[for]` resolves to the FIRST
element carrying that id -- the seed NumberInput, earlier in the DOM. So the
click activated the seed field and the switch never saw it. Giving the switch
its own `ids.hiddenInput`, derived from `useId` so it stays unique across
widget instances, breaks the collision.

The Video panel's label text was also an inert `<Text>` sibling outside
`Switch.Root`, so even a working switch would not have responded to a click on
the words. It is now a `Switch.Label`, matching Upscale.

Covered by a browser test asserting the switch and the seed input hold
different ids, that the switch's own label points at the switch, and that
clicking either the control or the label toggles without focusing the seed
field. Verified failing before the fix (`fired=0`).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../features/upscale/ui/UpscaleWidgetView.tsx | 16 ++-
 .../src/features/video/ui/VideoWidgetView.tsx | 24 ++++-
 .../video/ui/seedToggle.browser.test.tsx      | 98 +++++++++++++++++++
 3 files changed, 131 insertions(+), 7 deletions(-)
 create mode 100644 invokeai/frontend/webv2/src/features/video/ui/seedToggle.browser.test.tsx

diff --git a/invokeai/frontend/webv2/src/features/upscale/ui/UpscaleWidgetView.tsx b/invokeai/frontend/webv2/src/features/upscale/ui/UpscaleWidgetView.tsx
index f53f959cc2b..e1ae5ebed83 100644
--- a/invokeai/frontend/webv2/src/features/upscale/ui/UpscaleWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/upscale/ui/UpscaleWidgetView.tsx
@@ -52,7 +52,7 @@ import { Combobox, Field, IconButton, Select, Tooltip } from '@platform/ui';
 import { SliderNumberField } from '@platform/ui/SliderNumberField';
 import { toaster } from '@platform/ui/toaster';
 import { DicesIcon } from 'lucide-react';
-import { memo, useCallback, useMemo } from 'react';
+import { memo, useCallback, useId, useMemo } from 'react';
 import { useTranslation } from 'react-i18next';
 
 import { areInputImagesEquivalent, valuesAreEqual } from './upscaleComparators';
@@ -284,6 +284,13 @@ export const UpscaleWidgetView = () => {
     [t, values]
   );
   const patch = useCallback((next: Partial<UpscaleWidgetValues>) => patchValues(next), [patchValues]);
+  // Chakra's `Field.Root` hands its single `ids.control` to EVERY control
+  // inside it, and the seed Field holds the NumberInput, the shuffle button
+  // and this switch. Without an id of its own the switch's hidden input
+  // collides with the seed input, so the `<label>` Switch.Root renders points
+  // at the seed field and clicking the toggle only moved focus.
+  const seedSwitchId = useId();
+  const seedSwitchIds = useMemo(() => ({ hiddenInput: `${seedSwitchId}-randomize-seed` }), [seedSwitchId]);
   const patchPromptDraft = useCallback((next: ProjectPromptDraftPatch) => patchDraft(next), [patchDraft]);
 
   useMountEffect(() => {
@@ -639,7 +646,12 @@ export const UpscaleWidgetView = () => {
                   <DicesIcon />
                 </IconButton>
               </Tooltip>
-              <Switch.Root checked={values.shouldRandomizeSeed} size="sm" onCheckedChange={set.randomizeSeed}>
+              <Switch.Root
+                checked={values.shouldRandomizeSeed}
+                ids={seedSwitchIds}
+                size="sm"
+                onCheckedChange={set.randomizeSeed}
+              >
                 <Switch.HiddenInput />
                 <Switch.Control _checked={SWITCH_CHECKED_PROPS}>
                   <Switch.Thumb />
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index 483196894e1..ba6d790bbe3 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -31,7 +31,7 @@ import { Button } from '@platform/ui/Button';
 import { SliderNumberField } from '@platform/ui/SliderNumberField';
 import { toaster } from '@platform/ui/toaster';
 import { ArrowLeftRightIcon, DicesIcon } from 'lucide-react';
-import { useCallback, useMemo } from 'react';
+import { useCallback, useId, useMemo } from 'react';
 import { useTranslation } from 'react-i18next';
 
 import { areVideoValuesEqual } from './videoComparators';
@@ -150,6 +150,13 @@ export const VideoWidgetView = () => {
   );
 
   const patch = useCallback((next: Partial<VideoWidgetValues>) => patchValues(next), [patchValues]);
+  // Chakra's `Field.Root` hands its single `ids.control` to EVERY control
+  // inside it, and this Field holds three. Without an id of its own the
+  // switch's hidden input collides with the seed NumberInput, so the
+  // `<label>` Switch.Root renders points at the seed field: clicking the
+  // toggle focused the seed input and never toggled anything.
+  const seedSwitchId = useId();
+  const seedSwitchIds = useMemo(() => ({ hiddenInput: `${seedSwitchId}-randomize-seed` }), [seedSwitchId]);
 
   useMountEffect(() => {
     void ensureModelsLoaded();
@@ -679,15 +686,22 @@ export const VideoWidgetView = () => {
                 <DicesIcon />
               </IconButton>
               <HStack gap="1">
-                <Switch.Root checked={values.shouldRandomizeSeed} size="sm" onCheckedChange={set.randomizeSeed}>
+                <Switch.Root
+                  checked={values.shouldRandomizeSeed}
+                  ids={seedSwitchIds}
+                  size="sm"
+                  onCheckedChange={set.randomizeSeed}
+                >
                   <Switch.HiddenInput />
                   <Switch.Control _checked={SWITCH_CHECKED_PROPS}>
                     <Switch.Thumb />
                   </Switch.Control>
+                  {/* Inside Switch.Root, so the words are part of the control
+                      (they were an inert sibling <Text> before). */}
+                  <Switch.Label color="fg.muted" fontSize="2xs">
+                    {t('widgets.video.randomizeSeed')}
+                  </Switch.Label>
                 </Switch.Root>
-                <Text color="fg.muted" fontSize="2xs">
-                  {t('widgets.video.randomizeSeed')}
-                </Text>
               </HStack>
             </HStack>
           </Field>
diff --git a/invokeai/frontend/webv2/src/features/video/ui/seedToggle.browser.test.tsx b/invokeai/frontend/webv2/src/features/video/ui/seedToggle.browser.test.tsx
new file mode 100644
index 00000000000..a998c18175a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/features/video/ui/seedToggle.browser.test.tsx
@@ -0,0 +1,98 @@
+import { ChakraProvider, NumberInput, Switch } from '@chakra-ui/react';
+import { Field } from '@platform/ui/Field';
+import { system } from '@theme/system';
+import { act, useId, useMemo } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { userEvent } from 'vitest/browser';
+
+/**
+ * The seed row of the Video and Upscale panels puts three controls -- a seed
+ * NumberInput, a shuffle button and a randomize Switch -- inside ONE `Field`.
+ * Chakra's `Field.Root` hands its single `ids.control` to every control it
+ * contains, so without an id of its own the switch's hidden input collides
+ * with the seed input and the `<label>` that `Switch.Root` renders resolves to
+ * the seed field instead. Clicking the toggle then just moved focus.
+ */
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+const SeedRow = ({ onCheckedChange }: { onCheckedChange: (details: { checked: boolean }) => void }) => {
+  const seedSwitchId = useId();
+  const seedSwitchIds = useMemo(() => ({ hiddenInput: `${seedSwitchId}-randomize-seed` }), [seedSwitchId]);
+
+  return (
+    <Field hint="seed" label="Seed">
+      <NumberInput.Root size="xs" value="42">
+        <NumberInput.Input aria-label="Seed" />
+      </NumberInput.Root>
+      <Switch.Root checked={false} ids={seedSwitchIds} size="sm" onCheckedChange={onCheckedChange}>
+        <Switch.HiddenInput data-testid="switch-input" />
+        <Switch.Control data-testid="switch-control">
+          <Switch.Thumb />
+        </Switch.Control>
+        <Switch.Label>Randomize seed</Switch.Label>
+      </Switch.Root>
+    </Field>
+  );
+};
+
+const render = (onCheckedChange: (details: { checked: boolean }) => void) =>
+  act(() => {
+    root.render(
+      <ChakraProvider value={system}>
+        <SeedRow onCheckedChange={onCheckedChange} />
+      </ChakraProvider>
+    );
+  });
+
+describe('seed row randomize switch', () => {
+  it('does not share the Field control id with the seed input', async () => {
+    await render(vi.fn());
+
+    const seed = container.querySelector<HTMLInputElement>('input[aria-label="Seed"]')!;
+    const toggle = container.querySelector<HTMLInputElement>('[data-testid="switch-input"]')!;
+
+    expect(toggle.id).not.toBe('');
+    expect(toggle.id).not.toBe(seed.id);
+    // The label Switch.Root renders must point at the switch, not the seed field.
+    expect(toggle.closest('label')?.getAttribute('for')).toBe(toggle.id);
+  });
+
+  it('toggles when the control is clicked, leaving the seed input unfocused', async () => {
+    const onCheckedChange = vi.fn();
+
+    await render(onCheckedChange);
+    const seed = container.querySelector<HTMLInputElement>('input[aria-label="Seed"]')!;
+
+    await userEvent.click(container.querySelector('[data-testid="switch-control"]')!);
+
+    expect(onCheckedChange).toHaveBeenCalledWith(expect.objectContaining({ checked: true }));
+    expect(document.activeElement).not.toBe(seed);
+  });
+
+  it('toggles when the label text is clicked', async () => {
+    const onCheckedChange = vi.fn();
+
+    await render(onCheckedChange);
+
+    const label = [...container.querySelectorAll('*')].find(
+      (node) => node.textContent === 'Randomize seed' && node.children.length === 0
+    )!;
+
+    await userEvent.click(label);
+
+    expect(onCheckedChange).toHaveBeenCalledWith(expect.objectContaining({ checked: true }));
+  });
+});

From f517b42c76227a01a4ff1fba204b9547550d0dd0 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 08:03:06 -0400
Subject: [PATCH 08/19] fix(webv2): keep the tail window's start absolute
 inside the estimate slop

The relative start index resolves to `startFrame + (real - estimate)`, which
goes NEGATIVE once the estimate overshoots by more than `startFrame` --
and `_ResolvedVideoRange.resolve` rejects an out-of-range index outright
rather than clamping, so Generate failed with

    start_frame=-142 is out of range for a 138-frame reference video

The guard was `startFrame === 0`, which misses by exactly the margin that
matters: a start of 1 is the common case for a clip barely longer than the
window, and `duration x fps` overshooting by a frame or two is the error
`toTailAwareIndex` was written to absorb in the first place. Before the
relative start existed the same input emitted a positive 1 and generated fine,
so this turned a small quality loss into a hard failure.

The guard is now `startFrame <= TAIL_INDEX_SLOP`, reusing (and naming) the
3-frame allowance `toTailAwareIndex` already applies at the other end of the
clip. Below the slop the window fills nearly the whole clip, where its length
cannot be honoured anyway, and the absolute form is always in range; the drift
it costs there is the estimate error itself. Above it the window keeps its
exact length at any real count, which is what the relative form is for.

Verified against the review's failing cases: est=143/real=141, est=145/real=138,
est=92/real=90 and est=1002/real=1000 all resolve, while est=402 keeps a
141-frame window at real counts of both 400 and 396.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../src/features/video/core/graph.test.ts     |  9 +++++-
 .../webv2/src/features/video/core/graph.ts    | 28 ++++++++++++++-----
 2 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/invokeai/frontend/webv2/src/features/video/core/graph.test.ts b/invokeai/frontend/webv2/src/features/video/core/graph.test.ts
index 3b3fa422301..04676668921 100644
--- a/invokeai/frontend/webv2/src/features/video/core/graph.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/graph.test.ts
@@ -573,8 +573,15 @@ describe('compileVideoGraph — MiniMax H3 Ref2VA', () => {
     // A user's own reference keeps an absolute start: their trim is a position,
     // not a length, and re-anchoring it would drift with the estimate.
     expect(startOf(linked({ endFrame: 400, startFrame: 260 }, false))).toBe(260);
-    // A start the clip's own beginning clamped stays 0 — true at any real count.
+    // A start at or inside the estimate's slop stays ABSOLUTE: the relative
+    // form resolves to `startFrame + (real - estimate)`, and the backend
+    // rejects a negative index rather than clamping, so an estimate that
+    // overshoots by more than `startFrame` would fail the whole generation.
     expect(startOf(linked({ endFrame: 400, startFrame: 0 }))).toBe(0);
+    expect(startOf(linked({ endFrame: 400, startFrame: 1 }))).toBe(1);
+    expect(startOf(linked({ endFrame: 400, startFrame: 3 }))).toBe(3);
+    // Clear of the slop, the window rides the negative anchor again.
+    expect(startOf(linked({ endFrame: 400, startFrame: 4 }))).toBe(-398);
     // A cutpoint far enough from the end that BOTH bounds keep the estimate.
     expect(startOf(linked({ endFrame: 300, startFrame: 160 }))).toBe(160);
     // The tail case: end went negative, so the start follows it.
diff --git a/invokeai/frontend/webv2/src/features/video/core/graph.ts b/invokeai/frontend/webv2/src/features/video/core/graph.ts
index bca9256bad3..dcddba2e128 100644
--- a/invokeai/frontend/webv2/src/features/video/core/graph.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/graph.ts
@@ -125,16 +125,23 @@ const addReferenceNode = (
  *
  * The linked entry's start is not an absolute pick — it is defined as
  * `tail - 1` frames before the cutpoint — so it rides the same negative anchor
- * and the window keeps its length whatever the real count turns out to be. Two
- * cases stay absolute: a start the clip's own beginning already clamped to 0
- * ("sample from the top" is true at any real count), and a cutpoint far enough
- * from the end that the end bound stayed positive, where both bounds already
- * share the estimate.
+ * and the window keeps its length whatever the real count turns out to be.
+ *
+ * Two cases stay absolute. A cutpoint far enough from the end leaves both
+ * bounds on the estimate already. And a start within `TAIL_INDEX_SLOP` of the
+ * clip's own beginning stays absolute because the relative form resolves to
+ * `startFrame + (real - estimate)`, which goes NEGATIVE once the estimate
+ * overshoots by more than `startFrame` — and `_ResolvedVideoRange.resolve`
+ * rejects an out-of-range index outright rather than clamping, failing the
+ * whole generation. That can only arise when the window fills nearly the entire
+ * clip, where its length cannot be honoured anyway; below the slop the absolute
+ * form is always in range, and the drift it costs is the estimate error itself,
+ * a frame or two.
  */
 const toReferenceStartIndex = (reference: Extract<VideoReferenceItem, { kind: 'video' }>, endIndex: number): number => {
   const { clip } = reference;
 
-  if (reference.fromSourceVideo !== true || clip.startFrame === 0 || endIndex >= 0) {
+  if (reference.fromSourceVideo !== true || endIndex >= 0 || clip.startFrame <= TAIL_INDEX_SLOP) {
     return toTailAwareIndex(clip.startFrame, clip.numFrames);
   }
 
@@ -166,10 +173,17 @@ const toImageField = (image: { image_name: string }) => ({ image_name: image.ima
 // start is always below the end, so the pair keeps its order when both go
 // negative). Mid-clip picks stay positive: a negative offset computed from
 // an overshooting estimate would drift them instead.
+/**
+ * How wrong the panel's `duration x fps` frame-count estimate is allowed to be.
+ * VFR containers overshoot it by a frame or two, so bounds within this many
+ * frames of the estimated end are emitted relative to the REAL end instead.
+ */
+const TAIL_INDEX_SLOP = 3;
+
 const toTailAwareIndex = (frame: number, estimatedNumFrames: number): number => {
   const tailOffset = estimatedNumFrames - 1 - frame;
 
-  return tailOffset <= 3 ? -(tailOffset + 1) : frame;
+  return tailOffset <= TAIL_INDEX_SLOP ? -(tailOffset + 1) : frame;
 };
 
 /**

From 8ce1d3b0607e1f30a55f371480df73de40391611 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 08:06:36 -0400
Subject: [PATCH 09/19] fix(webv2): pin the continuity anchor during
 normalization, before the cap trim

Two of this branch's own changes combined into data loss.

`sanitizeVideoReferences` was changed to drop videos from the FRONT, on the
reasoning that the anchor is pinned last so a tail-drop would discard it. That
holds only for panels this build wrote. The commit immediately before this
branch PREPENDED the anchor, so every project saved before it loads with the
anchor at index 0 -- and the front-drop then deletes exactly the entry it was
added to protect.

The second half is quieter and hits every already-saved panel, over the cap or
not: normalization never pinned, so a prepended anchor stayed first. The
generated frames continue from the LAST reference block, so those panels keep
generating from whatever reference follows the anchor. Nothing repaired it --
`setNumFrames` does not pin, and the model-selection transition skips the
derive entirely when a flagged entry already exists -- so it persisted until
the user happened to touch the reference list.

Pinning inside `sanitizeVideoReferences`, ahead of the cap trim, closes both:
the anchor is last by the time the overflow rule runs, so the front-drop
protects it, and normalization runs on every read, so old panels heal on load.

The pins in `setReferences` and `applyReferenceExtendSourceVideo` stay. They
are redundant with this one on any path that normalizes, but they keep the
written value correct for any that does not, and a violated ordering invariant
is silent.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../src/features/video/core/settings.test.ts  | 31 +++++++++++++++++++
 .../webv2/src/features/video/core/settings.ts |  8 ++++-
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index be775970d81..5201bc3e697 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -376,6 +376,37 @@ describe('references', () => {
     ]);
   });
 
+  it('normalization heals a panel saved with the anchor prepended', () => {
+    // The build before the anchor was pinned PREPENDED it, so those projects
+    // load with it at index 0. Normalization must move it last -- otherwise the
+    // generated frames continue from whatever reference follows it -- and it
+    // must do so BEFORE the cap trim, or the front-drop deletes the anchor.
+    const anchor = {
+      ...VIDEO_REFERENCE,
+      clip: { ...VIDEO_REFERENCE.clip, video_name: 'anchor.mp4' },
+      fromSourceVideo: true,
+    };
+    const named = (entry: { kind: string; clip?: { video_name: string } }) =>
+      entry.kind === 'video' ? entry.clip!.video_name : 'img';
+
+    const healed = normalizeVideoSettings(createSettings({ references: [anchor, IMAGE_REFERENCE] as never }));
+
+    expect(healed?.references.map(named as never)).toEqual(['img', 'anchor.mp4']);
+
+    // Over the cap, with the anchor in the position the old build left it.
+    const stale = [
+      anchor,
+      ...Array.from({ length: 3 }, (_unused, index) => ({
+        ...VIDEO_REFERENCE,
+        clip: { ...VIDEO_REFERENCE.clip, video_name: `v${index}.mp4` },
+      })),
+    ];
+    const trimmed = normalizeVideoSettings(createSettings({ references: stale as never }));
+
+    expect(trimmed?.references.map(named as never)).toEqual(['v1.mp4', 'v2.mp4', 'anchor.mp4']);
+    expect(trimmed?.references.at(-1)).toMatchObject({ fromSourceVideo: true });
+  });
+
   it('isVideoSettings rejects references combined with frame media', () => {
     expect(isVideoSettings(createSettings({ firstFrameImage: FIRST_FRAME, references: [IMAGE_REFERENCE] }))).toBe(
       false
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index da3d3eb07fc..de562521d20 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -118,7 +118,13 @@ const sanitizeVideoReferences = (value: unknown): VideoReferenceItem[] => {
   if (!Array.isArray(value)) {
     return [];
   }
-  const valid = value.filter((entry) => isVideoReferenceItem(entry));
+  // Pin BEFORE the cap trim. The front-drop below assumes the anchor is last,
+  // but a project saved by the build that PREPENDED it loads with the anchor
+  // first -- so without this the overflow rule deletes the one entry it exists
+  // to protect. Pinning here also heals those panels on load: normalization
+  // runs on every read, whereas `setReferences` only fires once the user
+  // touches the reference list.
+  const valid = pinReferenceExtendAnchor(value.filter((entry) => isVideoReferenceItem(entry)));
   let videosToDrop = Math.max(0, valid.filter((entry) => entry.kind === 'video').length - VIDEO_REFERENCE_MAX_VIDEOS);
   const result: VideoReferenceItem[] = [];
   let images = 0;

From f9749d3385252dc735037d11f01044c7cfbaea52 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 08:14:17 -0400
Subject: [PATCH 10/19] fix(webv2): make reference-list writes functional
 updates

`addImageReference` / `addVideoReference` closed over `references`, awaited a
gallery resolve, then wrote `[...references, item]` -- the array as it was at
drop time. `isLoading` gates the reference cards and the drop zone, but not the
Initial Video field or the Frames slider, and this branch made both of those
writers of `references`. Two losses, neither of them warned about:

- Drop a video into References; while it resolves, set an Initial Video. The
  resolve lands and writes the pre-anchor array. You get `sourceVideo` set with
  NO anchor, the cap gate reading false and validation passing, so the
  extension generates with no continuity reference at all.
- Drop an image into References; while it resolves, drag Frames 345 -> 90.
  `setNumFrames` re-derives the anchor to a 90-frame window; the resolve then
  restores the stale 141-frame one. `frames[:90]` keeps the FRONT, so 51 frames
  at the cutpoint are discarded -- the exact bug this branch exists to fix --
  and nothing re-derives afterwards, so it is permanent.

`onChange` now takes an updater instead of a snapshot, and `setReferences`
applies it against a ref holding the newest normalized list, so a write that
landed during the await is merged rather than clobbered. Every handler
converted, not just the async ones: a delete or reorder during an in-flight
resolve is the same race.

The ref syncs in an effect rather than during render -- the react-compiler rule
forbids touching a ref while rendering, and a gallery resolve lands whole
frames after the commit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../src/features/video/core/settings.test.ts  | 27 +++++++++-
 .../video/ui/VideoReferenceListField.tsx      | 52 +++++++++++--------
 .../src/features/video/ui/VideoWidgetView.tsx | 22 ++++++--
 3 files changed, 76 insertions(+), 25 deletions(-)

diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index 5201bc3e697..cab2901dff3 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import type { VideoSettings } from './types';
+import type { VideoReferenceItem, VideoSettings } from './types';
 
 import { MINIMAX_H3_NUM_FRAMES_CHOICES } from './dimensions';
 import {
@@ -604,6 +604,31 @@ describe('reference-extend linkage', () => {
     });
   });
 
+  it('an updater applied after a concurrent write keeps both changes', () => {
+    // The reference field hands `setReferences` an UPDATER because its add
+    // handlers await a gallery resolve before writing. Modelled here: the
+    // handler captures the list, the Initial Video field places the anchor
+    // during the await, then the resolve lands. A captured-array write would
+    // drop the anchor entirely; an updater over live state keeps both.
+    const captured: VideoReferenceItem[] = [];
+    const add = (current: VideoReferenceItem[]): VideoReferenceItem[] => [...current, IMAGE_REFERENCE];
+
+    // ...the Initial Video lands mid-flight.
+    const live = applyReferenceExtendSourceVideo(captured, source24, 3, FRAMES);
+
+    expect(live.some((entry) => entry.kind === 'video' && entry.fromSourceVideo === true)).toBe(true);
+
+    // ...then the resolve writes, against LIVE state rather than `captured`.
+    const merged = pinReferenceExtendAnchor(add(live));
+
+    expect(merged).toHaveLength(2);
+    expect(merged[0]).toBe(IMAGE_REFERENCE);
+    expect(merged[1]).toMatchObject({ fromSourceVideo: true, kind: 'video' });
+
+    // The snapshot write this replaced would have produced just the image.
+    expect(add(captured)).toEqual([IMAGE_REFERENCE]);
+  });
+
   it('pins the continuity anchor last, whatever the add or drag order', () => {
     // Request order is rotary order: the generated frames continue from the
     // LAST reference block. An image added after the Initial Video would
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
index 5af4792db69..cf5d7815d73 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
@@ -230,7 +230,13 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
   disabled?: boolean;
   maxImages: number;
   maxVideos: number;
-  onChange: (references: VideoReferenceItem[]) => void;
+  /**
+   * Accepts an UPDATER, not a snapshot. The add handlers `await` a gallery
+   * resolve before writing, and the Initial Video field and Frames slider both
+   * write references too -- a captured array would clobber whichever of those
+   * landed during the await.
+   */
+  onChange: (update: (current: VideoReferenceItem[]) => VideoReferenceItem[]) => void;
   references: VideoReferenceItem[];
 }) {
   const { t } = useTranslation();
@@ -289,8 +295,8 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
         const [resolved] = await galleryImages.resolveMany([imageName]);
 
         if (resolved) {
-          onChange([
-            ...references,
+          onChange((current) => [
+            ...current,
             {
               detail: 'max',
               image: { height: resolved.height, image_name: resolved.imageName, width: resolved.width },
@@ -306,7 +312,7 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
         setIsLoading(false);
       }
     },
-    [onChange, references, reportError]
+    [onChange, reportError]
   );
 
   const addVideoReference = useCallback(
@@ -326,8 +332,8 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
             width: item.width,
           });
 
-          onChange([
-            ...references,
+          onChange((current) => [
+            ...current,
             {
               // References are truncated to the generated duration, not joined: default to
               // the whole clip rather than the extend-mode 2-frame-tail trim.
@@ -345,7 +351,7 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
         setIsLoading(false);
       }
     },
-    [onChange, references, reportError]
+    [onChange, reportError]
   );
 
   const handleDragEnd = useCallback(
@@ -425,32 +431,36 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
 
   const updateReference = useCallback(
     (index: number, reference: VideoReferenceItem) => {
-      onChange(references.map((entry, entryIndex) => (entryIndex === index ? reference : entry)));
+      onChange((current) => current.map((entry, entryIndex) => (entryIndex === index ? reference : entry)));
     },
-    [onChange, references]
+    [onChange]
   );
   const removeReference = useCallback(
     (index: number) => {
-      onChange(references.filter((_, entryIndex) => entryIndex !== index));
+      onChange((current) => current.filter((_, entryIndex) => entryIndex !== index));
     },
-    [onChange, references]
+    [onChange]
   );
   const moveReference = useCallback(
     (index: number, direction: -1 | 1) => {
-      const target = index + direction;
+      onChange((current) => {
+        const target = index + direction;
 
-      if (target < 0 || target >= references.length) {
-        return;
-      }
-      const next = [...references];
-      const [entry] = next.splice(index, 1);
+        if (target < 0 || target >= current.length) {
+          return current;
+        }
+        const next = [...current];
+        const [entry] = next.splice(index, 1);
 
-      if (entry) {
+        if (!entry) {
+          return current;
+        }
         next.splice(target, 0, entry);
-        onChange(next);
-      }
+
+        return next;
+      });
     },
-    [onChange, references]
+    [onChange]
   );
 
   return (
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index ba6d790bbe3..4dec56af68a 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -31,7 +31,7 @@ import { Button } from '@platform/ui/Button';
 import { SliderNumberField } from '@platform/ui/SliderNumberField';
 import { toaster } from '@platform/ui/toaster';
 import { ArrowLeftRightIcon, DicesIcon } from 'lucide-react';
-import { useCallback, useId, useMemo } from 'react';
+import { useCallback, useEffect, useId, useMemo, useRef } from 'react';
 import { useTranslation } from 'react-i18next';
 
 import { areVideoValuesEqual } from './videoComparators';
@@ -302,13 +302,29 @@ export const VideoWidgetView = () => {
     },
     [maxVideoReferences, patch, referenceExtend, t, values.numFrames, values.references]
   );
+  // Always the newest normalized list. The reference field's add handlers
+  // `await` a gallery resolve before writing, and the Initial Video field and
+  // the Frames slider write references too — so an updater that resolved
+  // against a captured array would clobber whichever of those landed during
+  // the await, silently deleting the anchor or restoring a window the frame
+  // count had already re-derived.
+  // Synced in an effect rather than during render: this file's react-compiler
+  // rule forbids touching a ref while rendering, and a gallery resolve lands
+  // whole frames later, long after the commit.
+  const referencesRef = useRef(values.references);
+
+  useEffect(() => {
+    referencesRef.current = values.references;
+  }, [values.references]);
+
   // The single choke point for every list edit the reference field makes — add,
   // remove, retrim, reorder — so pinning the continuity anchor here covers all
   // of them. Request order is rotary order and the generation continues from
   // the LAST reference, so the anchor's position is derived, not user-set.
   const setReferences = useCallback(
-    (references: VideoReferenceItem[]) => {
-      const next = referenceExtend ? pinReferenceExtendAnchor(references) : references;
+    (update: (current: VideoReferenceItem[]) => VideoReferenceItem[]) => {
+      const updated = update(referencesRef.current);
+      const next = referenceExtend ? pinReferenceExtendAnchor(updated) : updated;
 
       patch({
         references: next,

From 701709ff104779a47bd940193a4040f1c283e93d Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 08:27:43 -0400
Subject: [PATCH 11/19] fix(webv2): stop the Initial Video cap gate blocking an
 adoptable clip

The gate was `no flagged entry && videoCount >= max`, but the setter refuses
only when `no flagged && no same-name entry && videoCount >= max`. Adopting an
existing reference for the clip consumes no slot, and the gate ignored that
term -- so it disabled the field in a state the setter handles fine.

Metadata recall lands exactly there. `graph.ts` records the references without
`fromSourceVideo` (it is panel state, deliberately not metadata) and records
`source_video` separately, so recalling a reference-extend generation that used
three video references restores three UNFLAGGED videos beside the clip: no
flagged entry, three videos, gate fires.

`disabled` reaches the clip's trim sliders as well as the drop target, so the
cutpoint could not be moved at all on a clip that was legitimately set,
re-dropping the same clip to re-establish the linkage was unreachable, and the
message ("Remove a video reference first") was wrong -- there was room.

Both sides now defer to `canPlaceReferenceExtendAnchor`, and a test drives the
predicate and the setter over the same seven reference states and asserts they
agree, so the gate cannot drift from the behaviour it describes.

The gate stays conservative for a clip not yet dropped: its name is unknowable
before the drop, so the answer is whether a NEW anchor would fit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../src/features/video/core/settings.test.ts  | 33 +++++++++++++++++++
 .../webv2/src/features/video/core/settings.ts | 29 ++++++++++++++++
 .../src/features/video/ui/VideoWidgetView.tsx | 12 ++++---
 3 files changed, 70 insertions(+), 4 deletions(-)

diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index cab2901dff3..e7f6b013a4e 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -6,6 +6,7 @@ import { MINIMAX_H3_NUM_FRAMES_CHOICES } from './dimensions';
 import {
   applyReferenceExtendSourceVideo,
   applyReferenceExtendNumFrames,
+  canPlaceReferenceExtendAnchor,
   pinReferenceExtendAnchor,
   clearDeletedVideoMedia,
   cloneVideoWidgetValues,
@@ -658,6 +659,38 @@ describe('reference-extend linkage', () => {
     expect(adopted[1]).toMatchObject({ fromSourceVideo: true, kind: 'video' });
   });
 
+  it('canPlaceReferenceExtendAnchor agrees with the setter in every state', () => {
+    const video = (name: string, flagged = false) => ({
+      ...VIDEO_REFERENCE,
+      clip: { ...VIDEO_REFERENCE.clip, video_name: name },
+      ...(flagged ? { fromSourceVideo: true } : {}),
+    });
+    const states: VideoReferenceItem[][] = [
+      [],
+      [IMAGE_REFERENCE],
+      [video('a.mp4')],
+      [video('a.mp4'), video('b.mp4')],
+      [video('a.mp4'), video('b.mp4'), video('c.mp4')],
+      // Recall's shape: three unflagged videos, one naming the source clip.
+      [video('long.mp4'), video('b.mp4'), video('c.mp4')],
+      [video('a.mp4'), video('b.mp4'), video('long.mp4', true)],
+    ];
+
+    for (const references of states) {
+      const placed = applyReferenceExtendSourceVideo(references, source24, 3, FRAMES);
+      // The setter signals refusal by returning the input array unchanged.
+      const setterAccepted = placed !== references;
+
+      expect({
+        references: references.map((e) => (e.kind === 'video' ? e.clip.video_name : 'img')),
+        placed: canPlaceReferenceExtendAnchor(references, source24.video_name, 3),
+      }).toEqual({
+        references: references.map((e) => (e.kind === 'video' ? e.clip.video_name : 'img')),
+        placed: setterAccepted,
+      });
+    }
+  });
+
   it('applyReferenceExtendNumFrames leaves unlinked references alone', () => {
     const unlinked = [VIDEO_REFERENCE, IMAGE_REFERENCE];
 
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index de562521d20..86dea91b023 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -524,6 +524,35 @@ export const pinReferenceExtendAnchor = (references: VideoReferenceItem[]): Vide
   return [...references.slice(0, index), ...references.slice(index + 1), pinned];
 };
 
+/**
+ * Whether setting `videoName` as the Initial Video could place its anchor.
+ *
+ * Mirrors `applyReferenceExtendSourceVideo`'s refusal condition so the UI gate
+ * cannot drift from what the setter actually does. An adoptable entry consumes
+ * no slot: the flagged anchor is rewritten in place, and so is an unflagged
+ * reference already naming the same clip -- which is exactly the shape recall
+ * restores, since `fromSourceVideo` is panel state and never reaches metadata.
+ *
+ * `videoName` is the clip currently set; for a clip not yet dropped its name is
+ * unknowable, so the answer is the conservative one -- whether a NEW anchor
+ * would fit.
+ */
+export const canPlaceReferenceExtendAnchor = (
+  references: VideoReferenceItem[],
+  videoName: string | undefined,
+  maxVideos: number
+): boolean => {
+  const videos = references.filter(
+    (entry): entry is Extract<VideoReferenceItem, { kind: 'video' }> => entry.kind === 'video'
+  );
+
+  return (
+    videos.some(
+      (entry) => entry.fromSourceVideo === true || (videoName !== undefined && entry.clip.video_name === videoName)
+    ) || videos.length < maxVideos
+  );
+};
+
 /**
  * Keeps the reference list in step with the Initial Video on a reference-extend
  * panel (pure; the setter and the model-selection transition both use it):
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index 4dec56af68a..56c8a8298de 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -11,6 +11,7 @@ import { getVideoDurationSeconds, invertVideoAspectRatioId } from '@features/vid
 import {
   applyReferenceExtendSourceVideo,
   applyReferenceExtendNumFrames,
+  canPlaceReferenceExtendAnchor,
   pinReferenceExtendAnchor,
   normalizeVideoWidgetValues,
   resolveVideoMode,
@@ -404,12 +405,15 @@ export const VideoWidgetView = () => {
   const supportsReferences = policy.modes.includes('reference');
   const supportsInitialVideo = supportsExtend || referenceExtend;
   // Setting an Initial Video on a reference-extend panel has to place a linked
-  // tail reference, which needs a free video slot. With an anchor already
-  // present the drop only re-derives it in place, so it stays available.
+  // tail reference, which needs a free video slot -- unless an existing entry
+  // can be adopted, which consumes none. Deferring to the same predicate the
+  // setter's refusal uses keeps the two from drifting: gating on the flag alone
+  // disabled the field after a recall, which restores references UNFLAGGED
+  // beside the source video, and `disabled` reaches the clip's trim sliders too
+  // -- so the cutpoint could not be moved on a clip that was legitimately set.
   const initialVideoCapBlocked =
     referenceExtend &&
-    !values.references.some((entry) => entry.kind === 'video' && entry.fromSourceVideo === true) &&
-    values.references.filter((entry) => entry.kind === 'video').length >= maxVideoReferences;
+    !canPlaceReferenceExtendAnchor(values.references, values.sourceVideo?.video_name, maxVideoReferences);
   const hasConditioningMedia = Boolean(values.firstFrameImage || values.lastFrameImage || values.sourceVideo);
   const derivedSourceText = dimensions ? t(`widgets.video.dimensionSource.${dimensions.source}`) : undefined;
   const derivedSizeText = dimensions

From 6a04f56729e28a80be2c68c031ce1f9031a194ca Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 08:35:25 -0400
Subject: [PATCH 12/19] fix(webv2): budget the tail window on short clips, and
 land it on the grid exactly

Two seam losses in the same function.

A clip shorter than the tail window fell through to `Math.max(0, ...)` and the
window became the whole clip -- an arbitrary length, so generally OFF the
17n+5 grid, and `encode_reference_video` snaps DOWN and drops the difference
from the END. No estimate error needed: at 24 fps a 120-frame clip with
numFrames 345 kept 107 of its 119 frames and stopped half a second short of the
cutpoint. It was the common case for any source under ~5.9s at 24 fps, and the
grid test could not see it because it only ran a 402-frame clip. The clamped
branch now falls back to the largest ON-GRID budget the clip does support, so
the same frames land ON the seam instead of before it.

And `ceil(budget * fps / 24)` was never exact. The resample is a step function,
so rounding up overshoots by a frame or two, and the overshoot is discarded at
the seam. Walking down to the smallest source count that still reaches the
budget hits it exactly wherever the source's frame boundaries allow, and within
one frame where they cannot (12 fps cannot reach an odd 141 at all). Over 15
rates x all 16 frame choices the total seam offset halves, 72 frames to 36,
with no budget lost either way.

The grid test now sweeps short clips across 6 rates x 7 clip lengths x 4 frame
counts, asserting at most one frame is trimmed and the window still ends on the
cutpoint.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../src/features/video/core/settings.test.ts  | 41 +++++++++++++++-
 .../webv2/src/features/video/core/settings.ts | 49 +++++++++++++++++--
 2 files changed, 83 insertions(+), 7 deletions(-)

diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index e7f6b013a4e..a0fe1b558a3 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -449,10 +449,12 @@ describe('reference-extend linkage', () => {
 
   it('derives the tail trim: the window ending at the cutpoint, clamped at 0', () => {
     expect(deriveReferenceExtendClip(source24, FRAMES)).toMatchObject({ endFrame: 400, startFrame: 260 });
-    // Shorter than the tail window: sample from the clip's own start.
+    // Shorter than the tail window: fall back to the largest ON-GRID budget the
+    // clip supports (80 frames -> 73) so the window still ENDS on the cutpoint.
+    // Starting at 0 kept the same 73 frames but stopped 7 short of the seam.
     expect(deriveReferenceExtendClip({ ...SOURCE_VIDEO, fps: 24 }, FRAMES)).toMatchObject({
       endFrame: 79,
-      startFrame: 0,
+      startFrame: 7,
     });
   });
 
@@ -486,6 +488,41 @@ describe('reference-extend linkage', () => {
     }
   });
 
+  it('a clip SHORTER than the window still ends its tail on the cutpoint', () => {
+    // The clamped branch used to take the whole clip, whose length is
+    // arbitrary: off the 17n+5 grid, so the snap-down cut the difference from
+    // the END. Nothing about it needs an inexact estimate — it was the common
+    // case for any source under ~5.9s at 24 fps, and the sweep above could not
+    // see it because it only runs a 402-frame clip.
+    const resample = (n: number, fps: number) => Math.floor((n * 24) / fps + 0.5);
+    const snapDown = (n: number) => Math.max(1, Math.floor((n - 5) / 17)) * 17 + 5;
+
+    for (const fps of [12, 16, 23.976, 24, 25, 30]) {
+      for (const total of [40, 60, 80, 100, 120, 141, 200]) {
+        for (const numFrames of [90, 124, 141, 345]) {
+          const source = { ...longSource, endFrame: total - 1, fps, numFrames: total };
+          const clip = deriveReferenceExtendClip(source, numFrames);
+          const window = clip.endFrame - clip.startFrame + 1;
+          const kept = snapDown(Math.min(resample(window, fps), numFrames));
+
+          const discarded = Math.min(resample(window, fps), numFrames) - kept;
+
+          // At most a single frame is trimmed off the seam end -- the source's
+          // own frame boundaries sometimes cannot land on the grid exactly (12
+          // fps cannot reach an odd 141 at all). The old clamp shed up to 16.
+          expect({ discarded: discarded <= 1, fps, numFrames, total }).toEqual({
+            discarded: true,
+            fps,
+            numFrames,
+            total,
+          });
+          // And the window always still ends where it was asked to.
+          expect(clip.endFrame).toBe(source.endFrame);
+        }
+      }
+    }
+  });
+
   it('converts the window into the source clip fps', () => {
     // 141 frames of 24 fps material is 94 frames of a 16 fps clip — the same
     // 5.875s of wall time, which is what the tail window actually means.
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index 86dea91b023..e2dbab72b86 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -444,19 +444,58 @@ export const deriveReferenceExtendClip = (sourceVideo: VideoSourceClip, numFrame
   startFrame: referenceExtendStartFrame(sourceVideo, numFrames),
 });
 
+/** `snap_reference_num_frames`: down to the `17n + 5` grid the video VAE encodes whole. */
+const snapReferenceFrames = (frames: number): number => Math.max(1, Math.floor((frames - 5) / 17)) * 17 + 5;
+
+/** Source frames -> frames after the backend's 24 fps resample (ffmpeg's fps-filter count). */
+const resampledFrameCount = (sourceFrames: number, fps: number): number =>
+  Math.floor((sourceFrames * MINIMAX_H3_FPS) / fps + 0.5);
+
 /** The tail window's start index — see `deriveReferenceExtendClip`. */
 const referenceExtendStartFrame = (clip: VideoSourceClip, numFrames: number): number => {
-  const budget = Number.isFinite(numFrames)
-    ? Math.min(VIDEO_REFERENCE_EXTEND_TAIL_FRAMES, Math.trunc(numFrames))
-    : VIDEO_REFERENCE_EXTEND_TAIL_FRAMES;
   // A clip whose probe recorded no usable rate: the backend resamples at the
   // rate it probes, so 24 — a no-op conversion — is the only safe assumption.
   // A zero or negative rate would otherwise collapse the window to the 2-frame
   // floor, which is below the 13 frames text conditioning needs.
   const fps = Number.isFinite(clip.fps) && clip.fps > 0 ? clip.fps : MINIMAX_H3_FPS;
-  const tail = Math.max(MIN_VIDEO_TRIM_FRAMES, Math.ceil((budget * fps) / MINIMAX_H3_FPS));
+  const requested = Number.isFinite(numFrames)
+    ? Math.min(VIDEO_REFERENCE_EXTEND_TAIL_FRAMES, Math.trunc(numFrames))
+    : VIDEO_REFERENCE_EXTEND_TAIL_FRAMES;
+  // A clip shorter than the window cannot supply the whole budget, and simply
+  // taking what is there leaves the window OFF the 17n+5 grid — so the
+  // snap-down cuts the difference from the END, the frames at the cutpoint.
+  // (24 fps, a 120-frame clip, numFrames 345: a [0,118] window keeps 107 of
+  // its 119 frames and stops half a second short of the seam.) Falling back to
+  // the largest on-grid budget the clip DOES support keeps the same frames and
+  // lands them on the seam. Both bounds are already on the grid in the normal
+  // case, so this is an identity there.
+  const budget = Math.min(
+    requested,
+    snapReferenceFrames(Math.min(resampledFrameCount(clip.endFrame + 1, fps), requested))
+  );
+
+  return Math.max(0, clip.endFrame - (tailSourceFrames(budget, fps) - 1));
+};
+
+/**
+ * The fewest source frames that still resample to at least `budget` frames.
+ *
+ * `ceil(budget * fps / 24)` is the closed form and it is not exact: the
+ * resample is a step function, so the rounded-up count can overshoot the
+ * budget by a frame or two, and every overshot frame is discarded from the END
+ * — the seam. Walking back down to the smallest count that still reaches the
+ * budget lands on it exactly wherever the source's frame boundaries allow, and
+ * within a frame where they do not (12 fps cannot hit an odd 141 at all). The
+ * loop runs `24 / fps` times at most.
+ */
+const tailSourceFrames = (budget: number, fps: number): number => {
+  let tail = Math.max(MIN_VIDEO_TRIM_FRAMES, Math.ceil((budget * fps) / MINIMAX_H3_FPS));
+
+  while (tail > MIN_VIDEO_TRIM_FRAMES && resampledFrameCount(tail - 1, fps) >= budget) {
+    tail -= 1;
+  }
 
-  return Math.max(0, clip.endFrame - (tail - 1));
+  return tail;
 };
 
 /**

From a32181461f3b5d1bb321f42e08f619c7c82e00c7 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 08:49:33 -0400
Subject: [PATCH 13/19] fix(webv2): disable reorder arrows the anchor pin would
 undo, and stabilise setNumFrames

Two leftovers from the review.

The continuity anchor is pinned last, so the arrows that would displace it fired
a patch and got the list straight back: the anchor's own up arrow, and the down
arrow of the card above it. Both looked enabled and did nothing (worse, the
patch remounted the list, since the keys embed the index). The card now takes
`canMoveUp` / `canMoveDown` instead of `isFirst` / `isLast`, and the list
excludes the moves the pin reverts.

`setNumFrames` listed `values.references` as a dependency, which is a fresh
array on every render, so the callback identity churned and the Frames slider
re-rendered on every patch anywhere in the panel -- against this file's stated
"every prop identity is stable by construction" contract. It now reads the list
through the ref added for the functional-update fix, which is safe precisely
because the re-derive is idempotent in `numFrames`.

The ref moves above both consumers: declared after them, react-compiler flagged
the effect's assignment as modifying a value already passed to a hook.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../video/ui/VideoReferenceListField.tsx      | 22 +++++++----
 .../src/features/video/ui/VideoWidgetView.tsx | 39 +++++++++++--------
 2 files changed, 36 insertions(+), 25 deletions(-)

diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
index cf5d7815d73..cbf6de925e5 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
@@ -67,8 +67,8 @@ const ReferenceCard = memo(function ReferenceCard({
   collections,
   disabled,
   index,
-  isFirst,
-  isLast,
+  canMoveDown,
+  canMoveUp,
   onMove,
   onRemove,
   onUpdate,
@@ -77,8 +77,8 @@ const ReferenceCard = memo(function ReferenceCard({
   collections: ReferenceCollections;
   disabled: boolean;
   index: number;
-  isFirst: boolean;
-  isLast: boolean;
+  canMoveDown: boolean;
+  canMoveUp: boolean;
   onMove: (index: number, direction: -1 | 1) => void;
   onRemove: (index: number) => void;
   onUpdate: (index: number, reference: VideoReferenceItem) => void;
@@ -189,7 +189,7 @@ const ReferenceCard = memo(function ReferenceCard({
         <Stack gap="0">
           <IconButton
             aria-label={t('widgets.video.moveReferenceUp')}
-            disabled={disabled || isFirst}
+            disabled={disabled || !canMoveUp}
             size="2xs"
             variant="ghost"
             onClick={handleMoveUp}
@@ -198,7 +198,7 @@ const ReferenceCard = memo(function ReferenceCard({
           </IconButton>
           <IconButton
             aria-label={t('widgets.video.moveReferenceDown')}
-            disabled={disabled || isLast}
+            disabled={disabled || !canMoveDown}
             size="2xs"
             variant="ghost"
             onClick={handleMoveDown}
@@ -246,6 +246,12 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
   const [isLoading, setIsLoading] = useState(false);
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
 
+  // The continuity anchor is pinned last, so any move that would displace it is
+  // reverted the moment it is written -- the button fired a patch and the list
+  // came back unchanged. Present those as disabled rather than inert.
+  const anchorIndex = references.findIndex(
+    (reference) => reference.kind === 'video' && reference.fromSourceVideo === true
+  );
   const videoCount = references.filter((reference) => reference.kind === 'video').length;
   const imageCount = references.length - videoCount;
   const canAddVideo = videoCount < maxVideos;
@@ -471,8 +477,8 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
           collections={collections}
           disabled={isInert}
           index={index}
-          isFirst={index === 0}
-          isLast={index === references.length - 1}
+          canMoveDown={index < references.length - 1 && index + 1 !== anchorIndex}
+          canMoveUp={index > 0 && index !== anchorIndex}
           reference={reference}
           onMove={moveReference}
           onRemove={removeReference}
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index 56c8a8298de..e9342de4100 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -151,6 +151,22 @@ export const VideoWidgetView = () => {
   );
 
   const patch = useCallback((next: Partial<VideoWidgetValues>) => patchValues(next), [patchValues]);
+
+  // Always the newest normalized list. The reference field's add handlers
+  // `await` a gallery resolve before writing, and the Initial Video field and
+  // the Frames slider write references too — so an updater that resolved
+  // against a captured array would clobber whichever of those landed during
+  // the await, silently deleting the anchor or restoring a window the frame
+  // count had already re-derived.
+  // Synced in an effect rather than during render: this file's react-compiler
+  // rule forbids touching a ref while rendering, and a gallery resolve lands
+  // whole frames later, long after the commit.
+  const referencesRef = useRef(values.references);
+
+  useEffect(() => {
+    referencesRef.current = values.references;
+  }, [values.references]);
+
   // Chakra's `Field.Root` hands its single `ids.control` to EVERY control
   // inside it, and this Field holds three. Without an id of its own the
   // switch's hidden input collides with the seed NumberInput, so the
@@ -271,10 +287,14 @@ export const VideoWidgetView = () => {
     (numFrames: number) =>
       patch(
         referenceExtend
-          ? { numFrames, references: applyReferenceExtendNumFrames(values.references, numFrames) }
+          ? { numFrames, references: applyReferenceExtendNumFrames(referencesRef.current, numFrames) }
           : { numFrames }
       ),
-    [patch, referenceExtend, values.references]
+    // Reads the list through the ref so the Frames control keeps a stable
+    // prop identity: depending on `values.references` re-created this on every
+    // panel patch, re-rendering the slider against the file's stable-identity
+    // contract. Safe because the re-derive is idempotent in `numFrames`.
+    [patch, referenceExtend]
   );
   const setSourceVideo = useCallback(
     (sourceVideo: VideoSourceClip | null) => {
@@ -303,21 +323,6 @@ export const VideoWidgetView = () => {
     },
     [maxVideoReferences, patch, referenceExtend, t, values.numFrames, values.references]
   );
-  // Always the newest normalized list. The reference field's add handlers
-  // `await` a gallery resolve before writing, and the Initial Video field and
-  // the Frames slider write references too — so an updater that resolved
-  // against a captured array would clobber whichever of those landed during
-  // the await, silently deleting the anchor or restoring a window the frame
-  // count had already re-derived.
-  // Synced in an effect rather than during render: this file's react-compiler
-  // rule forbids touching a ref while rendering, and a gallery resolve lands
-  // whole frames later, long after the commit.
-  const referencesRef = useRef(values.references);
-
-  useEffect(() => {
-    referencesRef.current = values.references;
-  }, [values.references]);
-
   // The single choke point for every list edit the reference field makes — add,
   // remove, retrim, reorder — so pinning the continuity anchor here covers all
   // of them. Request order is rotary order and the generation continues from

From 9fcd0233181e29be4fec4b5ca6dda83c58eb9b82 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 09:46:46 -0400
Subject: [PATCH 14/19] fix(webv2): scope the reference ref to its project,
 derive the anchor flag on load

Two identities that did not survive a boundary.

The latest-references ref crossed PROJECTS. The video widget is reconciled,
never remounted, across a project switch (the <Activity> key is the panel
instance, not the project), while `patch` stays bound to the project its render
belonged to. So the bare ref tracked whichever project was ACTIVE: drop a video
into project A's references, switch to B before the gallery resolve lands, and
the captured updater ran against B's list with A's patch -- replacing A's
reference list with B's entries plus the new one, invisibly until the user
switched back. The snapshot array this branch removed was at least
per-project-correct. The ref now carries `{ projectId, references }` and a
write whose project has moved on is dropped: losing one pending add because
the user switched projects mid-resolve beats overwriting a list they can see.

The anchor flag did not survive RECALL. `fromSourceVideo` is panel state and
never reaches metadata, so a recalled reference-extend panel arrives with its
anchor unflagged beside the source video -- and every invariant this branch
built keys on the flag. The pin skipped it (the model continued from whatever
reference followed), the frame-count re-budget skipped it (Frames 345 -> 90
left a 141-frame window and the backend cut 2.125s off the seam, the exact
failure this branch exists to prevent), and the seam-anchored start index fell
back to the absolute form. The cap-gate commit even taught its predicate to
tolerate the unflagged shape without noticing the other three invariants do
not.

The flag is derivable, not just storable: the video reference naming the
Initial Video's clip IS the anchor, the same identity the setter adopts by.
`sanitizeVideoReferences` now re-derives it -- before the pin, which is before
the cap trim, so a freshly flagged anchor is also immediately last and
protected from overflow. An already-flagged entry stays authoritative.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../src/features/video/core/settings.test.ts  | 44 +++++++++++++++++++
 .../webv2/src/features/video/core/settings.ts | 33 ++++++++++++--
 .../src/features/video/ui/VideoWidgetView.tsx | 33 ++++++++++----
 3 files changed, 98 insertions(+), 12 deletions(-)

diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index a0fe1b558a3..351780f91ee 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -573,6 +573,50 @@ describe('reference-extend linkage', () => {
     expect(applyReferenceExtendSourceVideo(unlinked, null, 3, FRAMES)).toBe(unlinked);
   });
 
+  it('normalization re-establishes the linkage recall drops, and the invariants reach it', () => {
+    // `fromSourceVideo` never reaches metadata, so a recalled reference-extend
+    // panel arrives with its anchor UNFLAGGED beside the source video. Every
+    // invariant keys on the flag, so before this: not pinned (the model
+    // continued from whatever followed it), and not re-budgeted (a Frames
+    // change left the window overrunning -- 2s cut off the seam at 345 -> 90).
+    const recalled = { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'long.mp4' } };
+    const normalized = normalizeVideoSettings(
+      createSettings({ references: [recalled, IMAGE_REFERENCE], sourceVideo: source24 })
+    );
+
+    // Flagged by clip identity -- the same rule the setter adopts by -- and pinned.
+    expect(normalized?.references).toHaveLength(2);
+    expect(normalized?.references[0]).toBe(IMAGE_REFERENCE);
+    expect(normalized?.references[1]).toMatchObject({
+      clip: { video_name: 'long.mp4' },
+      fromSourceVideo: true,
+    });
+
+    // The frame-count re-budget now reaches the recalled window.
+    const rebudgeted = applyReferenceExtendNumFrames(normalized!.references, 90);
+
+    expect(rebudgeted[1]).toMatchObject({ clip: { endFrame: 47, startFrame: 9 } });
+
+    // A flagged entry stays authoritative: an unflagged same-name entry beside
+    // it is NOT a second anchor.
+    const flaggedElsewhere = normalizeVideoSettings(
+      createSettings({
+        references: [recalled, { ...VIDEO_REFERENCE, fromSourceVideo: true }],
+        sourceVideo: source24,
+      })
+    );
+
+    expect(
+      flaggedElsewhere?.references.filter((entry) => entry.kind === 'video' && entry.fromSourceVideo === true)
+    ).toHaveLength(1);
+    expect(flaggedElsewhere?.references[1]).toMatchObject({ clip: { video_name: 'ref.mp4' }, fromSourceVideo: true });
+
+    // No source video: nothing to link, nothing flagged.
+    const unlinked = normalizeVideoSettings(createSettings({ references: [recalled] }));
+
+    expect(unlinked?.references[0]).not.toHaveProperty('fromSourceVideo');
+  });
+
   it('adopts an unflagged reference for the same clip instead of duplicating it (recall shape)', () => {
     const recalled = { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'long.mp4' } };
     const result = applyReferenceExtendSourceVideo([IMAGE_REFERENCE, recalled], source24, 3, FRAMES);
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index e2dbab72b86..5742977d4f7 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -114,17 +114,41 @@ export const isVideoReferenceItem = (value: unknown): value is VideoReferenceIte
  * from the tail would discard exactly the entry the extension depends on.
  * Images carry no ordering role and keep the front.
  */
-const sanitizeVideoReferences = (value: unknown): VideoReferenceItem[] => {
+const sanitizeVideoReferences = (value: unknown, sourceVideoName?: string): VideoReferenceItem[] => {
   if (!Array.isArray(value)) {
     return [];
   }
+  let valid = value.filter((entry) => isVideoReferenceItem(entry));
+
+  // Re-establish the linkage recall drops. `fromSourceVideo` is panel state
+  // and never reaches metadata, so a recalled panel arrives with its anchor
+  // UNFLAGGED beside the source video -- and every invariant keyed on the flag
+  // (the pin, the frame-count re-budget, the seam-anchored start index)
+  // silently lapses: a Frames change left the recalled window unbudgeted and
+  // the backend cut 2s off the seam. The flag is derivable, not just
+  // storable: the video reference naming the Initial Video's clip IS the
+  // anchor, the same identity `applyReferenceExtendSourceVideo` adopts by.
+  // An already-flagged entry stays authoritative.
+  if (
+    sourceVideoName !== undefined &&
+    !valid.some((entry) => entry.kind === 'video' && entry.fromSourceVideo === true)
+  ) {
+    const adopt = valid.findIndex((entry) => entry.kind === 'video' && entry.clip.video_name === sourceVideoName);
+
+    if (adopt >= 0) {
+      valid = valid.map((entry, index) =>
+        index === adopt && entry.kind === 'video' ? { ...entry, fromSourceVideo: true } : entry
+      );
+    }
+  }
+
   // Pin BEFORE the cap trim. The front-drop below assumes the anchor is last,
   // but a project saved by the build that PREPENDED it loads with the anchor
   // first -- so without this the overflow rule deletes the one entry it exists
   // to protect. Pinning here also heals those panels on load: normalization
   // runs on every read, whereas `setReferences` only fires once the user
   // touches the reference list.
-  const valid = pinReferenceExtendAnchor(value.filter((entry) => isVideoReferenceItem(entry)));
+  valid = pinReferenceExtendAnchor(valid);
   let videosToDrop = Math.max(0, valid.filter((entry) => entry.kind === 'video').length - VIDEO_REFERENCE_MAX_VIDEOS);
   const result: VideoReferenceItem[] = [];
   let images = 0;
@@ -221,7 +245,10 @@ export const normalizeVideoSettings = (values: unknown): VideoSettings | null =>
   // record somehow holds both, the references win deterministically. A source
   // video COEXISTS with references (Ref2VA reference-extend) — validation
   // rejects the pair on models that cannot consume it.
-  const references = sanitizeVideoReferences(values.references);
+  const references = sanitizeVideoReferences(
+    values.references,
+    isVideoSourceClip(values.sourceVideo) ? values.sourceVideo.video_name : undefined
+  );
   const hasReferences = references.length > 0;
   const firstFrameImage = !hasReferences && isImageWithDims(values.firstFrameImage) ? values.firstFrameImage : null;
   // A first frame and a source video are mutually exclusive; if a stale
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index e9342de4100..ea6ce8828b5 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -161,11 +161,17 @@ export const VideoWidgetView = () => {
   // Synced in an effect rather than during render: this file's react-compiler
   // rule forbids touching a ref while rendering, and a gallery resolve lands
   // whole frames later, long after the commit.
-  const referencesRef = useRef(values.references);
+  // Keyed by PROJECT, not just latest: the widget is reconciled, never
+  // remounted, across a project switch (the <Activity> key is the panel
+  // instance), while `patch` stays bound to the project its render belonged
+  // to. A bare latest-list ref therefore tracks whichever project is ACTIVE —
+  // and a gallery resolve landing after a switch would write the new project's
+  // reference list into the old project, wholesale.
+  const referencesRef = useRef({ projectId, references: values.references });
 
   useEffect(() => {
-    referencesRef.current = values.references;
-  }, [values.references]);
+    referencesRef.current = { projectId, references: values.references };
+  }, [projectId, values.references]);
 
   // Chakra's `Field.Root` hands its single `ids.control` to EVERY control
   // inside it, and this Field holds three. Without an id of its own the
@@ -286,15 +292,17 @@ export const VideoWidgetView = () => {
   const setNumFrames = useCallback(
     (numFrames: number) =>
       patch(
-        referenceExtend
-          ? { numFrames, references: applyReferenceExtendNumFrames(referencesRef.current, numFrames) }
+        referenceExtend && referencesRef.current.projectId === projectId
+          ? { numFrames, references: applyReferenceExtendNumFrames(referencesRef.current.references, numFrames) }
           : { numFrames }
       ),
     // Reads the list through the ref so the Frames control keeps a stable
     // prop identity: depending on `values.references` re-created this on every
     // panel patch, re-rendering the slider against the file's stable-identity
-    // contract. Safe because the re-derive is idempotent in `numFrames`.
-    [patch, referenceExtend]
+    // contract. Safe because the re-derive is idempotent in `numFrames`. The
+    // project guard is unreachable for this synchronous caller; it keeps the
+    // ref's contract uniform.
+    [patch, projectId, referenceExtend]
   );
   const setSourceVideo = useCallback(
     (sourceVideo: VideoSourceClip | null) => {
@@ -329,7 +337,14 @@ export const VideoWidgetView = () => {
   // the LAST reference, so the anchor's position is derived, not user-set.
   const setReferences = useCallback(
     (update: (current: VideoReferenceItem[]) => VideoReferenceItem[]) => {
-      const updated = update(referencesRef.current);
+      // A pending edit whose project has moved on is DROPPED: this callback's
+      // `patch` still targets the project it rendered for, but that project's
+      // current list is gone from the ref. Losing one add because the user
+      // switched projects mid-resolve beats overwriting a list they can see.
+      if (referencesRef.current.projectId !== projectId) {
+        return;
+      }
+      const updated = update(referencesRef.current.references);
       const next = referenceExtend ? pinReferenceExtendAnchor(updated) : updated;
 
       patch({
@@ -339,7 +354,7 @@ export const VideoWidgetView = () => {
           : {}),
       });
     },
-    [patch, referenceExtend]
+    [patch, projectId, referenceExtend]
   );
   const clearReferences = useCallback(() => patch({ references: [] }), [patch]);
   const setLoras = useCallback(

From 6ec6c9e6ed20da7fec68cbe0dee958ffb0b8e4cf Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 10:03:23 -0400
Subject: [PATCH 15/19] fix(webv2): refuse an Initial Video drop the anchor
 cannot follow, and say why

`setSourceVideo` detected the refusal -- `applyReferenceExtendSourceVideo`
returning its input untouched -- toasted about it, and then patched the clip in
anyway. That left the panel in the worst available state: an Initial Video set
with NO continuity anchor, generating an extension with nothing sampling the
clip, and the cap gate then closing over it so the trim sliders froze. The cap
gate cannot pre-empt this: it can only ask about the clip currently set, and
the refused drop is by definition a different clip. The drop is now refused
whole -- no partial application -- and the toast says what actually happened
("Initial video not set") instead of describing a reference that was never
created. Clearing is unaffected: removing the linked entry cannot overflow
anything.

And when the gate does close with a clip already set (reachable by deleting the
anchor card and filling the slots), the only symptom was frozen trim sliders:
`disabledReason` rendered exclusively in the empty-state slot, which a set clip
replaces with its preview. The trim block now shows the same reason.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 invokeai/frontend/webv2/public/locales/en.json        |  4 ++--
 .../src/features/video/ui/VideoSourceClipField.tsx    |  7 +++++++
 .../webv2/src/features/video/ui/VideoWidgetView.tsx   | 11 +++++++++--
 3 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/invokeai/frontend/webv2/public/locales/en.json b/invokeai/frontend/webv2/public/locales/en.json
index 6df1b51204d..640aa2bc8fd 100644
--- a/invokeai/frontend/webv2/public/locales/en.json
+++ b/invokeai/frontend/webv2/public/locales/en.json
@@ -3164,8 +3164,8 @@
       "referenceConditioningVideoAudio": "Video + audio",
       "referenceDetailMatch": "Match generation size",
       "referenceDetailMax": "Max detail (2048px, slower)",
-      "referenceExtendCapFull": "No continuity reference added",
-      "referenceExtendCapFullDescription": "All 3 video reference slots are in use, so the extension has no reference sampling the initial video. Remove a video reference to add one.",
+      "referenceExtendCapFull": "Initial video not set",
+      "referenceExtendCapFullDescription": "All 3 video reference slots are in use, so there is no room for the continuity reference this clip needs. Remove a video reference, then drop the clip again.",
       "referenceExtendHelp": "The generated video is appended to this clip at its End Frame. A linked video reference samples up to the last ~5 seconds before that cutpoint for continuity — never more than the generated clip's own length, since the model discards the overrun at the seam. Its trim re-derives whenever the cutpoints or the frame count change.",
       "referenceFromInitialVideo": "Initial video",
       "references": "References",
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoSourceClipField.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoSourceClipField.tsx
index 3fa82942610..7c58f9c915a 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoSourceClipField.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoSourceClipField.tsx
@@ -377,6 +377,13 @@ export const VideoSourceClipField = memo(
         ) : null}
         {sourceVideo ? (
           <Stack gap="2">
+            {/* The empty-state slot shows the reason when no clip is set; with
+                one set, the frozen trim sliders were the only symptom. */}
+            {disabled && disabledReason ? (
+              <Text color="fg.muted" fontSize="2xs" textWrap="pretty">
+                {disabledReason}
+              </Text>
+            ) : null}
             <Field helpText={t('widgets.video.trimHelp')} label={t('widgets.video.trimStart')}>
               <SliderNumberField
                 ariaLabel={t('widgets.video.trimStart')}
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index ea6ce8828b5..3685fc75a55 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -315,14 +315,21 @@ export const VideoWidgetView = () => {
         );
 
         // Unchanged identity with a clip set means the video cap is full and
-        // no same-clip entry could be adopted: the extension would run with
-        // no continuity anchor at all, which deserves more than silence.
+        // no same-clip entry could be adopted. REFUSE the whole drop: patching
+        // the clip anyway produced an extension with no continuity anchor at
+        // all, behind nothing but a toast -- and the cap gate then froze the
+        // clip's trim sliders. (The gate cannot pre-empt this case: it can
+        // only ask about the clip currently set, and this drop is a different
+        // one.) Clearing is never refused -- removing the linked entry cannot
+        // overflow anything.
         if (sourceVideo && references === values.references) {
           toaster.create({
             description: t('widgets.video.referenceExtendCapFullDescription'),
             title: t('widgets.video.referenceExtendCapFull'),
             type: 'warning',
           });
+
+          return;
         }
         patch({ references, sourceVideo, ...(sourceVideo ? { firstFrameImage: null } : {}) });
         return;

From 7deea6afcb9543d34287e9f718f944109c25babf Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 10:40:32 -0400
Subject: [PATCH 16/19] fix(webv2): re-check reference caps at apply time,
 overflow drops the newest

The render-time cap gates (`canAddVideo` / `canAddImage`) are evaluated before
the add handlers' await, and the Initial Video field is an independent writer
that can fill the slots during it. The over-cap write then reached
normalization, whose front-drop overflow deleted the user's OLDEST reference --
where the pre-branch keep-first rule had at least deleted the surplus add.
So a race turned into silent loss of the user's earliest work.

Two layers:

- The add updaters re-check the cap against the LIVE list at apply time. A
  declined add surfaces through the field's existing error line ("All 3 video
  reference slots filled while this one was loading, so it was not added")
  rather than vanishing. The updater form makes this exact: it runs against
  the same list the write would land on.
- Sanitization's overflow now drops the NEWEST non-anchor videos instead of
  the front. The surplus in any over-cap record is whatever arrived last; the
  anchor stays exempt wherever it sits, which was the one thing the front-drop
  got right. This also restores the pre-branch behaviour for anchor-less
  lists, which the front-drop had changed for no reason the rationale covered.

The race shape is pinned in a test: [B, C, anchor, D-raced-in] normalizes to
[B, C, anchor] -- the racing add is the casualty, not B.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../frontend/webv2/public/locales/en.json     |  2 +
 .../src/features/video/core/settings.test.ts  | 45 +++++++++---
 .../webv2/src/features/video/core/settings.ts | 32 +++++---
 .../video/ui/VideoReferenceListField.tsx      | 73 ++++++++++++++-----
 4 files changed, 110 insertions(+), 42 deletions(-)

diff --git a/invokeai/frontend/webv2/public/locales/en.json b/invokeai/frontend/webv2/public/locales/en.json
index 640aa2bc8fd..35fa8bebfaf 100644
--- a/invokeai/frontend/webv2/public/locales/en.json
+++ b/invokeai/frontend/webv2/public/locales/en.json
@@ -3167,6 +3167,8 @@
       "referenceExtendCapFull": "Initial video not set",
       "referenceExtendCapFullDescription": "All 3 video reference slots are in use, so there is no room for the continuity reference this clip needs. Remove a video reference, then drop the clip again.",
       "referenceExtendHelp": "The generated video is appended to this clip at its End Frame. A linked video reference samples up to the last ~5 seconds before that cutpoint for continuity — never more than the generated clip's own length, since the model discards the overrun at the seam. Its trim re-derives whenever the cutpoints or the frame count change.",
+      "referenceImageCapRace": "All {{max}} image reference slots filled while this one was loading, so it was not added.",
+      "referenceVideoCapRace": "All {{max}} video reference slots filled while this one was loading, so it was not added.",
       "referenceFromInitialVideo": "Initial video",
       "references": "References",
       "referencesHelp": "Up to 3 videos and 9 images condition the generation, in order — reordering references changes the result. A video reference can contribute its image track, its soundtrack, or both.",
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index 351780f91ee..4606edc1905 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -338,7 +338,8 @@ describe('references', () => {
   });
 
   it('normalization drops malformed entries and enforces the caps, preserving order', () => {
-    // Videos over the cap overflow from the FRONT — see the over-cap test below.
+    // Videos over the cap drop the NEWEST non-anchor entries — the surplus is
+    // whatever arrived last. See the over-cap tests below.
     const tooMany = [
       ...Array.from({ length: 4 }, (_, index) => ({
         ...VIDEO_REFERENCE,
@@ -350,16 +351,16 @@ describe('references', () => {
     const normalized = normalizeVideoSettings(createSettings({ references: tooMany as never }));
 
     expect(normalized?.references.map((entry) => (entry.kind === 'video' ? entry.clip.video_name : 'img'))).toEqual([
+      'v0.mp4',
       'v1.mp4',
       'v2.mp4',
-      'v3.mp4',
       'img',
     ]);
   });
 
-  it('an over-cap video list overflows from the front, keeping the continuity anchor', () => {
-    // The anchor is last, so dropping from the tail would discard exactly the
-    // entry the extension depends on. Reachable only from a stale record.
+  it('over-cap overflow drops the newest videos but never the anchor', () => {
+    const named = (entry: { kind: string; clip?: { video_name: string } }) =>
+      entry.kind === 'video' ? entry.clip!.video_name : 'img';
     const tooMany = [
       IMAGE_REFERENCE,
       ...Array.from({ length: 5 }, (_unused, index) => ({
@@ -369,12 +370,32 @@ describe('references', () => {
     ];
     const normalized = normalizeVideoSettings(createSettings({ references: tooMany as never }));
 
-    expect(normalized?.references.map((entry) => (entry.kind === 'video' ? entry.clip.video_name : 'img'))).toEqual([
-      'img',
-      'v2.mp4',
-      'v3.mp4',
-      'v4.mp4',
-    ]);
+    expect(normalized?.references.map(named as never)).toEqual(['img', 'v0.mp4', 'v1.mp4', 'v2.mp4']);
+
+    // The race shape: an add slipped past the render-time cap gate while the
+    // Initial Video was placing its anchor. The surplus is the racing add (D),
+    // not the user's oldest reference (B) — a plain front-drop deleted B.
+    const anchor = {
+      ...VIDEO_REFERENCE,
+      clip: { ...VIDEO_REFERENCE.clip, video_name: 'anchor.mp4' },
+      fromSourceVideo: true,
+    };
+    const raced = ['b.mp4', 'c.mp4'].map((video_name) => ({
+      ...VIDEO_REFERENCE,
+      clip: { ...VIDEO_REFERENCE.clip, video_name },
+    }));
+    const healed = normalizeVideoSettings(
+      createSettings({
+        references: [
+          ...raced,
+          anchor,
+          { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'd.mp4' } },
+        ] as never,
+      })
+    );
+
+    expect(healed?.references.map(named as never)).toEqual(['b.mp4', 'c.mp4', 'anchor.mp4']);
+    expect(healed?.references.at(-1)).toMatchObject({ fromSourceVideo: true });
   });
 
   it('normalization heals a panel saved with the anchor prepended', () => {
@@ -404,7 +425,7 @@ describe('references', () => {
     ];
     const trimmed = normalizeVideoSettings(createSettings({ references: stale as never }));
 
-    expect(trimmed?.references.map(named as never)).toEqual(['v1.mp4', 'v2.mp4', 'anchor.mp4']);
+    expect(trimmed?.references.map(named as never)).toEqual(['v0.mp4', 'v1.mp4', 'anchor.mp4']);
     expect(trimmed?.references.at(-1)).toMatchObject({ fromSourceVideo: true });
   });
 
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index 5742977d4f7..acec796f571 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -104,15 +104,17 @@ export const isVideoReferenceItem = (value: unknown): value is VideoReferenceIte
 /**
  * Drops invalid entries and enforces the per-kind caps, preserving order.
  *
- * An over-cap list should never reach here — both add paths are gated on the
- * cap and the Initial Video field disables itself when the video slots are
- * full — so this is the guard for a stale or hand-edited project record.
+ * An over-cap list should never reach here — the add paths re-check the cap
+ * against the live list at apply time and the Initial Video field disables
+ * itself when the video slots are full — so this is the guard for a stale or
+ * hand-edited project record.
  *
- * Videos overflow from the FRONT. Request order is rotary order and the
- * generated frames continue from the LAST reference block, so on a
- * reference-extend panel the final video is the continuity anchor: dropping
- * from the tail would discard exactly the entry the extension depends on.
- * Images carry no ordering role and keep the front.
+ * Video overflow drops the NEWEST non-anchor entries: the surplus is whatever
+ * arrived last, and a plain front-drop deleted the user's OLDEST reference
+ * whenever a racing add slipped past the cap. The anchor is exempt whatever
+ * its position — request order is rotary order and the generated frames
+ * continue from the LAST block, so it is the one entry the extension depends
+ * on. Images carry no ordering role and keep the front.
  */
 const sanitizeVideoReferences = (value: unknown, sourceVideoName?: string): VideoReferenceItem[] => {
   if (!Array.isArray(value)) {
@@ -149,7 +151,18 @@ const sanitizeVideoReferences = (value: unknown, sourceVideoName?: string): Vide
   // runs on every read, whereas `setReferences` only fires once the user
   // touches the reference list.
   valid = pinReferenceExtendAnchor(valid);
+
   let videosToDrop = Math.max(0, valid.filter((entry) => entry.kind === 'video').length - VIDEO_REFERENCE_MAX_VIDEOS);
+  const dropped = new Set<VideoReferenceItem>();
+  for (let index = valid.length - 1; index >= 0 && videosToDrop > 0; index -= 1) {
+    const entry = valid[index]!;
+
+    if (entry.kind === 'video' && entry.fromSourceVideo !== true) {
+      dropped.add(entry);
+      videosToDrop -= 1;
+    }
+  }
+
   const result: VideoReferenceItem[] = [];
   let images = 0;
   for (const entry of valid) {
@@ -158,8 +171,7 @@ const sanitizeVideoReferences = (value: unknown, sourceVideoName?: string): Vide
         continue;
       }
       images += 1;
-    } else if (videosToDrop > 0) {
-      videosToDrop -= 1;
+    } else if (dropped.has(entry)) {
       continue;
     }
     result.push(entry);
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
index cbf6de925e5..e9df66c6f4f 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoReferenceListField.tsx
@@ -301,14 +301,32 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
         const [resolved] = await galleryImages.resolveMany([imageName]);
 
         if (resolved) {
-          onChange((current) => [
-            ...current,
-            {
-              detail: 'max',
-              image: { height: resolved.height, image_name: resolved.imageName, width: resolved.width },
-              kind: 'image',
-            },
-          ]);
+          // Re-check the cap against the LIVE list: the render-time gate was
+          // evaluated before the await, and another writer (a second drop, or
+          // the Initial Video placing its anchor) can fill the slots meanwhile.
+          // An over-cap write would survive to normalization, whose overflow
+          // rule then has to delete SOMETHING the user placed.
+          let declined = false;
+
+          onChange((current) => {
+            if (current.filter((entry) => entry.kind === 'image').length >= maxImages) {
+              declined = true;
+
+              return current;
+            }
+
+            return [
+              ...current,
+              {
+                detail: 'max',
+                image: { height: resolved.height, image_name: resolved.imageName, width: resolved.width },
+                kind: 'image',
+              },
+            ];
+          });
+          if (declined) {
+            setErrorMessage(t('widgets.video.referenceImageCapRace', { max: maxImages }));
+          }
         }
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -318,7 +336,7 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
         setIsLoading(false);
       }
     },
-    [onChange, reportError]
+    [maxImages, onChange, reportError, t]
   );
 
   const addVideoReference = useCallback(
@@ -338,16 +356,31 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
             width: item.width,
           });
 
-          onChange((current) => [
-            ...current,
-            {
-              // References are truncated to the generated duration, not joined: default to
-              // the whole clip rather than the extend-mode 2-frame-tail trim.
-              clip: { ...clip, endFrame: Math.max(0, clip.numFrames - 1), startFrame: 0 },
-              conditioning: 'video_audio',
-              kind: 'video',
-            },
-          ]);
+          // Same live cap re-check as the image path -- the Initial Video's
+          // anchor is the writer that most easily fills the slots mid-await.
+          let declined = false;
+
+          onChange((current) => {
+            if (current.filter((entry) => entry.kind === 'video').length >= maxVideos) {
+              declined = true;
+
+              return current;
+            }
+
+            return [
+              ...current,
+              {
+                // References are truncated to the generated duration, not joined: default to
+                // the whole clip rather than the extend-mode 2-frame-tail trim.
+                clip: { ...clip, endFrame: Math.max(0, clip.numFrames - 1), startFrame: 0 },
+                conditioning: 'video_audio',
+                kind: 'video',
+              },
+            ];
+          });
+          if (declined) {
+            setErrorMessage(t('widgets.video.referenceVideoCapRace', { max: maxVideos }));
+          }
         }
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -357,7 +390,7 @@ export const VideoReferenceListField = memo(function VideoReferenceListField({
         setIsLoading(false);
       }
     },
-    [onChange, reportError]
+    [maxVideos, onChange, reportError, t]
   );
 
   const handleDragEnd = useCallback(

From c42be9352e5d4c2302509a9f50e26eb5173cab68 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 10:56:38 -0400
Subject: [PATCH 17/19] fix(webv2): live-read setSourceVideo, close out the
 review's small findings

setSourceVideo was the one reference writer still resolving against a captured
`values.references` -- and it is called from an await (the clip field's adopt
and upload paths), so a reference added while an Initial Video drop resolved
was clobbered by the stale list. It now reads through the project-scoped ref
like its siblings, with the same drop-the-write guard for a project that moved
on, and its refusal identity check compares against the list it actually used.

tailSourceFrames gets its closed form: for an integer budget,
`floor(t*24/fps + 0.5) >= budget` is exactly `t >= (budget - 0.5)*fps/24`, so
the smallest count is a ceil away, with two at-most-a-step loops absorbing
last-ulp float disagreements. The previous walk down from `ceil(budget*fps/24)`
ran ~fps/24 iterations -- its own comment claimed the inverse bound -- which an
absurd-but-probeable container frame rate turned into 124 ms per Frames
keystroke. Verified value-identical across 3,952 (budget x rate) pairs
including NTSC rationals; the up-loop never fired.

The browser seed-toggle test now sets IS_REACT_ACT_ENVIRONMENT like every
other browser test, so its act() calls actually gate on effect flushing
instead of warning six times and passing on userEvent's own awaits.

Also DECIDED, recorded in toReferenceStartIndex's docstring: TAIL_INDEX_SLOP
stays at 3. An estimate error past the slop can still hard-fail the relative
start, but only on a clip barely longer than the window (it needs
error > startFrame), and 3 is this file's declared bound on estimate error.
A wider guard would move the cliff, not remove it, and pay with silent length
drift on every clip inside the wider margin.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../webv2/src/features/video/core/graph.ts    |  7 ++++++
 .../webv2/src/features/video/core/settings.ts | 24 ++++++++++++-------
 .../src/features/video/ui/VideoWidgetView.tsx | 19 ++++++++-------
 .../video/ui/seedToggle.browser.test.tsx      |  2 ++
 4 files changed, 36 insertions(+), 16 deletions(-)

diff --git a/invokeai/frontend/webv2/src/features/video/core/graph.ts b/invokeai/frontend/webv2/src/features/video/core/graph.ts
index dcddba2e128..6334b7ecd2f 100644
--- a/invokeai/frontend/webv2/src/features/video/core/graph.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/graph.ts
@@ -137,6 +137,13 @@ const addReferenceNode = (
  * clip, where its length cannot be honoured anyway; below the slop the absolute
  * form is always in range, and the drift it costs is the estimate error itself,
  * a frame or two.
+ *
+ * DECIDED: the slop is not widened beyond 3. An estimate error past the slop
+ * can still fail the relative form, but only on a clip barely longer than the
+ * window (it needs `error > startFrame`), and `TAIL_INDEX_SLOP` is this file's
+ * declared bound on how wrong the estimate gets. A wider guard would not
+ * remove the cliff — it would move it, and pay for the move with silent length
+ * drift on every clip inside the wider margin.
  */
 const toReferenceStartIndex = (reference: Extract<VideoReferenceItem, { kind: 'video' }>, endIndex: number): number => {
   const { clip } = reference;
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index acec796f571..7f0ce0eedd6 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -519,17 +519,25 @@ const referenceExtendStartFrame = (clip: VideoSourceClip, numFrames: number): nu
 /**
  * The fewest source frames that still resample to at least `budget` frames.
  *
- * `ceil(budget * fps / 24)` is the closed form and it is not exact: the
- * resample is a step function, so the rounded-up count can overshoot the
- * budget by a frame or two, and every overshot frame is discarded from the END
- * — the seam. Walking back down to the smallest count that still reaches the
- * budget lands on it exactly wherever the source's frame boundaries allow, and
- * within a frame where they do not (12 fps cannot hit an odd 141 at all). The
- * loop runs `24 / fps` times at most.
+ * `floor(t * 24/fps + 0.5) >= budget` is, for an integer budget, exactly
+ * `t >= (budget - 0.5) * fps / 24` — so the smallest such `t` has a closed
+ * form. The two bounded loops absorb the last-ulp disagreements between that
+ * expression and `resampledFrameCount`'s association of the same arithmetic;
+ * each runs at most a step or two. (An earlier version walked down from
+ * `ceil(budget * fps / 24)` instead, which is `~fps / 24` iterations — 124 ms
+ * per Frames keystroke at an absurd-but-probeable rate.)
+ *
+ * Landing short is what matters: the resample is a step function, and every
+ * frame past the budget is discarded from the END — the seam. The minimum
+ * lands on the budget exactly wherever the source's frame boundaries allow,
+ * and within a frame where they cannot (12 fps cannot hit an odd 141 at all).
  */
 const tailSourceFrames = (budget: number, fps: number): number => {
-  let tail = Math.max(MIN_VIDEO_TRIM_FRAMES, Math.ceil((budget * fps) / MINIMAX_H3_FPS));
+  let tail = Math.max(MIN_VIDEO_TRIM_FRAMES, Math.ceil(((budget - 0.5) * fps) / MINIMAX_H3_FPS));
 
+  while (resampledFrameCount(tail, fps) < budget) {
+    tail += 1;
+  }
   while (tail > MIN_VIDEO_TRIM_FRAMES && resampledFrameCount(tail - 1, fps) >= budget) {
     tail -= 1;
   }
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index 3685fc75a55..70a98da720e 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -307,12 +307,15 @@ export const VideoWidgetView = () => {
   const setSourceVideo = useCallback(
     (sourceVideo: VideoSourceClip | null) => {
       if (referenceExtend) {
-        const references = applyReferenceExtendSourceVideo(
-          values.references,
-          sourceVideo,
-          maxVideoReferences,
-          values.numFrames
-        );
+        // Same project-scoped live read as `setReferences`: the clip field's
+        // adopt and upload paths call this after an await, and a captured
+        // list would clobber a reference added meanwhile. A write whose
+        // project has moved on is dropped.
+        if (referencesRef.current.projectId !== projectId) {
+          return;
+        }
+        const current = referencesRef.current.references;
+        const references = applyReferenceExtendSourceVideo(current, sourceVideo, maxVideoReferences, values.numFrames);
 
         // Unchanged identity with a clip set means the video cap is full and
         // no same-clip entry could be adopted. REFUSE the whole drop: patching
@@ -322,7 +325,7 @@ export const VideoWidgetView = () => {
         // only ask about the clip currently set, and this drop is a different
         // one.) Clearing is never refused -- removing the linked entry cannot
         // overflow anything.
-        if (sourceVideo && references === values.references) {
+        if (sourceVideo && references === current) {
           toaster.create({
             description: t('widgets.video.referenceExtendCapFullDescription'),
             title: t('widgets.video.referenceExtendCapFull'),
@@ -336,7 +339,7 @@ export const VideoWidgetView = () => {
       }
       patch({ sourceVideo, ...(sourceVideo ? { firstFrameImage: null } : {}) });
     },
-    [maxVideoReferences, patch, referenceExtend, t, values.numFrames, values.references]
+    [maxVideoReferences, patch, projectId, referenceExtend, t, values.numFrames]
   );
   // The single choke point for every list edit the reference field makes — add,
   // remove, retrim, reorder — so pinning the continuity anchor here covers all
diff --git a/invokeai/frontend/webv2/src/features/video/ui/seedToggle.browser.test.tsx b/invokeai/frontend/webv2/src/features/video/ui/seedToggle.browser.test.tsx
index a998c18175a..3858afcb66b 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/seedToggle.browser.test.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/seedToggle.browser.test.tsx
@@ -17,6 +17,8 @@ import { userEvent } from 'vitest/browser';
 let container: HTMLDivElement;
 let root: Root;
 
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
 beforeEach(() => {
   container = document.createElement('div');
   document.body.append(container);

From bfd058947d9cabec357c6f828189649b8c173f09 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 11:29:54 -0400
Subject: [PATCH 18/19] fix(webv2): close the third review round's findings

Four fixes, two of them sharing a root.

The derived flag adopts the LAST same-name entry, not the first. The pin
invariant records the anchor last, and metadata can hold a user's own
reference to the source clip ahead of it -- a first-match flagged the user's
entry: their trim was re-budgeted, the list reordered against the recording,
and the true tail window sat unprotected at the seam, the exact bug the
derivation exists to fix, displaced onto the wrong reference.

The flag is canonicalized to at most one entry (keeping the last) before the
pin and the trim. Two flagged entries -- a corrupt or hand-merged record --
were a poisoned state: the pin swaps the pair on alternate normalization
passes, and the overflow trim exempts every flagged entry, so an over-cap
list of them could never come back under the cap. With one flag, both
invariants hold unconditionally. The drop set is also keyed by index rather
than object identity, so an aliased entry can no longer take its twin down
with it.

The fps guard gains an upper bound (1000). Past ~2^53 source frames the
tailSourceFrames adjustment loops cannot even step -- `tail + 1 === tail` in
floats -- and spin forever: a hand-edited record with fps 1e17 froze the tab
on the first Frames keystroke, verified with a real 60s hang. The closed-form
commit fixed the ~1e6-range loop cost and left this range hanging; absurd
rates now take the same fallback as broken ones.

The reference ref carries a LIVENESS bit, set in its sync effect and cleared
in that effect's cleanup. A hidden <Activity> destroys effects while promise
continuations keep running, so the ref froze with the projectId still
matching -- and a same-project guard replayed the frozen list over whatever
the store had done meanwhile, resurrecting references a gallery deletion
sweep had removed. A write now needs the ref both live and same-project.
setReferences also skips the patch when the updater returns its input
identity: a declined add no longer fires the spread's first/last-frame
clearing or dirties the project with a no-op write. Comments corrected to
say effect-fresh rather than live -- two resolves in one microtask drain
still share a window, which is inherent to reading through React state.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../src/features/video/core/settings.test.ts  | 64 ++++++++++++++++
 .../webv2/src/features/video/core/settings.ts | 76 ++++++++++++++-----
 .../src/features/video/ui/VideoWidgetView.tsx | 60 ++++++++++-----
 3 files changed, 164 insertions(+), 36 deletions(-)

diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index 4606edc1905..c78b0de5f51 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -638,6 +638,70 @@ describe('reference-extend linkage', () => {
     expect(unlinked?.references[0]).not.toHaveProperty('fromSourceVideo');
   });
 
+  it('adopts the LAST same-name entry: the pin invariant records the anchor last', () => {
+    // Recorded metadata can hold a user's OWN reference to the source clip
+    // ahead of the anchor -- the pin forces the anchor last, so it is always
+    // the later same-name entry. A first-match flagged the user's reference:
+    // their trim got re-budgeted, the list reordered against the recording,
+    // and the true tail window sat unprotected at the seam.
+    const userRef = {
+      ...VIDEO_REFERENCE,
+      clip: { ...VIDEO_REFERENCE.clip, endFrame: 20, startFrame: 0, video_name: 'long.mp4' },
+    };
+    const tailRef = { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'long.mp4' } };
+    const normalized = normalizeVideoSettings(
+      createSettings({ references: [userRef, tailRef], sourceVideo: source24 })
+    );
+
+    expect(normalized?.references[0]).toBe(userRef);
+    expect(normalized?.references[1]).toMatchObject({ clip: { endFrame: 47 }, fromSourceVideo: true });
+  });
+
+  it('canonicalizes the flag to at most one entry and keeps normalization stable', () => {
+    // Two flagged entries (a corrupt or hand-merged record) used to oscillate:
+    // the pin moves the FIRST flagged entry last, swapping the pair on every
+    // pass -- and the overflow trim exempts every flagged entry, so an
+    // over-cap list of them could never come back under the cap.
+    const flaggedNamed = (video_name: string) => ({
+      ...VIDEO_REFERENCE,
+      clip: { ...VIDEO_REFERENCE.clip, video_name },
+      fromSourceVideo: true,
+    });
+    const once = normalizeVideoSettings(createSettings({ references: [flaggedNamed('a.mp4'), flaggedNamed('b.mp4')] }));
+    const twice = normalizeVideoSettings(createSettings({ references: once!.references }));
+
+    expect(once?.references.filter((entry) => entry.kind === 'video' && entry.fromSourceVideo === true)).toHaveLength(
+      1
+    );
+    expect(once?.references.at(-1)).toMatchObject({ clip: { video_name: 'b.mp4' }, fromSourceVideo: true });
+    expect(twice?.references).toEqual(once?.references);
+
+    // All-flagged over the cap: the exemption can no longer make the surplus
+    // immortal -- the cap holds, and the surviving flag is the last one.
+    const overCap = normalizeVideoSettings(
+      createSettings({ references: ['a', 'b', 'c', 'd'].map((name) => flaggedNamed(`${name}.mp4`)) })
+    );
+
+    expect(overCap?.references).toHaveLength(3);
+    expect(
+      overCap?.references.filter((entry) => entry.kind === 'video' && entry.fromSourceVideo === true)
+    ).toHaveLength(1);
+    expect(overCap?.references.at(-1)).toMatchObject({ clip: { video_name: 'd.mp4' }, fromSourceVideo: true });
+  });
+
+  it('an absurd probed frame rate falls back to 24 instead of hanging', () => {
+    // Past ~2^53 source frames, tailSourceFrames' adjustment loops cannot even
+    // step (tail + 1 === tail in floats) -- fps 1e17 froze the tab. Any rate
+    // no real container produces now takes the same fallback as a broken one.
+    expect(deriveReferenceExtendClip({ ...source24, fps: 1e17 }, 141)).toMatchObject({
+      endFrame: 400,
+      startFrame: 260,
+    });
+    expect(deriveReferenceExtendClip({ ...source24, fps: 1001 }, 141)).toMatchObject({ startFrame: 260 });
+    // The boundary itself is still a real rate.
+    expect(deriveReferenceExtendClip({ ...source24, fps: 1000 }, 141)).not.toMatchObject({ startFrame: 260 });
+  });
+
   it('adopts an unflagged reference for the same clip instead of duplicating it (recall shape)', () => {
     const recalled = { ...VIDEO_REFERENCE, clip: { ...VIDEO_REFERENCE.clip, video_name: 'long.mp4' } };
     const result = applyReferenceExtendSourceVideo([IMAGE_REFERENCE, recalled], source24, 3, FRAMES);
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index 7f0ce0eedd6..35fee0cb39b 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -122,6 +122,28 @@ const sanitizeVideoReferences = (value: unknown, sourceVideoName?: string): Vide
   }
   let valid = value.filter((entry) => isVideoReferenceItem(entry));
 
+  // Canonicalize the flag to AT MOST ONE entry, keeping the LAST. Only a
+  // corrupt or hand-merged record carries two, but two is a poisoned state:
+  // the pin moves the FIRST flagged entry last, so normalization oscillates
+  // between the pair on alternate passes, and the overflow trim below exempts
+  // every flagged entry, so an over-cap list of them could never be brought
+  // under the cap again. The last one matches the pin invariant every healthy
+  // record was written under.
+  let flagged = -1;
+  for (let index = valid.length - 1; index >= 0; index -= 1) {
+    const entry = valid[index]!;
+
+    if (entry.kind === 'video' && entry.fromSourceVideo === true) {
+      flagged = index;
+      break;
+    }
+  }
+  valid = valid.map((entry, index) =>
+    index !== flagged && entry.kind === 'video' && entry.fromSourceVideo === true
+      ? { ...entry, fromSourceVideo: false }
+      : entry
+  );
+
   // Re-establish the linkage recall drops. `fromSourceVideo` is panel state
   // and never reaches metadata, so a recalled panel arrives with its anchor
   // UNFLAGGED beside the source video -- and every invariant keyed on the flag
@@ -129,18 +151,24 @@ const sanitizeVideoReferences = (value: unknown, sourceVideoName?: string): Vide
   // silently lapses: a Frames change left the recalled window unbudgeted and
   // the backend cut 2s off the seam. The flag is derivable, not just
   // storable: the video reference naming the Initial Video's clip IS the
-  // anchor, the same identity `applyReferenceExtendSourceVideo` adopts by.
-  // An already-flagged entry stays authoritative.
-  if (
-    sourceVideoName !== undefined &&
-    !valid.some((entry) => entry.kind === 'video' && entry.fromSourceVideo === true)
-  ) {
-    const adopt = valid.findIndex((entry) => entry.kind === 'video' && entry.clip.video_name === sourceVideoName);
-
-    if (adopt >= 0) {
-      valid = valid.map((entry, index) =>
-        index === adopt && entry.kind === 'video' ? { ...entry, fromSourceVideo: true } : entry
-      );
+  // anchor. An already-flagged entry stays authoritative.
+  //
+  // Adopt the LAST same-name entry, not the first. The pin invariant means
+  // the anchor is always recorded last, and recorded metadata can hold a
+  // user's OWN reference to the same clip ahead of it -- a first-match
+  // flagged that one instead: the user's trim got re-budgeted, the list
+  // reordered against the recording, and the true tail window was left
+  // unprotected at the seam.
+  if (flagged === -1 && sourceVideoName !== undefined) {
+    for (let index = valid.length - 1; index >= 0; index -= 1) {
+      const entry = valid[index]!;
+
+      if (entry.kind === 'video' && entry.clip.video_name === sourceVideoName) {
+        valid = valid.map((candidate, candidateIndex) =>
+          candidateIndex === index && candidate.kind === 'video' ? { ...candidate, fromSourceVideo: true } : candidate
+        );
+        break;
+      }
     }
   }
 
@@ -152,26 +180,30 @@ const sanitizeVideoReferences = (value: unknown, sourceVideoName?: string): Vide
   // touches the reference list.
   valid = pinReferenceExtendAnchor(valid);
 
+  // Keyed by INDEX, not object identity: a hand-edited record can alias the
+  // same entry object twice, and an identity Set would drop both copies.
+  // With the flag canonicalized to at most one entry above, the flag
+  // exemption can never leave the surplus undroppable.
   let videosToDrop = Math.max(0, valid.filter((entry) => entry.kind === 'video').length - VIDEO_REFERENCE_MAX_VIDEOS);
-  const dropped = new Set<VideoReferenceItem>();
+  const dropped = new Set<number>();
   for (let index = valid.length - 1; index >= 0 && videosToDrop > 0; index -= 1) {
     const entry = valid[index]!;
 
     if (entry.kind === 'video' && entry.fromSourceVideo !== true) {
-      dropped.add(entry);
+      dropped.add(index);
       videosToDrop -= 1;
     }
   }
 
   const result: VideoReferenceItem[] = [];
   let images = 0;
-  for (const entry of valid) {
+  for (const [index, entry] of valid.entries()) {
     if (entry.kind === 'image') {
       if (images >= VIDEO_REFERENCE_MAX_IMAGES) {
         continue;
       }
       images += 1;
-    } else if (dropped.has(entry)) {
+    } else if (dropped.has(index)) {
       continue;
     }
     result.push(entry);
@@ -483,6 +515,9 @@ export const deriveReferenceExtendClip = (sourceVideo: VideoSourceClip, numFrame
   startFrame: referenceExtendStartFrame(sourceVideo, numFrames),
 });
 
+/** The highest source frame rate the tail-window math accepts as real; see the fps guard below. */
+const MAX_REFERENCE_SOURCE_FPS = 1000;
+
 /** `snap_reference_num_frames`: down to the `17n + 5` grid the video VAE encodes whole. */
 const snapReferenceFrames = (frames: number): number => Math.max(1, Math.floor((frames - 5) / 17)) * 17 + 5;
 
@@ -495,8 +530,13 @@ const referenceExtendStartFrame = (clip: VideoSourceClip, numFrames: number): nu
   // A clip whose probe recorded no usable rate: the backend resamples at the
   // rate it probes, so 24 — a no-op conversion — is the only safe assumption.
   // A zero or negative rate would otherwise collapse the window to the 2-frame
-  // floor, which is below the 13 frames text conditioning needs.
-  const fps = Number.isFinite(clip.fps) && clip.fps > 0 ? clip.fps : MINIMAX_H3_FPS;
+  // floor, which is below the 13 frames text conditioning needs. The upper
+  // bound is a hang guard: past ~2^53 source frames, `tailSourceFrames`'
+  // adjustment loops cannot even step (`tail + 1 === tail` in floats) and spin
+  // forever on the main thread — a hand-edited record with fps 1e17 froze the
+  // tab on the first Frames keystroke. No real container exceeds 1000 fps.
+  const fps =
+    Number.isFinite(clip.fps) && clip.fps > 0 && clip.fps <= MAX_REFERENCE_SOURCE_FPS ? clip.fps : MINIMAX_H3_FPS;
   const requested = Number.isFinite(numFrames)
     ? Math.min(VIDEO_REFERENCE_EXTEND_TAIL_FRAMES, Math.trunc(numFrames))
     : VIDEO_REFERENCE_EXTEND_TAIL_FRAMES;
diff --git a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
index 70a98da720e..ffa06b4db55 100644
--- a/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
+++ b/invokeai/frontend/webv2/src/features/video/ui/VideoWidgetView.tsx
@@ -161,16 +161,30 @@ export const VideoWidgetView = () => {
   // Synced in an effect rather than during render: this file's react-compiler
   // rule forbids touching a ref while rendering, and a gallery resolve lands
   // whole frames later, long after the commit.
-  // Keyed by PROJECT, not just latest: the widget is reconciled, never
-  // remounted, across a project switch (the <Activity> key is the panel
+  // Keyed by PROJECT, and carrying a LIVENESS bit. The widget is reconciled,
+  // never remounted, across a project switch (the <Activity> key is the panel
   // instance), while `patch` stays bound to the project its render belonged
-  // to. A bare latest-list ref therefore tracks whichever project is ACTIVE —
-  // and a gallery resolve landing after a switch would write the new project's
-  // reference list into the old project, wholesale.
-  const referencesRef = useRef({ projectId, references: values.references });
+  // to — so a bare latest-list ref tracks whichever project is ACTIVE, and a
+  // gallery resolve landing after a switch would write the new project's
+  // reference list into the old project, wholesale. And a hidden <Activity>
+  // destroys effects while promise continuations keep running: the ref then
+  // freezes with the projectId still matching, so a same-project guard would
+  // happily replay a list the store has since rewritten (a gallery deletion
+  // sweep, say) — resurrecting swept references. `live` is true exactly while
+  // the sync effect is mounted, which is the only time the ref's contents can
+  // be trusted; a write finding it false or mismatched is dropped.
+  //
+  // "Fresh" here means effect-fresh, not instantaneous: two resolves landing
+  // in the same microtask drain still read the same pre-commit list. That
+  // window is inherent to reading through React state at all.
+  const referencesRef = useRef({ live: true, projectId, references: values.references });
 
   useEffect(() => {
-    referencesRef.current = { projectId, references: values.references };
+    referencesRef.current = { live: true, projectId, references: values.references };
+
+    return () => {
+      referencesRef.current = { ...referencesRef.current, live: false };
+    };
   }, [projectId, values.references]);
 
   // Chakra's `Field.Root` hands its single `ids.control` to EVERY control
@@ -292,7 +306,7 @@ export const VideoWidgetView = () => {
   const setNumFrames = useCallback(
     (numFrames: number) =>
       patch(
-        referenceExtend && referencesRef.current.projectId === projectId
+        referenceExtend && referencesRef.current.live && referencesRef.current.projectId === projectId
           ? { numFrames, references: applyReferenceExtendNumFrames(referencesRef.current.references, numFrames) }
           : { numFrames }
       ),
@@ -307,11 +321,12 @@ export const VideoWidgetView = () => {
   const setSourceVideo = useCallback(
     (sourceVideo: VideoSourceClip | null) => {
       if (referenceExtend) {
-        // Same project-scoped live read as `setReferences`: the clip field's
-        // adopt and upload paths call this after an await, and a captured
-        // list would clobber a reference added meanwhile. A write whose
-        // project has moved on is dropped.
-        if (referencesRef.current.projectId !== projectId) {
+        // Same guard as `setReferences`: the clip field's adopt and upload
+        // paths call this after an await, and a captured list would clobber a
+        // reference added meanwhile. Dropped when the project moved on or the
+        // sync effect is unmounted — the ref is effect-fresh, not live, and
+        // only vouches for its contents while mounted.
+        if (!referencesRef.current.live || referencesRef.current.projectId !== projectId) {
           return;
         }
         const current = referencesRef.current.references;
@@ -347,14 +362,23 @@ export const VideoWidgetView = () => {
   // the LAST reference, so the anchor's position is derived, not user-set.
   const setReferences = useCallback(
     (update: (current: VideoReferenceItem[]) => VideoReferenceItem[]) => {
-      // A pending edit whose project has moved on is DROPPED: this callback's
-      // `patch` still targets the project it rendered for, but that project's
-      // current list is gone from the ref. Losing one add because the user
-      // switched projects mid-resolve beats overwriting a list they can see.
-      if (referencesRef.current.projectId !== projectId) {
+      // A pending edit is DROPPED when the ref cannot vouch for the list:
+      // the project moved on (this callback's `patch` still targets the one
+      // it rendered for), or the sync effect is unmounted (a hidden panel's
+      // continuations would replay a frozen list over whatever the store has
+      // done since). Losing one add beats overwriting a list the user can see.
+      if (!referencesRef.current.live || referencesRef.current.projectId !== projectId) {
         return;
       }
       const updated = update(referencesRef.current.references);
+
+      // Identity return means the updater declined (an apply-time cap check)
+      // or had nothing to do: patching anyway would still fire this spread's
+      // firstFrameImage/lastFrameImage clearing — a refused add erasing frame
+      // slots it never touched — and dirty the project with a no-op write.
+      if (updated === referencesRef.current.references) {
+        return;
+      }
       const next = referenceExtend ? pinReferenceExtendAnchor(updated) : updated;
 
       patch({

From 42cf748a9efba401a655a31f5e6ce6b5a35d3ee0 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Mon, 31 Aug 2026 17:24:28 -0400
Subject: [PATCH 19/19] fix(webv2): widen the fps hang guard to 1e6 -- 1000
 regressed real high-rate clips

The float plateau the bound guards (`tail + 1 === tail`) starts around fps
1.5e15; the bound was 1000 -- twelve orders tighter than the failure. Every
rate in between terminated in the closed form and produced a correct window
before the guard existed, and the clamp broke it: a probe-reported 1200 fps
clip took the 24 fallback, the frontend sized a 141-SOURCE-frame window, and
the backend -- which resamples at the rate it probes itself, with no fps field
in the graph to override it -- collapsed that window to 3 frames, under text
conditioning's 13-frame minimum. A working input became a hard invoke-time
ValueError with nothing pointing at the clamp.

1e6 kills the hang with nine orders of margin and no reachable regression.
The boundary test now actually pins the behaviour on both sides: 1200 fps on
a 50001-frame clip derives its real 7025-source-frame window (previously
asserted through a fixture too short to distinguish the clamp from its
fallback), and 1e17 takes the fallback and terminates.

Found by the fourth adversarial pass, scoped to the previous commit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDrDMYKpzD8h5PRy5kLjzH
---
 .../webv2/src/features/video/core/settings.test.ts | 12 +++++++++---
 .../webv2/src/features/video/core/settings.ts      | 14 +++++++++++---
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
index c78b0de5f51..19f0ac57711 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.test.ts
@@ -697,9 +697,15 @@ describe('reference-extend linkage', () => {
       endFrame: 400,
       startFrame: 260,
     });
-    expect(deriveReferenceExtendClip({ ...source24, fps: 1001 }, 141)).toMatchObject({ startFrame: 260 });
-    // The boundary itself is still a real rate.
-    expect(deriveReferenceExtendClip({ ...source24, fps: 1000 }, 141)).not.toMatchObject({ startFrame: 260 });
+    // Below the bound, a genuinely high-rate clip still gets its REAL window:
+    // 1200 fps needs 7025 source frames for 141 resampled ones. A 1000-fps
+    // bound sent this through the 24 fallback, and the backend -- which
+    // resamples at the rate it probes itself -- collapsed the 141-source-frame
+    // window to 3 frames and raised under text conditioning's 13-frame floor.
+    const highRate = { ...source24, endFrame: 50000, fps: 1200, numFrames: 50001 };
+
+    expect(deriveReferenceExtendClip(highRate, 141)).toMatchObject({ endFrame: 50000, startFrame: 42976 });
+    expect(deriveReferenceExtendClip({ ...highRate, fps: 1e17 }, 141)).toMatchObject({ startFrame: 49860 });
   });
 
   it('adopts an unflagged reference for the same clip instead of duplicating it (recall shape)', () => {
diff --git a/invokeai/frontend/webv2/src/features/video/core/settings.ts b/invokeai/frontend/webv2/src/features/video/core/settings.ts
index 35fee0cb39b..4cbc9cd8558 100644
--- a/invokeai/frontend/webv2/src/features/video/core/settings.ts
+++ b/invokeai/frontend/webv2/src/features/video/core/settings.ts
@@ -515,8 +515,16 @@ export const deriveReferenceExtendClip = (sourceVideo: VideoSourceClip, numFrame
   startFrame: referenceExtendStartFrame(sourceVideo, numFrames),
 });
 
-/** The highest source frame rate the tail-window math accepts as real; see the fps guard below. */
-const MAX_REFERENCE_SOURCE_FPS = 1000;
+/**
+ * The highest source frame rate the tail-window math accepts as real; see the
+ * fps guard below. The float plateau it guards (`tail + 1 === tail`) starts
+ * around fps 1.5e15, so 1e6 keeps nine orders of margin — a tighter bound of
+ * 1000 turned real high-rate containers (probe-reported 1200 fps decoded fine
+ * before) into backend hard failures: the 24 fps fallback sized a 141-SOURCE-
+ * frame window that the backend, resampling at the rate it probes itself,
+ * collapsed to 3 frames, under text conditioning's 13-frame minimum.
+ */
+const MAX_REFERENCE_SOURCE_FPS = 1e6;
 
 /** `snap_reference_num_frames`: down to the `17n + 5` grid the video VAE encodes whole. */
 const snapReferenceFrames = (frames: number): number => Math.max(1, Math.floor((frames - 5) / 17)) * 17 + 5;
@@ -534,7 +542,7 @@ const referenceExtendStartFrame = (clip: VideoSourceClip, numFrames: number): nu
   // bound is a hang guard: past ~2^53 source frames, `tailSourceFrames`'
   // adjustment loops cannot even step (`tail + 1 === tail` in floats) and spin
   // forever on the main thread — a hand-edited record with fps 1e17 froze the
-  // tab on the first Frames keystroke. No real container exceeds 1000 fps.
+  // tab on the first Frames keystroke.
   const fps =
     Number.isFinite(clip.fps) && clip.fps > 0 && clip.fps <= MAX_REFERENCE_SOURCE_FPS ? clip.fps : MINIMAX_H3_FPS;
   const requested = Number.isFinite(numFrames)