Adjust guide video annotation timing

Bump version to 1.4.11 for updater release
Add automatic update checks
2026-06-05 20:39:26 +07:00 · 2026-06-05 16:17:26 +07:00 · 2026-06-05 10:54:22 +07:00 · 2026-06-05 05:58:14 +07:00 · 2026-05-28 21:05:39 +07:00 · 2026-05-28 19:35:42 +07:00
23 changed files with 1514 additions and 293 deletions
@@ -13,11 +13,17 @@
  },
  "npmRebuild": true,
  "buildDependenciesFromSource": true,
-  "compression": "normal",
-  "directories": {
-    "output": "release/${version}"
-  },
-  "files": [
+  "compression": "normal",
+  "directories": {
+    "output": "release/${version}"
+  },
+  "publish": [
+    {
+      "provider": "generic",
+      "url": "https://gittea.softs.business/huanld/openscreen/raw/branch/release-assets%2Flatest"
+    }
+  ],
+  "files": [
    "dist",
    "dist-electron",
    "!*.png",
@@ -24,6 +24,14 @@ declare namespace NodeJS {
 // Used in Renderer process, expose in `preload.ts`
 interface Window {
 	electronAPI: {
+		updates: {
+			getStatus: () => Promise<import("../src/lib/updateStatus").UpdateStatus>;
+			check: () => Promise<import("../src/lib/updateStatus").UpdateCheckResult>;
+			install: () => Promise<import("../src/lib/updateStatus").UpdateCheckResult>;
+			onStatus: (
+				callback: (status: import("../src/lib/updateStatus").UpdateStatus) => void,
+			) => () => void;
+		};
 		invokeNativeBridge: <TData = unknown>(
 			request: import("../src/native/contracts").NativeBridgeRequest,
 		) => Promise<import("../src/native/contracts").NativeBridgeResponse<TData>>;
@@ -232,6 +232,74 @@ describe("GuideStore", () => {
 		await expect(fs.readFile(html.path, "utf-8")).resolves.toContain("<!doctype html>");
 	});

+	it("resumes OCR without reprocessing completed snapshots", async () => {
+		const recognizedSnapshotIds: string[] = [];
+		const store = new GuideStore(recordingsDir, {
+			ocrClient: {
+				recognize: async (snapshot) => {
+					recognizedSnapshotIds.push(snapshot.id);
+					return [];
+				},
+			},
+		});
+		await store.startSession(115);
+		const firstMarker = await store.addMarker({
+			recordingId: 115,
+			kind: "hotkey",
+			timeMs: 100,
+			label: "Ctrl+F12 marker",
+			normalizedX: 0.25,
+			normalizedY: 0.35,
+		});
+		const secondMarker = await store.addMarker({
+			recordingId: 115,
+			kind: "hotkey",
+			timeMs: 300,
+			label: "Ctrl+F12 marker",
+			normalizedX: 0.6,
+			normalizedY: 0.7,
+		});
+		const firstEvent = firstMarker.event;
+		const secondEvent = secondMarker.event;
+		await store.writeSnapshot({
+			recordingId: 115,
+			eventId: firstEvent?.id ?? "",
+			timeMs: 100,
+			offsetMs: 0,
+			width: 800,
+			height: 600,
+			pngBytes: new Uint8Array([1, 2, 3]).buffer,
+		});
+		await store.writeSnapshot({
+			recordingId: 115,
+			eventId: secondEvent?.id ?? "",
+			timeMs: 300,
+			offsetMs: 0,
+			width: 800,
+			height: 600,
+			pngBytes: new Uint8Array([4, 5, 6]).buffer,
+		});
+
+		await store.runOcr({
+			recordingId: 115,
+			snapshotIds: [`snapshot-${firstEvent?.id}`],
+		});
+		expect(recognizedSnapshotIds).toEqual([`snapshot-${firstEvent?.id}`]);
+
+		const resumedSession = await store.runOcr({ recordingId: 115 });
+		expect(recognizedSnapshotIds).toEqual([
+			`snapshot-${firstEvent?.id}`,
+			`snapshot-${secondEvent?.id}`,
+		]);
+		expect(resumedSession.snapshots.every((snapshot) => snapshot.ocrCompletedAt)).toBe(true);
+
+		await store.runOcr({ recordingId: 115 });
+		expect(recognizedSnapshotIds).toEqual([
+			`snapshot-${firstEvent?.id}`,
+			`snapshot-${secondEvent?.id}`,
+		]);
+	});
+
 	it("repairs generic hotkey marker text and attaches AI draft artifacts", async () => {
 		const store = new GuideStore(recordingsDir, {
 			ocrClient: {
@@ -58,6 +58,8 @@ const VALID_EVENT_SOURCES = new Set<GuideEventSource>([
 	"review-ui",
 ]);

+const guideOcrJobsByRecordingId = new Map<string, Promise<GuideSession>>();
+
 export class GuideStoreError extends Error {
 	constructor(
 		readonly code: GuideErrorCode,
@@ -259,50 +261,103 @@ export class GuideStore {
 	}

 	async runOcr(input: RunGuideOcrInput): Promise<GuideSession> {
-		const session = await this.readSession(input.recordingId);
-		const requestedIds = new Set(input.snapshotIds ?? []);
-		const snapshots =
-			requestedIds.size > 0
-				? session.snapshots.filter((snapshot) => requestedIds.has(snapshot.id))
-				: session.snapshots;
-		if (snapshots.length === 0) {
-			throw new GuideStoreError("guide-invalid-input", "No guide snapshots are available for OCR.");
+		const recordingId = normalizeGuideRecordingId(input.recordingId);
+		if (!recordingId) {
+			throw new GuideStoreError("guide-invalid-input", "OCR run is missing recordingId.");
 		}

-		const ocrClient =
-			this.dependencies.ocrClient ??
-			DefaultGuideOcrClient.fromConfig(await this.dependencies.ocrConfigProvider?.getOcrConfig());
-		const shouldFocusOcrSnapshots =
-			this.dependencies.focusOcrSnapshots ?? this.dependencies.ocrClient === undefined;
-		const eventsById = new Map(session.events.map((event) => [event.id, event]));
-		const blocks: OcrBlock[] = [];
-		try {
-			for (const snapshot of snapshots) {
-				const focusedSnapshot = shouldFocusOcrSnapshots
-					? await createFocusedOcrSnapshot({
-							snapshot,
-							event: eventsById.get(snapshot.eventId),
-							outputDir: session.outputDir,
-						})
-					: { snapshot };
-				const recognizedBlocks = await ocrClient.recognize(focusedSnapshot.snapshot);
-				blocks.push(...remapFocusedOcrBlocks(recognizedBlocks, focusedSnapshot.transform));
+		const previousJob =
+			guideOcrJobsByRecordingId.get(recordingId)?.catch(() => undefined) ?? Promise.resolve();
+		const nextJob = previousJob.then(async () => {
+			let session = await this.readSession(recordingId);
+			const requestedIds = new Set(input.snapshotIds ?? []);
+			const snapshots =
+				requestedIds.size > 0
+					? session.snapshots.filter((snapshot) => requestedIds.has(snapshot.id))
+					: session.snapshots;
+			if (snapshots.length === 0) {
+				throw new GuideStoreError(
+					"guide-invalid-input",
+					"No guide snapshots are available for OCR.",
+				);
 			}
-		} catch (error) {
-			throw new GuideStoreError(
-				"guide-ocr-unavailable",
-				error instanceof Error ? error.message : "OCR failed.",
-				true,
-			);
-		}

-		const snapshotIds = new Set(snapshots.map((snapshot) => snapshot.id));
+			const completedSnapshotIds = new Set(
+				session.snapshots
+					.filter((snapshot) => isSnapshotOcrCompleted(snapshot, session.ocrBlocks))
+					.map((snapshot) => snapshot.id),
+			);
+			const pendingSnapshots = snapshots.filter(
+				(snapshot) => !completedSnapshotIds.has(snapshot.id),
+			);
+			if (pendingSnapshots.length === 0) {
+				if (session.status === "ocr-ready") {
+					return session;
+				}
+				const readySession = touchSession({
+					...session,
+					status: "ocr-ready",
+					candidates: buildGuideStepCandidates(session),
+				});
+				await this.writeSession(readySession);
+				return readySession;
+			}
+
+			const ocrClient =
+				this.dependencies.ocrClient ??
+				DefaultGuideOcrClient.fromConfig(await this.dependencies.ocrConfigProvider?.getOcrConfig());
+			const shouldFocusOcrSnapshots =
+				this.dependencies.focusOcrSnapshots ?? this.dependencies.ocrClient === undefined;
+			const eventsById = new Map(session.events.map((event) => [event.id, event]));
+			try {
+				for (const snapshot of pendingSnapshots) {
+					const focusedSnapshot = shouldFocusOcrSnapshots
+						? await createFocusedOcrSnapshot({
+								snapshot,
+								event: eventsById.get(snapshot.eventId),
+								outputDir: session.outputDir,
+							})
+						: { snapshot };
+					const recognizedBlocks = await ocrClient.recognize(focusedSnapshot.snapshot);
+					const blocks = remapFocusedOcrBlocks(recognizedBlocks, focusedSnapshot.transform);
+					session = await this.writeOcrSnapshotProgress(session, snapshot.id, blocks);
+				}
+			} catch (error) {
+				throw new GuideStoreError(
+					"guide-ocr-unavailable",
+					error instanceof Error ? error.message : "OCR failed.",
+					true,
+				);
+			}
+
+			return session;
+		});
+		guideOcrJobsByRecordingId.set(recordingId, nextJob);
+		try {
+			return await nextJob;
+		} finally {
+			if (guideOcrJobsByRecordingId.get(recordingId) === nextJob) {
+				guideOcrJobsByRecordingId.delete(recordingId);
+			}
+		}
+	}
+
+	private async writeOcrSnapshotProgress(
+		session: GuideSession,
+		snapshotId: string,
+		blocks: OcrBlock[],
+	): Promise<GuideSession> {
 		const updatedOcrBlocks = [
-			...session.ocrBlocks.filter((block) => !snapshotIds.has(block.snapshotId)),
+			...session.ocrBlocks.filter((block) => block.snapshotId !== snapshotId),
 			...blocks,
 		];
+		const completedAt = new Date().toISOString();
+		const updatedSnapshots = session.snapshots.map((snapshot) =>
+			snapshot.id === snapshotId ? { ...snapshot, ocrCompletedAt: completedAt } : snapshot,
+		);
 		const draftSession = {
 			...session,
+			snapshots: updatedSnapshots,
 			ocrBlocks: updatedOcrBlocks,
 		};
 		const updatedSession = touchSession({
@@ -679,6 +734,7 @@ function normalizeGuideSnapshot(input: unknown): GuideSnapshot | null {
 	const eventId = normalizeString(input.eventId);
 	const pathValue = normalizeString(input.path);
 	const markedPath = normalizeOptionalString(input.markedPath);
+	const ocrCompletedAt = normalizeOptionalString(input.ocrCompletedAt);
 	const timeMs = normalizeNonNegativeNumber(input.timeMs);
 	const offsetMs = normalizeOptionalNumber(input.offsetMs);
 	const width = normalizePositiveInteger(input.width);
@@ -694,7 +750,23 @@ function normalizeGuideSnapshot(input: unknown): GuideSnapshot | null {
 	) {
 		return null;
 	}
-	return { id, eventId, timeMs, offsetMs, path: pathValue, markedPath, width, height };
+	return {
+		id,
+		eventId,
+		timeMs,
+		offsetMs,
+		path: pathValue,
+		markedPath,
+		ocrCompletedAt,
+		width,
+		height,
+	};
+}
+
+function isSnapshotOcrCompleted(snapshot: GuideSnapshot, ocrBlocks: OcrBlock[]): boolean {
+	return (
+		Boolean(snapshot.ocrCompletedAt) || ocrBlocks.some((block) => block.snapshotId === snapshot.id)
+	);
 }

 function normalizeOcrBlock(input: unknown): OcrBlock | null {
@@ -1,11 +1,10 @@
-import { type ChildProcessWithoutNullStreams, execFile, spawn } from "node:child_process";
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { promisify } from "node:util";
 import type { DesktopCapturerSource, Rectangle } from "electron";
 import {
 	app,
@@ -18,7 +17,7 @@ import {
 	shell,
 	systemPreferences,
 } from "electron";
-import type { GuideEvent, GuideMarkerCapturedPayload } from "../../src/guide/contracts";
+import type { GuideMarkerCapturedPayload } from "../../src/guide/contracts";
 import type { NativeMacRecordingRequest } from "../../src/lib/nativeMacRecording";
 import type { NativeWindowsRecordingRequest } from "../../src/lib/nativeWindowsRecording";
 import {
@@ -57,7 +56,6 @@ const RECORDING_SESSION_SUFFIX = ".session.json";
 const ALLOWED_IMPORT_VIDEO_EXTENSIONS = new Set([".webm", ".mp4", ".mov", ".avi", ".mkv"]);
 const PREVIEW_AUDIO_DIR = path.join(app.getPath("userData"), "preview-audio");
 const nativeMacCaptureEvents = new EventEmitter();
-const execFileAsync = promisify(execFile);

 /**
 * Paths explicitly approved by the user via file picker dialogs or project loads.
@@ -456,7 +454,6 @@ let activeGuideHotkeyRecording: GuideHotkeyRecordingState | null = null;
 let activeGuideHotkeySessionId: number | null = null;
 let guideMarkerHotkeyRegistered = false;
 let lastGuideHotkeyCaptureAtMs = 0;
-const guideHotkeyBackgroundJobs = new Map<string, Promise<void>>();
 const GUIDE_HOTKEY_CAPTURE_DEBOUNCE_MS = 250;

 function normalizeCursorSample(sample: unknown): CursorRecordingSample | null {
@@ -811,203 +808,6 @@ function clampGuideHotkey01(value: number): number {
 	return Math.min(1, Math.max(0, value));
 }

-async function captureGuideHotkeySnapshotAndRunOcr(
-	guideStore: GuideStore,
-	event: GuideEvent,
-	boundsInput: GuideHotkeyBounds,
-	point: { normalizedX: number; normalizedY: number },
-) {
-	try {
-		const bounds = sanitizeGuideHotkeyBounds(boundsInput);
-		const sources = await desktopCapturer.getSources({
-			types: ["screen"],
-			thumbnailSize: {
-				width: Math.max(1, Math.round(bounds.width)),
-				height: Math.max(1, Math.round(bounds.height)),
-			},
-		});
-		const source = findScreenSourceForGuideBounds(sources, bounds);
-		if (!source || source.thumbnail.isEmpty()) {
-			console.warn("[guide-hotkey] no live screen thumbnail was available for OCR");
-			return;
-		}
-
-		const pngBuffer = source.thumbnail.toPNG();
-		const imageSize = source.thumbnail.getSize();
-		const markedPngBuffer = await createMarkedGuideSnapshotPng(pngBuffer, {
-			width: imageSize.width,
-			height: imageSize.height,
-			x: point.normalizedX * imageSize.width,
-			y: point.normalizedY * imageSize.height,
-		}).catch((error) => {
-			console.warn("[guide-hotkey] failed to create marked live snapshot:", error);
-			return undefined;
-		});
-
-		enqueueGuideHotkeyBackgroundJob(event.recordingId, async () => {
-			const session = await guideStore.writeSnapshot({
-				recordingId: event.recordingId,
-				eventId: event.id,
-				timeMs: event.timeMs,
-				offsetMs: 0,
-				pngBytes: bufferToArrayBuffer(pngBuffer),
-				markedPngBytes: markedPngBuffer ? bufferToArrayBuffer(markedPngBuffer) : undefined,
-				width: imageSize.width,
-				height: imageSize.height,
-			});
-			const snapshot = session.snapshots.find((item) => item.eventId === event.id);
-			if (!snapshot) {
-				return;
-			}
-
-			await guideStore.runOcr({
-				recordingId: event.recordingId,
-				snapshotIds: [snapshot.id],
-			});
-			console.info("[guide-hotkey] live snapshot OCR completed", {
-				recordingId: event.recordingId,
-				eventId: event.id,
-				snapshotId: snapshot.id,
-			});
-		});
-	} catch (error) {
-		console.warn("[guide-hotkey] live snapshot OCR failed:", error);
-	}
-}
-
-function enqueueGuideHotkeyBackgroundJob(recordingId: string, job: () => Promise<void>) {
-	const previousJob =
-		guideHotkeyBackgroundJobs.get(recordingId)?.catch(() => undefined) ?? Promise.resolve();
-	const nextJob = previousJob
-		.then(job)
-		.catch((error) => {
-			console.warn("[guide-hotkey] background OCR job failed:", error);
-		})
-		.finally(() => {
-			if (guideHotkeyBackgroundJobs.get(recordingId) === nextJob) {
-				guideHotkeyBackgroundJobs.delete(recordingId);
-			}
-		});
-	guideHotkeyBackgroundJobs.set(recordingId, nextJob);
-}
-
-function findScreenSourceForGuideBounds(
-	sources: DesktopCapturerSource[],
-	bounds: GuideHotkeyBounds,
-): DesktopCapturerSource | undefined {
-	const displays = screen.getAllDisplays();
-	const displayIndex = displays.findIndex((display) =>
-		rectMatchesGuideBounds(display.bounds, bounds),
-	);
-	const display = displayIndex >= 0 ? displays[displayIndex] : undefined;
-	if (display) {
-		const byDisplayId = sources.find((source) => Number(source.display_id) === display.id);
-		if (byDisplayId) {
-			return byDisplayId;
-		}
-		const bySourceIndex = sources.find(
-			(source) => parseDesktopCapturerScreenIndex(source.id) === displayIndex,
-		);
-		if (bySourceIndex) {
-			return bySourceIndex;
-		}
-	}
-	return sources.find((source) => source.id.startsWith("screen:")) ?? sources[0];
-}
-
-function rectMatchesGuideBounds(rect: Rectangle, bounds: GuideHotkeyBounds): boolean {
-	return (
-		Math.round(rect.x) === Math.round(bounds.x) &&
-		Math.round(rect.y) === Math.round(bounds.y) &&
-		Math.round(rect.width) === Math.round(bounds.width) &&
-		Math.round(rect.height) === Math.round(bounds.height)
-	);
-}
-
-async function createMarkedGuideSnapshotPng(
-	pngBuffer: Buffer,
-	marker: { width: number; height: number; x: number; y: number },
-): Promise<Buffer> {
-	const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openscreen-guide-marker-"));
-	const sourcePath = path.join(tempDir, "source.png");
-	const outputPath = path.join(tempDir, "marked.png");
-	try {
-		await fs.writeFile(sourcePath, pngBuffer);
-		await execFileAsync(
-			"powershell.exe",
-			[
-				"-NoProfile",
-				"-ExecutionPolicy",
-				"Bypass",
-				"-EncodedCommand",
-				buildMarkerScript(sourcePath, outputPath, marker),
-			],
-			{
-				timeout: 30000,
-				windowsHide: true,
-				maxBuffer: 1024 * 1024,
-			},
-		);
-		return await fs.readFile(outputPath);
-	} finally {
-		await fs.rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
-	}
-}
-
-function buildMarkerScript(
-	sourcePath: string,
-	outputPath: string,
-	marker: { width: number; height: number; x: number; y: number },
-): string {
-	const sourcePathBase64 = Buffer.from(sourcePath, "utf8").toString("base64");
-	const outputPathBase64 = Buffer.from(outputPath, "utf8").toString("base64");
-	const script = `
-$ErrorActionPreference = "Stop"
-$sourcePath = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("${sourcePathBase64}"))
-$outputPath = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("${outputPathBase64}"))
-Add-Type -AssemblyName System.Drawing
-
-$source = [System.Drawing.Image]::FromFile($sourcePath)
-$bitmap = [System.Drawing.Bitmap]::new($source.Width, $source.Height)
-$graphics = [System.Drawing.Graphics]::FromImage($bitmap)
-try {
-  $graphics.SmoothingMode = [System.Drawing.Drawing2D.SmoothingMode]::AntiAlias
-  $graphics.DrawImage($source, 0, 0, $source.Width, $source.Height)
-  $shortSide = [Math]::Max(1, [Math]::Min($source.Width, $source.Height))
-  $haloRadius = [Math]::Min(14, [Math]::Max(8, [Math]::Round($shortSide * 0.012)))
-  $dotRadius = [Math]::Min(6, [Math]::Max(3, [Math]::Round($shortSide * 0.0045)))
-  $lineWidth = [Math]::Max(1, [Math]::Round($shortSide * 0.0015))
-  $x = [Math]::Min($source.Width, [Math]::Max(0, ${marker.x.toFixed(4)}))
-  $y = [Math]::Min($source.Height, [Math]::Max(0, ${marker.y.toFixed(4)}))
-  $haloBrush = [System.Drawing.SolidBrush]::new([System.Drawing.Color]::FromArgb(87, 250, 204, 21))
-  $ringPen = [System.Drawing.Pen]::new([System.Drawing.Color]::FromArgb(184, 239, 68, 68), $lineWidth)
-  $dotBrush = [System.Drawing.SolidBrush]::new([System.Drawing.Color]::FromArgb(235, 220, 38, 38))
-  try {
-    $graphics.FillEllipse($haloBrush, $x - $haloRadius, $y - $haloRadius, $haloRadius * 2, $haloRadius * 2)
-    $graphics.DrawEllipse($ringPen, $x - $haloRadius, $y - $haloRadius, $haloRadius * 2, $haloRadius * 2)
-    $graphics.FillEllipse($dotBrush, $x - $dotRadius, $y - $dotRadius, $dotRadius * 2, $dotRadius * 2)
-  } finally {
-    $haloBrush.Dispose()
-    $ringPen.Dispose()
-    $dotBrush.Dispose()
-  }
-  $bitmap.Save($outputPath, [System.Drawing.Imaging.ImageFormat]::Png)
-} finally {
-  $graphics.Dispose()
-  $bitmap.Dispose()
-  $source.Dispose()
-}
-`;
-	return Buffer.from(script, "utf16le").toString("base64");
-}
-
-function bufferToArrayBuffer(buffer: Buffer): ArrayBuffer {
-	return buffer.buffer.slice(
-		buffer.byteOffset,
-		buffer.byteOffset + buffer.byteLength,
-	) as ArrayBuffer;
-}
-
 async function captureGuideHotkeyMarker(
 	guideStore: GuideStore,
 	trigger: GuideMarkerTrigger = "global-shortcut",
@@ -1054,7 +854,6 @@ async function captureGuideHotkeyMarker(
 			rawY: point.rawY,
 			bounds: point.bounds,
 		});
-		void captureGuideHotkeySnapshotAndRunOcr(guideStore, result.event, recording.bounds, point);
 		return { captured: true, ...result };
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
@@ -13,6 +13,7 @@ import {
 } from "electron";
 import { mainT, setMainLocale } from "./i18n";
 import { getSelectedDesktopSource, registerIpcHandlers } from "./ipc/handlers";
+import { initializeAutoUpdates } from "./updater";
 import {
 	createCountdownOverlayWindow,
 	createEditorWindow,
@@ -515,6 +516,7 @@ app.whenReady().then(async () => {
 	createTray();
 	updateTrayMenu();
 	setupApplicationMenu();
+	initializeAutoUpdates();
 	// Ensure recordings directory exists
 	await ensureRecordingsDir();

@@ -26,6 +26,27 @@ const assetBaseUrl = assetBaseUrlArg ? assetBaseUrlArg.slice(ASSET_BASE_URL_ARG_

 contextBridge.exposeInMainWorld("electronAPI", {
 	assetBaseUrl,
+	updates: {
+		getStatus: () => {
+			return ipcRenderer.invoke("updates:get-status");
+		},
+		check: () => {
+			return ipcRenderer.invoke("updates:check");
+		},
+		install: () => {
+			return ipcRenderer.invoke("updates:install");
+		},
+		onStatus: (callback: (status: import("../src/lib/updateStatus").UpdateStatus) => void) => {
+			const listener = (
+				_event: Electron.IpcRendererEvent,
+				status: import("../src/lib/updateStatus").UpdateStatus,
+			) => {
+				callback(status);
+			};
+			ipcRenderer.on("updates:status", listener);
+			return () => ipcRenderer.removeListener("updates:status", listener);
+		},
+	},
 	invokeNativeBridge: <TData>(request: NativeBridgeRequest) => {
 		return ipcRenderer.invoke(NATIVE_BRIDGE_CHANNEL, request) as Promise<TData>;
 	},
@@ -0,0 +1,177 @@
+import { app, BrowserWindow, ipcMain } from "electron";
+import { autoUpdater, type ProgressInfo, type UpdateInfo } from "electron-updater";
+import type { UpdateCheckResult, UpdateStatus } from "../src/lib/updateStatus";
+
+const DEFAULT_UPDATE_FEED_URL =
+	"https://gittea.softs.business/huanld/openscreen/raw/branch/release-assets%2Flatest";
+const AUTO_CHECK_DELAY_MS = 10_000;
+const AUTO_CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000;
+
+let status: UpdateStatus = createStatus("idle");
+let handlersRegistered = false;
+let initialized = false;
+let checkInFlight: Promise<UpdateCheckResult> | null = null;
+
+function createStatus(
+	phase: UpdateStatus["phase"],
+	patch: Partial<UpdateStatus> = {},
+): UpdateStatus {
+	return {
+		phase,
+		currentVersion: app.getVersion(),
+		updatedAt: new Date().toISOString(),
+		...patch,
+	};
+}
+
+function normalizeReleaseNotes(releaseNotes: UpdateInfo["releaseNotes"]): string | undefined {
+	if (typeof releaseNotes === "string") {
+		return releaseNotes;
+	}
+	if (Array.isArray(releaseNotes)) {
+		return releaseNotes
+			.map((note) => note.note)
+			.filter(Boolean)
+			.join("\n\n");
+	}
+	return undefined;
+}
+
+function updateStatus(next: UpdateStatus) {
+	status = next;
+	for (const window of BrowserWindow.getAllWindows()) {
+		if (!window.isDestroyed()) {
+			window.webContents.send("updates:status", status);
+		}
+	}
+}
+
+function statusFromInfo(phase: UpdateStatus["phase"], info: UpdateInfo): UpdateStatus {
+	return createStatus(phase, {
+		version: info.version,
+		releaseName: info.releaseName ?? undefined,
+		releaseNotes: normalizeReleaseNotes(info.releaseNotes),
+	});
+}
+
+async function checkForUpdates(): Promise<UpdateCheckResult> {
+	if (!initialized) {
+		updateStatus(
+			createStatus("unsupported", {
+				error: "Update service is not initialized.",
+			}),
+		);
+		return { success: false, status, error: status.error };
+	}
+
+	if (!app.isPackaged && process.env.OPENSCREEN_ALLOW_DEV_UPDATE_CHECK !== "1") {
+		updateStatus(
+			createStatus("unsupported", {
+				error: "Update checks only run in packaged builds.",
+			}),
+		);
+		return { success: false, status, error: status.error };
+	}
+
+	if (checkInFlight) {
+		return checkInFlight;
+	}
+
+	updateStatus(createStatus("checking"));
+	checkInFlight = autoUpdater
+		.checkForUpdates()
+		.then(() => ({ success: true, status }))
+		.catch((error) => {
+			const message = error instanceof Error ? error.message : String(error);
+			updateStatus(createStatus("error", { error: message }));
+			return { success: false, status, error: message };
+		})
+		.finally(() => {
+			checkInFlight = null;
+		});
+
+	return checkInFlight;
+}
+
+function registerUpdateIpcHandlers() {
+	if (handlersRegistered) {
+		return;
+	}
+
+	handlersRegistered = true;
+	ipcMain.handle("updates:get-status", () => status);
+	ipcMain.handle("updates:check", () => checkForUpdates());
+	ipcMain.handle("updates:install", () => {
+		if (status.phase !== "downloaded") {
+			return {
+				success: false,
+				status,
+				error: "No downloaded update is ready to install.",
+			};
+		}
+		setImmediate(() => autoUpdater.quitAndInstall(false, true));
+		return { success: true, status };
+	});
+}
+
+export function initializeAutoUpdates() {
+	registerUpdateIpcHandlers();
+
+	if (initialized) {
+		return;
+	}
+
+	initialized = true;
+	autoUpdater.autoDownload = true;
+	autoUpdater.autoInstallOnAppQuit = true;
+	autoUpdater.logger = console;
+
+	const feedUrl = process.env.OPENSCREEN_UPDATE_FEED_URL?.trim() || DEFAULT_UPDATE_FEED_URL;
+	const updateToken = process.env.OPENSCREEN_UPDATE_TOKEN?.trim();
+	if (updateToken) {
+		autoUpdater.requestHeaders = {
+			Authorization: `token ${updateToken}`,
+		};
+	}
+	autoUpdater.setFeedURL({
+		provider: "generic",
+		url: feedUrl,
+	});
+
+	autoUpdater.on("checking-for-update", () => {
+		updateStatus(createStatus("checking"));
+	});
+	autoUpdater.on("update-available", (info) => {
+		updateStatus(statusFromInfo("available", info));
+	});
+	autoUpdater.on("update-not-available", (info) => {
+		updateStatus(statusFromInfo("not-available", info));
+	});
+	autoUpdater.on("download-progress", (progress: ProgressInfo) => {
+		updateStatus(
+			createStatus("downloading", {
+				version: status.version,
+				releaseName: status.releaseName,
+				releaseNotes: status.releaseNotes,
+				percent: progress.percent,
+				bytesPerSecond: progress.bytesPerSecond,
+				transferred: progress.transferred,
+				total: progress.total,
+			}),
+		);
+	});
+	autoUpdater.on("update-downloaded", (info) => {
+		updateStatus(statusFromInfo("downloaded", info));
+	});
+	autoUpdater.on("error", (error) => {
+		const message = error instanceof Error ? error.message : String(error);
+		updateStatus(createStatus("error", { error: message }));
+	});
+
+	setTimeout(() => {
+		void checkForUpdates();
+	}, AUTO_CHECK_DELAY_MS);
+	setInterval(() => {
+		void checkForUpdates();
+	}, AUTO_CHECK_INTERVAL_MS).unref();
+}
@@ -1,12 +1,12 @@
 {
 	"name": "openscreen",
-	"version": "1.4.8",
+	"version": "1.4.12",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "openscreen",
-			"version": "1.4.8",
+			"version": "1.4.12",
 			"dependencies": {
 				"@fix-webm-duration/fix": "^1.0.1",
 				"@pixi/filter-drop-shadow": "^5.2.0",
@@ -29,6 +29,7 @@
 				"class-variance-authority": "^0.7.1",
 				"clsx": "^2.1.1",
 				"dnd-timeline": "^2.4.0",
+				"electron-updater": "^6.8.3",
 				"emoji-picker-react": "^4.18.0",
 				"fix-webm-duration": "^1.0.6",
 				"gif.js": "^0.2.0",
@@ -4625,7 +4626,6 @@
 			"version": "2.0.1",
 			"resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
 			"integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
-			"dev": true,
 			"license": "Python-2.0"
 		},
 		"node_modules/aria-hidden": {
@@ -4959,7 +4959,6 @@
 			"version": "9.5.1",
 			"resolved": "https://registry.npmjs.org/builder-util-runtime/-/builder-util-runtime-9.5.1.tgz",
 			"integrity": "sha512-qt41tMfgHTllhResqM5DcnHyDIWNgzHvuY2jDcYP9iaGpkWxTUzV6GQjDeLnlR1/DtdlcsWQbA7sByMpmJFTLQ==",
-			"dev": true,
 			"license": "MIT",
 			"dependencies": {
 				"debug": "^4.3.4",
@@ -5504,7 +5503,6 @@
 			"version": "4.4.3",
 			"resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
 			"integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
-			"dev": true,
 			"license": "MIT",
 			"dependencies": {
 				"ms": "^2.1.3"
@@ -6015,6 +6013,69 @@
 			"dev": true,
 			"license": "ISC"
 		},
+		"node_modules/electron-updater": {
+			"version": "6.8.3",
+			"resolved": "https://registry.npmjs.org/electron-updater/-/electron-updater-6.8.3.tgz",
+			"integrity": "sha512-Z6sgw3jgbikWKXei1ENdqFOxBP0WlXg3TtKfz0rgw2vIZFJUyI4pD7ZN7jrkm7EoMK+tcm/qTnPUdqfZukBlBQ==",
+			"license": "MIT",
+			"dependencies": {
+				"builder-util-runtime": "9.5.1",
+				"fs-extra": "^10.1.0",
+				"js-yaml": "^4.1.0",
+				"lazy-val": "^1.0.5",
+				"lodash.escaperegexp": "^4.1.2",
+				"lodash.isequal": "^4.5.0",
+				"semver": "~7.7.3",
+				"tiny-typed-emitter": "^2.1.0"
+			}
+		},
+		"node_modules/electron-updater/node_modules/fs-extra": {
+			"version": "10.1.0",
+			"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-10.1.0.tgz",
+			"integrity": "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ==",
+			"license": "MIT",
+			"dependencies": {
+				"graceful-fs": "^4.2.0",
+				"jsonfile": "^6.0.1",
+				"universalify": "^2.0.0"
+			},
+			"engines": {
+				"node": ">=12"
+			}
+		},
+		"node_modules/electron-updater/node_modules/jsonfile": {
+			"version": "6.2.1",
+			"resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.1.tgz",
+			"integrity": "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==",
+			"license": "MIT",
+			"dependencies": {
+				"universalify": "^2.0.0"
+			},
+			"optionalDependencies": {
+				"graceful-fs": "^4.1.6"
+			}
+		},
+		"node_modules/electron-updater/node_modules/semver": {
+			"version": "7.7.4",
+			"resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
+			"integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+			"license": "ISC",
+			"bin": {
+				"semver": "bin/semver.js"
+			},
+			"engines": {
+				"node": ">=10"
+			}
+		},
+		"node_modules/electron-updater/node_modules/universalify": {
+			"version": "2.0.1",
+			"resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz",
+			"integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==",
+			"license": "MIT",
+			"engines": {
+				"node": ">= 10.0.0"
+			}
+		},
 		"node_modules/electron-winstaller": {
 			"version": "5.4.0",
 			"resolved": "https://registry.npmjs.org/electron-winstaller/-/electron-winstaller-5.4.0.tgz",
@@ -6874,7 +6935,6 @@
 			"version": "4.2.11",
 			"resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
 			"integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
-			"dev": true,
 			"license": "ISC"
 		},
 		"node_modules/gsap": {
@@ -7287,7 +7347,6 @@
 			"version": "4.1.1",
 			"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
 			"integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
-			"dev": true,
 			"license": "MIT",
 			"dependencies": {
 				"argparse": "^2.0.1"
@@ -7419,7 +7478,6 @@
 			"version": "1.0.5",
 			"resolved": "https://registry.npmjs.org/lazy-val/-/lazy-val-1.0.5.tgz",
 			"integrity": "sha512-0/BnGCCfyUMkBpeDgWihanIAF9JmZhHBgUhEqzvf+adhNGLoP6TaiI5oF8oyb3I45P+PcnrqihSf01M0l0G5+Q==",
-			"dev": true,
 			"license": "MIT"
 		},
 		"node_modules/lilconfig": {
@@ -7586,6 +7644,19 @@
 			"dev": true,
 			"license": "MIT"
 		},
+		"node_modules/lodash.escaperegexp": {
+			"version": "4.1.2",
+			"resolved": "https://registry.npmjs.org/lodash.escaperegexp/-/lodash.escaperegexp-4.1.2.tgz",
+			"integrity": "sha512-TM9YBvyC84ZxE3rgfefxUWiQKLilstD6k7PTGt6wfbtXF8ixIJLOL3VYyV/z+ZiPLsVxAsKAFVwWlWeb2Y8Yyw==",
+			"license": "MIT"
+		},
+		"node_modules/lodash.isequal": {
+			"version": "4.5.0",
+			"resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz",
+			"integrity": "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==",
+			"deprecated": "This package is deprecated. Use require('node:util').isDeepStrictEqual instead.",
+			"license": "MIT"
+		},
 		"node_modules/log-update": {
 			"version": "6.1.0",
 			"resolved": "https://registry.npmjs.org/log-update/-/log-update-6.1.0.tgz",
@@ -7991,7 +8062,6 @@
 			"version": "2.1.3",
 			"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
 			"integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
-			"dev": true,
 			"license": "MIT"
 		},
 		"node_modules/mz": {
@@ -9394,7 +9464,6 @@
 			"version": "1.6.0",
 			"resolved": "https://registry.npmjs.org/sax/-/sax-1.6.0.tgz",
 			"integrity": "sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA==",
-			"dev": true,
 			"license": "BlueOak-1.0.0",
 			"engines": {
 				"node": ">=11.0.0"
@@ -10099,6 +10168,12 @@
 				"node": ">=12"
 			}
 		},
+		"node_modules/tiny-typed-emitter": {
+			"version": "2.1.0",
+			"resolved": "https://registry.npmjs.org/tiny-typed-emitter/-/tiny-typed-emitter-2.1.0.tgz",
+			"integrity": "sha512-qVtvMxeXbVej0cQWKqVSSAHmKZEHAvxdF8HEUBFWts8h+xEo5m/lEiPakuyZ3BnCBjOD8i24kzNOiOLLgsSxhA==",
+			"license": "MIT"
+		},
 		"node_modules/tinybench": {
 			"version": "2.9.0",
 			"resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
@@ -1,7 +1,7 @@
 {
 	"name": "openscreen",
 	"private": true,
-	"version": "1.4.8",
+	"version": "1.4.12",
 	"type": "module",
 	"packageManager": "npm@10.9.4",
 	"engines": {
@@ -70,6 +70,7 @@
 		"class-variance-authority": "^0.7.1",
 		"clsx": "^2.1.1",
 		"dnd-timeline": "^2.4.0",
+		"electron-updater": "^6.8.3",
 		"emoji-picker-react": "^4.18.0",
 		"fix-webm-duration": "^1.0.6",
 		"gif.js": "^0.2.0",
@@ -1,4 +1,5 @@
-import { lazy, Suspense, useEffect, useState } from "react";
+import { lazy, Suspense, useEffect, useRef, useState } from "react";
+import { toast } from "sonner";
 import { CountdownOverlay } from "./components/launch/CountdownOverlay.tsx";
 import { LaunchWindow } from "./components/launch/LaunchWindow";
 import { SourceSelector } from "./components/launch/SourceSelector";
@@ -6,6 +7,7 @@ import { Toaster } from "./components/ui/sonner";
 import { TooltipProvider } from "./components/ui/tooltip";
 import { ShortcutsProvider } from "./contexts/ShortcutsContext";
 import { loadAllCustomFonts } from "./lib/customFonts";
+import type { UpdateStatus } from "./lib/updateStatus";

 const VideoEditor = lazy(() => import("./components/video-editor/VideoEditor"));
 const ShortcutsConfigDialog = lazy(() =>
@@ -79,11 +81,78 @@ export default function App() {
 	return (
 		<TooltipProvider>
 			{content}
+			<UpdateNotifier
+				enabled={
+					hasElectronBridge &&
+					windowType !== "hud-overlay" &&
+					windowType !== "source-selector" &&
+					windowType !== "countdown-overlay"
+				}
+			/>
 			<Toaster theme="dark" className="pointer-events-auto" />
 		</TooltipProvider>
 	);
 }

+function UpdateNotifier({ enabled }: { enabled: boolean }) {
+	const lastPhaseRef = useRef<UpdateStatus["phase"]>("idle");
+
+	useEffect(() => {
+		if (!enabled || !window.electronAPI?.updates) {
+			return;
+		}
+
+		const applyStatus = (status: UpdateStatus) => {
+			const version = status.version ? ` ${status.version}` : "";
+			if (status.phase === "available") {
+				toast.loading(`Downloading OpenScreen${version} update...`, {
+					id: "openscreen-update",
+					duration: Number.POSITIVE_INFINITY,
+				});
+			} else if (status.phase === "downloading") {
+				const percent = typeof status.percent === "number" ? ` ${Math.round(status.percent)}%` : "";
+				toast.loading(`Downloading OpenScreen${version} update${percent}...`, {
+					id: "openscreen-update",
+					duration: Number.POSITIVE_INFINITY,
+				});
+			} else if (status.phase === "downloaded") {
+				toast.success(`OpenScreen${version} is ready to install.`, {
+					id: "openscreen-update",
+					duration: Number.POSITIVE_INFINITY,
+					action: {
+						label: "Restart",
+						onClick: () => {
+							void window.electronAPI.updates.install();
+						},
+					},
+				});
+			} else if (
+				status.phase === "error" &&
+				(lastPhaseRef.current === "available" ||
+					lastPhaseRef.current === "downloading" ||
+					lastPhaseRef.current === "downloaded")
+			) {
+				toast.error(status.error || "OpenScreen update failed.", {
+					id: "openscreen-update",
+				});
+			} else if (status.phase === "not-available" || status.phase === "unsupported") {
+				toast.dismiss("openscreen-update");
+			}
+			lastPhaseRef.current = status.phase;
+		};
+
+		const unsubscribe = window.electronAPI.updates.onStatus(applyStatus);
+		void window.electronAPI.updates
+			.getStatus()
+			.then(applyStatus)
+			.catch(() => undefined);
+
+		return unsubscribe;
+	}, [enabled]);
+
+	return null;
+}
+
 function BrowserDevFallback() {
 	return (
 		<div className="flex h-screen w-screen items-center justify-center bg-[#08090b] px-6 text-slate-100">
@@ -82,6 +82,7 @@ export function AnnotationOverlay({
 	);
 	const [livePointerPoint, setLivePointerPoint] = useState<{ x: number; y: number } | null>(null);
 	const mosaicCanvasRef = useRef<HTMLCanvasElement | null>(null);
+	const magnifierCanvasRef = useRef<HTMLCanvasElement | null>(null);
 	const blurType = "mosaic";
 	const blurOverlayColor =
 		annotation.type === "blur" ? getBlurOverlayColor(annotation.blurData) : "";
@@ -183,6 +184,79 @@ export function AnnotationOverlay({
 		y,
 	]);

+	useEffect(() => {
+		if (annotation.type !== "magnifier") {
+			return;
+		}
+		void previewFrameVersion;
+
+		const canvas = magnifierCanvasRef.current;
+		const sourceCanvas = previewSourceCanvas;
+		if (!canvas || !sourceCanvas) {
+			return;
+		}
+
+		const sourceWidth = sourceCanvas.width;
+		const sourceHeight = sourceCanvas.height;
+		const sourceClientWidth = sourceCanvas.clientWidth || containerWidth || sourceWidth;
+		const sourceClientHeight = sourceCanvas.clientHeight || containerHeight || sourceHeight;
+		if (
+			sourceWidth <= 0 ||
+			sourceHeight <= 0 ||
+			sourceClientWidth <= 0 ||
+			sourceClientHeight <= 0
+		) {
+			return;
+		}
+
+		const drawWidth = Math.max(1, Math.round(width));
+		const drawHeight = Math.max(1, Math.round(height));
+		canvas.width = drawWidth;
+		canvas.height = drawHeight;
+
+		const context = canvas.getContext("2d");
+		if (!context) {
+			return;
+		}
+
+		const zoom = Math.max(1, annotation.magnifierData?.zoom ?? 2.2);
+		const target = annotation.magnifierData?.target ?? {
+			x: annotation.position.x + annotation.size.width / 2,
+			y: annotation.position.y + annotation.size.height / 2,
+		};
+		const scaleX = sourceWidth / sourceClientWidth;
+		const scaleY = sourceHeight / sourceClientHeight;
+		const targetX = (target.x / 100) * sourceClientWidth * scaleX;
+		const targetY = (target.y / 100) * sourceClientHeight * scaleY;
+		const sampleWidth = Math.max(1, drawWidth / zoom);
+		const sampleHeight = Math.max(1, drawHeight / zoom);
+		const sx = Math.max(0, Math.min(sourceWidth - sampleWidth, targetX - sampleWidth / 2));
+		const sy = Math.max(0, Math.min(sourceHeight - sampleHeight, targetY - sampleHeight / 2));
+
+		context.clearRect(0, 0, drawWidth, drawHeight);
+		context.imageSmoothingEnabled = true;
+		context.imageSmoothingQuality = "high";
+		context.drawImage(
+			sourceCanvas as CanvasImageSource,
+			sx,
+			sy,
+			Math.min(sampleWidth, sourceWidth - sx),
+			Math.min(sampleHeight, sourceHeight - sy),
+			0,
+			0,
+			drawWidth,
+			drawHeight,
+		);
+	}, [
+		annotation,
+		containerHeight,
+		containerWidth,
+		height,
+		previewFrameVersion,
+		previewSourceCanvas,
+		width,
+	]);
+
 	const renderArrow = () => {
 		const direction = annotation.figureData?.arrowDirection || "right";
 		const color = annotation.figureData?.color || "#34B27B";
@@ -351,6 +425,30 @@ export function AnnotationOverlay({
 					<div className="w-full h-full flex items-center justify-center p-2">{renderArrow()}</div>
 				);

+			case "magnifier": {
+				const shape = annotation.magnifierData?.shape ?? "circle";
+				const caption = annotation.magnifierData?.caption;
+				return (
+					<div className="relative h-full w-full">
+						<canvas
+							ref={magnifierCanvasRef}
+							className="absolute inset-0 h-full w-full"
+							style={{
+								borderRadius: shape === "circle" ? "9999px" : "10px",
+								border: "3px solid rgba(248,250,252,0.96)",
+								boxShadow: "0 14px 36px rgba(0,0,0,0.38), 0 0 0 1px rgba(52,178,123,0.55)",
+								backgroundColor: "rgba(15, 23, 42, 0.9)",
+							}}
+						/>
+						{caption && (
+							<div className="absolute left-1/2 top-full mt-1 max-w-[220px] -translate-x-1/2 rounded-md bg-slate-950/90 px-2 py-1 text-center text-[11px] font-semibold leading-4 text-slate-100 shadow-lg">
+								{caption}
+							</div>
+						)}
+					</div>
+				);
+			}
+
 			case "blur": {
 				const shape = annotation.blurData?.shape ?? "rectangle";
 				const blurIntensity = Math.max(
@@ -623,6 +721,7 @@ export function AnnotationOverlay({
 					annotation.type === "text" && "bg-transparent",
 					annotation.type === "image" && "bg-transparent",
 					annotation.type === "figure" && "bg-transparent",
+					annotation.type === "magnifier" && "bg-transparent",
 					annotation.type === "blur" && "bg-transparent",
 					isSelected && annotation.type !== "blur" && "shadow-lg",
 				)}
@@ -13,6 +13,8 @@ import {
 } from "@/components/ui/dialog";
 import { useI18n, useScopedT } from "@/contexts/I18nContext";
 import { useShortcuts } from "@/contexts/ShortcutsContext";
+import type { GuideSession } from "@/guide/contracts";
+import { buildGuideVideoAnnotations, buildGuideVideoSpeedRegions } from "@/guide/videoAnnotations";
 import { INITIAL_EDITOR_STATE, useEditorHistory } from "@/hooks/useEditorHistory";
 import { type Locale } from "@/i18n/config";
 import { getAvailableLocales, getLocaleName } from "@/i18n/loader";
@@ -1374,6 +1376,34 @@ export default function VideoEditor() {
 		[pushState],
 	);

+	const handleGuideAttachToVideo = useCallback(
+		(session: GuideSession) => {
+			const guideAnnotations = buildGuideVideoAnnotations(session, {
+				nextId: () => `annotation-${nextAnnotationIdRef.current++}`,
+				nextZIndex: () => nextAnnotationZIndexRef.current++,
+			});
+			const guideSpeedRegions = buildGuideVideoSpeedRegions(session, {
+				nextId: () => `speed-${nextSpeedIdRef.current++}`,
+			});
+			if (guideAnnotations.length === 0 && guideSpeedRegions.length === 0) {
+				toast.error("Generate a guide draft before attaching steps to the video.");
+				return;
+			}
+
+			pushState((prev) => ({
+				annotationRegions: [...prev.annotationRegions, ...guideAnnotations],
+				speedRegions: [...prev.speedRegions, ...guideSpeedRegions],
+			}));
+			const firstTextAnnotation = guideAnnotations.find((annotation) => annotation.type === "text");
+			setSelectedAnnotationId(firstTextAnnotation?.id ?? guideAnnotations[0]?.id ?? null);
+			setSelectedBlurId(null);
+			setSelectedZoomId(null);
+			setSelectedTrimId(null);
+			setSelectedSpeedId(null);
+		},
+		[pushState],
+	);
+
 	useEffect(() => {
 		const handleKeyDown = (e: KeyboardEvent) => {
 			const mod = e.ctrlKey || e.metaKey;
@@ -2162,6 +2192,7 @@ export default function VideoEditor() {
 										videoPath={videoPath}
 										videoSourcePath={videoSourcePath}
 										currentTimeMs={currentTime * 1000}
+										onAttachToVideo={handleGuideAttachToVideo}
 									/>
 								)}
 								<div className="min-h-0 flex-1 overflow-hidden">
@@ -1963,18 +1963,20 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 										region: blurRegion,
 									})),
 								].sort((a, b) => a.region.zIndex - b.region.zIndex);
-								const previewSnapshotCanvas =
-									filteredBlurRegions.length > 0
-										? (() => {
-												const app = appRef.current;
-												if (!app?.renderer?.extract) return null;
-												try {
-													return app.renderer.extract.canvas(app.stage);
-												} catch {
-													return null;
-												}
-											})()
-										: null;
+								const needsPreviewSnapshot =
+									filteredBlurRegions.length > 0 ||
+									filteredAnnotations.some((annotation) => annotation.type === "magnifier");
+								const previewSnapshotCanvas = needsPreviewSnapshot
+									? (() => {
+											const app = appRef.current;
+											if (!app?.renderer?.extract) return null;
+											try {
+												return app.renderer.extract.canvas(app.stage);
+											} catch {
+												return null;
+											}
+										})()
+									: null;

 								// Handle click-through cycling: when clicking same annotation, cycle to next
 								const handleAnnotationClick = (clickedId: string) => {
@@ -1,4 +1,4 @@
-import { KeyRound, ListChecks, RefreshCw, Save, Trash2, Wand2 } from "lucide-react";
+import { KeyRound, ListChecks, RefreshCw, Save, Trash2, Video, Wand2 } from "lucide-react";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
@@ -9,6 +9,7 @@ import type {
 	GuideLanguage,
 	GuideOcrProfile,
 	GuideSession,
+	GuideSnapshot,
 } from "@/guide/contracts";
 import { captureGuideSnapshots } from "@/guide/snapshot/extractGuideSnapshots";

@@ -17,9 +18,17 @@ interface GuidePanelProps {
 	videoPath: string | null;
 	videoSourcePath: string | null;
 	currentTimeMs: number;
+	onAttachToVideo?: (session: GuideSession) => void;
 }

-type BusyAction = "load" | "generate";
+type BusyAction = "load" | "generate" | "attach";
+
+interface GuideProgressState {
+	label: string;
+	current: number;
+	total: number;
+	detail?: string;
+}

 const COPY = {
 	en: {
@@ -63,6 +72,14 @@ const COPY = {
 		noEvents: "No click events were captured for this guide.",
 		ocrUnavailable: "Local OCR service is unavailable. You can still create a local draft.",
 		exported: "Guide exported",
+		attachToVideo: "Attach to video",
+		attachedToVideo: "Guide steps attached to the video timeline.",
+		noDraft: "Generate a guide draft before attaching steps to the video.",
+		progressPreparing: "Preparing events",
+		progressSnapshots: "Capturing snapshots",
+		progressOcr: "Running OCR",
+		progressDraft: "Writing draft",
+		progressExport: "Exporting files",
 	},
 	vi: {
 		title: "Hướng dẫn",
@@ -105,10 +122,41 @@ const COPY = {
 		noEvents: "Chưa ghi nhận click event nào cho guide này.",
 		ocrUnavailable: "OCR local chưa chạy. Vẫn có thể tạo draft local.",
 		exported: "Đã export hướng dẫn",
+		attachToVideo: "Gắn vào video",
+		attachedToVideo: "Đã gắn các bước guide vào timeline video.",
+		noDraft: "Hãy tạo draft guide trước khi gắn vào video.",
+		progressPreparing: "Đang chuẩn bị events",
+		progressSnapshots: "Đang chụp ảnh",
+		progressOcr: "Đang OCR",
+		progressDraft: "Đang tạo draft",
+		progressExport: "Đang export file",
 	},
 } as const;

-export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePanelProps) {
+function getPendingOcrSnapshots(session: GuideSession): GuideSnapshot[] {
+	const ocrCompletedSnapshotIds = new Set(session.ocrBlocks.map((block) => block.snapshotId));
+	return session.snapshots.filter(
+		(snapshot) => !snapshot.ocrCompletedAt && !ocrCompletedSnapshotIds.has(snapshot.id),
+	);
+}
+
+function getProgressPercent(progress: GuideProgressState | null): number {
+	if (!progress) {
+		return 0;
+	}
+	if (progress.total <= 0) {
+		return 100;
+	}
+	const percent = Math.round((progress.current / progress.total) * 100);
+	return Math.min(100, Math.max(progress.current > 0 ? 8 : 4, percent));
+}
+
+export function GuidePanel({
+	recordingId,
+	videoPath,
+	videoSourcePath,
+	onAttachToVideo,
+}: GuidePanelProps) {
 	const { locale } = useI18n();
 	const copy = useMemo(() => (locale.startsWith("vi") ? COPY.vi : COPY.en), [locale]);
 	const guideLanguage: GuideLanguage = locale.startsWith("vi") ? "vi" : "en";
@@ -124,8 +172,10 @@ export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePan
 	const [ocrProfile, setOcrProfile] = useState<GuideOcrProfile>("vietnamese");
 	const [ocrLanguage, setOcrLanguage] = useState("vi,en");
 	const [message, setMessage] = useState<string | null>(null);
+	const [progress, setProgress] = useState<GuideProgressState | null>(null);

 	const isBusy = busyAction !== null;
+	const progressPercent = getProgressPercent(progress);
 	const canUseGuide = Boolean(recordingId && videoSourcePath && window.electronAPI?.guide);
 	const generatedSteps = session?.generatedGuide?.steps ?? [];
 	const statusLabel = useMemo(() => {
@@ -220,6 +270,15 @@ export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePan
 		}

 		let current = session;
+		const readResult = await window.electronAPI.guide.readSession(recordingId);
+		if (readResult.success) {
+			current = readResult.data;
+		} else if (readResult.code === "guide-session-not-found") {
+			current = null;
+		} else if (!current) {
+			throw new Error(readResult.error);
+		}
+
 		if (!current) {
 			const startResult = await window.electronAPI.guide.startSession(recordingId);
 			if (!startResult.success) {
@@ -251,6 +310,7 @@ export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePan
 			}
 			setBusyAction(action);
 			setMessage(null);
+			setProgress(null);
 			try {
 				await task();
 			} catch (error) {
@@ -355,21 +415,59 @@ export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePan
 			if (!videoPath) {
 				throw new Error("Video URL is not available.");
 			}
+			setProgress({
+				label: copy.progressPreparing,
+				current: 0,
+				total: 1,
+				detail: "0/1",
+			});
 			let current = await ensureEventsSession();
+			setProgress({
+				label: copy.progressPreparing,
+				current: 1,
+				total: 1,
+				detail: "1/1",
+			});
 			if (current.events.length === 0) {
 				throw new Error(copy.noEvents);
 			}
-			if (current.snapshots.length < current.events.length) {
+			const snapshotEventIds = new Set(current.snapshots.map((snapshot) => snapshot.eventId));
+			const pendingSnapshotTotal = current.events.filter(
+				(event) => !snapshotEventIds.has(event.id),
+			).length;
+			if (pendingSnapshotTotal > 0) {
+				setProgress({
+					label: copy.progressSnapshots,
+					current: 0,
+					total: pendingSnapshotTotal,
+					detail: `0/${pendingSnapshotTotal}`,
+				});
 				current = await captureGuideSnapshots({
 					session: current,
 					videoUrl: videoPath,
 					maxWidth: 1280,
+					onProgress: ({ completed, total }) => {
+						setProgress({
+							label: copy.progressSnapshots,
+							current: completed,
+							total,
+							detail: `${completed}/${total}`,
+						});
+					},
 				});
 				setSession(current);
 			}
-			if (current.ocrBlocks.length === 0 && current.snapshots.length > 0) {
+			const pendingOcrSnapshots = getPendingOcrSnapshots(current);
+			for (const [index, snapshot] of pendingOcrSnapshots.entries()) {
+				setProgress({
+					label: copy.progressOcr,
+					current: index,
+					total: pendingOcrSnapshots.length,
+					detail: `${index + 1}/${pendingOcrSnapshots.length}`,
+				});
 				const ocrResult = await window.electronAPI.guide.runOcr({
 					recordingId: current.recordingId,
+					snapshotIds: [snapshot.id],
 				});
 				if (!ocrResult.success) {
 					if (ocrResult.code === "guide-ocr-unavailable") {
@@ -379,7 +477,19 @@ export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePan
 				}
 				current = ocrResult.data;
 				setSession(current);
+				setProgress({
+					label: copy.progressOcr,
+					current: index + 1,
+					total: pendingOcrSnapshots.length,
+					detail: `${index + 1}/${pendingOcrSnapshots.length}`,
+				});
 			}
+			setProgress({
+				label: copy.progressDraft,
+				current: 0,
+				total: 1,
+				detail: "0/1",
+			});
 			const result = await window.electronAPI.guide.generateDraft({
 				recordingId: current.recordingId,
 				language: guideLanguage,
@@ -388,18 +498,44 @@ export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePan
 			if (!result.success) {
 				throw new Error(result.error);
 			}
+			current = result.data;
+			setSession(current);
+			setProgress({
+				label: copy.progressDraft,
+				current: 1,
+				total: 1,
+				detail: "1/1",
+			});
+			setProgress({
+				label: copy.progressExport,
+				current: 0,
+				total: 2,
+				detail: "0/2",
+			});
 			const markdownResult = await window.electronAPI.guide.exportMarkdown({
 				recordingId: current.recordingId,
 			});
 			if (!markdownResult.success) {
 				throw new Error(markdownResult.error);
 			}
+			setProgress({
+				label: copy.progressExport,
+				current: 1,
+				total: 2,
+				detail: "1/2",
+			});
 			const htmlResult = await window.electronAPI.guide.exportHtml({
 				recordingId: current.recordingId,
 			});
 			if (!htmlResult.success) {
 				throw new Error(htmlResult.error);
 			}
+			setProgress({
+				label: copy.progressExport,
+				current: 2,
+				total: 2,
+				detail: "2/2",
+			});
 			const revealResult = await window.electronAPI.revealInFolder(htmlResult.data.path);
 			if (!revealResult.success) {
 				toast.warning(revealResult.error ?? "Unable to open guide folder.");
@@ -415,6 +551,11 @@ export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePan
 		copy.keyMissing,
 		copy.noEvents,
 		copy.ocrUnavailable,
+		copy.progressDraft,
+		copy.progressExport,
+		copy.progressOcr,
+		copy.progressPreparing,
+		copy.progressSnapshots,
 		ensureEventsSession,
 		guideLanguage,
 		provider,
@@ -422,6 +563,25 @@ export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePan
 		videoPath,
 	]);

+	const handleAttachToVideo = useCallback(() => {
+		if (!session?.generatedGuide || session.generatedGuide.steps.length === 0) {
+			setMessage(copy.noDraft);
+			toast.error(copy.noDraft);
+			return;
+		}
+		if (!onAttachToVideo) {
+			return;
+		}
+		setBusyAction("attach");
+		try {
+			onAttachToVideo(session);
+			setMessage(null);
+			toast.success(copy.attachedToVideo);
+		} finally {
+			setBusyAction(null);
+		}
+	}, [copy.attachedToVideo, copy.noDraft, onAttachToVideo, session]);
+
 	return (
 		<section className="editor-inspector-shell flex max-h-[320px] min-h-[246px] shrink-0 flex-col overflow-hidden rounded-[18px] border border-white/[0.075] bg-[#090a0c]">
 			<div className="flex items-center justify-between border-b border-white/[0.07] px-3 py-2">
@@ -445,6 +605,24 @@ export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePan
 					{canUseGuide ? statusLabel : copy.noRecording}
 				</p>
 				{message && <p className="mb-2 text-[11px] leading-4 text-amber-300">{message}</p>}
+				{progress && (
+					<div className="mb-2 rounded-md border border-white/[0.07] bg-white/[0.035] px-2 py-1.5">
+						<div className="mb-1 flex items-center justify-between gap-2 text-[10px] leading-4">
+							<span className="min-w-0 truncate font-semibold text-slate-200">
+								{progress.label}
+							</span>
+							<span className="shrink-0 text-slate-500">
+								{progress.detail ?? `${progress.current}/${progress.total}`}
+							</span>
+						</div>
+						<div className="h-1.5 overflow-hidden rounded-full bg-white/[0.06]">
+							<div
+								className="h-full rounded-full bg-[#34B27B] transition-all duration-200"
+								style={{ width: `${progressPercent}%` }}
+							/>
+						</div>
+					</div>
+				)}

 				<div className="mb-2 flex items-center gap-1.5">
 					<select
@@ -482,6 +660,16 @@ export function GuidePanel({ recordingId, videoPath, videoSourcePath }: GuidePan
 					</span>
 				</button>

+				<button
+					type="button"
+					disabled={!generatedSteps.length || isBusy || !onAttachToVideo}
+					onClick={handleAttachToVideo}
+					className="mb-2 flex h-9 w-full items-center justify-center gap-2 rounded-md border border-sky-400/25 bg-sky-400/10 px-3 text-xs font-semibold text-sky-100 transition-all hover:border-sky-300/45 hover:bg-sky-400/18 disabled:cursor-not-allowed disabled:opacity-40"
+				>
+					<Video className="h-3.5 w-3.5 shrink-0" />
+					<span className="truncate">{copy.attachToVideo}</span>
+				</button>
+
 				{settingsOpen && (
 					<div className="mb-2 space-y-2 rounded-md border border-white/[0.07] bg-white/[0.035] p-2">
 						<div className="flex items-center justify-between gap-2">
@@ -23,6 +23,7 @@ import {
 	DEFAULT_BLUR_FREEHAND_POINTS,
 	DEFAULT_BLUR_INTENSITY,
 	DEFAULT_FIGURE_DATA,
+	DEFAULT_MAGNIFIER_DATA,
 	DEFAULT_PLAYBACK_SPEED,
 	DEFAULT_ZOOM_DEPTH,
 	DEFAULT_ZOOM_MOTION_BLUR,
@@ -325,7 +326,10 @@ export function normalizeProjectEditor(editor: Partial<ProjectEditorState>): Pro
 						startMs,
 						endMs,
 						type:
-							region.type === "image" || region.type === "figure" || region.type === "blur"
+							region.type === "image" ||
+							region.type === "figure" ||
+							region.type === "blur" ||
+							region.type === "magnifier"
 								? region.type
 								: "text",
 						content: typeof region.content === "string" ? region.content : "",
@@ -410,6 +414,45 @@ export function normalizeProjectEditor(editor: Partial<ProjectEditorState>): Pro
 											: DEFAULT_BLUR_FREEHAND_POINTS,
 									}
 								: undefined,
+						magnifierData:
+							region.magnifierData && typeof region.magnifierData === "object"
+								? {
+										...DEFAULT_MAGNIFIER_DATA,
+										...region.magnifierData,
+										target: {
+											x: clamp(
+												isFiniteNumber(region.magnifierData.target?.x)
+													? region.magnifierData.target.x
+													: DEFAULT_MAGNIFIER_DATA.target.x,
+												0,
+												100,
+											),
+											y: clamp(
+												isFiniteNumber(region.magnifierData.target?.y)
+													? region.magnifierData.target.y
+													: DEFAULT_MAGNIFIER_DATA.target.y,
+												0,
+												100,
+											),
+										},
+										zoom: clamp(
+											isFiniteNumber(region.magnifierData.zoom)
+												? region.magnifierData.zoom
+												: DEFAULT_MAGNIFIER_DATA.zoom,
+											1,
+											6,
+										),
+										shape:
+											region.magnifierData.shape === "rounded" ||
+											region.magnifierData.shape === "circle"
+												? region.magnifierData.shape
+												: DEFAULT_MAGNIFIER_DATA.shape,
+										caption:
+											typeof region.magnifierData.caption === "string"
+												? region.magnifierData.caption
+												: undefined,
+									}
+								: undefined,
 					};
 				})
 		: [];
@@ -206,7 +206,7 @@ export interface TrimRegion {
 	endMs: number;
 }

-export type AnnotationType = "text" | "image" | "figure" | "blur";
+export type AnnotationType = "text" | "image" | "figure" | "blur" | "magnifier";

 export type ArrowDirection =
 	| "up"
@@ -245,6 +245,13 @@ export interface BlurData {
 	freehandPoints?: Array<{ x: number; y: number }>;
 }

+export interface MagnifierData {
+	target: AnnotationPosition;
+	zoom: number;
+	shape: "circle" | "rounded";
+	caption?: string;
+}
+
 export interface AnnotationPosition {
 	x: number;
 	y: number;
@@ -280,6 +287,7 @@ export interface AnnotationRegion {
 	zIndex: number;
 	figureData?: FigureData;
 	blurData?: BlurData;
+	magnifierData?: MagnifierData;
 }

 export const DEFAULT_ANNOTATION_POSITION: AnnotationPosition = {
@@ -330,6 +338,12 @@ export const DEFAULT_BLUR_DATA: BlurData = {
 	freehandPoints: DEFAULT_BLUR_FREEHAND_POINTS,
 };

+export const DEFAULT_MAGNIFIER_DATA: MagnifierData = {
+	target: { x: 50, y: 50 },
+	zoom: 2.2,
+	shape: "circle",
+};
+
 export interface CropRegion {
 	x: number;
 	y: number;
@@ -56,6 +56,7 @@ export interface GuideSnapshot {
 	offsetMs: number;
 	path: string;
 	markedPath?: string;
+	ocrCompletedAt?: string;
 	width: number;
 	height: number;
 }
@@ -4,6 +4,13 @@ export interface CaptureGuideSnapshotsInput {
 	session: GuideSession;
 	videoUrl: string;
 	maxWidth?: number;
+	onProgress?: (progress: CaptureGuideSnapshotsProgress) => void;
+}
+
+export interface CaptureGuideSnapshotsProgress {
+	event: GuideEvent;
+	completed: number;
+	total: number;
 }

 export async function captureGuideSnapshots(
@@ -13,6 +20,13 @@ export async function captureGuideSnapshots(
 	if (events.length === 0) {
 		return input.session;
 	}
+	const existingSnapshotsByEventId = new Set(
+		input.session.snapshots.map((snapshot) => snapshot.eventId),
+	);
+	const pendingEvents = events.filter((event) => !existingSnapshotsByEventId.has(event.id));
+	if (pendingEvents.length === 0) {
+		return input.session;
+	}

 	const video = document.createElement("video");
 	video.preload = "auto";
@@ -35,13 +49,8 @@ export async function captureGuideSnapshots(
 		canvas.height = Math.max(1, Math.round(sourceHeight * scale));

 		let latestSession = input.session;
-		const existingSnapshotsByEventId = new Set(
-			input.session.snapshots.map((snapshot) => snapshot.eventId),
-		);
-		for (const event of events) {
-			if (existingSnapshotsByEventId.has(event.id)) {
-				continue;
-			}
+		let completed = 0;
+		for (const event of pendingEvents) {
 			const offsetMs = event.screenshotOffsetMs ?? 500;
 			const timeMs = getSnapshotTimeMs(event, offsetMs, video.duration);
 			await seekVideo(video, timeMs / 1000);
@@ -65,6 +74,12 @@ export async function captureGuideSnapshots(
 				throw new Error(result.error);
 			}
 			latestSession = result.data;
+			completed += 1;
+			input.onProgress?.({
+				event,
+				completed,
+				total: pendingEvents.length,
+			});
 		}

 		return latestSession;
@@ -177,17 +192,7 @@ function drawSnapshotMarker(
 	point: { x: number; y: number },
 ) {
 	const shortSide = Math.max(1, Math.min(canvas.width, canvas.height));
-	const haloRadius = clampNumber(Math.round(shortSide * 0.012), 8, 14);
-	const dotRadius = clampNumber(Math.round(shortSide * 0.0045), 3, 6);
-	const lineWidth = Math.max(1, Math.round(shortSide * 0.0015));
-
-	context.beginPath();
-	context.arc(point.x, point.y, haloRadius, 0, Math.PI * 2);
-	context.fillStyle = "rgba(250, 204, 21, 0.34)";
-	context.fill();
-	context.lineWidth = lineWidth;
-	context.strokeStyle = "rgba(239, 68, 68, 0.72)";
-	context.stroke();
+	const dotRadius = clampNumber(Math.round(shortSide * 0.005), 4, 7);

 	context.beginPath();
 	context.arc(point.x, point.y, dotRadius, 0, Math.PI * 2);
@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { GUIDE_SCHEMA_VERSION, type GuideSession } from "./contracts";
+import { buildGuideVideoAnnotations, buildGuideVideoSpeedRegions } from "./videoAnnotations";
+
+function createSession(): GuideSession {
+	return {
+		schemaVersion: GUIDE_SCHEMA_VERSION,
+		recordingId: "recording-1",
+		videoPath: "recording.mp4",
+		guidePath: "recording.guide.json",
+		outputDir: "recording-guide",
+		status: "draft-ready",
+		events: [],
+		snapshots: [],
+		ocrBlocks: [],
+		candidates: [
+			{
+				id: "candidate-1",
+				eventId: "event-1",
+				timeMs: 1200,
+				action: "click",
+				targetText: "Settings",
+				targetRole: "button",
+				position: {
+					normalizedX: 0.2,
+					normalizedY: 0.25,
+					xPercent: 20,
+					yPercent: 25,
+					description: "top left",
+				},
+				nearbyText: ["Settings"],
+				confidence: 0.91,
+			},
+		],
+		generatedGuide: {
+			title: "Guide",
+			steps: [
+				{
+					id: "step-1",
+					order: 1,
+					title: "Open settings",
+					instruction: "Click Settings.",
+					sourceCandidateId: "candidate-1",
+				},
+			],
+		},
+		createdAt: "2026-06-04T00:00:00.000Z",
+		updatedAt: "2026-06-04T00:00:00.000Z",
+	};
+}
+
+describe("buildGuideVideoAnnotations", () => {
+	it("creates caption and pointer annotations from generated guide candidates", () => {
+		let id = 1;
+		let zIndex = 1;
+		const annotations = buildGuideVideoAnnotations(createSession(), {
+			nextId: () => `guide-video-${id++}`,
+			nextZIndex: () => zIndex++,
+		});
+
+		expect(annotations).toHaveLength(3);
+		expect(annotations[0]).toMatchObject({
+			id: "guide-video-1",
+			type: "text",
+			startMs: 1200,
+			content: "1. Click Settings.",
+		});
+		expect(annotations[0]?.endMs).toBe(3200);
+		expect(annotations[0]?.position.x).toBeGreaterThan(20);
+		expect(annotations[1]?.endMs).toBe(3200);
+		expect(annotations[1]?.position.x).toBeGreaterThan((annotations[0]?.position.x ?? 0) + 34);
+		expect(annotations[1]?.position.y).toBeCloseTo(30.5);
+		expect(annotations[1]).toMatchObject({
+			id: "guide-video-2",
+			type: "magnifier",
+			magnifierData: {
+				target: { x: 20, y: 25 },
+				zoom: 2.2,
+				shape: "circle",
+				caption: "Settings",
+			},
+		});
+		expect(annotations[2]).toMatchObject({
+			id: "guide-video-3",
+			type: "figure",
+			endMs: 3200,
+			figureData: {
+				arrowDirection: "left",
+				color: "#34B27B",
+			},
+		});
+		expect(annotations[2]?.position.x).toBeGreaterThan(20);
+	});
+
+	it("returns an empty list when no draft exists", () => {
+		const session = createSession();
+		session.generatedGuide = undefined;
+
+		const annotations = buildGuideVideoAnnotations(session, {
+			nextId: () => "unused",
+			nextZIndex: () => 1,
+		});
+
+		expect(annotations).toEqual([]);
+	});
+
+	it("creates 0.3x speed regions for two seconds at each guide point", () => {
+		let id = 1;
+		const speedRegions = buildGuideVideoSpeedRegions(createSession(), {
+			nextId: () => `guide-speed-${id++}`,
+		});
+
+		expect(speedRegions).toEqual([
+			{
+				id: "guide-speed-1",
+				startMs: 1200,
+				endMs: 3200,
+				speed: 0.3,
+			},
+		]);
+	});
+});
@@ -0,0 +1,249 @@
+import {
+	type AnnotationRegion,
+	type ArrowDirection,
+	DEFAULT_ANNOTATION_STYLE,
+	DEFAULT_FIGURE_DATA,
+	DEFAULT_MAGNIFIER_DATA,
+	type SpeedRegion,
+} from "@/components/video-editor/types";
+import type { GeneratedGuideStep, GuideSession, GuideStepCandidate } from "./contracts";
+
+export interface BuildGuideVideoAnnotationsOptions {
+	nextId: () => string;
+	nextZIndex: () => number;
+	defaultDurationMs?: number;
+}
+
+const DEFAULT_STEP_DURATION_MS = 2000;
+const DEFAULT_STEP_SLOW_MOTION_DURATION_MS = 2000;
+const DEFAULT_STEP_SLOW_MOTION_SPEED = 0.3;
+const CAPTION_WIDTH = 34;
+const CAPTION_HEIGHT = 13;
+const MAGNIFIER_SIZE = 18;
+const ARROW_SIZE = 10;
+const ANNOTATION_GAP = 2;
+
+function clamp(value: number, min: number, max: number) {
+	return Math.min(max, Math.max(min, value));
+}
+
+function findCandidate(
+	step: GeneratedGuideStep,
+	stepIndex: number,
+	candidates: GuideStepCandidate[],
+): GuideStepCandidate | undefined {
+	if (step.sourceCandidateId) {
+		const matched = candidates.find((candidate) => candidate.id === step.sourceCandidateId);
+		if (matched) return matched;
+	}
+	const sorted = [...candidates].sort((left, right) => left.timeMs - right.timeMs);
+	return sorted[stepIndex];
+}
+
+function getCaptionPosition(candidate: GuideStepCandidate | undefined) {
+	const target = candidate?.position;
+	if (!target) {
+		return { x: 8, y: 8 };
+	}
+
+	const targetX = target.normalizedX * 100;
+	const targetY = target.normalizedY * 100;
+	const x = target.normalizedX < 0.5 ? targetX + 8 : targetX - CAPTION_WIDTH - 8;
+	const y = target.normalizedY < 0.5 ? targetY + 8 : targetY - CAPTION_HEIGHT - 8;
+
+	return {
+		x: clamp(x, 2, 100 - CAPTION_WIDTH - 2),
+		y: clamp(y, 2, 100 - CAPTION_HEIGHT - 2),
+	};
+}
+
+function getArrowDirection(
+	candidate: GuideStepCandidate | undefined,
+	originPosition: { x: number; y: number },
+	originSize: { width: number; height: number } = {
+		width: CAPTION_WIDTH,
+		height: CAPTION_HEIGHT,
+	},
+): ArrowDirection {
+	const target = candidate?.position;
+	if (!target) return "right";
+
+	const originCenterX = originPosition.x + originSize.width / 2;
+	const originCenterY = originPosition.y + originSize.height / 2;
+	const dx = target.normalizedX * 100 - originCenterX;
+	const dy = target.normalizedY * 100 - originCenterY;
+	const horizontal = dx > 8 ? "right" : dx < -8 ? "left" : "";
+	const vertical = dy > 8 ? "down" : dy < -8 ? "up" : "";
+
+	if (vertical && horizontal) return `${vertical}-${horizontal}` as ArrowDirection;
+	return (horizontal || vertical || "right") as ArrowDirection;
+}
+
+function getMagnifierPosition(captionPosition: { x: number; y: number }) {
+	const canPlaceRight = captionPosition.x + CAPTION_WIDTH + ANNOTATION_GAP + MAGNIFIER_SIZE <= 98;
+	const x = canPlaceRight
+		? captionPosition.x + CAPTION_WIDTH + ANNOTATION_GAP
+		: captionPosition.x - MAGNIFIER_SIZE - ANNOTATION_GAP;
+	const y = captionPosition.y + (CAPTION_HEIGHT - MAGNIFIER_SIZE) / 2;
+
+	return {
+		x: clamp(x, 2, 100 - MAGNIFIER_SIZE - 2),
+		y: clamp(y, 2, 100 - MAGNIFIER_SIZE - 2),
+	};
+}
+
+function getArrowPosition(
+	position: NonNullable<GuideStepCandidate["position"]>,
+	originPosition: { x: number; y: number },
+	originSize: { width: number; height: number },
+) {
+	const targetX = position.normalizedX * 100;
+	const targetY = position.normalizedY * 100;
+	const originCenterX = originPosition.x + originSize.width / 2;
+	const originCenterY = originPosition.y + originSize.height / 2;
+	const distance = Math.hypot(targetX - originCenterX, targetY - originCenterY);
+	const targetOffset = Math.min(18, Math.max(10, distance * 0.35));
+	const ratio = distance > 0 ? Math.max(0, (distance - targetOffset) / distance) : 0;
+	const arrowCenterX = originCenterX + (targetX - originCenterX) * ratio;
+	const arrowCenterY = originCenterY + (targetY - originCenterY) * ratio;
+
+	return {
+		x: clamp(arrowCenterX - ARROW_SIZE / 2, 0, 100 - ARROW_SIZE),
+		y: clamp(arrowCenterY - ARROW_SIZE / 2, 0, 100 - ARROW_SIZE),
+	};
+}
+
+function buildCaption(step: GeneratedGuideStep) {
+	const instruction = step.instruction.trim();
+	const title = step.title.trim();
+	if (instruction) {
+		return `${step.order}. ${instruction}`;
+	}
+	return title ? `${step.order}. ${title}` : `Step ${step.order}`;
+}
+
+export function buildGuideVideoAnnotations(
+	session: GuideSession,
+	options: BuildGuideVideoAnnotationsOptions,
+): AnnotationRegion[] {
+	const guide = session.generatedGuide;
+	if (!guide || guide.steps.length === 0) {
+		return [];
+	}
+
+	const durationMs = Math.max(1000, options.defaultDurationMs ?? DEFAULT_STEP_DURATION_MS);
+	const sortedSteps = [...guide.steps].sort((left, right) => left.order - right.order);
+	const annotations: AnnotationRegion[] = [];
+
+	for (const [index, step] of sortedSteps.entries()) {
+		const candidate = findCandidate(step, index, session.candidates);
+		const startMs = Math.max(0, Math.round(candidate?.timeMs ?? index * durationMs));
+		const endMs = Math.max(startMs + 750, startMs + durationMs);
+		const captionPosition = getCaptionPosition(candidate);
+
+		annotations.push({
+			id: options.nextId(),
+			startMs,
+			endMs,
+			type: "text",
+			content: buildCaption(step),
+			textContent: buildCaption(step),
+			position: captionPosition,
+			size: { width: CAPTION_WIDTH, height: CAPTION_HEIGHT },
+			style: {
+				...DEFAULT_ANNOTATION_STYLE,
+				color: "#f8fafc",
+				backgroundColor: "rgba(15, 23, 42, 0.88)",
+				fontSize: 18,
+				fontWeight: "bold",
+				textAlign: "left",
+			},
+			zIndex: options.nextZIndex(),
+		});
+
+		if (candidate?.position) {
+			const magnifierPosition = getMagnifierPosition(captionPosition);
+			const arrowPosition = getArrowPosition(candidate.position, magnifierPosition, {
+				width: MAGNIFIER_SIZE,
+				height: MAGNIFIER_SIZE,
+			});
+			const arrowDirection = getArrowDirection(candidate, arrowPosition, {
+				width: ARROW_SIZE,
+				height: ARROW_SIZE,
+			});
+
+			annotations.push({
+				id: options.nextId(),
+				startMs,
+				endMs,
+				type: "magnifier",
+				content: buildCaption(step),
+				position: magnifierPosition,
+				size: { width: MAGNIFIER_SIZE, height: MAGNIFIER_SIZE },
+				style: { ...DEFAULT_ANNOTATION_STYLE },
+				zIndex: options.nextZIndex(),
+				magnifierData: {
+					...DEFAULT_MAGNIFIER_DATA,
+					target: {
+						x: candidate.position.normalizedX * 100,
+						y: candidate.position.normalizedY * 100,
+					},
+					caption: candidate.targetText,
+				},
+			});
+			annotations.push({
+				id: options.nextId(),
+				startMs,
+				endMs,
+				type: "figure",
+				content: "",
+				position: arrowPosition,
+				size: { width: ARROW_SIZE, height: ARROW_SIZE },
+				style: { ...DEFAULT_ANNOTATION_STYLE },
+				zIndex: options.nextZIndex(),
+				figureData: {
+					...DEFAULT_FIGURE_DATA,
+					arrowDirection,
+					color: "#34B27B",
+					strokeWidth: 5,
+				},
+			});
+		}
+	}
+
+	return annotations;
+}
+
+export interface BuildGuideVideoSpeedRegionsOptions {
+	nextId: () => string;
+	durationMs?: number;
+	speed?: number;
+}
+
+export function buildGuideVideoSpeedRegions(
+	session: GuideSession,
+	options: BuildGuideVideoSpeedRegionsOptions,
+): SpeedRegion[] {
+	const guide = session.generatedGuide;
+	if (!guide || guide.steps.length === 0) {
+		return [];
+	}
+
+	const durationMs = Math.max(
+		100,
+		Math.round(options.durationMs ?? DEFAULT_STEP_SLOW_MOTION_DURATION_MS),
+	);
+	const speed = options.speed ?? DEFAULT_STEP_SLOW_MOTION_SPEED;
+	const sortedSteps = [...guide.steps].sort((left, right) => left.order - right.order);
+
+	return sortedSteps.map((step, index) => {
+		const candidate = findCandidate(step, index, session.candidates);
+		const startMs = Math.max(0, Math.round(candidate?.timeMs ?? index * durationMs));
+		return {
+			id: options.nextId(),
+			startMs,
+			endMs: startMs + durationMs,
+			speed,
+		};
+	});
+}
@@ -9,6 +9,8 @@ import {

 let blurScratchCanvas: HTMLCanvasElement | null = null;
 let blurScratchCtx: CanvasRenderingContext2D | null = null;
+let magnifierScratchCanvas: HTMLCanvasElement | null = null;
+let magnifierScratchCtx: CanvasRenderingContext2D | null = null;

 // Matches a single code point whose script is Han (including non-BMP
 // Extension A-F), Hiragana, Katakana (including halfwidth forms), or
@@ -396,6 +398,130 @@ async function renderImage(
 	});
 }

+function renderMagnifier(
+	ctx: CanvasRenderingContext2D,
+	annotation: AnnotationRegion,
+	x: number,
+	y: number,
+	width: number,
+	height: number,
+	canvasWidth: number,
+	canvasHeight: number,
+	scaleFactor: number,
+) {
+	if (!magnifierScratchCanvas || !magnifierScratchCtx) {
+		magnifierScratchCanvas = document.createElement("canvas");
+		magnifierScratchCtx = magnifierScratchCanvas.getContext("2d");
+	}
+	if (!magnifierScratchCanvas || !magnifierScratchCtx) return;
+
+	const data = annotation.magnifierData;
+	const zoom = Math.max(1, data?.zoom ?? 2.2);
+	const target = data?.target ?? {
+		x: annotation.position.x + annotation.size.width / 2,
+		y: annotation.position.y + annotation.size.height / 2,
+	};
+	const targetX = (target.x / 100) * canvasWidth;
+	const targetY = (target.y / 100) * canvasHeight;
+	const sampleWidth = Math.max(1, width / zoom);
+	const sampleHeight = Math.max(1, height / zoom);
+	const sx = Math.max(0, Math.min(canvasWidth - sampleWidth, targetX - sampleWidth / 2));
+	const sy = Math.max(0, Math.min(canvasHeight - sampleHeight, targetY - sampleHeight / 2));
+	const sw = Math.max(1, Math.min(sampleWidth, canvasWidth - sx));
+	const sh = Math.max(1, Math.min(sampleHeight, canvasHeight - sy));
+
+	magnifierScratchCanvas.width = Math.max(1, Math.round(width));
+	magnifierScratchCanvas.height = Math.max(1, Math.round(height));
+	magnifierScratchCtx.clearRect(0, 0, magnifierScratchCanvas.width, magnifierScratchCanvas.height);
+	magnifierScratchCtx.imageSmoothingEnabled = true;
+	magnifierScratchCtx.imageSmoothingQuality = "high";
+	magnifierScratchCtx.drawImage(
+		ctx.canvas,
+		sx,
+		sy,
+		sw,
+		sh,
+		0,
+		0,
+		magnifierScratchCanvas.width,
+		magnifierScratchCanvas.height,
+	);
+
+	const centerX = x + width / 2;
+	const centerY = y + height / 2;
+	const shape = data?.shape ?? "circle";
+	const radius = Math.min(width, height) / 2;
+	const cornerRadius = shape === "circle" ? radius : Math.min(18 * scaleFactor, radius);
+
+	ctx.save();
+	ctx.strokeStyle = "rgba(52,178,123,0.85)";
+	ctx.lineWidth = Math.max(2, 2 * scaleFactor);
+	ctx.beginPath();
+	ctx.moveTo(centerX, centerY);
+	ctx.lineTo(targetX, targetY);
+	ctx.stroke();
+	ctx.fillStyle = "#34B27B";
+	ctx.beginPath();
+	ctx.arc(targetX, targetY, Math.max(4, 4 * scaleFactor), 0, Math.PI * 2);
+	ctx.fill();
+
+	ctx.shadowColor = "rgba(0,0,0,0.38)";
+	ctx.shadowBlur = 24 * scaleFactor;
+	ctx.shadowOffsetY = 12 * scaleFactor;
+	ctx.fillStyle = "rgba(15,23,42,0.92)";
+	ctx.beginPath();
+	ctx.roundRect(x, y, width, height, cornerRadius);
+	ctx.fill();
+	ctx.restore();
+
+	ctx.save();
+	ctx.beginPath();
+	ctx.roundRect(x, y, width, height, cornerRadius);
+	ctx.clip();
+	ctx.drawImage(magnifierScratchCanvas, x, y, width, height);
+	ctx.restore();
+
+	ctx.save();
+	ctx.strokeStyle = "rgba(248,250,252,0.96)";
+	ctx.lineWidth = Math.max(3, 3 * scaleFactor);
+	ctx.beginPath();
+	ctx.roundRect(x, y, width, height, cornerRadius);
+	ctx.stroke();
+	ctx.strokeStyle = "rgba(52,178,123,0.58)";
+	ctx.lineWidth = Math.max(1, 1.5 * scaleFactor);
+	ctx.beginPath();
+	ctx.roundRect(
+		x + 2 * scaleFactor,
+		y + 2 * scaleFactor,
+		width - 4 * scaleFactor,
+		height - 4 * scaleFactor,
+		cornerRadius,
+	);
+	ctx.stroke();
+
+	const caption = data?.caption || "";
+	if (caption) {
+		const fontSize = Math.max(12, 13 * scaleFactor);
+		ctx.font = `bold ${fontSize}px Inter, sans-serif`;
+		ctx.textAlign = "center";
+		ctx.textBaseline = "middle";
+		const paddingX = 8 * scaleFactor;
+		const paddingY = 5 * scaleFactor;
+		const metrics = ctx.measureText(caption);
+		const captionWidth = Math.min(width * 1.6, metrics.width + paddingX * 2);
+		const captionHeight = fontSize + paddingY * 2;
+		const captionX = centerX - captionWidth / 2;
+		const captionY = y + height + 8 * scaleFactor;
+		ctx.fillStyle = "rgba(15,23,42,0.92)";
+		ctx.beginPath();
+		ctx.roundRect(captionX, captionY, captionWidth, captionHeight, 6 * scaleFactor);
+		ctx.fill();
+		ctx.fillStyle = "#f8fafc";
+		ctx.fillText(caption, centerX, captionY + captionHeight / 2, captionWidth - paddingX * 2);
+	}
+	ctx.restore();
+}
+
 export async function renderAnnotations(
 	ctx: CanvasRenderingContext2D,
 	annotations: AnnotationRegion[],
@@ -443,6 +569,20 @@ export async function renderAnnotations(
 				}
 				break;

+			case "magnifier":
+				renderMagnifier(
+					ctx,
+					annotation,
+					x,
+					y,
+					width,
+					height,
+					canvasWidth,
+					canvasHeight,
+					scaleFactor,
+				);
+				break;
+
 			case "blur":
 				renderBlur(ctx, annotation, x, y, width, height, scaleFactor);
 				break;
@@ -0,0 +1,29 @@
+export type UpdateStatusPhase =
+	| "idle"
+	| "checking"
+	| "available"
+	| "not-available"
+	| "downloading"
+	| "downloaded"
+	| "error"
+	| "unsupported";
+
+export interface UpdateStatus {
+	phase: UpdateStatusPhase;
+	currentVersion: string;
+	version?: string;
+	releaseName?: string;
+	releaseNotes?: string;
+	percent?: number;
+	bytesPerSecond?: number;
+	transferred?: number;
+	total?: number;
+	error?: string;
+	updatedAt: string;
+}
+
+export interface UpdateCheckResult {
+	success: boolean;
+	status: UpdateStatus;
+	error?: string;
+}
Author	SHA1	Message	Date
huanld	5069354df3	Adjust guide video annotation timing CI / Lint (push) Has been cancelled Details CI / Type Check (push) Has been cancelled Details CI / Test (push) Has been cancelled Details CI / Build (push) Has been cancelled Details Bump Nix package on release / bump (release) Has been cancelled Details Update Homebrew Cask / update-cask (release) Has been cancelled Details	2026-06-05 20:39:26 +07:00
huanld	ee69df9222	Bump version to 1.4.11 for updater release CI / Lint (push) Has been cancelled Details CI / Type Check (push) Has been cancelled Details CI / Test (push) Has been cancelled Details CI / Build (push) Has been cancelled Details	2026-06-05 16:17:26 +07:00
huanld	a235a0c50b	Add automatic update checks CI / Lint (push) Has been cancelled Details CI / Type Check (push) Has been cancelled Details CI / Test (push) Has been cancelled Details CI / Build (push) Has been cancelled Details	2026-06-05 10:54:22 +07:00
huanld	94490a71af	Add guide video magnifier annotations CI / Lint (push) Has been cancelled Details CI / Type Check (push) Has been cancelled Details CI / Test (push) Has been cancelled Details CI / Build (push) Has been cancelled Details	2026-06-05 05:58:14 +07:00
huanld	6ebabbaaaa	Defer guide OCR to generate progress CI / Lint (push) Has been cancelled Details CI / Type Check (push) Has been cancelled Details CI / Test (push) Has been cancelled Details CI / Build (push) Has been cancelled Details	2026-05-28 21:05:39 +07:00
huanld	0bd26eebf7	Track guide OCR snapshot progress	2026-05-28 19:35:42 +07:00