@editframe/elements 0.37.3-beta → 0.38.1

package/dist/preview/QualityUpgradeScheduler.d.ts

@@ -0,0 +1,76 @@
+//#region src/preview/QualityUpgradeScheduler.d.ts
+/**
+ * QualityUpgradeScheduler: Centralized deadline-ordered work queue
+ *
+ * Coordinates main-quality segment fetching across multiple video elements.
+ * Generic scheduler that doesn't understand media concepts (segments, renditions, etc.)
+ * - only processes { key, deadlineMs, fetch, owner } tuples.
+ *
+ * Design principles:
+ * - Deadline-based ordering: always process nearest deadline first
+ * - Ground-truth cache validation: check cache before starting any fetch
+ * - In-flight fetches never cancelled: they populate shared cache
+ * - Event-driven: elements submit tasks only on state changes, not every frame
+ */
+interface UpgradeTask {
+  /** Opaque dedup key (e.g. "${owner}:${segmentId}:${renditionId}") */
+  key: string;
+  /** Fetch function that populates the cache */
+  fetch: (signal: AbortSignal) => Promise<void>;
+  /** Timeline time when this segment will be needed */
+  deadlineMs: number;
+  /** Element ID, for bulk operations */
+  owner: string;
+}
+interface UpgradeTaskStatus {
+  key: string;
+  owner: string;
+  deadlineMs: number;
+  status: "queued" | "active" | "completed" | "failed";
+  error?: string;
+}
+interface OwnerProgress {
+  queued: number;
+  active: number;
+  completed: number;
+  failed: number;
+}
+declare class QualityUpgradeScheduler {
+  #private;
+  constructor(options: {
+    requestFrameRender: () => void;
+    maxConcurrent?: number;
+    isCached?: (key: string) => boolean;
+  });
+  /**
+   * Add tasks without affecting existing ones (additive).
+   * Used for lookahead extension during playback.
+   */
+  enqueue(tasks: UpgradeTask[]): void;
+  /**
+   * Replace all queued tasks for an owner.
+   * Used on seeks, trim changes, timeline position changes where old deadlines are stale.
+   * Does NOT cancel in-flight tasks (they populate shared cache).
+   */
+  replaceForOwner(owner: string, tasks: UpgradeTask[]): void;
+  /**
+   * Cancel all tasks for an owner.
+   * Removes queued tasks. Does NOT abort in-flight fetches.
+   */
+  cancelForOwner(owner: string): void;
+  /**
+   * Get snapshot of current queue state for debugging.
+   */
+  getQueueSnapshot(): UpgradeTaskStatus[];
+  /**
+   * Get progress for a specific owner.
+   */
+  getOwnerProgress(owner: string): OwnerProgress;
+  /**
+   * Dispose the scheduler - abort all in-flight work.
+   */
+  dispose(): void;
+}
+//#endregion
+export { QualityUpgradeScheduler };
+//# sourceMappingURL=QualityUpgradeScheduler.d.ts.map

package/dist/preview/QualityUpgradeScheduler.js

@@ -0,0 +1,158 @@
+//#region src/preview/QualityUpgradeScheduler.ts
+var QualityUpgradeScheduler = class {
+	#maxConcurrent;
+	#queue = [];
+	#activeTasks = /* @__PURE__ */ new Map();
+	#completedTasks = /* @__PURE__ */ new Map();
+	#abortController;
+	#requestFrameRender;
+	#isCached;
+	constructor(options) {
+		this.#requestFrameRender = options.requestFrameRender;
+		this.#maxConcurrent = options.maxConcurrent ?? 4;
+		this.#isCached = options.isCached;
+		this.#abortController = new AbortController();
+	}
+	/**
+	* Add tasks without affecting existing ones (additive).
+	* Used for lookahead extension during playback.
+	*/
+	enqueue(tasks) {
+		if (this.#abortController.signal.aborted) return;
+		for (const task of tasks) {
+			if (this.#queue.some((t) => t.key === task.key) || this.#activeTasks.has(task.key) || this.#completedTasks.has(task.key)) continue;
+			this.#queue.push(task);
+		}
+		this.#queue.sort((a, b) => a.deadlineMs - b.deadlineMs);
+		this.#processQueue();
+	}
+	/**
+	* Replace all queued tasks for an owner.
+	* Used on seeks, trim changes, timeline position changes where old deadlines are stale.
+	* Does NOT cancel in-flight tasks (they populate shared cache).
+	*/
+	replaceForOwner(owner, tasks) {
+		if (this.#abortController.signal.aborted) return;
+		this.#queue = this.#queue.filter((t) => t.owner !== owner);
+		for (const task of tasks) {
+			if (this.#activeTasks.has(task.key) || this.#completedTasks.has(task.key)) continue;
+			this.#queue.push(task);
+		}
+		this.#queue.sort((a, b) => a.deadlineMs - b.deadlineMs);
+		this.#processQueue();
+	}
+	/**
+	* Cancel all tasks for an owner.
+	* Removes queued tasks. Does NOT abort in-flight fetches.
+	*/
+	cancelForOwner(owner) {
+		this.#queue = this.#queue.filter((t) => t.owner !== owner);
+		for (const [key, task] of this.#completedTasks.entries()) if (task.owner === owner) this.#completedTasks.delete(key);
+	}
+	/**
+	* Process the queue - start tasks up to maxConcurrent limit.
+	*/
+	#processQueue() {
+		if (this.#abortController.signal.aborted) return;
+		while (this.#activeTasks.size < this.#maxConcurrent && this.#queue.length > 0) {
+			const task = this.#queue.shift();
+			if (!task) break;
+			if (this.#isCached?.(task.key)) {
+				this.#completedTasks.set(task.key, {
+					key: task.key,
+					owner: task.owner,
+					status: "completed"
+				});
+				continue;
+			}
+			this.#startTask(task);
+		}
+	}
+	/**
+	* Start a single task.
+	*/
+	#startTask(task) {
+		const promise = task.fetch(this.#abortController.signal).then(() => {
+			this.#activeTasks.delete(task.key);
+			this.#completedTasks.set(task.key, {
+				key: task.key,
+				owner: task.owner,
+				status: "completed"
+			});
+			this.#requestFrameRender();
+			this.#processQueue();
+		}).catch((error) => {
+			this.#activeTasks.delete(task.key);
+			if (!(error instanceof DOMException && error.name === "AbortError")) this.#completedTasks.set(task.key, {
+				key: task.key,
+				owner: task.owner,
+				status: "failed",
+				error: error instanceof Error ? error.message : String(error)
+			});
+			this.#processQueue();
+		});
+		this.#activeTasks.set(task.key, {
+			task,
+			startedAt: performance.now(),
+			promise
+		});
+	}
+	/**
+	* Get snapshot of current queue state for debugging.
+	*/
+	getQueueSnapshot() {
+		const results = [];
+		for (const task of this.#queue) results.push({
+			key: task.key,
+			owner: task.owner,
+			deadlineMs: task.deadlineMs,
+			status: "queued"
+		});
+		for (const [key, activeTask] of this.#activeTasks.entries()) results.push({
+			key,
+			owner: activeTask.task.owner,
+			deadlineMs: activeTask.task.deadlineMs,
+			status: "active"
+		});
+		for (const [key, completed] of this.#completedTasks.entries()) results.push({
+			key,
+			owner: completed.owner,
+			deadlineMs: 0,
+			status: completed.status,
+			error: completed.error
+		});
+		return results;
+	}
+	/**
+	* Get progress for a specific owner.
+	*/
+	getOwnerProgress(owner) {
+		const queued = this.#queue.filter((t) => t.owner === owner).length;
+		let active = 0;
+		for (const activeTask of this.#activeTasks.values()) if (activeTask.task.owner === owner) active++;
+		let completed = 0;
+		let failed = 0;
+		for (const task of this.#completedTasks.values()) if (task.owner === owner) if (task.status === "completed") completed++;
+		else failed++;
+		return {
+			queued,
+			active,
+			completed,
+			failed
+		};
+	}
+	/**
+	* Dispose the scheduler - abort all in-flight work.
+	*/
+	dispose() {
+		for (const activeTask of this.#activeTasks.values()) activeTask.promise.catch(() => {});
+		this.#abortController.abort();
+		this.#queue = [];
+		this.#activeTasks.clear();
+		this.#completedTasks.clear();
+	}
+};
+
+//#endregion
+export { QualityUpgradeScheduler };
+//# sourceMappingURL=QualityUpgradeScheduler.js.map

package/dist/preview/QualityUpgradeScheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QualityUpgradeScheduler.js","names":["#requestFrameRender","#maxConcurrent","#isCached","#abortController","#queue","#activeTasks","#completedTasks","#processQueue","#startTask","results: UpgradeTaskStatus[]"],"sources":["../../src/preview/QualityUpgradeScheduler.ts"],"sourcesContent":["/**\n * QualityUpgradeScheduler: Centralized deadline-ordered work queue\n *\n * Coordinates main-quality segment fetching across multiple video elements.\n * Generic scheduler that doesn't understand media concepts (segments, renditions, etc.)\n * - only processes { key, deadlineMs, fetch, owner } tuples.\n *\n * Design principles:\n * - Deadline-based ordering: always process nearest deadline first\n * - Ground-truth cache validation: check cache before starting any fetch\n * - In-flight fetches never cancelled: they populate shared cache\n * - Event-driven: elements submit tasks only on state changes, not every frame\n */\n\nexport interface UpgradeTask {\n  /** Opaque dedup key (e.g. \"${owner}:${segmentId}:${renditionId}\") */\n  key: string;\n  /** Fetch function that populates the cache */\n  fetch: (signal: AbortSignal) => Promise<void>;\n  /** Timeline time when this segment will be needed */\n  deadlineMs: number;\n  /** Element ID, for bulk operations */\n  owner: string;\n}\n\nexport interface UpgradeTaskStatus {\n  key: string;\n  owner: string;\n  deadlineMs: number;\n  status: \"queued\" | \"active\" | \"completed\" | \"failed\";\n  error?: string;\n}\n\nexport interface OwnerProgress {\n  queued: number;\n  active: number;\n  completed: number;\n  failed: number;\n}\n\ninterface ActiveTask {\n  task: UpgradeTask;\n  startedAt: number;\n  promise: Promise<void>;\n}\n\ninterface CompletedTask {\n  key: string;\n  owner: string;\n  status: \"completed\" | \"failed\";\n  error?: string;\n}\n\nexport class QualityUpgradeScheduler {\n  #maxConcurrent: number;\n  #queue: UpgradeTask[] = [];\n  #activeTasks = new Map<string, ActiveTask>();\n  #completedTasks = new Map<string, CompletedTask>();\n  #abortController: AbortController;\n  #requestFrameRender: () => void;\n  #isCached?: (key: string) => boolean;\n\n  constructor(options: {\n    requestFrameRender: () => void;\n    maxConcurrent?: number;\n    isCached?: (key: string) => boolean;\n  }) {\n    this.#requestFrameRender = options.requestFrameRender;\n    this.#maxConcurrent = options.maxConcurrent ?? 4;\n    this.#isCached = options.isCached;\n    this.#abortController = new AbortController();\n  }\n\n  /**\n   * Add tasks without affecting existing ones (additive).\n   * Used for lookahead extension during playback.\n   */\n  enqueue(tasks: UpgradeTask[]): void {\n    if (this.#abortController.signal.aborted) return;\n\n    for (const task of tasks) {\n      // Skip if already queued, active, or completed\n      if (\n        this.#queue.some((t) => t.key === task.key) ||\n        this.#activeTasks.has(task.key) ||\n        this.#completedTasks.has(task.key)\n      ) {\n        continue;\n      }\n\n      this.#queue.push(task);\n    }\n\n    // Sort queue by deadline (ascending)\n    this.#queue.sort((a, b) => a.deadlineMs - b.deadlineMs);\n\n    // Start processing if we have capacity\n    this.#processQueue();\n  }\n\n  /**\n   * Replace all queued tasks for an owner.\n   * Used on seeks, trim changes, timeline position changes where old deadlines are stale.\n   * Does NOT cancel in-flight tasks (they populate shared cache).\n   */\n  replaceForOwner(owner: string, tasks: UpgradeTask[]): void {\n    if (this.#abortController.signal.aborted) return;\n\n    // Remove queued (not active) tasks for this owner\n    this.#queue = this.#queue.filter((t) => t.owner !== owner);\n\n    // Add new tasks\n    for (const task of tasks) {\n      // Skip if already active or completed\n      if (\n        this.#activeTasks.has(task.key) ||\n        this.#completedTasks.has(task.key)\n      ) {\n        continue;\n      }\n\n      this.#queue.push(task);\n    }\n\n    // Sort queue by deadline (ascending)\n    this.#queue.sort((a, b) => a.deadlineMs - b.deadlineMs);\n\n    // Start processing if we have capacity\n    this.#processQueue();\n  }\n\n  /**\n   * Cancel all tasks for an owner.\n   * Removes queued tasks. Does NOT abort in-flight fetches.\n   */\n  cancelForOwner(owner: string): void {\n    // Remove from queue\n    this.#queue = this.#queue.filter((t) => t.owner !== owner);\n\n    // Remove from completed tracking (allows resubmission)\n    for (const [key, task] of this.#completedTasks.entries()) {\n      if (task.owner === owner) {\n        this.#completedTasks.delete(key);\n      }\n    }\n\n    // Note: we do NOT cancel active tasks - they populate the shared cache\n  }\n\n  /**\n   * Process the queue - start tasks up to maxConcurrent limit.\n   */\n  #processQueue(): void {\n    if (this.#abortController.signal.aborted) return;\n\n    while (\n      this.#activeTasks.size < this.#maxConcurrent &&\n      this.#queue.length > 0\n    ) {\n      const task = this.#queue.shift();\n      if (!task) break;\n\n      // Ground-truth cache check before starting\n      if (this.#isCached?.(task.key)) {\n        // Already cached from another path, mark as completed and continue\n        this.#completedTasks.set(task.key, {\n          key: task.key,\n          owner: task.owner,\n          status: \"completed\",\n        });\n        continue;\n      }\n\n      // Start the task\n      this.#startTask(task);\n    }\n  }\n\n  /**\n   * Start a single task.\n   */\n  #startTask(task: UpgradeTask): void {\n    const promise = task\n      .fetch(this.#abortController.signal)\n      .then(() => {\n        // Success\n        this.#activeTasks.delete(task.key);\n        this.#completedTasks.set(task.key, {\n          key: task.key,\n          owner: task.owner,\n          status: \"completed\",\n        });\n\n        // Trigger re-render so upgraded quality gets displayed\n        this.#requestFrameRender();\n\n        // Start next task if available\n        this.#processQueue();\n      })\n      .catch((error) => {\n        // Failure\n        this.#activeTasks.delete(task.key);\n\n        // Don't track AbortError as failure (intentional cancellation)\n        const isAbortError =\n          error instanceof DOMException && error.name === \"AbortError\";\n\n        if (!isAbortError) {\n          this.#completedTasks.set(task.key, {\n            key: task.key,\n            owner: task.owner,\n            status: \"failed\",\n            error: error instanceof Error ? error.message : String(error),\n          });\n        }\n\n        // Continue processing queue even after failure\n        this.#processQueue();\n      });\n\n    this.#activeTasks.set(task.key, {\n      task,\n      startedAt: performance.now(),\n      promise,\n    });\n  }\n\n  /**\n   * Get snapshot of current queue state for debugging.\n   */\n  getQueueSnapshot(): UpgradeTaskStatus[] {\n    const results: UpgradeTaskStatus[] = [];\n\n    // Queued tasks\n    for (const task of this.#queue) {\n      results.push({\n        key: task.key,\n        owner: task.owner,\n        deadlineMs: task.deadlineMs,\n        status: \"queued\",\n      });\n    }\n\n    // Active tasks\n    for (const [key, activeTask] of this.#activeTasks.entries()) {\n      results.push({\n        key,\n        owner: activeTask.task.owner,\n        deadlineMs: activeTask.task.deadlineMs,\n        status: \"active\",\n      });\n    }\n\n    // Completed tasks\n    for (const [key, completed] of this.#completedTasks.entries()) {\n      results.push({\n        key,\n        owner: completed.owner,\n        deadlineMs: 0, // No longer relevant\n        status: completed.status as \"completed\" | \"failed\",\n        error: completed.error,\n      });\n    }\n\n    return results;\n  }\n\n  /**\n   * Get progress for a specific owner.\n   */\n  getOwnerProgress(owner: string): OwnerProgress {\n    const queued = this.#queue.filter((t) => t.owner === owner).length;\n\n    let active = 0;\n    for (const activeTask of this.#activeTasks.values()) {\n      if (activeTask.task.owner === owner) {\n        active++;\n      }\n    }\n\n    let completed = 0;\n    let failed = 0;\n    for (const task of this.#completedTasks.values()) {\n      if (task.owner === owner) {\n        if (task.status === \"completed\") {\n          completed++;\n        } else {\n          failed++;\n        }\n      }\n    }\n\n    return { queued, active, completed, failed };\n  }\n\n  /**\n   * Dispose the scheduler - abort all in-flight work.\n   */\n  dispose(): void {\n    // Suppress in-flight task rejections before aborting to avoid unhandled\n    // rejection events from the synchronous abort signal firing.\n    for (const activeTask of this.#activeTasks.values()) {\n      activeTask.promise.catch(() => {});\n    }\n    this.#abortController.abort();\n    this.#queue = [];\n    this.#activeTasks.clear();\n    this.#completedTasks.clear();\n  }\n}\n"],"mappings":"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"}

package/dist/preview/RenderContext.d.ts

@@ -1 +1,119 @@
-import "../elements/EFVideo.js";
+import { EFVideo } from "../elements/EFVideo.js";
+
+//#region src/preview/RenderContext.d.ts
+
+/**
+ * Result of capturing a video frame.
+ */
+interface CapturedFrame {
+  dataUrl: string;
+  width: number;
+  height: number;
+}
+/**
+ * Options for creating a RenderContext.
+ */
+interface RenderContextOptions {
+  /** Maximum number of canvas dataURLs to cache (default: 50) */
+  maxCanvasCacheSize?: number;
+  /** Maximum number of video frame dataURLs to cache (default: 100) */
+  maxVideoFrameCacheSize?: number;
+}
+/**
+ * RenderContext provides scoped caching for render operations.
+ *
+ * Create at the start of a render, dispose when complete:
+ * ```typescript
+ * const context = new RenderContext();
+ * try {
+ *   // ... render operations
+ * } finally {
+ *   context.dispose();
+ * }
+ * ```
+ */
+declare class RenderContext {
+  #private;
+  constructor(options?: RenderContextOptions);
+  /**
+   * Check if the context has been disposed.
+   */
+  get disposed(): boolean;
+  /**
+   * Get cache metrics for monitoring.
+   */
+  get metrics(): {
+    canvasCacheHits: number;
+    canvasCacheMisses: number;
+    videoFrameCacheHits: number;
+    videoFrameCacheMisses: number;
+  };
+  /**
+   * Get a cached dataURL for a static element.
+   * Returns undefined if not cached or element doesn't support caching.
+   */
+  getCachedCanvasDataUrl(element: Element): string | undefined;
+  /**
+   * Cache a dataURL for a static element.
+   * Does nothing if the element doesn't support caching.
+   */
+  setCachedCanvasDataUrl(element: Element, dataUrl: string): void;
+  /**
+   * Get a cached video frame.
+   * Returns undefined if not cached.
+   */
+  getCachedVideoFrame(videoElement: Element, sourceTimeMs: number): CapturedFrame | undefined;
+  /**
+   * Cache a video frame.
+   */
+  setCachedVideoFrame(videoElement: Element, sourceTimeMs: number, frame: CapturedFrame): void;
+  /**
+   * Convenience method to get or capture a video frame.
+   * Checks cache first, then captures if not cached.
+   *
+   * @param video - The ef-video element
+   * @param sourceTimeMs - Source media timestamp
+   * @param options - Capture options including quality and signal
+   * @returns The captured frame data
+   */
+  getOrCaptureVideoFrame(video: EFVideo, sourceTimeMs: number, options?: {
+    quality?: "auto" | "scrub" | "main";
+    signal?: AbortSignal;
+  }): Promise<CapturedFrame>;
+  /**
+   * Get cached document styles.
+   * Returns undefined if not cached.
+   */
+  getCachedDocumentStyles(): string | undefined;
+  /**
+   * Cache document styles.
+   */
+  setCachedDocumentStyles(styles: string): void;
+  /**
+   * Dispose the context and clear all caches.
+   * Should be called when rendering is complete.
+   */
+  dispose(): void;
+  /**
+   * Symbol.dispose implementation for use with the `using` keyword.
+   *
+   * @example
+   * ```typescript
+   * using context = new RenderContext();
+   * // ... render operations
+   * // context is automatically disposed when scope exits
+   * ```
+   */
+  [Symbol.dispose](): void;
+  /**
+   * Get the current size of the canvas cache.
+   */
+  get canvasCacheSize(): number;
+  /**
+   * Get the current size of the video frame cache.
+   */
+  get videoFrameCacheSize(): number;
+}
+//#endregion
+export { RenderContext };
+//# sourceMappingURL=RenderContext.d.ts.map

package/dist/preview/RenderContext.js

@@ -33,7 +33,7 @@ function getElementUniqueId(element) {
 }
 /**
 * RenderContext provides scoped caching for render operations.
-* 
+*
 * Create at the start of a render, dispose when complete:
 * ```typescript
 * const context = new RenderContext();
@@ -49,6 +49,8 @@ var RenderContext = class {
 	#canvasCache;
 	/** Cache for video frames by source timestamp */
 	#videoFrameCache;
+	/** Cache for document styles (computed once per render session) */
+	#documentStylesCache = null;
 	/** Whether this context has been disposed */
 	#disposed = false;
 	/** Metrics for monitoring cache effectiveness */
@@ -138,7 +140,7 @@ var RenderContext = class {
 	/**
 	* Convenience method to get or capture a video frame.
 	* Checks cache first, then captures if not cached.
-	* 
+	*
 	* @param video - The ef-video element
 	* @param sourceTimeMs - Source media timestamp
 	* @param options - Capture options including quality and signal
@@ -152,6 +154,21 @@ var RenderContext = class {
 		return frame;
 	}
 	/**
+	* Get cached document styles.
+	* Returns undefined if not cached.
+	*/
+	getCachedDocumentStyles() {
+		if (this.#disposed) return void 0;
+		return this.#documentStylesCache ?? void 0;
+	}
+	/**
+	* Cache document styles.
+	*/
+	setCachedDocumentStyles(styles) {
+		if (this.#disposed) return;
+		this.#documentStylesCache = styles;
+	}
+	/**
 	* Dispose the context and clear all caches.
 	* Should be called when rendering is complete.
 	*/
@@ -159,11 +176,12 @@ var RenderContext = class {
 		if (this.#disposed) return;
 		this.#canvasCache.clear();
 		this.#videoFrameCache.clear();
+		this.#documentStylesCache = null;
 		this.#disposed = true;
 	}
 	/**
 	* Symbol.dispose implementation for use with the `using` keyword.
-	* 
+	*
 	* @example
 	* ```typescript
 	* using context = new RenderContext();

package/dist/preview/RenderContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"RenderContext.js","names":["#canvasCache","#videoFrameCache","#disposed","#metrics","#getCanvasCacheKey","#getVideoFrameCacheKey"],"sources":["../../src/preview/RenderContext.ts"],"sourcesContent":["/**\n * RenderContext manages scoped caches for the rendering pipeline.\n * \n * Used during foreignObject serialization to cache:\n * - Video frames by source timestamp (useful for freeze frames, slow-mo)\n * - Static element canvases by element identity + renderVersion\n * \n * The context should be created at the start of a render operation\n * and disposed when the render completes (success or failure).\n */\n\nimport { LRUCache } from \"../utils/LRUCache.js\";\nimport type { EFVideo } from \"../elements/EFVideo.js\";\n\n/**\n * Check if an element has a renderVersion property.\n */\nfunction hasRenderVersion(element: Element): element is Element & { renderVersion: number } {\n  return \"renderVersion\" in element && typeof (element as any).renderVersion === \"number\";\n}\n\n/**\n * Module-level counter for generating unique element IDs.\n * This ensures uniqueness across all RenderContext instances.\n */\nlet nextElementId = 1;\n\n/**\n * WeakMap to store unique IDs for elements.\n * Using WeakMap ensures we don't prevent garbage collection of elements.\n * The ID is stable for the lifetime of the element.\n */\nconst elementUniqueIds = new WeakMap<Element, number>();\n\n/**\n * Get or create a unique ID for an element.\n * This guarantees uniqueness even for elements with the same id attribute\n * or no id attribute at all.\n */\nfunction getElementUniqueId(element: Element): number {\n  let id = elementUniqueIds.get(element);\n  if (id === undefined) {\n    id = nextElementId++;\n    elementUniqueIds.set(element, id);\n  }\n  return id;\n}\n\n/**\n * Result of capturing a video frame.\n */\nexport interface CapturedFrame {\n  dataUrl: string;\n  width: number;\n  height: number;\n}\n\n/**\n * Options for creating a RenderContext.\n */\nexport interface RenderContextOptions {\n  /** Maximum number of canvas dataURLs to cache (default: 50) */\n  maxCanvasCacheSize?: number;\n  /** Maximum number of video frame dataURLs to cache (default: 100) */\n  maxVideoFrameCacheSize?: number;\n}\n\n/**\n * RenderContext provides scoped caching for render operations.\n * \n * Create at the start of a render, dispose when complete:\n * ```typescript\n * const context = new RenderContext();\n * try {\n *   // ... render operations\n * } finally {\n *   context.dispose();\n * }\n * ```\n */\nexport class RenderContext {\n  /** Cache for static element canvases (ef-image, ef-waveform) */\n  #canvasCache: LRUCache<string, string>;\n  \n  /** Cache for video frames by source timestamp */\n  #videoFrameCache: LRUCache<string, CapturedFrame>;\n  \n  /** Whether this context has been disposed */\n  #disposed = false;\n  \n  /** Metrics for monitoring cache effectiveness */\n  #metrics = {\n    canvasCacheHits: 0,\n    canvasCacheMisses: 0,\n    videoFrameCacheHits: 0,\n    videoFrameCacheMisses: 0,\n  };\n\n  constructor(options: RenderContextOptions = {}) {\n    const { maxCanvasCacheSize = 50, maxVideoFrameCacheSize = 100 } = options;\n    this.#canvasCache = new LRUCache(maxCanvasCacheSize);\n    this.#videoFrameCache = new LRUCache(maxVideoFrameCacheSize);\n  }\n\n  /**\n   * Check if the context has been disposed.\n   */\n  get disposed(): boolean {\n    return this.#disposed;\n  }\n\n  /**\n   * Get cache metrics for monitoring.\n   */\n  get metrics() {\n    return { ...this.#metrics };\n  }\n\n  // ============================================================================\n  // Static Element Cache (ef-image, ef-waveform)\n  // ============================================================================\n\n  /**\n   * Generate a cache key for a static element.\n   * Uses a unique element ID (via WeakMap) to ensure uniqueness even if\n   * multiple elements have the same id attribute.\n   * Returns null if the element doesn't support caching (no renderVersion).\n   */\n  #getCanvasCacheKey(element: Element): string | null {\n    if (!hasRenderVersion(element)) {\n      return null;\n    }\n    // Use unique element ID + render version for guaranteed uniqueness\n    const uniqueId = getElementUniqueId(element);\n    return `canvas:${uniqueId}:${element.renderVersion}`;\n  }\n\n  /**\n   * Get a cached dataURL for a static element.\n   * Returns undefined if not cached or element doesn't support caching.\n   */\n  getCachedCanvasDataUrl(element: Element): string | undefined {\n    if (this.#disposed) return undefined;\n    \n    const key = this.#getCanvasCacheKey(element);\n    if (!key) return undefined;\n    \n    const cached = this.#canvasCache.get(key);\n    if (cached) {\n      this.#metrics.canvasCacheHits++;\n    } else {\n      this.#metrics.canvasCacheMisses++;\n    }\n    return cached;\n  }\n\n  /**\n   * Cache a dataURL for a static element.\n   * Does nothing if the element doesn't support caching.\n   */\n  setCachedCanvasDataUrl(element: Element, dataUrl: string): void {\n    if (this.#disposed) return;\n    \n    const key = this.#getCanvasCacheKey(element);\n    if (key) {\n      this.#canvasCache.set(key, dataUrl);\n    }\n  }\n\n  // ============================================================================\n  // Video Frame Cache\n  // ============================================================================\n\n  /**\n   * Generate a cache key for a video frame.\n   * Uses a unique element ID (via WeakMap) to ensure uniqueness even if\n   * multiple videos have the same id attribute.\n   */\n  #getVideoFrameCacheKey(videoElement: Element, sourceTimeMs: number): string {\n    const uniqueId = getElementUniqueId(videoElement);\n    // Round to nearest ms to avoid floating point issues\n    const roundedTime = Math.round(sourceTimeMs);\n    return `video:${uniqueId}:${roundedTime}`;\n  }\n\n  /**\n   * Get a cached video frame.\n   * Returns undefined if not cached.\n   */\n  getCachedVideoFrame(videoElement: Element, sourceTimeMs: number): CapturedFrame | undefined {\n    if (this.#disposed) return undefined;\n    \n    const key = this.#getVideoFrameCacheKey(videoElement, sourceTimeMs);\n    const cached = this.#videoFrameCache.get(key);\n    if (cached) {\n      this.#metrics.videoFrameCacheHits++;\n    } else {\n      this.#metrics.videoFrameCacheMisses++;\n    }\n    return cached;\n  }\n\n  /**\n   * Cache a video frame.\n   */\n  setCachedVideoFrame(videoElement: Element, sourceTimeMs: number, frame: CapturedFrame): void {\n    if (this.#disposed) return;\n    \n    const key = this.#getVideoFrameCacheKey(videoElement, sourceTimeMs);\n    this.#videoFrameCache.set(key, frame);\n  }\n\n  /**\n   * Convenience method to get or capture a video frame.\n   * Checks cache first, then captures if not cached.\n   * \n   * @param video - The ef-video element\n   * @param sourceTimeMs - Source media timestamp\n   * @param options - Capture options including quality and signal\n   * @returns The captured frame data\n   */\n  async getOrCaptureVideoFrame(\n    video: EFVideo,\n    sourceTimeMs: number,\n    options: {\n      quality?: \"auto\" | \"scrub\" | \"main\";\n      signal?: AbortSignal;\n    } = {}\n  ): Promise<CapturedFrame> {\n    // Check cache first\n    const cached = this.getCachedVideoFrame(video, sourceTimeMs);\n    if (cached) {\n      return cached;\n    }\n\n    // Capture frame using direct API\n    const frame = await video.captureFrameAtSourceTime(sourceTimeMs, options);\n    \n    // Cache for future use\n    this.setCachedVideoFrame(video, sourceTimeMs, frame);\n    \n    return frame;\n  }\n\n  // ============================================================================\n  // Cleanup\n  // ============================================================================\n\n  /**\n   * Dispose the context and clear all caches.\n   * Should be called when rendering is complete.\n   */\n  dispose(): void {\n    if (this.#disposed) return;\n    \n    this.#canvasCache.clear();\n    this.#videoFrameCache.clear();\n    this.#disposed = true;\n  }\n\n  /**\n   * Symbol.dispose implementation for use with the `using` keyword.\n   * \n   * @example\n   * ```typescript\n   * using context = new RenderContext();\n   * // ... render operations\n   * // context is automatically disposed when scope exits\n   * ```\n   */\n  [Symbol.dispose](): void {\n    this.dispose();\n  }\n\n  /**\n   * Get the current size of the canvas cache.\n   */\n  get canvasCacheSize(): number {\n    return this.#canvasCache.size;\n  }\n\n  /**\n   * Get the current size of the video frame cache.\n   */\n  get videoFrameCacheSize(): number {\n    return this.#videoFrameCache.size;\n  }\n}\n"],"mappings":";;;;;;AAiBA,SAAS,iBAAiB,SAAkE;AAC1F,QAAO,mBAAmB,WAAW,OAAQ,QAAgB,kBAAkB;;;;;;AAOjF,IAAI,gBAAgB;;;;;;AAOpB,MAAM,mCAAmB,IAAI,SAA0B;;;;;;AAOvD,SAAS,mBAAmB,SAA0B;CACpD,IAAI,KAAK,iBAAiB,IAAI,QAAQ;AACtC,KAAI,OAAO,QAAW;AACpB,OAAK;AACL,mBAAiB,IAAI,SAAS,GAAG;;AAEnC,QAAO;;;;;;;;;;;;;;;AAmCT,IAAa,gBAAb,MAA2B;;CAEzB;;CAGA;;CAGA,YAAY;;CAGZ,WAAW;EACT,iBAAiB;EACjB,mBAAmB;EACnB,qBAAqB;EACrB,uBAAuB;EACxB;CAED,YAAY,UAAgC,EAAE,EAAE;EAC9C,MAAM,EAAE,qBAAqB,IAAI,yBAAyB,QAAQ;AAClE,QAAKA,cAAe,IAAI,SAAS,mBAAmB;AACpD,QAAKC,kBAAmB,IAAI,SAAS,uBAAuB;;;;;CAM9D,IAAI,WAAoB;AACtB,SAAO,MAAKC;;;;;CAMd,IAAI,UAAU;AACZ,SAAO,EAAE,GAAG,MAAKC,SAAU;;;;;;;;CAa7B,mBAAmB,SAAiC;AAClD,MAAI,CAAC,iBAAiB,QAAQ,CAC5B,QAAO;AAIT,SAAO,UADU,mBAAmB,QAAQ,CAClB,GAAG,QAAQ;;;;;;CAOvC,uBAAuB,SAAsC;AAC3D,MAAI,MAAKD,SAAW,QAAO;EAE3B,MAAM,MAAM,MAAKE,kBAAmB,QAAQ;AAC5C,MAAI,CAAC,IAAK,QAAO;EAEjB,MAAM,SAAS,MAAKJ,YAAa,IAAI,IAAI;AACzC,MAAI,OACF,OAAKG,QAAS;MAEd,OAAKA,QAAS;AAEhB,SAAO;;;;;;CAOT,uBAAuB,SAAkB,SAAuB;AAC9D,MAAI,MAAKD,SAAW;EAEpB,MAAM,MAAM,MAAKE,kBAAmB,QAAQ;AAC5C,MAAI,IACF,OAAKJ,YAAa,IAAI,KAAK,QAAQ;;;;;;;CAavC,uBAAuB,cAAuB,cAA8B;AAI1E,SAAO,SAHU,mBAAmB,aAAa,CAGxB,GADL,KAAK,MAAM,aAAa;;;;;;CAQ9C,oBAAoB,cAAuB,cAAiD;AAC1F,MAAI,MAAKE,SAAW,QAAO;EAE3B,MAAM,MAAM,MAAKG,sBAAuB,cAAc,aAAa;EACnE,MAAM,SAAS,MAAKJ,gBAAiB,IAAI,IAAI;AAC7C,MAAI,OACF,OAAKE,QAAS;MAEd,OAAKA,QAAS;AAEhB,SAAO;;;;;CAMT,oBAAoB,cAAuB,cAAsB,OAA4B;AAC3F,MAAI,MAAKD,SAAW;EAEpB,MAAM,MAAM,MAAKG,sBAAuB,cAAc,aAAa;AACnE,QAAKJ,gBAAiB,IAAI,KAAK,MAAM;;;;;;;;;;;CAYvC,MAAM,uBACJ,OACA,cACA,UAGI,EAAE,EACkB;EAExB,MAAM,SAAS,KAAK,oBAAoB,OAAO,aAAa;AAC5D,MAAI,OACF,QAAO;EAIT,MAAM,QAAQ,MAAM,MAAM,yBAAyB,cAAc,QAAQ;AAGzE,OAAK,oBAAoB,OAAO,cAAc,MAAM;AAEpD,SAAO;;;;;;CAWT,UAAgB;AACd,MAAI,MAAKC,SAAW;AAEpB,QAAKF,YAAa,OAAO;AACzB,QAAKC,gBAAiB,OAAO;AAC7B,QAAKC,WAAY;;;;;;;;;;;;CAanB,CAAC,OAAO,WAAiB;AACvB,OAAK,SAAS;;;;;CAMhB,IAAI,kBAA0B;AAC5B,SAAO,MAAKF,YAAa;;;;;CAM3B,IAAI,sBAA8B;AAChC,SAAO,MAAKC,gBAAiB"}
+{"version":3,"file":"RenderContext.js","names":["#canvasCache","#videoFrameCache","#disposed","#metrics","#getCanvasCacheKey","#getVideoFrameCacheKey","#documentStylesCache"],"sources":["../../src/preview/RenderContext.ts"],"sourcesContent":["/**\n * RenderContext manages scoped caches for the rendering pipeline.\n *\n * Used during foreignObject serialization to cache:\n * - Video frames by source timestamp (useful for freeze frames, slow-mo)\n * - Static element canvases by element identity + renderVersion\n *\n * The context should be created at the start of a render operation\n * and disposed when the render completes (success or failure).\n */\n\nimport { LRUCache } from \"../utils/LRUCache.js\";\nimport type { EFVideo } from \"../elements/EFVideo.js\";\n\n/**\n * Check if an element has a renderVersion property.\n */\nfunction hasRenderVersion(\n  element: Element,\n): element is Element & { renderVersion: number } {\n  return (\n    \"renderVersion\" in element &&\n    typeof (element as any).renderVersion === \"number\"\n  );\n}\n\n/**\n * Module-level counter for generating unique element IDs.\n * This ensures uniqueness across all RenderContext instances.\n */\nlet nextElementId = 1;\n\n/**\n * WeakMap to store unique IDs for elements.\n * Using WeakMap ensures we don't prevent garbage collection of elements.\n * The ID is stable for the lifetime of the element.\n */\nconst elementUniqueIds = new WeakMap<Element, number>();\n\n/**\n * Get or create a unique ID for an element.\n * This guarantees uniqueness even for elements with the same id attribute\n * or no id attribute at all.\n */\nfunction getElementUniqueId(element: Element): number {\n  let id = elementUniqueIds.get(element);\n  if (id === undefined) {\n    id = nextElementId++;\n    elementUniqueIds.set(element, id);\n  }\n  return id;\n}\n\n/**\n * Result of capturing a video frame.\n */\nexport interface CapturedFrame {\n  dataUrl: string;\n  width: number;\n  height: number;\n}\n\n/**\n * Options for creating a RenderContext.\n */\nexport interface RenderContextOptions {\n  /** Maximum number of canvas dataURLs to cache (default: 50) */\n  maxCanvasCacheSize?: number;\n  /** Maximum number of video frame dataURLs to cache (default: 100) */\n  maxVideoFrameCacheSize?: number;\n}\n\n/**\n * RenderContext provides scoped caching for render operations.\n *\n * Create at the start of a render, dispose when complete:\n * ```typescript\n * const context = new RenderContext();\n * try {\n *   // ... render operations\n * } finally {\n *   context.dispose();\n * }\n * ```\n */\nexport class RenderContext {\n  /** Cache for static element canvases (ef-image, ef-waveform) */\n  #canvasCache: LRUCache<string, string>;\n\n  /** Cache for video frames by source timestamp */\n  #videoFrameCache: LRUCache<string, CapturedFrame>;\n\n  /** Cache for document styles (computed once per render session) */\n  #documentStylesCache: string | null = null;\n\n  /** Whether this context has been disposed */\n  #disposed = false;\n\n  /** Metrics for monitoring cache effectiveness */\n  #metrics = {\n    canvasCacheHits: 0,\n    canvasCacheMisses: 0,\n    videoFrameCacheHits: 0,\n    videoFrameCacheMisses: 0,\n  };\n\n  constructor(options: RenderContextOptions = {}) {\n    const { maxCanvasCacheSize = 50, maxVideoFrameCacheSize = 100 } = options;\n    this.#canvasCache = new LRUCache(maxCanvasCacheSize);\n    this.#videoFrameCache = new LRUCache(maxVideoFrameCacheSize);\n  }\n\n  /**\n   * Check if the context has been disposed.\n   */\n  get disposed(): boolean {\n    return this.#disposed;\n  }\n\n  /**\n   * Get cache metrics for monitoring.\n   */\n  get metrics() {\n    return { ...this.#metrics };\n  }\n\n  // ============================================================================\n  // Static Element Cache (ef-image, ef-waveform)\n  // ============================================================================\n\n  /**\n   * Generate a cache key for a static element.\n   * Uses a unique element ID (via WeakMap) to ensure uniqueness even if\n   * multiple elements have the same id attribute.\n   * Returns null if the element doesn't support caching (no renderVersion).\n   */\n  #getCanvasCacheKey(element: Element): string | null {\n    if (!hasRenderVersion(element)) {\n      return null;\n    }\n    // Use unique element ID + render version for guaranteed uniqueness\n    const uniqueId = getElementUniqueId(element);\n    return `canvas:${uniqueId}:${element.renderVersion}`;\n  }\n\n  /**\n   * Get a cached dataURL for a static element.\n   * Returns undefined if not cached or element doesn't support caching.\n   */\n  getCachedCanvasDataUrl(element: Element): string | undefined {\n    if (this.#disposed) return undefined;\n\n    const key = this.#getCanvasCacheKey(element);\n    if (!key) return undefined;\n\n    const cached = this.#canvasCache.get(key);\n    if (cached) {\n      this.#metrics.canvasCacheHits++;\n    } else {\n      this.#metrics.canvasCacheMisses++;\n    }\n    return cached;\n  }\n\n  /**\n   * Cache a dataURL for a static element.\n   * Does nothing if the element doesn't support caching.\n   */\n  setCachedCanvasDataUrl(element: Element, dataUrl: string): void {\n    if (this.#disposed) return;\n\n    const key = this.#getCanvasCacheKey(element);\n    if (key) {\n      this.#canvasCache.set(key, dataUrl);\n    }\n  }\n\n  // ============================================================================\n  // Video Frame Cache\n  // ============================================================================\n\n  /**\n   * Generate a cache key for a video frame.\n   * Uses a unique element ID (via WeakMap) to ensure uniqueness even if\n   * multiple videos have the same id attribute.\n   */\n  #getVideoFrameCacheKey(videoElement: Element, sourceTimeMs: number): string {\n    const uniqueId = getElementUniqueId(videoElement);\n    // Round to nearest ms to avoid floating point issues\n    const roundedTime = Math.round(sourceTimeMs);\n    return `video:${uniqueId}:${roundedTime}`;\n  }\n\n  /**\n   * Get a cached video frame.\n   * Returns undefined if not cached.\n   */\n  getCachedVideoFrame(\n    videoElement: Element,\n    sourceTimeMs: number,\n  ): CapturedFrame | undefined {\n    if (this.#disposed) return undefined;\n\n    const key = this.#getVideoFrameCacheKey(videoElement, sourceTimeMs);\n    const cached = this.#videoFrameCache.get(key);\n    if (cached) {\n      this.#metrics.videoFrameCacheHits++;\n    } else {\n      this.#metrics.videoFrameCacheMisses++;\n    }\n    return cached;\n  }\n\n  /**\n   * Cache a video frame.\n   */\n  setCachedVideoFrame(\n    videoElement: Element,\n    sourceTimeMs: number,\n    frame: CapturedFrame,\n  ): void {\n    if (this.#disposed) return;\n\n    const key = this.#getVideoFrameCacheKey(videoElement, sourceTimeMs);\n    this.#videoFrameCache.set(key, frame);\n  }\n\n  /**\n   * Convenience method to get or capture a video frame.\n   * Checks cache first, then captures if not cached.\n   *\n   * @param video - The ef-video element\n   * @param sourceTimeMs - Source media timestamp\n   * @param options - Capture options including quality and signal\n   * @returns The captured frame data\n   */\n  async getOrCaptureVideoFrame(\n    video: EFVideo,\n    sourceTimeMs: number,\n    options: {\n      quality?: \"auto\" | \"scrub\" | \"main\";\n      signal?: AbortSignal;\n    } = {},\n  ): Promise<CapturedFrame> {\n    // Check cache first\n    const cached = this.getCachedVideoFrame(video, sourceTimeMs);\n    if (cached) {\n      return cached;\n    }\n\n    // Capture frame using direct API\n    const frame = await video.captureFrameAtSourceTime(sourceTimeMs, options);\n\n    // Cache for future use\n    this.setCachedVideoFrame(video, sourceTimeMs, frame);\n\n    return frame;\n  }\n\n  // ============================================================================\n  // Document Styles Cache\n  // ============================================================================\n\n  /**\n   * Get cached document styles.\n   * Returns undefined if not cached.\n   */\n  getCachedDocumentStyles(): string | undefined {\n    if (this.#disposed) return undefined;\n    return this.#documentStylesCache ?? undefined;\n  }\n\n  /**\n   * Cache document styles.\n   */\n  setCachedDocumentStyles(styles: string): void {\n    if (this.#disposed) return;\n    this.#documentStylesCache = styles;\n  }\n\n  // ============================================================================\n  // Cleanup\n  // ============================================================================\n\n  /**\n   * Dispose the context and clear all caches.\n   * Should be called when rendering is complete.\n   */\n  dispose(): void {\n    if (this.#disposed) return;\n\n    this.#canvasCache.clear();\n    this.#videoFrameCache.clear();\n    this.#documentStylesCache = null;\n    this.#disposed = true;\n  }\n\n  /**\n   * Symbol.dispose implementation for use with the `using` keyword.\n   *\n   * @example\n   * ```typescript\n   * using context = new RenderContext();\n   * // ... render operations\n   * // context is automatically disposed when scope exits\n   * ```\n   */\n  [Symbol.dispose](): void {\n    this.dispose();\n  }\n\n  /**\n   * Get the current size of the canvas cache.\n   */\n  get canvasCacheSize(): number {\n    return this.#canvasCache.size;\n  }\n\n  /**\n   * Get the current size of the video frame cache.\n   */\n  get videoFrameCacheSize(): number {\n    return this.#videoFrameCache.size;\n  }\n}\n"],"mappings":"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"}

package/dist/preview/RenderProfiler.js.map

@@ -1 +1 @@
-{"version":3,"file":"RenderProfiler.js","names":["parts: string[]"],"sources":["../../src/preview/RenderProfiler.ts"],"sourcesContent":["/**\n * Profiling utility for render operations.\n * Centralizes timing accumulation and logging to keep business logic clean.\n */\n\n/** Interval between profiling log outputs (ms) */\nconst DEFAULT_LOG_INTERVAL_MS = 2000;\n\n/** Interval for periodic frame logging (every N frames) */\nconst DEFAULT_FRAME_LOG_INTERVAL = 60;\n\n/**\n * Phases tracked during rendering.\n */\nexport interface RenderTimings {\n  setup: number;\n  draw: number;\n  downsample: number;\n  canvasEncode: number;\n  inline: number;\n  serialize: number;\n  base64: number;\n  imageLoad: number;\n  restore: number;\n}\n\n/**\n * Profiler for render operations.\n * Accumulates timing data and provides structured logging.\n */\nexport class RenderProfiler {\n  private _renderCount = 0;\n  private _lastLogTime = 0;\n  private _timingLoggedAt = 0;\n  \n  private _timings: RenderTimings = {\n    setup: 0,\n    draw: 0,\n    downsample: 0,\n    canvasEncode: 0,\n    inline: 0,\n    serialize: 0,\n    base64: 0,\n    imageLoad: 0,\n    restore: 0,\n  };\n\n  /**\n   * Reset all timing data.\n   */\n  reset(): void {\n    this._renderCount = 0;\n    this._lastLogTime = 0;\n    this._timingLoggedAt = 0;\n    \n    for (const key of Object.keys(this._timings) as (keyof RenderTimings)[]) {\n      this._timings[key] = 0;\n    }\n  }\n\n  /**\n   * Get current render count.\n   */\n  get renderCount(): number {\n    return this._renderCount;\n  }\n\n  /**\n   * Increment render count.\n   */\n  incrementRenderCount(): void {\n    this._renderCount++;\n  }\n\n  /**\n   * Add time to a specific phase.\n   */\n  addTime(phase: keyof RenderTimings, ms: number): void {\n    this._timings[phase] += ms;\n  }\n\n  /**\n   * Time a synchronous operation and add to the specified phase.\n   */\n  time<T>(phase: keyof RenderTimings, fn: () => T): T {\n    const start = performance.now();\n    const result = fn();\n    this._timings[phase] += performance.now() - start;\n    return result;\n  }\n\n  /**\n   * Time an async operation and add to the specified phase.\n   */\n  async timeAsync<T>(phase: keyof RenderTimings, fn: () => Promise<T>): Promise<T> {\n    const start = performance.now();\n    const result = await fn();\n    this._timings[phase] += performance.now() - start;\n    return result;\n  }\n\n  /**\n   * Check if enough time has passed since last log (for time-based logging).\n   */\n  shouldLogByTime(intervalMs: number = DEFAULT_LOG_INTERVAL_MS): boolean {\n    const now = performance.now();\n    if (now - this._lastLogTime > intervalMs) {\n      this._lastLogTime = now;\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Check if enough frames have passed since last log (for frame-based logging).\n   */\n  shouldLogByFrameCount(interval: number = DEFAULT_FRAME_LOG_INTERVAL): boolean {\n    if (this._renderCount - this._timingLoggedAt >= interval) {\n      this._timingLoggedAt = this._renderCount;\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Check if this is an early render (for initial debug logging).\n   */\n  isEarlyRender(threshold: number = 2): boolean {\n    return this._renderCount < threshold;\n  }\n\n  /**\n   * Get timing summary string.\n   */\n  summary(): string {\n    const t = this._timings;\n    const parts: string[] = [];\n    \n    if (t.setup > 0) parts.push(`setup=${t.setup.toFixed(0)}ms`);\n    if (t.draw > 0) parts.push(`draw=${t.draw.toFixed(0)}ms`);\n    if (t.downsample > 0) parts.push(`downsample=${t.downsample.toFixed(0)}ms`);\n    if (t.canvasEncode > 0) parts.push(`canvasEncode=${t.canvasEncode.toFixed(0)}ms`);\n    if (t.inline > 0) parts.push(`inline=${t.inline.toFixed(0)}ms`);\n    if (t.serialize > 0) parts.push(`serialize=${t.serialize.toFixed(0)}ms`);\n    if (t.base64 > 0) parts.push(`base64=${t.base64.toFixed(0)}ms`);\n    if (t.imageLoad > 0) parts.push(`imageLoad=${t.imageLoad.toFixed(0)}ms`);\n    if (t.restore > 0) parts.push(`restore=${t.restore.toFixed(0)}ms`);\n    \n    return parts.join(', ');\n  }\n\n  /**\n   * Get raw timings object.\n   */\n  getTimings(): Readonly<RenderTimings> {\n    return { ...this._timings };\n  }\n}\n\n/**\n * Default shared profiler instance.\n * Can be replaced with a custom instance for testing.\n */\nexport const defaultProfiler = new RenderProfiler();\n"],"mappings":";;;;;;AAMA,MAAM,0BAA0B;;AAGhC,MAAM,6BAA6B;;;;;AAqBnC,IAAa,iBAAb,MAA4B;;sBACH;sBACA;yBACG;kBAEQ;GAChC,OAAO;GACP,MAAM;GACN,YAAY;GACZ,cAAc;GACd,QAAQ;GACR,WAAW;GACX,QAAQ;GACR,WAAW;GACX,SAAS;GACV;;;;;CAKD,QAAc;AACZ,OAAK,eAAe;AACpB,OAAK,eAAe;AACpB,OAAK,kBAAkB;AAEvB,OAAK,MAAM,OAAO,OAAO,KAAK,KAAK,SAAS,CAC1C,MAAK,SAAS,OAAO;;;;;CAOzB,IAAI,cAAsB;AACxB,SAAO,KAAK;;;;;CAMd,uBAA6B;AAC3B,OAAK;;;;;CAMP,QAAQ,OAA4B,IAAkB;AACpD,OAAK,SAAS,UAAU;;;;;CAM1B,KAAQ,OAA4B,IAAgB;EAClD,MAAM,QAAQ,YAAY,KAAK;EAC/B,MAAM,SAAS,IAAI;AACnB,OAAK,SAAS,UAAU,YAAY,KAAK,GAAG;AAC5C,SAAO;;;;;CAMT,MAAM,UAAa,OAA4B,IAAkC;EAC/E,MAAM,QAAQ,YAAY,KAAK;EAC/B,MAAM,SAAS,MAAM,IAAI;AACzB,OAAK,SAAS,UAAU,YAAY,KAAK,GAAG;AAC5C,SAAO;;;;;CAMT,gBAAgB,aAAqB,yBAAkC;EACrE,MAAM,MAAM,YAAY,KAAK;AAC7B,MAAI,MAAM,KAAK,eAAe,YAAY;AACxC,QAAK,eAAe;AACpB,UAAO;;AAET,SAAO;;;;;CAMT,sBAAsB,WAAmB,4BAAqC;AAC5E,MAAI,KAAK,eAAe,KAAK,mBAAmB,UAAU;AACxD,QAAK,kBAAkB,KAAK;AAC5B,UAAO;;AAET,SAAO;;;;;CAMT,cAAc,YAAoB,GAAY;AAC5C,SAAO,KAAK,eAAe;;;;;CAM7B,UAAkB;EAChB,MAAM,IAAI,KAAK;EACf,MAAMA,QAAkB,EAAE;AAE1B,MAAI,EAAE,QAAQ,EAAG,OAAM,KAAK,SAAS,EAAE,MAAM,QAAQ,EAAE,CAAC,IAAI;AAC5D,MAAI,EAAE,OAAO,EAAG,OAAM,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,CAAC,IAAI;AACzD,MAAI,EAAE,aAAa,EAAG,OAAM,KAAK,cAAc,EAAE,WAAW,QAAQ,EAAE,CAAC,IAAI;AAC3E,MAAI,EAAE,eAAe,EAAG,OAAM,KAAK,gBAAgB,EAAE,aAAa,QAAQ,EAAE,CAAC,IAAI;AACjF,MAAI,EAAE,SAAS,EAAG,OAAM,KAAK,UAAU,EAAE,OAAO,QAAQ,EAAE,CAAC,IAAI;AAC/D,MAAI,EAAE,YAAY,EAAG,OAAM,KAAK,aAAa,EAAE,UAAU,QAAQ,EAAE,CAAC,IAAI;AACxE,MAAI,EAAE,SAAS,EAAG,OAAM,KAAK,UAAU,EAAE,OAAO,QAAQ,EAAE,CAAC,IAAI;AAC/D,MAAI,EAAE,YAAY,EAAG,OAAM,KAAK,aAAa,EAAE,UAAU,QAAQ,EAAE,CAAC,IAAI;AACxE,MAAI,EAAE,UAAU,EAAG,OAAM,KAAK,WAAW,EAAE,QAAQ,QAAQ,EAAE,CAAC,IAAI;AAElE,SAAO,MAAM,KAAK,KAAK;;;;;CAMzB,aAAsC;AACpC,SAAO,EAAE,GAAG,KAAK,UAAU;;;;;;;AAQ/B,MAAa,kBAAkB,IAAI,gBAAgB"}
+{"version":3,"file":"RenderProfiler.js","names":["parts: string[]"],"sources":["../../src/preview/RenderProfiler.ts"],"sourcesContent":["/**\n * Profiling utility for render operations.\n * Centralizes timing accumulation and logging to keep business logic clean.\n */\n\n/** Interval between profiling log outputs (ms) */\nconst DEFAULT_LOG_INTERVAL_MS = 2000;\n\n/** Interval for periodic frame logging (every N frames) */\nconst DEFAULT_FRAME_LOG_INTERVAL = 60;\n\n/**\n * Phases tracked during rendering.\n */\nexport interface RenderTimings {\n  setup: number;\n  draw: number;\n  downsample: number;\n  canvasEncode: number;\n  inline: number;\n  serialize: number;\n  base64: number;\n  imageLoad: number;\n  restore: number;\n}\n\n/**\n * Profiler for render operations.\n * Accumulates timing data and provides structured logging.\n */\nexport class RenderProfiler {\n  private _renderCount = 0;\n  private _lastLogTime = 0;\n  private _timingLoggedAt = 0;\n\n  private _timings: RenderTimings = {\n    setup: 0,\n    draw: 0,\n    downsample: 0,\n    canvasEncode: 0,\n    inline: 0,\n    serialize: 0,\n    base64: 0,\n    imageLoad: 0,\n    restore: 0,\n  };\n\n  /**\n   * Reset all timing data.\n   */\n  reset(): void {\n    this._renderCount = 0;\n    this._lastLogTime = 0;\n    this._timingLoggedAt = 0;\n\n    for (const key of Object.keys(this._timings) as (keyof RenderTimings)[]) {\n      this._timings[key] = 0;\n    }\n  }\n\n  /**\n   * Get current render count.\n   */\n  get renderCount(): number {\n    return this._renderCount;\n  }\n\n  /**\n   * Increment render count.\n   */\n  incrementRenderCount(): void {\n    this._renderCount++;\n  }\n\n  /**\n   * Add time to a specific phase.\n   */\n  addTime(phase: keyof RenderTimings, ms: number): void {\n    this._timings[phase] += ms;\n  }\n\n  /**\n   * Time a synchronous operation and add to the specified phase.\n   */\n  time<T>(phase: keyof RenderTimings, fn: () => T): T {\n    const start = performance.now();\n    const result = fn();\n    this._timings[phase] += performance.now() - start;\n    return result;\n  }\n\n  /**\n   * Time an async operation and add to the specified phase.\n   */\n  async timeAsync<T>(\n    phase: keyof RenderTimings,\n    fn: () => Promise<T>,\n  ): Promise<T> {\n    const start = performance.now();\n    const result = await fn();\n    this._timings[phase] += performance.now() - start;\n    return result;\n  }\n\n  /**\n   * Check if enough time has passed since last log (for time-based logging).\n   */\n  shouldLogByTime(intervalMs: number = DEFAULT_LOG_INTERVAL_MS): boolean {\n    const now = performance.now();\n    if (now - this._lastLogTime > intervalMs) {\n      this._lastLogTime = now;\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Check if enough frames have passed since last log (for frame-based logging).\n   */\n  shouldLogByFrameCount(\n    interval: number = DEFAULT_FRAME_LOG_INTERVAL,\n  ): boolean {\n    if (this._renderCount - this._timingLoggedAt >= interval) {\n      this._timingLoggedAt = this._renderCount;\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Check if this is an early render (for initial debug logging).\n   */\n  isEarlyRender(threshold: number = 2): boolean {\n    return this._renderCount < threshold;\n  }\n\n  /**\n   * Get timing summary string.\n   */\n  summary(): string {\n    const t = this._timings;\n    const parts: string[] = [];\n\n    if (t.setup > 0) parts.push(`setup=${t.setup.toFixed(0)}ms`);\n    if (t.draw > 0) parts.push(`draw=${t.draw.toFixed(0)}ms`);\n    if (t.downsample > 0) parts.push(`downsample=${t.downsample.toFixed(0)}ms`);\n    if (t.canvasEncode > 0)\n      parts.push(`canvasEncode=${t.canvasEncode.toFixed(0)}ms`);\n    if (t.inline > 0) parts.push(`inline=${t.inline.toFixed(0)}ms`);\n    if (t.serialize > 0) parts.push(`serialize=${t.serialize.toFixed(0)}ms`);\n    if (t.base64 > 0) parts.push(`base64=${t.base64.toFixed(0)}ms`);\n    if (t.imageLoad > 0) parts.push(`imageLoad=${t.imageLoad.toFixed(0)}ms`);\n    if (t.restore > 0) parts.push(`restore=${t.restore.toFixed(0)}ms`);\n\n    return parts.join(\", \");\n  }\n\n  /**\n   * Get raw timings object.\n   */\n  getTimings(): Readonly<RenderTimings> {\n    return { ...this._timings };\n  }\n}\n\n/**\n * Default shared profiler instance.\n * Can be replaced with a custom instance for testing.\n */\nexport const defaultProfiler = new RenderProfiler();\n"],"mappings":";;;;;;AAMA,MAAM,0BAA0B;;AAGhC,MAAM,6BAA6B;;;;;AAqBnC,IAAa,iBAAb,MAA4B;;sBACH;sBACA;yBACG;kBAEQ;GAChC,OAAO;GACP,MAAM;GACN,YAAY;GACZ,cAAc;GACd,QAAQ;GACR,WAAW;GACX,QAAQ;GACR,WAAW;GACX,SAAS;GACV;;;;;CAKD,QAAc;AACZ,OAAK,eAAe;AACpB,OAAK,eAAe;AACpB,OAAK,kBAAkB;AAEvB,OAAK,MAAM,OAAO,OAAO,KAAK,KAAK,SAAS,CAC1C,MAAK,SAAS,OAAO;;;;;CAOzB,IAAI,cAAsB;AACxB,SAAO,KAAK;;;;;CAMd,uBAA6B;AAC3B,OAAK;;;;;CAMP,QAAQ,OAA4B,IAAkB;AACpD,OAAK,SAAS,UAAU;;;;;CAM1B,KAAQ,OAA4B,IAAgB;EAClD,MAAM,QAAQ,YAAY,KAAK;EAC/B,MAAM,SAAS,IAAI;AACnB,OAAK,SAAS,UAAU,YAAY,KAAK,GAAG;AAC5C,SAAO;;;;;CAMT,MAAM,UACJ,OACA,IACY;EACZ,MAAM,QAAQ,YAAY,KAAK;EAC/B,MAAM,SAAS,MAAM,IAAI;AACzB,OAAK,SAAS,UAAU,YAAY,KAAK,GAAG;AAC5C,SAAO;;;;;CAMT,gBAAgB,aAAqB,yBAAkC;EACrE,MAAM,MAAM,YAAY,KAAK;AAC7B,MAAI,MAAM,KAAK,eAAe,YAAY;AACxC,QAAK,eAAe;AACpB,UAAO;;AAET,SAAO;;;;;CAMT,sBACE,WAAmB,4BACV;AACT,MAAI,KAAK,eAAe,KAAK,mBAAmB,UAAU;AACxD,QAAK,kBAAkB,KAAK;AAC5B,UAAO;;AAET,SAAO;;;;;CAMT,cAAc,YAAoB,GAAY;AAC5C,SAAO,KAAK,eAAe;;;;;CAM7B,UAAkB;EAChB,MAAM,IAAI,KAAK;EACf,MAAMA,QAAkB,EAAE;AAE1B,MAAI,EAAE,QAAQ,EAAG,OAAM,KAAK,SAAS,EAAE,MAAM,QAAQ,EAAE,CAAC,IAAI;AAC5D,MAAI,EAAE,OAAO,EAAG,OAAM,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,CAAC,IAAI;AACzD,MAAI,EAAE,aAAa,EAAG,OAAM,KAAK,cAAc,EAAE,WAAW,QAAQ,EAAE,CAAC,IAAI;AAC3E,MAAI,EAAE,eAAe,EACnB,OAAM,KAAK,gBAAgB,EAAE,aAAa,QAAQ,EAAE,CAAC,IAAI;AAC3D,MAAI,EAAE,SAAS,EAAG,OAAM,KAAK,UAAU,EAAE,OAAO,QAAQ,EAAE,CAAC,IAAI;AAC/D,MAAI,EAAE,YAAY,EAAG,OAAM,KAAK,aAAa,EAAE,UAAU,QAAQ,EAAE,CAAC,IAAI;AACxE,MAAI,EAAE,SAAS,EAAG,OAAM,KAAK,UAAU,EAAE,OAAO,QAAQ,EAAE,CAAC,IAAI;AAC/D,MAAI,EAAE,YAAY,EAAG,OAAM,KAAK,aAAa,EAAE,UAAU,QAAQ,EAAE,CAAC,IAAI;AACxE,MAAI,EAAE,UAAU,EAAG,OAAM,KAAK,WAAW,EAAE,QAAQ,QAAQ,EAAE,CAAC,IAAI;AAElE,SAAO,MAAM,KAAK,KAAK;;;;;CAMzB,aAAsC;AACpC,SAAO,EAAE,GAAG,KAAK,UAAU;;;;;;;AAQ/B,MAAa,kBAAkB,IAAI,gBAAgB"}

package/dist/preview/RenderStats.js

@@ -0,0 +1,85 @@
+//#region src/preview/RenderStats.ts
+/**
+* RenderStats collects performance data from the rendering system.
+*
+* Usage:
+* ```typescript
+* const stats = new RenderStats(adaptiveTracker);
+*
+* // In render loop (always call this)
+* stats.recordFrame(renderTime, timestamp, isAtRest);
+*
+* // In display (only when visible)
+* const data = stats.getStats(renderWidth, renderHeight, resolutionScale);
+* ```
+*/
+var RenderStats = class {
+	constructor(adaptiveTracker) {
+		this.renderTimes = [];
+		this.frameIntervals = [];
+		this.lastFrameTime = 0;
+		this.ROLLING_WINDOW_SIZE = 30;
+		this.TARGET_FRAME_TIME_MS = 33.33;
+		this.adaptiveTracker = adaptiveTracker;
+	}
+	/**
+	* Record a completed frame render.
+	* Call this from the render loop after each frame completes.
+	*
+	* @param renderTime - Time spent rendering this frame (ms)
+	* @param timestamp - Current timestamp from performance.now() or rAF
+	* @param isAtRest - Whether the system is at rest (not playing/scrubbing)
+	*/
+	recordFrame(renderTime, timestamp, isAtRest) {
+		this.renderTimes.push(renderTime);
+		if (this.renderTimes.length > this.ROLLING_WINDOW_SIZE) this.renderTimes.shift();
+		if (this.lastFrameTime > 0) {
+			const interval = timestamp - this.lastFrameTime;
+			this.frameIntervals.push(interval);
+			if (this.frameIntervals.length > this.ROLLING_WINDOW_SIZE) this.frameIntervals.shift();
+		}
+		this.lastFrameTime = timestamp;
+		if (!isAtRest) this.adaptiveTracker.recordFrame(renderTime, timestamp);
+	}
+	/**
+	* Get current statistics for display.
+	*
+	* @param renderWidth - Current render width in pixels
+	* @param renderHeight - Current render height in pixels
+	* @param resolutionScale - Current resolution scale (0-1), or null if not applicable
+	* @returns Current playback statistics
+	*/
+	getStats(renderWidth, renderHeight, resolutionScale = null) {
+		const avgRenderTime = this.renderTimes.length > 0 ? this.renderTimes.reduce((a, b) => a + b, 0) / this.renderTimes.length : null;
+		const avgFrameInterval = this.frameIntervals.length > 0 ? this.frameIntervals.reduce((a, b) => a + b, 0) / this.frameIntervals.length : 16.67;
+		const fps = avgFrameInterval > 0 ? 1e3 / avgFrameInterval : 0;
+		const headroom = avgRenderTime !== null ? this.TARGET_FRAME_TIME_MS - avgRenderTime : null;
+		const trackerStats = this.adaptiveTracker.getStats();
+		return {
+			fps,
+			avgRenderTime,
+			headroom,
+			pressureState: trackerStats.pressureState,
+			pressureHistory: trackerStats.pressureHistory,
+			renderWidth,
+			renderHeight,
+			resolutionScale,
+			samplesAtCurrentScale: trackerStats.samplesAtCurrentScale,
+			canScaleUp: trackerStats.canScaleUp,
+			canScaleDown: trackerStats.canScaleDown
+		};
+	}
+	/**
+	* Reset all collected statistics.
+	* Useful when switching modes or starting a new session.
+	*/
+	reset() {
+		this.renderTimes = [];
+		this.frameIntervals = [];
+		this.lastFrameTime = 0;
+	}
+};
+
+//#endregion
+export { RenderStats };
+//# sourceMappingURL=RenderStats.js.map

package/dist/preview/RenderStats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderStats.js","names":[],"sources":["../../src/preview/RenderStats.ts"],"sourcesContent":["/**\n * RenderStats: Always-on performance statistics collection\n *\n * This class continuously collects rendering performance data regardless of\n * whether stats are being displayed. It acts as a persistent data store that\n * the UI can read from at any time.\n *\n * Key principles:\n * - Collection is always active (not tied to display visibility)\n * - Data persists across mode changes and zoom operations\n * - Display is orthogonal to collection\n */\n\nimport type { AdaptiveResolutionTracker } from \"./AdaptiveResolutionTracker.js\";\n\n/**\n * Playback statistics for display.\n */\nexport interface PlaybackStats {\n  fps: number;\n  avgRenderTime: number | null;\n  headroom: number | null;\n  pressureState: string;\n  pressureHistory: string[];\n  renderWidth: number;\n  renderHeight: number;\n  resolutionScale: number | null;\n  samplesAtCurrentScale?: number;\n  canScaleUp?: boolean;\n  canScaleDown?: boolean;\n}\n\n/**\n * RenderStats collects performance data from the rendering system.\n *\n * Usage:\n * ```typescript\n * const stats = new RenderStats(adaptiveTracker);\n *\n * // In render loop (always call this)\n * stats.recordFrame(renderTime, timestamp, isAtRest);\n *\n * // In display (only when visible)\n * const data = stats.getStats(renderWidth, renderHeight, resolutionScale);\n * ```\n */\nexport class RenderStats {\n  private adaptiveTracker: AdaptiveResolutionTracker;\n\n  // Frame timing data\n  private renderTimes: number[] = [];\n  private frameIntervals: number[] = [];\n  private lastFrameTime = 0;\n\n  private readonly ROLLING_WINDOW_SIZE = 30; // ~1 second at 30fps\n  private readonly TARGET_FRAME_TIME_MS = 33.33; // 30fps target\n\n  constructor(adaptiveTracker: AdaptiveResolutionTracker) {\n    this.adaptiveTracker = adaptiveTracker;\n  }\n\n  /**\n   * Record a completed frame render.\n   * Call this from the render loop after each frame completes.\n   *\n   * @param renderTime - Time spent rendering this frame (ms)\n   * @param timestamp - Current timestamp from performance.now() or rAF\n   * @param isAtRest - Whether the system is at rest (not playing/scrubbing)\n   */\n  recordFrame(renderTime: number, timestamp: number, isAtRest: boolean): void {\n    // Track render times for averaging\n    this.renderTimes.push(renderTime);\n    if (this.renderTimes.length > this.ROLLING_WINDOW_SIZE) {\n      this.renderTimes.shift();\n    }\n\n    // Track frame intervals for FPS calculation\n    if (this.lastFrameTime > 0) {\n      const interval = timestamp - this.lastFrameTime;\n      this.frameIntervals.push(interval);\n      if (this.frameIntervals.length > this.ROLLING_WINDOW_SIZE) {\n        this.frameIntervals.shift();\n      }\n    }\n    this.lastFrameTime = timestamp;\n\n    // Update adaptive tracker (only when in motion)\n    if (!isAtRest) {\n      this.adaptiveTracker.recordFrame(renderTime, timestamp);\n    }\n  }\n\n  /**\n   * Get current statistics for display.\n   *\n   * @param renderWidth - Current render width in pixels\n   * @param renderHeight - Current render height in pixels\n   * @param resolutionScale - Current resolution scale (0-1), or null if not applicable\n   * @returns Current playback statistics\n   */\n  getStats(\n    renderWidth: number,\n    renderHeight: number,\n    resolutionScale: number | null = null,\n  ): PlaybackStats {\n    // Calculate average render time\n    const avgRenderTime =\n      this.renderTimes.length > 0\n        ? this.renderTimes.reduce((a, b) => a + b, 0) / this.renderTimes.length\n        : null;\n\n    // Calculate FPS from frame intervals\n    const avgFrameInterval =\n      this.frameIntervals.length > 0\n        ? this.frameIntervals.reduce((a, b) => a + b, 0) /\n          this.frameIntervals.length\n        : 16.67;\n    const fps = avgFrameInterval > 0 ? 1000 / avgFrameInterval : 0;\n\n    // Calculate headroom (positive = faster than target, negative = slower)\n    const headroom =\n      avgRenderTime !== null ? this.TARGET_FRAME_TIME_MS - avgRenderTime : null;\n\n    // Get adaptive tracker stats\n    const trackerStats = this.adaptiveTracker.getStats();\n\n    return {\n      fps,\n      avgRenderTime,\n      headroom,\n      pressureState: trackerStats.pressureState,\n      pressureHistory: trackerStats.pressureHistory,\n      renderWidth,\n      renderHeight,\n      resolutionScale,\n      samplesAtCurrentScale: trackerStats.samplesAtCurrentScale,\n      canScaleUp: trackerStats.canScaleUp,\n      canScaleDown: trackerStats.canScaleDown,\n    };\n  }\n\n  /**\n   * Reset all collected statistics.\n   * Useful when switching modes or starting a new session.\n   */\n  reset(): void {\n    this.renderTimes = [];\n    this.frameIntervals = [];\n    this.lastFrameTime = 0;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AA8CA,IAAa,cAAb,MAAyB;CAWvB,YAAY,iBAA4C;qBAPxB,EAAE;wBACC,EAAE;uBACb;6BAEe;8BACC;AAGtC,OAAK,kBAAkB;;;;;;;;;;CAWzB,YAAY,YAAoB,WAAmB,UAAyB;AAE1E,OAAK,YAAY,KAAK,WAAW;AACjC,MAAI,KAAK,YAAY,SAAS,KAAK,oBACjC,MAAK,YAAY,OAAO;AAI1B,MAAI,KAAK,gBAAgB,GAAG;GAC1B,MAAM,WAAW,YAAY,KAAK;AAClC,QAAK,eAAe,KAAK,SAAS;AAClC,OAAI,KAAK,eAAe,SAAS,KAAK,oBACpC,MAAK,eAAe,OAAO;;AAG/B,OAAK,gBAAgB;AAGrB,MAAI,CAAC,SACH,MAAK,gBAAgB,YAAY,YAAY,UAAU;;;;;;;;;;CAY3D,SACE,aACA,cACA,kBAAiC,MAClB;EAEf,MAAM,gBACJ,KAAK,YAAY,SAAS,IACtB,KAAK,YAAY,QAAQ,GAAG,MAAM,IAAI,GAAG,EAAE,GAAG,KAAK,YAAY,SAC/D;EAGN,MAAM,mBACJ,KAAK,eAAe,SAAS,IACzB,KAAK,eAAe,QAAQ,GAAG,MAAM,IAAI,GAAG,EAAE,GAC9C,KAAK,eAAe,SACpB;EACN,MAAM,MAAM,mBAAmB,IAAI,MAAO,mBAAmB;EAG7D,MAAM,WACJ,kBAAkB,OAAO,KAAK,uBAAuB,gBAAgB;EAGvE,MAAM,eAAe,KAAK,gBAAgB,UAAU;AAEpD,SAAO;GACL;GACA;GACA;GACA,eAAe,aAAa;GAC5B,iBAAiB,aAAa;GAC9B;GACA;GACA;GACA,uBAAuB,aAAa;GACpC,YAAY,aAAa;GACzB,cAAc,aAAa;GAC5B;;;;;;CAOH,QAAc;AACZ,OAAK,cAAc,EAAE;AACrB,OAAK,iBAAiB,EAAE;AACxB,OAAK,gBAAgB"}