@editframe/elements 0.30.2-beta.0 → 0.31.0-beta.1

package/dist/preview/renderTimegroupToCanvas.js

@@ -0,0 +1,833 @@
+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 { getEffectiveRenderMode } from "./renderers.js";
+import { WorkerPool, encodeCanvasInWorker } from "./workers/WorkerPool.js";
+import { getEncoderWorkerUrl } from "./workers/encoderWorkerInline.js";
+import { defaultProfiler } from "./RenderProfiler.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.
+*/
+var ContentNotReadyError = class extends Error {
+	constructor(timeMs, timeoutMs, blankVideos) {
+		super(`Video content not ready at ${timeMs}ms after ${timeoutMs}ms timeout. Blank videos: ${blankVideos.join(", ")}`);
+		this.timeMs = timeMs;
+		this.timeoutMs = timeoutMs;
+		this.blankVideos = blankVideos;
+		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.
+*/
+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;
+	}
+}
+/**
+* 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.
+*/
+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;
+}
+/**
+* Reset all module state including profiling counters, caches, and logging flags.
+* Call at the start of export sessions to ensure clean state.
+*/
+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;
+}
+/**
+* Create a debug label for showing render info.
+*/
+function createDebugLabel() {
+	const debugLabel = document.createElement("div");
+	debugLabel.style.cssText = `
+    position: absolute;
+    top: -24px;
+    left: 0;
+    padding: 2px 8px;
+    font: bold 12px monospace;
+    background: rgba(0, 0, 0, 0.8);
+    border-radius: 3px;
+    white-space: nowrap;
+    z-index: 1000;
+    pointer-events: none;
+  `;
+	return debugLabel;
+}
+/**
+* Update debug label with resolution info.
+*/
+function updateDebugLabel(label, renderWidth, renderHeight, resolutionScale) {
+	const scaleColors = {
+		1: "#00ff00",
+		.75: "#ffff00",
+		.5: "#ff8800",
+		.25: "#ff0000"
+	};
+	label.style.color = scaleColors[resolutionScale] || "#ffffff";
+	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.
+*/
+function canvasHasContent(canvas) {
+	const ctx = canvas.getContext("2d");
+	if (!ctx) return false;
+	try {
+		const width = canvas.width;
+		const height = canvas.height;
+		if (width === 0 || height === 0) return false;
+		const stripY = Math.floor(height / 2);
+		const data = ctx.getImageData(0, stripY, width, CANVAS_SAMPLE_STRIP_HEIGHT).data;
+		for (let i = 3; i < data.length; i += 4) if (data[i] !== 0) return true;
+		return false;
+	} catch {
+		return true;
+	}
+}
+/**
+* Wait for video canvases within a timegroup to have content.
+* Only checks videos that should be visible at the current time.
+* Returns result with ready status and list of blank video names.
+*/
+async function waitForVideoContent(timegroup, timeMs, maxWaitMs) {
+	const startTime = performance.now();
+	const allVideos = timegroup.querySelectorAll("ef-video");
+	if (allVideos.length === 0) return {
+		ready: true,
+		blankVideos: []
+	};
+	const visibleVideos = Array.from(allVideos).filter((video) => {
+		if (!isVisibleAtTime(video, timeMs)) return false;
+		let parent = video.parentElement;
+		while (parent && parent !== timegroup) {
+			if (parent.tagName === "EF-TIMEGROUP" && !isVisibleAtTime(parent, timeMs)) return false;
+			parent = parent.parentElement;
+		}
+		return true;
+	});
+	if (visibleVideos.length === 0) return {
+		ready: true,
+		blankVideos: []
+	};
+	const getBlankVideoNames = () => visibleVideos.filter((video) => {
+		const shadowCanvas = video.shadowRoot?.querySelector("canvas");
+		return shadowCanvas && !canvasHasContent(shadowCanvas);
+	}).map((v) => v.src || v.id || "unnamed");
+	while (performance.now() - startTime < maxWaitMs) {
+		let allHaveContent = true;
+		for (const video of visibleVideos) {
+			const shadowCanvas = video.shadowRoot?.querySelector("canvas");
+			if (shadowCanvas && shadowCanvas.width > 0 && shadowCanvas.height > 0) {
+				if (!canvasHasContent(shadowCanvas)) {
+					allHaveContent = false;
+					break;
+				}
+			}
+		}
+		if (allHaveContent) return {
+			ready: true,
+			blankVideos: []
+		};
+		await waitForFrame();
+	}
+	return {
+		ready: false,
+		blankVideos: getBlankVideoNames()
+	};
+}
+/**
+* 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).
+* 
+* @param renderClone - A render clone that has already been seeked to the target time
+* @param renderContainer - The container holding the render clone (from createRenderClone)
+* @param options - Capture options
+* @returns Canvas with the rendered frame
+*/
+async function captureFromClone(renderClone, renderContainer, options = {}) {
+	const { scale = DEFAULT_THUMBNAIL_SCALE, contentReadyMode = "immediate", blockingTimeoutMs = DEFAULT_BLOCKING_TIMEOUT_MS, originalTimegroup } = options;
+	const sourceForDimensions = originalTimegroup ?? renderClone;
+	const width = sourceForDimensions.offsetWidth || DEFAULT_WIDTH;
+	const height = sourceForDimensions.offsetHeight || DEFAULT_HEIGHT;
+	const dpr = window.devicePixelRatio || 1;
+	const canvas = document.createElement("canvas");
+	canvas.width = Math.floor(width * scale * dpr);
+	canvas.height = Math.floor(height * scale * dpr);
+	canvas.style.width = `${Math.floor(width * scale)}px`;
+	canvas.style.height = `${Math.floor(height * scale)}px`;
+	const ctx = canvas.getContext("2d");
+	if (!ctx) throw new Error("Failed to get canvas 2d context");
+	const timeMs = renderClone.currentTimeMs;
+	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 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.
+* 
+* CLONE-TIMELINE ARCHITECTURE:
+* Creates an independent render clone, seeks it to the target time, and captures.
+* Prime-timeline is NEVER seeked - user can continue previewing/editing during capture.
+* 
+* @param timegroup - The source timegroup
+* @param options - Capture options including timeMs, scale, contentReadyMode
+* @returns Canvas with the rendered frame
+* @throws ContentNotReadyError if blocking mode times out waiting for video content
+*/
+async function captureTimegroupAtTime(timegroup, options) {
+	const { timeMs, scale = DEFAULT_THUMBNAIL_SCALE, contentReadyMode = "immediate", blockingTimeoutMs = DEFAULT_BLOCKING_TIMEOUT_MS } = options;
+	const { clone: renderClone, container: renderContainer, cleanup: cleanupRenderClone } = await timegroup.createRenderClone();
+	try {
+		await renderClone.seekForRender(timeMs);
+		return await captureFromClone(renderClone, renderContainer, {
+			scale,
+			contentReadyMode,
+			blockingTimeoutMs,
+			originalTimegroup: timegroup
+		});
+	} finally {
+		cleanupRenderClone();
+	}
+}
+/** Epsilon for comparing time values (ms) - times within this are considered equal */
+const TIME_EPSILON_MS = 1;
+/** Default scale for preview rendering */
+const DEFAULT_PREVIEW_SCALE = 1;
+/** Default resolution scale (full resolution) */
+const DEFAULT_RESOLUTION_SCALE = 1;
+/**
+* Convert relative time to absolute time for a timegroup.
+* Nested timegroup children have ABSOLUTE startTimeMs values,
+* so relative capture times must be converted for temporal culling.
+*/
+function toAbsoluteTime(timegroup, relativeTimeMs) {
+	return relativeTimeMs + (timegroup.startTimeMs ?? 0);
+}
+/**
+* Renders a timegroup preview to a canvas using SVG foreignObject.
+* 
+* Optimized with:
+* - Persistent clone structure (built once)
+* - Temporal bucketing for time-based culling
+* - Property split (static vs animated)
+* - Parent index for O(1) visibility checks
+* - Resolution scaling for performance (renders at lower resolution, CSS upscales)
+*
+* @param timegroup - The source timegroup to preview
+* @param scaleOrOptions - Scale factor (default 1) or options object
+* @returns Object with canvas and refresh function
+*/
+function renderTimegroupToCanvas(timegroup, scaleOrOptions = DEFAULT_PREVIEW_SCALE) {
+	const options = typeof scaleOrOptions === "number" ? { scale: scaleOrOptions } : scaleOrOptions;
+	const scale = options.scale ?? DEFAULT_PREVIEW_SCALE;
+	let currentResolutionScale = options.resolutionScale ?? DEFAULT_RESOLUTION_SCALE;
+	const width = timegroup.offsetWidth || DEFAULT_WIDTH;
+	const height = timegroup.offsetHeight || DEFAULT_HEIGHT;
+	const dpr = window.devicePixelRatio || 1;
+	let renderWidth = Math.floor(width * currentResolutionScale);
+	let renderHeight = Math.floor(height * currentResolutionScale);
+	const canvas = createDprCanvas({
+		renderWidth,
+		renderHeight,
+		scale,
+		fullWidth: width,
+		fullHeight: height,
+		dpr
+	});
+	const wrapperContainer = document.createElement("div");
+	wrapperContainer.style.cssText = "position: relative; display: inline-block;";
+	const debugLabel = createDebugLabel();
+	wrapperContainer.appendChild(debugLabel);
+	wrapperContainer.appendChild(canvas);
+	const ctx = canvas.getContext("2d");
+	if (!ctx) throw new Error("Failed to get canvas 2d context");
+	const { container, syncState } = buildCloneStructure(timegroup, toAbsoluteTime(timegroup, timegroup.currentTimeMs ?? 0));
+	const previewContainer = createPreviewContainer({
+		width: renderWidth,
+		height: renderHeight,
+		background: getComputedStyle(timegroup).background || "#000"
+	});
+	if (currentResolutionScale < 1) {
+		container.style.transform = `scale(${currentResolutionScale})`;
+		container.style.transformOrigin = "top left";
+	}
+	const styleEl = document.createElement("style");
+	styleEl.textContent = collectDocumentStyles();
+	previewContainer.appendChild(styleEl);
+	previewContainer.appendChild(container);
+	overrideRootCloneStyles(syncState);
+	let rendering = false;
+	let lastTimeMs = -1;
+	let hasLoggedScale = false;
+	let pendingResolutionScale = null;
+	/**
+	* Apply pending resolution scale changes.
+	* Called at the start of refresh() before rendering, so the old content
+	* stays visible until new content is ready to be drawn.
+	*/
+	const applyPendingResolutionChange = () => {
+		if (pendingResolutionScale === null) return;
+		const newScale = pendingResolutionScale;
+		pendingResolutionScale = null;
+		currentResolutionScale = newScale;
+		renderWidth = Math.floor(width * currentResolutionScale);
+		renderHeight = Math.floor(height * currentResolutionScale);
+		previewContainer.style.width = `${renderWidth}px`;
+		previewContainer.style.height = `${renderHeight}px`;
+		if (currentResolutionScale < 1) {
+			container.style.transform = `scale(${currentResolutionScale})`;
+			container.style.transformOrigin = "top left";
+		} else container.style.transform = "";
+	};
+	/**
+	* Dynamically change resolution scale without rebuilding clone structure.
+	* The actual change is deferred until next refresh() to avoid blanking -
+	* old content stays visible until new content is ready.
+	*/
+	const setResolutionScale = (newScale) => {
+		newScale = Math.max(.1, Math.min(1, newScale));
+		if (newScale === currentResolutionScale && pendingResolutionScale === null) return;
+		pendingResolutionScale = newScale;
+		lastTimeMs = -1;
+	};
+	const getResolutionScale = () => pendingResolutionScale ?? currentResolutionScale;
+	const refresh = async () => {
+		if (rendering) return;
+		const sourceTimeMs = timegroup.currentTimeMs ?? 0;
+		const userTimeMs = timegroup.userTimeMs ?? 0;
+		if (Math.abs(sourceTimeMs - userTimeMs) > TIME_EPSILON_MS) return;
+		if (userTimeMs === lastTimeMs) return;
+		lastTimeMs = userTimeMs;
+		rendering = true;
+		applyPendingResolutionChange();
+		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}`);
+		}
+		try {
+			syncStyles(syncState, toAbsoluteTime(timegroup, userTimeMs));
+			overrideRootCloneStyles(syncState);
+			const t0 = performance.now();
+			const image = await renderToImage(previewContainer, renderWidth, renderHeight, { canvasScale: currentResolutionScale });
+			const renderTime = performance.now() - t0;
+			const targetWidth = Math.floor(renderWidth * scale * dpr);
+			const targetHeight = Math.floor(renderHeight * scale * dpr);
+			if (canvas.width !== targetWidth || canvas.height !== targetHeight) {
+				canvas.width = targetWidth;
+				canvas.height = targetHeight;
+			} else ctx.clearRect(0, 0, canvas.width, canvas.height);
+			ctx.save();
+			ctx.scale(dpr * scale, dpr * scale);
+			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})`);
+			updateDebugLabel(debugLabel, renderWidth, renderHeight, currentResolutionScale);
+		} catch (e) {
+			console.error("Canvas preview render failed:", e);
+		} finally {
+			rendering = false;
+		}
+	};
+	refresh();
+	return {
+		container: wrapperContainer,
+		canvas,
+		refresh,
+		syncState,
+		setResolutionScale,
+		getResolutionScale
+	};
+}
+
+//#endregion
+export { captureFromClone, captureTimegroupAtTime, renderTimegroupToCanvas, resetRenderState };
+//# sourceMappingURL=renderTimegroupToCanvas.js.map