@zseven-w/pen-renderer 0.6.0 → 0.7.1

package/src/image-loader.ts

@@ -1,4 +1,16 @@
-import type { CanvasKit, Image as SkImage } from 'canvaskit-wasm'
+import type { CanvasKit, Image as SkImage } from 'canvaskit-wasm';
+
+const MAX_IMAGE_DIMENSION = 4096;
+const MAX_IMAGE_PIXELS = MAX_IMAGE_DIMENSION * MAX_IMAGE_DIMENSION;
+
+export interface ResolvedImageSource {
+  cacheKey: string;
+  loadUrl: string | null;
+}
+
+export interface ImageLoadStatus {
+  state: 'loading' | 'loaded' | 'missing' | 'error';
+}
 
 /**
  * Async image loader for CanvasKit. Loads images via browser's native Image
@@ -6,88 +18,163 @@ import type { CanvasKit, Image as SkImage } from 'canvaskit-wasm'
  * then converts to CanvasKit Image for GPU rendering.
  */
 export class SkiaImageLoader {
-  private ck: CanvasKit
-  private cache = new Map<string, SkImage | null>()
-  private loading = new Set<string>()
-  private onLoaded: (() => void) | null = null
+  private ck: CanvasKit;
+  private cache = new Map<string, SkImage | null>();
+  private loading = new Set<string>();
+  /** In-flight load promises (separate from `loading` URL set, used for flushPending) */
+  private pendingPromises = new Set<Promise<unknown>>();
+  private status = new Map<string, ImageLoadStatus>();
+  private onLoaded: (() => void) | null = null;
+  private sourceResolver: (src: string) => ResolvedImageSource = (src) => ({
+    cacheKey: src,
+    loadUrl: src,
+  });
 
   constructor(ck: CanvasKit) {
-    this.ck = ck
+    this.ck = ck;
   }
 
   /** Set callback to trigger re-render when an image finishes loading. */
   setOnLoaded(cb: () => void) {
-    this.onLoaded = cb
+    this.onLoaded = cb;
+  }
+
+  setSourceResolver(resolver: (src: string) => ResolvedImageSource) {
+    this.sourceResolver = resolver;
   }
 
   /** Get a cached image, or null if not loaded / failed. Returns undefined if not yet requested. */
   get(src: string): SkImage | null | undefined {
-    return this.cache.get(src)
+    const resolved = this.sourceResolver(src);
+    return this.cache.get(resolved.cacheKey);
+  }
+
+  getStatus(src: string): ImageLoadStatus | undefined {
+    const resolved = this.sourceResolver(src);
+    return this.status.get(resolved.cacheKey);
   }
 
   /** Start loading an image if not already cached or in progress. */
   request(src: string) {
-    if (this.cache.has(src) || this.loading.has(src)) return
-    this.loading.add(src)
-    this.loadAsync(src)
+    const resolved = this.sourceResolver(src);
+    if (this.cache.has(resolved.cacheKey) || this.loading.has(resolved.cacheKey)) return;
+
+    if (!resolved.loadUrl) {
+      this.cache.set(resolved.cacheKey, null);
+      this.status.set(resolved.cacheKey, { state: 'missing' });
+      this.onLoaded?.();
+      return;
+    }
+
+    this.loading.add(resolved.cacheKey);
+    this.status.set(resolved.cacheKey, { state: 'loading' });
+    const pending = this.loadAsync(resolved);
+    this.pendingPromises.add(pending);
+    pending.finally(() => this.pendingPromises.delete(pending));
+  }
+
+  /** Number of in-flight image load promises. */
+  pendingCount(): number {
+    return this.pendingPromises.size;
+  }
+
+  /**
+   * Wait for every currently pending image load to settle.
+   * Used by SkiaEngine.waitForSettled to coordinate readback timing.
+   */
+  async flushPending(): Promise<void> {
+    const snapshot = Array.from(this.pendingPromises);
+    await Promise.all(snapshot.map((p) => p.catch(() => undefined)));
   }
 
   dispose() {
     for (const img of this.cache.values()) {
-      img?.delete()
+      img?.delete();
     }
-    this.cache.clear()
-    this.loading.clear()
+    this.cache.clear();
+    this.loading.clear();
+    this.pendingPromises.clear();
+    this.status.clear();
   }
 
-  private async loadAsync(src: string) {
+  private async loadAsync(source: ResolvedImageSource) {
     try {
       // Use browser Image element — supports all browser-supported formats
-      const htmlImg = await this.loadHtmlImage(src)
-      const skImg = this.htmlImageToSkia(htmlImg)
-      this.cache.set(src, skImg)
-      this.loading.delete(src)
-      this.onLoaded?.()
+      const htmlImg = await this.loadHtmlImage(source.loadUrl!);
+      const skImg = this.htmlImageToSkia(htmlImg);
+      this.cache.set(source.cacheKey, skImg);
+      this.loading.delete(source.cacheKey);
+      this.status.set(source.cacheKey, { state: skImg ? 'loaded' : 'error' });
+      this.onLoaded?.();
     } catch (e) {
-      console.warn('Failed to load image:', src.slice(0, 80), e)
-      this.cache.set(src, null)
-      this.loading.delete(src)
+      console.warn('Failed to load image:', source.loadUrl?.slice(0, 80), e);
+      this.cache.set(source.cacheKey, null);
+      this.loading.delete(source.cacheKey);
+      this.status.set(source.cacheKey, { state: 'error' });
+      this.onLoaded?.();
     }
   }
 
   private loadHtmlImage(src: string): Promise<HTMLImageElement> {
     return new Promise((resolve, reject) => {
-      const img = new Image()
-      img.crossOrigin = 'anonymous'
-      img.onload = () => resolve(img)
-      img.onerror = (e) => reject(new Error(`Image load failed: ${e}`))
-      img.src = src
-    })
+      const img = new Image();
+      if (/^https?:\/\//i.test(src)) {
+        img.crossOrigin = 'anonymous';
+      }
+      img.onload = () => resolve(img);
+      img.onerror = (e) => reject(new Error(`Image load failed: ${e}`));
+      img.src = src;
+    });
   }
 
   /** Rasterize an HTML Image to Canvas 2D, then convert to CanvasKit Image. */
   private htmlImageToSkia(htmlImg: HTMLImageElement): SkImage | null {
-    const w = htmlImg.naturalWidth || htmlImg.width
-    const h = htmlImg.naturalHeight || htmlImg.height
-    if (w <= 0 || h <= 0) return null
-
-    const canvas = document.createElement('canvas')
-    canvas.width = w
-    canvas.height = h
-    const ctx = canvas.getContext('2d')!
-    ctx.drawImage(htmlImg, 0, 0, w, h)
-    const imageData = ctx.getImageData(0, 0, w, h)
-
-    return this.ck.MakeImage(
-      {
-        width: w,
-        height: h,
-        alphaType: this.ck.AlphaType.Unpremul,
-        colorType: this.ck.ColorType.RGBA_8888,
-        colorSpace: this.ck.ColorSpace.SRGB,
-      },
-      imageData.data,
-      w * 4,
-    ) ?? null
+    const sourceW = htmlImg.naturalWidth || htmlImg.width;
+    const sourceH = htmlImg.naturalHeight || htmlImg.height;
+    if (sourceW <= 0 || sourceH <= 0) return null;
+
+    const { width, height } = this.getSafeRasterSize(sourceW, sourceH);
+
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return null;
+
+    ctx.imageSmoothingEnabled = width !== sourceW || height !== sourceH;
+    ctx.drawImage(htmlImg, 0, 0, width, height);
+    const imageData = ctx.getImageData(0, 0, width, height);
+
+    return (
+      this.ck.MakeImage(
+        {
+          width,
+          height,
+          alphaType: this.ck.AlphaType.Unpremul,
+          colorType: this.ck.ColorType.RGBA_8888,
+          colorSpace: this.ck.ColorSpace.SRGB,
+        },
+        imageData.data,
+        width * 4,
+      ) ?? null
+    );
+  }
+
+  private getSafeRasterSize(sourceW: number, sourceH: number): { width: number; height: number } {
+    let scale = 1;
+    const maxDimension = Math.max(sourceW, sourceH);
+    if (maxDimension > MAX_IMAGE_DIMENSION) {
+      scale = Math.min(scale, MAX_IMAGE_DIMENSION / maxDimension);
+    }
+
+    const totalPixels = sourceW * sourceH;
+    if (totalPixels > MAX_IMAGE_PIXELS) {
+      scale = Math.min(scale, Math.sqrt(MAX_IMAGE_PIXELS / totalPixels));
+    }
+
+    return {
+      width: Math.max(1, Math.round(sourceW * scale)),
+      height: Math.max(1, Math.round(sourceH * scale)),
+    };
   }
 }

package/src/index.ts

@@ -14,19 +14,20 @@
  */
 
 // ---- Primary API ----
-export { loadCanvasKit, getCanvasKit } from './init.js'
-export { PenRenderer } from './renderer.js'
+export { loadCanvasKit, getCanvasKit } from './init.js';
+export type { LoadCanvasKitOptions } from './init.js';
+export { PenRenderer } from './renderer.js';
 
 // ---- Types ----
-export type { RenderNode, ViewportState, PenRendererOptions, IconLookupFn } from './types.js'
+export type { RenderNode, ViewportState, PenRendererOptions, IconLookupFn } from './types.js';
 
 // ---- Low-level utilities (for apps/web editor re-use) ----
-export { SkiaNodeRenderer } from './node-renderer.js'
-export { SkiaTextRenderer } from './text-renderer.js'
-export { SkiaFontManager, BUNDLED_FONT_FAMILIES } from './font-manager.js'
-export type { FontManagerOptions } from './font-manager.js'
-export { SkiaImageLoader } from './image-loader.js'
-export { SpatialIndex } from './spatial-index.js'
+export { SkiaNodeRenderer } from './node-renderer.js';
+export { SkiaTextRenderer } from './text-renderer.js';
+export { SkiaFontManager, BUNDLED_FONT_FAMILIES } from './font-manager.js';
+export type { FontManagerOptions } from './font-manager.js';
+export { SkiaImageLoader } from './image-loader.js';
+export { SpatialIndex } from './spatial-index.js';
 export {
   flattenToRenderNodes,
   resolveRefs,
@@ -34,7 +35,7 @@ export {
   premeasureTextHeights,
   collectReusableIds,
   collectInstanceIds,
-} from './document-flattener.js'
+} from './document-flattener.js';
 export {
   viewportMatrix,
   screenToScene,
@@ -42,7 +43,7 @@ export {
   zoomToPoint,
   getViewportBounds,
   isRectInViewport,
-} from './viewport.js'
+} from './viewport.js';
 export {
   parseColor,
   cornerRadiusValue,
@@ -52,9 +53,9 @@ export {
   resolveStrokeWidth,
   wrapLine,
   cssFontFamily,
-} from './paint-utils.js'
-export {
-  sanitizeSvgPath,
-  hasInvalidNumbers,
-  tryManualPathParse,
-} from './path-utils.js'
+} from './paint-utils.js';
+export { sanitizeSvgPath, hasInvalidNumbers, tryManualPathParse } from './path-utils.js';
+
+// ---- Thumbnail helper (Phase 7c) ----
+export { renderNodeThumbnail } from './render-node-thumbnail.js';
+export type { ThumbnailContext } from './render-node-thumbnail.js';

package/src/init.ts

@@ -1,44 +1,73 @@
-import type { CanvasKit } from 'canvaskit-wasm'
+import type { CanvasKit } from 'canvaskit-wasm';
 
-let ckInstance: CanvasKit | null = null
-let ckPromise: Promise<CanvasKit> | null = null
+let ckInstance: CanvasKit | null = null;
+let ckPromise: Promise<CanvasKit> | null = null;
+
+export interface LoadCanvasKitOptions {
+  locateFile?: string | ((file: string) => string);
+  onProgress?: (loaded: number, total: number) => void;
+}
 
 /**
  * Load CanvasKit WASM singleton. Returns the same instance on subsequent calls.
  *
- * @param locateFile - Base path string (e.g. '/canvaskit/') or a function
- *   `(file: string) => string` that resolves WASM file URLs. Defaults to '/canvaskit/'.
+ * @param locateFileOrOptions - Base path string (e.g. '/canvaskit/'), a resolver
+ *   function `(file: string) => string`, or a `LoadCanvasKitOptions` object.
+ *   Defaults to '/canvaskit/'.
  */
 export async function loadCanvasKit(
-  locateFile?: string | ((file: string) => string),
+  locateFileOrOptions?: string | ((file: string) => string) | LoadCanvasKitOptions,
 ): Promise<CanvasKit> {
-  if (ckInstance) return ckInstance
-  if (ckPromise) return ckPromise
+  if (ckInstance) return ckInstance;
+  if (ckPromise) return ckPromise;
+
+  let resolver: (file: string) => string;
+  let onProgress: ((loaded: number, total: number) => void) | undefined;
 
-  const resolver: (file: string) => string = typeof locateFile === 'function'
-    ? locateFile
-    : (file: string) => `${locateFile ?? '/canvaskit/'}${file}`
+  if (
+    typeof locateFileOrOptions === 'object' &&
+    locateFileOrOptions !== null &&
+    !('call' in locateFileOrOptions)
+  ) {
+    const opts = locateFileOrOptions as LoadCanvasKitOptions;
+    resolver =
+      typeof opts.locateFile === 'function'
+        ? opts.locateFile
+        : (file: string) => `${opts.locateFile ?? '/canvaskit/'}${file}`;
+    onProgress = opts.onProgress;
+  } else {
+    const locateFile = locateFileOrOptions as string | ((file: string) => string) | undefined;
+    resolver =
+      typeof locateFile === 'function'
+        ? locateFile
+        : (file: string) => `${locateFile ?? '/canvaskit/'}${file}`;
+  }
 
   ckPromise = (async () => {
     // canvaskit-wasm is a CJS module (module.exports = CanvasKitInit).
     // Depending on bundler interop, the init function may be on .default or the module itself.
-    const mod = await import('canvaskit-wasm')
-    const CanvasKitInit = typeof mod.default === 'function'
-      ? mod.default
-      : (mod as unknown as (opts?: { locateFile?: (file: string) => string }) => Promise<CanvasKit>)
+    const mod = await import('canvaskit-wasm');
+    const CanvasKitInit =
+      typeof mod.default === 'function'
+        ? mod.default
+        : (mod as unknown as (opts?: {
+            locateFile?: (file: string) => string;
+          }) => Promise<CanvasKit>);
     const ck = await CanvasKitInit({
       locateFile: resolver,
-    })
-    ckInstance = ck
-    return ck
-  })()
+    });
+    ckInstance = ck;
+    // Fire final progress (best effort)
+    onProgress?.(1, 1);
+    return ck;
+  })();
 
-  return ckPromise
+  return ckPromise;
 }
 
 /**
  * Get the already-loaded CanvasKit instance. Returns null if not yet loaded.
  */
 export function getCanvasKit(): CanvasKit | null {
-  return ckInstance
+  return ckInstance;
 }