Spector.js captures a whole WebGL frame

What a capture contains: commands, state and context

Spector.js records one frame of WebGL activity and turns it into something you can read. The README describes the result as your entire commands list with their associated visual states and context information.

That distinction is the whole point. A browser's built-in WebGL inspector, the one Spector's author says he was a fan of, shows the current state of your context. Spector shows what was called, in what order, and what the context looked like at each call. When a draw call produces the wrong pixels because a uniform was not rebound, only the second view tells you.

The origin story in the README matters for scope. The author describes being a core member of the BabylonJS team, needing to debug a WebGL context, losing the tool he relied on when Babylon introduced WebGL2, and deciding to build one compatible with all WebGL and WebGL2 engines rather than just his own. That is why it is engine-agnostic: the repository topics list webgl, webgl2, webvr, inspector and debugger, and the summary line says it supports all engines and vanilla script usage.

Spector.js is aimed at WebGL developers across engines.

Three ways in: extension, UMD module, script tag

Spector can be used in three configurations, and picking the wrong one costs you time.

The browser extension is the fastest route and requires no code. There are store listings for Chrome and Firefox, plus documentation on how to load the extension from source in the repository.

For code integration, the library is transpiled as a UMD module, so it works as a script reference or through a bundler. The npm package is `spectorjs`:

npm install spectorjs

The README's webpack walkthrough creates a sample directory, installs webpack and webpack-cli plus spectorjs as dev dependencies, and writes an `entry.js` with three lines:

var SPECTOR = require("spectorjs");

var spector = new SPECTOR.Spector();
spector.displayUI();

Bundling is then a single command:

npx webpack entry.js 

As a plain script, the README offers three sources: the jsDelivr CDN at a versioned URL, the `dist` folder in the repository if you self-host, and the `node_modules/spectorjs/dist` copy if you installed from npm. All three resolve to `spector.bundle.js`, and the reference tag is:

<script type="text/javascript" src="https://spectorcdn.babylonjs.com/spector.bundle.js"></script>

captureCanvas, spyCanvases and the onCapture callback

Instantiating the inspector and showing its UI is two calls:

var spector = new SPECTOR.Spector();
spector.displayUI();

The third method is the one to build tooling on. `captureCanvas` takes a canvas element and captures its frame, and `onCapture` is an event you subscribe to in order to receive the result as JSON:

spector.onCapture.add((capture) => {
    var myEvent = new CustomEvent("SpectorOnCaptureEvent", { detail: { captureString: JSON.stringify(capture) } });
    document.dispatchEvent(myEvent);
});

var canvas = document.getElementById("renderCanvas");
spector.captureCanvas(canvas);

The README's example serialises the capture and re-dispatches it as a DOM CustomEvent, which is the pattern to copy if you want to hand a capture to another part of your page or to an automated test rather than just look at it.

`spector.spyCanvases()` is the fourth entry point and the easiest to overlook. The README says it enables complete tracking of the gl calls even before capturing, which gives access to texture inputs and memory consumption information. In other words, it is a continuous instrumentation mode rather than a one-shot snapshot, and that is what you want when the bug is about what was uploaded rather than what was drawn.

There is also a custom data hook: adding a field named `__SPECTOR_Metadata` to your WebGLObj attaches your own data to the capture.

OffscreenCanvas support is split into three modes with different reliability

The table of contents gives OffscreenCanvas its own section with three subsections, and the differences between them are the honest signal about how mature that support is.

There is main-thread OffscreenCanvas, worker OffscreenCanvas described as manual API and recommended, and auto-injection described as best-effort. That labelling is not cosmetic. Manual API means you wire the capture up yourself and get predictable behaviour. Auto-injection means the tool patches canvas creation for you and may or may not attach cleanly, which is exactly the sort of thing that fails on the one browser version you care about.

The repository reflects this. The sample directory includes `workerAutoInject.html` alongside `index.html`, so there is a runnable case for the worker path, and the package publishes two bundles rather than one: `dist/spector.bundle.js` and `dist/spector.worker.bundle.js`. You load the worker bundle in the worker and the main bundle in the page.

For a worker-based renderer, use the manual API with the worker bundle. Do not start with auto-injection.

MCP server and the toolchain around the bundle

The repository now includes an `mcp/` directory and an MCP Server section in the table of contents, which means the capture can be driven from an agent tool rather than only from the UI.

The rest of the toolchain is visible in package.json. The build is webpack: `build:bundle` runs webpack in prod mode against tools/webpack.config.js, and `build:types` runs a bundling script for declaration files. The full build chains tslint, the bundle, the types, two copy steps that push the bundle into an `extensions/` folder, and a concat step that wraps the bundle with a header and footer to produce `spector.bundle.func.js`.

That last file is the browser extension build, which is why the same source produces both the extension and the standalone page version.

Testing is three-layered. The `test` script runs jest unit tests, then Playwright tests, then Playwright again against a separate integration config. A playwright.config.ts and a jest.config.js sit at the repository root. Testing a graphics capture tool is inherently awkward because the thing you assert on is a pixel buffer, and running the same assertions in a unit pass, a browser pass and an integration pass is a reasonable answer to that.

Lint is tslint with a tslint.json config, which is dated but still what the scripts invoke.

Version 0.9.35 in package.json, v0.9.33 as the newest tag

The versioning here is worth pausing on, because the three numbers a reader encounters do not agree.

package.json says version 0.9.35. The README's CDN link points at `[email protected]`, matching that. But the latest GitHub release is v0.9.33, tagged on 2026-09-14, and the release before it is v0.9.27 from 2021-09-26. There is also v0.9.26 from 2021-07-02.

So the repository is being maintained at a steady trickle, with the last push on 2026-10-12, while the tags are sparse and the npm version runs ahead of them.

The 0.9.x line itself has been in place for years, which cuts both ways. It means the API is settled and unlikely to move under you, which is what you want from a debugging tool. It also means the package sits below 1.0, so semver promises nothing about breaking changes.

One naming detail catches people: the npm package is `spectorjs` with no dot and no capital S, while the repository, the docs and the homepage all use Spector.js.

When Spector is the wrong tool

The first boundary is obvious but worth stating: this is for WebGL and WebGL2. If your rendering goes through WebGPU, or through a canvas abstraction that never touches a WebGL context, there is nothing here to capture. The topics list is explicit that this is WebGL.

The second is that a capture is a snapshot, and the problem you have may not be in one frame. `spyCanvases` gives continuous tracking, but a full frame captured under instrumentation is large, and serialising it to JSON and moving it around your page is not free. If your issue is a slow first frame or a memory leak that accumulates over thousands of frames, a per-frame capture tool answers the wrong question.

The third is the production concern. Every example in the README wires Spector into your entry point. That is fine for a development build and wrong for a shipped one, since the inspector is a debugging surface with a UI and no security boundary around what it exposes. Keep it behind a development-only conditional in your own build.

The fourth is engine-agnosticism as a double edge. Supporting all engines means no engine-specific knowledge. Spector focuses on WebGL calls and their context. If your bug is a scene graph or material configuration issue rather than a GL state issue, the wrong tool is a different category of tool.

Against the built-in inspector and against recording instead

There are two other approaches worth comparing honestly.

The browser's own WebGL context is inspectable without any tool. Every modern browser ships a WebGL panel showing current state, and it costs nothing and is always present. What it cannot do is history. Spector's value over it is the per-call state sequence, and the README is candid that the author built it after losing his preferred tool when Babylon moved to WebGL2.

The other approach is not a debugger at all. Video recording of the canvas, or capturing screenshots frame by frame, tells you what the output looked like without telling you why. That is the right tool when the question is visual regression, and Spector is the wrong one because it does not compare renders.

A third is an automated graphics test harness, which asserts on output and fails a build. Spector is not that either, though its onCapture JSON is usable as the input to one, which is the most interesting composition available here.

So the honest summary: use the built-in inspector for current state, Spector for the call history behind one frame, and a capture-and-compare harness for regressions across many frames.

Editorial conclusion

Use Spector.js when you need to see the exact WebGL calls behind a frame and you are working in the browser or in a worker you control. Do not adopt it as a permanent part of a production bundle, since the package is a debugging tool and the README's own examples wire it straight into your entry point. Verify first which version you get, because the README's CDN link points at 0.9.35 while the latest GitHub release tag is v0.9.33 from 2026-09-14, with the previous release dating from 2021.

Frequently asked questions

Official sources

1. BabylonJS/Spector.js on GitHub
2. License: MIT
3. Project website
4. README
5. Releases