@nrutils/node-red-utils 0.0.0-stage → 0.2.0

package/node-red-gpu/Kernel.js

@@ -0,0 +1,35 @@
+'use strict';
+
+class Kernel {
+    /**
+     * @param {string[]} requiredPushConstants - names that every dispatch must pass in pushConstants
+     */
+    constructor(kernelHandle, backend, name, requiredPushConstants) {
+        this._handle = kernelHandle;
+        this._backend = backend;
+        this._name = name;
+        this._required = requiredPushConstants;
+        this._destroyed = false;
+    }
+
+    /** Throw if pushConstants lacks a declared value: Vulkan would read 0, the CPU undefined. */
+    _checkPushConstants(pushConstants) {
+        const missing = this._required.filter(k => pushConstants?.[k] === undefined);
+        if (missing.length > 0) {
+            throw new TypeError(`Kernel '${this._name}': pushConstants has no value for ${missing.map(k => `'${k}'`).join(', ')}`);
+        }
+    }
+
+    async dispatch({ buffers, pushConstants, groups, groupsY = 1, groupsZ = 1 }) {
+        this._checkPushConstants(pushConstants);
+        return this._backend.dispatch(this._handle, { buffers, pushConstants, groups, groupsY, groupsZ });
+    }
+
+    destroy() {
+        if (this._destroyed) return;
+        this._destroyed = true;
+        this._backend.destroyKernel(this._handle);
+    }
+}
+
+module.exports = { Kernel };

package/node-red-gpu/README.md

@@ -0,0 +1,220 @@
+# node-red-gpu (experimental)
+
+Run compute kernels on the GPU through Vulkan, from a [worker thread](../node-red-worker/README.md). You write the kernel in a small subset of JavaScript, or in GLSL.
+
+This module is experimental and its API can change. It is tested on a Raspberry Pi 5 (V3D GPU). The native Vulkan addon is optional and not built on install. Without it, kernels run on the CPU backend, which needs no GPU.
+
+## Usage
+
+An edge filter for gray images: a blur kernel, then a Sobel kernel. The node starts a worker and hands it the image:
+
+```js
+const path = require('path');
+const { NodeRedNodeBase, nodeRedWorker, nodeRedGpu } = require('@nrutils/node-red-utils');
+
+// msg.payload is { width, height, pixels }: a Buffer with one gray byte per pixel
+module.exports = NodeRedNodeBase.createNode('gpu-edges', [nodeRedWorker, nodeRedGpu], (RED, thisNode, config) => {
+    const worker = thisNode.nodeRedWorker.init(path.join(__dirname, 'edge-worker.js'));
+
+    thisNode.on('input', (msg, send, done) => {
+        worker.request('edges', msg.payload, [], { timeout: 5000 }).then((edges) => {
+            msg.payload = { ...msg.payload, pixels: Buffer.from(edges.buffer) };
+            send(msg);
+            done();
+        }, done);
+    });
+});
+```
+
+The worker owns the GPU context:
+
+```js
+// edge-worker.js
+const { nodeRedGpuWorker } = require('@nrutils/node-red-utils/node-red-gpu');
+
+module.exports = function (worker) {
+    const gpu = nodeRedGpuWorker();
+    const options = {
+        buffers: [{ name: 'src', dtype: 'f32', access: 'readonly' }, { name: 'dst', dtype: 'f32', access: 'writeonly' }],
+        constants: { width: 'u32', height: 'u32' },
+        workgroupSize: [16, 16]     // 2D: one thread per pixel; return writes dst[y * count + x]
+    };
+    const blur = gpu.registerJsKernel('blur', { ...options, kernel: function (src, dst) {
+        const x = this.thread.x;
+        const y = this.thread.y;
+        const w = this.constants.width;
+        if (x < 1 || y < 1 || x + 1 >= w || y + 1 >= this.constants.height) return src[y * w + x];
+        let sum = 0.0;
+        for (let dy = 0; dy < 3; dy++) {
+            for (let dx = 0; dx < 3; dx++) sum += src[(y + dy - 1) * w + x + dx - 1];
+        }
+        return sum / 9.0;
+    } });
+    const edges = gpu.registerJsKernel('edges', { ...options, kernel: function (src, dst) {
+        const x = this.thread.x;
+        const y = this.thread.y;
+        const w = this.constants.width;
+        if (x < 1 || y < 1 || x + 1 >= w || y + 1 >= this.constants.height) return 0.0;
+        const i = y * w + x;
+        const gx = src[i - w + 1] + 2.0 * src[i + 1] + src[i + w + 1] - src[i - w - 1] - 2.0 * src[i - 1] - src[i + w - 1];
+        const gy = src[i + w - 1] + 2.0 * src[i + w] + src[i + w + 1] - src[i - w - 1] - 2.0 * src[i - w] - src[i - w + 1];
+        return Math.sqrt(gx * gx + gy * gy);
+    } });
+
+    worker.handle('edges', async ({ width, height, pixels }, transferList) => {
+        // Released buffers are reused by the next request of the same size
+        const [a, b, c] = [0, 1, 2].map(() => gpu.createBuffer(width * height, 'f32'));
+        try {
+            a.view.set(pixels);     // bytes to f32
+            const pushConstants = { count: width, countY: height, width, height };
+            const groups = Math.ceil(width / 16);
+            const groupsY = Math.ceil(height / 16);
+            // One submit: edges reads what blur wrote
+            await gpu.dispatchChain([
+                { kernel: blur, buffers: [a, b], pushConstants, groups, groupsY },
+                { kernel: edges, buffers: [b, c], pushConstants, groups, groupsY }
+            ]);
+            const out = Uint8ClampedArray.from(c.view);
+            transferList.push(out.buffer);  // moved to the main thread, not copied
+            return out;
+        } finally {
+            [a, b, c].forEach((buf) => gpu.releaseBuffer(buf));
+        }
+    });
+    worker.parentPorts.subscribe('close', () => gpu.close());
+};
+```
+
+The two kernels run in one `dispatchChain`, and the blurred image stays in buffer `b` between them. After each request the three buffers go back to the pool, so the next image of the same size reuses them. Without the Vulkan addon, the same kernels run on the CPU backend.
+
+`request()` is described in [node-red-worker](../node-red-worker/README.md#usage). If the kernel throws, or the worker stops, the request rejects and `done(err)` reports it.
+
+The `nodeRedGpu` mixin on the main thread checks that Vulkan loads and logs one line per process: the device name, or the reason for the CPU fallback. If you force the Vulkan backend and it fails, the node shows a red status and logs the error. The mixin also points the SPIR-V cache at the Node-RED user directory (see [Build the Vulkan addon](#build-the-vulkan-addon-linux)).
+
+### Constants and push constants
+
+The word "constants" has two sides:
+
+- At registration, `constants` declares the names and types: `constants: { width: 'u32', height: 'u32' }`. The kernel reads them as `this.constants.width`.
+- At dispatch, `pushConstants` gives the values: `pushConstants: { count: width, countY: height, width, height }`. The name comes from Vulkan, which sends them to the GPU as push constants.
+
+A JS kernel also has the push constants `count`, `countY` and `countZ` (see [JS kernels](#js-kernels)). Every dispatch must give `count` and each declared constant. If one is missing, `dispatch` and `dispatchChain` throw an error that names it. `countY` and `countZ` can be left out. A raw kernel must get every name in its `pushConstants`. Specialization constants (`specConstants`) are not passed at dispatch; see `respecializeKernel`.
+
+## Backends
+
+Set `NODE_RED_GPU_BACKEND` before you start Node-RED:
+
+- `auto` (default): try Vulkan, else use the CPU and log a warning with the reason.
+- `vulkan`: Vulkan or an error.
+- `cpu`: always the CPU.
+
+The CPU backend calls a JavaScript function for each kernel. `registerJsKernel` makes that function from your kernel. A raw `registerKernel` call needs a `cpuFallback` function; without one, it throws on the CPU backend. `cpuFallback` gets `{ buffers, pushConstants, specConstants, groups, groupsY, groupsZ }`, where `buffers` are typed arrays.
+
+## Raw GLSL kernels
+
+```js
+const ADD_GLSL = `#version 450
+layout(local_size_x = 256) in;
+layout(std430, binding = 0) readonly  buffer A { uint a[]; };
+layout(std430, binding = 1) readonly  buffer B { uint b[]; };
+layout(std430, binding = 2) writeonly buffer O { uint o[]; };
+layout(push_constant) uniform P { uint count; } p;
+void main() {
+    uint i = gl_GlobalInvocationID.x;
+    if (i < p.count) o[i] = a[i] + b[i];
+}`;
+
+const add = gpu.registerKernel('add', {
+    source: ADD_GLSL,
+    language: 'glsl',               // or 'spirv' with a SPIR-V binary
+    bindings: ['readonly', 'readonly', 'writeonly'],
+    pushConstants: { count: 'u32' },
+    workgroupSize: 256,
+    cpuFallback({ buffers: [a, b, out], pushConstants: p }) {
+        for (let i = 0; i < p.count; i++) out[i] = a[i] + b[i];
+    }
+});
+```
+
+## API
+
+`nodeRedGpuWorker()` returns a GPU context for the current thread. Names in `[ ]` are optional.
+
+- `registerJsKernel(name, { kernel, [buffers], [constants], [specConstants], [workgroupSize] })`: transpile a JS kernel to GLSL and register it. Returns a kernel.
+- `registerKernel(name, { source, [language], [bindings], [pushConstants], [specConstants], [workgroupSize], [cpuFallback] })`: register a GLSL or SPIR-V kernel. Returns a kernel. `language` is `'glsl'` if you leave it out. The CPU backend needs `cpuFallback`.
+- `createBuffer(count, dtype)`: returns a buffer. It reuses a released buffer of the same byte size if one exists. The contents are not cleared, so a reused buffer holds old data. Call `buffer.view.fill(0)` if the kernel needs zeros.
+- `releaseBuffer(buffer)`: give a buffer back for reuse.
+- `stats()`: device, buffer, kernel and dispatch counters.
+- `close()`: destroy all buffers and kernels of this context. Call it on `close` in the worker.
+
+- `dispatchChain([{ kernel, buffers, [pushConstants], groups, [groupsY], [groupsZ] }])`: run several kernels in order. `kernel` is a kernel from `registerKernel` or `registerJsKernel`. Each kernel sees the writes of the kernel before it. With Vulkan this is one queue submit with memory barriers between the kernels.
+- `respecializeKernel(kernel, values)`: set new specialization constant values. A constant that is not in `values` becomes 0. With Vulkan this rebuilds the pipeline; the CPU backend keeps the values for the next dispatch. Throws if the kernel has no specialization constants.
+
+These need the Vulkan backend:
+
+- `exportBuffer(buffer)` and `importBuffer(ref)`: pass a buffer to another worker without a copy. The ref is a plain object that you can publish.
+
+A kernel has `dispatch({ buffers, [pushConstants], groups, [groupsY], [groupsZ] })`, which returns a Promise, and `destroy()`.
+
+A buffer has `view` (a typed array; with Vulkan it maps GPU memory), `count`, `dtype`, `byteLength`, `destroy()`, and `detach()`, which returns the `ArrayBuffer` and destroys the buffer.
+
+Data types: `u8` `u16` `u32` `i8` `i16` `i32` `f32` `f64`.
+
+## JS kernels
+
+The kernel is a `function`, named or anonymous, with one parameter per buffer, in the order of `buffers`. Give each parameter the same name as its buffer. `registerJsKernel` throws a `GpuCompileError` on both backends for these mistakes, so a kernel that registers on the CPU backend also compiles on the GPU:
+
+- An arrow function. It has no `this`, so use `function`.
+- A variable from outside the function. The CPU backend rebuilds the kernel from its source, and the GPU cannot see JavaScript variables. Pass values in `this.constants`.
+- A buffer, constant or local variable with a GLSL keyword or built-in name, such as `output`, `out`, `in`, `input`, `texture`, `mix`, `min`, `vec3` or a name that starts with `gl_`. The error names the identifier.
+
+Inside the kernel you can use:
+
+- `this.thread.x`, `.y`, `.z`, `.localX`, `.localY`, `.localZ`, and `this.constants.<name>`.
+- `let` and `const`, `for`, `if`/`else`, the ternary operator, arithmetic, bitwise and comparison operators, `buf[index]` reads and writes.
+- `return value` to write to the output buffer (the first buffer with `writeonly` or `readwrite` access), at index `x + y * count + z * count * countY`.
+- `Math.abs`, `ceil`, `floor`, `round`, `sign`, `min`, `max`, `sqrt`, `pow`, `exp`, `log`, `log2`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`.
+
+You cannot use `while`, nested functions, objects, arrays, strings, classes, `async` or `require`.
+
+The transpiler also accepts GLSL-only calls:
+
+- `float()`, `int()`, `uint()` and `Math.clamp`, `exp2`, `mix`, `step`, `smoothstep`, `fract`, `mod`. The CPU backend runs them with small JavaScript versions. Integer division stays different: in JavaScript `uint(v) / 2` gives a fraction, in GLSL it rounds down.
+- `atomicAdd()` and the other atomics, and `barrier()`. They need the Vulkan backend. On the CPU backend, `registerJsKernel` throws a `GpuCompileError` that names the call.
+
+Buffer options:
+
+```js
+{ name: 'data', dtype: 'f32' }                                   // readwrite storage buffer
+{ name: 'data', dtype: 'f32', access: 'readonly' }               // or 'writeonly'
+{ name: 'tile', dtype: 'f32', shared: true, count: 256 }         // workgroup shared memory
+```
+
+The context adds the push constants `count`, `countY` and `countZ`. Threads with `x >= count`, `y >= countY` or `z >= countZ` do not run; a `countY` or `countZ` of 0 counts as 1. For a 2D kernel, set `workgroupSize: [16, 16]` and pass `count`, `countY`, `groups` and `groupsY` to `dispatch`. `return v` then writes to index `y * count + x` of the output buffer, on the GPU and on the CPU.
+
+## Build the Vulkan addon (Linux)
+
+These steps are for Debian, Ubuntu and Raspberry Pi OS.
+
+```bash
+# build
+sudo apt install g++ make python3 libvulkan-dev
+# runtime
+sudo apt install mesa-vulkan-drivers glslang-tools vulkan-tools
+
+cd node_modules/@nrutils/node-red-utils/node-red-gpu/native
+npx node-gyp rebuild
+```
+
+- `glslangValidator` (from `glslang-tools`) must be on the `PATH`. It compiles GLSL to SPIR-V at kernel registration.
+- `node-addon-api` must be in `node_modules`. It is an optional dependency of this package, so `npm install` puts it there unless you install with `--omit=optional`.
+- Run `vulkaninfo --summary` to check the GPU. If you see only `llvmpipe`, the driver cannot reach the GPU; check the permissions on `/dev/dri/renderD*`. The addon picks a hardware device and uses `llvmpipe` only if there is no other.
+- Compiled SPIR-V is cached in `gpu-cache/` in the Node-RED user directory (the `-u` option; `~/.node-red` by default). The `nodeRedGpu` mixin sets `NODE_RED_GPU_CACHE` from `RED.settings.userDir`, and worker threads read it from there. Set `NODE_RED_GPU_CACHE` yourself to use another directory. Outside Node-RED the default is `~/.node-red/gpu-cache/`.
+
+From a clone of this repository, `npm run test:gpu` runs a raw GLSL kernel and a JS kernel on the selected backend.
+
+## How it works
+
+All workers in the process share one Vulkan device. Buffer handles are valid in every worker, which is what makes `exportBuffer` work. On GPUs with unified memory, such as the Pi 5, `view` maps the GPU memory, so there is no copy between JavaScript and the GPU. Dispatches run off the JavaScript thread.
+
+[Back to node-red-utils](../README.md)

package/node-red-gpu/backends/CpuBackend.js

@@ -0,0 +1,109 @@
+'use strict';
+
+// The CPU backend ignores GLSL source entirely and calls cpuFallback instead.
+// Kernels from registerJsKernel get a cpuFallback automatically. Raw kernels need their own.
+// cpuFallback gets { buffers, pushConstants, specConstants, groups, groupsY, groupsZ }.
+
+const { GpuCompileError, GpuOutOfMemoryError } = require('../errors.js');
+
+const DTYPE_CTOR = {
+    u8:  Uint8Array,
+    i8:  Int8Array,
+    u16: Uint16Array,
+    i16: Int16Array,
+    u32: Uint32Array,
+    i32: Int32Array,
+    f32: Float32Array,
+    f64: Float64Array,
+};
+
+class CpuBackend {
+    constructor() {
+        this._kernels = new Map();
+        this._buffers = new Set();
+        this._dispatches = 0;
+        this._nextId = 1;
+    }
+
+    registerKernel(name, options) {
+        if (!options.cpuFallback) throw new GpuCompileError(`Kernel '${name}' requires cpuFallback for the CPU backend`);
+        // Spec constant values, as the Vulkan backend sets them: the default, else 0
+        const specConstants = {};
+        for (const [k, v] of Object.entries(options.specConstants || {})) {
+            specConstants[k] = (typeof v === 'object' ? v.default : 0) || 0;
+        }
+        const handle = { id: this._nextId++, name, cpuFallback: options.cpuFallback, specConstants };
+        this._kernels.set(handle.id, handle);
+        return handle;
+    }
+
+    createBuffer(count, dtype, _options) {
+        const Ctor = DTYPE_CTOR[dtype];
+        if (!Ctor) throw new TypeError(`Unknown dtype: ${dtype}`);
+        let typedArray;
+        try {
+            typedArray = new Ctor(count);
+        } catch (e) {
+            throw new GpuOutOfMemoryError(`Failed to allocate ${count} × ${dtype}`, count * Ctor.BYTES_PER_ELEMENT);
+        }
+        const handle = { view: typedArray, count, dtype, byteLength: typedArray.byteLength };
+        this._buffers.add(handle);
+        return handle;
+    }
+
+    async dispatch(kernelHandle, { buffers, pushConstants, groups, groupsY, groupsZ }) {
+        const views = buffers.map(b => b._handle.view);
+        kernelHandle.cpuFallback({ buffers: views, pushConstants, specConstants: kernelHandle.specConstants, groups, groupsY, groupsZ });
+        this._dispatches++;
+    }
+
+    // Run the kernels in order; each one sees the writes of the one before
+    async dispatchChain(specs) {
+        for (const s of specs) {
+            await this.dispatch(s.kernelHandle, { ...s, groupsY: s.groupsY || 1, groupsZ: s.groupsZ || 1 });
+        }
+    }
+
+    // There is no pipeline to rebuild: store the values for the next dispatch
+    respecializeKernel(handle, specValues) {
+        if (Object.keys(handle.specConstants).length === 0) {
+            throw new Error(`respecializeKernel: kernel '${handle.name}' has no specialization constants`);
+        }
+        // Like Vulkan, a value that is not given becomes 0
+        for (const k of Object.keys(handle.specConstants)) handle.specConstants[k] = specValues[k] ?? 0;
+    }
+
+    refBuffer(_handle) {
+        throw new Error('CpuBackend does not support shared GPU buffers');
+    }
+
+    importBuffer(_ref) {
+        throw new Error('CpuBackend does not support shared GPU buffers');
+    }
+
+    destroyBuffer(handle) {
+        this._buffers.delete(handle);
+    }
+
+    destroyKernel(handle) {
+        this._kernels.delete(handle.id);
+    }
+
+    destroyDevice() {
+        this._buffers.clear();
+        this._kernels.clear();
+    }
+
+    stats() {
+        let totalBytes = 0;
+        for (const b of this._buffers) totalBytes += b.byteLength;
+        return {
+            device: { name: 'cpu', driverVersion: 'n/a', api: 'cpu' },
+            buffers: { count: this._buffers.size, totalBytes, hostVisible: this._buffers.size, deviceLocal: 0 },
+            kernels: { count: this._kernels.size, cacheHits: 0, cacheMisses: 0 },
+            dispatches: { submitted: this._dispatches, completed: this._dispatches, inFlight: 0, lastDurationUs: 0 },
+        };
+    }
+}
+
+module.exports = { CpuBackend };

package/node-red-gpu/backends/VulkanBackend.js

@@ -0,0 +1,232 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const { GpuAddonMissingError, GpuDeviceLostError, GpuCompileError, GpuOutOfMemoryError, GpuDispatchError } = require('../errors.js');
+
+let addon;
+try {
+    addon = require('../native/build/Release/gpu_addon.node');
+} catch (e) {
+    throw new GpuAddonMissingError(`Failed to load gpu_addon: ${e.message}`);
+}
+
+// Read at compile time: the nodeRedGpu mixin sets NODE_RED_GPU_CACHE from the Node-RED userDir
+const cacheDir = () => process.env.NODE_RED_GPU_CACHE || path.join(os.homedir(), '.node-red', 'gpu-cache');
+
+const DTYPE_CTOR = {
+    u8: Uint8Array, i8: Int8Array, u16: Uint16Array, i16: Int16Array,
+    u32: Uint32Array, i32: Int32Array, f32: Float32Array, f64: Float64Array,
+};
+
+const PC_ENCODERS = {
+    u32: (view, off, val) => { view.setUint32(off, val, true); return 4; },
+    i32: (view, off, val) => { view.setInt32(off, val, true); return 4; },
+    f32: (view, off, val) => { view.setFloat32(off, val, true); return 4; },
+    u64: (view, off, val) => { view.setBigUint64(off, BigInt(val), true); return 8; },
+};
+
+const PC_SIZES = { u32: 4, i32: 4, f32: 4, u64: 8 };
+
+function compileSpirvFromGlsl(source) {
+    const hash = crypto.createHash('sha256').update(source).digest('hex');
+    const CACHE_DIR = cacheDir();
+    const spvPath = path.join(CACHE_DIR, `${hash}.spv`);
+    if (fs.existsSync(spvPath)) return { spv: fs.readFileSync(spvPath), cacheHit: true };
+
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+    const compPath = path.join(CACHE_DIR, `${hash}.comp`);
+    fs.writeFileSync(compPath, source, 'utf8');
+    try {
+        execFileSync('glslangValidator', ['--target-env', 'vulkan1.2', '-S', 'comp', '-o', spvPath, compPath]);
+    } catch (e) {
+        // glslangValidator prints its errors to stdout
+        throw new GpuCompileError(`glslangValidator failed`, `${e.stdout || ''}${e.stderr || ''}` || e.message);
+    } finally {
+        try { fs.unlinkSync(compPath); } catch (_) {}
+    }
+    return { spv: fs.readFileSync(spvPath), cacheHit: false };
+}
+
+function encodePushConstants(schema, values) {
+    const totalBytes = Object.values(schema).reduce((sum, t) => sum + (PC_SIZES[t] || 4), 0);
+    const ab = new ArrayBuffer(totalBytes);
+    const view = new DataView(ab);
+    let offset = 0;
+    for (const [field, type] of Object.entries(schema)) {
+        const encoder = PC_ENCODERS[type];
+        if (!encoder) throw new TypeError(`Unknown push constant type: ${type}`);
+        offset += encoder(view, offset, values[field] ?? 0);
+    }
+    return ab;
+}
+
+class VulkanBackend {
+    constructor() {
+        let deviceInfo;
+        try {
+            deviceInfo = addon.openDevice();
+        } catch (e) {
+            throw new GpuDeviceLostError(`openDevice failed: ${e.message}`);
+        }
+        this._device = deviceInfo;
+        this._kernels = new Map();
+        this._buffers = new Set();
+        this._nextId = 1;
+        this._cacheHits = 0;
+        this._cacheMisses = 0;
+    }
+
+    registerKernel(name, options) {
+        const { source, language = 'glsl', bindings = [], pushConstants = {}, workgroupSize = 64, specConstants = {} } = options;
+        let spirv;
+        if (language === 'spirv') {
+            spirv = source instanceof ArrayBuffer ? source : Buffer.from(source).buffer;
+        } else {
+            const { spv, cacheHit } = compileSpirvFromGlsl(source);
+            cacheHit ? this._cacheHits++ : this._cacheMisses++;
+            spirv = spv.buffer.slice(spv.byteOffset, spv.byteOffset + spv.byteLength);
+        }
+        const pcSize = Object.values(pushConstants).reduce((s, t) => s + (PC_SIZES[t] || 4), 0);
+
+        // Build spec constant count and initial values buffer
+        const specConstantNames = Object.keys(specConstants);
+        const specCount = specConstantNames.length;
+        let addonHandle;
+        try {
+            if (specCount > 0) {
+                // Encode initial spec values (all 0 by default — caller calls respecializeKernel to update)
+                const specSchema = {};
+                for (const [k, v] of Object.entries(specConstants)) {
+                    specSchema[k] = typeof v === 'object' ? v.dtype : (v || 'u32');
+                }
+                const initialValues = {};
+                for (const [k, v] of Object.entries(specConstants)) {
+                    initialValues[k] = (typeof v === 'object' ? v.default : 0) || 0;
+                }
+                const specAb = encodePushConstants(specSchema, initialValues);
+                addonHandle = addon.registerKernel(spirv, bindings.length, pcSize, workgroupSize, specCount, specAb);
+            } else {
+                addonHandle = addon.registerKernel(spirv, bindings.length, pcSize, workgroupSize);
+            }
+        } catch (e) {
+            throw new GpuCompileError(`registerKernel '${name}' failed: ${e.message}`);
+        }
+
+        // Build schema for spec constants (for respecializeKernel encoding)
+        const specConstantSchema = {};
+        for (const [k, v] of Object.entries(specConstants)) {
+            specConstantSchema[k] = typeof v === 'object' ? v.dtype : (v || 'u32');
+        }
+
+        const handle = {
+            id: this._nextId++,
+            name,
+            _addonHandle: addonHandle,
+            pushConstantSchema: pushConstants,
+            specConstantSchema,
+            specConstantCount: specCount,
+        };
+        this._kernels.set(handle.id, handle);
+        return handle;
+    }
+
+    respecializeKernel(handle, specValues) {
+        if (!handle.specConstantCount) {
+            throw new Error(`respecializeKernel: kernel '${handle.name}' has no specialization constants`);
+        }
+        const ab = encodePushConstants(handle.specConstantSchema, specValues);
+        try {
+            addon.respecializeKernel(handle._addonHandle, ab);
+        } catch (e) {
+            throw new GpuCompileError(`respecializeKernel '${handle.name}' failed: ${e.message}`);
+        }
+    }
+
+    createBuffer(count, dtype, _options) {
+        const Ctor = DTYPE_CTOR[dtype];
+        if (!Ctor) throw new TypeError(`Unknown dtype: ${dtype}`);
+        const byteSize = count * Ctor.BYTES_PER_ELEMENT;
+        let result;
+        try {
+            result = addon.createBuffer(byteSize);
+        } catch (e) {
+            throw new GpuOutOfMemoryError(`createBuffer failed for ${byteSize} bytes: ${e.message}`, byteSize);
+        }
+        const view = new Ctor(result.buffer);
+        const handle = { view, count, dtype, byteLength: byteSize, _addonHandle: result.handle };
+        this._buffers.add(handle);
+        return handle;
+    }
+
+    async dispatch(kernelHandle, { buffers, pushConstants, groups, groupsY = 1, groupsZ = 1 }) {
+        const handleArray = buffers.map(b => b._handle._addonHandle);
+        const pcArrayBuffer = encodePushConstants(kernelHandle.pushConstantSchema, pushConstants || {});
+        try {
+            await addon.dispatch(kernelHandle._addonHandle, handleArray, pcArrayBuffer, groups, groupsY, groupsZ);
+        } catch (e) {
+            throw new GpuDispatchError(`dispatch failed: ${e.message}`);
+        }
+    }
+
+    refBuffer(handle) {
+        addon.refBuffer(handle._addonHandle);
+    }
+
+    importBuffer(ref) {
+        const Ctor = DTYPE_CTOR[ref.dtype];
+        if (!Ctor) throw new TypeError(`Unknown dtype: ${ref.dtype}`);
+        const ab = addon.getBufferView(ref._gpuHandle);
+        const view = new Ctor(ab);
+        const handle = { view, count: ref.count, dtype: ref.dtype, byteLength: ref.byteLength, _addonHandle: ref._gpuHandle };
+        this._buffers.add(handle);
+        return handle;
+    }
+
+    async dispatchChain(specs) {
+        const nativeSpecs = specs.map(s => ({
+            kernel: s.kernelHandle._addonHandle,
+            buffers: s.buffers.map(b => b._handle._addonHandle),
+            pushConstants: encodePushConstants(s.kernelHandle.pushConstantSchema, s.pushConstants || {}),
+            groupsX: s.groups,
+            groupsY: s.groupsY || 1,
+            groupsZ: s.groupsZ || 1,
+        }));
+        try {
+            await addon.dispatchChain(nativeSpecs);
+        } catch (e) {
+            throw new GpuDispatchError(`dispatchChain failed: ${e.message}`);
+        }
+    }
+
+    destroyBuffer(handle) {
+        addon.destroyBuffer(handle._addonHandle);
+        this._buffers.delete(handle);
+    }
+
+    destroyKernel(handle) {
+        addon.destroyKernel(handle._addonHandle);
+        this._kernels.delete(handle.id);
+    }
+
+    destroyDevice() {
+        this._buffers.clear();
+        this._kernels.clear();
+        addon.destroyDevice();
+    }
+
+    stats() {
+        const s = addon.stats();
+        return {
+            device: { name: this._device.deviceName, driverVersion: this._device.driverVersion, api: this._device.apiVersion, memoryBudgetMB: this._device.memoryBudgetMB },
+            buffers: { count: s.buffersAllocated, totalBytes: s.buffersBytes, hostVisible: s.buffersAllocated, deviceLocal: 0 },
+            kernels: { count: s.kernelsRegistered, cacheHits: this._cacheHits, cacheMisses: this._cacheMisses },
+            dispatches: { submitted: s.dispatchesCompleted, completed: s.dispatchesCompleted, inFlight: 0, lastDurationUs: s.lastDispatchUs, lastGpuExecutionUs: s.lastGpuExecutionUs || 0 },
+        };
+    }
+}
+
+module.exports = { VulkanBackend };

package/node-red-gpu/errors.js

@@ -0,0 +1,48 @@
+'use strict';
+
+class GpuError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = 'GpuError';
+        this.code = code;
+    }
+}
+
+class GpuCompileError extends GpuError {
+    constructor(message, diagnostics = []) {
+        super(message, 'GPU_COMPILE_ERROR');
+        this.name = 'GpuCompileError';
+        this.diagnostics = diagnostics;
+    }
+}
+
+class GpuOutOfMemoryError extends GpuError {
+    constructor(message, requestedBytes) {
+        super(message, 'GPU_OUT_OF_MEMORY');
+        this.name = 'GpuOutOfMemoryError';
+        this.requestedBytes = requestedBytes;
+    }
+}
+
+class GpuDispatchError extends GpuError {
+    constructor(message) {
+        super(message, 'GPU_DISPATCH_FAILED');
+        this.name = 'GpuDispatchError';
+    }
+}
+
+class GpuDeviceLostError extends GpuError {
+    constructor(message) {
+        super(message, 'GPU_DEVICE_LOST');
+        this.name = 'GpuDeviceLostError';
+    }
+}
+
+class GpuAddonMissingError extends GpuError {
+    constructor(message) {
+        super(message, 'GPU_ADDON_MISSING');
+        this.name = 'GpuAddonMissingError';
+    }
+}
+
+module.exports = { GpuError, GpuCompileError, GpuOutOfMemoryError, GpuDispatchError, GpuDeviceLostError, GpuAddonMissingError };

package/node-red-gpu/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { nodeRedGpu } = require('./nodeRedGpuMain.js');
+const { nodeRedGpuWorker } = require('./nodeRedGpuWorker.js');
+
+module.exports = { nodeRedGpu, nodeRedGpuWorker };

package/node-red-gpu/log.js

@@ -0,0 +1,18 @@
+'use strict';
+
+// The backend choice is logged once per process, not once per node or worker
+let logged = false;
+
+/** Call log(message) the first time only. */
+function logBackendOnce(log, message) {
+    if (logged) return;
+    logged = true;
+    log(message);
+}
+
+/** The fallback message: the first line of the error, without the require stack. */
+function fallbackMessage(err) {
+    return `node-red-gpu: Vulkan is not available (${String(err.message).split('\n')[0]}). Using the CPU backend.`;
+}
+
+module.exports = { logBackendOnce, fallbackMessage };