From 4f18cdfe9ee843c871aa54a88473033de6f9c144 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 15:11:40 +0800
Subject: [PATCH 01/14] fix(editor): fold a probed duration in on the shared
 write queue

`useSequentialTimelineOps` exists because every timeline edit is a
read-modify-write of the whole document, and its header says so: anything that
reads the doc and saves it back belongs on that chain. The `loadedmetadata`
handler did neither -- it read `getState().document` and issued its own save.

That is enough to lose an edit, because the store is only written once the bridge
answers. A user's save in flight leaves `getState()` returning the PRE-edit
document, the probe builds a full snapshot from it, and whichever write lands
second wins. The epoch check in `saveDocument` does not cover this: it guards
undo, redo and project switches, not a concurrent save.

Move the read, the compute and the write inside `enqueueTimelineWrite`, which the
shell already holds, and await the saves so the queue actually waits for them --
a fire-and-forget write would let the next queued edit read a document this one
has not committed yet.
---
 src/components/ai-edition/NewEditorShell.tsx | 91 +++++++++++---------
 1 file changed, 52 insertions(+), 39 deletions(-)

diff --git a/src/components/ai-edition/NewEditorShell.tsx b/src/components/ai-edition/NewEditorShell.tsx
index b82c2a1cf..e04887d95 100644
--- a/src/components/ai-edition/NewEditorShell.tsx
+++ b/src/components/ai-edition/NewEditorShell.tsx
@@ -429,47 +429,60 @@ export function NewEditorShell() {
 			// placeholder. All store reads go through getState() to avoid
 			// stale-closure bugs.
 			const known = Number.isFinite(durationSec) && durationSec > 0 ? durationSec : 60;
-			const state = useProjectStore.getState();
 			setSourceDuration(known);
-			const doc = state.document;
-			if (!doc || doc.assets.length === 0) return;
-			if (doc.timeline.clips.length === 0) {
-				// ponytail: replaceTimeline derives clip length from
-				// asset.durationSec, which import never populates — without this
-				// patch the first auto-created clip silently comes out empty
-				// (normalizeIntervals clamps against a 0 duration and drops it).
-				const primaryAssetId = doc.project.primaryAssetId ?? doc.assets[0]?.id;
-				const docWithDuration = primaryAssetId
-					? {
-							...doc,
-							assets: doc.assets.map((a) =>
-								a.id === primaryAssetId ? { ...a, durationSec: known } : a,
-							),
-						}
-					: doc;
-				const next = replaceTimelineOp(
-					docWithDuration,
-					[{ startSec: 0, endSec: known }],
-					"Auto-created full-duration clip",
-				);
-				// `history: false` for both writes in this callback: they are the probed
-				// duration being folded into the document on load, not something the user
-				// did — an undo landing on one of them would empty their timeline.
-				void state.saveDocument(next, { history: false });
-				return;
-			}
-			// Hand the probed duration to the pure document layer: it patches only the
-			// clips of THIS asset that are still waiting for a real length (the
-			// pre-probe placeholder, or the extent-less clip a legacy v2 import mints),
-			// shifts what follows, and brings the modifiers along — anchoring the ones
-			// migration had to leave unanchored. Returns the document untouched when
-			// nothing is waiting, so there is nothing to guard here.
-			const next = applyProbedDuration(doc, assetId, known);
-			if (next !== doc) {
-				void state.saveDocument(next, { history: false });
-			}
+			// On the shared write queue, and reading the document inside it. Folding a
+			// probed duration in is a read-modify-write of the whole document, which is
+			// what `useSequentialTimelineOps` exists for -- its header says anything that
+			// reads the doc and saves it back belongs there. Off the queue, `getState()`
+			// returns the PRE-edit document while a user's save is still in flight (the
+			// store is only written once the bridge answers), and the full snapshot built
+			// from it lands after theirs and takes their edit with it.
+			void enqueueTimelineWrite(async () => {
+				const state = useProjectStore.getState();
+				const doc = state.document;
+				if (!doc || doc.assets.length === 0) return;
+				if (doc.timeline.clips.length === 0) {
+					// ponytail: replaceTimeline derives clip length from
+					// asset.durationSec, which import never populates — without this
+					// patch the first auto-created clip silently comes out empty
+					// (normalizeIntervals clamps against a 0 duration and drops it).
+					const primaryAssetId = doc.project.primaryAssetId ?? doc.assets[0]?.id;
+					const docWithDuration = primaryAssetId
+						? {
+								...doc,
+								assets: doc.assets.map((a) =>
+									a.id === primaryAssetId ? { ...a, durationSec: known } : a,
+								),
+							}
+						: doc;
+					const next = replaceTimelineOp(
+						docWithDuration,
+						[{ startSec: 0, endSec: known }],
+						"Auto-created full-duration clip",
+					);
+					// `history: false` for both writes in this callback: they are the probed
+					// duration being folded into the document on load, not something the user
+					// did — an undo landing on one of them would empty their timeline.
+					//
+					// Awaited, not `void`ed: the queue only serialises what it can see finish,
+					// so a fire-and-forget write here would let the next queued edit read the
+					// document this one has not committed yet.
+					await state.saveDocument(next, { history: false });
+					return;
+				}
+				// Hand the probed duration to the pure document layer: it patches only the
+				// clips of THIS asset that are still waiting for a real length (the
+				// pre-probe placeholder, or the extent-less clip a legacy v2 import mints),
+				// shifts what follows, and brings the modifiers along — anchoring the ones
+				// migration had to leave unanchored. Returns the document untouched when
+				// nothing is waiting, so there is nothing to guard here.
+				const next = applyProbedDuration(doc, assetId, known);
+				if (next !== doc) {
+					await state.saveDocument(next, { history: false });
+				}
+			});
 		},
-		[setSourceDuration],
+		[setSourceDuration, enqueueTimelineWrite],
 	);
 
 	const handleSeek = useCallback(

From 2130023b666b195df4fe3c6ee423884deb761b2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 15:11:52 +0800
Subject: [PATCH 02/14] fix(timeline): read the document at write time in
 addZoomsBulk

Its `add*` siblings compute and save in the same tick, so reading the render
closure is harmless there. This one is different: the wand captures the callback,
awaits a multi-second cursor-telemetry IPC, and only then calls it. Anything the
user commits during that wait is in the store but not in the closure, so the
snapshot written back is missing their edit -- and it was also anchoring the new
regions against clips that may no longer exist.

Read from the store inside the callback, and anchor against that same document,
matching `applyClipEdit`, `setTrimEntries` and `insertClipAt` -- which is also
what lets this compose with `useSequentialTimelineOps` instead of racing it.

The test captures the callback before the store moves, the way the wand does, and
fails against the closure read: the saved document comes back carrying the old
title, with the user's edit gone.
---
 src/lib/ai-edition/store/useTimeline.test.ts | 60 ++++++++++++++++++++
 src/lib/ai-edition/store/useTimeline.ts      | 21 +++++--
 2 files changed, 76 insertions(+), 5 deletions(-)

diff --git a/src/lib/ai-edition/store/useTimeline.test.ts b/src/lib/ai-edition/store/useTimeline.test.ts
index 2bc430311..e9ad26df1 100644
--- a/src/lib/ai-edition/store/useTimeline.test.ts
+++ b/src/lib/ai-edition/store/useTimeline.test.ts
@@ -1596,3 +1596,63 @@ describe("useTimeline audio tracks", () => {
 		expect(probeAudioDurationMock).toHaveBeenCalledTimes(1);
 	});
 });
+
+// The wand (`V4Timeline.runAutoZooms`) captures this callback, awaits a
+// multi-second cursor-telemetry IPC, and only then calls it. Anything the user
+// commits during that wait is in the store but not in the callback's render
+// closure, so reading the closure writes back a snapshot that drops their edit.
+// Its `add*` siblings compute and save in the same tick, which is why this one
+// is the reachable case.
+describe("useTimeline.addZoomsBulk reads the document at write time", () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	beforeEach(() => {
+		useProjectStore.getState().clear();
+		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
+		toastErrorMock.mockReset();
+		bridgeMocks.save.mockImplementation(async (document: AxcutDocument) => ({
+			success: true,
+			document,
+		}));
+		useProjectStore.setState({
+			projectId: "proj_test",
+			document: sampleDoc,
+			revision: 1,
+			status: "ready",
+			error: null,
+		});
+	});
+
+	it("does not write back the document from before the telemetry wait", async () => {
+		const { result } = renderTimeline();
+		// Captured the way the wand captures it: before the wait, not after.
+		const addZoomsBulk = result.current.addZoomsBulk;
+
+		// The user's edit lands while the wand is off fetching telemetry.
+		const edited: AxcutDocument = {
+			...sampleDoc,
+			project: { ...sampleDoc.project, title: "Edited while the wand was busy" },
+		};
+		act(() => {
+			useProjectStore.setState({ document: edited, revision: 2 });
+		});
+
+		let added: number | undefined;
+		await act(async () => {
+			added = await addZoomsBulk([
+				{ span: { start: 1000, end: 2000 }, focus: { cx: 0.5, cy: 0.5 } },
+			]);
+		});
+
+		expect(added).toBe(1);
+		const saved = bridgeMocks.save.mock.calls.at(-1)?.[0] as AxcutDocument;
+		// The zoom was added, and the edit is still there.
+		expect(saved.zoomRanges).toHaveLength(1);
+		expect(saved.project.title).toBe("Edited while the wand was busy");
+		expect(useProjectStore.getState().document?.project.title).toBe(
+			"Edited while the wand was busy",
+		);
+	});
+});
diff --git a/src/lib/ai-edition/store/useTimeline.ts b/src/lib/ai-edition/store/useTimeline.ts
index 40e2408fd..860b9f13f 100644
--- a/src/lib/ai-edition/store/useTimeline.ts
+++ b/src/lib/ai-edition/store/useTimeline.ts
@@ -334,7 +334,15 @@ export function useTimeline() {
 	// Returns the count actually added (0 when there's no doc/suggestions).
 	const addZoomsBulk = useCallback(
 		async (suggestions: AutoZoomSuggestion[]) => {
-			if (!document || suggestions.length === 0) return 0;
+			// Read from the store, not off the render closure. Unlike its `add*` siblings,
+			// which compute and save in the same tick, this one is reached from the wand
+			// AFTER a multi-second cursor-telemetry IPC: the closure document is the one
+			// from before that wait, so anything the user committed during it is missing
+			// from the snapshot, and writing the snapshot back drops their edit. Reading
+			// here is also what lets this compose with `useSequentialTimelineOps` -- same
+			// reason as `applyClipEdit`, `setTrimEntries` and `insertClipAt`.
+			const doc = useProjectStore.getState().document;
+			if (!doc || suggestions.length === 0) return 0;
 			const anchored = suggestions.flatMap((s) =>
 				anchorRegionsWithDerivedMs(
 					[
@@ -347,18 +355,21 @@ export function useTimeline() {
 							focusMode: "auto" as const,
 						},
 					],
-					document.timeline.clips,
+					// Anchored against the SAME document the write is built from: anchoring
+					// on the stale clips and saving the fresh document would place regions
+					// against a timeline that no longer exists.
+					doc.timeline.clips,
 					() => createId("zoom"),
 				),
 			);
 			const next: AxcutDocument = {
-				...document,
-				zoomRanges: [...document.zoomRanges, ...anchored] as AxcutDocument["zoomRanges"],
+				...doc,
+				zoomRanges: [...doc.zoomRanges, ...anchored] as AxcutDocument["zoomRanges"],
 			};
 			if (!(await saveDocument(next, { history: true }))) return 0;
 			return suggestions.length;
 		},
-		[document, saveDocument],
+		[saveDocument],
 	);
 
 	const addTrim = useCallback(

From 955a9eda6c8f68484b2e53a7820c835f4e8a9b86 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 15:24:39 +0800
Subject: [PATCH 03/14] fix(editor): bind the probed duration to the take that
 produced it

Putting the write on the queue fixed one race and opened a narrower one: there is
now real time between the metadata event and the write, and the duration in hand
came off the video that fired the event. Two ways it can land somewhere it does
not belong.

Across projects: switch while the task is queued and the document read inside it
is the new project, which gets the old video's length. `saveDocument`'s epoch
check cannot see this -- the write is issued after the switch, not across it. So
the event is bound to the project that was open when it fired, and dropped if
that is no longer the one loaded.

Within one project: the seed branch stamps the duration on the primary asset and
sizes the clip from it, and `replaceTimeline` hard-codes clips to that same
primary asset -- so an event from any OTHER asset seeds one video's length under
another's id. Pre-existing, but the queue delay is what makes a primary change
between the event and the write reachable at all. Seed only when the asset that
fired is the one the seed is about; the primary's own event does its own seeding.

The sibling branch needed neither guard: `applyProbedDuration` is handed the
asset id and returns the document untouched when it does not hold it.
---
 src/components/ai-edition/NewEditorShell.tsx | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/components/ai-edition/NewEditorShell.tsx b/src/components/ai-edition/NewEditorShell.tsx
index e04887d95..41c2be0b1 100644
--- a/src/components/ai-edition/NewEditorShell.tsx
+++ b/src/components/ai-edition/NewEditorShell.tsx
@@ -437,16 +437,30 @@ export function NewEditorShell() {
 			// returns the PRE-edit document while a user's save is still in flight (the
 			// store is only written once the bridge answers), and the full snapshot built
 			// from it lands after theirs and takes their edit with it.
+			// Bound to the project that was open when the event fired. Queueing puts real
+			// time between the two, and `known` came off THAT video: applied to a project
+			// the user switched to meanwhile it is simply a wrong number, and
+			// `saveDocument`'s epoch check cannot catch it because the write is issued
+			// after the switch, not across it.
+			const originatingProjectId = useProjectStore.getState().document?.project.id;
 			void enqueueTimelineWrite(async () => {
 				const state = useProjectStore.getState();
 				const doc = state.document;
 				if (!doc || doc.assets.length === 0) return;
+				if (doc.project.id !== originatingProjectId) return;
 				if (doc.timeline.clips.length === 0) {
 					// ponytail: replaceTimeline derives clip length from
 					// asset.durationSec, which import never populates — without this
 					// patch the first auto-created clip silently comes out empty
 					// (normalizeIntervals clamps against a 0 duration and drops it).
 					const primaryAssetId = doc.project.primaryAssetId ?? doc.assets[0]?.id;
+					// Only the asset that actually fired this event. The seed stamps `known`
+					// on the primary asset and sizes the whole clip from it, so on a project
+					// whose primary is some OTHER asset that is one video's length written as
+					// another's -- a full-duration clip at the wrong length. The sibling
+					// branch never had this hole: `applyProbedDuration` is handed `assetId`
+					// and returns the document untouched when it does not hold it.
+					if (primaryAssetId !== assetId) return;
 					const docWithDuration = primaryAssetId
 						? {
 								...doc,

From de5b93aed2efa5c7a630bd73da5490efbc5ca1ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 15:35:52 +0800
Subject: [PATCH 04/14] test(editor): cover the probed-duration decision,
 guards included

The two guards in the previous commit shipped untested, on the argument that the
`loadedmetadata` path has no component harness. That confused "cannot test the
component" with "cannot test the behaviour": the decision is pure -- a document,
an asset id, a duration and the project the event came from -- and only the
queueing around it needs the component.

So the decision moves to an exported `documentAfterProbedDuration` and the
handler keeps the wiring. Both guards now fail their tests when removed: without
the project binding a switched-to project takes the old video's length, and
without the asset check a non-primary asset seeds a clip that `replaceTimeline`
pins to the primary. The seed, the fold-in and the already-settled cases are
covered too.

Two `saveDocument` call sites became one, so the write-audit table loses a row.
---
 .../NewEditorShell.probedDuration.test.tsx    | 131 ++++++++++++++++++
 src/components/ai-edition/NewEditorShell.tsx  | 129 +++++++++--------
 .../store/documentWriteAudit.test.ts          |   1 -
 3 files changed, 202 insertions(+), 59 deletions(-)
 create mode 100644 src/components/ai-edition/NewEditorShell.probedDuration.test.tsx

diff --git a/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx b/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
new file mode 100644
index 000000000..ca1bf87a4
--- /dev/null
+++ b/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+// The decision a `loadedmetadata` event makes, on its own.
+//
+// The event itself arrives through Preview -> PreviewCanvas -> VirtualPreview and a
+// real <video>, which jsdom never fires, so the component cannot be driven end to
+// end here. `documentAfterProbedDuration` is the part that decides what gets
+// written, and both guards below live in it: the queue the shell puts this write on
+// is what makes them necessary, because it puts real time between the event and the
+// write. The queue's own serialization is covered by useSequentialTimelineOps.test.
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@/contexts/ShortcutsContext", async () => {
+	const { DEFAULT_SHORTCUTS } = await import("@/lib/shortcuts");
+	return {
+		useShortcuts: () => ({
+			shortcuts: DEFAULT_SHORTCUTS,
+			isMac: false,
+			isConfigOpen: false,
+			openConfig: vi.fn(),
+			closeConfig: vi.fn(),
+			setShortcuts: vi.fn(),
+			persistShortcuts: () => Promise.resolve(true),
+		}),
+	};
+});
+
+vi.mock("@/contexts/I18nContext", () => ({
+	useI18n: () => ({ locale: "en", setLocale: vi.fn() }),
+	useScopedT: () => (key: string) => key,
+}));
+
+import { migrateProjectDataToAxcutDocument } from "@/lib/ai-edition/document/migrate";
+import { type AxcutDocument, createEmptyDocument, documentSchema } from "@/lib/ai-edition/schema";
+import { documentAfterProbedDuration } from "./NewEditorShell";
+
+const PROJECT = "proj_a";
+
+/** A fresh import: assets on the document, nothing on the timeline yet. */
+function emptyTimeline(primaryAssetId: string, assetIds: string[]): AxcutDocument {
+	const doc = createEmptyDocument({ projectId: PROJECT, title: "A" });
+	return {
+		...doc,
+		project: { ...doc.project, primaryAssetId },
+		assets: assetIds.map((id) => ({
+			id,
+			kind: "video" as const,
+			label: `${id}.mp4`,
+			originalPath: `/tmp/${id}.mp4`,
+			cameraTrack: null,
+		})),
+	};
+}
+
+/** A v1.7 project: one clip with no source extent, waiting for a real length. */
+function legacyWithClip(): AxcutDocument {
+	return documentSchema.parse(
+		migrateProjectDataToAxcutDocument({
+			version: 2,
+			videoPath: "C:/rec/screen.webm",
+			media: { videoPath: "C:/rec/screen.webm" },
+			editor: {
+				zoomRegions: [],
+				annotationRegions: [],
+				trimRegions: [],
+				speedRegions: [],
+				cameraFullscreenRegions: [],
+			},
+		} as never),
+	);
+}
+
+describe("documentAfterProbedDuration", () => {
+	it("seeds a full-duration clip when the primary asset reports its length", () => {
+		const doc = emptyTimeline("asset_1", ["asset_1"]);
+
+		const next = documentAfterProbedDuration(doc, "asset_1", 30, PROJECT);
+
+		expect(next).not.toBeNull();
+		expect(next?.assets[0].durationSec).toBe(30);
+		expect(next?.timeline.clips).toHaveLength(1);
+		expect(next?.timeline.clips[0].timelineStartSec).toBe(0);
+		expect(next?.timeline.clips[0].timelineEndSec).toBe(30);
+	});
+
+	// The write is queued, so the user can switch projects between the event and this
+	// decision. `knownSec` came off the OLD video; applying it to whatever is loaded
+	// now writes one recording's length into another project.
+	it("writes nothing when the project changed after the event fired", () => {
+		const doc = emptyTimeline("asset_1", ["asset_1"]);
+
+		expect(documentAfterProbedDuration(doc, "asset_1", 30, "proj_switched_to")).toBeNull();
+		expect(documentAfterProbedDuration(doc, "asset_1", 30, undefined)).toBeNull();
+	});
+
+	// `replaceTimeline` pins every clip it builds to the primary asset, and the seed
+	// sizes that clip from `knownSec` — so seeding on another asset's event would put
+	// one video's length under a different asset's id. The primary's own event seeds it.
+	it("does not seed from an asset that is not the one the seed is about", () => {
+		const doc = emptyTimeline("asset_1", ["asset_1", "asset_2"]);
+
+		expect(documentAfterProbedDuration(doc, "asset_2", 30, PROJECT)).toBeNull();
+		// And the primary still seeds normally on the same document.
+		expect(documentAfterProbedDuration(doc, "asset_1", 30, PROJECT)).not.toBeNull();
+	});
+
+	it("folds the length into a clip that was waiting for one", () => {
+		const doc = legacyWithClip();
+		const assetId = doc.assets[0].id;
+
+		const next = documentAfterProbedDuration(doc, assetId, 30, doc.project.id);
+
+		expect(next?.timeline.clips[0].sourceEndSec).toBe(30);
+		expect(next?.assets[0].durationSec).toBe(30);
+	});
+
+	it("writes nothing when the length is already recorded", () => {
+		const doc = legacyWithClip();
+		const assetId = doc.assets[0].id;
+		const settled = documentAfterProbedDuration(doc, assetId, 30, doc.project.id);
+
+		expect(settled).not.toBeNull();
+		expect(
+			documentAfterProbedDuration(settled as AxcutDocument, assetId, 30, doc.project.id),
+		).toBeNull();
+	});
+
+	it("writes nothing without a document or without assets", () => {
+		expect(documentAfterProbedDuration(null, "asset_1", 30, PROJECT)).toBeNull();
+		expect(documentAfterProbedDuration(emptyTimeline("asset_1", []), "asset_1", 30, PROJECT)).toBeNull();
+	});
+});
diff --git a/src/components/ai-edition/NewEditorShell.tsx b/src/components/ai-edition/NewEditorShell.tsx
index 41c2be0b1..bc0010658 100644
--- a/src/components/ai-edition/NewEditorShell.tsx
+++ b/src/components/ai-edition/NewEditorShell.tsx
@@ -25,7 +25,12 @@ import {
 	setDocumentWordText,
 } from "@/lib/ai-edition/document/transcript";
 import { isModalOpen } from "@/lib/ai-edition/modalGuard";
-import { type AxcutAudioTrack, type AxcutClip, documentSchema } from "@/lib/ai-edition/schema";
+import {
+	type AxcutAudioTrack,
+	type AxcutClip,
+	type AxcutDocument,
+	documentSchema,
+} from "@/lib/ai-edition/schema";
 import { useProjectStore } from "@/lib/ai-edition/store/projectStore";
 import {
 	useAssetTranscriptions,
@@ -115,6 +120,57 @@ export const DEFAULT_TIMELINE_HEIGHT_PX = 392;
 export const MIN_TIMELINE_HEIGHT_PX = 160;
 export const MAX_TIMELINE_HEIGHT_PX = 560;
 
+/**
+ * What a `loadedmetadata` event should write, or `null` for "write nothing".
+ *
+ * Exported because it is the only part of this path a test can reach: the event
+ * arrives through Preview -> PreviewCanvas -> VirtualPreview and a real <video>,
+ * none of which jsdom fires. Keeping the decision here and the queueing in the
+ * component means the two guards below are testable without standing all four up.
+ *
+ * `originatingProjectId` is the project that was open when the event fired. It
+ * matters because the write is queued: by the time this runs the user may have
+ * switched, and `knownSec` came off the OLD video, so applying it to the new
+ * project is simply a wrong number. `saveDocument`'s epoch check cannot catch
+ * that — the write is issued after the switch rather than across it.
+ */
+export function documentAfterProbedDuration(
+	doc: AxcutDocument | null,
+	assetId: string,
+	knownSec: number,
+	originatingProjectId: string | undefined,
+): AxcutDocument | null {
+	if (!doc || doc.assets.length === 0) return null;
+	if (doc.project.id !== originatingProjectId) return null;
+	if (doc.timeline.clips.length === 0) {
+		// ponytail: replaceTimeline derives clip length from asset.durationSec, which
+		// import never populates — without this the first auto-created clip silently
+		// comes out empty (normalizeIntervals clamps against a 0 duration, dropping it).
+		const primaryAssetId = doc.project.primaryAssetId ?? doc.assets[0]?.id;
+		// Only the asset that actually fired. `replaceTimeline` pins every clip it
+		// builds to the primary asset, and the seed sizes that clip from `knownSec` —
+		// so seeding on an event from any OTHER asset writes one video's length under
+		// another's id. Not a lost seed: the primary's own event does its own seeding.
+		if (!primaryAssetId || primaryAssetId !== assetId) return null;
+		const docWithDuration: AxcutDocument = {
+			...doc,
+			assets: doc.assets.map((a) => (a.id === primaryAssetId ? { ...a, durationSec: knownSec } : a)),
+		};
+		return replaceTimelineOp(
+			docWithDuration,
+			[{ startSec: 0, endSec: knownSec }],
+			"Auto-created full-duration clip",
+		);
+	}
+	// The pure document layer patches only the clips of THIS asset that are still
+	// waiting for a real length (the pre-probe placeholder, or the extent-less clip a
+	// legacy v2 import mints), shifts what follows, and brings the modifiers along —
+	// anchoring the ones migration had to leave unanchored. It returns the document
+	// untouched when nothing is waiting, which is this function's "write nothing".
+	const next = applyProbedDuration(doc, assetId, knownSec);
+	return next === doc ? null : next;
+}
+
 export function NewEditorShell() {
 	const te = useScopedT("editor");
 	const document = useProjectStore((s) => s.document);
@@ -426,10 +482,12 @@ export function NewEditorShell() {
 			// ponytail: WebM recordings from MediaRecorder report NaN/Infinity
 			// until the main-process EBML fix lands. Fall back to a 60s seed if
 			// duration is unknown so the timeline never gets stuck on an empty
-			// placeholder. All store reads go through getState() to avoid
-			// stale-closure bugs.
+			// placeholder.
 			const known = Number.isFinite(durationSec) && durationSec > 0 ? durationSec : 60;
 			setSourceDuration(known);
+			// Read before queueing: this is the project the event belongs to. What the
+			// decision does with it is `documentAfterProbedDuration`'s business.
+			const originatingProjectId = useProjectStore.getState().document?.project.id;
 			// On the shared write queue, and reading the document inside it. Folding a
 			// probed duration in is a read-modify-write of the whole document, which is
 			// what `useSequentialTimelineOps` exists for -- its header says anything that
@@ -437,63 +495,18 @@ export function NewEditorShell() {
 			// returns the PRE-edit document while a user's save is still in flight (the
 			// store is only written once the bridge answers), and the full snapshot built
 			// from it lands after theirs and takes their edit with it.
-			// Bound to the project that was open when the event fired. Queueing puts real
-			// time between the two, and `known` came off THAT video: applied to a project
-			// the user switched to meanwhile it is simply a wrong number, and
-			// `saveDocument`'s epoch check cannot catch it because the write is issued
-			// after the switch, not across it.
-			const originatingProjectId = useProjectStore.getState().document?.project.id;
 			void enqueueTimelineWrite(async () => {
 				const state = useProjectStore.getState();
-				const doc = state.document;
-				if (!doc || doc.assets.length === 0) return;
-				if (doc.project.id !== originatingProjectId) return;
-				if (doc.timeline.clips.length === 0) {
-					// ponytail: replaceTimeline derives clip length from
-					// asset.durationSec, which import never populates — without this
-					// patch the first auto-created clip silently comes out empty
-					// (normalizeIntervals clamps against a 0 duration and drops it).
-					const primaryAssetId = doc.project.primaryAssetId ?? doc.assets[0]?.id;
-					// Only the asset that actually fired this event. The seed stamps `known`
-					// on the primary asset and sizes the whole clip from it, so on a project
-					// whose primary is some OTHER asset that is one video's length written as
-					// another's -- a full-duration clip at the wrong length. The sibling
-					// branch never had this hole: `applyProbedDuration` is handed `assetId`
-					// and returns the document untouched when it does not hold it.
-					if (primaryAssetId !== assetId) return;
-					const docWithDuration = primaryAssetId
-						? {
-								...doc,
-								assets: doc.assets.map((a) =>
-									a.id === primaryAssetId ? { ...a, durationSec: known } : a,
-								),
-							}
-						: doc;
-					const next = replaceTimelineOp(
-						docWithDuration,
-						[{ startSec: 0, endSec: known }],
-						"Auto-created full-duration clip",
-					);
-					// `history: false` for both writes in this callback: they are the probed
-					// duration being folded into the document on load, not something the user
-					// did — an undo landing on one of them would empty their timeline.
-					//
-					// Awaited, not `void`ed: the queue only serialises what it can see finish,
-					// so a fire-and-forget write here would let the next queued edit read the
-					// document this one has not committed yet.
-					await state.saveDocument(next, { history: false });
-					return;
-				}
-				// Hand the probed duration to the pure document layer: it patches only the
-				// clips of THIS asset that are still waiting for a real length (the
-				// pre-probe placeholder, or the extent-less clip a legacy v2 import mints),
-				// shifts what follows, and brings the modifiers along — anchoring the ones
-				// migration had to leave unanchored. Returns the document untouched when
-				// nothing is waiting, so there is nothing to guard here.
-				const next = applyProbedDuration(doc, assetId, known);
-				if (next !== doc) {
-					await state.saveDocument(next, { history: false });
-				}
+				const next = documentAfterProbedDuration(state.document, assetId, known, originatingProjectId);
+				if (!next) return;
+				// `history: false`: this is the probed duration being folded into the
+				// document on load, not something the user did — an undo landing on it would
+				// empty their timeline.
+				//
+				// Awaited, not `void`ed: the queue only serialises what it can see finish, so
+				// a fire-and-forget write would let the next queued edit read a document this
+				// one has not committed yet.
+				await state.saveDocument(next, { history: false });
 			});
 		},
 		[setSourceDuration, enqueueTimelineWrite],
diff --git a/src/lib/ai-edition/store/documentWriteAudit.test.ts b/src/lib/ai-edition/store/documentWriteAudit.test.ts
index 9a832b356..4a58c0fb6 100644
--- a/src/lib/ai-edition/store/documentWriteAudit.test.ts
+++ b/src/lib/ai-edition/store/documentWriteAudit.test.ts
@@ -126,7 +126,6 @@ const DECLARED: WritePath[] = [
 	// The probed duration folded into the document when the <video> loads. Twice:
 	// the first clip seed, and the backfill for clips still on a placeholder length.
 	w("src/components/ai-edition/NewEditorShell.tsx", "handleLoadedMetadata", "save", "automatic"),
-	w("src/components/ai-edition/NewEditorShell.tsx", "handleLoadedMetadata", "save", "automatic"),
 	// Renaming the project from the title field.
 	w("src/components/ai-edition/NewEditorShell.tsx", "handleRenameProject", "save", "gesture"),
 	// Ctrl+S / File > Save.

From e48d65d9f66f0cc681f14bd2bb7cadd32374fe64 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 16:03:07 +0800
Subject: [PATCH 05/14] style: apply biome formatting to the probed-duration
 changes

---
 .../ai-edition/NewEditorShell.probedDuration.test.tsx |  4 +++-
 src/components/ai-edition/NewEditorShell.tsx          | 11 +++++++++--
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx b/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
index ca1bf87a4..86cb96ed6 100644
--- a/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
+++ b/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
@@ -126,6 +126,8 @@ describe("documentAfterProbedDuration", () => {
 
 	it("writes nothing without a document or without assets", () => {
 		expect(documentAfterProbedDuration(null, "asset_1", 30, PROJECT)).toBeNull();
-		expect(documentAfterProbedDuration(emptyTimeline("asset_1", []), "asset_1", 30, PROJECT)).toBeNull();
+		expect(
+			documentAfterProbedDuration(emptyTimeline("asset_1", []), "asset_1", 30, PROJECT),
+		).toBeNull();
 	});
 });
diff --git a/src/components/ai-edition/NewEditorShell.tsx b/src/components/ai-edition/NewEditorShell.tsx
index bc0010658..c5ab65028 100644
--- a/src/components/ai-edition/NewEditorShell.tsx
+++ b/src/components/ai-edition/NewEditorShell.tsx
@@ -154,7 +154,9 @@ export function documentAfterProbedDuration(
 		if (!primaryAssetId || primaryAssetId !== assetId) return null;
 		const docWithDuration: AxcutDocument = {
 			...doc,
-			assets: doc.assets.map((a) => (a.id === primaryAssetId ? { ...a, durationSec: knownSec } : a)),
+			assets: doc.assets.map((a) =>
+				a.id === primaryAssetId ? { ...a, durationSec: knownSec } : a,
+			),
 		};
 		return replaceTimelineOp(
 			docWithDuration,
@@ -497,7 +499,12 @@ export function NewEditorShell() {
 			// from it lands after theirs and takes their edit with it.
 			void enqueueTimelineWrite(async () => {
 				const state = useProjectStore.getState();
-				const next = documentAfterProbedDuration(state.document, assetId, known, originatingProjectId);
+				const next = documentAfterProbedDuration(
+					state.document,
+					assetId,
+					known,
+					originatingProjectId,
+				);
 				if (!next) return;
 				// `history: false`: this is the probed duration being folded into the
 				// document on load, not something the user did — an undo landing on it would

From 3e840a1e85ebc413d9feaa9558c626349cf5edae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 19:59:32 +0800
Subject: [PATCH 06/14] fix(preview): mount the primary asset while the
 timeline is empty
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

With no clips to follow, the preview fell back to the whole asset list and
VirtualPreview mounted index 0 — `document.assets[0]`, which is not always the
primary. `handleLoadedMetadata` seeds the first clip against
`primaryAssetId ?? assets[0]` and, since the guard added here earlier, ignores an
event from any other asset. So the two disagreed exactly when they had to agree:
the mounted asset fired an event the seed refused, nothing else was ever mounted
(the index only moves for clips, and there are none), and the timeline stayed
empty for good.

A project whose first import is audio is that case. Audio never claims the empty
primary slot (document-service.addAsset), so `assets[0]` is the audio track and
the primary is the video added after it.

The empty-timeline fallback now mounts the resolved primary instead, and keeps
the old whole-list behaviour when that id resolves to nothing, so a stale primary
cannot leave the stage with no source at all.
---
 src/components/ai-edition/NewEditorShell.tsx |  4 ++
 src/components/ai-edition/Preview.test.tsx   | 40 +++++++++++++++++++-
 src/components/ai-edition/Preview.tsx        | 23 ++++++++++-
 3 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/src/components/ai-edition/NewEditorShell.tsx b/src/components/ai-edition/NewEditorShell.tsx
index c5ab65028..34810eea7 100644
--- a/src/components/ai-edition/NewEditorShell.tsx
+++ b/src/components/ai-edition/NewEditorShell.tsx
@@ -1606,6 +1606,10 @@ export function NewEditorShell() {
 									hasProject={hasProject}
 									hasAsset={hasAsset}
 									videoSources={videoSources}
+									// While the timeline is empty the preview mounts this asset rather
+									// than whichever one sorts first, so the clip `handleLoadedMetadata`
+									// seeds comes from the video it is sized against.
+									primaryAssetId={document?.project.primaryAssetId}
 									// Imported audio tracks (issue #350). `videoSources` already
 									// resolves a URL for every asset (audio included), so it doubles as
 									// the audio source list; VirtualPreview looks each track up by assetId.
diff --git a/src/components/ai-edition/Preview.test.tsx b/src/components/ai-edition/Preview.test.tsx
index db84828b8..d4810ce70 100644
--- a/src/components/ai-edition/Preview.test.tsx
+++ b/src/components/ai-edition/Preview.test.tsx
@@ -75,6 +75,7 @@ function source(id: string): VideoSource {
 function previewProps(props: {
 	videoSources: VideoSource[];
 	clips: AxcutClip[];
+	primaryAssetId?: string;
 	hasAsset?: boolean;
 	hasProject?: boolean;
 }) {
@@ -84,6 +85,7 @@ function previewProps(props: {
 				hasProject={props.hasProject ?? true}
 				hasAsset={props.hasAsset ?? true}
 				videoSources={props.videoSources}
+				primaryAssetId={props.primaryAssetId}
 				clips={props.clips}
 				seekTarget={null}
 				onTimeChange={vi.fn()}
@@ -157,12 +159,48 @@ describe("Preview follows the timeline, not the asset list", () => {
 	// The bootstrap path: `handleLoadedMetadata` mints the very first clip from
 	// the <video>'s own metadata, so a just-imported asset has to be mounted
 	// while nothing references it yet.
-	it("falls back to every asset while the timeline is empty", () => {
+	it("mounts the asset while the timeline is empty", () => {
 		renderPreview({ videoSources: [source("fresh_import")], clips: [] });
 
 		expect(canvas()).toHaveAttribute("data-sources", "fresh_import");
 	});
 
+	// A project whose first import was audio: audio never claims the empty primary
+	// slot, so `assets[0]` is the audio track and the primary is the video added
+	// after it. Only one source is mounted at a time and nothing on an empty
+	// timeline moves that index off 0 — so mounting the audio would hand
+	// `handleLoadedMetadata` an event for an asset it refuses to seed from, and the
+	// timeline would never get its first clip at all.
+	it("mounts the primary asset, not the one that sorts first", () => {
+		renderPreview({
+			videoSources: [source("bgm"), source("screen")],
+			primaryAssetId: "screen",
+			clips: [],
+		});
+
+		expect(canvas()).toHaveAttribute("data-sources", "screen");
+	});
+
+	// No primary recorded (a v1.7 project that predates the field): fall back to
+	// `assets[0]`, which is what the seed itself falls back to.
+	it("mounts the first asset when the project has no primary", () => {
+		renderPreview({ videoSources: [source("first"), source("second")], clips: [] });
+
+		expect(canvas()).toHaveAttribute("data-sources", "first");
+	});
+
+	// A primary id pointing at an asset with no source would otherwise mount
+	// nothing and collapse the stage to the empty state.
+	it("keeps every asset when the primary has no source", () => {
+		renderPreview({
+			videoSources: [source("a"), source("b")],
+			primaryAssetId: "gone",
+			clips: [],
+		});
+
+		expect(canvas()).toHaveAttribute("data-sources", "a,b");
+	});
+
 	// A clip landing on a healthy asset takes over the preview regardless of what
 	// happened to the asset that was mounted before it.
 	it("switches to the asset a new clip references", () => {
diff --git a/src/components/ai-edition/Preview.tsx b/src/components/ai-edition/Preview.tsx
index 3a1db9756..666af3ae7 100644
--- a/src/components/ai-edition/Preview.tsx
+++ b/src/components/ai-edition/Preview.tsx
@@ -23,6 +23,9 @@ interface PreviewProps {
 	hasProject: boolean;
 	hasAsset: boolean;
 	videoSources: VideoSource[];
+	/** `document.project.primaryAssetId`, when the project has one. Read only while
+	 *  the timeline is empty — see `previewSources`. */
+	primaryAssetId?: string;
 	/** Imported audio tracks and the (unfiltered) asset URLs they resolve to
 	 *  (issue #350). Passed straight through to VirtualPreview — unlike the video
 	 *  `previewSources` below, these are NOT narrowed to clip-referenced assets,
@@ -61,6 +64,7 @@ export function Preview({
 	hasProject,
 	hasAsset,
 	videoSources,
+	primaryAssetId,
 	audioTracks = [],
 	audioSources = [],
 	clips,
@@ -116,8 +120,23 @@ export function Preview({
 			const source = videoSources.find((s) => s.id === clip.assetId);
 			if (source) referenced.push(source);
 		}
-		return referenced.length > 0 ? referenced : videoSources;
-	}, [clips, videoSources]);
+		if (referenced.length > 0) return referenced;
+		// Empty timeline: mount the asset the seed is minted FOR, not whichever asset
+		// happens to sort first. `handleLoadedMetadata` sizes that first clip against
+		// `primaryAssetId ?? assets[0]` and ignores an event from any other asset, and
+		// only ONE source is ever mounted (`videoSources[sourceIndex]` in
+		// VirtualPreview, index 0 while nothing on the timeline moves it) — so mounting
+		// a non-primary asset here fires an event nothing acts on and the timeline
+		// stays empty for good. A project whose first import was audio is exactly that
+		// case: audio never claims the empty primary slot (document-service.addAsset),
+		// so `assets[0]` is the audio and the primary is the video added after it.
+		// `videoSources` mirrors `document.assets` in order, so index 0 is the same
+		// `assets[0]` the seed itself falls back to.
+		const primary = primaryAssetId
+			? videoSources.find((source) => source.id === primaryAssetId)
+			: videoSources[0];
+		return primary ? [primary] : videoSources;
+	}, [clips, videoSources, primaryAssetId]);
 
 	// ponytail: a media failure used to fall through to `EditorEmptyState`, and
 	// that is issue #395: ONE `error` event on the hidden <video> — including the

From e8762b64e045f82bc5a29d07164331f6a57aaee2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 19:59:43 +0800
Subject: [PATCH 07/14] test: run the probed-duration decision test in the
 default environment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The file opts into jsdom but never touches the DOM: it calls
`documentAfterProbedDuration` directly and asserts on the document it returns.
vitest.config.ts makes `node` the default for exactly this reason and the docblock
is the opt-in — 972ms of environment setup here bought nothing.
---
 .../ai-edition/NewEditorShell.probedDuration.test.tsx        | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx b/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
index 86cb96ed6..284cdf65e 100644
--- a/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
+++ b/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
@@ -1,9 +1,8 @@
-// @vitest-environment jsdom
 // The decision a `loadedmetadata` event makes, on its own.
 //
 // The event itself arrives through Preview -> PreviewCanvas -> VirtualPreview and a
-// real <video>, which jsdom never fires, so the component cannot be driven end to
-// end here. `documentAfterProbedDuration` is the part that decides what gets
+// real <video>, which no test environment here can decode, so the component cannot
+// be driven end to end. `documentAfterProbedDuration` is the part that decides what gets
 // written, and both guards below live in it: the queue the shell puts this write on
 // is what makes them necessary, because it puts real time between the event and the
 // write. The queue's own serialization is covered by useSequentialTimelineOps.test.

From 1b6423b4bb393d4fad5c5d984d5427e7483d5a88 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 22:09:19 +0800
Subject: [PATCH 08/14] feat(store): let a caller bound a document save that
 never answers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`saveDocument` awaits the bridge with no deadline of its own and, by contract,
never rejects — so a main process that stops answering leaves the promise pending
for the life of the renderer, and anything sequenced after it stops with it.

Two views of the same deadline: `waitForDocumentSaves` for a caller queued BEHIND
a save, `saveWithDeadline` for the one that started it. Both report `"timeout"`
rather than a value, because a write that has not answered says nothing about
what is on disk — the caller has to keep whatever state lets a later attempt
retry, not assume the write failed.
---
 src/lib/ai-edition/store/projectStore.test.ts |  65 +++++-
 src/lib/ai-edition/store/projectStore.ts      | 187 +++++++++++++-----
 2 files changed, 198 insertions(+), 54 deletions(-)

diff --git a/src/lib/ai-edition/store/projectStore.test.ts b/src/lib/ai-edition/store/projectStore.test.ts
index 2b75f0a04..175e9dc71 100644
--- a/src/lib/ai-edition/store/projectStore.test.ts
+++ b/src/lib/ai-edition/store/projectStore.test.ts
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { useProjectStore } from "./projectStore";
+import { saveWithDeadline, useProjectStore, waitForDocumentSaves } from "./projectStore";
 import { clearHistory, past, pushHistory } from "./undoStack";
 
 const bridgeMocks = vi.hoisted(() => ({
@@ -636,4 +636,67 @@ describe("useProjectStore", () => {
 			expect(useProjectStore.getState().document?.project.id).toBe("proj_other");
 		});
 	});
+
+	// The other half of the deadline. `waitForDocumentSaves` is for a caller queued
+	// BEHIND a save; this is for the one that started it, whose own `await` is what
+	// a chain or a queue gets sequenced on. Plain promises rather than the store, so
+	// nothing here leaves the in-flight counter raised.
+	describe("saveWithDeadline", () => {
+		it("passes the save's own answer through", async () => {
+			await expect(saveWithDeadline(Promise.resolve(true), 5_000)).resolves.toBe(true);
+			await expect(saveWithDeadline(Promise.resolve(false), 5_000)).resolves.toBe(false);
+		});
+
+		it("gives up on a save that never settles", async () => {
+			await expect(saveWithDeadline(new Promise(() => undefined), 10)).resolves.toBe("timeout");
+		});
+
+		it("clears the deadline once the save answers", async () => {
+			vi.useFakeTimers();
+			try {
+				await expect(saveWithDeadline(Promise.resolve(true), 10_000)).resolves.toBe(true);
+				expect(vi.getTimerCount()).toBe(0);
+			} finally {
+				vi.useRealTimers();
+			}
+		});
+	});
+
+	// `saveDocument` releases waiters from a `finally`, so a save that REJECTS is
+	// already covered. A bridge call that never settles at all runs no `finally`:
+	// without a deadline the in-flight counter stays above zero and every waiter
+	// parks for the life of the renderer, wedging the fresh-recording auto-zoom
+	// chain behind it. The stuck case is deliberately last in this file — its save
+	// never resolves, so it leaves the counter raised for anything after it.
+	describe("waitForDocumentSaves", () => {
+		it("resolves idle immediately when nothing is in flight", async () => {
+			await expect(waitForDocumentSaves(5_000)).resolves.toBe("idle");
+		});
+
+		it("resolves idle once an in-flight save settles", async () => {
+			useProjectStore.setState({ projectId: "proj_test", document: sampleDoc, dirty: true });
+			let release!: () => void;
+			bridgeMocks.save.mockReturnValue(
+				new Promise((resolve) => {
+					release = () => resolve({ success: true, document: sampleDoc });
+				}),
+			);
+			const inFlight = useProjectStore.getState().saveDocument(sampleDoc, { history: false });
+			const wait = waitForDocumentSaves(5_000);
+			release();
+			await inFlight;
+			await expect(wait).resolves.toBe("idle");
+		});
+
+		it("gives up with a timeout when a save never settles", async () => {
+			useProjectStore.setState({ projectId: "proj_test", document: sampleDoc, dirty: true });
+			bridgeMocks.save.mockReturnValue(new Promise(() => undefined));
+			void useProjectStore.getState().saveDocument(sampleDoc, { history: false });
+
+			await expect(waitForDocumentSaves(10)).resolves.toBe("timeout");
+			// A timed-out waiter takes itself out of the queue, so the next caller gets
+			// its own deadline rather than inheriting a stale resolver.
+			await expect(waitForDocumentSaves(10)).resolves.toBe("timeout");
+		});
+	});
 });
diff --git a/src/lib/ai-edition/store/projectStore.ts b/src/lib/ai-edition/store/projectStore.ts
index fd47da9cc..ec60b230b 100644
--- a/src/lib/ai-edition/store/projectStore.ts
+++ b/src/lib/ai-edition/store/projectStore.ts
@@ -10,6 +10,82 @@ import { type AxcutAsset, type AxcutDocument, createAudioTrack, documentSchema }
 import { probeAudioDuration, probeVideoDimensions } from "../timeline/duration";
 import { clearHistory, currentWriteEpoch, pushHistory } from "./undoStack";
 
+let documentSavesInFlight = 0;
+const documentSavesIdle: Array<() => void> = [];
+
+/** Outcome of `waitForDocumentSaves`: saves drained, or the wait gave up. */
+export type DocumentSavesWait = "idle" | "timeout";
+
+/** How long a waiter sits before it stops believing a save will ever settle. */
+export const DOCUMENT_SAVES_WAIT_TIMEOUT_MS = 10_000;
+
+function beginDocumentSave() {
+	documentSavesInFlight += 1;
+}
+
+function endDocumentSave() {
+	documentSavesInFlight = Math.max(0, documentSavesInFlight - 1);
+	if (documentSavesInFlight > 0) return;
+	while (documentSavesIdle.length > 0) {
+		documentSavesIdle.shift()?.();
+	}
+}
+
+/**
+ * `"idle"` once no `saveDocument` is still waiting on IPC or installing its
+ * result; `"timeout"` if that has not happened within `timeoutMs`.
+ *
+ * The timeout is not decoration. `saveDocument` decrements its counter in a
+ * `finally`, so a rejected save still releases waiters — but a bridge call that
+ * never settles at all runs no `finally`, leaves the counter above zero, and
+ * would park every waiter here forever. Callers must treat `"timeout"` as "I do
+ * not know whether that save landed" and abandon the attempt, keeping whatever
+ * pending state lets a later attempt retry. Reporting it as `"idle"` would be a
+ * lie about disk state, and is how a queued write ends up racing a stuck one.
+ */
+export function waitForDocumentSaves(
+	timeoutMs: number = DOCUMENT_SAVES_WAIT_TIMEOUT_MS,
+): Promise<DocumentSavesWait> {
+	if (documentSavesInFlight === 0) return Promise.resolve("idle");
+	return new Promise((resolve) => {
+		const settle = (outcome: DocumentSavesWait) => {
+			const at = documentSavesIdle.indexOf(waiter);
+			if (at >= 0) documentSavesIdle.splice(at, 1);
+			clearTimeout(timer);
+			resolve(outcome);
+		};
+		const waiter = () => settle("idle");
+		const timer = setTimeout(() => settle("timeout"), timeoutMs);
+		documentSavesIdle.push(waiter);
+	});
+}
+
+/**
+ * `saveDocument`'s own answer, or `"timeout"` if it has not produced one within
+ * `timeoutMs`.
+ *
+ * The companion to {@link waitForDocumentSaves}, for the caller that started the
+ * save rather than one waiting behind it: a bridge call that never settles leaves
+ * this promise pending forever, and anything sequenced after it — a queue, a
+ * chain of later callbacks — stops with it. `"timeout"` carries the same meaning
+ * here as there: the write may still land, so treat the document as unknown and
+ * keep whatever state lets a later attempt retry.
+ */
+export async function saveWithDeadline(
+	save: Promise<boolean>,
+	timeoutMs: number = DOCUMENT_SAVES_WAIT_TIMEOUT_MS,
+): Promise<boolean | "timeout"> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const deadline = new Promise<"timeout">((resolve) => {
+		timer = setTimeout(() => resolve("timeout"), timeoutMs);
+	});
+	try {
+		return await Promise.race([save, deadline]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
 // ponytail: thin Zustand wrapper over the native-bridge client. Keeps the
 // current project + revision counter in renderer memory; mutations round-trip
 // through the main process via the bridge so disk state stays authoritative.
@@ -469,61 +545,66 @@ export const useProjectStore = create<ProjectState>((set, get) => ({
 	},
 
 	async saveDocument(document, opts) {
-		// Read BEFORE the await, while `get().document` is still the pre-edit one.
-		// This is where undo history actually comes from: the editor writes through
-		// `saveDocument` for every user edit -- add a region, delete one, rename the
-		// project, every timeline op -- and `setDocument` is reserved for the handful
-		// of live/optimistic paths. Recording only in `setDocument` left `past` empty
-		// for everything the user does, so Ctrl+Z was a no-op (#433).
-		const base = historyBaseFor(opts, get().document);
-		// Read alongside it, and for the same reason: both describe the world this write
-		// is building on, and the await is where that world can change underneath it.
-		const epoch = currentWriteEpoch();
+		beginDocumentSave();
 		try {
-			const result = await nativeBridgeClient.aiEdition.save(document);
-			if (!result.success || !result.document) {
-				throw new Error(result.error ?? "Failed to save project");
+			// Read BEFORE the await, while `get().document` is still the pre-edit one.
+			// This is where undo history actually comes from: the editor writes through
+			// `saveDocument` for every user edit -- add a region, delete one, rename the
+			// project, every timeline op -- and `setDocument` is reserved for the handful
+			// of live/optimistic paths. Recording only in `setDocument` left `past` empty
+			// for everything the user does, so Ctrl+Z was a no-op (#433).
+			const base = historyBaseFor(opts, get().document);
+			// Read alongside it, and for the same reason: both describe the world this write
+			// is building on, and the await is where that world can change underneath it.
+			const epoch = currentWriteEpoch();
+			try {
+				const result = await nativeBridgeClient.aiEdition.save(document);
+				if (!result.success || !result.document) {
+					throw new Error(result.error ?? "Failed to save project");
+				}
+				// The undo wins, and this write is dropped -- store and history both. It was
+				// in flight when the user pressed Ctrl+Z (or switched projects), so its document
+				// is the one they just asked to leave: installing it reverted the undo on screen,
+				// and recording it put a FORWARD state on `past` and cleared `future`, so the
+				// redo they had just earned was gone.
+				//
+				// Dropped rather than reverted, because reverting is not this write's to do: the
+				// bytes are already on disk, and it is the undo's own persist -- issued from
+				// `useUndoRedoShortcuts`'s `onAfter` the moment it ran, so ordered after this one
+				// on the same IPC channel -- that puts the restored document back over them.
+				// `dirty` is deliberately left set for exactly that reason.
+				if (currentWriteEpoch() !== epoch) return false;
+				const parsed = parseDocument(result.document);
+				set({
+					document: parsed,
+					revision: get().revision + 1,
+					dirty: false,
+					lastSavedAt: new Date(),
+				});
+				// Recorded HERE, below the write, and not above it. `saveDocument` resolves
+				// false on a handled failure (a read-only project) and callers read that as
+				// "the edit did not happen". Recording first left `past` holding a snapshot
+				// identical to the live document and `future` wiped, so the next Ctrl+Z
+				// visibly did nothing and redo was gone -- #433's own symptom, re-created by
+				// the fix for it. Nothing between the `set` above and this line awaits, so no
+				// undo can observe the half-applied state.
+				recordHistory(base, document, opts);
+				return true;
+			} catch (error) {
+				// Logged as well as toasted: a toast is gone in five seconds, and "my edit
+				// disappeared" gets reported much later than that.
+				console.error("[project] failed to save document:", error);
+				toast.error(toastText("editor", "project.failedToSave"), {
+					description: error instanceof Error ? error.message : String(error),
+				});
+				// `dirty` is deliberately left alone. It is the only input to the
+				// `beforeunload` guard and to `setHasUnsavedChanges`, so clearing it here
+				// would let the window close without a prompt on the one path where there is
+				// definitely something unsaved.
+				return false;
 			}
-			// The undo wins, and this write is dropped -- store and history both. It was
-			// in flight when the user pressed Ctrl+Z (or switched projects), so its document
-			// is the one they just asked to leave: installing it reverted the undo on screen,
-			// and recording it put a FORWARD state on `past` and cleared `future`, so the
-			// redo they had just earned was gone.
-			//
-			// Dropped rather than reverted, because reverting is not this write's to do: the
-			// bytes are already on disk, and it is the undo's own persist -- issued from
-			// `useUndoRedoShortcuts`'s `onAfter` the moment it ran, so ordered after this one
-			// on the same IPC channel -- that puts the restored document back over them.
-			// `dirty` is deliberately left set for exactly that reason.
-			if (currentWriteEpoch() !== epoch) return false;
-			const parsed = parseDocument(result.document);
-			set({
-				document: parsed,
-				revision: get().revision + 1,
-				dirty: false,
-				lastSavedAt: new Date(),
-			});
-			// Recorded HERE, below the write, and not above it. `saveDocument` resolves
-			// false on a handled failure (a read-only project) and callers read that as
-			// "the edit did not happen". Recording first left `past` holding a snapshot
-			// identical to the live document and `future` wiped, so the next Ctrl+Z
-			// visibly did nothing and redo was gone -- #433's own symptom, re-created by
-			// the fix for it. Nothing between the `set` above and this line awaits, so no
-			// undo can observe the half-applied state.
-			recordHistory(base, document, opts);
-			return true;
-		} catch (error) {
-			// Logged as well as toasted: a toast is gone in five seconds, and "my edit
-			// disappeared" gets reported much later than that.
-			console.error("[project] failed to save document:", error);
-			toast.error(toastText("editor", "project.failedToSave"), {
-				description: error instanceof Error ? error.message : String(error),
-			});
-			// `dirty` is deliberately left alone. It is the only input to the
-			// `beforeunload` guard and to `setHasUnsavedChanges`, so clearing it here
-			// would let the window close without a prompt on the one path where there is
-			// definitely something unsaved.
-			return false;
+		} finally {
+			endDocumentSave();
 		}
 	},
 

From b336c9484cab71b654fe095d93226a4d243183c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 22:09:29 +0800
Subject: [PATCH 09/14] refactor(timeline): one auto-zoom collect/append path
 for both callers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The wand builds suggestions from cursor telemetry and appends them; the
fresh-recording import is about to need exactly that. Two copies would drift —
the anchoring in particular, which has to run against the same document the write
is built from, or the regions land on a timeline that no longer exists.

So the collect and the append move into `apply-auto-zooms.ts` and the wand's
`addZoomsBulk` calls them. It keeps reading the document from the store rather
than from the render closure; only the region-building moves.
---
 .../document/applyProbedDuration.test.ts      |  24 ++++
 src/lib/ai-edition/document/timeline.ts       |   4 +-
 src/lib/ai-edition/store/useTimeline.ts       |  29 +----
 .../timeline/apply-auto-zooms.test.ts         | 112 ++++++++++++++++++
 .../ai-edition/timeline/apply-auto-zooms.ts   |  68 +++++++++++
 5 files changed, 211 insertions(+), 26 deletions(-)
 create mode 100644 src/lib/ai-edition/timeline/apply-auto-zooms.test.ts
 create mode 100644 src/lib/ai-edition/timeline/apply-auto-zooms.ts

diff --git a/src/lib/ai-edition/document/applyProbedDuration.test.ts b/src/lib/ai-edition/document/applyProbedDuration.test.ts
index 0147f5f69..64081a666 100644
--- a/src/lib/ai-edition/document/applyProbedDuration.test.ts
+++ b/src/lib/ai-edition/document/applyProbedDuration.test.ts
@@ -89,6 +89,30 @@ describe("applyProbedDuration — the v1.7 import gap", () => {
 		expect(next.timeline.clips[0].timelineEndSec).toBe(12);
 	});
 
+	it("overwrites a leftover 60s fallback on the asset when the real duration arrives", () => {
+		const doc = documentSchema.parse(migrateProjectDataToAxcutDocument(legacyProjectWithZoom()));
+		const assetId = doc.assets[0].id;
+		const seeded: AxcutDocument = {
+			...doc,
+			assets: doc.assets.map((asset) =>
+				asset.id === assetId ? { ...asset, durationSec: PLACEHOLDER_DURATION_SEC } : asset,
+			),
+			timeline: {
+				...doc.timeline,
+				clips: [
+					{
+						...doc.timeline.clips[0],
+						sourceEndSec: PLACEHOLDER_DURATION_SEC,
+						timelineEndSec: PLACEHOLDER_DURATION_SEC,
+					},
+				],
+			},
+		};
+		const next = applyProbedDuration(seeded, assetId, 90);
+		expect(next.timeline.clips[0].sourceEndSec).toBe(90);
+		expect(next.assets[0].durationSec).toBe(90);
+	});
+
 	it("leaves a clip the user has already trimmed alone", () => {
 		const doc = documentSchema.parse(migrateProjectDataToAxcutDocument(legacyProjectWithZoom()));
 		const assetId = doc.assets[0].id;
diff --git a/src/lib/ai-edition/document/timeline.ts b/src/lib/ai-edition/document/timeline.ts
index 8ae93098f..870b2ac94 100644
--- a/src/lib/ai-edition/document/timeline.ts
+++ b/src/lib/ai-edition/document/timeline.ts
@@ -539,9 +539,7 @@ export function applyProbedDuration(
 	const withClips: AxcutDocument = {
 		...document,
 		assets: document.assets.map((asset) =>
-			asset.id === assetId && asset.durationSec == null
-				? { ...asset, durationSec: durationSec }
-				: asset,
+			asset.id === assetId ? { ...asset, durationSec: durationSec } : asset,
 		),
 		timeline: { ...document.timeline, clips: nextClips },
 	};
diff --git a/src/lib/ai-edition/store/useTimeline.ts b/src/lib/ai-edition/store/useTimeline.ts
index 860b9f13f..4ab744f7c 100644
--- a/src/lib/ai-edition/store/useTimeline.ts
+++ b/src/lib/ai-edition/store/useTimeline.ts
@@ -28,6 +28,7 @@ import {
 	withClipsChanged,
 } from "../document/timeline";
 import type { AxcutAudioTrack, AxcutClipCropRegion, AxcutDocument } from "../schema";
+import { appendAutoZoomSuggestions } from "../timeline/apply-auto-zooms";
 import { hasAnyClipWithCamera } from "../timeline/camera";
 import { probeAudioDuration, probeVideoDimensions, probeVideoDuration } from "../timeline/duration";
 import {
@@ -343,29 +344,11 @@ export function useTimeline() {
 			// reason as `applyClipEdit`, `setTrimEntries` and `insertClipAt`.
 			const doc = useProjectStore.getState().document;
 			if (!doc || suggestions.length === 0) return 0;
-			const anchored = suggestions.flatMap((s) =>
-				anchorRegionsWithDerivedMs(
-					[
-						{
-							id: createId("zoom"),
-							startMs: Math.round(s.span.start),
-							endMs: Math.round(s.span.end),
-							depth: 3 as const,
-							focus: { cx: s.focus.cx, cy: s.focus.cy },
-							focusMode: "auto" as const,
-						},
-					],
-					// Anchored against the SAME document the write is built from: anchoring
-					// on the stale clips and saving the fresh document would place regions
-					// against a timeline that no longer exists.
-					doc.timeline.clips,
-					() => createId("zoom"),
-				),
-			);
-			const next: AxcutDocument = {
-				...doc,
-				zoomRanges: [...doc.zoomRanges, ...anchored] as AxcutDocument["zoomRanges"],
-			};
+			// One append shared with the fresh-recording import path, so the wand and the
+			// import cannot drift apart. It anchors against the SAME document the write is
+			// built from: anchoring on stale clips and saving the fresh document would
+			// place the regions against a timeline that no longer exists.
+			const next = appendAutoZoomSuggestions(doc, suggestions);
 			if (!(await saveDocument(next, { history: true }))) return 0;
 			return suggestions.length;
 		},
diff --git a/src/lib/ai-edition/timeline/apply-auto-zooms.test.ts b/src/lib/ai-edition/timeline/apply-auto-zooms.test.ts
new file mode 100644
index 000000000..c00124f19
--- /dev/null
+++ b/src/lib/ai-edition/timeline/apply-auto-zooms.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import type { CursorTelemetryPoint } from "@/components/video-editor/types";
+import { type AxcutDocument, createEmptyDocument } from "../schema";
+import {
+	appendAutoZoomSuggestions,
+	collectAutoZoomSuggestionsForDocument,
+} from "./apply-auto-zooms";
+
+function dwell(
+	centerMs: number,
+	cx: number,
+	cy: number,
+	count = 6,
+	spanMs = 900,
+): CursorTelemetryPoint[] {
+	const step = spanMs / (count - 1);
+	return Array.from({ length: count }, (_, i) => ({
+		timeMs: centerMs - spanMs / 2 + i * step,
+		cx,
+		cy,
+	}));
+}
+
+function documentWithClip(durationSec = 10): AxcutDocument {
+	const doc = createEmptyDocument({ projectId: "p1", title: "Recording" });
+	return {
+		...doc,
+		assets: [
+			{
+				id: "asset_1",
+				kind: "video",
+				label: "rec.mp4",
+				originalPath: "C:\\recordings\\rec.mp4",
+				cameraTrack: null,
+				durationSec,
+			},
+		],
+		project: { ...doc.project, primaryAssetId: "asset_1" },
+		timeline: {
+			...doc.timeline,
+			clips: [
+				{
+					id: "clip_1",
+					assetId: "asset_1",
+					sourceStartSec: 0,
+					sourceEndSec: durationSec,
+					timelineStartSec: 0,
+					timelineEndSec: durationSec,
+					wordRefs: [],
+					origin: "system",
+					reason: "",
+				},
+			],
+		},
+	};
+}
+
+describe("collectAutoZoomSuggestionsForDocument", () => {
+	it("builds suggestions from the asset's cursor sidecar", async () => {
+		const document = documentWithClip();
+		const suggestions = await collectAutoZoomSuggestionsForDocument(document, async () =>
+			dwell(4000, 0.4, 0.6),
+		);
+		expect(suggestions).toHaveLength(1);
+		expect(suggestions[0].span.start).toBe(3000);
+		expect(suggestions[0].span.end).toBe(5000);
+		expect(suggestions[0].focus.cx).toBeCloseTo(0.4, 5);
+	});
+
+	it("asks for telemetry on the asset path, not a file URL", async () => {
+		const document = documentWithClip();
+		const paths: string[] = [];
+		await collectAutoZoomSuggestionsForDocument(document, async (videoPath) => {
+			paths.push(videoPath);
+			return [];
+		});
+		expect(paths).toEqual(["C:\\recordings\\rec.mp4"]);
+	});
+
+	it("returns nothing without a clip window", async () => {
+		const document = createEmptyDocument({ projectId: "p1", title: "Empty" });
+		const suggestions = await collectAutoZoomSuggestionsForDocument(document, async () =>
+			dwell(1000, 0.5, 0.5),
+		);
+		expect(suggestions).toEqual([]);
+	});
+});
+
+describe("appendAutoZoomSuggestions", () => {
+	it("leaves the document unchanged when there is nothing to add", () => {
+		const document = documentWithClip();
+		expect(appendAutoZoomSuggestions(document, [])).toBe(document);
+	});
+
+	it("anchors each suggestion onto the clip", () => {
+		const document = documentWithClip();
+		const next = appendAutoZoomSuggestions(
+			document,
+			[{ span: { start: 3000, end: 5000 }, focus: { cx: 0.4, cy: 0.6 } }],
+			(prefix) => `${prefix}_fixed`,
+		);
+		expect(next).not.toBe(document);
+		expect(next.zoomRanges).toHaveLength(1);
+		expect(next.zoomRanges[0]).toMatchObject({
+			startMs: 3000,
+			endMs: 5000,
+			depth: 3,
+			focusMode: "auto",
+			clipId: "clip_1",
+		});
+	});
+});
diff --git a/src/lib/ai-edition/timeline/apply-auto-zooms.ts b/src/lib/ai-edition/timeline/apply-auto-zooms.ts
new file mode 100644
index 000000000..f1f1c82c0
--- /dev/null
+++ b/src/lib/ai-edition/timeline/apply-auto-zooms.ts
@@ -0,0 +1,68 @@
+// Shared auto-zoom apply path: the HUD toggle / fresh-recording import and the
+// timeline wand both end here. Suggestion math stays in zoom-suggestions.ts;
+// this file only collects per-asset telemetry and appends the resulting regions.
+
+import type { CursorTelemetryPoint } from "@/components/video-editor/types";
+import { createId } from "../document/ids";
+import type { AxcutDocument } from "../schema";
+import { anchorRegionsWithDerivedMs } from "./timelineMap";
+import { type AutoZoomSuggestion, buildAutoZoomSuggestionsForClips } from "./zoom-suggestions";
+
+export const AUTO_ZOOM_DEFAULT_DURATION_MS = 2000;
+
+export async function collectAutoZoomSuggestionsForDocument(
+	document: AxcutDocument,
+	getTelemetry: (videoPath: string) => Promise<CursorTelemetryPoint[] | null | undefined>,
+): Promise<AutoZoomSuggestion[]> {
+	const existingRegions = document.zoomRanges.map((region) => ({
+		startMs: region.startMs,
+		endMs: region.endMs,
+	}));
+	const assetsWithClips = document.assets.filter(
+		(asset) =>
+			asset.kind === "video" &&
+			asset.originalPath &&
+			document.timeline.clips.some((clip) => clip.assetId === asset.id),
+	);
+	const perSource = await Promise.all(
+		assetsWithClips.map(async (asset) => {
+			const telemetry = (await getTelemetry(asset.originalPath)) ?? [];
+			return buildAutoZoomSuggestionsForClips({
+				cursorTelemetry: telemetry,
+				assetId: asset.id,
+				clips: document.timeline.clips,
+				existingRegions,
+				defaultDurationMs: AUTO_ZOOM_DEFAULT_DURATION_MS,
+			});
+		}),
+	);
+	return perSource.flat();
+}
+
+export function appendAutoZoomSuggestions(
+	document: AxcutDocument,
+	suggestions: AutoZoomSuggestion[],
+	makeId: (prefix: string) => string = createId,
+): AxcutDocument {
+	if (suggestions.length === 0) return document;
+	const anchored = suggestions.flatMap((suggestion) =>
+		anchorRegionsWithDerivedMs(
+			[
+				{
+					id: makeId("zoom"),
+					startMs: Math.round(suggestion.span.start),
+					endMs: Math.round(suggestion.span.end),
+					depth: 3 as const,
+					focus: { cx: suggestion.focus.cx, cy: suggestion.focus.cy },
+					focusMode: "auto" as const,
+				},
+			],
+			document.timeline.clips,
+			() => makeId("zoom"),
+		),
+	);
+	return {
+		...document,
+		zoomRanges: [...document.zoomRanges, ...anchored] as AxcutDocument["zoomRanges"],
+	};
+}

From 7986d28a7a0f3c02c0f2e1fbf8df255d3a8fbfd4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 22:09:47 +0800
Subject: [PATCH 10/14] feat(recording): suggest cursor-dwell zooms for a
 freshly imported take

1.5 suggested zooms when a fresh recording opened in the editor. Current main
still has the wand, but HUD import only seeded a clip, so a new take landed
un-zoomed (issue #539). This restores that pass on the current document model.
Zooms stay editor regions; they are not baked into the MP4.

The pass is marked pending at import and applied once the document is ready,
through the same collect/append the wand uses. What makes it safe to run behind a
user who is already editing:

- Contention means exit, not rebase. If the document moved while the suggestion
  pass ran, the attempt is working from a snapshot that is already history;
  recomputing onto the newer one just races the writer that produced it. The
  attempt is dropped with pending still set, and the delayed retries run against
  a settled document instead.
- A wait or a write that times out has told us nothing about what is on disk, so
  pending stays set rather than being cleared on an assumption.
- A take recorded with the system cursor is never marked pending: there is no
  overlay telemetry to read dwells from.
---
 .../ai-edition/recordingImport.test.ts        | 578 +++++++++++++++++-
 src/components/ai-edition/recordingImport.ts  | 309 +++++++++-
 src/native/browserShim.ts                     |   2 +
 3 files changed, 878 insertions(+), 11 deletions(-)

diff --git a/src/components/ai-edition/recordingImport.test.ts b/src/components/ai-edition/recordingImport.test.ts
index 4faea3d5c..ceb7590d6 100644
--- a/src/components/ai-edition/recordingImport.test.ts
+++ b/src/components/ai-edition/recordingImport.test.ts
@@ -5,7 +5,13 @@ import { type AxcutDocument, createEmptyDocument } from "@/lib/ai-edition/schema
 import { useProjectStore } from "@/lib/ai-edition/store/projectStore";
 import { undo } from "@/lib/ai-edition/store/undo";
 import { clearHistory, past } from "@/lib/ai-edition/store/undoStack";
-import { importPendingRecording } from "./recordingImport";
+import {
+	applyPendingFreshRecordingAutoZooms,
+	consumeFreshRecordingAutoZoomPending,
+	importPendingRecording,
+	markFreshRecordingAutoZoomPending,
+	maybeSaveFreshRecordingAutoZooms,
+} from "./recordingImport";
 
 // The first describe stubs the store actions, so the bridge is never reached
 // there. The second one runs the REAL store against these, which is the only way
@@ -14,11 +20,26 @@ const bridge = vi.hoisted(() => ({
 	create: vi.fn(),
 	addAsset: vi.fn(),
 	save: vi.fn(),
+	getTelemetry: vi.fn(async () => []),
+}));
+vi.mock("@/native/client", () => ({
+	nativeBridgeClient: {
+		aiEdition: bridge,
+		cursor: { getTelemetry: bridge.getTelemetry },
+	},
 }));
-vi.mock("@/native/client", () => ({ nativeBridgeClient: { aiEdition: bridge } }));
 
-const createProject = vi.fn(async () => undefined);
-const addAsset = vi.fn(async () => null);
+// Typed to the store's own action signatures rather than cast through `any`:
+// tsconfig.test.json typechecks this file in CI, so a stub that drifts from the
+// contract it stands in for should fail there instead of passing silently.
+// `createProject` returns a document because the real one does — the import path
+// discards it, but a stub that lies about the shape is a stub that stops catching
+// the day something starts reading it.
+const createProject = vi.fn(
+	async (title: string): Promise<AxcutDocument> =>
+		createEmptyDocument({ projectId: "proj_stub", title }),
+);
+const addAsset = vi.fn(async (): Promise<null> => null);
 const replaceTimeline = vi.fn(async () => undefined);
 
 // Read before anything stubs them: the first describe replaces these actions on the
@@ -27,11 +48,19 @@ const realActions = {
 	createProject: useProjectStore.getState().createProject,
 	addAsset: useProjectStore.getState().addAsset,
 	replaceTimeline: useProjectStore.getState().replaceTimeline,
+	saveDocument: useProjectStore.getState().saveDocument,
 };
 
 /** Stands in for the main-process recording slot: one value, set and read. */
-function stubElectronApi(screenVideoPath: string | null) {
-	let session = screenVideoPath ? { screenVideoPath, createdAt: 0 } : null;
+function stubElectronApi(
+	screenVideoPath: string | null,
+	cursorCaptureMode: "editable-overlay" | "system" = "editable-overlay",
+) {
+	let session: {
+		screenVideoPath: string;
+		createdAt: number;
+		cursorCaptureMode: "editable-overlay" | "system";
+	} | null = screenVideoPath ? { screenVideoPath, createdAt: 0, cursorCaptureMode } : null;
 	const api = {
 		getCurrentRecordingSession: vi.fn(async () =>
 			session ? { success: true, session } : { success: false },
@@ -49,12 +78,11 @@ function stubElectronApi(screenVideoPath: string | null) {
 describe("importPendingRecording", () => {
 	beforeEach(() => {
 		vi.clearAllMocks();
+		consumeFreshRecordingAutoZoomPending();
 		useProjectStore.setState({
 			document: null,
-			// biome-ignore lint/suspicious/noExplicitAny: partial action stubs, the rest of the store is untouched
-			createProject: createProject as any,
-			// biome-ignore lint/suspicious/noExplicitAny: partial action stubs, the rest of the store is untouched
-			addAsset: addAsset as any,
+			createProject,
+			addAsset,
 			replaceTimeline,
 		});
 	});
@@ -144,6 +172,7 @@ describe("what the recording import leaves on the undo stack", () => {
 
 	beforeEach(() => {
 		vi.clearAllMocks();
+		consumeFreshRecordingAutoZoomPending();
 		useProjectStore.getState().clear();
 		useProjectStore.setState(realActions);
 		clearHistory();
@@ -187,3 +216,532 @@ describe("what the recording import leaves on the undo stack", () => {
 		expect(useProjectStore.getState().document?.timeline.clips).toHaveLength(1);
 	});
 });
+
+function dwell(
+	centerMs: number,
+	cx: number,
+	cy: number,
+	count = 6,
+	spanMs = 900,
+): Array<{ timeMs: number; cx: number; cy: number }> {
+	const step = spanMs / (count - 1);
+	return Array.from({ length: count }, (_, i) => ({
+		timeMs: centerMs - spanMs / 2 + i * step,
+		cx,
+		cy,
+	}));
+}
+
+function documentWithClip(durationSec = 10): AxcutDocument {
+	const doc = createEmptyDocument({ projectId: "p_autozoom", title: "Recording" });
+	return {
+		...doc,
+		assets: [
+			{
+				id: "asset_1",
+				kind: "video",
+				label: "rec.mp4",
+				originalPath: "C:\\recordings\\rec.mp4",
+				cameraTrack: null,
+				durationSec,
+			},
+		],
+		project: { ...doc.project, primaryAssetId: "asset_1" },
+		timeline: {
+			...doc.timeline,
+			clips: [
+				{
+					id: "clip_1",
+					assetId: "asset_1",
+					sourceStartSec: 0,
+					sourceEndSec: durationSec,
+					timelineStartSec: 0,
+					timelineEndSec: durationSec,
+					wordRefs: [],
+					origin: "system",
+					reason: "",
+				},
+			],
+		},
+	};
+}
+
+describe("fresh-recording auto-zoom", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		consumeFreshRecordingAutoZoomPending();
+		useProjectStore.setState({
+			document: null,
+			createProject,
+			addAsset,
+			replaceTimeline,
+		});
+	});
+
+	it("marks a successful import as waiting when the document is not ready yet", async () => {
+		stubElectronApi("C:\\recordings\\recording-1.mp4");
+		await importPendingRecording();
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(true);
+	});
+
+	it("does not mark when nothing is waiting", async () => {
+		stubElectronApi(null);
+		await importPendingRecording();
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(false);
+	});
+
+	// A system-cursor take writes no `.cursor.json`, so there is never a dwell to
+	// find. Marking it pending anyway left the flag set for the life of the window
+	// and burned all three retries on an empty sidecar.
+	it("does not mark a system-cursor take as waiting", async () => {
+		stubElectronApi("C:\\recordings\\recording-1.mp4", "system");
+		await importPendingRecording();
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(false);
+	});
+
+	it("still marks an editable-cursor take from the same import path", async () => {
+		stubElectronApi("C:\\recordings\\recording-1.mp4", "editable-overlay");
+		await importPendingRecording();
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(true);
+	});
+
+	it("applies cursor-dwell zooms once, after duration is known", async () => {
+		markFreshRecordingAutoZoomPending();
+		const next = await applyPendingFreshRecordingAutoZooms(documentWithClip(), {
+			enabled: true,
+			getTelemetry: async () => dwell(4000, 0.4, 0.6),
+			createId: (prefix) => `${prefix}_test`,
+		});
+		expect(next.zoomRanges).toHaveLength(1);
+		expect(next.zoomRanges[0]).toMatchObject({
+			startMs: 3000,
+			endMs: 5000,
+			focusMode: "auto",
+		});
+		expect(await applyPendingFreshRecordingAutoZooms(next, { enabled: true })).toBe(next);
+	});
+
+	it("skips when the HUD toggle is off", async () => {
+		markFreshRecordingAutoZoomPending();
+		const document = documentWithClip();
+		const next = await applyPendingFreshRecordingAutoZooms(document, {
+			enabled: false,
+			getTelemetry: async () => dwell(4000, 0.5, 0.5),
+		});
+		expect(next).toBe(document);
+		expect(next.zoomRanges).toEqual([]);
+	});
+
+	it("keeps the pending flag when the sidecar is still empty, then applies on retry", async () => {
+		markFreshRecordingAutoZoomPending();
+		const document = documentWithClip();
+		const first = await applyPendingFreshRecordingAutoZooms(document, {
+			enabled: true,
+			getTelemetry: async () => [],
+		});
+		expect(first).toBe(document);
+		const next = await applyPendingFreshRecordingAutoZooms(document, {
+			enabled: true,
+			getTelemetry: async () => dwell(4000, 0.4, 0.6),
+			createId: (prefix) => `${prefix}_retry`,
+		});
+		expect(next.zoomRanges).toHaveLength(1);
+		expect(await applyPendingFreshRecordingAutoZooms(next, { enabled: true })).toBe(next);
+	});
+
+	it("keeps the pending flag when clips are not on the document yet", async () => {
+		markFreshRecordingAutoZoomPending();
+		const document = createEmptyDocument({ projectId: "p_empty", title: "Recording" });
+		const next = await applyPendingFreshRecordingAutoZooms(document, {
+			enabled: true,
+			getTelemetry: async () => dwell(4000, 0.5, 0.5),
+		});
+		expect(next).toBe(document);
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(true);
+	});
+
+	it("keeps pending when telemetry is present but no dwell has landed yet", async () => {
+		markFreshRecordingAutoZoomPending();
+		const document = documentWithClip();
+		const moving = Array.from({ length: 8 }, (_, i) => ({
+			timeMs: 1000 + i * 80,
+			cx: 0.2 + i * 0.08,
+			cy: 0.3,
+		}));
+		const first = await applyPendingFreshRecordingAutoZooms(document, {
+			enabled: true,
+			getTelemetry: async () => moving,
+		});
+		expect(first).toBe(document);
+		const next = await applyPendingFreshRecordingAutoZooms(document, {
+			enabled: true,
+			getTelemetry: async () => dwell(4000, 0.4, 0.6),
+			createId: (prefix) => `${prefix}_late`,
+		});
+		expect(next.zoomRanges).toHaveLength(1);
+	});
+
+	it("keeps pending when telemetry read throws", async () => {
+		markFreshRecordingAutoZoomPending();
+		const document = documentWithClip();
+		const next = await applyPendingFreshRecordingAutoZooms(document, {
+			enabled: true,
+			getTelemetry: async () => {
+				throw new Error("sidecar missing");
+			},
+		});
+		expect(next).toBe(document);
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(true);
+	});
+
+	it("does not decorate a different project's asset after a leftover pending flag", async () => {
+		markFreshRecordingAutoZoomPending("C:\\recordings\\fresh.mp4");
+		const other = documentWithClip();
+		const next = await applyPendingFreshRecordingAutoZooms(other, {
+			enabled: true,
+			getTelemetry: async () => dwell(4000, 0.4, 0.6),
+		});
+		expect(next).toBe(other);
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(true);
+	});
+
+	it("does not decorate a later imported clip while the fresh take is still pending", async () => {
+		const fresh = documentWithClip();
+		const laterPath = "C:\\recordings\\later.mp4";
+		const withLater: AxcutDocument = {
+			...fresh,
+			assets: [
+				...fresh.assets,
+				{
+					id: "asset_later",
+					kind: "video",
+					label: "later.mp4",
+					originalPath: laterPath,
+					cameraTrack: null,
+					durationSec: 10,
+				},
+			],
+			timeline: {
+				...fresh.timeline,
+				clips: [
+					...fresh.timeline.clips,
+					{
+						id: "clip_later",
+						assetId: "asset_later",
+						sourceStartSec: 0,
+						sourceEndSec: 10,
+						timelineStartSec: 10,
+						timelineEndSec: 20,
+						wordRefs: [],
+						origin: "system",
+						reason: "",
+					},
+				],
+			},
+		};
+		markFreshRecordingAutoZoomPending(fresh.assets[0].originalPath);
+		const next = await applyPendingFreshRecordingAutoZooms(withLater, {
+			enabled: true,
+			getTelemetry: async (videoPath) => (videoPath === laterPath ? dwell(14000, 0.4, 0.6) : []),
+			createId: (prefix) => `${prefix}_later`,
+		});
+		expect(next).toBe(withLater);
+		expect(next.zoomRanges).toEqual([]);
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(true);
+	});
+
+	it("waits for a probed asset duration before generating zooms", async () => {
+		markFreshRecordingAutoZoomPending();
+		const placeholder = documentWithClip(60);
+		placeholder.assets[0].durationSec = undefined;
+		const first = await applyPendingFreshRecordingAutoZooms(placeholder, {
+			enabled: true,
+			getTelemetry: async () => dwell(4000, 0.4, 0.6),
+		});
+		expect(first).toBe(placeholder);
+		expect(first.zoomRanges).toEqual([]);
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(true);
+	});
+
+	it("appends to the store document after telemetry, not the caller's snapshot", async () => {
+		const stale = documentWithClip(90);
+		const trimmed = {
+			...stale,
+			timeline: {
+				...stale.timeline,
+				clips: [
+					{
+						...stale.timeline.clips[0],
+						sourceEndSec: 80,
+						timelineEndSec: 80,
+					},
+				],
+			},
+		};
+		let release!: () => void;
+		const gate = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		markFreshRecordingAutoZoomPending(stale.assets[0].originalPath);
+		useProjectStore.setState({ document: stale });
+		const pending = applyPendingFreshRecordingAutoZooms(stale, {
+			enabled: true,
+			getTelemetry: async () => {
+				await gate;
+				return dwell(4000, 0.4, 0.6);
+			},
+			createId: (prefix) => `${prefix}_live`,
+		});
+		useProjectStore.setState({ document: trimmed });
+		release();
+		const next = await pending;
+		expect(next.timeline.clips[0].sourceEndSec).toBe(80);
+		expect(next.zoomRanges).toHaveLength(1);
+	});
+
+	it("does not re-apply after a successful save once the user removes the zooms", async () => {
+		const document = documentWithClip();
+		const saveDocument = vi.fn(async (next: AxcutDocument) => {
+			useProjectStore.setState({ document: next });
+			return true;
+		});
+		useProjectStore.setState({
+			document,
+			saveDocument,
+		});
+		markFreshRecordingAutoZoomPending(document.assets[0].originalPath);
+		await expect(
+			maybeSaveFreshRecordingAutoZooms(document, {
+				enabled: true,
+				getTelemetry: async () => dwell(4000, 0.4, 0.6),
+				createId: (prefix) => `${prefix}_once`,
+			}),
+		).resolves.toBe(true);
+		expect(useProjectStore.getState().document?.zoomRanges).toHaveLength(1);
+
+		const cleared = {
+			...useProjectStore.getState().document,
+			zoomRanges: [],
+		} as AxcutDocument;
+		useProjectStore.setState({ document: cleared });
+		await expect(
+			maybeSaveFreshRecordingAutoZooms(cleared, {
+				enabled: true,
+				getTelemetry: async () => dwell(4000, 0.4, 0.6),
+			}),
+		).resolves.toBe(false);
+		expect(useProjectStore.getState().document?.zoomRanges).toEqual([]);
+	});
+
+	it("does not overwrite an in-flight user save with stale zooms", async () => {
+		const stale = documentWithClip(90);
+		const trimmed = {
+			...stale,
+			timeline: {
+				...stale.timeline,
+				clips: [
+					{
+						...stale.timeline.clips[0],
+						sourceEndSec: 80,
+						timelineEndSec: 80,
+					},
+				],
+			},
+		};
+		let releaseUserSave!: () => void;
+		const userSaveGate = new Promise<void>((resolve) => {
+			releaseUserSave = resolve;
+		});
+		let releaseTelemetry!: () => void;
+		const telemetryGate = new Promise<void>((resolve) => {
+			releaseTelemetry = resolve;
+		});
+		let saveCalls = 0;
+		bridge.save.mockImplementation(async (document: unknown) => {
+			saveCalls += 1;
+			if (saveCalls === 1) await userSaveGate;
+			return { success: true, document };
+		});
+		useProjectStore.setState({
+			document: stale,
+			saveDocument: realActions.saveDocument,
+		});
+		markFreshRecordingAutoZoomPending(stale.assets[0].originalPath);
+		const userSave = useProjectStore.getState().saveDocument(trimmed, { history: true });
+		const autoZoom = maybeSaveFreshRecordingAutoZooms(stale, {
+			enabled: true,
+			getTelemetry: async () => {
+				await telemetryGate;
+				return dwell(4000, 0.4, 0.6);
+			},
+			createId: (prefix) => `${prefix}_race`,
+		});
+		releaseTelemetry();
+		releaseUserSave();
+		await expect(userSave).resolves.toBe(true);
+		await expect(autoZoom).resolves.toBe(true);
+		const stored = useProjectStore.getState().document;
+		expect(stored?.timeline.clips[0].sourceEndSec).toBe(80);
+		expect(stored?.zoomRanges).toHaveLength(1);
+	});
+
+	// Contention is an exit, not a rebase: recomputing onto the document the other
+	// writer just produced only races that writer again. The attempt is dropped
+	// with pending intact so a retry runs against a settled document.
+	it("exits without writing when a user save lands mid-attempt", async () => {
+		const stale = documentWithClip(90);
+		const trimmed = {
+			...stale,
+			timeline: {
+				...stale.timeline,
+				clips: [{ ...stale.timeline.clips[0], sourceEndSec: 80, timelineEndSec: 80 }],
+			},
+		};
+		bridge.save.mockImplementation(async (document: unknown) => ({ success: true, document }));
+		useProjectStore.setState({ document: stale, saveDocument: realActions.saveDocument });
+		markFreshRecordingAutoZoomPending(stale.assets[0].originalPath);
+		let userSaveLanded = false;
+
+		const result = await maybeSaveFreshRecordingAutoZooms(stale, {
+			enabled: true,
+			// Runs between the two `waitForDocumentSaves` calls, which is exactly the
+			// window a rebase would have gone through. The save fires ONCE: if it
+			// fired again on a second suggestion pass, a rebasing implementation
+			// would bail on the newer write instead of on the contention itself, and
+			// this test would pass against the behaviour it exists to rule out.
+			getTelemetry: async () => {
+				if (!userSaveLanded) {
+					userSaveLanded = true;
+					await useProjectStore.getState().saveDocument(trimmed, { history: true });
+				}
+				return dwell(4000, 0.4, 0.6);
+			},
+			createId: (prefix) => `${prefix}_contended`,
+		});
+
+		expect(result).toBe(false);
+		const stored = useProjectStore.getState().document;
+		expect(stored?.timeline.clips[0].sourceEndSec).toBe(80);
+		expect(stored?.zoomRanges).toEqual([]);
+		// Still pending: the retries are what eventually apply the zooms.
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(true);
+	});
+
+	it("keeps pending when a later user save wipes zooms before they settle", async () => {
+		const stale = documentWithClip(90);
+		const trimmed = {
+			...stale,
+			timeline: {
+				...stale.timeline,
+				clips: [
+					{
+						...stale.timeline.clips[0],
+						sourceEndSec: 80,
+						timelineEndSec: 80,
+					},
+				],
+			},
+		};
+		let releaseAutoZoomIpc!: () => void;
+		const autoZoomIpcGate = new Promise<void>((resolve) => {
+			releaseAutoZoomIpc = resolve;
+		});
+		let releaseUserIpc!: () => void;
+		const userIpcGate = new Promise<void>((resolve) => {
+			releaseUserIpc = resolve;
+		});
+		let autoZoomStarted!: () => void;
+		const autoZoomStartedGate = new Promise<void>((resolve) => {
+			autoZoomStarted = resolve;
+		});
+		let userStarted!: () => void;
+		const userStartedGate = new Promise<void>((resolve) => {
+			userStarted = resolve;
+		});
+		let saveCalls = 0;
+		bridge.save.mockImplementation(async (document: unknown) => {
+			saveCalls += 1;
+			if (saveCalls === 1) {
+				autoZoomStarted();
+				await autoZoomIpcGate;
+			} else {
+				userStarted();
+				await userIpcGate;
+			}
+			return { success: true, document };
+		});
+		useProjectStore.setState({
+			document: stale,
+			saveDocument: realActions.saveDocument,
+		});
+		markFreshRecordingAutoZoomPending(stale.assets[0].originalPath);
+		const autoZoom = maybeSaveFreshRecordingAutoZooms(stale, {
+			enabled: true,
+			getTelemetry: async () => dwell(4000, 0.4, 0.6),
+			createId: (prefix) => `${prefix}_after`,
+		});
+		await autoZoomStartedGate;
+		const userSave = useProjectStore.getState().saveDocument(trimmed, { history: true });
+		await userStartedGate;
+		releaseAutoZoomIpc();
+		releaseUserIpc();
+		await expect(userSave).resolves.toBe(true);
+		await expect(autoZoom).resolves.toBe(true);
+		const wiped = useProjectStore.getState().document;
+		expect(wiped?.timeline.clips[0].sourceEndSec).toBe(80);
+		expect(wiped?.zoomRanges).toEqual([]);
+
+		await expect(
+			maybeSaveFreshRecordingAutoZooms(wiped as AxcutDocument, {
+				enabled: true,
+				getTelemetry: async () => dwell(4000, 0.4, 0.6),
+				createId: (prefix) => `${prefix}_rebase`,
+			}),
+		).resolves.toBe(true);
+		const recovered = useProjectStore.getState().document;
+		expect(recovered?.timeline.clips[0].sourceEndSec).toBe(80);
+		expect(recovered?.zoomRanges).toHaveLength(1);
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(false);
+	});
+	// Waiting on somebody else's write is only half of it: this path's OWN write
+	// can hang too. `saveDocument` never rejects, so a main process that stops
+	// answering leaves the await pending forever — inside the shared chain, which
+	// then takes every retry down with it.
+	//
+	// LAST in this file on purpose: the abandoned save is never released, so it
+	// leaves the in-flight counter raised for anything that runs after it.
+	it("gives up on a write that never answers, and leaves the chain usable", async () => {
+		const doc = documentWithClip(90);
+		bridge.save.mockReturnValue(new Promise(() => undefined));
+		useProjectStore.setState({ document: doc, saveDocument: realActions.saveDocument });
+		markFreshRecordingAutoZoomPending(doc.assets[0].originalPath);
+
+		await expect(
+			maybeSaveFreshRecordingAutoZooms(doc, {
+				enabled: true,
+				getTelemetry: async () => dwell(4000, 0.4, 0.6),
+				createId: (prefix) => `${prefix}_stuck`,
+				saveTimeoutMs: 10,
+				waitTimeoutMs: 10,
+			}),
+		).resolves.toBe(false);
+		// Nothing was written, and the attempt is still owed.
+		expect(useProjectStore.getState().document?.zoomRanges).toEqual([]);
+
+		// The chain let go: a later attempt runs instead of queueing behind a promise
+		// that is never coming back. (The abandoned save still holds the in-flight
+		// counter, so this one waits out its own deadline rather than resolving idle
+		// — which is the point: degraded, not wedged.)
+		bridge.save.mockImplementation(async (document: unknown) => ({ success: true, document }));
+		await expect(
+			maybeSaveFreshRecordingAutoZooms(doc, {
+				enabled: true,
+				getTelemetry: async () => dwell(4000, 0.4, 0.6),
+				createId: (prefix) => `${prefix}_after`,
+				saveTimeoutMs: 1_000,
+				waitTimeoutMs: 10,
+			}),
+		).resolves.toBe(false);
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(true);
+	});
+});
diff --git a/src/components/ai-edition/recordingImport.ts b/src/components/ai-edition/recordingImport.ts
index 9a3474397..a8e68beb6 100644
--- a/src/components/ai-edition/recordingImport.ts
+++ b/src/components/ai-edition/recordingImport.ts
@@ -14,7 +14,297 @@
 // derived `currentVideoPath`); the only renderer that still needs the session
 // after this point is the CLI runner, which lives in its own process.
 
-import { useProjectStore } from "@/lib/ai-edition/store/projectStore";
+import type { CursorTelemetryPoint } from "@/components/video-editor/types";
+import { createId } from "@/lib/ai-edition/document/ids";
+import type { AxcutDocument } from "@/lib/ai-edition/schema";
+import {
+	DOCUMENT_SAVES_WAIT_TIMEOUT_MS,
+	saveWithDeadline,
+	useProjectStore,
+	waitForDocumentSaves,
+} from "@/lib/ai-edition/store/projectStore";
+import {
+	appendAutoZoomSuggestions,
+	collectAutoZoomSuggestionsForDocument,
+} from "@/lib/ai-edition/timeline/apply-auto-zooms";
+import { nativeBridgeClient } from "@/native/client";
+
+// Fresh recordings used to get cursor-dwell zooms on load (legacy editor
+// `autoZoomEnabled`, default on). The ai-edition import only seeded a clip, so
+// the wand still worked but a new take landed un-zoomed. This flag is the
+// one-shot hand-off: set as soon as the asset is on the document, then taken
+// only after a real apply attempt (clips exist, duration is probed, and
+// telemetry was readable, or the toggle is off). Keeping it across an
+// empty-clip / empty-sidecar / placeholder-duration pass is what lets metadata
+// win the race against the helper flush. The path stops a leftover flag from
+// decorating a later, unrelated project in the same window. A successful save
+// records the project id so a later undo or delete cannot be silently re-seeded.
+let pendingFreshRecordingAutoZoom = false;
+let pendingFreshRecordingAutoZoomPath: string | null = null;
+let appliedFreshRecordingAutoZoomProjectId: string | null = null;
+let pendingFreshRecordingAutoZoomTimers: ReturnType<typeof setTimeout>[] = [];
+let freshRecordingAutoZoomSaveChain: Promise<void> = Promise.resolve();
+
+const FRESH_RECORDING_AUTO_ZOOM_RETRY_MS = [500, 1500, 3000];
+
+function clearFreshRecordingAutoZoomTimers(): void {
+	for (const timer of pendingFreshRecordingAutoZoomTimers) {
+		clearTimeout(timer);
+	}
+	pendingFreshRecordingAutoZoomTimers = [];
+}
+
+function scheduleFreshRecordingAutoZoomRetries(): void {
+	clearFreshRecordingAutoZoomTimers();
+	for (const delayMs of FRESH_RECORDING_AUTO_ZOOM_RETRY_MS) {
+		pendingFreshRecordingAutoZoomTimers.push(
+			setTimeout(() => {
+				if (!pendingFreshRecordingAutoZoom) return;
+				const document = useProjectStore.getState().document;
+				if (document) {
+					void maybeSaveFreshRecordingAutoZooms(document);
+				}
+			}, delayMs),
+		);
+	}
+}
+
+export function markFreshRecordingAutoZoomPending(assetPath?: string): void {
+	pendingFreshRecordingAutoZoom = true;
+	pendingFreshRecordingAutoZoomPath = assetPath ?? null;
+	appliedFreshRecordingAutoZoomProjectId = null;
+	scheduleFreshRecordingAutoZoomRetries();
+}
+
+function clearFreshRecordingAutoZoomPending(): void {
+	pendingFreshRecordingAutoZoom = false;
+	pendingFreshRecordingAutoZoomPath = null;
+	clearFreshRecordingAutoZoomTimers();
+}
+
+export function consumeFreshRecordingAutoZoomPending(): boolean {
+	const was = pendingFreshRecordingAutoZoom;
+	clearFreshRecordingAutoZoomPending();
+	appliedFreshRecordingAutoZoomProjectId = null;
+	freshRecordingAutoZoomSaveChain = Promise.resolve();
+	return was;
+}
+
+export type ApplyFreshRecordingAutoZoomsDeps = {
+	enabled?: boolean;
+	getTelemetry?: (videoPath: string) => Promise<CursorTelemetryPoint[] | null | undefined>;
+	createId?: (prefix: string) => string;
+	/** Deadline for this path's own write. Tests use a short one. */
+	saveTimeoutMs?: number;
+	/** Deadline for waiting on writes somebody else started. Tests shorten it. */
+	waitTimeoutMs?: number;
+};
+
+async function readAutoZoomPref(): Promise<boolean> {
+	try {
+		const prefs = await window.electronAPI?.getRecordingPrefs?.();
+		return prefs?.autoZoomEnabled !== false;
+	} catch {
+		return true;
+	}
+}
+
+function pendingFreshRecordingAsset(document: AxcutDocument) {
+	if (pendingFreshRecordingAutoZoomPath) {
+		return document.assets.find(
+			(asset) => asset.originalPath === pendingFreshRecordingAutoZoomPath,
+		);
+	}
+	const primaryId = document.project.primaryAssetId;
+	return document.assets.find((asset) => asset.id === primaryId) ?? document.assets[0];
+}
+
+function hasProbedDurationForPendingAsset(document: AxcutDocument): boolean {
+	const asset = pendingFreshRecordingAsset(document);
+	return (
+		asset != null &&
+		asset.durationSec != null &&
+		Number.isFinite(asset.durationSec) &&
+		asset.durationSec > 0
+	);
+}
+
+function clipExtentSignature(document: AxcutDocument): string {
+	return document.timeline.clips
+		.map(
+			(clip) =>
+				`${clip.id}:${clip.assetId}:${clip.sourceStartSec}:${clip.sourceEndSec ?? ""}:${clip.timelineStartSec}:${clip.timelineEndSec}`,
+		)
+		.join("|");
+}
+
+function canApplyFreshRecordingAutoZooms(document: AxcutDocument): boolean {
+	if (!pendingFreshRecordingAutoZoom) return false;
+	if (appliedFreshRecordingAutoZoomProjectId === document.project.id) return false;
+	if ((document.zoomRanges?.length ?? 0) > 0) return false;
+	if ((document.timeline?.clips?.length ?? 0) === 0) return false;
+	if (!hasProbedDurationForPendingAsset(document)) return false;
+	if (
+		pendingFreshRecordingAutoZoomPath &&
+		!document.assets.some((asset) => asset.originalPath === pendingFreshRecordingAutoZoomPath)
+	) {
+		return false;
+	}
+	return true;
+}
+
+function liveDocument(fallback: AxcutDocument): AxcutDocument {
+	return useProjectStore.getState().document ?? fallback;
+}
+
+export async function applyPendingFreshRecordingAutoZooms(
+	document: AxcutDocument,
+	deps: ApplyFreshRecordingAutoZoomsDeps = {},
+): Promise<AxcutDocument> {
+	if (!pendingFreshRecordingAutoZoom) return document;
+	if (appliedFreshRecordingAutoZoomProjectId === document.project.id) {
+		clearFreshRecordingAutoZoomPending();
+		return document;
+	}
+	const enabled = deps.enabled ?? (await readAutoZoomPref());
+	if (!enabled) {
+		clearFreshRecordingAutoZoomPending();
+		return liveDocument(document);
+	}
+	const start = liveDocument(document);
+	if ((start.zoomRanges?.length ?? 0) > 0) {
+		clearFreshRecordingAutoZoomPending();
+		appliedFreshRecordingAutoZoomProjectId = start.project.id;
+		return start;
+	}
+	if (!canApplyFreshRecordingAutoZooms(start)) {
+		return start;
+	}
+	const inner =
+		deps.getTelemetry ?? ((videoPath: string) => nativeBridgeClient.cursor.getTelemetry(videoPath));
+	const getTelemetry = async (videoPath: string) => {
+		try {
+			return await inner(videoPath);
+		} catch {
+			// Sidecar may not be readable yet. Keep pending for the delayed retries.
+			return [];
+		}
+	};
+	const collectFrom = async (source: AxcutDocument) => {
+		const scoped = pendingFreshRecordingAutoZoomPath
+			? {
+					...source,
+					assets: source.assets.filter(
+						(asset) => asset.originalPath === pendingFreshRecordingAutoZoomPath,
+					),
+				}
+			: source;
+		return collectAutoZoomSuggestionsForDocument(scoped, getTelemetry);
+	};
+
+	const firstSignature = clipExtentSignature(start);
+	let suggestions = await collectFrom(start);
+	let latest = liveDocument(start);
+	if (latest.project.id !== start.project.id) {
+		return latest;
+	}
+	if ((latest.zoomRanges?.length ?? 0) > 0) {
+		clearFreshRecordingAutoZoomPending();
+		appliedFreshRecordingAutoZoomProjectId = latest.project.id;
+		return latest;
+	}
+	if (!canApplyFreshRecordingAutoZooms(latest)) {
+		return latest;
+	}
+	if (clipExtentSignature(latest) !== firstSignature) {
+		suggestions = await collectFrom(latest);
+		latest = liveDocument(latest);
+		if (latest.project.id !== start.project.id) return latest;
+		if ((latest.zoomRanges?.length ?? 0) > 0) {
+			clearFreshRecordingAutoZoomPending();
+			appliedFreshRecordingAutoZoomProjectId = latest.project.id;
+			return latest;
+		}
+		if (!canApplyFreshRecordingAutoZooms(latest)) return latest;
+	}
+	if (suggestions.length === 0) {
+		// Do not consume: a mid-flush sidecar can have samples but no dwell yet
+		// (the qualifying sit is often the last second of the take).
+		return latest;
+	}
+	return appendAutoZoomSuggestions(latest, suggestions, deps.createId ?? createId);
+}
+
+export async function maybeSaveFreshRecordingAutoZooms(
+	document: AxcutDocument,
+	deps: ApplyFreshRecordingAutoZoomsDeps = {},
+): Promise<boolean> {
+	const writeFreshRecordingAutoZooms = async (): Promise<boolean> => {
+		try {
+			// A wait that times out has told us nothing about what is on disk, so the
+			// only safe move is to abandon this attempt with pending still set: the
+			// retries below rebase onto whatever the stuck save eventually leaves.
+			if ((await waitForDocumentSaves(deps.waitTimeoutMs)) === "timeout") return false;
+			const latest = liveDocument(document);
+			const next = await applyPendingFreshRecordingAutoZooms(latest, deps);
+			if ((await waitForDocumentSaves(deps.waitTimeoutMs)) === "timeout") return false;
+			const current = liveDocument(document);
+			if (current.project.id !== latest.project.id) return false;
+			if ((current.zoomRanges?.length ?? 0) > 0) {
+				appliedFreshRecordingAutoZoomProjectId = current.project.id;
+				clearFreshRecordingAutoZoomPending();
+				return false;
+			}
+			// Contention means exit, not rebase. If the document moved while the
+			// suggestion pass ran, this attempt is working from a snapshot that is
+			// already history — recomputing onto the newer one just races the writer
+			// that produced it. Drop the attempt with pending still set; the
+			// 500/1500/3000 ms retries run against a settled document instead.
+			if (current !== latest) return false;
+			const toSave = next;
+			const storedNow = liveDocument(document);
+			if (storedNow !== latest) return false;
+			if (toSave === latest || toSave === storedNow) return false;
+			if (storedNow.project.id !== latest.project.id) return false;
+			const saved = await saveWithDeadline(
+				useProjectStore.getState().saveDocument(toSave, { history: true }),
+				deps.saveTimeoutMs ?? DOCUMENT_SAVES_WAIT_TIMEOUT_MS,
+			);
+			// The write never answered. Keep pending and let go of the chain, so the
+			// retries get to run instead of queueing behind a promise that is not
+			// coming back.
+			if (saved === "timeout") return false;
+			// A trim (or any other edit) can start after this save was submitted and
+			// still be in flight when it returns: `waitForDocumentSaves` before the
+			// write only sees saves that have already begun. Wait again, then look at
+			// the store — if that later write landed on the unzoomed snapshot, keep
+			// pending so a retry can try again. A timeout here says the same thing for
+			// a different reason: we cannot tell what landed, so do not clear pending.
+			if ((await waitForDocumentSaves(deps.waitTimeoutMs)) === "timeout") return saved;
+			const stored = useProjectStore.getState().document;
+			if (saved && stored && (stored.zoomRanges?.length ?? 0) > 0) {
+				appliedFreshRecordingAutoZoomProjectId = stored.project.id;
+				clearFreshRecordingAutoZoomPending();
+			}
+			return saved;
+		} catch (error) {
+			// `saveDocument` reports failure by returning false, so anything thrown
+			// here came from the suggestion pass or a bridge call. Pending stays set
+			// and the retries fire silently — log it, or the whole path is invisible.
+			console.warn("[recording] fresh-recording auto-zoom write failed:", error);
+			return false;
+		}
+	};
+	const done = freshRecordingAutoZoomSaveChain.then(
+		writeFreshRecordingAutoZooms,
+		writeFreshRecordingAutoZooms,
+	);
+	freshRecordingAutoZoomSaveChain = done.then(
+		() => undefined,
+		() => undefined,
+	);
+	return done;
+}
 
 /**
  * Imports the recording the HUD handed over into a new project, and consumes the
@@ -31,10 +321,23 @@ export async function importPendingRecording(): Promise<boolean> {
 	const result = await api.getCurrentRecordingSession();
 	const screenPath = result.success ? result.session?.screenVideoPath : undefined;
 	if (!screenPath) return false;
+	const cursorCaptureMode = result.success ? result.session?.cursorCaptureMode : undefined;
 
 	const label = screenPath.split(/[\\/]/).pop() || "Recording";
 	await useProjectStore.getState().createProject(`Recording ${new Date().toLocaleString()}`);
 	await useProjectStore.getState().addAsset(screenPath, label);
+	// Mark before the video element can fire `loadedmetadata`. The asset path is
+	// already on the document; waiting until the 60s seed finished let the first
+	// metadata pass consume nothing and the second never arrive.
+	//
+	// Except for a system-cursor take, which writes no `.cursor.json` at all: the
+	// toggle stays on in prefs (it is only disabled in the UI while that mode is
+	// picked), so without this the flag was set for a recording that can never
+	// produce a dwell, and all three retries ran against an empty sidecar. What
+	// governs is the mode THIS take was recorded in, not the current preference.
+	if (cursorCaptureMode !== "system") {
+		markFreshRecordingAutoZoomPending(screenPath);
+	}
 	// Consumed: the recording now lives in a project. Cleared here rather than
 	// after the timeline seed below so a failure down there can't hand the same
 	// recording to the next editor window.
@@ -58,5 +361,9 @@ export async function importPendingRecording(): Promise<boolean> {
 				history: false,
 			});
 	}
+	const latest = useProjectStore.getState().document;
+	if (latest) {
+		await maybeSaveFreshRecordingAutoZooms(latest);
+	}
 	return true;
 }
diff --git a/src/native/browserShim.ts b/src/native/browserShim.ts
index c9e5d395b..c973d3a44 100644
--- a/src/native/browserShim.ts
+++ b/src/native/browserShim.ts
@@ -47,6 +47,7 @@ type ShimRecordingPrefs = {
 	camDeviceId: string | null;
 	systemAudioEnabled: boolean;
 	cursorCaptureMode: "editable-overlay" | "system";
+	autoZoomEnabled: boolean;
 };
 const recordingPrefsStorageKey = "browser-shim-recording-prefs";
 let shimRecordingPrefs: ShimRecordingPrefs = {
@@ -57,6 +58,7 @@ let shimRecordingPrefs: ShimRecordingPrefs = {
 	camDeviceId: null,
 	systemAudioEnabled: false,
 	cursorCaptureMode: "editable-overlay",
+	autoZoomEnabled: true,
 };
 (() => {
 	try {

From 6af6c2d2b3c8216fcfa4bb36107894a7b09a8c23 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 22:10:05 +0800
Subject: [PATCH 11/14] feat(launch): add the after-recording auto-zoom toggle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One switch, on by default, in `recordingPrefs`, surfaced in both places a take is
started from: the HUD and the Rec stage. It is disabled while the cursor is in
system mode, because the pass reads the overlay's cursor telemetry and there is
none to read — the tooltip says so rather than leaving a dead control.

`aria-pressed` on the HUD button, like the mic and camera toggles beside it, so
the state is not carried by colour alone.
---
 electron/ipc/handlers.ts                      |   3 +
 .../ai-edition/v4/RecStage.test.tsx           | 113 ++++++++++++++++++
 src/components/ai-edition/v4/RecStage.tsx     |  32 ++++-
 src/components/ai-edition/v4/V4Timeline.tsx   |  35 ++----
 src/components/launch/HudControls.tsx         |  30 +++++
 src/components/launch/HudIcons.tsx            |  10 ++
 src/components/launch/LaunchWindow.test.tsx   |  75 +++++++++++-
 src/components/launch/LaunchWindow.tsx        |  31 +++++
 src/hooks/useScreenRecorder.ts                |   6 +
 src/i18n/locales/ar/editor.json               |   2 +
 src/i18n/locales/ar/launch.json               |   5 +
 src/i18n/locales/en/editor.json               |   2 +
 src/i18n/locales/en/launch.json               |   5 +
 src/i18n/locales/es/editor.json               |   2 +
 src/i18n/locales/es/launch.json               |   5 +
 src/i18n/locales/fr/editor.json               |   2 +
 src/i18n/locales/fr/launch.json               |   5 +
 src/i18n/locales/it/editor.json               |   2 +
 src/i18n/locales/it/launch.json               |   5 +
 src/i18n/locales/ja-JP/editor.json            |   2 +
 src/i18n/locales/ja-JP/launch.json            |   5 +
 src/i18n/locales/ko-KR/editor.json            |   2 +
 src/i18n/locales/ko-KR/launch.json            |   5 +
 src/i18n/locales/pt-BR/editor.json            |   2 +
 src/i18n/locales/pt-BR/launch.json            |   5 +
 src/i18n/locales/ru/editor.json               |   2 +
 src/i18n/locales/ru/launch.json               |   5 +
 src/i18n/locales/tr/editor.json               |   2 +
 src/i18n/locales/tr/launch.json               |   5 +
 src/i18n/locales/vi/editor.json               |   2 +
 src/i18n/locales/vi/launch.json               |   5 +
 src/i18n/locales/zh-CN/editor.json            |   2 +
 src/i18n/locales/zh-CN/launch.json            |   5 +
 src/i18n/locales/zh-TW/editor.json            |   2 +
 src/i18n/locales/zh-TW/launch.json            |   5 +
 35 files changed, 396 insertions(+), 30 deletions(-)
 create mode 100644 src/components/ai-edition/v4/RecStage.test.tsx

diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index fcda39e0c..302f820a1 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -605,6 +605,8 @@ export interface RecordingPrefs {
 	camDeviceId: string | null;
 	systemAudioEnabled: boolean;
 	cursorCaptureMode: CursorCaptureMode;
+	/** After a take, suggest cursor-dwell zooms. Default on, matching 1.5. */
+	autoZoomEnabled: boolean;
 }
 let recordingPrefs: RecordingPrefs = {
 	micEnabled: false,
@@ -614,6 +616,7 @@ let recordingPrefs: RecordingPrefs = {
 	camDeviceId: null,
 	systemAudioEnabled: false,
 	cursorCaptureMode: "editable-overlay",
+	autoZoomEnabled: true,
 };
 
 // Cached source from the user's pick. Used by setDisplayMediaRequestHandler in main.ts for cursor-free capture.
diff --git a/src/components/ai-edition/v4/RecStage.test.tsx b/src/components/ai-edition/v4/RecStage.test.tsx
new file mode 100644
index 000000000..ac98dbe3e
--- /dev/null
+++ b/src/components/ai-edition/v4/RecStage.test.tsx
@@ -0,0 +1,113 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { RecStage } from "./RecStage";
+
+vi.mock("@/contexts/I18nContext", () => ({
+	useScopedT: () => (key: string) => key,
+}));
+
+vi.mock("@/hooks/useMicrophoneDevices", () => ({
+	useMicrophoneDevices: () => ({
+		devices: [],
+		selectedDeviceId: "default",
+		setSelectedDeviceId: vi.fn(),
+		isLoading: false,
+	}),
+}));
+
+vi.mock("@/hooks/useCameraDevices", () => ({
+	useCameraDevices: () => ({
+		devices: [],
+		selectedDeviceId: "",
+		setSelectedDeviceId: vi.fn(),
+		isLoading: false,
+		error: null,
+	}),
+}));
+
+vi.mock("@/hooks/useAudioLevelMeter", () => ({
+	useAudioLevelMeter: () => ({ level: 0 }),
+}));
+
+vi.mock("@/hooks/useCameraPreviewStream", () => ({
+	useCameraPreviewStream: () => ({ stream: null, error: null }),
+}));
+
+vi.mock("@/hooks/usePortalOwnsSource", () => ({
+	usePortalOwnsSource: () => false,
+}));
+
+function stubRecordingPrefs(prefs: Record<string, unknown> = {}) {
+	const getRecordingPrefs = vi.fn(async () => prefs);
+	const setRecordingPrefs = vi.fn(async () => undefined);
+	(window as unknown as { electronAPI?: unknown }).electronAPI = {
+		getRecordingPrefs,
+		setRecordingPrefs,
+		getSelectedSource: vi.fn(async () => null),
+	};
+	return { getRecordingPrefs, setRecordingPrefs };
+}
+
+function renderRecStage() {
+	const onStartRecording = vi.fn();
+	render(<RecStage onStartRecording={onStartRecording} />);
+	return { onStartRecording };
+}
+
+describe("RecStage auto-zoom", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	afterEach(() => {
+		cleanup();
+		(window as unknown as { electronAPI?: unknown }).electronAPI = undefined;
+	});
+
+	it("defaults on when a legacy prefs blob has no autoZoomEnabled key", async () => {
+		const { getRecordingPrefs } = stubRecordingPrefs({
+			micEnabled: false,
+			cursorCaptureMode: "editable-overlay",
+		});
+		renderRecStage();
+		await waitFor(() => {
+			expect(getRecordingPrefs).toHaveBeenCalled();
+		});
+		const button = await screen.findByTestId("rec-auto-zoom-button");
+		expect(button).toHaveAttribute("aria-pressed", "true");
+		expect(button).toHaveTextContent("rec.on");
+		expect(button).toBeEnabled();
+	});
+
+	it("writes autoZoomEnabled through setRecordingPrefs on click", async () => {
+		const { setRecordingPrefs } = stubRecordingPrefs({
+			cursorCaptureMode: "editable-overlay",
+			autoZoomEnabled: true,
+		});
+		renderRecStage();
+		const button = await screen.findByTestId("rec-auto-zoom-button");
+		await waitFor(() => {
+			expect(button).toBeEnabled();
+		});
+		fireEvent.click(button);
+		expect(setRecordingPrefs).toHaveBeenCalledWith({ autoZoomEnabled: false });
+	});
+
+	it("disables auto-zoom while Rec-stage cursor capture is system", async () => {
+		const { setRecordingPrefs } = stubRecordingPrefs({
+			cursorCaptureMode: "system",
+			autoZoomEnabled: true,
+		});
+		renderRecStage();
+		const button = await screen.findByTestId("rec-auto-zoom-button");
+		await waitFor(() => {
+			expect(button).toBeDisabled();
+		});
+		expect(button).toHaveAttribute("title", "rec.autoZoomNeedsEditableCursor");
+		expect(button).toHaveAttribute("aria-pressed", "false");
+		fireEvent.click(button);
+		expect(setRecordingPrefs).not.toHaveBeenCalled();
+	});
+});
diff --git a/src/components/ai-edition/v4/RecStage.tsx b/src/components/ai-edition/v4/RecStage.tsx
index 8564d4895..2f098b3c1 100644
--- a/src/components/ai-edition/v4/RecStage.tsx
+++ b/src/components/ai-edition/v4/RecStage.tsx
@@ -9,6 +9,7 @@ import {
 	MousePointer2,
 	Volume2,
 	VolumeX,
+	ZoomIn,
 } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 import { AudioLevelMeter } from "@/components/ui/audio-level-meter";
@@ -28,6 +29,7 @@ interface RecordingPrefsState {
 	camDeviceId: string | null;
 	systemAudioEnabled: boolean;
 	cursorCaptureMode: "editable-overlay" | "system";
+	autoZoomEnabled: boolean;
 }
 
 const DEFAULT_PREFS: RecordingPrefsState = {
@@ -38,6 +40,7 @@ const DEFAULT_PREFS: RecordingPrefsState = {
 	camDeviceId: null,
 	systemAudioEnabled: false,
 	cursorCaptureMode: "editable-overlay",
+	autoZoomEnabled: true,
 };
 
 /**
@@ -67,7 +70,13 @@ export function RecStage({
 		void window.electronAPI
 			?.getRecordingPrefs?.()
 			.then((p) => {
-				if (!cancelled && p) setPrefsState(p as RecordingPrefsState);
+				if (!cancelled && p) {
+					setPrefsState({
+						...DEFAULT_PREFS,
+						...p,
+						autoZoomEnabled: p.autoZoomEnabled !== false,
+					} as RecordingPrefsState);
+				}
 			})
 			.catch((err) => {
 				// Bare ipcRenderer.invoke — rejects if the main handler throws. Keeping
@@ -367,6 +376,27 @@ export function RecStage({
 							{cursorHighlight ? t("rec.on") : t("rec.off")}
 						</button>
 					</div>
+
+					<div className={styles.recRow}>
+						<div className={styles.recRowLabel}>
+							<ZoomIn size={15} />
+							{t("rec.autoZoom")}
+						</div>
+						<button
+							type="button"
+							data-testid="rec-auto-zoom-button"
+							className={`${styles.recToggleBtn}${prefs.autoZoomEnabled !== false && cursorHighlight ? ` ${styles.on}` : ""}`}
+							aria-pressed={prefs.autoZoomEnabled !== false && cursorHighlight}
+							disabled={!cursorHighlight}
+							title={cursorHighlight ? undefined : t("rec.autoZoomNeedsEditableCursor")}
+							onClick={() => {
+								if (!cursorHighlight) return;
+								updatePrefs({ autoZoomEnabled: prefs.autoZoomEnabled === false });
+							}}
+						>
+							{prefs.autoZoomEnabled !== false && cursorHighlight ? t("rec.on") : t("rec.off")}
+						</button>
+					</div>
 				</div>
 			</div>
 
diff --git a/src/components/ai-edition/v4/V4Timeline.tsx b/src/components/ai-edition/v4/V4Timeline.tsx
index a4b41ff32..8dd426376 100644
--- a/src/components/ai-edition/v4/V4Timeline.tsx
+++ b/src/components/ai-edition/v4/V4Timeline.tsx
@@ -28,7 +28,7 @@ import {
 import { toast } from "sonner";
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
 import { Tooltip, TooltipProvider } from "@/components/ui/tooltip";
-import { fromFileUrl, toFileUrl } from "@/components/video-editor/projectPersistence";
+import { toFileUrl } from "@/components/video-editor/projectPersistence";
 import { ZOOM_DEPTH_SCALES } from "@/components/video-editor/types";
 import { useScopedT } from "@/contexts/I18nContext";
 import { useShortcuts } from "@/contexts/ShortcutsContext";
@@ -52,6 +52,7 @@ import { useTimelineTranscriptGate } from "@/lib/ai-edition/store/transcriptionS
 import { useChatPromptBus } from "@/lib/ai-edition/store/useChatPromptBus";
 import { useEditorSettings } from "@/lib/ai-edition/store/useEditorSettings";
 import type { useTimeline } from "@/lib/ai-edition/store/useTimeline";
+import { collectAutoZoomSuggestionsForDocument } from "@/lib/ai-edition/timeline/apply-auto-zooms";
 import { hasAnyClipWithCamera } from "@/lib/ai-edition/timeline/camera";
 import { formatSec } from "@/lib/ai-edition/timeline/format";
 import {
@@ -65,10 +66,6 @@ import {
 	resolveTimelineSpanToTrim,
 	ventilateTimelineSpanToTrims,
 } from "@/lib/ai-edition/timeline/trim-mapping";
-import {
-	type AutoZoomSuggestion,
-	buildAutoZoomSuggestionsForClips,
-} from "@/lib/ai-edition/timeline/zoom-suggestions";
 import { formatBinding } from "@/lib/shortcuts";
 import { nativeBridgeClient } from "@/native/client";
 import { TransportBar } from "../TransportBar";
@@ -1484,34 +1481,16 @@ export function V4Timeline({
 	// timeline was previously never consulted at all.
 	const runAutoZooms = useCallback(async () => {
 		setAutoEnhanceOpen(false);
-		const sources = videoSources.filter((source) => clips.some((c) => c.assetId === source.id));
-		if (sources.length === 0) {
+		const document = useProjectStore.getState().document;
+		if (!document || document.timeline.clips.length === 0) {
 			toast.error(t("toolbar.importRecordingFirst"));
 			return;
 		}
 		setAutoBusy(true);
 		try {
-			// Read once, up front: every clip reserves against the zooms the document
-			// ALREADY holds, and two clips can never contest the same stretch of ruler, so
-			// nothing here depends on the order the assets are visited — which is what lets
-			// their telemetry be fetched concurrently rather than one IPC round trip after
-			// another. `Promise.all` preserves input order, so the suggestions come out in
-			// the same sequence a loop would have produced.
-			const existingRegions = tl.zoomRegions.map((z) => ({ startMs: z.startMs, endMs: z.endMs }));
-			const perSource = await Promise.all(
-				sources.map(async (source) => {
-					const telemetry =
-						(await nativeBridgeClient.cursor.getTelemetry(fromFileUrl(source.src))) ?? [];
-					return buildAutoZoomSuggestionsForClips({
-						cursorTelemetry: telemetry,
-						assetId: source.id,
-						clips,
-						existingRegions,
-						defaultDurationMs: 2000,
-					});
-				}),
+			const suggestions = await collectAutoZoomSuggestionsForDocument(document, (videoPath) =>
+				nativeBridgeClient.cursor.getTelemetry(videoPath),
 			);
-			const suggestions: AutoZoomSuggestion[] = perSource.flat();
 			if (suggestions.length === 0) {
 				toast.info(t("toolbar.noAutoZoomMoments"), {
 					description: t("toolbar.noAutoZoomMomentsDescription"),
@@ -1533,7 +1512,7 @@ export function V4Timeline({
 		} finally {
 			setAutoBusy(false);
 		}
-	}, [videoSources, clips, tl, t]);
+	}, [tl, t]);
 
 	// Auto-enhance option 2 — hand a generic prompt to the AI agent (smart
 	// zooms + cuts) via the chat prompt-bus. The chat panel owns the outcome
diff --git a/src/components/launch/HudControls.tsx b/src/components/launch/HudControls.tsx
index 360499c79..72547f29c 100644
--- a/src/components/launch/HudControls.tsx
+++ b/src/components/launch/HudControls.tsx
@@ -4,6 +4,7 @@ import { formatTimePadded } from "../../utils/timeUtils";
 import { Button } from "../ui/button";
 import { Tooltip } from "../ui/tooltip";
 import {
+	AutoZoomIcon,
 	CameraIcon,
 	CursorIcon,
 	getIcon,
@@ -253,6 +254,35 @@ export const HudSettingsButton = memo(function HudSettingsButton({
 	);
 });
 
+export const HudAutoZoomButton = memo(function HudAutoZoomButton({
+	enabled,
+	disabled,
+	label,
+	onClick,
+}: {
+	enabled: boolean;
+	disabled: boolean;
+	label: string;
+	onClick: () => void;
+}) {
+	return (
+		<button
+			data-testid="launch-auto-zoom-button"
+			className={`flex h-[34px] w-[34px] shrink-0 items-center justify-center rounded-[10px] border-0 cursor-pointer transition-all duration-150 active:scale-95 ${hudDisabledClasses} ${styles.electronNoDrag} ${
+				enabled
+					? "bg-[#10b981] text-[#08090d] hover:bg-[#0e9e6e]"
+					: "bg-transparent text-[#828c99] hover:bg-[#1a1e25] hover:text-[#f5f7fa]"
+			}`}
+			aria-pressed={enabled}
+			onClick={onClick}
+			disabled={disabled}
+			title={label}
+		>
+			<AutoZoomIcon />
+		</button>
+	);
+});
+
 export const HudCursorButton = memo(function HudCursorButton({
 	editableOverlay,
 	disabled,
diff --git a/src/components/launch/HudIcons.tsx b/src/components/launch/HudIcons.tsx
index 0ec73bdff..f8e527abb 100644
--- a/src/components/launch/HudIcons.tsx
+++ b/src/components/launch/HudIcons.tsx
@@ -117,6 +117,16 @@ export function CameraIcon({ off, className }: { off: boolean; className?: strin
 	);
 }
 
+export function AutoZoomIcon({ className }: { className?: string }) {
+	return (
+		<svg {...HUD_SVG_PROPS} className={className} aria-hidden="true">
+			<circle cx="10.5" cy="10.5" r="5.5" />
+			<path d="M14.5 14.5 20 20" />
+			<path d="M10.5 8v5M8 10.5h5" />
+		</svg>
+	);
+}
+
 export function CursorIcon({ className }: { className?: string }) {
 	return (
 		<svg
diff --git a/src/components/launch/LaunchWindow.test.tsx b/src/components/launch/LaunchWindow.test.tsx
index 60894f9e0..0632d524d 100644
--- a/src/components/launch/LaunchWindow.test.tsx
+++ b/src/components/launch/LaunchWindow.test.tsx
@@ -3,6 +3,8 @@ import "@testing-library/jest-dom";
 import { act, cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
 import { StrictMode } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { nativeBridgeClient } from "@/native";
+import type { NativePlatform } from "@/native/contracts";
 import { TooltipProvider } from "../ui/tooltip";
 import { HUD_BAR_BOTTOM, HUD_POPOVER_GAP, HUD_POPOVER_MAX_HEIGHT } from "./hudGeometry";
 import { LaunchWindow } from "./LaunchWindow";
@@ -11,7 +13,7 @@ type SelectedSourceChangedListener = Parameters<
 	Window["electronAPI"]["onSelectedSourceChanged"]
 >[0];
 
-const platformState = vi.hoisted(() => ({ value: "darwin" }));
+const platformState = vi.hoisted(() => ({ value: "darwin" as NativePlatform }));
 const linuxHelperAvailable = vi.hoisted(() => ({ value: true }));
 const resizeCallbacks = vi.hoisted(() => [] as Array<ResizeObserverCallback>);
 
@@ -59,6 +61,8 @@ const recorderState = vi.hoisted(() => ({
 		setSystemAudioEnabled: vi.fn(),
 		cursorCaptureMode: "editable-overlay",
 		setCursorCaptureMode: vi.fn(),
+		autoZoomEnabled: true,
+		setAutoZoomEnabled: vi.fn(),
 		softwareEncoderFallbackNoticeVisible: false,
 		dismissSoftwareEncoderFallbackNotice: vi.fn(),
 	},
@@ -171,6 +175,10 @@ vi.mock("@/contexts/I18nContext", () => ({
 			"webcam.cameraDevice": "Camera device",
 			"cursor.useEditableCursor": "Use editable cursor",
 			"cursor.useSystemCursor": "Use system cursor",
+			"autoZoom.enable": "Enable auto-zoom after recording",
+			"autoZoom.disable": "Disable auto-zoom after recording",
+			"autoZoom.needsEditableCursor":
+				"Auto-zoom needs the editable cursor. Switch cursor mode to enable.",
 			"tooltips.openStudio": "Open Studio",
 			"tooltips.hideHUD": "Hide HUD",
 			"tooltips.closeApp": "Close App",
@@ -237,6 +245,7 @@ function stubElectronAPI(getSelectedSource: Window["electronAPI"]["getSelectedSo
 		endHudOverlayDrag: vi.fn(),
 		hudOverlayHide: vi.fn(),
 		hudOverlayClose: vi.fn(),
+		setRecordingPrefs: vi.fn(async (prefs) => prefs),
 		openNotes: vi.fn(),
 		switchToEditor: vi.fn(async () => undefined),
 		onSelectedSourceChanged: vi.fn((callback) => {
@@ -287,6 +296,10 @@ function emitSourceSelectorClosed() {
 function resetLaunchMocks() {
 	vi.stubGlobal("ResizeObserver", StubResizeObserver);
 	recorderState.value.toggleRecording.mockClear();
+	recorderState.value.cursorCaptureMode = "editable-overlay";
+	recorderState.value.autoZoomEnabled = true;
+	recorderState.value.setAutoZoomEnabled.mockClear();
+	recorderState.value.setCursorCaptureMode.mockClear();
 	recorderState.value.softwareEncoderFallbackNoticeVisible = false;
 	recorderState.value.dismissSoftwareEncoderFallbackNotice.mockClear();
 	recorderState.value.recording = false;
@@ -305,6 +318,9 @@ function resetLaunchMocks() {
 	i18nState.value.resolveSystemLocaleSuggestion.mockClear();
 	i18nState.value.setLocale.mockClear();
 	linuxHelperAvailable.value = true;
+	vi.mocked(nativeBridgeClient.system.getPlatform).mockImplementation(
+		async () => platformState.value,
+	);
 	appInfoState.value = { version: "1.9.6", canCheckForUpdates: true };
 	updateCheckMock.mockReset();
 	updateCheckMock.mockResolvedValue(undefined);
@@ -338,6 +354,63 @@ describe("LaunchWindow record button", () => {
 		expect(recorderState.value.toggleRecording).not.toHaveBeenCalled();
 	});
 
+	// The button says "on" with a colour fill and nothing else, so a screen reader
+	// gets no toggle state at all — the same `aria-pressed` the mic and camera
+	// buttons beside it already carry.
+	it("reports the auto-zoom toggle state", () => {
+		renderLaunchWindow();
+
+		expect(screen.getByTestId("launch-auto-zoom-button")).toHaveAttribute("aria-pressed", "true");
+
+		cleanup();
+		recorderState.value.autoZoomEnabled = false;
+		renderLaunchWindow();
+
+		expect(screen.getByTestId("launch-auto-zoom-button")).toHaveAttribute("aria-pressed", "false");
+	});
+
+	it("toggles post-record auto-zoom without touching cursor capture", () => {
+		renderLaunchWindow();
+
+		const button = screen.getByTestId("launch-auto-zoom-button");
+		expect(button).toHaveAttribute("title", "Disable auto-zoom after recording");
+		fireEvent.click(button);
+
+		expect(recorderState.value.setAutoZoomEnabled).toHaveBeenCalledWith(false);
+		expect(window.electronAPI.setRecordingPrefs).toHaveBeenCalledWith({ autoZoomEnabled: false });
+		expect(recorderState.value.setCursorCaptureMode).not.toHaveBeenCalled();
+	});
+
+	it("disables auto-zoom while the HUD is in system-cursor mode", async () => {
+		recorderState.value.cursorCaptureMode = "system";
+		renderLaunchWindow();
+
+		const button = await waitFor(() => {
+			const el = screen.getByTestId("launch-auto-zoom-button");
+			expect(el).toBeDisabled();
+			return el;
+		});
+		expect(button).toHaveAttribute(
+			"title",
+			"Auto-zoom needs the editable cursor. Switch cursor mode to enable.",
+		);
+		fireEvent.click(button);
+		expect(recorderState.value.setAutoZoomEnabled).not.toHaveBeenCalled();
+	});
+
+	it("disables auto-zoom in system-cursor mode before platform detection finishes", () => {
+		vi.mocked(nativeBridgeClient.system.getPlatform).mockImplementation(
+			() => new Promise(() => undefined),
+		);
+		recorderState.value.cursorCaptureMode = "system";
+		renderLaunchWindow();
+
+		const button = screen.getByTestId("launch-auto-zoom-button");
+		expect(button).toBeDisabled();
+		fireEvent.click(button);
+		expect(recorderState.value.setAutoZoomEnabled).not.toHaveBeenCalled();
+	});
+
 	it("records immediately after source selection when the record button opened the picker", async () => {
 		renderLaunchWindow();
 		await waitForSourceSelectionSubscription();
diff --git a/src/components/launch/LaunchWindow.tsx b/src/components/launch/LaunchWindow.tsx
index 8a2427fc1..ea1573028 100644
--- a/src/components/launch/LaunchWindow.tsx
+++ b/src/components/launch/LaunchWindow.tsx
@@ -9,6 +9,7 @@ import { usePortalOwnsSource } from "../../hooks/usePortalOwnsSource";
 import { useScreenRecorder } from "../../hooks/useScreenRecorder";
 import { requestCameraAccess } from "../../lib/requestCameraAccess";
 import {
+	HudAutoZoomButton,
 	HudCameraButton,
 	HudCursorButton,
 	HudDivider,
@@ -105,6 +106,8 @@ export function LaunchWindow() {
 		setWebcamDeviceName,
 		cursorCaptureMode,
 		setCursorCaptureMode,
+		autoZoomEnabled,
+		setAutoZoomEnabled,
 		softwareEncoderFallbackNoticeVisible,
 		dismissSoftwareEncoderFallbackNotice,
 	} = useScreenRecorder();
@@ -720,6 +723,7 @@ export function LaunchWindow() {
 			camDeviceId?: string;
 			micDeviceId?: string;
 			micDeviceName?: string;
+			autoZoomEnabled?: boolean;
 		}) => {
 			void window.electronAPI?.setRecordingPrefs?.(patch).catch((error) => {
 				console.warn("Failed to persist the device preference:", error);
@@ -728,6 +732,21 @@ export function LaunchWindow() {
 		[],
 	);
 
+	const systemCursorLocksAutoZoom = cursorCaptureMode === "system";
+	const toggleAutoZoom = useCallback(() => {
+		if (controlsLocked) return;
+		if (systemCursorLocksAutoZoom) return;
+		const next = !autoZoomEnabled;
+		setAutoZoomEnabled(next);
+		persistRecordingPrefs({ autoZoomEnabled: next });
+	}, [
+		autoZoomEnabled,
+		controlsLocked,
+		persistRecordingPrefs,
+		setAutoZoomEnabled,
+		systemCursorLocksAutoZoom,
+	]);
+
 	const toggleWebcam = useCallback(() => {
 		if (controlsLocked) return;
 		const next = !webcamEnabled;
@@ -1009,6 +1028,18 @@ export function LaunchWindow() {
 							onClick={toggleDeviceSettings}
 						/>
 					</div>
+					<HudAutoZoomButton
+						enabled={autoZoomEnabled && !systemCursorLocksAutoZoom}
+						disabled={controlsLocked || systemCursorLocksAutoZoom}
+						label={
+							systemCursorLocksAutoZoom
+								? t("autoZoom.needsEditableCursor")
+								: autoZoomEnabled
+									? t("autoZoom.disable")
+									: t("autoZoom.enable")
+						}
+						onClick={toggleAutoZoom}
+					/>
 					{supportsCursorModeToggle && (
 						<HudCursorButton
 							editableOverlay={cursorCaptureMode === "editable-overlay"}
diff --git a/src/hooks/useScreenRecorder.ts b/src/hooks/useScreenRecorder.ts
index fcab5452b..396866b0f 100644
--- a/src/hooks/useScreenRecorder.ts
+++ b/src/hooks/useScreenRecorder.ts
@@ -106,6 +106,8 @@ type UseScreenRecorderReturn = {
 	setWebcamEnabled: (enabled: boolean) => Promise<boolean>;
 	cursorCaptureMode: CursorCaptureMode;
 	setCursorCaptureMode: (mode: CursorCaptureMode) => void;
+	autoZoomEnabled: boolean;
+	setAutoZoomEnabled: (enabled: boolean) => void;
 	softwareEncoderFallbackNoticeVisible: boolean;
 	dismissSoftwareEncoderFallbackNotice: (dontShowAgain?: boolean) => void;
 };
@@ -242,6 +244,7 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 	const [systemAudioEnabled, setSystemAudioEnabled] = useState(false);
 	const [webcamEnabled, setWebcamEnabledState] = useState(false);
 	const [cursorCaptureMode, setCursorCaptureMode] = useState<CursorCaptureMode>("editable-overlay");
+	const [autoZoomEnabled, setAutoZoomEnabled] = useState(true);
 	const [softwareEncoderFallbackNoticeVisible, setSoftwareEncoderFallbackNoticeVisible] =
 		useState(false);
 
@@ -267,6 +270,7 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 				if (prefs.camDeviceId) setWebcamDeviceId(prefs.camDeviceId);
 				setSystemAudioEnabled(prefs.systemAudioEnabled);
 				setCursorCaptureMode(prefs.cursorCaptureMode);
+				setAutoZoomEnabled(prefs.autoZoomEnabled !== false);
 			})
 			.catch((err) => {
 				// Bare ipcRenderer.invoke — rejects if the main handler throws. Falling
@@ -2347,6 +2351,8 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 		setWebcamEnabled,
 		cursorCaptureMode,
 		setCursorCaptureMode,
+		autoZoomEnabled,
+		setAutoZoomEnabled,
 		softwareEncoderFallbackNoticeVisible,
 		dismissSoftwareEncoderFallbackNotice,
 	};
diff --git a/src/i18n/locales/ar/editor.json b/src/i18n/locales/ar/editor.json
index 45190b2eb..98e0f38f0 100644
--- a/src/i18n/locales/ar/editor.json
+++ b/src/i18n/locales/ar/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "الميكروفون",
 		"camera": "الكاميرا",
 		"cursorHighlight": "إبراز المؤشر",
+		"autoZoom": "تكبير تلقائي بعد التسجيل",
+		"autoZoomNeedsEditableCursor": "التكبير التلقائي يحتاج إلى المؤشر القابل للتحرير. بدّل وضع المؤشر للتفعيل.",
 		"on": "تشغيل",
 		"off": "إيقاف",
 		"loading": "جارٍ التحميل...",
diff --git a/src/i18n/locales/ar/launch.json b/src/i18n/locales/ar/launch.json
index 0198af382..d632953b3 100644
--- a/src/i18n/locales/ar/launch.json
+++ b/src/i18n/locales/ar/launch.json
@@ -78,6 +78,11 @@
 		"useEditableCursor": "استخدام مؤشر قابل للتحرير",
 		"useSystemCursor": "استخدام مؤشر النظام"
 	},
+	"autoZoom": {
+		"enable": "تفعيل التكبير التلقائي بعد التسجيل",
+		"disable": "تعطيل التكبير التلقائي بعد التسجيل",
+		"needsEditableCursor": "التكبير التلقائي يحتاج إلى المؤشر القابل للتحرير. بدّل وضع المؤشر للتفعيل."
+	},
 	"softwareEncoderFallback": {
 		"title": "تم التبديل إلى الترميز البرمجي",
 		"description": "تعذّر تشغيل مرمّز GPU الافتراضي، لذا تحوّل OpenScreen إلى ترميز H.264 البرمجي. سيستمر التسجيل كالمعتاد، لكن استخدام المعالج قد يكون أعلى.",
diff --git a/src/i18n/locales/en/editor.json b/src/i18n/locales/en/editor.json
index 6b738c399..2c4ddc248 100644
--- a/src/i18n/locales/en/editor.json
+++ b/src/i18n/locales/en/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "Microphone",
 		"camera": "Camera",
 		"cursorHighlight": "Cursor highlight",
+		"autoZoom": "Auto-zoom after recording",
+		"autoZoomNeedsEditableCursor": "Auto-zoom needs the editable cursor. Switch cursor mode to enable.",
 		"on": "On",
 		"off": "Off",
 		"loading": "Loading…",
diff --git a/src/i18n/locales/en/launch.json b/src/i18n/locales/en/launch.json
index ad2385c02..3c60aad22 100644
--- a/src/i18n/locales/en/launch.json
+++ b/src/i18n/locales/en/launch.json
@@ -56,6 +56,11 @@
 		"useEditableCursor": "Use editable cursor",
 		"useSystemCursor": "Use system cursor"
 	},
+	"autoZoom": {
+		"enable": "Enable auto-zoom after recording",
+		"disable": "Disable auto-zoom after recording",
+		"needsEditableCursor": "Auto-zoom needs the editable cursor. Switch cursor mode to enable."
+	},
 	"sourceSelector": {
 		"loading": "Loading sources...",
 		"screens": "Screens ({{count}})",
diff --git a/src/i18n/locales/es/editor.json b/src/i18n/locales/es/editor.json
index 397a86298..68b3fbc2c 100644
--- a/src/i18n/locales/es/editor.json
+++ b/src/i18n/locales/es/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "Micrófono",
 		"camera": "Cámara",
 		"cursorHighlight": "Resaltar cursor",
+		"autoZoom": "Zoom automático tras grabar",
+		"autoZoomNeedsEditableCursor": "El zoom automático necesita el cursor editable. Cambia el modo del cursor para activarlo.",
 		"on": "Activado",
 		"off": "Desactivado",
 		"loading": "Cargando…",
diff --git a/src/i18n/locales/es/launch.json b/src/i18n/locales/es/launch.json
index 7a2c92a55..7fe44a485 100644
--- a/src/i18n/locales/es/launch.json
+++ b/src/i18n/locales/es/launch.json
@@ -56,6 +56,11 @@
 		"useEditableCursor": "Usar cursor editable",
 		"useSystemCursor": "Usar cursor del sistema"
 	},
+	"autoZoom": {
+		"enable": "Activar zoom automático tras grabar",
+		"disable": "Desactivar zoom automático tras grabar",
+		"needsEditableCursor": "El zoom automático necesita el cursor editable. Cambia el modo del cursor para activarlo."
+	},
 	"sourceSelector": {
 		"loading": "Cargando fuentes...",
 		"screens": "Pantallas ({{count}})",
diff --git a/src/i18n/locales/fr/editor.json b/src/i18n/locales/fr/editor.json
index dcc83218f..b38fff0b6 100644
--- a/src/i18n/locales/fr/editor.json
+++ b/src/i18n/locales/fr/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "Microphone",
 		"camera": "Caméra",
 		"cursorHighlight": "Curseur en surbrillance",
+		"autoZoom": "Zoom automatique après l'enregistrement",
+		"autoZoomNeedsEditableCursor": "Le zoom automatique nécessite le curseur modifiable. Changez le mode du curseur pour l'activer.",
 		"on": "Activé",
 		"off": "Désactivé",
 		"loading": "Chargement…",
diff --git a/src/i18n/locales/fr/launch.json b/src/i18n/locales/fr/launch.json
index 858fd58f1..a1819e350 100644
--- a/src/i18n/locales/fr/launch.json
+++ b/src/i18n/locales/fr/launch.json
@@ -56,6 +56,11 @@
 		"useEditableCursor": "Utiliser le curseur éditable",
 		"useSystemCursor": "Utiliser le curseur système"
 	},
+	"autoZoom": {
+		"enable": "Activer le zoom automatique après l'enregistrement",
+		"disable": "Désactiver le zoom automatique après l'enregistrement",
+		"needsEditableCursor": "Le zoom automatique nécessite le curseur modifiable. Changez le mode du curseur pour l'activer."
+	},
 	"sourceSelector": {
 		"loading": "Chargement des sources...",
 		"screens": "Écrans ({{count}})",
diff --git a/src/i18n/locales/it/editor.json b/src/i18n/locales/it/editor.json
index e343d482e..00a092ee7 100644
--- a/src/i18n/locales/it/editor.json
+++ b/src/i18n/locales/it/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "Microfono",
 		"camera": "Fotocamera",
 		"cursorHighlight": "Evidenzia cursore",
+		"autoZoom": "Zoom automatico dopo la registrazione",
+		"autoZoomNeedsEditableCursor": "Lo zoom automatico richiede il cursore modificabile. Cambia la modalità del cursore per attivarlo.",
 		"on": "Attivo",
 		"off": "Disattivo",
 		"loading": "Caricamento…",
diff --git a/src/i18n/locales/it/launch.json b/src/i18n/locales/it/launch.json
index ed5088d67..e4adbc465 100644
--- a/src/i18n/locales/it/launch.json
+++ b/src/i18n/locales/it/launch.json
@@ -56,6 +56,11 @@
 		"useEditableCursor": "Usa cursore modificabile",
 		"useSystemCursor": "Usa cursore di sistema"
 	},
+	"autoZoom": {
+		"enable": "Attiva lo zoom automatico dopo la registrazione",
+		"disable": "Disattiva lo zoom automatico dopo la registrazione",
+		"needsEditableCursor": "Lo zoom automatico richiede il cursore modificabile. Cambia la modalità del cursore per attivarlo."
+	},
 	"sourceSelector": {
 		"loading": "Caricamento sorgenti...",
 		"screens": "Schermi ({{count}})",
diff --git a/src/i18n/locales/ja-JP/editor.json b/src/i18n/locales/ja-JP/editor.json
index 239bc1287..b8f600334 100644
--- a/src/i18n/locales/ja-JP/editor.json
+++ b/src/i18n/locales/ja-JP/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "マイク",
 		"camera": "カメラ",
 		"cursorHighlight": "カーソルの強調表示",
+		"autoZoom": "録画後に自動ズーム",
+		"autoZoomNeedsEditableCursor": "自動ズームには編集可能なカーソルが必要です。カーソルモードを切り替えてください。",
 		"on": "オン",
 		"off": "オフ",
 		"loading": "読み込み中…",
diff --git a/src/i18n/locales/ja-JP/launch.json b/src/i18n/locales/ja-JP/launch.json
index ab9cebbd5..bf940cc04 100644
--- a/src/i18n/locales/ja-JP/launch.json
+++ b/src/i18n/locales/ja-JP/launch.json
@@ -56,6 +56,11 @@
 		"useEditableCursor": "編集可能なカーソルを使う",
 		"useSystemCursor": "システムカーソルを使う"
 	},
+	"autoZoom": {
+		"enable": "録画後の自動ズームをオンにする",
+		"disable": "録画後の自動ズームをオフにする",
+		"needsEditableCursor": "自動ズームには編集可能なカーソルが必要です。カーソルモードを切り替えてください。"
+	},
 	"sourceSelector": {
 		"loading": "ソースを読み込み中...",
 		"screens": "画面 ({{count}})",
diff --git a/src/i18n/locales/ko-KR/editor.json b/src/i18n/locales/ko-KR/editor.json
index 8dd4be036..2f382d135 100644
--- a/src/i18n/locales/ko-KR/editor.json
+++ b/src/i18n/locales/ko-KR/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "마이크",
 		"camera": "카메라",
 		"cursorHighlight": "커서 강조",
+		"autoZoom": "녹화 후 자동 확대",
+		"autoZoomNeedsEditableCursor": "자동 확대는 편집 가능한 커서가 필요합니다. 커서 모드를 전환하세요.",
 		"on": "켜짐",
 		"off": "꺼짐",
 		"loading": "로딩 중…",
diff --git a/src/i18n/locales/ko-KR/launch.json b/src/i18n/locales/ko-KR/launch.json
index 192089224..6e13f7ba5 100644
--- a/src/i18n/locales/ko-KR/launch.json
+++ b/src/i18n/locales/ko-KR/launch.json
@@ -56,6 +56,11 @@
 		"useEditableCursor": "편집 가능한 커서 사용",
 		"useSystemCursor": "시스템 커서 사용"
 	},
+	"autoZoom": {
+		"enable": "녹화 후 자동 확대 켜기",
+		"disable": "녹화 후 자동 확대 끄기",
+		"needsEditableCursor": "자동 확대는 편집 가능한 커서가 필요합니다. 커서 모드를 전환하세요."
+	},
 	"sourceSelector": {
 		"loading": "소스 불러오는 중...",
 		"screens": "화면 ({{count}}개)",
diff --git a/src/i18n/locales/pt-BR/editor.json b/src/i18n/locales/pt-BR/editor.json
index 5a6219e6c..7bdb2a2d4 100644
--- a/src/i18n/locales/pt-BR/editor.json
+++ b/src/i18n/locales/pt-BR/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "Microfone",
 		"camera": "Câmera",
 		"cursorHighlight": "Destaque do cursor",
+		"autoZoom": "Zoom automático após a gravação",
+		"autoZoomNeedsEditableCursor": "O zoom automático precisa do cursor editável. Alterne o modo do cursor para ativar.",
 		"on": "Ativado",
 		"off": "Desativado",
 		"loading": "Carregando…",
diff --git a/src/i18n/locales/pt-BR/launch.json b/src/i18n/locales/pt-BR/launch.json
index 4d1fc9270..a10645385 100644
--- a/src/i18n/locales/pt-BR/launch.json
+++ b/src/i18n/locales/pt-BR/launch.json
@@ -56,6 +56,11 @@
 		"useEditableCursor": "Usar cursor editável",
 		"useSystemCursor": "Usar cursor do sistema"
 	},
+	"autoZoom": {
+		"enable": "Ativar zoom automático após a gravação",
+		"disable": "Desativar zoom automático após a gravação",
+		"needsEditableCursor": "O zoom automático precisa do cursor editável. Alterne o modo do cursor para ativar."
+	},
 	"sourceSelector": {
 		"loading": "Carregando fontes...",
 		"screens": "Telas ({{count}})",
diff --git a/src/i18n/locales/ru/editor.json b/src/i18n/locales/ru/editor.json
index 86830571b..dd531e56b 100644
--- a/src/i18n/locales/ru/editor.json
+++ b/src/i18n/locales/ru/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "Микрофон",
 		"camera": "Камера",
 		"cursorHighlight": "Подсветка курсора",
+		"autoZoom": "Автомасштабирование после записи",
+		"autoZoomNeedsEditableCursor": "Автомасштабирование требует редактируемый курсор. Переключите режим курсора.",
 		"on": "Вкл",
 		"off": "Выкл",
 		"loading": "Загрузка…",
diff --git a/src/i18n/locales/ru/launch.json b/src/i18n/locales/ru/launch.json
index 0af9564c4..67fb6f637 100644
--- a/src/i18n/locales/ru/launch.json
+++ b/src/i18n/locales/ru/launch.json
@@ -78,6 +78,11 @@
 		"useEditableCursor": "Использовать редактируемый курсор",
 		"useSystemCursor": "Использовать системный курсор"
 	},
+	"autoZoom": {
+		"enable": "Включить автомасштабирование после записи",
+		"disable": "Отключить автомасштабирование после записи",
+		"needsEditableCursor": "Автомасштабирование требует редактируемый курсор. Переключите режим курсора."
+	},
 	"softwareEncoderFallback": {
 		"title": "Выполнен переход на программное кодирование",
 		"description": "Стандартный GPU-кодировщик не запустился, поэтому OpenScreen перешёл на программное кодирование H.264. Запись продолжится как обычно, но нагрузка на процессор может быть выше.",
diff --git a/src/i18n/locales/tr/editor.json b/src/i18n/locales/tr/editor.json
index cb1c1906e..b94ba0e84 100644
--- a/src/i18n/locales/tr/editor.json
+++ b/src/i18n/locales/tr/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "Mikrofon",
 		"camera": "Kamera",
 		"cursorHighlight": "İmleç vurgusu",
+		"autoZoom": "Kayıttan sonra otomatik yakınlaştırma",
+		"autoZoomNeedsEditableCursor": "Otomatik yakınlaştırma düzenlenebilir imleç ister. Etkinleştirmek için imleç modunu değiştirin.",
 		"on": "Açık",
 		"off": "Kapalı",
 		"loading": "Yükleniyor…",
diff --git a/src/i18n/locales/tr/launch.json b/src/i18n/locales/tr/launch.json
index 632709c82..a5b84df60 100644
--- a/src/i18n/locales/tr/launch.json
+++ b/src/i18n/locales/tr/launch.json
@@ -56,6 +56,11 @@
 		"useEditableCursor": "Düzenlenebilir imleci kullan",
 		"useSystemCursor": "Sistem imlecini kullan"
 	},
+	"autoZoom": {
+		"enable": "Kayıttan sonra otomatik yakınlaştırmayı aç",
+		"disable": "Kayıttan sonra otomatik yakınlaştırmayı kapat",
+		"needsEditableCursor": "Otomatik yakınlaştırma düzenlenebilir imleç ister. Etkinleştirmek için imleç modunu değiştirin."
+	},
 	"sourceSelector": {
 		"loading": "Kaynaklar yükleniyor...",
 		"screens": "Ekranlar ({{count}})",
diff --git a/src/i18n/locales/vi/editor.json b/src/i18n/locales/vi/editor.json
index 9f484688c..59ba3489b 100644
--- a/src/i18n/locales/vi/editor.json
+++ b/src/i18n/locales/vi/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "Micro",
 		"camera": "Máy ảnh",
 		"cursorHighlight": "Làm nổi bật con trỏ",
+		"autoZoom": "Tự động phóng to sau khi ghi",
+		"autoZoomNeedsEditableCursor": "Tự động phóng to cần con trỏ chỉnh sửa được. Hãy đổi chế độ con trỏ.",
 		"on": "Bật",
 		"off": "Tắt",
 		"loading": "Đang tải…",
diff --git a/src/i18n/locales/vi/launch.json b/src/i18n/locales/vi/launch.json
index 98405bf99..e4997af28 100644
--- a/src/i18n/locales/vi/launch.json
+++ b/src/i18n/locales/vi/launch.json
@@ -78,6 +78,11 @@
 		"useEditableCursor": "Dùng con trỏ có thể chỉnh sửa",
 		"useSystemCursor": "Dùng con trỏ hệ thống"
 	},
+	"autoZoom": {
+		"enable": "Bật tự động phóng to sau khi ghi",
+		"disable": "Tắt tự động phóng to sau khi ghi",
+		"needsEditableCursor": "Tự động phóng to cần con trỏ chỉnh sửa được. Hãy đổi chế độ con trỏ."
+	},
 	"softwareEncoderFallback": {
 		"title": "Đã chuyển sang mã hóa bằng phần mềm",
 		"description": "Bộ mã hóa GPU mặc định không khởi động được, nên OpenScreen đã chuyển sang mã hóa H.264 bằng phần mềm. Quá trình ghi vẫn tiếp tục bình thường, nhưng mức sử dụng CPU có thể cao hơn.",
diff --git a/src/i18n/locales/zh-CN/editor.json b/src/i18n/locales/zh-CN/editor.json
index 0405b5c13..7c3a6d98e 100644
--- a/src/i18n/locales/zh-CN/editor.json
+++ b/src/i18n/locales/zh-CN/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "麦克风",
 		"camera": "摄像头",
 		"cursorHighlight": "光标高亮",
+		"autoZoom": "录制后自动缩放",
+		"autoZoomNeedsEditableCursor": "自动缩放需要可编辑光标。请先切换光标模式。",
 		"on": "开",
 		"off": "关",
 		"loading": "加载中…",
diff --git a/src/i18n/locales/zh-CN/launch.json b/src/i18n/locales/zh-CN/launch.json
index e7efe8eec..521591aaa 100644
--- a/src/i18n/locales/zh-CN/launch.json
+++ b/src/i18n/locales/zh-CN/launch.json
@@ -56,6 +56,11 @@
 		"useEditableCursor": "使用可编辑光标",
 		"useSystemCursor": "使用系统光标"
 	},
+	"autoZoom": {
+		"enable": "启用录制后自动缩放",
+		"disable": "关闭录制后自动缩放",
+		"needsEditableCursor": "自动缩放需要可编辑光标。请先切换光标模式。"
+	},
 	"sourceSelector": {
 		"loading": "正在加载源...",
 		"screens": "屏幕 ({{count}})",
diff --git a/src/i18n/locales/zh-TW/editor.json b/src/i18n/locales/zh-TW/editor.json
index f4d10694f..fefdaf004 100644
--- a/src/i18n/locales/zh-TW/editor.json
+++ b/src/i18n/locales/zh-TW/editor.json
@@ -110,6 +110,8 @@
 		"microphone": "麥克風",
 		"camera": "攝影機",
 		"cursorHighlight": "游標醒目提示",
+		"autoZoom": "錄製後自動縮放",
+		"autoZoomNeedsEditableCursor": "自動縮放需要可編輯游標。請先切換游標模式。",
 		"on": "開",
 		"off": "關",
 		"loading": "載入中…",
diff --git a/src/i18n/locales/zh-TW/launch.json b/src/i18n/locales/zh-TW/launch.json
index 025e422e7..9e6361bd8 100644
--- a/src/i18n/locales/zh-TW/launch.json
+++ b/src/i18n/locales/zh-TW/launch.json
@@ -56,6 +56,11 @@
 		"useEditableCursor": "使用可編輯游標",
 		"useSystemCursor": "使用系統游標"
 	},
+	"autoZoom": {
+		"enable": "啟用錄製後自動縮放",
+		"disable": "關閉錄製後自動縮放",
+		"needsEditableCursor": "自動縮放需要可編輯游標。請先切換游標模式。"
+	},
 	"sourceSelector": {
 		"loading": "正在載入來源...",
 		"screens": "螢幕 ({{count}})",

From 0c4961c03af1d0ad8077b2d8e67939f26117a96f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 22:10:27 +0800
Subject: [PATCH 12/14] feat(editor): run the fresh-take auto-zoom pass on the
 metadata write queue
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The suggestion pass has to run once the document is ready, and "ready" is the
`loadedmetadata` write that folds the probed duration in. So it goes on the same
queued task as that write rather than after it: on `useSequentialTimelineOps`,
the suggestions are serialised against the user's own edits, not just against
other metadata events.

The step moves out of the callback closure into `runLoadedMetadataWrite` so it
can be tested at all — the event only reaches the shell through Preview,
PreviewCanvas, VirtualPreview and a real `<video>` decoding real media. Three
things it does that the closure could not be asked about:

- The save is bounded. It is awaited so the queue can serialise it, which means a
  bridge call that never answers would hold the queue slot and every edit behind
  it. Removing the deadline does not make that test fail on a value; it makes it
  never finish.
- Project ownership is re-checked AFTER the save, not only before. That await is
  exactly when a switch lands. It would not write zooms into the other project —
  the pending-path guard refuses that — but the passes before that guard still
  clear the pending flag on whatever document they are handed, silently
  cancelling the auto-zoom for the take that was actually imported.
- A duration that is not a real measurement seeds a placeholder clip without
  being recorded as the asset's duration. MediaRecorder WebMs report NaN until
  the EBML fix lands; auto-zoom keys off that field and would otherwise act on a
  length nothing measured.
---
 .../NewEditorShell.loadedMetadata.test.ts     | 183 ++++++++++++++++++
 .../NewEditorShell.probedDuration.test.tsx    |  45 +++++
 src/components/ai-edition/NewEditorShell.tsx  | 118 ++++++++---
 .../store/documentWriteAudit.test.ts          |  13 +-
 4 files changed, 328 insertions(+), 31 deletions(-)
 create mode 100644 src/components/ai-edition/NewEditorShell.loadedMetadata.test.ts

diff --git a/src/components/ai-edition/NewEditorShell.loadedMetadata.test.ts b/src/components/ai-edition/NewEditorShell.loadedMetadata.test.ts
new file mode 100644
index 000000000..f9c869553
--- /dev/null
+++ b/src/components/ai-edition/NewEditorShell.loadedMetadata.test.ts
@@ -0,0 +1,183 @@
+// What one `loadedmetadata` event does once it reaches the front of the queue.
+//
+// The queue is why this is worth its own test: the shell puts this step on
+// `useSequentialTimelineOps` alongside the user's own edits, so a step that never
+// finishes holds that queue — and everything behind it. The pure decision
+// (`documentAfterProbedDuration`) is covered next door; this covers what surrounds
+// it — the guards, the bounded save, and what the auto-zoom pass is handed.
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@/contexts/ShortcutsContext", async () => {
+	const { DEFAULT_SHORTCUTS } = await import("@/lib/shortcuts");
+	return {
+		useShortcuts: () => ({
+			shortcuts: DEFAULT_SHORTCUTS,
+			isMac: false,
+			isConfigOpen: false,
+			openConfig: vi.fn(),
+			closeConfig: vi.fn(),
+			setShortcuts: vi.fn(),
+			persistShortcuts: () => Promise.resolve(true),
+		}),
+	};
+});
+
+vi.mock("@/contexts/I18nContext", () => ({
+	useI18n: () => ({ locale: "en", setLocale: vi.fn() }),
+	useScopedT: () => (key: string) => key,
+}));
+
+import { type AxcutDocument, createEmptyDocument } from "@/lib/ai-edition/schema";
+import { useProjectStore } from "@/lib/ai-edition/store/projectStore";
+import { runLoadedMetadataWrite } from "./NewEditorShell";
+
+const PROJECT = "proj_a";
+
+/** A fresh import: one video asset on the document, nothing on the timeline yet. */
+function freshImport(): AxcutDocument {
+	const doc = createEmptyDocument({ projectId: PROJECT, title: "A" });
+	return {
+		...doc,
+		project: { ...doc.project, primaryAssetId: "asset_1" },
+		assets: [
+			{
+				id: "asset_1",
+				kind: "video",
+				label: "screen.mp4",
+				originalPath: "/tmp/screen.mp4",
+				cameraTrack: null,
+			},
+		],
+	};
+}
+
+/** Stands in for a save that answers, installing its result the way the real one does. */
+function settlingSave() {
+	return vi.fn(async (document: AxcutDocument) => {
+		useProjectStore.setState({ document });
+		return true;
+	});
+}
+
+describe("runLoadedMetadataWrite", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		useProjectStore.setState({ document: freshImport() });
+	});
+
+	it("folds the probed length in and hands auto-zoom the saved document", async () => {
+		const saveDocument = settlingSave();
+		useProjectStore.setState({ saveDocument });
+		const autoZoom = vi.fn(async () => undefined);
+
+		await runLoadedMetadataWrite(12.5, "asset_1", PROJECT, { autoZoom });
+
+		expect(saveDocument).toHaveBeenCalledTimes(1);
+		const saved = saveDocument.mock.calls[0][0];
+		expect(saved.timeline.clips).toHaveLength(1);
+		expect(saved.assets[0].durationSec).toBe(12.5);
+		// Not the pre-save snapshot: auto-zoom appends to whatever is on the store now.
+		expect(autoZoom).toHaveBeenCalledWith(useProjectStore.getState().document);
+		expect(useProjectStore.getState().document?.timeline.clips).toHaveLength(1);
+	});
+
+	// THE reason the save is bounded. `saveDocument` awaits the bridge with no
+	// deadline of its own and never rejects, so a main process that stops answering
+	// leaves this step pending for the life of the renderer — and every edit queued
+	// behind it waits with it, this take's auto-zoom included. Without the deadline
+	// this test does not fail with a wrong value, it never finishes.
+	it("gives up on a save that never answers instead of holding the queue", async () => {
+		const saveDocument = vi.fn(() => new Promise<boolean>(() => undefined));
+		useProjectStore.setState({ saveDocument });
+		const autoZoom = vi.fn(async () => undefined);
+
+		await runLoadedMetadataWrite(12.5, "asset_1", PROJECT, { autoZoom, saveTimeoutMs: 20 });
+
+		expect(saveDocument).toHaveBeenCalledTimes(1);
+		// The step let go and carried on, with the document the store actually holds
+		// — the stuck write never installed one.
+		expect(autoZoom).toHaveBeenCalledTimes(1);
+		expect(useProjectStore.getState().document?.timeline.clips).toHaveLength(0);
+	});
+
+	// The switch that happens DURING the save, which the guard at the top cannot
+	// see. Auto-zoom would not write zooms into the new project — the pending-path
+	// guard refuses it — but the passes before that check clear the pending flag on
+	// whatever document they are handed, so the take that was actually imported
+	// would lose its auto-zoom without a trace.
+	it("stops when the project changes while the save is in flight", async () => {
+		// Carrying assets on purpose: an assetless document is turned away a line
+		// later for a different reason, and this test would then pass without the
+		// ownership check it exists to cover.
+		const other = { ...freshImport(), project: { ...freshImport().project, id: "proj_b" } };
+		const saveDocument = vi.fn(async () => {
+			useProjectStore.setState({ document: other });
+			return true;
+		});
+		useProjectStore.setState({ saveDocument });
+		const autoZoom = vi.fn(async () => undefined);
+
+		await runLoadedMetadataWrite(12.5, "asset_1", PROJECT, { autoZoom });
+
+		expect(saveDocument).toHaveBeenCalledTimes(1);
+		expect(autoZoom).not.toHaveBeenCalled();
+	});
+
+	// Same for the project being closed outright: there is nothing left for this
+	// event to belong to, and the pre-switch snapshot is not a stand-in for it.
+	it("stops when the project is closed while the save is in flight", async () => {
+		const saveDocument = vi.fn(async () => {
+			useProjectStore.setState({ document: null });
+			return true;
+		});
+		useProjectStore.setState({ saveDocument });
+		const autoZoom = vi.fn(async () => undefined);
+
+		await runLoadedMetadataWrite(12.5, "asset_1", PROJECT, { autoZoom });
+
+		expect(autoZoom).not.toHaveBeenCalled();
+	});
+
+	// The event is bound to the project that owned the video when it fired, and the
+	// queue puts real time between the two.
+	it("writes nothing when the project changed before it ran", async () => {
+		const saveDocument = settlingSave();
+		useProjectStore.setState({ saveDocument });
+		const autoZoom = vi.fn(async () => undefined);
+
+		await runLoadedMetadataWrite(12.5, "asset_1", "proj_switched_away_from", { autoZoom });
+
+		expect(saveDocument).not.toHaveBeenCalled();
+		expect(autoZoom).not.toHaveBeenCalled();
+	});
+
+	it("writes nothing without a document, or without assets", async () => {
+		const saveDocument = settlingSave();
+		const autoZoom = vi.fn(async () => undefined);
+
+		useProjectStore.setState({ document: null, saveDocument });
+		await runLoadedMetadataWrite(12.5, "asset_1", PROJECT, { autoZoom });
+
+		const empty = createEmptyDocument({ projectId: PROJECT, title: "A" });
+		useProjectStore.setState({ document: empty, saveDocument });
+		await runLoadedMetadataWrite(12.5, "asset_1", PROJECT, { autoZoom });
+
+		expect(saveDocument).not.toHaveBeenCalled();
+		expect(autoZoom).not.toHaveBeenCalled();
+	});
+
+	// Nothing to fold in is not a reason to skip auto-zoom: a second event for a
+	// document that already has its length still has to let the suggestion pass run.
+	it("still runs auto-zoom when the document needs no write", async () => {
+		const saveDocument = settlingSave();
+		useProjectStore.setState({ saveDocument });
+		const autoZoom = vi.fn(async () => undefined);
+
+		await runLoadedMetadataWrite(12.5, "asset_1", PROJECT, { autoZoom });
+		saveDocument.mockClear();
+		await runLoadedMetadataWrite(12.5, "asset_1", PROJECT, { autoZoom });
+
+		expect(saveDocument).not.toHaveBeenCalled();
+		expect(autoZoom).toHaveBeenCalledTimes(2);
+	});
+});
diff --git a/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx b/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
index 284cdf65e..238920cfd 100644
--- a/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
+++ b/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
@@ -29,6 +29,7 @@ vi.mock("@/contexts/I18nContext", () => ({
 }));
 
 import { migrateProjectDataToAxcutDocument } from "@/lib/ai-edition/document/migrate";
+import { PLACEHOLDER_DURATION_SEC } from "@/lib/ai-edition/document/timeline";
 import { type AxcutDocument, createEmptyDocument, documentSchema } from "@/lib/ai-edition/schema";
 import { documentAfterProbedDuration } from "./NewEditorShell";
 
@@ -123,6 +124,50 @@ describe("documentAfterProbedDuration", () => {
 		).toBeNull();
 	});
 
+	// MediaRecorder WebMs report NaN/Infinity until the main-process EBML fix lands.
+	// A clip still has to be seeded — an empty timeline is worse than a wrong length —
+	// but 60 is a placeholder, not a measurement, so it must not be filed as the
+	// asset's probed duration. Auto-zoom keys off that field and would otherwise act
+	// on a length nothing measured.
+	it("seeds a placeholder clip from an unusable duration without recording it", () => {
+		const doc = emptyTimeline("asset_1", ["asset_1"]);
+
+		for (const bad of [Number.NaN, Number.POSITIVE_INFINITY, 0, -1]) {
+			const next = documentAfterProbedDuration(doc, "asset_1", bad, PROJECT);
+			expect(next?.timeline.clips).toHaveLength(1);
+			expect(next?.timeline.clips[0].timelineEndSec).toBe(PLACEHOLDER_DURATION_SEC);
+			expect(next?.assets[0].durationSec).toBeUndefined();
+		}
+	});
+
+	// …and once a timeline exists, an unusable duration has nothing to fold in: the
+	// placeholder above only exists so the FIRST clip is not empty.
+	it("writes nothing into an existing timeline from an unusable duration", () => {
+		const seeded = documentAfterProbedDuration(
+			emptyTimeline("asset_1", ["asset_1"]),
+			"asset_1",
+			Number.NaN,
+			PROJECT,
+		) as AxcutDocument;
+
+		expect(documentAfterProbedDuration(seeded, "asset_1", Number.NaN, PROJECT)).toBeNull();
+	});
+
+	// The real length arriving later replaces the placeholder.
+	it("replaces a placeholder clip once a real duration arrives", () => {
+		const seeded = documentAfterProbedDuration(
+			emptyTimeline("asset_1", ["asset_1"]),
+			"asset_1",
+			Number.NaN,
+			PROJECT,
+		) as AxcutDocument;
+
+		const next = documentAfterProbedDuration(seeded, "asset_1", 8, PROJECT);
+
+		expect(next?.timeline.clips[0].sourceEndSec).toBe(8);
+		expect(next?.assets[0].durationSec).toBe(8);
+	});
+
 	it("writes nothing without a document or without assets", () => {
 		expect(documentAfterProbedDuration(null, "asset_1", 30, PROJECT)).toBeNull();
 		expect(
diff --git a/src/components/ai-edition/NewEditorShell.tsx b/src/components/ai-edition/NewEditorShell.tsx
index 34810eea7..ab7cbed39 100644
--- a/src/components/ai-edition/NewEditorShell.tsx
+++ b/src/components/ai-edition/NewEditorShell.tsx
@@ -16,6 +16,7 @@ import {
 } from "@/lib/ai-edition/document/migrate";
 import {
 	applyProbedDuration,
+	PLACEHOLDER_DURATION_SEC,
 	replaceTimeline as replaceTimelineOp,
 } from "@/lib/ai-edition/document/timeline";
 import {
@@ -31,7 +32,7 @@ import {
 	type AxcutDocument,
 	documentSchema,
 } from "@/lib/ai-edition/schema";
-import { useProjectStore } from "@/lib/ai-edition/store/projectStore";
+import { saveWithDeadline, useProjectStore } from "@/lib/ai-edition/store/projectStore";
 import {
 	useAssetTranscriptions,
 	useAutoTranscription,
@@ -66,7 +67,7 @@ import {
 	type UnsavedChoice,
 } from "./Modals";
 import { Preview } from "./Preview";
-import { importPendingRecording } from "./recordingImport";
+import { importPendingRecording, maybeSaveFreshRecordingAutoZooms } from "./recordingImport";
 import { AddAudioLayerDialog } from "./v4/AddAudioLayerDialog";
 import v4 from "./v4/EditorShellV4.module.css";
 import { type EditorMode, EditorTopBar } from "./v4/EditorTopBar";
@@ -137,11 +138,17 @@ export const MAX_TIMELINE_HEIGHT_PX = 560;
 export function documentAfterProbedDuration(
 	doc: AxcutDocument | null,
 	assetId: string,
-	knownSec: number,
+	durationSec: number,
 	originatingProjectId: string | undefined,
 ): AxcutDocument | null {
 	if (!doc || doc.assets.length === 0) return null;
 	if (doc.project.id !== originatingProjectId) return null;
+	// ponytail: WebM recordings from MediaRecorder report NaN/Infinity until the
+	// main-process EBML fix lands. A seed still has to happen — an empty timeline is
+	// worse than a wrong length — but 60 is a placeholder, not a measurement, so it
+	// is not written to `asset.durationSec`. Auto-zoom waits for a real probe.
+	const finite = Number.isFinite(durationSec) && durationSec > 0;
+	const knownSec = finite ? durationSec : PLACEHOLDER_DURATION_SEC;
 	if (doc.timeline.clips.length === 0) {
 		// ponytail: replaceTimeline derives clip length from asset.durationSec, which
 		// import never populates — without this the first auto-created clip silently
@@ -158,12 +165,24 @@ export function documentAfterProbedDuration(
 				a.id === primaryAssetId ? { ...a, durationSec: knownSec } : a,
 			),
 		};
-		return replaceTimelineOp(
+		const withClip = replaceTimelineOp(
 			docWithDuration,
 			[{ startSec: 0, endSec: knownSec }],
 			"Auto-created full-duration clip",
 		);
+		if (finite) return withClip;
+		return {
+			...withClip,
+			assets: withClip.assets.map((asset) => {
+				if (asset.id !== primaryAssetId) return asset;
+				const { durationSec: _placeholder, ...rest } = asset;
+				return rest;
+			}),
+		};
 	}
+	// Nothing to fold into an existing timeline without a real length: the
+	// placeholder above exists only so the first clip is not empty.
+	if (!finite) return null;
 	// The pure document layer patches only the clips of THIS asset that are still
 	// waiting for a real length (the pre-probe placeholder, or the extent-less clip a
 	// legacy v2 import mints), shifts what follows, and brings the modifiers along —
@@ -173,6 +192,61 @@ export function documentAfterProbedDuration(
 	return next === doc ? null : next;
 }
 
+/**
+ * What one `loadedmetadata` event does, from the front of the write queue.
+ *
+ * Exported because it is only reachable from outside the component: the event
+ * arrives through Preview, PreviewCanvas, VirtualPreview and a real `<video>`
+ * decoding real media, which no test environment here provides.
+ *
+ * Every store read is at call time, not from a closure. By the time this runs the
+ * document may have moved on, and `originatingProjectId` is what says whether it
+ * moved to a different project.
+ */
+export async function runLoadedMetadataWrite(
+	durationSec: number,
+	assetId: string,
+	originatingProjectId: string | undefined,
+	deps: {
+		/** Defaults to the real auto-zoom pass; injected in tests. */
+		autoZoom?: (document: AxcutDocument) => Promise<unknown>;
+		saveTimeoutMs?: number;
+	} = {},
+): Promise<void> {
+	const state = useProjectStore.getState();
+	const next = documentAfterProbedDuration(
+		state.document,
+		assetId,
+		durationSec,
+		originatingProjectId,
+	);
+	if (next) {
+		// `history: false`: this is the probed duration being folded into the document
+		// on load, not something the user did — an undo landing on it would empty their
+		// timeline. Auto-zoom below is a later, undoable suggestion.
+		//
+		// Awaited so the queue can serialise it, but bounded: `saveDocument` awaits the
+		// bridge with no deadline of its own and never rejects, so a main process that
+		// stops answering would hold this queue slot — and every edit behind it — for
+		// the life of the renderer. The abandoned write is safe to let go of.
+		await saveWithDeadline(state.saveDocument(next, { history: false }), deps.saveTimeoutMs);
+	}
+	// Re-checked rather than assumed: the await above is exactly when a project
+	// switch lands, and the check inside the decision spoke only for the document as
+	// it was before it. Handing the auto-zoom pass another project's document would
+	// not write zooms into it — `canApplyFreshRecordingAutoZooms` refuses a document
+	// that does not hold the pending recording — but the passes before that check DO
+	// clear the pending flag on what they are given, so the take that was actually
+	// imported would silently lose its auto-zoom. A closed project ends the step for
+	// the same reason: there is nothing left this event belongs to.
+	const settled = useProjectStore.getState().document;
+	if (!settled || settled.project.id !== originatingProjectId) return;
+	// A document with no assets has no take to suggest zooms for. The auto-zoom pass
+	// would refuse it anyway; not calling it keeps "nothing to do" meaning nothing.
+	if (settled.assets.length === 0) return;
+	await (deps.autoZoom ?? maybeSaveFreshRecordingAutoZooms)(settled);
+}
+
 export function NewEditorShell() {
 	const te = useScopedT("editor");
 	const document = useProjectStore((s) => s.document);
@@ -481,14 +555,10 @@ export function NewEditorShell() {
 
 	const handleLoadedMetadata = useCallback(
 		(durationSec: number, assetId: string) => {
-			// ponytail: WebM recordings from MediaRecorder report NaN/Infinity
-			// until the main-process EBML fix lands. Fall back to a 60s seed if
-			// duration is unknown so the timeline never gets stuck on an empty
-			// placeholder.
-			const known = Number.isFinite(durationSec) && durationSec > 0 ? durationSec : 60;
-			setSourceDuration(known);
-			// Read before queueing: this is the project the event belongs to. What the
-			// decision does with it is `documentAfterProbedDuration`'s business.
+			setSourceDuration(
+				Number.isFinite(durationSec) && durationSec > 0 ? durationSec : PLACEHOLDER_DURATION_SEC,
+			);
+			// Read before queueing: this is the project the event belongs to.
 			const originatingProjectId = useProjectStore.getState().document?.project.id;
 			// On the shared write queue, and reading the document inside it. Folding a
 			// probed duration in is a read-modify-write of the whole document, which is
@@ -497,24 +567,12 @@ export function NewEditorShell() {
 			// returns the PRE-edit document while a user's save is still in flight (the
 			// store is only written once the bridge answers), and the full snapshot built
 			// from it lands after theirs and takes their edit with it.
-			void enqueueTimelineWrite(async () => {
-				const state = useProjectStore.getState();
-				const next = documentAfterProbedDuration(
-					state.document,
-					assetId,
-					known,
-					originatingProjectId,
-				);
-				if (!next) return;
-				// `history: false`: this is the probed duration being folded into the
-				// document on load, not something the user did — an undo landing on it would
-				// empty their timeline.
-				//
-				// Awaited, not `void`ed: the queue only serialises what it can see finish, so
-				// a fire-and-forget write would let the next queued edit read a document this
-				// one has not committed yet.
-				await state.saveDocument(next, { history: false });
-			});
+			//
+			// The auto-zoom pass goes on the same queued task rather than after it, so a
+			// fresh take's suggestions are serialised against user edits too.
+			void enqueueTimelineWrite(() =>
+				runLoadedMetadataWrite(durationSec, assetId, originatingProjectId),
+			);
 		},
 		[setSourceDuration, enqueueTimelineWrite],
 	);
diff --git a/src/lib/ai-edition/store/documentWriteAudit.test.ts b/src/lib/ai-edition/store/documentWriteAudit.test.ts
index 4a58c0fb6..fa6f62a48 100644
--- a/src/lib/ai-edition/store/documentWriteAudit.test.ts
+++ b/src/lib/ai-edition/store/documentWriteAudit.test.ts
@@ -125,7 +125,18 @@ const DECLARED: WritePath[] = [
 	w("src/components/ai-edition/NewEditorShell.tsx", "handleConfirmUnsaved", "save", "gesture"),
 	// The probed duration folded into the document when the <video> loads. Twice:
 	// the first clip seed, and the backfill for clips still on a placeholder length.
-	w("src/components/ai-edition/NewEditorShell.tsx", "handleLoadedMetadata", "save", "automatic"),
+	// It sits in `runLoadedMetadataWrite` rather than the handler because the handler
+	// only puts it on the write queue — the write itself, and its deadline, are there.
+	w("src/components/ai-edition/NewEditorShell.tsx", "runLoadedMetadataWrite", "save", "automatic"),
+	// Auto-zoom regions suggested for a freshly imported recording. `history: true`
+	// on purpose: unlike the probed duration above, this is a suggestion the user is
+	// meant to be able to undo.
+	w(
+		"src/components/ai-edition/recordingImport.ts",
+		"writeFreshRecordingAutoZooms",
+		"save",
+		"gesture",
+	),
 	// Renaming the project from the title field.
 	w("src/components/ai-edition/NewEditorShell.tsx", "handleRenameProject", "save", "gesture"),
 	// Ctrl+S / File > Save.

From c5ca6d62fc1b19538979d67a83c46ef9aa58a0d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 22:54:31 +0800
Subject: [PATCH 13/14] fix(editor): keep the placeholder duration on the
 asset, and off auto-zoom
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The seed for a take whose container reports no duration wrote a placeholder clip
and then removed `durationSec` from the asset, on the theory that 60 is not a
measurement and auto-zoom should wait for a real probe. The theory was right; the
mechanism was wrong, and it broke something bigger.

`primaryAssetDuration` returns 0 for an asset with no duration, and every
interval the timeline layer builds is clamped against it —
`planTimelineReplacement` included. So the next `replaceTimeline` on that
document clamps to zero, drops every clip and persists an empty timeline. For a
MediaRecorder WebM, whose later `loadedmetadata` events are non-finite too,
nothing ever repairs it.

So the placeholder goes back on the asset, which is what the timeline layer needs
and what main already does, and auto-zoom stops relying on that field: it asks
the clips instead, through the `clipAwaitsProbedDuration` the document layer
already uses for exactly this question. The cost is that a take of exactly
60.000 s is never auto-zoomed — the same ambiguity `applyProbedDuration` lives
with, and much cheaper than either an emptied timeline or zooms suggested against
a length nothing measured.

The regression test is the one that matters: seed from a non-finite duration,
run a timeline write over the result, and assert the clip survives.
---
 .../NewEditorShell.probedDuration.test.tsx    | 32 ++++++++++---
 src/components/ai-edition/NewEditorShell.tsx  | 20 ++++----
 src/components/ai-edition/recordingImport.ts  | 48 +++++++++++++------
 src/lib/ai-edition/document/timeline.ts       |  2 +-
 4 files changed, 67 insertions(+), 35 deletions(-)

diff --git a/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx b/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
index 238920cfd..77f16e801 100644
--- a/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
+++ b/src/components/ai-edition/NewEditorShell.probedDuration.test.tsx
@@ -29,7 +29,7 @@ vi.mock("@/contexts/I18nContext", () => ({
 }));
 
 import { migrateProjectDataToAxcutDocument } from "@/lib/ai-edition/document/migrate";
-import { PLACEHOLDER_DURATION_SEC } from "@/lib/ai-edition/document/timeline";
+import { PLACEHOLDER_DURATION_SEC, replaceTimeline } from "@/lib/ai-edition/document/timeline";
 import { type AxcutDocument, createEmptyDocument, documentSchema } from "@/lib/ai-edition/schema";
 import { documentAfterProbedDuration } from "./NewEditorShell";
 
@@ -125,21 +125,39 @@ describe("documentAfterProbedDuration", () => {
 	});
 
 	// MediaRecorder WebMs report NaN/Infinity until the main-process EBML fix lands.
-	// A clip still has to be seeded — an empty timeline is worse than a wrong length —
-	// but 60 is a placeholder, not a measurement, so it must not be filed as the
-	// asset's probed duration. Auto-zoom keys off that field and would otherwise act
-	// on a length nothing measured.
-	it("seeds a placeholder clip from an unusable duration without recording it", () => {
+	// A clip still has to be seeded — an empty timeline is worse than a wrong length.
+	// The placeholder goes on the asset too, and that is not sloppiness: the timeline
+	// layer clamps every interval it builds against `primaryAssetDuration`, so an
+	// asset with no duration makes the NEXT `replaceTimeline` clamp to zero, drop
+	// every clip, and persist an empty timeline. Auto-zoom is kept honest elsewhere,
+	// by asking the clips rather than this field.
+	it("seeds a placeholder clip from an unusable duration", () => {
 		const doc = emptyTimeline("asset_1", ["asset_1"]);
 
 		for (const bad of [Number.NaN, Number.POSITIVE_INFINITY, 0, -1]) {
 			const next = documentAfterProbedDuration(doc, "asset_1", bad, PROJECT);
 			expect(next?.timeline.clips).toHaveLength(1);
 			expect(next?.timeline.clips[0].timelineEndSec).toBe(PLACEHOLDER_DURATION_SEC);
-			expect(next?.assets[0].durationSec).toBeUndefined();
+			expect(next?.assets[0].durationSec).toBe(PLACEHOLDER_DURATION_SEC);
 		}
 	});
 
+	// The reason the line above matters: a seeded placeholder document has to survive
+	// the next timeline write. With no duration on the asset this comes back empty.
+	it("leaves a placeholder document that a later timeline write does not empty", () => {
+		const seeded = documentAfterProbedDuration(
+			emptyTimeline("asset_1", ["asset_1"]),
+			"asset_1",
+			Number.NaN,
+			PROJECT,
+		) as AxcutDocument;
+
+		const rebuilt = replaceTimeline(seeded, [{ startSec: 0, endSec: 30 }], "trim");
+
+		expect(rebuilt.timeline.clips).toHaveLength(1);
+		expect(rebuilt.timeline.clips[0].sourceEndSec).toBe(30);
+	});
+
 	// …and once a timeline exists, an unusable duration has nothing to fold in: the
 	// placeholder above only exists so the FIRST clip is not empty.
 	it("writes nothing into an existing timeline from an unusable duration", () => {
diff --git a/src/components/ai-edition/NewEditorShell.tsx b/src/components/ai-edition/NewEditorShell.tsx
index ab7cbed39..f822a7792 100644
--- a/src/components/ai-edition/NewEditorShell.tsx
+++ b/src/components/ai-edition/NewEditorShell.tsx
@@ -145,8 +145,13 @@ export function documentAfterProbedDuration(
 	if (doc.project.id !== originatingProjectId) return null;
 	// ponytail: WebM recordings from MediaRecorder report NaN/Infinity until the
 	// main-process EBML fix lands. A seed still has to happen — an empty timeline is
-	// worse than a wrong length — but 60 is a placeholder, not a measurement, so it
-	// is not written to `asset.durationSec`. Auto-zoom waits for a real probe.
+	// worse than a wrong length — and the placeholder IS written to
+	// `asset.durationSec`, because the timeline layer clamps every interval it
+	// builds against `primaryAssetDuration`: leave that unset and the next
+	// `replaceTimeline` clamps to zero, drops every clip and persists an empty
+	// timeline. What must not be fooled by the placeholder is auto-zoom, and that is
+	// handled where it belongs — `hasProbedDurationForPendingAsset` asks the clips,
+	// not the asset, whether a real probe has landed.
 	const finite = Number.isFinite(durationSec) && durationSec > 0;
 	const knownSec = finite ? durationSec : PLACEHOLDER_DURATION_SEC;
 	if (doc.timeline.clips.length === 0) {
@@ -165,20 +170,11 @@ export function documentAfterProbedDuration(
 				a.id === primaryAssetId ? { ...a, durationSec: knownSec } : a,
 			),
 		};
-		const withClip = replaceTimelineOp(
+		return replaceTimelineOp(
 			docWithDuration,
 			[{ startSec: 0, endSec: knownSec }],
 			"Auto-created full-duration clip",
 		);
-		if (finite) return withClip;
-		return {
-			...withClip,
-			assets: withClip.assets.map((asset) => {
-				if (asset.id !== primaryAssetId) return asset;
-				const { durationSec: _placeholder, ...rest } = asset;
-				return rest;
-			}),
-		};
 	}
 	// Nothing to fold into an existing timeline without a real length: the
 	// placeholder above exists only so the first clip is not empty.
diff --git a/src/components/ai-edition/recordingImport.ts b/src/components/ai-edition/recordingImport.ts
index a8e68beb6..cb5457e0f 100644
--- a/src/components/ai-edition/recordingImport.ts
+++ b/src/components/ai-edition/recordingImport.ts
@@ -16,6 +16,7 @@
 
 import type { CursorTelemetryPoint } from "@/components/video-editor/types";
 import { createId } from "@/lib/ai-edition/document/ids";
+import { clipAwaitsProbedDuration } from "@/lib/ai-edition/document/timeline";
 import type { AxcutDocument } from "@/lib/ai-edition/schema";
 import {
 	DOCUMENT_SAVES_WAIT_TIMEOUT_MS,
@@ -109,6 +110,15 @@ async function readAutoZoomPref(): Promise<boolean> {
 	}
 }
 
+function clipExtentSignature(document: AxcutDocument): string {
+	return document.timeline.clips
+		.map(
+			(clip) =>
+				`${clip.id}:${clip.assetId}:${clip.sourceStartSec}:${clip.sourceEndSec ?? ""}:${clip.timelineStartSec}:${clip.timelineEndSec}`,
+		)
+		.join("|");
+}
+
 function pendingFreshRecordingAsset(document: AxcutDocument) {
 	if (pendingFreshRecordingAutoZoomPath) {
 		return document.assets.find(
@@ -119,23 +129,31 @@ function pendingFreshRecordingAsset(document: AxcutDocument) {
 	return document.assets.find((asset) => asset.id === primaryId) ?? document.assets[0];
 }
 
+/**
+ * Whether the pending take's real length has landed yet.
+ *
+ * Not just `asset.durationSec != null`. A recording whose container reports no
+ * duration (MediaRecorder WebM, until the EBML fix) still gets the placeholder
+ * written to that field, because the timeline layer clamps every interval it
+ * builds against `primaryAssetDuration` and would otherwise drop every clip. So
+ * the asset says "60" for a take nothing has measured, and the clips are what
+ * distinguish the two: one still sitting at the placeholder length is waiting.
+ *
+ * The cost is a take of exactly 60.000 s never being auto-zoomed. That is the
+ * same ambiguity `applyProbedDuration` already lives with, and it is a far
+ * smaller price than suggesting zooms against a length nothing measured.
+ */
 function hasProbedDurationForPendingAsset(document: AxcutDocument): boolean {
 	const asset = pendingFreshRecordingAsset(document);
-	return (
-		asset != null &&
-		asset.durationSec != null &&
-		Number.isFinite(asset.durationSec) &&
-		asset.durationSec > 0
-	);
-}
-
-function clipExtentSignature(document: AxcutDocument): string {
-	return document.timeline.clips
-		.map(
-			(clip) =>
-				`${clip.id}:${clip.assetId}:${clip.sourceStartSec}:${clip.sourceEndSec ?? ""}:${clip.timelineStartSec}:${clip.timelineEndSec}`,
-		)
-		.join("|");
+	if (
+		asset == null ||
+		asset.durationSec == null ||
+		!Number.isFinite(asset.durationSec) ||
+		asset.durationSec <= 0
+	) {
+		return false;
+	}
+	return !document.timeline.clips.some((clip) => clipAwaitsProbedDuration(clip, asset.id));
 }
 
 function canApplyFreshRecordingAutoZooms(document: AxcutDocument): boolean {
diff --git a/src/lib/ai-edition/document/timeline.ts b/src/lib/ai-edition/document/timeline.ts
index 870b2ac94..3bfe1ffab 100644
--- a/src/lib/ai-edition/document/timeline.ts
+++ b/src/lib/ai-edition/document/timeline.ts
@@ -481,7 +481,7 @@ function rederiveAnchoredRegion<
  *  source extent at all (what `migrateProjectDataToAxcutDocument` produces — the
  *  migration is pure, so it cannot probe the file for a duration), or it still sits at
  *  the pre-probe placeholder length. Both mean "waiting for the real duration". */
-function clipAwaitsProbedDuration(clip: AxcutClip, assetId: string): boolean {
+export function clipAwaitsProbedDuration(clip: AxcutClip, assetId: string): boolean {
 	if (clip.assetId !== assetId || clip.sourceStartSec !== 0) return false;
 	const end = clip.sourceEndSec ?? 0;
 	if (end <= clip.sourceStartSec) return true; // no extent at all (v2 migration)

From 01aca43c9586816fe2ebf8292433627322e7b7d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E8=B6=85=E7=BA=A7?=
 =?UTF-8?q?=E5=96=9C=E6=AC=A2=E4=BD=A0=E7=9A=84=E8=BE=BE=E5=A6=AE=E5=A8=85?=
 <176143450+My-Denia@users.noreply.github.com>
Date: Mon, 7 Sep 2026 22:55:04 +0800
Subject: [PATCH 14/14] fix(timeline): re-collect auto-zoom suggestions when
 the clips move underneath
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A suggestion carries a TIMELINE span, and `appendAutoZoomSuggestions` anchors it
against whatever clips the document holds at write time. Collecting takes a
multi-second telemetry round trip, so those are not necessarily the same
document — and if the user trims, moves, adds, removes or reorders a clip during
the wait, the spans land on different media, or on nothing.

The import path already handled this by comparing clip geometry before and after
and collecting again if it moved. The wand did not: it built suggestions from the
document it captured up front and handed them to `addZoomsBulk`, which reads the
latest one.

That check moves into `apply-auto-zooms` next to the collect it guards, and both
callers use it — which is the whole reason that module exists. One retry, not a
loop: a user who keeps editing through the wait keeps invalidating it, and the
honest answer there is the write-time guards, not spinning here.
---
 src/components/ai-edition/recordingImport.ts  | 10 +---
 src/components/ai-edition/v4/V4Timeline.tsx   | 13 +++--
 .../timeline/apply-auto-zooms.test.ts         | 52 ++++++++++++++++++-
 .../ai-edition/timeline/apply-auto-zooms.ts   | 46 ++++++++++++++++
 4 files changed, 108 insertions(+), 13 deletions(-)

diff --git a/src/components/ai-edition/recordingImport.ts b/src/components/ai-edition/recordingImport.ts
index cb5457e0f..2c22d61fb 100644
--- a/src/components/ai-edition/recordingImport.ts
+++ b/src/components/ai-edition/recordingImport.ts
@@ -26,6 +26,7 @@ import {
 } from "@/lib/ai-edition/store/projectStore";
 import {
 	appendAutoZoomSuggestions,
+	clipExtentSignature,
 	collectAutoZoomSuggestionsForDocument,
 } from "@/lib/ai-edition/timeline/apply-auto-zooms";
 import { nativeBridgeClient } from "@/native/client";
@@ -110,15 +111,6 @@ async function readAutoZoomPref(): Promise<boolean> {
 	}
 }
 
-function clipExtentSignature(document: AxcutDocument): string {
-	return document.timeline.clips
-		.map(
-			(clip) =>
-				`${clip.id}:${clip.assetId}:${clip.sourceStartSec}:${clip.sourceEndSec ?? ""}:${clip.timelineStartSec}:${clip.timelineEndSec}`,
-		)
-		.join("|");
-}
-
 function pendingFreshRecordingAsset(document: AxcutDocument) {
 	if (pendingFreshRecordingAutoZoomPath) {
 		return document.assets.find(
diff --git a/src/components/ai-edition/v4/V4Timeline.tsx b/src/components/ai-edition/v4/V4Timeline.tsx
index 8dd426376..cd2edb07f 100644
--- a/src/components/ai-edition/v4/V4Timeline.tsx
+++ b/src/components/ai-edition/v4/V4Timeline.tsx
@@ -52,7 +52,7 @@ import { useTimelineTranscriptGate } from "@/lib/ai-edition/store/transcriptionS
 import { useChatPromptBus } from "@/lib/ai-edition/store/useChatPromptBus";
 import { useEditorSettings } from "@/lib/ai-edition/store/useEditorSettings";
 import type { useTimeline } from "@/lib/ai-edition/store/useTimeline";
-import { collectAutoZoomSuggestionsForDocument } from "@/lib/ai-edition/timeline/apply-auto-zooms";
+import { collectAutoZoomSuggestionsForLatestDocument } from "@/lib/ai-edition/timeline/apply-auto-zooms";
 import { hasAnyClipWithCamera } from "@/lib/ai-edition/timeline/camera";
 import { formatSec } from "@/lib/ai-edition/timeline/format";
 import {
@@ -1488,9 +1488,16 @@ export function V4Timeline({
 		}
 		setAutoBusy(true);
 		try {
-			const suggestions = await collectAutoZoomSuggestionsForDocument(document, (videoPath) =>
-				nativeBridgeClient.cursor.getTelemetry(videoPath),
+			// Collected against the document as it is now, and again if the clips moved
+			// while the telemetry was being read: the suggestions carry timeline spans and
+			// `addZoomsBulk` anchors them against whatever the store holds at write time,
+			// so a trim or a reorder during that multi-second wait would land them on
+			// different media.
+			const collected = await collectAutoZoomSuggestionsForLatestDocument(
+				() => useProjectStore.getState().document,
+				(videoPath) => nativeBridgeClient.cursor.getTelemetry(videoPath),
 			);
+			const suggestions = collected?.suggestions ?? [];
 			if (suggestions.length === 0) {
 				toast.info(t("toolbar.noAutoZoomMoments"), {
 					description: t("toolbar.noAutoZoomMomentsDescription"),
diff --git a/src/lib/ai-edition/timeline/apply-auto-zooms.test.ts b/src/lib/ai-edition/timeline/apply-auto-zooms.test.ts
index c00124f19..484c79fc9 100644
--- a/src/lib/ai-edition/timeline/apply-auto-zooms.test.ts
+++ b/src/lib/ai-edition/timeline/apply-auto-zooms.test.ts
@@ -1,9 +1,10 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import type { CursorTelemetryPoint } from "@/components/video-editor/types";
 import { type AxcutDocument, createEmptyDocument } from "../schema";
 import {
 	appendAutoZoomSuggestions,
 	collectAutoZoomSuggestionsForDocument,
+	collectAutoZoomSuggestionsForLatestDocument,
 } from "./apply-auto-zooms";
 
 function dwell(
@@ -110,3 +111,52 @@ describe("appendAutoZoomSuggestions", () => {
 		});
 	});
 });
+
+describe("collectAutoZoomSuggestionsForLatestDocument", () => {
+	const telemetry: CursorTelemetryPoint[] = [0, 600, 1200, 1800].map((timeMs) => ({
+		timeMs,
+		cx: 0.5,
+		cy: 0.5,
+	}));
+
+	it("collects once when the clips stand still", async () => {
+		const doc = documentWithClip();
+		const getTelemetry = vi.fn(async () => telemetry);
+
+		const out = await collectAutoZoomSuggestionsForLatestDocument(() => doc, getTelemetry);
+
+		expect(out?.document).toBe(doc);
+		expect(getTelemetry).toHaveBeenCalledTimes(1);
+	});
+
+	// THE case: the telemetry read takes seconds, and the suggestions carry timeline
+	// spans that `appendAutoZoomSuggestions` will anchor against whatever the store
+	// holds at write time. A trim landing in between makes the first collection
+	// describe a timeline that no longer exists.
+	it("collects again when the clips moved during the read", async () => {
+		const before = documentWithClip();
+		const after: AxcutDocument = {
+			...before,
+			timeline: {
+				...before.timeline,
+				clips: before.timeline.clips.map((clip) => ({ ...clip, sourceEndSec: 4 })),
+			},
+		};
+		let current = before;
+		const getTelemetry = vi.fn(async () => {
+			current = after;
+			return telemetry;
+		});
+
+		const out = await collectAutoZoomSuggestionsForLatestDocument(() => current, getTelemetry);
+
+		expect(out?.document).toBe(after);
+		expect(getTelemetry.mock.calls.length).toBeGreaterThan(1);
+	});
+
+	it("gives up when the project is gone", async () => {
+		const getTelemetry = vi.fn(async () => telemetry);
+		expect(await collectAutoZoomSuggestionsForLatestDocument(() => null, getTelemetry)).toBeNull();
+		expect(getTelemetry).not.toHaveBeenCalled();
+	});
+});
diff --git a/src/lib/ai-edition/timeline/apply-auto-zooms.ts b/src/lib/ai-edition/timeline/apply-auto-zooms.ts
index f1f1c82c0..3a6c5fac0 100644
--- a/src/lib/ai-edition/timeline/apply-auto-zooms.ts
+++ b/src/lib/ai-edition/timeline/apply-auto-zooms.ts
@@ -39,6 +39,52 @@ export async function collectAutoZoomSuggestionsForDocument(
 	return perSource.flat();
 }
 
+/**
+ * The clip geometry the suggestions were built against, as a comparable string.
+ *
+ * Suggestions carry TIMELINE spans, and `appendAutoZoomSuggestions` anchors them
+ * against whatever clips the document holds when the write happens. Collecting
+ * takes a multi-second telemetry round trip, so those two documents are not
+ * necessarily the same one — and if a clip was trimmed, moved, added, removed or
+ * reordered in between, the spans land on different media, or on nothing.
+ */
+export function clipExtentSignature(document: AxcutDocument): string {
+	return document.timeline.clips
+		.map(
+			(clip) =>
+				`${clip.id}:${clip.assetId}:${clip.sourceStartSec}:${clip.sourceEndSec ?? ""}:${clip.timelineStartSec}:${clip.timelineEndSec}`,
+		)
+		.join("|");
+}
+
+/**
+ * Collect against the document as it is NOW, and collect again if the clips moved
+ * while the telemetry was being read.
+ *
+ * One retry, not a loop: a user who keeps editing through the wait will keep
+ * invalidating it, and the honest answer there is the write-time guards, not
+ * spinning here. Returns the suggestions together with the document they were
+ * built from, so the caller can tell what they describe.
+ */
+export async function collectAutoZoomSuggestionsForLatestDocument(
+	readDocument: () => AxcutDocument | null,
+	getTelemetry: (videoPath: string) => Promise<CursorTelemetryPoint[] | null | undefined>,
+): Promise<{ document: AxcutDocument; suggestions: AutoZoomSuggestion[] } | null> {
+	const start = readDocument();
+	if (!start) return null;
+	const startSignature = clipExtentSignature(start);
+	const suggestions = await collectAutoZoomSuggestionsForDocument(start, getTelemetry);
+	const latest = readDocument();
+	if (!latest) return null;
+	if (clipExtentSignature(latest) === startSignature) {
+		return { document: latest, suggestions };
+	}
+	return {
+		document: latest,
+		suggestions: await collectAutoZoomSuggestionsForDocument(latest, getTelemetry),
+	};
+}
+
 export function appendAutoZoomSuggestions(
 	document: AxcutDocument,
 	suggestions: AutoZoomSuggestion[],