Onboarding: gpujs/gpu.js

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gpujs/gpu.js shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Stale — last commit 1y ago

• 10 active contributors
• MIT licensed
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gpujs/gpu.js repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gpujs/gpu.js.

What it runs against: a local clone of gpujs/gpu.js — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gpujs/gpu.js | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 409 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>gpujs/gpu.js</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gpujs/gpu.js. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gpujs/gpu.js.git
#   cd gpu.js
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gpujs/gpu.js and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gpujs/gpu.js(\\.git)?\\b" \\
  && ok "origin remote is gpujs/gpu.js" \\
  || miss "origin remote is not gpujs/gpu.js (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "src/index.js" \\
  && ok "src/index.js" \\
  || miss "missing critical file: src/index.js"
test -f "src/backend/kernel.js" \\
  && ok "src/backend/kernel.js" \\
  || miss "missing critical file: src/backend/kernel.js"
test -f "src/backend/function-builder.js" \\
  && ok "src/backend/function-builder.js" \\
  || miss "missing critical file: src/backend/function-builder.js"
test -f "src/backend/function-tracer.js" \\
  && ok "src/backend/function-tracer.js" \\
  || miss "missing critical file: src/backend/function-tracer.js"
test -f "src/backend/web-gl/kernel.js" \\
  && ok "src/backend/web-gl/kernel.js" \\
  || miss "missing critical file: src/backend/web-gl/kernel.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 409 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~379d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gpujs/gpu.js"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

GPU.js is a JavaScript transpiler that automatically converts JavaScript functions into WebGL/WebGPU shader code, executing them on the GPU for parallel computation. It provides a fallback to CPU JavaScript when GPU acceleration is unavailable, enabling developers to write GPGPU algorithms (matrix multiplication, fluid simulations, raycasting) without manually writing shader languages, with typical speedups of 1-15x depending on hardware. Modular backend architecture: src/backend/cpu/ and src/backend/gl/ contain platform-specific kernel implementations; src/backend/function-builder.js and function-tracer.js handle AST parsing and transpilation; src/alias.js provides public API. Browser bundles (dist/gpu-browser*.js) are transpiled via Gulp using Browserify. Examples/ contains runnable HTML and TypeScript demos.

Who it's for

JavaScript developers building performance-critical applications like scientific computing, image processing, physics simulations, or data analysis who need GPU acceleration without learning GLSL/WGSL. Contributors include graphics engineers and compiler enthusiasts working on transpilation pipelines.

Maturity & risk

Production-ready and actively maintained at v2.16.0 with test coverage via QUnit (test/ directory), C8 coverage reporting, and established CI/CD (gulpfile.js). The project has substantial examples (15+ demos) and TypeScript support via src/index.d.ts. Last verified update shows Node >=8.0.0 support and modern dependencies (acorn 8.14.0, webgpu 0.2.9), indicating active development.

Moderate risk: WebGPU support (0.2.9) is pre-release and API-unstable; gl (8.1.6) for WebGL is mature but Node-only. Dependency on gpu-mock.js via GitHub (non-npm) adds maintenance overhead. The transpiler's reliance on Acorn AST parsing means JavaScript syntax edge cases could break kernels. No visible breaking-change log or deprecation warnings in documentation.

Active areas of work

Active maintenance with WebGPU integration ongoing (0.2.9 dependency), QUnit test suite covering issues/internal/features, and npm/Unpkg CDN distribution. Documentation generation via doxdox suggests API docs are kept current. No specific PR/milestone data visible, but package.json version 2.16.0 and recent dependency updates indicate regular releases.

Get running

git clone https://github.com/gpujs/gpu.js.git
cd gpu.js
npm install
npm run make

Daily commands:

npm run make      # Gulp build pipeline (see gulpfile.js)
npm run build     # Same as make, generates dist/
npm run test      # QUnit test suite (test/issues, test/internal, test/features)
npm run coverage  # C8 code coverage report

Map of the codebase

• src/index.js — Main entry point that exports the GPU class and initializes the library—required reading to understand the public API surface
• src/backend/kernel.js — Base Kernel class that all backends inherit from; defines the core kernel execution interface and lifecycle
• src/backend/function-builder.js — Orchestrates function compilation and transpilation from JavaScript to GPU shader code; central to the kernel building pipeline
• src/backend/function-tracer.js — Traces and analyzes JavaScript function ASTs to extract dependencies and determine kernel compatibility
• src/backend/web-gl/kernel.js — WebGL-specific kernel implementation; the primary GPU backend for browser environments
• src/backend/cpu/kernel.js — Fallback CPU kernel implementation; executed when GPU is unavailable
• src/backend/function-node.js — Abstract base for parsing and converting function nodes to shader syntax across all backends

How to make changes

Add Support for a New Data Type in WebGL Kernel Values

1. Create a new file in src/backend/web-gl/kernel-value/ following naming convention (e.g., custom-type.js) (src/backend/web-gl/kernel-value/custom-type.js)
2. Extend the KernelValue base class and implement getValue() and updateValue() methods to bind the type to WebGL uniforms or textures (src/backend/web-gl/kernel-value/custom-type.js)
3. Register the new type handler in the kernel-value index by adding it to the exports (src/backend/web-gl/kernel-value/index.js)
4. Update kernel-value-maps.js to map the detected type to your new handler class in the TYPE_MAP (src/backend/web-gl/kernel-value-maps.js)
5. Add test cases in test directory to ensure the type correctly binds and updates values during kernel execution (test/[test-file].js)

Add a New GPU Backend (e.g., WebGPU or Vulkan)

1. Create a new directory src/backend/[backend-name]/ with kernel.js and function-node.js files (src/backend/[backend-name]/kernel.js)
2. Extend the base Kernel class in your backend kernel.js and implement build(), run(), and output() methods (src/backend/[backend-name]/kernel.js)
3. Create function-node.js to transpile JavaScript AST to your backend's shader language (e.g., WGSL for WebGPU) (src/backend/[backend-name]/function-node.js)
4. Update src/index.js to detect available backend capabilities and instantiate your backend when appropriate (src/index.js)
5. Create shader template files (fragment, vertex, compute) in your backend directory if needed (src/backend/[backend-name]/shader-template.glsl)
6. Add integration tests to verify kernel compilation, parameter binding, and output for your backend (test/backend-[backend-name].js)

Add a New Texture Encoding Format for WebGL

1. Create a new texture encoder file in src/backend/gl/texture/ (e.g., custom-encoding.js) (src/backend/gl/texture/custom-encoding.js)
2. Implement encode() to convert JavaScript arrays to WebGL texture data and decode() to extract results (src/backend/gl/texture/custom-encoding.js)
3. Register your encoder in src/backend/gl/texture/index.js by adding a condition to the factory function (src/backend/gl/texture/index.js)
4. Add shader utilities in fragment-shader or a helper file if your encoding requires special unpack logic (src/backend/web-gl/fragment-shader.js)
5. Test with various array dimensions (1D, 2D, 3D) to verify encoding/decoding fidelity and performance (test/texture-encoding.js)

Optimize Kernel Compilation by Extending Function Tracer

1. Review src/backend/function-tracer.js to understand how it parses AST and extracts variable dependencies (src/backend/function-tracer.js)
2. Identify optimization opportunity (e.g., constant folding, dead code elimination) and add a new analysis method to FunctionTracer (src/backend/function-tracer.js)
3. Modify src/backend/function-builder.js to apply your optimization before generating shader code (src/backend/function-builder.js)
4. Update relevant function-node.js files to emit optimized shader code based on tracer insights (src/backend/web-gl/function-node.js)
5. Add benchmarks to examples/ to measure compilation time and shader execution speedup (examples/benchmark-optimization.js)

Traps & gotchas

1. Kernel scope isolation: Functions passed to createKernel() cannot access outer-scope variables directly; only kernel parameters and this.thread are available — AST tracing extracts only kernel-local code. 2) Shader type precision: GPU precision (float32 vs float64) differs from JavaScript; mathematical edge cases (NaN, Infinity) behave differently. 3) Array dimension mismatch: Input arrays must match declared dimensions (1D, 2D, 3D); GPU texture mapping expects strict shape. 4) No dynamic GPU dispatch: Output dimensions must be set via .setOutput([x, y, z]) before execution; cannot change per-invocation. 5) Browser context requirement: WebGL backend needs valid canvas/WebGLContext; Node.js gl library (8.1.6) must be separately installed and configured.

Architecture

Concepts to learn

• Abstract Syntax Tree (AST) Transpilation — GPU.js uses Acorn to parse JavaScript into AST, then walks it (function-tracer.js) to extract kernel semantics and emit GLSL—understanding this pipeline is essential to extend language support or fix parser bugs
• GPGPU (General-Purpose computing on GPUs) — The core concept GPU.js enables: using massively parallel GPU cores for non-graphics computation; critical to understanding performance model (thousands of threads in parallel, strict memory layout requirements)
• WebGL Texture Binding & Fragment Shaders — GPU.js compiles kernels to WebGL fragment shaders and binds array inputs as textures (src/backend/gl/texture/); developers must grasp how 2D/3D arrays map to texture coordinates for correctness
• Thread Indexing (this.thread.x/y/z) — GPU.js replaces traditional nested loops with parallel thread assignment; this.thread provides the unique identifier for each GPU core executing the kernel, enabling implicit parallelization
• Kernel Fusion & Loop Unrolling — The transpiler may unroll loops or fuse operations for GPU efficiency; understanding limitations (fixed loop counts, no dynamic dispatch) is vital when designing kernels
• Fallback Execution & Graceful Degradation — GPU.js auto-falls back to CPU (src/backend/cpu/kernel.js) when WebGL unavailable; the transpiler must preserve semantics across both paths, making cross-backend testing critical
• WebGPU vs. WebGL API Differences — GPU.js supports both WebGL (mature, broad support) and WebGPU (emerging, future-proof); the dual-backend design (src/backend/gl/ vs. webgpu support) means maintainers juggle two API contracts

Related repos

• TensorFlow/tfjs — JavaScript tensor computation library with GPU backend via WebGL/WebGPU; overlapping use cases (matrix ops, NDarrays) but higher-level API
• processing/p5.js — Creative coding library; often paired with GPU.js for real-time graphics, shaders, and WebGL visualization
• gpujs/gpu-mock.js — Direct dependency (github:weagle08/gpu-mock.js in package.json) used for testing GPU kernels without real hardware
• webgpu/webgpu — Official WebGPU specification and polyfill; GPU.js targets webgpu 0.2.9 as next-generation backend
• oframe/ogl — WebGL abstraction layer; alternative approach to GPU compute but focuses on rendering rather than GPGPU algorithms

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for WebGL texture types (src/backend/gl/texture/)

The texture directory contains 16 different texture type implementations (array-2-float, array-3-float, memory-optimized variants, etc.) but there are no visible dedicated test files for these critical components. Given that texture handling is core to GPU computation, adding thorough tests for each texture type would catch regressions and improve maintainability.

• [ ] Create test/backend/gl/texture/ directory structure
• [ ] Add unit tests for each texture type in src/backend/gl/texture/ (float.js, array-2-float.js, memory-optimized.js, etc.)
• [ ] Test texture initialization, data binding, and dimension handling for 1D, 2D, and 3D variants
• [ ] Test unsigned and float precision variants
• [ ] Run tests with: npm test and verify coverage with: npm run coverage

Add integration tests for GPU backend switching (CPU/WebGL/Headless-GL/WebGPU)

The codebase supports multiple backends (src/backend/cpu, src/backend/gl, src/backend/headless-gl, src/backend/web-gl) but based on test script in package.json (test/issues, test/internal, test/features), there's no evidence of explicit backend switching tests. New contributors could add tests that verify the same kernel produces consistent results across all available backends.

• [ ] Create test/backend/ directory for cross-backend tests
• [ ] Write integration test suite that runs identical kernels on CPU, WebGL, Headless-GL backends
• [ ] Verify numeric output consistency across backends for various operations (matrix multiply, convolution, reduction)
• [ ] Add tests for fallback behavior when GPU is unavailable
• [ ] Document results in test output showing which backends are available in test environment

Add validation and error-handling tests for src/backend/function-builder.js and src/backend/function-tracer.js

These critical transpilation modules (function-builder.js and function-tracer.js) are responsible for converting JavaScript to shader code. There's no visible test coverage for edge cases, invalid inputs, or error messages. Adding tests would improve code reliability and help new contributors understand the transpilation pipeline.

• [ ] Create test/backend/function-builder.test.js to test kernel function parsing
• [ ] Add tests for unsupported JavaScript features that should throw helpful errors
• [ ] Test function tracing with various variable scopes and closure scenarios
• [ ] Add tests for type inference edge cases (arrays, objects, mixed types)
• [ ] Test error messages are clear and guide users to supported patterns
• [ ] Include tests for the examples in examples/ directory to ensure they transpile correctly

Good first issues

• Add TypeScript definition tests: src/index.d.ts exists but no test/typescript/ suite validates type safety; create test files for matrix multiplication, loop syntax, and thread access to catch definition drift.
• Document shader output for common kernels: Create examples/shader-output/ directory with .html files showing GLSL output of simple kernels using kernel.toString(); helps developers debug transpilation.
• Expand CPU backend feature parity: src/backend/cpu/kernel.js likely missing some edge cases covered by GL backend (e.g., nested array access, bitwise ops); add test/features/cpu-specific-edge-cases.js with failing examples.

Top contributors

• @robertleeplummerjr — 77 commits
• @dependabot[bot] — 14 commits
• @ultrasonicsoft — 2 commits
• @JenLyndle — 1 commits
• @dhritzkiv — 1 commits

Recent commits

• f66631c — Merge pull request #840 from JenLyndle/upgrade-dependencies (robertleeplummerjr)
• 2f688fe — upgrade all dependencies to latest, change gulp merge addon to 'ordered-read-streams' to make build work (JenLyndle)
• 6d7dde3 — fix: Upgrade browserify (robertleeplummerjr)
• 87cf1f1 — fix: Upgrade c8 (robertleeplummerjr)
• 62516ef — Merge pull request #710 from gpujs/dependabot/npm_and_yarn/path-parse-1.0.7 (robertleeplummerjr)
• 1d02b9a — Merge pull request #792 from gpujs/dependabot/npm_and_yarn/terser-and-gulp-uglify-es-5.15.1 (robertleeplummerjr)
• a428c45 — build(deps): bump terser and gulp-uglify-es (dependabot[bot])
• 5f0fa3b — Merge pull request #796 from gpujs/dependabot/npm_and_yarn/tar-6.1.11 (robertleeplummerjr)
• 8848bec — build(deps): bump tar from 4.4.13 to 6.1.11 (dependabot[bot])
• 81f6e3b — Merge pull request #795 from gpujs/dependabot/npm_and_yarn/minimist-1.2.7 (robertleeplummerjr)

Security observations

• High · Outdated Acorn Dependency with Known Vulnerabilities — package.json - acorn: 8.14.0. The project uses acorn 8.14.0, which is an older version of the JavaScript parser. Acorn has had multiple security vulnerabilities in past versions related to prototype pollution and other issues. The current pinned version should be verified against CVE databases. Fix: Update acorn to the latest stable version (currently 8.11.3 or later). Run 'npm audit' to identify known vulnerabilities and update dependencies accordingly.
• High · GPU-Mock.js Dependency from GitHub with No Version Pinning — package.json - gpu-mock.js: github:weagle08/gpu-mock.js. The dependency 'gpu-mock.js' is sourced directly from GitHub (weagle08/gpu-mock.js) without a specific commit hash or version tag. This creates supply chain risk as updates could be pulled without control or verification. Fix: Pin the dependency to a specific commit hash: 'github:weagle08/gpu-mock.js#<commit-hash>' or use a version tag if available. Alternatively, consider publishing to npm for better version control.
• Medium · Dynamic Code Transpilation Without Input Validation — src/backend/function-tracer.js, src/backend/function-builder.js, src/backend/function-node.js. The codebase transpiles JavaScript functions to shader language. The function-tracer, function-builder, and kernel-string modules suggest dynamic code generation and execution. Without proper input validation and sanitization, user-provided functions could lead to injection vulnerabilities or unintended code execution. Fix: Implement strict input validation and AST (Abstract Syntax Tree) analysis to ensure only safe JavaScript constructs are transpiled. Use allowlisting for permitted functions and operations. Add security documentation for users.
• Medium · WebGL/Headless GL Backend Execution Risk — src/backend/web-gl/, src/backend/headless-gl/. The project includes WebGL and headless-gl backends that execute GPU code. If user input is not properly validated before being sent to GPU kernels, it could lead to unexpected behavior, denial of service, or information disclosure. Fix: Implement strict type checking and bounds validation for all inputs passed to GPU kernels. Document security boundaries clearly. Consider implementing a sandboxing mechanism for untrusted code.
• Medium · Dynamic HTML Texture Handling Without XSS Protection — src/backend/web-gl/kernel-value/dynamic-html-image.js, src/backend/web-gl/kernel-value/dynamic-html-video.js. The presence of 'dynamic-html-image.js' and 'dynamic-html-video.js' in kernel-value handlers suggests the project accepts HTML elements as input. These could potentially be exploited for XSS attacks if user-controlled content is processed without proper sanitization. Fix: Validate and sanitize all HTML input sources. Ensure that only legitimate canvas/image/video elements are accepted. Document security requirements for applications using these features.
• Low · Missing Package-lock.json Integrity — package.json - ordered-read-streams: ^2.0.0. While package-lock.json exists, the dependency 'ordered-read-streams' uses a caret (^2.0.0) which allows breaking changes. This can introduce vulnerabilities through transitive dependencies. Fix: Pin all dependencies to specific versions using exact version numbers instead of ranges. Regularly audit and update dependencies intentionally rather than allowing automatic updates.
• Low · No Security Policy or Vulnerability Disclosure Process — Repository root. The repository does not appear to have a SECURITY.md file or documented vulnerability disclosure policy, making it difficult for security researchers to report issues responsibly. Fix: Create a SECURITY.md file documenting how to responsibly report security vulnerabilities. Include contact information and expected response times.
• Low · Insecure Protocol in Documentation URL — package.json - homepage: http://gpu.rocks/. The homepage URL uses http:// instead of https://, which could lead to man-in-the-middle attacks when users visit the project homepage. Fix: Change homepage to use HTTPS: https

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.