PNGine NPM Package

WebGPU bytecode engine for PNG payloads.

Runtime Profiles

PNGine now ships four browser-facing profiles:

| Profile | Import | Purpose | | --- | --- | --- | | Viewer (default) | pngine or pngine/viewer | Lean production player for PNG payloads with embedded executor | | Dev | pngine/dev | Full feature surface for iteration and debugging | | Core | pngine/core | Low-level runtime API (dispatcher-centric) | | Executor | pngine/executor | Advanced payload/executor helper API |

Viewer API (Default)

Usage scenario

Use viewer for normal playback of PNG payloads generated with the default embedded executor.

Input contract

pngine(
  source: string | Uint8Array | ArrayBuffer | Blob,
  options: {
    canvas: HTMLCanvasElement;
    debug?: boolean;
    onError?: (err: Error) => void;
  }
)

Notes:

• canvas is required.
• source can be URL or byte data.
• wasmUrl, selector strings, and HTMLImageElement sources are dev-only features.
• Viewer keeps wasm-in-wasm runtime support enabled by default.
• Viewer supports runtime interactivity via draw(...uniforms), setUniform, setUniforms, and getUniforms.

Example

import { pngine, play } from 'pngine';

const canvas = document.getElementById('canvas');
const p = await pngine('/assets/triangle.png', { canvas });
play(p);

Dev API

Dev profile keeps the full feature set:

• Selector and image-element initialization paths.
• Shared executor fallback (wasmUrl) for payloads without embedded executor.
• Executor helper exports on the same entrypoint.

import { pngine, parsePayload } from 'pngine/dev';

Core API

Core profile is for integrators who already manage device/context/lifecycle.

import { createCoreDispatcher, configureCanvas, getDevice } from 'pngine/core';

Executor API

Advanced helpers for payload parsing and manual executor loading.

import { parsePayload, createExecutor, getExecutorImports } from 'pngine/executor';

Bundle Sizes (Current)

Generated by npm run build on 2026-02-08:

| File | Raw | Gzip | | --- | --- | --- | | viewer.mjs | 27.1 KB | 9.4 KB | | dev.mjs | 29.5 KB | 10.2 KB | | core.mjs | 15.9 KB | 5.4 KB | | executor.mjs | 1.8 KB | 0.9 KB | | index.js (Node stub) | 1.1 KB | - |

Build Commands

# Production bundles
npm run build

# Debug bundles (source maps, DEBUG=true)
npm run build:debug

Dist Files

dist/
├── viewer.mjs
├── dev.mjs
├── core.mjs
├── executor.mjs
├── index.js          # Node CJS stubs
├── index.mjs         # Node ESM stubs
├── index.d.ts        # default (viewer) types
├── viewer.d.ts
├── dev.d.ts
├── core.d.ts
└── executor.d.ts

CLI and Native Binaries

The package also ships the pngine CLI via optional native binaries:

| Package | Platform | | --- | --- | | @pngine/darwin-arm64 | macOS Apple Silicon | | @pngine/darwin-x64 | macOS Intel | | @pngine/linux-x64 | Linux x64 | | @pngine/linux-arm64 | Linux ARM64 | | @pngine/win32-x64 | Windows x64 | | @pngine/win32-arm64 | Windows ARM64 |

License

MIT