@plasius/gpu-lock-free-queue 0.1.1-beta.1 → 0.1.2

package/CHANGELOG.md

@@ -20,38 +20,34 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 
-## [0.1.1-beta.1] - 2026-01-08
+## [0.1.2] - 2026-01-22
 
 - **Added**
-  - (placeholder)
-
-- **Changed**
-  - (placeholder)
-
-- **Fixed**
-  - (placeholder)
-
-- **Security**
-  - (placeholder)
-
-## [0.1.1-beta.0] - 2026-01-08
-
-- **Added**
-  - (placeholder)
+  - Deterministic demo test pattern mode for stable image hashing in e2e tests.
+  - 4x4 demo grid for multi-canvas output.
+  - Timestamped demo logging.
+  - Demo FPS counter and per-image progress indicators.
+  - Loader and WGSL guard tests, plus an e2e WGSL compilation check.
 
 - **Changed**
-  - (placeholder)
+  - `loadQueueWgsl` accepts `url`/`fetcher` overrides and falls back to filesystem reads for `file:` URLs.
+  - Demo renders 500 interleaved static frames using per-image queues per frame.
+  - Demo updates canvases line-by-line for progressive static output.
+  - Build outputs now ship as ESM and CJS bundles with the WGSL asset in `dist/`.
 
 - **Fixed**
-  - (placeholder)
+  - WGSL entry points now validate queue configuration and clamp job counts to buffer lengths.
+  - WGSL load errors now surface with explicit HTTP status details.
+  - CD build now installs TypeScript for the tsup build step.
 
 - **Security**
-  - (placeholder)
+  - None.
 
 ## [0.1.0] - 2025-01-08
 
 - **Added**
   - WebGPU lock-free MPMC queue with sequence counters.
   - Demo for enqueue/dequeue, FFT spectrogram, and randomness heuristics.
-[0.1.1-beta.0]: https://github.com/Plasius-LTD/gpu-lock-free-queue/releases/tag/v0.1.1-beta.0
-[0.1.1-beta.1]: https://github.com/Plasius-LTD/gpu-lock-free-queue/releases/tag/v0.1.1-beta.1
+
+[0.1.0]: https://github.com/Plasius-LTD/gpu-lock-free-queue/releases/tag/v0.1.0
+[0.1.2]: https://github.com/Plasius-LTD/gpu-lock-free-queue/releases/tag/v0.1.2

package/README.md

@@ -1,7 +1,13 @@
 # @plasius/gpu-lock-free-queue
 
+[![npm version](https://img.shields.io/npm/v/@plasius/gpu-lock-free-queue)](https://www.npmjs.com/package/@plasius/gpu-lock-free-queue)
+[![CI](https://github.com/Plasius-LTD/gpu-lock-free-queue/actions/workflows/ci.yml/badge.svg)](https://github.com/Plasius-LTD/gpu-lock-free-queue/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@plasius/gpu-lock-free-queue)](./LICENSE)
+
 A minimal WebGPU lock-free MPMC ring queue using a per-slot sequence counter (Vyukov-style). This is a starter implementation focused on correctness, robustness, and low overhead.
 
+Apache-2.0. ESM + CJS builds. WGSL assets are published in `dist/`.
+
 ## Install
 ```
 npm install @plasius/gpu-lock-free-queue
@@ -35,6 +41,17 @@ python3 -m http.server
 
 Then open `http://localhost:8000` and check the console/output.
 
+## Build Outputs
+
+`npm run build` emits `dist/index.js`, `dist/index.cjs`, and `dist/queue.wgsl`.
+
+## Tests
+```
+npm run test:unit
+npm run test:coverage
+npm run test:e2e
+```
+
 ## Files
 - `demo/index.html`: Loads the demo.
 - `demo/main.js`: WebGPU setup, enqueue/dequeue test, FFT spectrogram, and randomness heuristics.

package/dist/index.cjs

@@ -0,0 +1,60 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  loadQueueWgsl: () => loadQueueWgsl,
+  queueWgslUrl: () => queueWgslUrl
+});
+module.exports = __toCommonJS(index_exports);
+var import_meta = {};
+var queueWgslUrl = new URL("./queue.wgsl", import_meta.url);
+async function loadQueueWgsl(options = {}) {
+  const { url = queueWgslUrl, fetcher = globalThis.fetch } = options ?? {};
+  const wgslUrl = url instanceof URL ? url : new URL(url, queueWgslUrl);
+  if (!fetcher || wgslUrl.protocol === "file:") {
+    const { readFile } = await import("fs/promises");
+    const { fileURLToPath } = await import("url");
+    return readFile(fileURLToPath(wgslUrl), "utf8");
+  }
+  const response = await fetcher(wgslUrl);
+  if (!response.ok) {
+    const status = "status" in response ? response.status : "unknown";
+    const statusText = "statusText" in response ? response.statusText : "";
+    const detail = statusText ? `${status} ${statusText}` : `${status}`;
+    throw new Error(`Failed to load WGSL (${detail})`);
+  }
+  return response.text();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  loadQueueWgsl,
+  queueWgslUrl
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.js"],"sourcesContent":["export const queueWgslUrl = new URL(\"./queue.wgsl\", import.meta.url);\n\nexport async function loadQueueWgsl(options = {}) {\n  const { url = queueWgslUrl, fetcher = globalThis.fetch } = options ?? {};\n  const wgslUrl = url instanceof URL ? url : new URL(url, queueWgslUrl);\n\n  if (!fetcher || wgslUrl.protocol === \"file:\") {\n    const { readFile } = await import(\"node:fs/promises\");\n    const { fileURLToPath } = await import(\"node:url\");\n    return readFile(fileURLToPath(wgslUrl), \"utf8\");\n  }\n\n  const response = await fetcher(wgslUrl);\n  if (!response.ok) {\n    const status = \"status\" in response ? response.status : \"unknown\";\n    const statusText = \"statusText\" in response ? response.statusText : \"\";\n    const detail = statusText ? `${status} ${statusText}` : `${status}`;\n    throw new Error(`Failed to load WGSL (${detail})`);\n  }\n  return response.text();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,eAAe,IAAI,IAAI,gBAAgB,YAAY,GAAG;AAEnE,eAAsB,cAAc,UAAU,CAAC,GAAG;AAChD,QAAM,EAAE,MAAM,cAAc,UAAU,WAAW,MAAM,IAAI,WAAW,CAAC;AACvE,QAAM,UAAU,eAAe,MAAM,MAAM,IAAI,IAAI,KAAK,YAAY;AAEpE,MAAI,CAAC,WAAW,QAAQ,aAAa,SAAS;AAC5C,UAAM,EAAE,SAAS,IAAI,MAAM,OAAO,aAAkB;AACpD,UAAM,EAAE,cAAc,IAAI,MAAM,OAAO,KAAU;AACjD,WAAO,SAAS,cAAc,OAAO,GAAG,MAAM;AAAA,EAChD;AAEA,QAAM,WAAW,MAAM,QAAQ,OAAO;AACtC,MAAI,CAAC,SAAS,IAAI;AAChB,UAAM,SAAS,YAAY,WAAW,SAAS,SAAS;AACxD,UAAM,aAAa,gBAAgB,WAAW,SAAS,aAAa;AACpE,UAAM,SAAS,aAAa,GAAG,MAAM,IAAI,UAAU,KAAK,GAAG,MAAM;AACjE,UAAM,IAAI,MAAM,wBAAwB,MAAM,GAAG;AAAA,EACnD;AACA,SAAO,SAAS,KAAK;AACvB;","names":[]}

package/dist/index.js

@@ -0,0 +1,24 @@
+// src/index.js
+var queueWgslUrl = new URL("./queue.wgsl", import.meta.url);
+async function loadQueueWgsl(options = {}) {
+  const { url = queueWgslUrl, fetcher = globalThis.fetch } = options ?? {};
+  const wgslUrl = url instanceof URL ? url : new URL(url, queueWgslUrl);
+  if (!fetcher || wgslUrl.protocol === "file:") {
+    const { readFile } = await import("fs/promises");
+    const { fileURLToPath } = await import("url");
+    return readFile(fileURLToPath(wgslUrl), "utf8");
+  }
+  const response = await fetcher(wgslUrl);
+  if (!response.ok) {
+    const status = "status" in response ? response.status : "unknown";
+    const statusText = "statusText" in response ? response.statusText : "";
+    const detail = statusText ? `${status} ${statusText}` : `${status}`;
+    throw new Error(`Failed to load WGSL (${detail})`);
+  }
+  return response.text();
+}
+export {
+  loadQueueWgsl,
+  queueWgslUrl
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.js"],"sourcesContent":["export const queueWgslUrl = new URL(\"./queue.wgsl\", import.meta.url);\n\nexport async function loadQueueWgsl(options = {}) {\n  const { url = queueWgslUrl, fetcher = globalThis.fetch } = options ?? {};\n  const wgslUrl = url instanceof URL ? url : new URL(url, queueWgslUrl);\n\n  if (!fetcher || wgslUrl.protocol === \"file:\") {\n    const { readFile } = await import(\"node:fs/promises\");\n    const { fileURLToPath } = await import(\"node:url\");\n    return readFile(fileURLToPath(wgslUrl), \"utf8\");\n  }\n\n  const response = await fetcher(wgslUrl);\n  if (!response.ok) {\n    const status = \"status\" in response ? response.status : \"unknown\";\n    const statusText = \"statusText\" in response ? response.statusText : \"\";\n    const detail = statusText ? `${status} ${statusText}` : `${status}`;\n    throw new Error(`Failed to load WGSL (${detail})`);\n  }\n  return response.text();\n}\n"],"mappings":";AAAO,IAAM,eAAe,IAAI,IAAI,gBAAgB,YAAY,GAAG;AAEnE,eAAsB,cAAc,UAAU,CAAC,GAAG;AAChD,QAAM,EAAE,MAAM,cAAc,UAAU,WAAW,MAAM,IAAI,WAAW,CAAC;AACvE,QAAM,UAAU,eAAe,MAAM,MAAM,IAAI,IAAI,KAAK,YAAY;AAEpE,MAAI,CAAC,WAAW,QAAQ,aAAa,SAAS;AAC5C,UAAM,EAAE,SAAS,IAAI,MAAM,OAAO,aAAkB;AACpD,UAAM,EAAE,cAAc,IAAI,MAAM,OAAO,KAAU;AACjD,WAAO,SAAS,cAAc,OAAO,GAAG,MAAM;AAAA,EAChD;AAEA,QAAM,WAAW,MAAM,QAAQ,OAAO;AACtC,MAAI,CAAC,SAAS,IAAI;AAChB,UAAM,SAAS,YAAY,WAAW,SAAS,SAAS;AACxD,UAAM,aAAa,gBAAgB,WAAW,SAAS,aAAa;AACpE,UAAM,SAAS,aAAa,GAAG,MAAM,IAAI,UAAU,KAAK,GAAG,MAAM;AACjE,UAAM,IAAI,MAAM,wBAAwB,MAAM,GAAG;AAAA,EACnD;AACA,SAAO,SAAS,KAAK;AACvB;","names":[]}

package/dist/queue.wgsl

@@ -0,0 +1,138 @@
+struct Queue {
+  head: atomic<u32>,
+  tail: atomic<u32>,
+  capacity: u32,
+  mask: u32,
+  _pad: vec2<u32>,
+};
+
+struct Slot {
+  seq: atomic<u32>,
+  value: u32,
+  _pad: vec2<u32>,
+};
+
+struct Params {
+  job_count: u32,
+  _pad: vec3<u32>,
+};
+
+@group(0) @binding(0) var<storage, read_write> queue: Queue;
+@group(0) @binding(1) var<storage, read_write> slots: array<Slot>;
+@group(0) @binding(2) var<storage, read> input_jobs: array<u32>;
+@group(0) @binding(3) var<storage, read_write> output_jobs: array<u32>;
+@group(0) @binding(4) var<storage, read_write> status: array<u32>;
+@group(0) @binding(5) var<uniform> params: Params;
+
+const MAX_RETRIES: u32 = 512u;
+
+fn queue_config_valid() -> bool {
+  if (queue.capacity == 0u) {
+    return false;
+  }
+  if ((queue.capacity & (queue.capacity - 1u)) != 0u) {
+    return false;
+  }
+  if (queue.mask != queue.capacity - 1u) {
+    return false;
+  }
+  if (queue.capacity > arrayLength(&slots)) {
+    return false;
+  }
+  return true;
+}
+
+fn enqueue_job_count() -> u32 {
+  let count = min(params.job_count, arrayLength(&input_jobs));
+  return min(count, arrayLength(&status));
+}
+
+fn dequeue_job_count() -> u32 {
+  let count = min(params.job_count, arrayLength(&output_jobs));
+  return min(count, arrayLength(&status));
+}
+
+fn enqueue(val: u32) -> u32 {
+  for (var attempt: u32 = 0u; attempt < MAX_RETRIES; attempt++) {
+    let t = atomicLoad(&queue.tail);
+    let slot_index = t & queue.mask;
+    let seq = atomicLoad(&slots[slot_index].seq);
+    let diff = i32(seq) - i32(t);
+
+    if (diff == 0) {
+      let res = atomicCompareExchangeWeak(&queue.tail, t, t + 1u);
+      if (res.exchanged) {
+        slots[slot_index].value = val;
+        atomicStore(&slots[slot_index].seq, t + 1u);
+        return 1u;
+      }
+    } else if (diff < 0) {
+      return 0u;
+    }
+  }
+
+  return 0u;
+}
+
+fn dequeue(idx: u32) -> u32 {
+  for (var attempt: u32 = 0u; attempt < MAX_RETRIES; attempt++) {
+    let h = atomicLoad(&queue.head);
+    let slot_index = h & queue.mask;
+    let seq = atomicLoad(&slots[slot_index].seq);
+    let diff = i32(seq) - i32(h + 1u);
+
+    if (diff == 0) {
+      let res = atomicCompareExchangeWeak(&queue.head, h, h + 1u);
+      if (res.exchanged) {
+        let val = slots[slot_index].value;
+        output_jobs[idx] = val;
+        atomicStore(&slots[slot_index].seq, h + queue.capacity);
+        return 1u;
+      }
+    } else if (diff < 0) {
+      return 0u;
+    }
+  }
+
+  return 0u;
+}
+
+@compute @workgroup_size(64)
+fn enqueue_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let idx = gid.x;
+  let job_count = enqueue_job_count();
+  if (idx >= job_count) {
+    return;
+  }
+  if (!queue_config_valid()) {
+    return;
+  }
+  if (status[idx] == 1u) {
+    return;
+  }
+
+  let ok = enqueue(input_jobs[idx]);
+  if (ok == 1u) {
+    status[idx] = 1u;
+  }
+}
+
+@compute @workgroup_size(64)
+fn dequeue_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let idx = gid.x;
+  let job_count = dequeue_job_count();
+  if (idx >= job_count) {
+    return;
+  }
+  if (!queue_config_valid()) {
+    return;
+  }
+  if (status[idx] == 1u) {
+    return;
+  }
+
+  let ok = dequeue(idx);
+  if (ok == 1u) {
+    status[idx] = 1u;
+  }
+}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@plasius/gpu-lock-free-queue",
-  "version": "0.1.1-beta.1",
+  "version": "0.1.2",
   "description": "WebGPU lock-free MPMC ring queue with sequence counters.",
   "type": "module",
   "sideEffects": false,
   "private": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "files": [
+    "dist",
     "src",
     "README.md",
     "CHANGELOG.md",
@@ -13,12 +16,20 @@
     "legal"
   ],
   "exports": {
-    ".": "./src/index.js",
-    "./queue.wgsl": "./src/queue.wgsl",
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./queue.wgsl": "./dist/queue.wgsl",
     "./package.json": "./package.json"
   },
   "scripts": {
-    "demo": "python3 -m http.server"
+    "build": "tsup && cp src/queue.wgsl dist/queue.wgsl",
+    "demo": "python3 -m http.server",
+    "test": "npm run test:unit",
+    "test:unit": "node --test",
+    "test:e2e": "npx playwright install chromium && playwright test",
+    "test:coverage": "c8 --reporter=lcov --reporter=text node --test"
   },
   "keywords": [
     "webgpu",
@@ -34,6 +45,12 @@
   ],
   "author": "Plasius LTD <development@plasius.co.uk>",
   "license": "Apache-2.0",
+  "devDependencies": {
+    "@playwright/test": "^1.57.0",
+    "c8": "^10.1.3",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Plasius-LTD/gpu-lock-free-queue.git"

package/src/index.js

@@ -1,6 +1,21 @@
 export const queueWgslUrl = new URL("./queue.wgsl", import.meta.url);
 
-export async function loadQueueWgsl() {
-  const response = await fetch(queueWgslUrl);
+export async function loadQueueWgsl(options = {}) {
+  const { url = queueWgslUrl, fetcher = globalThis.fetch } = options ?? {};
+  const wgslUrl = url instanceof URL ? url : new URL(url, queueWgslUrl);
+
+  if (!fetcher || wgslUrl.protocol === "file:") {
+    const { readFile } = await import("node:fs/promises");
+    const { fileURLToPath } = await import("node:url");
+    return readFile(fileURLToPath(wgslUrl), "utf8");
+  }
+
+  const response = await fetcher(wgslUrl);
+  if (!response.ok) {
+    const status = "status" in response ? response.status : "unknown";
+    const statusText = "statusText" in response ? response.statusText : "";
+    const detail = statusText ? `${status} ${statusText}` : `${status}`;
+    throw new Error(`Failed to load WGSL (${detail})`);
+  }
   return response.text();
 }

package/src/queue.wgsl

@@ -26,6 +26,32 @@ struct Params {
 
 const MAX_RETRIES: u32 = 512u;
 
+fn queue_config_valid() -> bool {
+  if (queue.capacity == 0u) {
+    return false;
+  }
+  if ((queue.capacity & (queue.capacity - 1u)) != 0u) {
+    return false;
+  }
+  if (queue.mask != queue.capacity - 1u) {
+    return false;
+  }
+  if (queue.capacity > arrayLength(&slots)) {
+    return false;
+  }
+  return true;
+}
+
+fn enqueue_job_count() -> u32 {
+  let count = min(params.job_count, arrayLength(&input_jobs));
+  return min(count, arrayLength(&status));
+}
+
+fn dequeue_job_count() -> u32 {
+  let count = min(params.job_count, arrayLength(&output_jobs));
+  return min(count, arrayLength(&status));
+}
+
 fn enqueue(val: u32) -> u32 {
   for (var attempt: u32 = 0u; attempt < MAX_RETRIES; attempt++) {
     let t = atomicLoad(&queue.tail);
@@ -74,7 +100,11 @@ fn dequeue(idx: u32) -> u32 {
 @compute @workgroup_size(64)
 fn enqueue_main(@builtin(global_invocation_id) gid: vec3<u32>) {
   let idx = gid.x;
-  if (idx >= params.job_count) {
+  let job_count = enqueue_job_count();
+  if (idx >= job_count) {
+    return;
+  }
+  if (!queue_config_valid()) {
     return;
   }
   if (status[idx] == 1u) {
@@ -90,7 +120,11 @@ fn enqueue_main(@builtin(global_invocation_id) gid: vec3<u32>) {
 @compute @workgroup_size(64)
 fn dequeue_main(@builtin(global_invocation_id) gid: vec3<u32>) {
   let idx = gid.x;
-  if (idx >= params.job_count) {
+  let job_count = dequeue_job_count();
+  if (idx >= job_count) {
+    return;
+  }
+  if (!queue_config_valid()) {
     return;
   }
   if (status[idx] == 1u) {