@meonode/canvas 1.6.0-beta.1 → 1.6.0-beta.2

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

@@ -31,22 +31,77 @@ function configure(options) {
     }
 }
 /**
- * Minimal Canvas-compatible wrapper returned when rendering in worker mode.
- * Exposes toBuffer / toBufferSync so callers can use the result identically.
+ * 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 {
-    _buffer;
-    constructor(_buffer) {
-        this._buffer = _buffer;
+    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;
     }
-    toBufferSync(_format) {
+    _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;
     }
-    toBuffer(_format) {
-        return Promise.resolve(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);
     }
 }
-/** Lazy-instantiated worker pool singleton */
+/** Worker thread pool — routes render and canvas-call messages */
 class WorkerPool {
     workers = [];
     idle = [];
@@ -56,22 +111,30 @@ class WorkerPool {
     constructor(size) {
         this.init(size);
     }
-    async 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', ({ id, buffer, error }) => {
-                const task = this.pending.get(id);
+            worker.on('message', (msg) => {
+                const task = this.pending.get(msg.taskId);
                 if (!task)
                     return;
-                this.pending.delete(id);
-                this.idle.push(worker);
-                this.drain();
-                if (error) {
-                    task.reject(new Error(error));
+                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 {
-                    task.resolve(buffer);
+                    // Canvas method call complete
+                    task.resolve(msg.result);
                 }
             });
             this.workers.push(worker);
@@ -82,22 +145,36 @@ class WorkerPool {
         while (this.queue.length > 0 && this.idle.length > 0) {
             const task = this.queue.shift();
             const worker = this.idle.pop();
-            worker.postMessage({ id: task.id, props: task.props });
+            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, reject });
+            this.pending.set(id, { resolve: resolve, reject });
             if (this.idle.length > 0) {
                 const worker = this.idle.pop();
-                worker.postMessage({ id, props });
+                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());
     }
@@ -211,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);
@@ -259,8 +338,8 @@ const Root = async (props) => {
         if (!_workerPool) {
             _workerPool = new WorkerPool(_workerPoolSize);
         }
-        const buffer = await _workerPool.render(props);
-        return new WorkerCanvas(buffer);
+        const result = await _workerPool.render(props);
+        return new WorkerCanvas({ ...result, pool: _workerPool });
     }
     return new RootNode(props).render();
 };

package/dist/esm/canvas/worker.types.d.ts

@@ -0,0 +1,76 @@
+import type { ExportFormat, ExportOptions, SaveOptions, RenderOptions } from 'skia-canvas';
+import type { RootProps } from '../canvas/canvas.type.js';
+export interface CanvasCallMap {
+    toBuffer: {
+        args: [ExportFormat, ExportOptions?];
+        result: Buffer;
+    };
+    toURL: {
+        args: [ExportFormat, ExportOptions?];
+        result: string;
+    };
+    toFile: {
+        args: [string, SaveOptions?];
+        result: void;
+    };
+    toSharp: {
+        args: [RenderOptions?];
+        result: Buffer;
+    };
+}
+export type CanvasCallMethod = keyof CanvasCallMap;
+export type CallArgs<M extends CanvasCallMethod> = CanvasCallMap[M]['args'];
+export type CallResult<M extends CanvasCallMethod> = CanvasCallMap[M]['result'];
+export interface WorkerRenderRequest {
+    type: 'render';
+    taskId: number;
+    props: RootProps;
+}
+/** Discriminated union — narrows args alongside method in switch statements */
+export type WorkerCallRequest = {
+    type: 'call';
+    taskId: number;
+    canvasId: number;
+    method: 'toBuffer';
+    args: CallArgs<'toBuffer'>;
+} | {
+    type: 'call';
+    taskId: number;
+    canvasId: number;
+    method: 'toURL';
+    args: CallArgs<'toURL'>;
+} | {
+    type: 'call';
+    taskId: number;
+    canvasId: number;
+    method: 'toFile';
+    args: CallArgs<'toFile'>;
+} | {
+    type: 'call';
+    taskId: number;
+    canvasId: number;
+    method: 'toSharp';
+    args: CallArgs<'toSharp'>;
+};
+export interface WorkerReleaseRequest {
+    type: 'release';
+    canvasId: number;
+}
+export type WorkerRequest = WorkerRenderRequest | WorkerCallRequest | WorkerReleaseRequest;
+export interface WorkerRenderResponse {
+    taskId: number;
+    canvasId: number;
+    buffer: Buffer;
+    width: number;
+    height: number;
+}
+export interface WorkerCallResponse {
+    taskId: number;
+    result: Buffer | string | void;
+}
+export interface WorkerErrorResponse {
+    taskId: number;
+    error: string;
+}
+export type WorkerResponse = WorkerRenderResponse | WorkerCallResponse | WorkerErrorResponse;
+//# sourceMappingURL=worker.types.d.ts.map

package/dist/esm/canvas/worker.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.types.d.ts","sourceRoot":"","sources":["../../../src/canvas/worker.types.ts"],"names":[],"mappings":"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"}

package/dist/esm/render.worker.js

@@ -3,19 +3,68 @@ import { RootNode } from './canvas/root.canvas.util.js';
 
 /**
  * Worker thread entry point for off-main-thread canvas rendering.
- * Receives serialized RootProps (with NodeDescriptor children), builds the
- * node tree, renders to canvas, encodes to PNG, and posts the buffer back.
+ *
+ * Message protocol (main → worker):
+ *   { type: 'render', taskId, props }                      — render and keep Canvas alive
+ *   { type: 'call',   taskId, canvasId, method, args }     — call a method on a live Canvas
+ *   { type: 'release', canvasId }                          — free Canvas from memory
+ *
+ * Responses (worker → main):
+ *   WorkerRenderResponse  — render complete (includes pre-encoded PNG buffer)
+ *   WorkerCallResponse    — method call result
+ *   WorkerErrorResponse   — any failure
  */
 if (!parentPort) {
     throw new Error('[render.worker] Must be run as a worker thread');
 }
-parentPort.on('message', async ({ id, props }) => {
-    try {
-        const canvas = await new RootNode(props).render();
-        const buffer = canvas.toBufferSync('png');
-        parentPort.postMessage({ id, buffer });
+const canvases = new Map();
+let nextCanvasId = 0;
+function reply(msg) {
+    parentPort.postMessage(msg);
+}
+parentPort.on('message', async (msg) => {
+    if (msg.type === 'render') {
+        try {
+            const canvas = await new RootNode(msg.props).render();
+            const canvasId = nextCanvasId++;
+            canvases.set(canvasId, canvas);
+            reply({ taskId: msg.taskId, canvasId, buffer: canvas.toBufferSync('png'), width: canvas.width, height: canvas.height });
+        }
+        catch (err) {
+            reply({ taskId: msg.taskId, error: String(err) });
+        }
+    }
+    else if (msg.type === 'call') {
+        const canvas = canvases.get(msg.canvasId);
+        if (!canvas) {
+            reply({ taskId: msg.taskId, error: `[render.worker] Canvas ${msg.canvasId} not found` });
+            return;
+        }
+        try {
+            let result;
+            switch (msg.method) {
+                case 'toBuffer':
+                    result = await canvas.toBuffer(...msg.args);
+                    break;
+                case 'toURL':
+                    result = await canvas.toURL(...msg.args);
+                    break;
+                case 'toFile':
+                    result = await canvas.toFile(...msg.args);
+                    break;
+                case 'toSharp':
+                    // Sharp instances can't be transferred across threads — serialize to buffer
+                    result = await canvas.toSharp(...msg.args).toBuffer();
+                    break;
+            }
+            reply({ taskId: msg.taskId, result });
+        }
+        catch (err) {
+            reply({ taskId: msg.taskId, error: String(err) });
+        }
     }
-    catch (err) {
-        parentPort.postMessage({ id, error: String(err) });
+    else {
+        // type === 'release'
+        canvases.delete(msg.canvasId);
     }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meonode/canvas",
-  "version": "1.6.0-beta.1",
+  "version": "1.6.0-beta.2",
   "description": "A declarative, component-based library for server-side canvas image generation. Write complex visuals with simple functions, similar to the composition style of @meonode/ui.",
   "keywords": [
     "canvas",