@editframe/elements 0.33.0-beta → 0.34.6-beta

package/dist/preview/renderTimegroupToCanvas.js

@@ -1,17 +1,17 @@
-import { DEFAULT_BLOCKING_TIMEOUT_MS, DEFAULT_HEIGHT, DEFAULT_THUMBNAIL_SCALE, DEFAULT_WIDTH, JPEG_QUALITY_HIGH, JPEG_QUALITY_MEDIUM, createPreviewContainer, isVisibleAtTime } from "./previewTypes.js";
-import { buildCloneStructure, collectDocumentStyles, overrideRootCloneStyles, syncStyles } from "./renderTimegroupPreview.js";
+import { FrameController } from "./FrameController.js";
+import { logger } from "./logger.js";
+import { DEFAULT_BLOCKING_TIMEOUT_MS, DEFAULT_HEIGHT, DEFAULT_THUMBNAIL_SCALE, DEFAULT_WIDTH, createPreviewContainer, isVisibleAtTime } from "./previewTypes.js";
+import { buildCloneStructure, collectDocumentStyles, overrideRootCloneStyles, removeHiddenNodesForSerialization, restoreHiddenNodes, syncStyles } from "./renderTimegroupPreview.js";
 import { getEffectiveRenderMode } from "./renderers.js";
-import { WorkerPool, encodeCanvasInWorker } from "./workers/WorkerPool.js";
-import { getEncoderWorkerUrl } from "./workers/encoderWorkerInline.js";
+import { RenderContext } from "./RenderContext.js";
 import { defaultProfiler } from "./RenderProfiler.js";
+import { createDprCanvas, renderToImageNative } from "./rendering/renderToImageNative.js";
+import { clearInlineImageCache } from "./rendering/inlineImages.js";
+import { loadImageFromDataUri, renderToImage, renderToImageDirect } from "./rendering/renderToImage.js";
 
 //#region src/preview/renderTimegroupToCanvas.ts
 /** Number of rows to sample when checking canvas content */
 const CANVAS_SAMPLE_STRIP_HEIGHT = 4;
-/** Interval between profiling log outputs (ms) */
-const PROFILING_LOG_INTERVAL_MS = 2e3;
-/** Maximum number of cached inline images before eviction */
-const MAX_INLINE_IMAGE_CACHE_SIZE = 100;
 /**
 * Error thrown when video content is not ready within the blocking timeout.
 */
@@ -24,159 +24,28 @@ var ContentNotReadyError = class extends Error {
 		this.name = "ContentNotReadyError";
 	}
 };
-/** Image cache for inlining external images as data URIs (foreignObject path) */
-const _inlineImageCache = /* @__PURE__ */ new Map();
-/** Track canvases that have been initialized for layoutsubtree (only need to wait once) */
-const _layoutInitializedCanvases = /* @__PURE__ */ new WeakSet();
-let _xmlSerializer = null;
-let _textEncoder = null;
-let _workerPool = null;
-let _workerPoolWarningLogged = false;
 /**
-* Get or create the worker pool for canvas encoding.
-* Returns null if workers are not available.
+* Module-level state for render operations.
+* Note: xmlSerializer is lazy-initialized for Node.js compatibility
 */
-function getWorkerPool() {
-	if (_workerPool) return _workerPool;
-	if (typeof Worker === "undefined" || typeof OffscreenCanvas === "undefined" || typeof createImageBitmap === "undefined") {
-		if (!_workerPoolWarningLogged) {
-			_workerPoolWarningLogged = true;
-			console.warn("[renderTimegroupToCanvas] Web Workers or OffscreenCanvas not available, using main thread fallback");
-		}
-		return null;
-	}
-	try {
-		_workerPool = new WorkerPool(getEncoderWorkerUrl());
-		if (!_workerPool.isAvailable()) {
-			const reason = _workerPool.workerCount === 0 ? "no workers created (check console for errors)" : "workers not available";
-			_workerPool = null;
-			if (!_workerPoolWarningLogged) {
-				_workerPoolWarningLogged = true;
-				console.warn(`[renderTimegroupToCanvas] Worker pool initialization failed (${reason}), using main thread fallback`);
-			}
-		}
-	} catch (error) {
-		_workerPool = null;
-		if (!_workerPoolWarningLogged) {
-			_workerPoolWarningLogged = true;
-			const errorMessage = error instanceof Error ? error.message : String(error);
-			console.warn(`[renderTimegroupToCanvas] Failed to create worker pool: ${errorMessage} - using main thread fallback`);
-		}
-	}
-	return _workerPool;
-}
-/**
-* Encode a single canvas to a data URL (fallback implementation for main thread).
-*/
-function encodeCanvasOnMainThread(canvas, canvasScale) {
-	try {
-		if (canvas.width === 0 || canvas.height === 0) return null;
-		const preserveAlpha = canvas.dataset.preserveAlpha === "true";
-		let dataUrl;
-		if (canvasScale < 1) {
-			const scaledWidth = Math.floor(canvas.width * canvasScale);
-			const scaledHeight = Math.floor(canvas.height * canvasScale);
-			const scaledCanvas = document.createElement("canvas");
-			scaledCanvas.width = scaledWidth;
-			scaledCanvas.height = scaledHeight;
-			const scaledCtx = scaledCanvas.getContext("2d");
-			if (scaledCtx) {
-				scaledCtx.drawImage(canvas, 0, 0, scaledWidth, scaledHeight);
-				const quality = canvasScale < .5 ? JPEG_QUALITY_MEDIUM : JPEG_QUALITY_HIGH;
-				dataUrl = preserveAlpha ? scaledCanvas.toDataURL("image/png") : scaledCanvas.toDataURL("image/jpeg", quality);
-			} else dataUrl = preserveAlpha ? canvas.toDataURL("image/png") : canvas.toDataURL("image/jpeg", JPEG_QUALITY_HIGH);
-		} else dataUrl = preserveAlpha ? canvas.toDataURL("image/png") : canvas.toDataURL("image/jpeg", JPEG_QUALITY_HIGH);
-		return {
-			dataUrl,
-			preserveAlpha
-		};
-	} catch (e) {
-		return null;
+const renderState = {
+	inlineImageCache: /* @__PURE__ */ new Map(),
+	layoutInitializedCanvases: /* @__PURE__ */ new WeakSet(),
+	xmlSerializer: null,
+	textEncoder: new TextEncoder(),
+	metrics: {
+		inlineImageCacheHits: 0,
+		inlineImageCacheMisses: 0,
+		inlineImageCacheEvictions: 0
 	}
-}
-/**
-* Encode canvases to data URLs in parallel using worker pool.
-* Falls back to main thread encoding if workers are unavailable.
-*/
-async function encodeCanvasesInParallel(canvases, canvasScale = 1) {
-	const workerPool = getWorkerPool();
-	if (!workerPool) {
-		const results = [];
-		for (const canvas of canvases) {
-			const encoded = encodeCanvasOnMainThread(canvas, canvasScale);
-			if (encoded) results.push({
-				canvas,
-				...encoded
-			});
-		}
-		return results;
-	}
-	const encodingTasks = canvases.map(async (canvas) => {
-		try {
-			if (canvas.width === 0 || canvas.height === 0) return null;
-			const preserveAlpha = canvas.dataset.preserveAlpha === "true";
-			let sourceCanvas = canvas;
-			if (canvasScale < 1) {
-				const scaledWidth = Math.floor(canvas.width * canvasScale);
-				const scaledHeight = Math.floor(canvas.height * canvasScale);
-				const scaledCanvas = document.createElement("canvas");
-				scaledCanvas.width = scaledWidth;
-				scaledCanvas.height = scaledHeight;
-				const scaledCtx = scaledCanvas.getContext("2d");
-				if (scaledCtx) {
-					scaledCtx.drawImage(canvas, 0, 0, scaledWidth, scaledHeight);
-					sourceCanvas = scaledCanvas;
-				}
-			}
-			return {
-				canvas,
-				dataUrl: await workerPool.execute((worker) => encodeCanvasInWorker(worker, sourceCanvas, preserveAlpha)),
-				preserveAlpha
-			};
-		} catch (error) {
-			const encoded = encodeCanvasOnMainThread(canvas, canvasScale);
-			if (encoded) return {
-				canvas,
-				...encoded
-			};
-			return null;
-		}
-	});
-	return (await Promise.all(encodingTasks)).filter((r) => r !== null);
-}
+};
 /**
-* Fast base64 encoding directly from Uint8Array.
-* Avoids the overhead of converting to binary string first.
-* Uses lookup table for optimal performance.
+* Reset cache metrics to zero.
 */
-function encodeBase64Fast(bytes) {
-	const base64Chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-	let result = "";
-	let i = 0;
-	const len = bytes.length;
-	while (i < len - 2) {
-		const byte1 = bytes[i++];
-		const byte2 = bytes[i++];
-		const byte3 = bytes[i++];
-		const bitmap = byte1 << 16 | byte2 << 8 | byte3;
-		result += base64Chars.charAt(bitmap >> 18 & 63);
-		result += base64Chars.charAt(bitmap >> 12 & 63);
-		result += base64Chars.charAt(bitmap >> 6 & 63);
-		result += base64Chars.charAt(bitmap & 63);
-	}
-	if (i < len) {
-		const byte1 = bytes[i++];
-		const bitmap = byte1 << 16;
-		result += base64Chars.charAt(bitmap >> 18 & 63);
-		result += base64Chars.charAt(bitmap >> 12 & 63);
-		if (i < len) {
-			const byte2 = bytes[i++];
-			const bitmap2 = byte1 << 16 | byte2 << 8;
-			result += base64Chars.charAt(bitmap2 >> 6 & 63);
-			result += "=";
-		} else result += "==";
-	}
-	return result;
+function resetCacheMetrics() {
+	renderState.metrics.inlineImageCacheHits = 0;
+	renderState.metrics.inlineImageCacheMisses = 0;
+	renderState.metrics.inlineImageCacheEvictions = 0;
 }
 /**
 * Reset all module state including profiling counters, caches, and logging flags.
@@ -184,22 +53,8 @@ function encodeBase64Fast(bytes) {
 */
 function resetRenderState() {
 	defaultProfiler.reset();
-	_inlineImageCache.clear();
-}
-/**
-* Create a canvas element with proper DPR handling.
-* Buffer size is based on renderWidth/renderHeight (internal resolution).
-* CSS size is based on fullWidth/fullHeight (logical display size).
-*/
-function createDprCanvas(options) {
-	const { renderWidth, renderHeight, scale, fullWidth, fullHeight } = options;
-	const dpr = options.dpr ?? window.devicePixelRatio ?? 1;
-	const canvas = document.createElement("canvas");
-	canvas.width = Math.floor(renderWidth * scale * dpr);
-	canvas.height = Math.floor(renderHeight * scale * dpr);
-	canvas.style.width = `${Math.floor(fullWidth * scale)}px`;
-	canvas.style.height = `${Math.floor(fullHeight * scale)}px`;
-	return canvas;
+	clearInlineImageCache();
+	resetCacheMetrics();
 }
 /**
 * Create a debug label for showing render info.
@@ -234,135 +89,12 @@ function updateDebugLabel(label, renderWidth, renderHeight, resolutionScale) {
 	label.textContent = `Render: ${renderWidth}x${renderHeight} (${Math.round(resolutionScale * 100)}%)`;
 }
 /**
-* Common SVG foreignObject serialization pipeline.
-* Handles canvas encoding, serialization, and base64 encoding.
-* 
-* @param container - The HTML element to serialize
-* @param width - Output width
-* @param height - Output height
-* @param options - Serialization options
-* @returns Serialization result with data URI and restore function
-*/
-async function serializeToSvgDataUri(container, width, height, options = {}) {
-	const { canvasScale = 1, inlineImages: shouldInlineImages = false, logEarlyRenders = false } = options;
-	const canvasRestoreInfo = [];
-	const canvasStart = performance.now();
-	const encodedResults = await encodeCanvasesInParallel(Array.from(container.querySelectorAll("canvas")), canvasScale);
-	for (const { canvas, dataUrl } of encodedResults) try {
-		const img = document.createElement("img");
-		img.src = dataUrl;
-		img.width = canvas.width;
-		img.height = canvas.height;
-		const style = canvas.getAttribute("style");
-		if (style) img.setAttribute("style", style);
-		const parent = canvas.parentNode;
-		if (parent) {
-			const nextSibling = canvas.nextSibling;
-			parent.replaceChild(img, canvas);
-			canvasRestoreInfo.push({
-				canvas,
-				parent,
-				nextSibling,
-				img
-			});
-		}
-	} catch {}
-	defaultProfiler.addTime("canvasEncode", performance.now() - canvasStart);
-	if (shouldInlineImages) {
-		const inlineStart = performance.now();
-		await inlineImages(container);
-		defaultProfiler.addTime("inline", performance.now() - inlineStart);
-	}
-	const serializeStart = performance.now();
-	const wrapper = document.createElement("div");
-	wrapper.setAttribute("xmlns", "http://www.w3.org/1999/xhtml");
-	wrapper.setAttribute("style", `width:${width}px;height:${height}px;overflow:hidden;position:relative;`);
-	wrapper.appendChild(container);
-	if (!_xmlSerializer) _xmlSerializer = new XMLSerializer();
-	const serialized = _xmlSerializer.serializeToString(wrapper);
-	defaultProfiler.addTime("serialize", performance.now() - serializeStart);
-	const restore = () => {
-		const restoreStart = performance.now();
-		wrapper.removeChild(container);
-		for (const { canvas, parent, nextSibling, img } of canvasRestoreInfo) if (img.parentNode === parent) if (nextSibling) {
-			parent.insertBefore(canvas, nextSibling);
-			parent.removeChild(img);
-		} else parent.replaceChild(canvas, img);
-		defaultProfiler.addTime("restore", performance.now() - restoreStart);
-	};
-	if (logEarlyRenders && defaultProfiler.isEarlyRender(2)) console.log(`[serializeToSvgDataUri] FO serialized: ${serialized.length} chars`);
-	const base64Start = performance.now();
-	const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><foreignObject width="100%" height="100%">${serialized}</foreignObject></svg>`;
-	if (!_textEncoder) _textEncoder = new TextEncoder();
-	const utf8Bytes = _textEncoder.encode(svg);
-	let base64;
-	if (typeof Uint8Array.prototype.toBase64 === "function") base64 = utf8Bytes.toBase64();
-	else base64 = encodeBase64Fast(utf8Bytes);
-	const dataUri = `data:image/svg+xml;base64,${base64}`;
-	defaultProfiler.addTime("base64", performance.now() - base64Start);
-	return {
-		dataUri,
-		restore
-	};
-}
-/**
-* Inline all images in a container as base64 data URIs.
-* SVG foreignObject can't load external images due to security restrictions.
-* Uses an LRU-style cache with size limits to prevent memory leaks.
-*/
-async function inlineImages(container) {
-	const images = container.querySelectorAll("img");
-	for (const image of images) {
-		const src = image.getAttribute("src");
-		if (!src || src.startsWith("data:")) continue;
-		const cached = _inlineImageCache.get(src);
-		if (cached) {
-			image.setAttribute("src", cached);
-			continue;
-		}
-		try {
-			const dataUrl = await blobToDataURL(await (await fetch(src)).blob());
-			image.setAttribute("src", dataUrl);
-			if (_inlineImageCache.size >= MAX_INLINE_IMAGE_CACHE_SIZE) {
-				const firstKey = _inlineImageCache.keys().next().value;
-				if (firstKey) _inlineImageCache.delete(firstKey);
-			}
-			_inlineImageCache.set(src, dataUrl);
-		} catch (e) {
-			console.warn("Failed to inline image:", src, e);
-		}
-	}
-}
-/**
-* Convert a Blob to a data URL.
-*/
-function blobToDataURL(blob) {
-	return new Promise((resolve, reject) => {
-		const reader = new FileReader();
-		reader.onload = () => resolve(reader.result);
-		reader.onerror = reject;
-		reader.readAsDataURL(blob);
-	});
-}
-/**
 * Wait for next animation frame (allows browser to complete layout)
 */
 function waitForFrame() {
 	return new Promise((resolve) => requestAnimationFrame(() => resolve()));
 }
 /**
-* Wait for multiple animation frames to ensure all paints are flushed.
-* This is necessary because video frame decoding and canvas painting may
-* happen asynchronously even after seek() returns.
-*/
-function waitForPaintFlush() {
-	return new Promise((resolve) => {
-		requestAnimationFrame(() => {
-			requestAnimationFrame(() => resolve());
-		});
-	});
-}
-/**
 * Check if a canvas has any rendered content (not all transparent/uninitialized).
 * Returns true if there's ANY non-transparent pixel.
 */
@@ -433,157 +165,6 @@ async function waitForVideoContent(timegroup, timeMs, maxWaitMs) {
 	};
 }
 /**
-* Render HTML content to canvas using native HTML-in-Canvas API (drawElementImage).
-* This is much faster than the foreignObject approach and avoids canvas tainting.
-* 
-* Note: The native API renders at device pixel ratio, so we capture at DPR scale
-* and then downsample to logical pixels to match the foreignObject path's output.
-* 
-* @param container - The HTML element to render
-* @param width - Target width in logical pixels
-* @param height - Target height in logical pixels
-* @param options - Rendering options (skipWait for batch mode)
-* 
-* @see https://github.com/WICG/html-in-canvas
-*/
-async function renderToImageNative(container, width, height, options = {}) {
-	const t0 = performance.now();
-	const { waitForPaint = false, reuseCanvas, skipDprScaling = false } = options;
-	const dpr = skipDprScaling ? 1 : window.devicePixelRatio || 1;
-	let captureCanvas;
-	let shouldCleanup = false;
-	if (reuseCanvas) {
-		captureCanvas = reuseCanvas;
-		const dpr$1 = skipDprScaling ? 1 : window.devicePixelRatio || 1;
-		const targetWidth = Math.floor(width * dpr$1);
-		const targetHeight = Math.floor(height * dpr$1);
-		if (captureCanvas.width !== targetWidth) captureCanvas.width = targetWidth;
-		if (captureCanvas.height !== targetHeight) captureCanvas.height = targetHeight;
-		captureCanvas.style.width = `${width}px`;
-		captureCanvas.style.height = `${height}px`;
-		if (!captureCanvas.hasAttribute("layoutsubtree")) {
-			captureCanvas.setAttribute("layoutsubtree", "");
-			captureCanvas.layoutSubtree = true;
-		}
-		if (!captureCanvas.parentNode) document.body.appendChild(captureCanvas);
-		if (container.parentElement !== captureCanvas) captureCanvas.appendChild(container);
-		if (getComputedStyle(container).display === "none") container.style.display = "block";
-		captureCanvas.offsetHeight;
-		container.offsetHeight;
-		getComputedStyle(captureCanvas).opacity;
-		getComputedStyle(container).opacity;
-	} else {
-		captureCanvas = document.createElement("canvas");
-		captureCanvas.width = Math.floor(width * dpr);
-		captureCanvas.height = Math.floor(height * dpr);
-		captureCanvas.setAttribute("layoutsubtree", "");
-		captureCanvas.layoutSubtree = true;
-		captureCanvas.appendChild(container);
-		captureCanvas.style.cssText = `
-      position: fixed;
-      left: 0;
-      top: 0;
-      width: ${width}px;
-      height: ${height}px;
-      opacity: 0;
-      pointer-events: none;
-      z-index: -9999;
-    `;
-		document.body.appendChild(captureCanvas);
-		shouldCleanup = true;
-	}
-	const t1 = performance.now();
-	defaultProfiler.addTime("setup", t1 - t0);
-	try {
-		getComputedStyle(container).opacity;
-		if (reuseCanvas && captureCanvas.layoutSubtree && !_layoutInitializedCanvases.has(captureCanvas)) {
-			await waitForFrame();
-			_layoutInitializedCanvases.add(captureCanvas);
-			if (!captureCanvas.parentNode) return captureCanvas;
-		}
-		if (waitForPaint) {
-			await waitForPaintFlush();
-			if (!captureCanvas.parentNode) return captureCanvas;
-		}
-		captureCanvas.getContext("2d").drawElementImage(container, 0, 0);
-	} finally {
-		if (shouldCleanup && captureCanvas.parentNode) captureCanvas.parentNode.removeChild(captureCanvas);
-	}
-	const t2 = performance.now();
-	defaultProfiler.addTime("draw", t2 - t1);
-	if (dpr === 1) {
-		defaultProfiler.incrementRenderCount();
-		return captureCanvas;
-	}
-	const outputCanvas = document.createElement("canvas");
-	outputCanvas.width = width;
-	outputCanvas.height = height;
-	outputCanvas.getContext("2d").drawImage(captureCanvas, 0, 0, captureCanvas.width, captureCanvas.height, 0, 0, width, height);
-	const t3 = performance.now();
-	defaultProfiler.addTime("downsample", t3 - t2);
-	defaultProfiler.incrementRenderCount();
-	defaultProfiler.shouldLogByTime(PROFILING_LOG_INTERVAL_MS);
-	return outputCanvas;
-}
-/**
-* Render HTML content to an image (or canvas) for drawing.
-* 
-* Supports two rendering modes (configurable via previewSettings):
-* - "native": Chrome's experimental drawElementImage API (fastest when available)
-* - "foreignObject": SVG foreignObject serialization (fallback, works everywhere)
-* 
-* @param container - The HTML element to render
-* @param width - Target width in logical pixels
-* @param height - Target height in logical pixels
-* @param options - Rendering options
-* @returns HTMLCanvasElement when using native, HTMLImageElement when using foreignObject
-*/
-async function renderToImage(container, width, height, options) {
-	if (getEffectiveRenderMode() === "native") return renderToImageNative(container, width, height, options);
-	const originalCanvases = Array.from(container.querySelectorAll("canvas"));
-	const clone = container.cloneNode(true);
-	const clonedCanvases = clone.querySelectorAll("canvas");
-	const canvasScale = options?.canvasScale ?? 1;
-	const canvasStart = performance.now();
-	const encodedResults = await encodeCanvasesInParallel(originalCanvases, canvasScale);
-	for (let i = 0; i < originalCanvases.length; i++) {
-		const srcCanvas = originalCanvases[i];
-		const dstCanvas = clonedCanvases[i];
-		const encoded = encodedResults.find((r) => r.canvas === srcCanvas);
-		if (!srcCanvas || !dstCanvas || !encoded) continue;
-		try {
-			const img = document.createElement("img");
-			img.src = encoded.dataUrl;
-			img.width = srcCanvas.width;
-			img.height = srcCanvas.height;
-			const style = dstCanvas.getAttribute("style");
-			if (style) img.setAttribute("style", style);
-			dstCanvas.parentNode?.replaceChild(img, dstCanvas);
-		} catch {}
-	}
-	defaultProfiler.addTime("canvasEncode", performance.now() - canvasStart);
-	const inlineStart = performance.now();
-	await inlineImages(clone);
-	defaultProfiler.addTime("inline", performance.now() - inlineStart);
-	const { dataUri } = await serializeToSvgDataUri(clone, width, height);
-	return loadImageFromDataUri(dataUri);
-}
-/**
-* Load an image from a data URI. Returns a Promise that resolves when loaded.
-*/
-function loadImageFromDataUri(dataUri) {
-	const img = new Image();
-	const imageLoadStart = performance.now();
-	return new Promise((resolve, reject) => {
-		img.onload = () => {
-			defaultProfiler.addTime("imageLoad", performance.now() - imageLoadStart);
-			resolve(img);
-		};
-		img.onerror = reject;
-		img.src = dataUri;
-	});
-}
-/**
 * Captures a frame from an already-seeked render clone.
 * Used internally by captureBatch for efficiency (reuses one clone across all captures).
 * 
@@ -606,48 +187,58 @@ async function captureFromClone(renderClone, renderContainer, options = {}) {
 	const ctx = canvas.getContext("2d");
 	if (!ctx) throw new Error("Failed to get canvas 2d context");
 	const timeMs = renderClone.currentTimeMs;
+	await new FrameController(renderClone).renderFrame(timeMs, { waitForLitUpdate: false });
 	if (contentReadyMode === "blocking") {
 		const result = await waitForVideoContent(renderClone, timeMs, blockingTimeoutMs);
 		if (!result.ready) throw new ContentNotReadyError(timeMs, blockingTimeoutMs, result.blankVideos);
 	}
-	let image;
-	if (getEffectiveRenderMode() === "native") {
-		renderContainer.style.cssText = `
-      position: fixed;
-      left: 0;
-      top: 0;
-      width: ${width}px;
-      height: ${height}px;
-      pointer-events: none;
-      overflow: hidden;
-    `;
-		image = await renderToImageNative(renderContainer, width, height, { skipDprScaling: scale < 1 });
-	} else {
-		const t0 = performance.now();
-		const { container, syncState } = buildCloneStructure(renderClone, timeMs);
-		const buildTime = performance.now() - t0;
-		const bgSource = originalTimegroup ?? renderClone;
-		const previewContainer = createPreviewContainer({
-			width,
-			height,
-			background: getComputedStyle(bgSource).background || "#000"
-		});
-		const t1 = performance.now();
-		const styleEl = document.createElement("style");
-		styleEl.textContent = collectDocumentStyles();
-		const stylesTime = performance.now() - t1;
-		previewContainer.appendChild(styleEl);
-		previewContainer.appendChild(container);
-		overrideRootCloneStyles(syncState, true);
-		const t2 = performance.now();
-		image = await renderToImage(previewContainer, width, height, { canvasScale: scale });
-		const renderTime = performance.now() - t2;
-		console.log(`[captureFromClone] build=${buildTime.toFixed(0)}ms, styles=${stylesTime.toFixed(0)}ms, render=${renderTime.toFixed(0)}ms (canvasScale=${scale})`);
+	const renderContext = new RenderContext();
+	try {
+		let image;
+		if (getEffectiveRenderMode() === "native") {
+			renderContainer.style.cssText = `
+        position: fixed;
+        left: 0;
+        top: 0;
+        width: ${width}px;
+        height: ${height}px;
+        pointer-events: none;
+        overflow: hidden;
+      `;
+			image = await renderToImageNative(renderContainer, width, height, { skipDprScaling: true });
+		} else {
+			const t0 = performance.now();
+			const { container, syncState } = buildCloneStructure(renderClone, timeMs);
+			const buildTime = performance.now() - t0;
+			const bgSource = originalTimegroup ?? renderClone;
+			const previewContainer = createPreviewContainer({
+				width,
+				height,
+				background: getComputedStyle(bgSource).background || "#000"
+			});
+			const t1 = performance.now();
+			const styleEl = document.createElement("style");
+			styleEl.textContent = collectDocumentStyles();
+			const stylesTime = performance.now() - t1;
+			previewContainer.appendChild(styleEl);
+			previewContainer.appendChild(container);
+			overrideRootCloneStyles(syncState, true);
+			const t2 = performance.now();
+			image = await renderToImage(previewContainer, width, height, {
+				canvasScale: scale,
+				renderContext,
+				sourceMap: syncState.canvasSourceMap
+			});
+			const renderTime = performance.now() - t2;
+			logger.debug(`[captureFromClone] build=${buildTime.toFixed(0)}ms, styles=${stylesTime.toFixed(0)}ms, render=${renderTime.toFixed(0)}ms (canvasScale=${scale})`);
+		}
+		const srcWidth = image.width;
+		const srcHeight = image.height;
+		ctx.drawImage(image, 0, 0, srcWidth, srcHeight, 0, 0, canvas.width, canvas.height);
+		return canvas;
+	} finally {
+		renderContext.dispose();
 	}
-	const srcWidth = image.width;
-	const srcHeight = image.height;
-	ctx.drawImage(image, 0, 0, srcWidth, srcHeight, 0, 0, canvas.width, canvas.height);
-	return canvas;
 }
 /**
 * Captures a single frame from a timegroup at a specific time.
@@ -745,6 +336,9 @@ function renderTimegroupToCanvas(timegroup, scaleOrOptions = DEFAULT_PREVIEW_SCA
 	overrideRootCloneStyles(syncState);
 	let rendering = false;
 	let lastTimeMs = -1;
+	let disposed = false;
+	const renderContext = new RenderContext();
+	const frameController = new FrameController(timegroup);
 	let hasLoggedScale = false;
 	let pendingResolutionScale = null;
 	/**
@@ -779,7 +373,7 @@ function renderTimegroupToCanvas(timegroup, scaleOrOptions = DEFAULT_PREVIEW_SCA
 	};
 	const getResolutionScale = () => pendingResolutionScale ?? currentResolutionScale;
 	const refresh = async () => {
-		if (rendering) return;
+		if (rendering || disposed) return;
 		const sourceTimeMs = timegroup.currentTimeMs ?? 0;
 		const userTimeMs = timegroup.userTimeMs ?? 0;
 		if (Math.abs(sourceTimeMs - userTimeMs) > TIME_EPSILON_MS) return;
@@ -790,14 +384,21 @@ function renderTimegroupToCanvas(timegroup, scaleOrOptions = DEFAULT_PREVIEW_SCA
 		if (!hasLoggedScale) {
 			hasLoggedScale = true;
 			const mode = getEffectiveRenderMode();
-			console.log(`[renderTimegroupToCanvas] Resolution scale: ${currentResolutionScale} (${width}x${height} → ${renderWidth}x${renderHeight}), canvas buffer: ${canvas.width}x${canvas.height}, CSS size: ${canvas.style.width}x${canvas.style.height}, renderMode: ${mode}`);
+			logger.debug(`[renderTimegroupToCanvas] Resolution scale: ${currentResolutionScale} (${width}x${height} → ${renderWidth}x${renderHeight}), canvas buffer: ${canvas.width}x${canvas.height}, CSS size: ${canvas.style.width}x${canvas.style.height}, renderMode: ${mode}`);
 		}
 		try {
+			await frameController.renderFrame(userTimeMs);
 			syncStyles(syncState, toAbsoluteTime(timegroup, userTimeMs));
 			overrideRootCloneStyles(syncState);
+			const removedNodes = removeHiddenNodesForSerialization(syncState);
 			const t0 = performance.now();
-			const image = await renderToImage(previewContainer, renderWidth, renderHeight, { canvasScale: currentResolutionScale });
+			const image = await renderToImage(previewContainer, renderWidth, renderHeight, {
+				canvasScale: currentResolutionScale,
+				renderContext,
+				sourceMap: syncState.canvasSourceMap
+			});
 			const renderTime = performance.now() - t0;
+			restoreHiddenNodes(removedNodes);
 			const targetWidth = Math.floor(renderWidth * scale * dpr);
 			const targetHeight = Math.floor(renderHeight * scale * dpr);
 			if (canvas.width !== targetWidth || canvas.height !== targetHeight) {
@@ -809,14 +410,23 @@ function renderTimegroupToCanvas(timegroup, scaleOrOptions = DEFAULT_PREVIEW_SCA
 			ctx.drawImage(image, 0, 0);
 			ctx.restore();
 			defaultProfiler.incrementRenderCount();
-			if (defaultProfiler.shouldLogByFrameCount(60)) console.log(`[renderTimegroupToCanvas] Frame render: ${renderTime.toFixed(1)}ms (resolutionScale=${currentResolutionScale}, image=${image.width}x${image.height})`);
+			if (defaultProfiler.shouldLogByFrameCount(60)) logger.debug(`[renderTimegroupToCanvas] Frame render: ${renderTime.toFixed(1)}ms (resolutionScale=${currentResolutionScale}, image=${image.width}x${image.height})`);
 			updateDebugLabel(debugLabel, renderWidth, renderHeight, currentResolutionScale);
 		} catch (e) {
-			console.error("Canvas preview render failed:", e);
+			logger.error("Canvas preview render failed:", e);
 		} finally {
 			rendering = false;
 		}
 	};
+	/**
+	* Dispose the preview and release resources.
+	*/
+	const dispose = () => {
+		if (disposed) return;
+		disposed = true;
+		frameController.abort();
+		renderContext.dispose();
+	};
 	refresh();
 	return {
 		container: wrapperContainer,
@@ -824,7 +434,8 @@ function renderTimegroupToCanvas(timegroup, scaleOrOptions = DEFAULT_PREVIEW_SCA
 		refresh,
 		syncState,
 		setResolutionScale,
-		getResolutionScale
+		getResolutionScale,
+		dispose
 	};
 }