@plasius/gpu-worker 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -20,6 +20,46 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 
+## [0.1.3] - 2026-02-28
+
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+## [0.1.2] - 2026-01-24
+
+- **Added**
+  - `loadJobWgsl` to register multiple job WGSL modules and receive `job_type` ids.
+  - Job-aware `assembleWorkerWgsl` that appends registered jobs and generates a dispatch wrapper.
+  - Optional debug mode for WGSL identifier clash detection during assembly.
+  - `loadQueueWgsl` helper that can apply queue compatibility renames during load.
+  - `createWorkerLoop` helper to drive worker/job compute dispatch at max or throttled rates.
+  - Demo denoise job WGSL (`demo/jobs/denoise.wgsl`) with a compute pass + present shader.
+  - Temporal denoise history buffer in the demo to stabilize jittered lighting.
+
+- **Changed**
+  - Demo visuals now render a campfire scene with deferred lighting (G-buffer + fullscreen lighting pass).
+  - Demo now builds per-type worklists from queue jobs and uses indirect draws for render jobs alongside physics jobs.
+  - `src/worker.wgsl` is now a minimal worker template; demo kernels live in `demo/jobs/*.wgsl`.
+  - Demo job shaders are split into `demo/jobs/common.wgsl`, `demo/jobs/physics.job.wgsl`, and `demo/jobs/render.job.wgsl`.
+  - Demo lighting sampling now uses screen-space jitter to avoid world-space banding artifacts.
+  - `assembleWorkerWgsl` can now consume a registry or explicit job list and emit a dispatching `process_job`.
+  - `assembleWorkerWgsl` now applies queue compatibility renames (e.g., `JobMeta` -> `JobDesc`) by default.
+
+- **Fixed**
+  - Reduced diagonal banding artifacts in the demo lighting pass.
+
+- **Security**
+  - (placeholder)
+
 ## [0.1.1] - 2026-01-23
 
 - **Added**
@@ -88,9 +128,22 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 
 ---
 
-[Unreleased]: https://github.com/Plasius-LTD/gpu-worker/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/Plasius-LTD/gpu-worker/compare/v0.1.3...HEAD
 [0.1.0-beta.1]: https://github.com/Plasius-LTD/gpu-worker/releases/tag/v0.1.0-beta.1
 [0.1.0]: https://github.com/Plasius-LTD/gpu-worker/releases/tag/v0.1.0
-[0.2.0]: https://github.com/Plasius-LTD/gpu-worker/releases/tag/v0.2.0
-[0.3.0]: https://github.com/Plasius-LTD/gpu-worker/releases/tag/v0.3.0
-[0.1.1]: https://github.com/Plasius-LTD/gpu-worker/releases/tag/v0.1.1
+[0.1.2]: https://github.com/Plasius-LTD/gpu-worker/releases/tag/v0.1.2
+
+## [0.1.2] - 2026-02-11
+
+- **Added**
+  - Initial release.
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+[0.1.3]: https://github.com/Plasius-LTD/gpu-worker/releases/tag/v0.1.3

package/README.md

@@ -1,6 +1,13 @@
 # @plasius/gpu-worker
 
-[![npm version](https://img.shields.io/npm/v/@plasius/gpu-worker)](https://www.npmjs.com/package/@plasius/gpu-worker)
+[![npm version](https://img.shields.io/npm/v/@plasius/gpu-worker.svg)](https://www.npmjs.com/package/@plasius/gpu-worker)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Plasius-LTD/gpu-worker/ci.yml?branch=main&label=build&style=flat)](https://github.com/Plasius-LTD/gpu-worker/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/codecov/c/github/Plasius-LTD/gpu-worker)](https://codecov.io/gh/Plasius-LTD/gpu-worker)
+[![License](https://img.shields.io/github/license/Plasius-LTD/gpu-worker)](./LICENSE)
+[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-yes-blue.svg)](./CODE_OF_CONDUCT.md)
+[![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
+[![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)
+
 [![CI](https://github.com/Plasius-LTD/gpu-worker/actions/workflows/ci.yml/badge.svg)](https://github.com/Plasius-LTD/gpu-worker/actions/workflows/ci.yml)
 [![license](https://img.shields.io/github/license/Plasius-LTD/gpu-worker)](./LICENSE)
 
@@ -15,15 +22,68 @@ npm install @plasius/gpu-worker
 
 ## Usage
 ```js
-import { assembleWorkerWgsl, loadWorkerWgsl } from "@plasius/gpu-worker";
+import {
+  assembleWorkerWgsl,
+  createWorkerLoop,
+  loadJobWgsl,
+  loadWorkerWgsl,
+} from "@plasius/gpu-worker";
 
 const workerWgsl = await loadWorkerWgsl();
-const shaderCode = await assembleWorkerWgsl(workerWgsl);
+const jobType = await loadJobWgsl({
+  wgsl: `
+fn process_job(job_index: u32, job_type: u32, payload_words: u32) {
+  // job logic here
+}
+`,
+  label: "physics",
+});
+
+const shaderCode = await assembleWorkerWgsl(workerWgsl, { debug: true });
 // Pass shaderCode to device.createShaderModule({ code: shaderCode })
 ```
 
-`assembleWorkerWgsl` also accepts an optional second argument to override the queue WGSL source:
-`assembleWorkerWgsl(workerWgsl, { queueWgsl, queueUrl, fetcher })`.
+`loadJobWgsl` registers job WGSL and returns the assigned `job_type` index.
+Call `assembleWorkerWgsl` again after registering new jobs to rebuild the
+combined WGSL. Job types are assigned in registration order, so keep the
+registration order stable across rebuilds if you need deterministic ids.
+
+`assembleWorkerWgsl` also accepts an optional second argument to override the
+queue WGSL source: `assembleWorkerWgsl(workerWgsl, { queueWgsl, queueUrl, fetcher })`.
+By default it applies queue compatibility renames (for example `JobMeta` -> `JobDesc`);
+set `queueCompat: false` to disable that behavior.
+If you are concatenating WGSL manually, `loadQueueWgsl` provides the same
+compatibility renames by default: `loadQueueWgsl({ url, fetcher, queueCompat: false })`.
+
+To bypass the registry, pass jobs directly:
+```js
+const shaderCode = await assembleWorkerWgsl(workerWgsl, {
+  jobs: [{ wgsl: jobA }, { wgsl: jobB, label: "lighting" }],
+  debug: true,
+});
+```
+
+When assembling jobs, each job WGSL must define
+`process_job(job_index, job_type, payload_words)`. The assembler rewrites each
+job's `process_job` to a unique name and generates a dispatcher based on
+`job_type`. Set `debug: true` to detect identifier clashes across appended WGSL.
+
+To run the worker loop at the highest practical rate (or a target rate), use the
+helper:
+```js
+const loop = createWorkerLoop({
+  device,
+  worker: { pipeline: workerPipeline, bindGroups: [queueBindGroup, simBindGroup] },
+  jobs: [
+    { pipeline: physicsPipeline, bindGroups: [queueBindGroup, simBindGroup], workgroups: physicsWorkgroups },
+    { pipeline: renderIndirectPipeline, bindGroups: [queueBindGroup, simBindGroup], workgroups: 1 },
+  ],
+  workgroupSize: 64,
+  maxJobsPerDispatch: queueCapacity,
+  // rateHz: 120, // optional throttle; omit for animation-frame cadence
+});
+loop.start();
+```
 
 ## What this is
 - A minimal GPU worker layer that combines a lock-free queue with user WGSL jobs.
@@ -31,8 +91,9 @@ const shaderCode = await assembleWorkerWgsl(workerWgsl);
 - A reference job format for fixed-size job dispatch (u32 indices).
 
 ## Demo
-The demo enqueues ray tracing tile jobs on the GPU and renders a simple scene. Install
-dependencies first so the lock-free queue package is available for the browser import map.
+The demo enqueues physics and render jobs on the GPU, builds per-type worklists, runs the
+physics kernel, and uses an indirect draw for the particle pass. Install dependencies first
+so the lock-free queue package is available for the browser import map.
 
 ```
 npm install
@@ -61,9 +122,12 @@ certificate for that name and set `DEMO_HOST`, `DEMO_PORT`, `DEMO_TLS_CERT`, and
 `npm run build` emits `dist/index.js`, `dist/index.cjs`, and `dist/worker.wgsl`.
 
 ## Files
-- `demo/index.html`: Loads the ray tracing demo.
-- `demo/main.js`: WebGPU setup, enqueue, and ray tracing kernel.
-- `src/worker.wgsl`: Worker entry points that dequeue jobs and run a ray tracer.
+- `demo/index.html`: Loads the WebGPU demo.
+- `demo/main.js`: WebGPU setup, queue jobs, physics worklists, and indirect draw.
+- `demo/jobs/common.wgsl`: Shared WGSL definitions for demo jobs.
+- `demo/jobs/physics.job.wgsl`: Physics job kernel (worklist + integration).
+- `demo/jobs/render.job.wgsl`: Render job kernel (worklist + indirect args).
+- `src/worker.wgsl`: Minimal worker entry point template (dequeue + `process_job` hook).
 - `src/index.js`: Helper functions to load/assemble WGSL.
 
 ## Job shape