@meonode/canvas 1.7.2 → 2.0.1

package/dist/esm/canvas/{image.canvas.util.js → image.canvas.js}

@@ -1,5 +1,5 @@
 import { loadImage } from 'skia-canvas';
-import { BoxNode } from './layout.canvas.util.js';
+import { BoxNode } from './layout.canvas.js';
 import { parseBorderRadius, drawRoundedRectPath } from './canvas.helper.js';
 import { promises } from 'fs';
 import { Style } from '../constant/common.const.js';
@@ -21,86 +21,6 @@ function calculateOffsetFromValue(positionValue, availableSpace) {
     console.warn(`[ImageNode] Invalid objectPosition value format: ${value}. Defaulting to 50%.`);
     return availableSpace * 0.5;
 }
-/**
- * A simple LRU cache for resolved `CanvasImage` objects.
- *
- * - Persists across render passes so repeated renders of the same tree don't
- *   re-fetch every image.
- * - Bounded by `maxSize` entries; least-recently-used entries are evicted first.
- * - Call `dispose()` to eagerly release all held images, or rely on the
- *   automatic `process.on('exit')` hook that clears the singleton.
- */
-class ImageLRUCache {
-    map = new Map();
-    maxSize;
-    constructor(maxSize) {
-        this.maxSize = maxSize;
-    }
-    get(key) {
-        const entry = this.map.get(key);
-        if (!entry)
-            return undefined;
-        // Move to end (most-recently used)
-        this.map.delete(key);
-        this.map.set(key, entry);
-        return entry.image;
-    }
-    set(key, image) {
-        // If key already exists, refresh it
-        if (this.map.has(key)) {
-            this.map.delete(key);
-        }
-        // Evict oldest if at capacity
-        while (this.map.size >= this.maxSize) {
-            const oldest = this.map.keys().next().value;
-            this.map.delete(oldest);
-        }
-        this.map.set(key, { image, key });
-    }
-    has(key) {
-        return this.map.has(key);
-    }
-    get size() {
-        return this.map.size;
-    }
-    dispose() {
-        this.map.clear();
-    }
-}
-/** Module-level singleton — lazily created on first render. */
-let _globalImageCache = null;
-const DEFAULT_CACHE_SIZE = 128;
-// Symbol key on process to track hook registration across module reloads (e.g. Jest resetModules)
-const HOOK_KEY = Symbol.for('__meonode_canvas_image_cache_hook__');
-/**
- * Returns the singleton `ImageLRUCache`, creating it on first access.
- * Registers a one-time process cleanup hook to clear the cache
- * so native image buffers are freed when the process shuts down.
- */
-function getImageCache(maxSize = DEFAULT_CACHE_SIZE) {
-    if (!_globalImageCache) {
-        _globalImageCache = new ImageLRUCache(maxSize);
-    }
-    if (!globalThis[HOOK_KEY]) {
-        globalThis[HOOK_KEY] = true;
-        const cleanup = () => {
-            _globalImageCache?.dispose();
-            _globalImageCache = null;
-        };
-        process.once('exit', cleanup);
-        process.once('SIGINT', cleanup);
-        process.once('SIGTERM', cleanup);
-    }
-    return _globalImageCache;
-}
-/**
- * Explicitly disposes the global image cache.
- * Useful in tests or when tearing down the rendering engine.
- */
-function disposeImageCache() {
-    _globalImageCache?.dispose();
-    _globalImageCache = null;
-}
 /**
  * Renders images with configurable sizing, positioning, and effects.
  * Supports object-fit modes, positioning, border radius, and saturation filters.
@@ -120,9 +40,9 @@ class ImageNode extends BoxNode {
             ...props,
         };
     }
-    load(cache) {
+    load(cache, diskCacheKeys) {
         if (!this.loadingPromise) {
-            this.loadingPromise = this._loadImage(cache);
+            this.loadingPromise = this._loadImage(cache, diskCacheKeys);
         }
         return this.loadingPromise;
     }
@@ -130,10 +50,10 @@ class ImageNode extends BoxNode {
      * Fetches and processes the image source into a CanvasImage.
      * Does not touch node state — pure fetch logic.
      *
-     * If `diskCacheKey` is provided, the resolved image buffer is written to the
-     * disk cache at `.cache/files/<diskCacheKey>` (best-effort, fire-and-forget).
+     * If `diskCacheKey` and `diskCacheKeys` are provided, the resolved image buffer
+     * is written to disk and the key is recorded so the caller can clean it up later.
      */
-    async _fetchCanvasImage(diskCacheKey) {
+    async _fetchCanvasImage(diskCacheKey, diskCacheKeys) {
         const { fileTypeFromBuffer, fileTypeFromFile } = await import('file-type');
         let finalSource = this.props.src;
         let isSvg = false;
@@ -192,11 +112,13 @@ class ImageNode extends BoxNode {
             const modifiedSvgString = svgString.replace(/fill="[^"]*"/g, `fill="${this.props.color}"`);
             finalSource = modifiedSvgString !== svgString ? Buffer.from(modifiedSvgString) : contentBuffer;
         }
-        // Write resolved buffer to disk cache (fire-and-forget, non-fatal)
-        if (diskCacheKey) {
+        // Write to disk and track the key so the render owner can clean it up
+        if (diskCacheKey && diskCacheKeys) {
             const cacheBuffer = Buffer.isBuffer(finalSource) ? finalSource : contentBuffer;
-            if (cacheBuffer)
-                writeDiskCache(diskCacheKey, cacheBuffer);
+            if (cacheBuffer) {
+                await writeDiskCache(diskCacheKey, cacheBuffer);
+                diskCacheKeys.add(diskCacheKey);
+            }
         }
         return loadImage(finalSource);
     }
@@ -204,14 +126,15 @@ class ImageNode extends BoxNode {
      * Loads and processes an image.
      *
      * Resolution order:
-     *   1. Persistent LRU cache (cross-render) — instant hit, no I/O.
-     *   2. Disk cache at `.cache/files/<hash>` — survives process restarts.
-     *   3. Per-render dedup cache — avoids duplicate in-flight fetches within a single render.
-     *   4. Fresh fetch via `_fetchCanvasImage()` — writes buffer to disk cache after fetch.
+     *   1. Disk cache at `.cache/files/<hash>` — survives process restarts.
+     *   2. Per-render dedup cache — avoids duplicate in-flight fetches when
+     *      multiple ImageNodes share the same src within one render pass.
+     *   3. Fresh fetch via `_fetchCanvasImage()` — writes buffer to disk cache.
      *
      * Buffer sources use a SHA-256 hash as their cache key (same as string sources).
+     * All resolved images are released when the render completes (no cross-render retention).
      */
-    _loadImage(cache) {
+    _loadImage(cache, diskCacheKeys) {
         if (!this.props.src) {
             const aspectRatioFromProps = typeof this.props.aspectRatio === 'number' && this.props.aspectRatio > 0 ? this.props.aspectRatio : undefined;
             this.node.setAspectRatio(aspectRatioFromProps);
@@ -222,56 +145,36 @@ class ImageNode extends BoxNode {
         return new Promise(resolve => {
             const load = async () => {
                 try {
-                    const lru = getImageCache();
-                    const cacheKey = typeof this.props.src === 'string'
-                        ? this.props.color
-                            ? `${this.props.src}|${this.props.color}`
-                            : this.props.src
-                        : this.props.color
-                            ? `${hashBuffer(this.props.src)}|${this.props.color}`
-                            : hashBuffer(this.props.src);
-                    // 1. Check persistent LRU cache
-                    const cached = lru.get(cacheKey);
-                    if (cached) {
-                        this.loadedImage = cached;
-                        this.naturalWidth = cached.width;
-                        this.naturalHeight = cached.height;
-                        const calculatedAspectRatio = cached.width > 0 && cached.height > 0 ? cached.width / cached.height : undefined;
-                        const finalAspectRatio = typeof this.props.aspectRatio === 'number' && this.props.aspectRatio > 0 ? this.props.aspectRatio : calculatedAspectRatio;
-                        this.node.setAspectRatio(finalAspectRatio);
-                        this.props.onLoad?.();
-                        resolve();
-                        return;
-                    }
-                    // 2. Check disk cache (persists across process restarts)
-                    const diskBuffer = await readDiskCache(cacheKey);
-                    if (diskBuffer) {
-                        const img = await loadImage(diskBuffer);
-                        lru.set(cacheKey, img);
-                        this.loadedImage = img;
-                        this.naturalWidth = img.width;
-                        this.naturalHeight = img.height;
-                        const calculatedAspectRatio = img.width > 0 && img.height > 0 ? img.width / img.height : undefined;
-                        const finalAspectRatio = typeof this.props.aspectRatio === 'number' && this.props.aspectRatio > 0 ? this.props.aspectRatio : calculatedAspectRatio;
-                        this.node.setAspectRatio(finalAspectRatio);
-                        this.props.onLoad?.();
-                        resolve();
-                        return;
+                    const srcHash = typeof this.props.src === 'string' ? hashBuffer(Buffer.from(this.props.src)) : hashBuffer(this.props.src);
+                    const cacheKey = this.props.color ? `${srcHash}|${this.props.color}` : srcHash;
+                    // 1. Disk cache read — only when disk caching is enabled for this render
+                    if (diskCacheKeys) {
+                        const diskBuffer = await readDiskCache(cacheKey);
+                        if (diskBuffer) {
+                            const img = await loadImage(diskBuffer);
+                            this.loadedImage = img;
+                            this.naturalWidth = img.width;
+                            this.naturalHeight = img.height;
+                            const calculatedAspectRatio = img.width > 0 && img.height > 0 ? img.width / img.height : undefined;
+                            const finalAspectRatio = typeof this.props.aspectRatio === 'number' && this.props.aspectRatio > 0 ? this.props.aspectRatio : calculatedAspectRatio;
+                            this.node.setAspectRatio(finalAspectRatio);
+                            this.props.onLoad?.();
+                            resolve();
+                            return;
+                        }
                     }
-                    // 3. Per-render dedup cache or fresh fetch (writes to disk internally)
+                    // 2. Per-render memory dedup cache or fresh fetch
                     let imagePromise;
                     if (cache) {
                         if (!cache.has(cacheKey)) {
-                            cache.set(cacheKey, this._fetchCanvasImage(cacheKey));
+                            cache.set(cacheKey, this._fetchCanvasImage(diskCacheKeys ? cacheKey : undefined, diskCacheKeys));
                         }
                         imagePromise = cache.get(cacheKey);
                     }
                     else {
-                        imagePromise = this._fetchCanvasImage(cacheKey);
+                        imagePromise = this._fetchCanvasImage(diskCacheKeys ? cacheKey : undefined, diskCacheKeys);
                     }
                     const img = await imagePromise;
-                    // 4. Store in persistent LRU cache
-                    lru.set(cacheKey, img);
                     this.loadedImage = img;
                     this.naturalWidth = img.width;
                     this.naturalHeight = img.height;
@@ -452,4 +355,4 @@ const Image = (props) => ({
     props: props,
 });
 
-export { Image, ImageLRUCache, ImageNode, disposeImageCache, getImageCache };
+export { Image, ImageNode };

package/dist/{cjs/canvas/layout.canvas.util.d.ts → esm/canvas/layout.canvas.d.ts}

@@ -119,4 +119,4 @@ export declare class RowNode extends BoxNode {
  * @returns {RowNode} New RowNode instance.
  */
 export declare const Row: ({ children, ...rest }: BoxProps) => CanvasElement;
-//# sourceMappingURL=layout.canvas.util.d.ts.map
+//# sourceMappingURL=layout.canvas.d.ts.map

package/dist/esm/canvas/layout.canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.canvas.d.ts","sourceRoot":"","sources":["../../../src/canvas/layout.canvas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAkB,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAGjG,OAAa,EAAS,IAAI,EAAE,MAAM,4BAA4B,CAAA;AAE9D;;;;GAIG;AACH,qBAAa,OAAO;IAClB;;OAEG;IACH,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAE/B;;OAEG;IACH,IAAI,EAAE,IAAI,CAAA;IAEV;;OAEG;IACH,QAAQ,EAAE,OAAO,EAAE,CAAA;IAEnB;;OAEG;IACH,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAA;IAE3B;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IAEtB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;;OAGG;gBACS,KAAK,GAAE,QAAQ,GAAG,SAAc;IAqB5C;;OAEG;IACI,sBAAsB;IAW7B;;;OAGG;IACH,SAAS,CAAC,sBAAsB,CAAC,WAAW,EAAE,QAAQ,GAAG,SAAS;IAkClE;;OAEG;IACH,SAAS,CAAC,aAAa,IAAI,IAAI;IAI/B;;;;OAIG;IACH,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM;IAanD;;;OAGG;IACI,cAAc,IAAI,OAAO;IAiBhC;;OAEG;IACH,SAAS,CAAC,+BAA+B;IAIzC;;;OAGG;IACH,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,QAAQ;IAqInC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,wBAAwB,EAAE,OAAO,GAAE,MAAU,EAAE,OAAO,GAAE,MAAU;IA+J9E;;;;;;;;OAQG;IACH,SAAS,CAAC,cAAc,CAAC,GAAG,EAAE,wBAAwB,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAoR5G;AAWD;;;;GAIG;AACH,eAAO,MAAM,GAAG,GAAI,uBAAuB,QAAQ,KAAG,aAIpD,CAAA;AAEF;;;GAGG;AACH,qBAAa,UAAW,SAAQ,OAAO;gBACzB,KAAK,GAAE,QAAQ,GAAG,SAAc;CAS7C;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,GAAI,uBAAuB,QAAQ,KAAG,aAIvD,CAAA;AAEF;;;GAGG;AACH,qBAAa,OAAQ,SAAQ,OAAO;gBACtB,KAAK,GAAE,QAAQ,GAAG,SAAc;CAS7C;AAED;;;;GAIG;AACH,eAAO,MAAM,GAAG,GAAI,uBAAuB,QAAQ,KAAG,aAIpD,CAAA"}

package/dist/{cjs/canvas/root.canvas.util.d.ts → esm/canvas/root.canvas.d.ts}

@@ -1,20 +1,25 @@
 import { Canvas } from 'skia-canvas';
-import { ColumnNode, BoxNode } from '../canvas/layout.canvas.util.js';
-import type { BaseProps, RootProps, CanvasElement } from '../canvas/canvas.type.js';
+import { ColumnNode, BoxNode } from '../canvas/layout.canvas.js';
+import type { BaseProps, RootProps, CanvasElement, RootPropsWithWorker, RootPropsWithoutWorker } from '../canvas/canvas.type.js';
 export declare const _clearRegisteredFonts: () => void;
 export interface CanvasEngineConfig {
     /** Run rendering in worker threads to avoid blocking the event loop (default: true) */
     workerMode?: boolean;
     /** Number of worker threads in the pool (default: os.cpus().length - 1) */
     workers?: number;
-    /** Maximum number of resolved images to keep in the persistent LRU cache (default: 128) */
-    imageCacheSize?: number;
 }
 /**
  * Configure the canvas rendering engine.
  * Call this once at application startup before rendering.
+ * @deprecated Pass workerMode and workers directly to Root() props instead.
  */
 export declare function configure(options: CanvasEngineConfig): void;
+/**
+ * Terminate all worker pools and free worker thread resources.
+ * Call this when shutting down a long-running server to clean up immediately.
+ * After calling, you must call configure() again before rendering.
+ */
+export declare function terminate(): void;
 /**
  * Converts a CanvasElement tree into actual BoxNode instances.
  * Used both for non-worker rendering (inline tree building) and inside
@@ -26,6 +31,7 @@ export declare function buildTree(descriptor: CanvasElement): BoxNode;
  * Inherits from ColumnNode to provide vertical layout capabilities.
  */
 export declare class RootNode extends ColumnNode {
+    props: RootProps & BaseProps;
     /** The canvas instance used for rendering */
     private canvas;
     /** The 2D rendering context for the canvas */
@@ -56,10 +62,24 @@ export declare class RootNode extends ColumnNode {
 }
 /**
  * Creates and renders a new root node with the given properties.
- * When worker mode is enabled via configure(), rendering runs in a worker thread
- * and the returned object implements the same toBuffer/toBufferSync interface.
+ * Rendering runs in worker threads by default for non-blocking operation.
+ * @example
+ * // Worker mode (default) - .release() available
+ * const canvas = await Root({ width: 400, children: [...] })
+ * canvas.release() // ✓ OK
+ * @example
+ * // Worker mode explicit - .release() available
+ * const canvas = await Root({ width: 400, workerMode: true, workers: 2 })
+ * canvas.release() // ✓ OK
+ * @example
+ * // Non-worker mode - .release() NOT available, workers not allowed
+ * const canvas = await Root({ width: 400, workerMode: false })
+ * canvas.release() // ✗ TypeScript error
  * @param props Configuration properties for the root node
- * @returns Promise resolving to the rendered Canvas (or WorkerCanvas in worker mode)
+ * @returns Canvas with .release() in worker mode, plain Canvas otherwise
  */
-export declare const Root: (props: RootProps) => Promise<Canvas>;
-//# sourceMappingURL=root.canvas.util.d.ts.map
+export declare function Root(props: RootPropsWithWorker): Promise<Canvas & {
+    release(): void;
+}>;
+export declare function Root(props: RootPropsWithoutWorker): Promise<Canvas>;
+//# sourceMappingURL=root.canvas.d.ts.map

package/dist/esm/canvas/root.canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.canvas.d.ts","sourceRoot":"","sources":["../../../src/canvas/root.canvas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAA8C,MAAM,aAAa,CAAA;AAEhF,OAAO,EAAE,UAAU,EAAE,OAAO,EAAW,MAAM,2BAA2B,CAAA;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAA;AAmB/H,eAAO,MAAM,qBAAqB,YAEjC,CAAA;AAwBD,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,kBAAkB,QAGpD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,SAKxB;AAgMD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO,CAmB5D;AAED;;;GAGG;AACH,qBAAa,QAAS,SAAQ,UAAU;IAC9B,KAAK,EAAE,SAAS,GAAG,SAAS,CAAA;IACpC,6CAA6C;IAC7C,OAAO,CAAC,MAAM,CAAoB;IAClC,8CAA8C;IAC9C,OAAO,CAAC,GAAG,CAAwC;IACnD,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAE9B;;;;OAIG;gBACS,KAAK,EAAE,SAAS,GAAG,SAAS;IAoDxC;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAazB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;CAqDhC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,GAAG;IAAE,OAAO,IAAI,IAAI,CAAA;CAAE,CAAC,CAAA;AACvF,wBAAgB,IAAI,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA"}

package/dist/esm/canvas/{root.canvas.util.js → root.canvas.js}

@@ -1,9 +1,10 @@
 import { FontLibrary, Canvas } from 'skia-canvas';
-import { ColumnNode, RowNode, BoxNode } from './layout.canvas.util.js';
-import { ImageNode, disposeImageCache, getImageCache } from './image.canvas.util.js';
-import { TextNode } from './text.canvas.util.js';
-import { ChartNode } from './chart.canvas.util.js';
-import { GridItemNode, GridNode } from './grid.canvas.util.js';
+import { ColumnNode, RowNode, BoxNode } from './layout.canvas.js';
+import { ImageNode } from './image.canvas.js';
+import { deleteDiskCache } from '../util/disk.cache.js';
+import { TextNode } from './text.canvas.js';
+import { ChartNode } from './chart.canvas.js';
+import { GridItemNode, GridNode } from './grid.canvas.js';
 import { Style } from '../constant/common.const.js';
 import { WorkerPreProcessor } from './canvas.helper.js';
 import * as path from 'node:path';
@@ -14,26 +15,48 @@ import { fileURLToPath } from 'node:url';
 
 /** Registry to track fonts that have already been loaded */
 const registeredFonts = new Map();
-/** Engine configuration */
-let _workerMode = true;
-let _workerPoolSize = Math.max(1, cpus().length - 1);
+/**
+ * FinalizationRegistry to clean up WorkerCanvas instances that were not explicitly released.
+ * This is a safety net — users should still call .release() explicitly.
+ */
+const canvasRegistry = new FinalizationRegistry(heldValue => {
+    // Best-effort cleanup — worker may already be terminated
+    try {
+        // Access workers via a public method or make it accessible
+        // For now, just try to send the message and let errors be caught
+        if (_workerPool) {
+            ;
+            _workerPool.workers?.[heldValue.workerIdx]?.postMessage({ type: 'release', canvasId: heldValue.canvasId });
+        }
+    }
+    catch {
+        // Worker already gone — nothing to clean up
+    }
+});
+/** Engine configuration — legacy support for configure() */
+let _defaultWorkerMode = true;
+let _defaultWorkerPoolSize = Math.max(1, cpus().length - 1);
 let _workerPool = null;
 /**
  * Configure the canvas rendering engine.
  * Call this once at application startup before rendering.
+ * @deprecated Pass workerMode and workers directly to Root() props instead.
  */
 function configure(options) {
     if (options.workerMode !== undefined)
-        _workerMode = options.workerMode;
+        _defaultWorkerMode = options.workerMode;
     if (options.workers !== undefined)
-        _workerPoolSize = options.workers;
-    if (options.imageCacheSize !== undefined) {
-        // Dispose existing cache and create a new one with the specified size
-        disposeImageCache();
-        getImageCache(options.imageCacheSize);
-    }
-    if (_workerMode) {
-        _workerPool = new WorkerPool(_workerPoolSize);
+        _defaultWorkerPoolSize = options.workers;
+}
+/**
+ * Terminate all worker pools and free worker thread resources.
+ * Call this when shutting down a long-running server to clean up immediately.
+ * After calling, you must call configure() again before rendering.
+ */
+function terminate() {
+    if (_workerPool) {
+        _workerPool.terminate();
+        _workerPool = null;
     }
 }
 /**
@@ -55,6 +78,8 @@ class WorkerCanvas {
         this._pool = opts.pool;
         this._workerIdx = opts.workerIdx;
         this._canvasId = opts.canvasId;
+        // Register for finalizer-based cleanup if user forgets to call .release()
+        canvasRegistry.register(this, { workerIdx: opts.workerIdx, canvasId: opts.canvasId }, this);
     }
     _call(method, ...args) {
         return this._pool.callOnCanvas(this._workerIdx, this._canvasId, method, args);
@@ -105,6 +130,8 @@ class WorkerCanvas {
     /** Release the Canvas from worker memory. Call when done with this object. */
     release() {
         this._pool.releaseCanvas(this._workerIdx, this._canvasId);
+        // Unregister from finalizer since we're explicitly cleaning up
+        canvasRegistry.unregister(this);
     }
 }
 /** Worker thread pool — routes render and canvas-call messages */
@@ -295,6 +322,7 @@ class RootNode extends ColumnNode {
      * @returns Promise resolving to the rendered Canvas instance
      */
     async render() {
+        const diskCacheKeys = this.props.useDiskCache ? new Set() : undefined;
         try {
             // Step 1: Load all images with a concurrency limit to avoid overwhelming remote sources.
             // A per-render cache deduplicates identical src+color combinations within this render pass.
@@ -306,7 +334,7 @@ class RootNode extends ColumnNode {
                 const workers = Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
                     while (queue.length > 0) {
                         const node = queue.shift();
-                        await node.load(imageCache);
+                        await node.load(imageCache, diskCacheKeys);
                     }
                 });
                 await Promise.allSettled(workers);
@@ -334,35 +362,26 @@ class RootNode extends ColumnNode {
             return this.canvas;
         }
         finally {
-            // Always clear the persistent image cache after render (success or error)
-            // so resolved CanvasImage references don't outlive the render pass.
-            disposeImageCache();
+            if (diskCacheKeys?.size) {
+                await Promise.allSettled([...diskCacheKeys].map(key => deleteDiskCache(key)));
+            }
         }
     }
 }
-/**
- * Creates and renders a new root node with the given properties.
- * When worker mode is enabled via configure(), rendering runs in a worker thread
- * and the returned object implements the same toBuffer/toBufferSync interface.
- * @param props Configuration properties for the root node
- * @returns Promise resolving to the rendered Canvas (or WorkerCanvas in worker mode)
- */
-const Root = async (props) => {
-    try {
-        if (_workerMode) {
-            if (!_workerPool) {
-                _workerPool = new WorkerPool(_workerPoolSize);
-            }
-            const result = await _workerPool.render(props);
-            return new WorkerCanvas({ ...result, pool: _workerPool });
+async function Root(props) {
+    // Determine worker mode: props override legacy configure()
+    const workerMode = props.workerMode ?? _defaultWorkerMode;
+    const workerPoolSize = props.workers ?? _defaultWorkerPoolSize;
+    if (workerMode) {
+        // Lazy initialize worker pool
+        if (!_workerPool) {
+            _workerPool = new WorkerPool(workerPoolSize);
         }
-        return await new RootNode(props).render();
+        const result = await _workerPool.render(props);
+        return new WorkerCanvas({ ...result, pool: _workerPool });
     }
-    catch (err) {
-        // Ensure cache is cleared even if Root-level orchestration fails
-        disposeImageCache();
-        throw err;
-    }
-};
+    // Non-worker mode — render directly and return Canvas
+    return new RootNode(props).render();
+}
 
-export { Root, RootNode, buildTree, configure };
+export { Root, RootNode, buildTree, configure, terminate };

package/dist/esm/canvas/{text.canvas.util.d.ts → text.canvas.d.ts}

@@ -1,6 +1,6 @@
 import type { TextProps, CanvasElement } from '../canvas/canvas.type.js';
 import { type CanvasRenderingContext2D } from 'skia-canvas';
-import { BoxNode } from '../canvas/layout.canvas.util.js';
+import { BoxNode } from '../canvas/layout.canvas.js';
 /**
  * Node for rendering text content with rich text styling support
  * Supports color and weight variations through HTML-like tags
@@ -162,4 +162,4 @@ export declare class TextNode extends BoxNode {
  * Creates a new TextNode instance with rich text support
  */
 export declare const Text: (text: number | string, props?: TextProps) => CanvasElement;
-//# sourceMappingURL=text.canvas.util.d.ts.map
+//# sourceMappingURL=text.canvas.d.ts.map

package/dist/esm/canvas/text.canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.canvas.d.ts","sourceRoot":"","sources":["../../../src/canvas/text.canvas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAe,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACpF,OAAO,EAAU,KAAK,wBAAwB,EAA2B,MAAM,aAAa,CAAA;AAC5F,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AAGnD;;;GAGG;AACH,qBAAa,QAAS,SAAQ,OAAO;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAwC;IACzE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,kBAAkB,CAAe;IAEjC,KAAK,EAAE,SAAS,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;gBAElC,IAAI,GAAE,MAAM,GAAG,MAAW,EAAE,KAAK,GAAE,SAAc;IAuB7D;;;;;;;;OAQG;WACW,gBAAgB,CAC5B,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,GAAE;QACL,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,UAAU,CAAC,EAAE,SAAS,CAAC,YAAY,CAAC,CAAA;QACpC,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,CAAC,CAAA;QAClC,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,SAAS,CAAC,EAAE,wBAAwB,CAAC,WAAW,CAAC,CAAA;QACjD,YAAY,CAAC,EAAE,wBAAwB,CAAC,cAAc,CAAC,CAAA;KACnD;cAwBW,aAAa,IAAI,IAAI;IAoDxC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,sBAAsB;IA8B9B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,aAAa;IA+ErB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,gBAAgB;IAyBxB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAM7B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IAiCrB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAQjC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,WAAW;IA+NnB;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;IA6KpB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAmErB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;;;;;;;;;;;;OAgBG;cACgB,cAAc,CAAC,GAAG,EAAE,wBAAwB,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAkXrH;AAED;;GAEG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,GAAG,MAAM,EAAE,QAAQ,SAAS,KAAG,aAI9D,CAAA"}

package/dist/esm/canvas/{text.canvas.util.js → text.canvas.js}

@@ -1,5 +1,5 @@
 import { Canvas } from 'skia-canvas';
-import { BoxNode } from './layout.canvas.util.js';
+import { BoxNode } from './layout.canvas.js';
 import { Style } from '../constant/common.const.js';
 
 /**

package/dist/esm/index.d.ts

@@ -1,10 +1,11 @@
 export * from './constant/common.const.js';
 export * from './canvas/canvas.type.js';
-export { Box, Column, Row, type BoxNode } from './canvas/layout.canvas.util.js';
-export { Image, disposeImageCache } from './canvas/image.canvas.util.js';
-export { Text } from './canvas/text.canvas.util.js';
-export { Root, configure } from './canvas/root.canvas.util.js';
-export { GridItem } from './canvas/grid.canvas.util.js';
-export { Grid } from './canvas/grid.canvas.util.js';
-export { Chart } from './canvas/chart.canvas.util.js';
+export { Box, Column, Row, type BoxNode } from './canvas/layout.canvas.js';
+export { Image } from './canvas/image.canvas.js';
+export { Text } from './canvas/text.canvas.js';
+export { Root, configure, terminate } from './canvas/root.canvas.js';
+export { GridItem } from './canvas/grid.canvas.js';
+export { Grid } from './canvas/grid.canvas.js';
+export { Chart } from './canvas/chart.canvas.js';
+export { clearDiskCache } from './util/disk.cache.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AACvC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,MAAM,gCAAgC,CAAA;AAC/E,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACxE,OAAO,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AACvC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,MAAM,2BAA2B,CAAA;AAC1E,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AAC9C,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/esm/index.js

@@ -1,8 +1,9 @@
 export { Border, Style } from './constant/common.const.js';
-export { Box, Column, Row } from './canvas/layout.canvas.util.js';
-export { Image, disposeImageCache } from './canvas/image.canvas.util.js';
-export { Text } from './canvas/text.canvas.util.js';
-export { Root, configure } from './canvas/root.canvas.util.js';
-export { Grid, GridItem } from './canvas/grid.canvas.util.js';
-export { Chart } from './canvas/chart.canvas.util.js';
+export { Box, Column, Row } from './canvas/layout.canvas.js';
+export { Image } from './canvas/image.canvas.js';
+export { Text } from './canvas/text.canvas.js';
+export { Root, configure, terminate } from './canvas/root.canvas.js';
+export { Grid, GridItem } from './canvas/grid.canvas.js';
+export { Chart } from './canvas/chart.canvas.js';
+export { clearDiskCache } from './util/disk.cache.js';
 export * from 'yoga-layout';

package/dist/esm/util/disk.cache.d.ts

@@ -1,4 +1,10 @@
 export declare function hashBuffer(buf: Buffer): string;
 export declare function readDiskCache(key: string): Promise<Buffer | null>;
 export declare function writeDiskCache(key: string, data: Buffer): Promise<void>;
+export declare function deleteDiskCache(key: string): Promise<void>;
+/**
+ * Delete the entire disk cache directory.
+ * Called on process exit to clean up any orphaned cache files.
+ */
+export declare function clearDiskCache(): Promise<void>;
 //# sourceMappingURL=disk.cache.d.ts.map

package/dist/esm/util/disk.cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"disk.cache.d.ts","sourceRoot":"","sources":["../../../src/util/disk.cache.ts"],"names":[],"mappings":"AAaA,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOvE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7E"}
+{"version":3,"file":"disk.cache.d.ts","sourceRoot":"","sources":["../../../src/util/disk.cache.ts"],"names":[],"mappings":"AAaA,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOvE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7E;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAOpD"}

package/dist/esm/util/disk.cache.js

@@ -31,5 +31,42 @@ async function writeDiskCache(key, data) {
         // best-effort — cache write failures are non-fatal
     }
 }
+async function deleteDiskCache(key) {
+    try {
+        await promises.unlink(join(CACHE_DIR, key));
+    }
+    catch {
+        // non-fatal — file may not exist if write failed earlier
+    }
+}
+/**
+ * Delete the entire disk cache directory.
+ * Called on process exit to clean up any orphaned cache files.
+ */
+async function clearDiskCache() {
+    _dirEnsured = false;
+    try {
+        await promises.rm(CACHE_DIR, { recursive: true, force: true });
+    }
+    catch {
+        // non-fatal — directory may not exist
+    }
+}
+// Clean up disk cache on process exit to handle crashes mid-render.
+// Guard prevents re-entry: clearDiskCache() is async, so without this the
+// beforeExit → schedule I/O → idle → beforeExit cycle loops forever.
+let _exitCleanupStarted = false;
+process.on('beforeExit', () => {
+    if (_exitCleanupStarted)
+        return;
+    _exitCleanupStarted = true;
+    void clearDiskCache();
+});
+// Also clean up on SIGINT/SIGTERM for graceful shutdowns
+const cleanupOnExit = () => {
+    clearDiskCache().finally(() => process.exit(0));
+};
+process.on('SIGINT', cleanupOnExit);
+process.on('SIGTERM', cleanupOnExit);
 
-export { hashBuffer, readDiskCache, writeDiskCache };
+export { clearDiskCache, deleteDiskCache, hashBuffer, readDiskCache, writeDiskCache };

package/dist/esm/worker/render.worker.js

@@ -1,5 +1,5 @@
 import { parentPort } from 'worker_threads';
-import { RootNode } from '../canvas/root.canvas.util.js';
+import { RootNode } from '../canvas/root.canvas.js';
 
 /**
  * Worker thread entry point for off-main-thread canvas rendering.