@editframe/elements 0.37.3-beta → 0.38.1

package/dist/preview/renderTimegroupToCanvas.d.ts

@@ -1,42 +1,144 @@
-import "./rendering/types.js";
-import "./rendering/renderToImage.js";
-import "./rendering/renderToImageNative.js";
-import "../elements/EFTimegroup.js";
+import { EFTimegroup } from "../elements/EFTimegroup.js";
+import { CanvasPreviewOptions, CanvasPreviewResult, CaptureFromCloneOptions, CaptureOptions, ContentReadyMode, GenerateThumbnailsOptions, GeneratedThumbnail, ThumbnailQueue } from "./renderTimegroupToCanvas.types.js";
+import { RenderOptions, RenderResult, Renderer, getEffectiveRenderMode, isCanvas, isImage } from "./renderers.js";
+import { loadImageFromDataUri } from "./rendering/loadImage.js";
+import { clearInlineImageCache, getInlineImageCacheSize } from "./rendering/inlineImages.js";
 
 //#region src/preview/renderTimegroupToCanvas.d.ts
 
 /**
- * Content readiness strategy for capture operations.
- * - "immediate": Capture NOW, skip all waits. May have blank video frames.
- * - "blocking": Wait for video content to be ready. Throws on timeout.
- */
-type ContentReadyMode = "immediate" | "blocking";
-/**
- * Options for capturing a timegroup frame.
- */
-interface CaptureOptions {
-  /** Time to capture at in milliseconds (required) */
-  timeMs: number;
-  /** Scale factor (default: 0.25 for captureTimegroupAtTime) */
-  scale?: number;
-  /** Skip restoring original time after capture (for batch operations) */
-  skipRestore?: boolean;
-  /** Content readiness strategy (default: "immediate") */
-  contentReadyMode?: ContentReadyMode;
-  /** Max wait time for blocking mode before throwing (default: 5000ms) */
-  blockingTimeoutMs?: number;
+ * Error thrown when video content is not ready within the blocking timeout.
+ */
+declare class ContentNotReadyError extends Error {
+  readonly timeMs: number;
+  readonly timeoutMs: number;
+  readonly blankVideos: string[];
+  constructor(timeMs: number, timeoutMs: number, blankVideos: string[]);
 }
 /**
- * Options for batch capture operations, excluding timeMs which is provided per-timestamp.
+ * Module-level render state including caches and reusable objects.
  */
-interface CaptureBatchOptions {
-  /** Scale factor for thumbnails (default: 0.25) */
-  scale?: number;
-  /** Content readiness strategy (default: "immediate") */
-  contentReadyMode?: ContentReadyMode;
-  /** Max wait time for blocking mode before throwing (default: 5000ms) */
-  blockingTimeoutMs?: number;
+interface RenderState {
+  inlineImageCache: Map<string, string>;
+  layoutInitializedCanvases: WeakSet<HTMLCanvasElement>;
+  xmlSerializer: XMLSerializer | null;
+  textEncoder: TextEncoder;
+  metrics: {
+    inlineImageCacheHits: number;
+    inlineImageCacheMisses: number;
+    inlineImageCacheEvictions: number;
+  };
 }
+/**
+ * Get the current render state for testing and debugging.
+ * @returns The module-level render state object
+ */
+declare function getRenderState(): RenderState;
+/**
+ * Get cache metrics for monitoring performance.
+ * @returns Object with cache hit/miss/eviction counts
+ */
+declare function getCacheMetrics(): RenderState["metrics"];
+/**
+ * Reset cache metrics to zero.
+ */
+declare function resetCacheMetrics(): void;
+/**
+ * Reset all module state including profiling counters, caches, and logging flags.
+ * Call at the start of export sessions to ensure clean state.
+ */
+declare function resetRenderState(): void;
+interface WaitForVideoContentResult {
+  ready: boolean;
+  blankVideos: string[];
+}
+/**
+ * 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.
+ */
+declare function waitForVideoContent(timegroup: EFTimegroup, timeMs: number, maxWaitMs: number): Promise<WaitForVideoContentResult>;
+/**
+ * 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 or Image with the rendered frame (both are CanvasImageSource)
+ */
+declare function captureFromClone(renderClone: EFTimegroup, _renderContainer: HTMLElement, options?: CaptureFromCloneOptions): Promise<CanvasImageSource>;
+/**
+ * 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
+ */
+declare function captureTimegroupAtTime(timegroup: EFTimegroup, options: CaptureOptions): Promise<CanvasImageSource>;
+/**
+ * Generate thumbnails using an existing render clone and mutable queue.
+ * The queue can be modified while generation is in progress.
+ *
+ * @param renderClone - Pre-created render clone to use
+ * @param renderContainer - Container for the render clone
+ * @param queue - Mutable queue that provides timestamps
+ * @param options - Capture options (scale, contentReadyMode, etc.)
+ * @yields Objects with { timeMs, canvas } for each captured thumbnail
+ *
+ * @example
+ * ```ts
+ * const queue = new MutableTimestampQueue();
+ * queue.reset([0, 100, 200]);
+ *
+ * for await (const { timeMs, canvas } of generateThumbnailsFromClone(clone, container, queue)) {
+ *   cache.set(timeMs, canvas);
+ *   // Queue can be modified here while generator continues
+ * }
+ * ```
+ */
+declare function generateThumbnailsFromClone(renderClone: EFTimegroup, renderContainer: HTMLElement, queue: ThumbnailQueue, options?: GenerateThumbnailsOptions): AsyncGenerator<GeneratedThumbnail>;
+/**
+ * Generate thumbnails for multiple timestamps efficiently using a single render clone.
+ * This avoids the overhead of creating/destroying a clone for each thumbnail.
+ *
+ * @param timegroup - The timegroup to capture
+ * @param timestamps - Array of timestamps to capture (in milliseconds)
+ * @param options - Capture options (scale, contentReadyMode, etc.)
+ * @param signal - Optional AbortSignal to cancel generation
+ * @yields Objects with { timeMs, canvas } for each captured thumbnail
+ *
+ * @example
+ * ```ts
+ * for await (const { timeMs, canvas } of generateThumbnails(tg, [0, 100, 200])) {
+ *   console.log(`Got thumbnail for ${timeMs}ms`);
+ *   thumbnailCache.set(timeMs, canvas);
+ * }
+ * ```
+ */
+declare function generateThumbnails(timegroup: EFTimegroup, timestamps: number[], options?: GenerateThumbnailsOptions, signal?: AbortSignal): AsyncGenerator<GeneratedThumbnail>;
+/**
+ * Renders a timegroup preview to a canvas using SVG foreignObject.
+ *
+ * Captures the prime timeline's current visual state including DOM changes
+ * from frame tasks (SVG paths, canvas content, text updates, etc.).
+ *
+ * Optimized with:
+ * - Passive clone structure rebuilt each frame from prime's current state
+ * - Temporal bucketing for time-based culling
+ * - RenderContext for canvas pixel caching across frames
+ * - Resolution scaling for performance (renders at lower resolution, CSS upscales)
+ *
+ * @param timegroup - The source timegroup to preview (prime timeline)
+ * @param scaleOrOptions - Scale factor (default 1) or options object
+ * @returns Object with canvas and refresh function
+ */
+declare function renderTimegroupToCanvas(timegroup: EFTimegroup, scaleOrOptions?: number | CanvasPreviewOptions): CanvasPreviewResult;
 //#endregion
-export { CaptureBatchOptions, CaptureOptions, ContentReadyMode };
+export { type CanvasPreviewOptions, type CanvasPreviewResult, type CaptureFromCloneOptions, type CaptureOptions, ContentNotReadyError, type ContentReadyMode, type GenerateThumbnailsOptions, type GeneratedThumbnail, type RenderOptions, type RenderResult, type Renderer, type ThumbnailQueue, captureFromClone, captureTimegroupAtTime, clearInlineImageCache, generateThumbnails, generateThumbnailsFromClone, getCacheMetrics, getEffectiveRenderMode, getInlineImageCacheSize, getRenderState, isCanvas, isImage, loadImageFromDataUri, renderTimegroupToCanvas, resetCacheMetrics, resetRenderState, waitForVideoContent };
 //# sourceMappingURL=renderTimegroupToCanvas.d.ts.map