@meonode/canvas 1.5.6 → 1.6.0-beta.2

package/dist/esm/canvas/image.canvas.util.js

@@ -39,23 +39,82 @@ class ImageNode extends BoxNode {
             ...props,
         };
     }
-    load() {
+    load(cache) {
         if (!this.loadingPromise) {
-            this.loadingPromise = this._loadImage();
+            this.loadingPromise = this._loadImage(cache);
         }
         return this.loadingPromise;
     }
     /**
-     * Loads and processes an image from various sources (URL, file path, or Buffer).
-     * Handles SVG color modifications and sets natural dimensions with an aspect ratio.
-     * @returns Promise that resolves when image loading completes
-     * @throws Error if image loading fails
+     * Fetches and processes the image source into a CanvasImage.
+     * Does not touch node state — pure fetch logic.
      */
-    _loadImage() {
-        if (this.loadingPromise)
-            return this.loadingPromise;
-        if (this.loadedImage)
-            return Promise.resolve();
+    async _fetchCanvasImage() {
+        const { fileTypeFromBuffer, fileTypeFromFile } = await import('file-type');
+        let finalSource = this.props.src;
+        let isSvg = false;
+        let contentBuffer = null;
+        let detectedMime;
+        if (typeof this.props.src === 'string') {
+            if (this.props.src.startsWith('http')) {
+                const response = await fetch(this.props.src);
+                if (!response.ok) {
+                    throw new Error(`HTTP error ${response.status} fetching image: ${this.props.src}`);
+                }
+                const imageArrayBuffer = await response.arrayBuffer();
+                contentBuffer = Buffer.from(imageArrayBuffer);
+                finalSource = contentBuffer;
+                const fileTypeResult = await fileTypeFromBuffer(contentBuffer);
+                detectedMime = fileTypeResult?.mime;
+                isSvg = detectedMime === 'image/svg+xml';
+                if ((!detectedMime || detectedMime === 'application/xml') && contentBuffer.toString('utf-8').includes('<svg')) {
+                    isSvg = true;
+                }
+            }
+            else {
+                finalSource = this.props.src;
+                const filePath = this.props.src;
+                try {
+                    const fileTypeResult = await fileTypeFromFile(filePath);
+                    detectedMime = fileTypeResult?.mime;
+                    isSvg = detectedMime === 'image/svg+xml';
+                    if ((!detectedMime || detectedMime === 'application/xml') && filePath.toLowerCase().endsWith('.svg')) {
+                        isSvg = true;
+                    }
+                }
+                catch {
+                    isSvg = filePath.toLowerCase().endsWith('.svg');
+                }
+                if (isSvg && this.props.color) {
+                    try {
+                        contentBuffer = await promises.readFile(filePath);
+                    }
+                    catch {
+                        isSvg = false;
+                        contentBuffer = null;
+                    }
+                }
+            }
+        }
+        else {
+            contentBuffer = this.props.src;
+            finalSource = contentBuffer;
+            const fileTypeResult = await fileTypeFromBuffer(contentBuffer);
+            detectedMime = fileTypeResult?.mime;
+            isSvg = detectedMime === 'image/svg+xml';
+        }
+        if (isSvg && this.props.color && contentBuffer) {
+            const svgString = contentBuffer.toString('utf-8');
+            const modifiedSvgString = svgString.replace(/fill="[^"]*"/g, `fill="${this.props.color}"`);
+            finalSource = modifiedSvgString !== svgString ? Buffer.from(modifiedSvgString) : contentBuffer;
+        }
+        return loadImage(finalSource);
+    }
+    /**
+     * Loads and processes an image, using the render-scoped cache to avoid
+     * re-fetching the same source within a single render pass.
+     */
+    _loadImage(cache) {
         if (!this.props.src) {
             const aspectRatioFromProps = typeof this.props.aspectRatio === 'number' && this.props.aspectRatio > 0 ? this.props.aspectRatio : undefined;
             this.node.setAspectRatio(aspectRatioFromProps);
@@ -65,71 +124,19 @@ class ImageNode extends BoxNode {
         }
         return new Promise(resolve => {
             const load = async () => {
-                const { fileTypeFromBuffer, fileTypeFromFile } = await import('file-type');
-                let finalSource = this.props.src;
-                let isSvg = false;
-                let contentBuffer = null;
-                let detectedMime;
                 try {
-                    if (typeof this.props.src === 'string') {
-                        if (this.props.src.startsWith('http')) {
-                            const response = await fetch(this.props.src);
-                            if (!response.ok) {
-                                throw new Error(`HTTP error ${response.status} fetching image: ${this.props.src}`);
-                            }
-                            const imageArrayBuffer = await response.arrayBuffer();
-                            contentBuffer = Buffer.from(imageArrayBuffer);
-                            finalSource = contentBuffer;
-                            const fileTypeResult = await fileTypeFromBuffer(contentBuffer);
-                            detectedMime = fileTypeResult?.mime;
-                            isSvg = detectedMime === 'image/svg+xml';
-                            if ((!detectedMime || detectedMime === 'application/xml') && contentBuffer.toString('utf-8').includes('<svg')) {
-                                isSvg = true;
-                            }
-                        }
-                        else {
-                            finalSource = this.props.src;
-                            const filePath = this.props.src;
-                            try {
-                                const fileTypeResult = await fileTypeFromFile(filePath);
-                                detectedMime = fileTypeResult?.mime;
-                                isSvg = detectedMime === 'image/svg+xml';
-                                if ((!detectedMime || detectedMime === 'application/xml') && filePath.toLowerCase().endsWith('.svg')) {
-                                    isSvg = true;
-                                }
-                            }
-                            catch {
-                                isSvg = filePath.toLowerCase().endsWith('.svg');
-                            }
-                            if (isSvg && this.props.color) {
-                                try {
-                                    contentBuffer = await promises.readFile(filePath);
-                                }
-                                catch {
-                                    isSvg = false;
-                                    contentBuffer = null;
-                                }
-                            }
+                    let imagePromise;
+                    if (cache && typeof this.props.src === 'string') {
+                        const cacheKey = this.props.color ? `${this.props.src}|${this.props.color}` : this.props.src;
+                        if (!cache.has(cacheKey)) {
+                            cache.set(cacheKey, this._fetchCanvasImage());
                         }
+                        imagePromise = cache.get(cacheKey);
                     }
                     else {
-                        contentBuffer = this.props.src;
-                        finalSource = contentBuffer;
-                        const fileTypeResult = await fileTypeFromBuffer(contentBuffer);
-                        detectedMime = fileTypeResult?.mime;
-                        isSvg = detectedMime === 'image/svg+xml';
-                    }
-                    if (isSvg && this.props.color && contentBuffer) {
-                        const svgString = contentBuffer.toString('utf-8');
-                        const modifiedSvgString = svgString.replace(/fill="[^"]*"/g, `fill="${this.props.color}"`);
-                        if (modifiedSvgString !== svgString) {
-                            finalSource = Buffer.from(modifiedSvgString);
-                        }
-                        else {
-                            finalSource = contentBuffer;
-                        }
+                        imagePromise = this._fetchCanvasImage();
                     }
-                    const img = await loadImage(finalSource);
+                    const img = await imagePromise;
                     this.loadedImage = img;
                     this.naturalWidth = img.width;
                     this.naturalHeight = img.height;
@@ -305,6 +312,9 @@ class ImageNode extends BoxNode {
 /**
  * Factory function to create ImageNode instances
  */
-const Image = (props) => new ImageNode(props);
+const Image = (props) => ({
+    __type: 'Image',
+    props: props,
+});
 
 export { Image, ImageNode };

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

@@ -1,5 +1,5 @@
 import { type CanvasRenderingContext2D } from 'skia-canvas';
-import type { BaseProps, BoxProps } from '../canvas/canvas.type.js';
+import type { BaseProps, BoxProps, NodeDescriptor } from '../canvas/canvas.type.js';
 import { Node } from '../constant/common.const.js';
 /**
  * @class BoxNode
@@ -92,7 +92,7 @@ export declare class BoxNode {
  * @param {BoxProps} props Box properties and configuration.
  * @returns {BoxNode} New BoxNode instance.
  */
-export declare const Box: (props: BoxProps) => BoxNode;
+export declare const Box: ({ children, ...rest }: BoxProps) => NodeDescriptor;
 /**
  * @class ColumnNode
  * Node class for vertical column layout
@@ -105,7 +105,7 @@ export declare class ColumnNode extends BoxNode {
  * @param {BoxProps} props Column properties and configuration.
  * @returns {ColumnNode} New ColumnNode instance.
  */
-export declare const Column: (props: BoxProps) => ColumnNode;
+export declare const Column: ({ children, ...rest }: BoxProps) => NodeDescriptor;
 /**
  * @class RowNode
  * @classdesc Node class for horizontal row layout.
@@ -118,5 +118,5 @@ export declare class RowNode extends BoxNode {
  * @param {BoxProps} props Row properties and configuration.
  * @returns {RowNode} New RowNode instance.
  */
-export declare const Row: (props: BoxProps) => RowNode;
+export declare const Row: ({ children, ...rest }: BoxProps) => NodeDescriptor;
 //# sourceMappingURL=layout.canvas.util.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"layout.canvas.util.d.ts","sourceRoot":"","sources":["../../../src/canvas/layout.canvas.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAkB,MAAM,yBAAyB,CAAA;AAGlF,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;AAED;;;;GAIG;AACH,eAAO,MAAM,GAAG,GAAI,OAAO,QAAQ,KAAG,OAA6B,CAAA;AAEnE;;;GAGG;AACH,qBAAa,UAAW,SAAQ,OAAO;gBACzB,KAAK,GAAE,QAAQ,GAAG,SAAc;CAS7C;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,QAAQ,KAAG,UAAmC,CAAA;AAE5E;;;GAGG;AACH,qBAAa,OAAQ,SAAQ,OAAO;gBACtB,KAAK,GAAE,QAAQ,GAAG,SAAc;CAS7C;AAED;;;;GAIG;AACH,eAAO,MAAM,GAAG,GAAI,OAAO,QAAQ,KAAG,OAA6B,CAAA"}
+{"version":3,"file":"layout.canvas.util.d.ts","sourceRoot":"","sources":["../../../src/canvas/layout.canvas.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAkB,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAGlG,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,cAIpD,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,cAIvD,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,cAIpD,CAAA"}

package/dist/esm/canvas/layout.canvas.util.js

@@ -718,12 +718,25 @@ class BoxNode {
         });
     }
 }
+/**
+ * Normalizes children into a flat NodeDescriptor array, filtering falsy values.
+ */
+function normalizeDescriptorChildren(children) {
+    if (children === undefined || children === null || children === false)
+        return undefined;
+    const arr = (Array.isArray(children) ? children : [children]).filter(Boolean);
+    return arr.length > 0 ? arr : undefined;
+}
 /**
  * Creates a new BoxNode instance.
  * @param {BoxProps} props Box properties and configuration.
  * @returns {BoxNode} New BoxNode instance.
  */
-const Box = (props) => new BoxNode(props);
+const Box = ({ children, ...rest }) => ({
+    __type: 'Box',
+    props: rest,
+    children: normalizeDescriptorChildren(children),
+});
 /**
  * @class ColumnNode
  * Node class for vertical column layout
@@ -744,7 +757,11 @@ class ColumnNode extends BoxNode {
  * @param {BoxProps} props Column properties and configuration.
  * @returns {ColumnNode} New ColumnNode instance.
  */
-const Column = (props) => new ColumnNode(props);
+const Column = ({ children, ...rest }) => ({
+    __type: 'Column',
+    props: rest,
+    children: normalizeDescriptorChildren(children),
+});
 /**
  * @class RowNode
  * @classdesc Node class for horizontal row layout.
@@ -765,6 +782,10 @@ class RowNode extends BoxNode {
  * @param {BoxProps} props Row properties and configuration.
  * @returns {RowNode} New RowNode instance.
  */
-const Row = (props) => new RowNode(props);
+const Row = ({ children, ...rest }) => ({
+    __type: 'Row',
+    props: rest,
+    children: normalizeDescriptorChildren(children),
+});
 
 export { Box, BoxNode, Column, ColumnNode, Row, RowNode };

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

@@ -1,7 +1,24 @@
 import { Canvas } from 'skia-canvas';
-import { ColumnNode } from '../canvas/layout.canvas.util.js';
-import type { BaseProps, RootProps } from '../canvas/canvas.type.js';
+import { ColumnNode, BoxNode } from '../canvas/layout.canvas.util.js';
+import type { BaseProps, RootProps, NodeDescriptor } 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;
+}
+/**
+ * Configure the canvas rendering engine.
+ * Call this once at application startup before rendering.
+ */
+export declare function configure(options: CanvasEngineConfig): void;
+/**
+ * Converts a NodeDescriptor tree into actual BoxNode instances.
+ * Used both for non-worker rendering (inline tree building) and inside
+ * the render worker (reconstructing the tree from serialized descriptors).
+ */
+export declare function buildTree(descriptor: NodeDescriptor): BoxNode;
 /**
  * Root node that manages the canvas rendering context and coordinates overall layout and drawing.
  * Inherits from ColumnNode to provide vertical layout capabilities.
@@ -36,9 +53,11 @@ export declare class RootNode extends ColumnNode {
     render(): Promise<Canvas>;
 }
 /**
- * Creates and renders a new root node with the given properties
+ * 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 instance
+ * @returns Promise resolving to the rendered Canvas (or WorkerCanvas in worker mode)
  */
 export declare const Root: (props: RootProps) => Promise<Canvas>;
 //# sourceMappingURL=root.canvas.util.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"root.canvas.util.d.ts","sourceRoot":"","sources":["../../../src/canvas/root.canvas.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAA8C,MAAM,aAAa,CAAA;AAChF,OAAO,EAAE,UAAU,EAAW,MAAM,gCAAgC,CAAA;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAUnE,eAAO,MAAM,qBAAqB,YAEjC,CAAA;AAED;;;GAGG;AACH,qBAAa,QAAS,SAAQ,UAAU;IACtC,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;IAyCxC;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAazB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;CA2ChC;AAED;;;;GAIG;AACH,eAAO,MAAM,IAAI,GAAU,OAAO,SAAS,oBAAuC,CAAA"}
+{"version":3,"file":"root.canvas.util.d.ts","sourceRoot":"","sources":["../../../src/canvas/root.canvas.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAA8C,MAAM,aAAa,CAAA;AAEhF,OAAO,EAAE,UAAU,EAAE,OAAO,EAAW,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAiBnF,eAAO,MAAM,qBAAqB,YAEjC,CAAA;AAOD,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,kBAAkB,QAMpD;AA2LD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAmB7D;AAED;;;GAGG;AACH,qBAAa,QAAS,SAAQ,UAAU;IACtC,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;CA6ChC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAU,OAAO,SAAS,KAAG,OAAO,CAAC,MAAM,CAS3D,CAAA"}

package/dist/esm/canvas/root.canvas.util.js

@@ -1,12 +1,209 @@
 import { FontLibrary, Canvas } from 'skia-canvas';
-import { ColumnNode } from './layout.canvas.util.js';
+import { ColumnNode, RowNode, BoxNode } from './layout.canvas.util.js';
 import { ImageNode } 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 { Style } from '../constant/common.const.js';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
+import { cpus } from 'node:os';
+import { Worker } from 'node:worker_threads';
+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);
+let _workerPool = null;
+/**
+ * Configure the canvas rendering engine.
+ * Call this once at application startup before rendering.
+ */
+function configure(options) {
+    if (options.workerMode !== undefined)
+        _workerMode = options.workerMode;
+    if (options.workers !== undefined)
+        _workerPoolSize = options.workers;
+    if (_workerMode) {
+        _workerPool = new WorkerPool(_workerPoolSize);
+    }
+}
+/**
+ * Proxies all skia-canvas Canvas APIs to a Canvas instance living inside a worker thread.
+ * Sync methods (toBufferSync, toURLSync) return from a pre-encoded PNG buffer.
+ * Async methods (toBuffer, toURL, toFile, getters) delegate to the worker.
+ */
+class WorkerCanvas {
+    width;
+    height;
+    _buffer; // pre-encoded PNG for sync use
+    _pool;
+    _workerIdx;
+    _canvasId;
+    constructor(opts) {
+        this._buffer = opts.buffer;
+        this.width = opts.width;
+        this.height = opts.height;
+        this._pool = opts.pool;
+        this._workerIdx = opts.workerIdx;
+        this._canvasId = opts.canvasId;
+    }
+    _call(method, ...args) {
+        return this._pool.callOnCanvas(this._workerIdx, this._canvasId, method, args);
+    }
+    // --- Sync methods: return from pre-encoded PNG buffer ---
+    toBufferSync(_format, _options) {
+        return this._buffer;
+    }
+    toURLSync(_format, _options) {
+        return `data:image/png;base64,${this._buffer.toString('base64')}`;
+    }
+    // --- Async methods: delegate to worker ---
+    toBuffer(format, options) {
+        return this._call('toBuffer', format, options);
+    }
+    toURL(format, options) {
+        return this._call('toURL', format, options);
+    }
+    toFile(filename, options) {
+        return this._call('toFile', filename, options);
+    }
+    /** Returns a Buffer (Sharp instance cannot be transferred across threads) */
+    toSharp(options) {
+        return this._call('toSharp', options);
+    }
+    toSharpSync(_options) {
+        throw new Error('[canvas] toSharpSync() is not available in worker mode — use toSharp() instead');
+    }
+    // --- Async convenience getters ---
+    get png() {
+        return this._call('toBuffer', 'png');
+    }
+    get webp() {
+        return this._call('toBuffer', 'webp');
+    }
+    get jpg() {
+        return this._call('toBuffer', 'jpg');
+    }
+    get svg() {
+        return this._call('toBuffer', 'svg');
+    }
+    get pdf() {
+        return this._call('toBuffer', 'pdf');
+    }
+    get raw() {
+        return this._call('toBuffer', 'raw');
+    }
+    /** Release the Canvas from worker memory. Call when done with this object. */
+    release() {
+        this._pool.releaseCanvas(this._workerIdx, this._canvasId);
+    }
+}
+/** Worker thread pool — routes render and canvas-call messages */
+class WorkerPool {
+    workers = [];
+    idle = [];
+    queue = [];
+    pending = new Map();
+    nextId = 0;
+    constructor(size) {
+        this.init(size);
+    }
+    init(size) {
+        const workerFile = path.join(path.dirname(fileURLToPath(import.meta.url)), '../render.worker.js');
+        for (let i = 0; i < size; i++) {
+            const workerIdx = i;
+            const worker = new Worker(workerFile);
+            worker.on('message', (msg) => {
+                const task = this.pending.get(msg.taskId);
+                if (!task)
+                    return;
+                this.pending.delete(msg.taskId);
+                if ('error' in msg) {
+                    task.reject(new Error(msg.error));
+                    return;
+                }
+                if ('canvasId' in msg) {
+                    // Render complete — put worker back to idle
+                    this.idle.push(worker);
+                    this.drain();
+                    const result = { buffer: msg.buffer, canvasId: msg.canvasId, workerIdx, width: msg.width, height: msg.height };
+                    task.resolve(result);
+                }
+                else {
+                    // Canvas method call complete
+                    task.resolve(msg.result);
+                }
+            });
+            this.workers.push(worker);
+            this.idle.push(worker);
+        }
+    }
+    drain() {
+        while (this.queue.length > 0 && this.idle.length > 0) {
+            const task = this.queue.shift();
+            const worker = this.idle.pop();
+            const request = { type: 'render', taskId: task.id, props: task.props };
+            worker.postMessage(request);
+        }
+    }
+    render(props) {
+        return new Promise((resolve, reject) => {
+            const id = this.nextId++;
+            this.pending.set(id, { resolve: resolve, reject });
+            if (this.idle.length > 0) {
+                const worker = this.idle.pop();
+                const request = { type: 'render', taskId: id, props };
+                worker.postMessage(request);
+            }
+            else {
+                this.queue.push({ id, props });
+            }
+        });
+    }
+    callOnCanvas(workerIdx, canvasId, method, args) {
+        return new Promise((resolve, reject) => {
+            const id = this.nextId++;
+            this.pending.set(id, { resolve: resolve, reject });
+            const request = { type: 'call', taskId: id, canvasId, method, args };
+            this.workers[workerIdx].postMessage(request);
+        });
+    }
+    releaseCanvas(workerIdx, canvasId) {
+        const request = { type: 'release', canvasId };
+        this.workers[workerIdx]?.postMessage(request);
+    }
+    terminate() {
+        this.workers.forEach(w => w.terminate());
+    }
+}
+/**
+ * Converts a NodeDescriptor tree into actual BoxNode instances.
+ * Used both for non-worker rendering (inline tree building) and inside
+ * the render worker (reconstructing the tree from serialized descriptors).
+ */
+function buildTree(descriptor) {
+    switch (descriptor.__type) {
+        case 'Box':
+            return new BoxNode({ ...descriptor.props, children: descriptor.children?.map(buildTree) });
+        case 'Column':
+            return new ColumnNode({ ...descriptor.props, children: descriptor.children?.map(buildTree) });
+        case 'Row':
+            return new RowNode({ ...descriptor.props, children: descriptor.children?.map(buildTree) });
+        case 'Grid':
+            return new GridNode({ ...descriptor.props, children: descriptor.children?.map(buildTree) });
+        case 'GridItem':
+            return new GridItemNode({ ...descriptor.props, children: descriptor.children?.map(buildTree) });
+        case 'Image':
+            return new ImageNode(descriptor.props);
+        case 'Text':
+            return new TextNode(descriptor.text, descriptor.props);
+        case 'Chart':
+            return new ChartNode(descriptor.props);
+    }
+}
 /**
  * Root node that manages the canvas rendering context and coordinates overall layout and drawing.
  * Inherits from ColumnNode to provide vertical layout capabilities.
@@ -56,6 +253,16 @@ class RootNode extends ColumnNode {
         this.targetWidth = props.width;
         this.targetHeight = props.height;
         this.node.setWidth(this.targetWidth);
+        // Convert any NodeDescriptor children to actual BoxNode instances
+        if (this.props.children) {
+            const childArray = Array.isArray(this.props.children) ? this.props.children : [this.props.children];
+            this.props.children = childArray.map(child => {
+                if (child && typeof child === 'object' && '__type' in child) {
+                    return buildTree(child);
+                }
+                return child;
+            });
+        }
         // Initialize children nodes
         this.processInitialChildren();
     }
@@ -81,15 +288,17 @@ class RootNode extends ColumnNode {
      * @returns Promise resolving to the rendered Canvas instance
      */
     async render() {
-        // Step 1: Load all images with a concurrency limit to avoid overwhelming remote sources
+        // 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.
         const imageNodes = this.findAllImageNodes();
         if (imageNodes.length > 0) {
+            const imageCache = new Map();
             const CONCURRENCY = 5;
             const queue = [...imageNodes];
             const workers = Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
                 while (queue.length > 0) {
                     const node = queue.shift();
-                    await node.load();
+                    await node.load(imageCache);
                 }
             });
             await Promise.allSettled(workers);
@@ -118,10 +327,21 @@ class RootNode extends ColumnNode {
     }
 }
 /**
- * Creates and renders a new root node with the given properties
+ * 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 instance
+ * @returns Promise resolving to the rendered Canvas (or WorkerCanvas in worker mode)
  */
-const Root = async (props) => await new RootNode(props).render();
+const Root = async (props) => {
+    if (_workerMode) {
+        if (!_workerPool) {
+            _workerPool = new WorkerPool(_workerPoolSize);
+        }
+        const result = await _workerPool.render(props);
+        return new WorkerCanvas({ ...result, pool: _workerPool });
+    }
+    return new RootNode(props).render();
+};
 
-export { Root, RootNode };
+export { Root, RootNode, buildTree, configure };

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

@@ -1,4 +1,4 @@
-import type { TextProps } from '../canvas/canvas.type.js';
+import type { TextProps, NodeDescriptor } from '../canvas/canvas.type.js';
 import { type CanvasRenderingContext2D } from 'skia-canvas';
 import { BoxNode } from '../canvas/layout.canvas.util.js';
 /**
@@ -161,5 +161,5 @@ export declare class TextNode extends BoxNode {
 /**
  * Creates a new TextNode instance with rich text support
  */
-export declare const Text: (text: number | string, props?: TextProps) => TextNode;
+export declare const Text: (text: number | string, props?: TextProps) => NodeDescriptor;
 //# sourceMappingURL=text.canvas.util.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"text.canvas.util.d.ts","sourceRoot":"","sources":["../../../src/canvas/text.canvas.util.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,yBAAyB,CAAA;AACrE,OAAO,EAAU,KAAK,wBAAwB,EAA2B,MAAM,aAAa,CAAA;AAC5F,OAAO,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAA;AAGxD;;;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,aAA8B,CAAA"}
+{"version":3,"file":"text.canvas.util.d.ts","sourceRoot":"","sources":["../../../src/canvas/text.canvas.util.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAe,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACrF,OAAO,EAAU,KAAK,wBAAwB,EAA2B,MAAM,aAAa,CAAA;AAC5F,OAAO,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAA;AAGxD;;;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,cAI9D,CAAA"}

package/dist/esm/canvas/text.canvas.util.js

@@ -1150,6 +1150,10 @@ class TextNode extends BoxNode {
 /**
  * Creates a new TextNode instance with rich text support
  */
-const Text = (text, props) => new TextNode(text, props);
+const Text = (text, props) => ({
+    __type: 'Text',
+    text,
+    props,
+});
 
 export { Text, TextNode };