Add guide video magnifier annotations

Defer guide OCR to generate progress
Track guide OCR snapshot progress
2026-06-05 05:58:14 +07:00 · 2026-05-28 21:05:39 +07:00 · 2026-05-28 19:35:42 +07:00
16 changed files with 1071 additions and 279 deletions
@@ -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);
@@ -1,12 +1,12 @@
 {
 	"name": "openscreen",
-	"version": "1.4.8",
+	"version": "1.4.10",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "openscreen",
-			"version": "1.4.8",
+			"version": "1.4.10",
 			"dependencies": {
 				"@fix-webm-duration/fix": "^1.0.1",
 				"@pixi/filter-drop-shadow": "^5.2.0",
@@ -1,7 +1,7 @@
 {
 	"name": "openscreen",
 	"private": true,
-	"version": "1.4.8",
+	"version": "1.4.10",
 	"type": "module",
 	"packageManager": "npm@10.9.4",
 	"engines": {
@@ -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,115 @@
+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]?.position.x).toBeGreaterThan(20);
+		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",
+			figureData: {
+				color: "#34B27B",
+			},
+		});
+	});
+
+	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 one second 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: 2200,
+				speed: 0.3,
+			},
+		]);
+	});
+});
@@ -0,0 +1,215 @@
+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 = 3200;
+const DEFAULT_STEP_SLOW_MOTION_DURATION_MS = 1000;
+const DEFAULT_STEP_SLOW_MOTION_SPEED = 0.3;
+const CAPTION_WIDTH = 34;
+const CAPTION_HEIGHT = 13;
+const MAGNIFIER_SIZE = 18;
+const ARROW_SIZE = 10;
+
+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,
+	captionPosition: { x: number; y: number },
+): ArrowDirection {
+	const target = candidate?.position;
+	if (!target) return "right";
+
+	const captionCenterX = captionPosition.x + CAPTION_WIDTH / 2;
+	const captionCenterY = captionPosition.y + CAPTION_HEIGHT / 2;
+	const dx = target.normalizedX * 100 - captionCenterX;
+	const dy = target.normalizedY * 100 - captionCenterY;
+	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 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);
+		const arrowDirection = getArrowDirection(candidate, captionPosition);
+
+		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) {
+			annotations.push({
+				id: options.nextId(),
+				startMs,
+				endMs,
+				type: "magnifier",
+				content: buildCaption(step),
+				position: {
+					x: clamp(
+						candidate.position.normalizedX * 100 - MAGNIFIER_SIZE / 2,
+						0,
+						100 - MAGNIFIER_SIZE,
+					),
+					y: clamp(
+						candidate.position.normalizedY * 100 - MAGNIFIER_SIZE / 2,
+						0,
+						100 - MAGNIFIER_SIZE,
+					),
+				},
+				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: {
+					x: clamp(candidate.position.normalizedX * 100 - ARROW_SIZE / 2, 0, 100 - ARROW_SIZE),
+					y: clamp(candidate.position.normalizedY * 100 - ARROW_SIZE / 2, 0, 100 - ARROW_SIZE),
+				},
+				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;
Author	SHA1	Message	Date
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