insomni-node 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,111 @@
+# insomni-node
+
+Headless Node.js adapter for the [insomni](../insomni) renderer. Runs the full
+GPU pipeline on Dawn/WebGPU (the [`webgpu`](https://www.npmjs.com/package/webgpu)
+npm package) without a browser, canvas, or display server. Designed for
+server-side chart rendering, CI screenshot tests, and PNG export pipelines.
+
+## Install
+
+```sh
+pnpm add insomni-node insomni
+```
+
+`webgpu` (native Dawn addon) is a peer dependency — install it alongside:
+
+```sh
+pnpm add webgpu
+```
+
+Prebuilt Dawn binaries are bundled inside the `webgpu` package. Verified on
+**arm64 macOS**; the `webgpu` package also ships Linux x64 and Windows x64
+binaries (untested by this package).
+
+## API
+
+### `createNodeRenderer(options): Promise<NodeRenderer>`
+
+#### Options
+
+| Option        | Type               | Default                                    | Description                                                                        |
+| ------------- | ------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------- |
+| `width`       | `number`           | required                                   | Offscreen texture width in pixels.                                                 |
+| `height`      | `number`           | required                                   | Offscreen texture height in pixels.                                                |
+| `sampleCount` | `number`           | renderer default (1 or 4)                  | MSAA sample count.                                                                 |
+| `format`      | `GPUTextureFormat` | `navigator.gpu.getPreferredCanvasFormat()` | Color attachment format.                                                           |
+| `gpu`         | `GPUHandle`        | `undefined`                                | Pre-built GPU handle to reuse; when omitted, one is acquired and owned internally. |
+| `persistent`  | `boolean`          | `false`                                    | Accepted for API symmetry; has no effect (no swap chain).                          |
+
+#### Return shape — `NodeRenderer`
+
+| Member                      | Type                    | Description                                                                                                              |
+| --------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `renderer`                  | `Renderer2D`            | Core insomni renderer. Call `renderer.setBackground(rgba(...))` before rendering.                                        |
+| `target`                    | `OffscreenRenderTarget` | The offscreen color+depth textures.                                                                                      |
+| `device`                    | `GPUDevice`             | Underlying WebGPU device.                                                                                                |
+| `frame(layers, maxFrames?)` | `Promise<void>`         | Render `layers` (a `Layer[]`) and drain the GPU queue. `maxFrames` extra ticks help async resources settle (default: 1). |
+| `readPixels()`              | `Promise<PixelData>`    | Copy rendered pixels to CPU as a tight RGBA `Uint8Array`.                                                                |
+| `toPNG(opts?)`              | `Promise<Uint8Array>`   | Render → readback → PNG encode. Returns a `Uint8Array` PNG buffer (unpremultiplied by default).                          |
+| `resize(w, h)`              | `void`                  | Resize the renderer and offscreen target.                                                                                |
+| `dispose()`                 | `void`                  | Destroy the renderer, offscreen target, and (if owned) the GPU handle.                                                   |
+
+## Offscreen-only caveat
+
+`insomni-node` has no swap chain or canvas. `present()` is a no-op. All
+readback goes through `copyTextureToBuffer` (via `readPixels()`). The rendered
+result is only accessible via `readPixels()` or `toPNG()` — there is no
+on-screen display.
+
+## Example
+
+```js
+import { createNodeRenderer } from "insomni-node";
+import { createLayer, rgba } from "insomni";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const W = 256,
+  H = 256;
+const api = await createNodeRenderer({ width: W, height: H });
+api.renderer.setBackground(rgba(0.05, 0.06, 0.09, 1));
+
+const scene = createLayer({ space: "ui" });
+scene.pushRect({
+  x: 32,
+  y: 32,
+  width: 192,
+  height: 192,
+  fill: rgba(0.36, 0.7, 1, 1),
+  cornerRadius: 24,
+});
+scene.pushRect({
+  x: 72,
+  y: 72,
+  width: 112,
+  height: 112,
+  fill: rgba(0.96, 0.45, 0.62, 1),
+  cornerRadius: 16,
+});
+
+await api.frame([scene]);
+const png = await api.toPNG();
+
+const outDir = join(dirname(fileURLToPath(import.meta.url)), "..", ".dev-shots");
+mkdirSync(outDir, { recursive: true });
+const outPath = join(outDir, "smoke.png");
+writeFileSync(outPath, png);
+console.log(`wrote ${outPath} (${png.byteLength} bytes)`);
+api.dispose();
+```
+
+Run it after building the package:
+
+```sh
+node packages/insomni-node/examples/smoke.mjs
+```
+
+## Further reading
+
+The downstream integration plan (migrating the demo harness to Dawn):
+[`plans/dawn-node-webgpu-migration.md`](../../plans/dawn-node-webgpu-migration.md)

package/dist/index.d.mts

@@ -0,0 +1,156 @@
+import { CanvasContext, PostAaPass, RenderTarget } from "insomni/internal";
+import { GPUHandle, Layer, Renderer2D, createRenderer } from "insomni";
+import { TgpuRoot } from "typegpu";
+
+//#region src/gpu.d.ts
+/**
+ * Installs the Dawn/WebGPU native adapter into the Node.js global scope.
+ * Safe to call multiple times — idempotent.
+ */
+declare function isNodeGPUInstalled(): boolean;
+declare function installNodeGPU(): void;
+//#endregion
+//#region src/offscreen-target.d.ts
+interface OffscreenTargetOptions {
+  width: number;
+  height: number;
+  format?: GPUTextureFormat;
+  sampleCount?: number;
+}
+/**
+ * A {@link RenderTarget} that renders into an owned GPU texture (no canvas/
+ * swap chain). The texture is created with `COPY_SRC` usage so it can be read
+ * back to CPU via `copyTextureToBuffer`. `present()` is a no-op — readback is
+ * the caller's responsibility via `colorTexture`.
+ */
+declare class OffscreenRenderTarget implements RenderTarget {
+  readonly format: GPUTextureFormat;
+  readonly context: CanvasContext;
+  private _width;
+  private _height;
+  private readonly sampleCount;
+  private readonly root;
+  /** The owned single-sample color texture. Used for GPU readback. */
+  private _colorTex;
+  private _colorView;
+  /** Scratch texture for in-place FXAA (copy colorTex → scratch, FXAA scratch → colorTex). */
+  private _scratchTex;
+  private _scratchView;
+  constructor(root: TgpuRoot, opts: OffscreenTargetOptions);
+  get width(): number;
+  get height(): number;
+  /** The owned color texture — pass to `readPixels()` for CPU readback. */
+  get colorTexture(): GPUTexture;
+  acquireColorView(): GPUTextureView;
+  present(encoder: GPUCommandEncoder, postAa?: PostAaPass | null): void;
+  resize(width: number, height: number): void;
+  destroy(): void;
+  private _createColorTexture;
+  private _createScratchTexture;
+}
+//#endregion
+//#region src/read-pixels.d.ts
+/**
+ * GPU texture → CPU pixel readback for Node.js.
+ *
+ * Mirrors the alignment/unstride logic from insomni's internal
+ * `pixel-readback.ts`, with an explicit `format` parameter so the caller can
+ * request BGRA→RGBA normalization. Output alpha state: whatever the renderer
+ * produced (premultiplied); unpremultiply happens downstream in `toPNG`.
+ */
+interface PixelData {
+  data: Uint8Array;
+  width: number;
+  height: number;
+}
+/**
+ * Read all pixels from a GPU texture into a tight Uint8Array (RGBA, row-major).
+ *
+ * - `format` drives the BGRA→RGBA channel swap: pass the texture's actual
+ *   format (e.g. `"bgra8unorm"`) so the output is always canonical RGBA.
+ * - The texture MUST have `GPUTextureUsage.COPY_SRC`.
+ * - Unmaps and destroys the staging buffer before resolving.
+ */
+declare function readPixels(device: GPUDevice, texture: GPUTexture, width: number, height: number, format: GPUTextureFormat): Promise<PixelData>;
+//#endregion
+//#region src/png.d.ts
+interface ToPNGOptions {
+  /**
+   * Whether the pixel data has premultiplied alpha (insomni renders with
+   * premultiplied alpha by default). When true, each channel is divided by
+   * alpha before encoding so the PNG stores straight alpha.
+   * Default: true.
+   */
+  premultiplied?: boolean;
+}
+/**
+ * Encode a {@link PixelData} (tight RGBA Uint8Array) to a PNG buffer.
+ *
+ * When `premultiplied` is true (the default), the function unpremultiplies
+ * each pixel before encoding: `straight_c = alpha > 0 ? min(255, round(c * 255 / alpha)) : 0`.
+ *
+ * Returns a Uint8Array whose first 8 bytes are the PNG magic signature.
+ */
+declare function toPNG(pixels: PixelData, opts?: ToPNGOptions): Uint8Array;
+//#endregion
+//#region src/frame-loop.d.ts
+interface RenderSettledOptions {
+  maxFrames?: number;
+  fullFrame?: boolean;
+}
+/**
+ * Render `layers` and wait for the GPU queue to drain.
+ *
+ * Calls `renderer.render(layers, { fullFrame })` `maxFrames` times (default 1;
+ * extra ticks help async resources settle), then `await
+ * device.queue.onSubmittedWorkDone()` to ensure readback sees a complete frame.
+ * No rAF, no clock, no needsFrame.
+ */
+declare function renderSettled(renderer: Renderer2D, layers: Layer[], opts?: RenderSettledOptions): Promise<void>;
+//#endregion
+//#region src/renderer.d.ts
+interface CreateNodeRendererOptions {
+  width: number;
+  height: number;
+  sampleCount?: number;
+  format?: GPUTextureFormat;
+  /**
+   * A pre-built {@link GPUHandle} to reuse. When omitted, `initGPU()` is
+   * called internally and the handle is owned by the returned renderer
+   * (destroyed on `dispose()`).
+   */
+  gpu?: GPUHandle;
+  /**
+   * Accepted for API symmetry but has no effect for offscreen targets — there
+   * is no swap chain to blit into. Defaults to `false`.
+   */
+  persistent?: boolean;
+}
+interface NodeRenderer {
+  renderer: ReturnType<typeof createRenderer>;
+  target: OffscreenRenderTarget;
+  device: GPUDevice;
+  /**
+   * Render `layers` and wait for the GPU queue to drain.
+   * `maxFrames` extra ticks help async resources settle (default: 1).
+   */
+  frame(layers: Layer[], maxFrames?: number): Promise<void>;
+  /** Copy the rendered pixels to CPU as a tight RGBA Uint8Array. */
+  readPixels(): Promise<PixelData>;
+  /** Render → readback → PNG encode. Returns a Uint8Array PNG buffer. */
+  toPNG(opts?: ToPNGOptions): Promise<Uint8Array>;
+  /** Resize the renderer and offscreen target. */
+  resize(width: number, height: number): void;
+  /** Destroy the renderer, offscreen target, and (if owned) the GPU handle. */
+  dispose(): void;
+}
+/**
+ * Create a headless insomni renderer suitable for use in Node.js.
+ *
+ * Installs Dawn/WebGPU into the global scope (idempotent), acquires a GPU
+ * adapter+device via `initGPU`, builds an {@link OffscreenRenderTarget}, and
+ * wires a `Renderer2D` through it — canvas-free.
+ */
+declare function createNodeRenderer(options: CreateNodeRendererOptions): Promise<NodeRenderer>;
+//#endregion
+export { type CreateNodeRendererOptions, type NodeRenderer, OffscreenRenderTarget, type OffscreenTargetOptions, type PixelData, type RenderSettledOptions, type ToPNGOptions, createNodeRenderer, installNodeGPU, isNodeGPUInstalled, readPixels, renderSettled, toPNG };

package/dist/index.mjs

@@ -0,0 +1,336 @@
+import { createRequire } from "node:module";
+import { createDepth, createMsaaColor } from "insomni/internal";
+import { encode } from "fast-png";
+import { createRenderer, initGPU } from "insomni";
+//#region src/gpu.ts
+const requireWebgpu = createRequire(import.meta.url);
+/**
+* Installs the Dawn/WebGPU native adapter into the Node.js global scope.
+* Safe to call multiple times — idempotent.
+*/
+function isNodeGPUInstalled() {
+	return typeof navigator !== "undefined" && !!navigator.gpu;
+}
+function installNodeGPU() {
+	if (isNodeGPUInstalled()) return;
+	const { create, globals } = requireWebgpu("webgpu");
+	const gpu = create([]);
+	Object.defineProperty(globalThis, "navigator", {
+		value: { gpu },
+		writable: true,
+		configurable: true
+	});
+	for (const [k, v] of Object.entries(globals)) globalThis[k] = v;
+}
+//#endregion
+//#region src/offscreen-target.ts
+/**
+* A {@link RenderTarget} that renders into an owned GPU texture (no canvas/
+* swap chain). The texture is created with `COPY_SRC` usage so it can be read
+* back to CPU via `copyTextureToBuffer`. `present()` is a no-op — readback is
+* the caller's responsibility via `colorTexture`.
+*/
+var OffscreenRenderTarget = class {
+	format;
+	context;
+	_width;
+	_height;
+	sampleCount;
+	root;
+	/** The owned single-sample color texture. Used for GPU readback. */
+	_colorTex;
+	_colorView;
+	/** Scratch texture for in-place FXAA (copy colorTex → scratch, FXAA scratch → colorTex). */
+	_scratchTex;
+	_scratchView;
+	constructor(root, opts) {
+		this.root = root;
+		this._width = Math.max(1, Math.floor(opts.width));
+		this._height = Math.max(1, Math.floor(opts.height));
+		this.format = opts.format ?? navigator.gpu.getPreferredCanvasFormat();
+		this.sampleCount = opts.sampleCount ?? 1;
+		this._colorTex = this._createColorTexture();
+		this._colorView = this._colorTex.createView();
+		this._scratchTex = this._createScratchTexture();
+		this._scratchView = this._scratchTex.createView();
+		const depth = createDepth(root, this._width, this._height, this.sampleCount);
+		const msaa = createMsaaColor(root, this._width, this._height, this.format, this.sampleCount);
+		this.context = {
+			canvas: {
+				width: this._width,
+				height: this._height
+			},
+			gpuContext: void 0,
+			format: this.format,
+			width: this._width,
+			height: this._height,
+			sampleCount: this.sampleCount,
+			colorTexture: msaa?.texture ?? null,
+			colorView: msaa?.view ?? null,
+			depthTexture: depth.depthTexture,
+			depthView: depth.depthView,
+			persistent: false,
+			backbuffer: null,
+			backbufferView: null
+		};
+	}
+	get width() {
+		return this._width;
+	}
+	get height() {
+		return this._height;
+	}
+	/** The owned color texture — pass to `readPixels()` for CPU readback. */
+	get colorTexture() {
+		return this._colorTex;
+	}
+	acquireColorView() {
+		return this._colorView;
+	}
+	present(encoder, postAa) {
+		if (!postAa) return;
+		encoder.copyTextureToTexture({ texture: this._colorTex }, { texture: this._scratchTex }, {
+			width: this._width,
+			height: this._height,
+			depthOrArrayLayers: 1
+		});
+		postAa.encode(encoder, this._scratchView, this._colorView, this._width, this._height);
+	}
+	resize(width, height) {
+		const w = Math.max(1, Math.floor(width));
+		const h = Math.max(1, Math.floor(height));
+		this._width = w;
+		this._height = h;
+		this.context.width = w;
+		this.context.height = h;
+		this.context.canvas.width = w;
+		this.context.canvas.height = h;
+		this._colorTex.destroy();
+		this._colorTex = this._createColorTexture();
+		this._colorView = this._colorTex.createView();
+		this._scratchTex.destroy();
+		this._scratchTex = this._createScratchTexture();
+		this._scratchView = this._scratchTex.createView();
+		this.context.depthTexture.destroy();
+		const depth = createDepth(this.root, w, h, this.sampleCount);
+		this.context.depthTexture = depth.depthTexture;
+		this.context.depthView = depth.depthView;
+		if (this.context.colorTexture) this.context.colorTexture.destroy();
+		const msaa = createMsaaColor(this.root, w, h, this.format, this.sampleCount);
+		this.context.colorTexture = msaa?.texture ?? null;
+		this.context.colorView = msaa?.view ?? null;
+	}
+	destroy() {
+		this._colorTex.destroy();
+		this._scratchTex.destroy();
+		this.context.depthTexture.destroy();
+		if (this.context.colorTexture) this.context.colorTexture.destroy();
+	}
+	_createColorTexture() {
+		return this.root.device.createTexture({
+			label: "insomni-node-offscreen-color",
+			size: [this._width, this._height],
+			format: this.format,
+			sampleCount: 1,
+			usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC | GPUTextureUsage.TEXTURE_BINDING
+		});
+	}
+	_createScratchTexture() {
+		return this.root.device.createTexture({
+			label: "insomni-node-offscreen-scratch",
+			size: [this._width, this._height],
+			format: this.format,
+			sampleCount: 1,
+			usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_DST | GPUTextureUsage.TEXTURE_BINDING
+		});
+	}
+};
+//#endregion
+//#region src/read-pixels.ts
+/**
+* GPU texture → CPU pixel readback for Node.js.
+*
+* Mirrors the alignment/unstride logic from insomni's internal
+* `pixel-readback.ts`, with an explicit `format` parameter so the caller can
+* request BGRA→RGBA normalization. Output alpha state: whatever the renderer
+* produced (premultiplied); unpremultiply happens downstream in `toPNG`.
+*/
+/** 256-byte alignment required by WebGPU `bytesPerRow` in `copyTextureToBuffer`. */
+const BYTES_PER_ROW_ALIGNMENT = 256;
+/** Bytes per RGBA pixel (8 bits per channel). */
+const BYTES_PER_PIXEL = 4;
+function alignUp(n, alignment) {
+	return Math.ceil(n / alignment) * alignment;
+}
+/**
+* Read all pixels from a GPU texture into a tight Uint8Array (RGBA, row-major).
+*
+* - `format` drives the BGRA→RGBA channel swap: pass the texture's actual
+*   format (e.g. `"bgra8unorm"`) so the output is always canonical RGBA.
+* - The texture MUST have `GPUTextureUsage.COPY_SRC`.
+* - Unmaps and destroys the staging buffer before resolving.
+*/
+async function readPixels(device, texture, width, height, format) {
+	const tightBytesPerRow = width * BYTES_PER_PIXEL;
+	const paddedBytesPerRow = alignUp(tightBytesPerRow, BYTES_PER_ROW_ALIGNMENT);
+	const stagingSize = paddedBytesPerRow * height;
+	const stagingBuffer = device.createBuffer({
+		label: "insomni-node-pixel-readback",
+		size: stagingSize,
+		usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+	});
+	const encoder = device.createCommandEncoder({ label: "insomni-node-readback" });
+	encoder.copyTextureToBuffer({
+		texture,
+		mipLevel: 0,
+		origin: {
+			x: 0,
+			y: 0,
+			z: 0
+		}
+	}, {
+		buffer: stagingBuffer,
+		bytesPerRow: paddedBytesPerRow,
+		rowsPerImage: height
+	}, {
+		width,
+		height,
+		depthOrArrayLayers: 1
+	});
+	device.queue.submit([encoder.finish()]);
+	await device.queue.onSubmittedWorkDone();
+	await stagingBuffer.mapAsync(GPUMapMode.READ, 0, stagingSize);
+	const mapped = new Uint8Array(stagingBuffer.getMappedRange(0, stagingSize));
+	const tight = new Uint8Array(width * height * BYTES_PER_PIXEL);
+	for (let row = 0; row < height; row++) {
+		const srcOffset = row * paddedBytesPerRow;
+		const dstOffset = row * tightBytesPerRow;
+		tight.set(mapped.subarray(srcOffset, srcOffset + tightBytesPerRow), dstOffset);
+	}
+	stagingBuffer.unmap();
+	stagingBuffer.destroy();
+	if (format === "bgra8unorm") for (let i = 0; i < tight.length; i += BYTES_PER_PIXEL) {
+		const b = tight[i];
+		tight[i] = tight[i + 2];
+		tight[i + 2] = b;
+	}
+	return {
+		data: tight,
+		width,
+		height
+	};
+}
+//#endregion
+//#region src/png.ts
+/**
+* Encode a {@link PixelData} (tight RGBA Uint8Array) to a PNG buffer.
+*
+* When `premultiplied` is true (the default), the function unpremultiplies
+* each pixel before encoding: `straight_c = alpha > 0 ? min(255, round(c * 255 / alpha)) : 0`.
+*
+* Returns a Uint8Array whose first 8 bytes are the PNG magic signature.
+*/
+function toPNG(pixels, opts = {}) {
+	const { premultiplied = true } = opts;
+	const { data, width, height } = pixels;
+	let source = data;
+	if (premultiplied) {
+		source = new Uint8Array(data.length);
+		for (let i = 0; i < data.length; i += 4) {
+			const a = data[i + 3];
+			if (a === 0) {
+				source[i] = 0;
+				source[i + 1] = 0;
+				source[i + 2] = 0;
+				source[i + 3] = 0;
+			} else if (a === 255) {
+				source[i] = data[i];
+				source[i + 1] = data[i + 1];
+				source[i + 2] = data[i + 2];
+				source[i + 3] = 255;
+			} else {
+				source[i] = Math.min(255, Math.round(data[i] * 255 / a));
+				source[i + 1] = Math.min(255, Math.round(data[i + 1] * 255 / a));
+				source[i + 2] = Math.min(255, Math.round(data[i + 2] * 255 / a));
+				source[i + 3] = a;
+			}
+		}
+	}
+	return encode({
+		width,
+		height,
+		data: source,
+		channels: 4,
+		depth: 8
+	});
+}
+//#endregion
+//#region src/frame-loop.ts
+/**
+* Render `layers` and wait for the GPU queue to drain.
+*
+* Calls `renderer.render(layers, { fullFrame })` `maxFrames` times (default 1;
+* extra ticks help async resources settle), then `await
+* device.queue.onSubmittedWorkDone()` to ensure readback sees a complete frame.
+* No rAF, no clock, no needsFrame.
+*/
+async function renderSettled(renderer, layers, opts = {}) {
+	const { maxFrames = 1, fullFrame = true } = opts;
+	for (let i = 0; i < maxFrames; i++) renderer.render(layers, { fullFrame });
+	await renderer.device.queue.onSubmittedWorkDone();
+}
+//#endregion
+//#region src/renderer.ts
+/**
+* Create a headless insomni renderer suitable for use in Node.js.
+*
+* Installs Dawn/WebGPU into the global scope (idempotent), acquires a GPU
+* adapter+device via `initGPU`, builds an {@link OffscreenRenderTarget}, and
+* wires a `Renderer2D` through it — canvas-free.
+*/
+async function createNodeRenderer(options) {
+	installNodeGPU();
+	const { width, height, sampleCount, gpu: providedGpu } = options;
+	const format = options.format ?? navigator.gpu.getPreferredCanvasFormat();
+	const ownedGpu = !providedGpu;
+	const handle = providedGpu ?? await initGPU();
+	const target = new OffscreenRenderTarget(handle.root, {
+		width,
+		height,
+		format,
+		sampleCount
+	});
+	const stubCanvas = {
+		width,
+		height
+	};
+	const renderer = createRenderer(handle.root, stubCanvas, {
+		target,
+		format
+	});
+	const self = {
+		renderer,
+		target,
+		device: handle.device,
+		async frame(layers, maxFrames) {
+			await renderSettled(renderer, layers, { maxFrames });
+		},
+		async readPixels() {
+			return readPixels(handle.device, target.colorTexture, target.width, target.height, format);
+		},
+		async toPNG(opts) {
+			return toPNG(await self.readPixels(), opts);
+		},
+		resize(w, h) {
+			renderer.resize(w, h);
+		},
+		dispose() {
+			renderer.destroy();
+			target.destroy();
+			if (ownedGpu) handle.destroy();
+		}
+	};
+	return self;
+}
+//#endregion
+export { OffscreenRenderTarget, createNodeRenderer, installNodeGPU, isNodeGPUInstalled, readPixels, renderSettled, toPNG };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "insomni-node",
+  "version": "0.1.0-alpha.1",
+  "description": "Headless Node adapter for the insomni renderer (Dawn/WebGPU).",
+  "license": "GPL-3.0",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fast-png": "^6.2.0",
+    "webgpu": "^0.4.0",
+    "insomni": "0.2.0-alpha.1"
+  },
+  "peerDependencies": {
+    "typegpu": "^0.10.2"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}

package/src/frame-loop.ts

@@ -0,0 +1,28 @@
+import type { Renderer2D, Layer } from "insomni";
+
+export interface RenderSettledOptions {
+  maxFrames?: number;
+  fullFrame?: boolean;
+}
+
+/**
+ * Render `layers` and wait for the GPU queue to drain.
+ *
+ * Calls `renderer.render(layers, { fullFrame })` `maxFrames` times (default 1;
+ * extra ticks help async resources settle), then `await
+ * device.queue.onSubmittedWorkDone()` to ensure readback sees a complete frame.
+ * No rAF, no clock, no needsFrame.
+ */
+export async function renderSettled(
+  renderer: Renderer2D,
+  layers: Layer[],
+  opts: RenderSettledOptions = {},
+): Promise<void> {
+  const { maxFrames = 1, fullFrame = true } = opts;
+
+  for (let i = 0; i < maxFrames; i++) {
+    renderer.render(layers, { fullFrame });
+  }
+
+  await renderer.device.queue.onSubmittedWorkDone();
+}

package/src/gpu.ts

@@ -0,0 +1,35 @@
+import { createRequire } from "node:module";
+
+const requireWebgpu = createRequire(import.meta.url);
+
+/**
+ * Installs the Dawn/WebGPU native adapter into the Node.js global scope.
+ * Safe to call multiple times — idempotent.
+ */
+export function isNodeGPUInstalled(): boolean {
+  return typeof navigator !== "undefined" && !!navigator.gpu;
+}
+
+export function installNodeGPU(): void {
+  if (isNodeGPUInstalled()) return;
+
+  const { create, globals } = requireWebgpu("webgpu") as {
+    create: (flags: string[]) => GPU;
+    globals: Record<string, unknown>;
+    isMac: boolean;
+  };
+
+  const gpu = create([]);
+
+  // Node's `navigator` is a read-only getter on globalThis; use defineProperty.
+  Object.defineProperty(globalThis, "navigator", {
+    value: { gpu },
+    writable: true,
+    configurable: true,
+  });
+
+  // Install GPU* constant namespaces (GPUBufferUsage, GPUTextureUsage, etc.)
+  for (const [k, v] of Object.entries(globals)) {
+    (globalThis as Record<string, unknown>)[k] = v;
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// insomni-node — headless Node.js adapter for the insomni renderer (Dawn/WebGPU)
+
+export { installNodeGPU, isNodeGPUInstalled } from "./gpu.ts";
+export { OffscreenRenderTarget } from "./offscreen-target.ts";
+export type { OffscreenTargetOptions } from "./offscreen-target.ts";
+export { readPixels } from "./read-pixels.ts";
+export type { PixelData } from "./read-pixels.ts";
+export { toPNG } from "./png.ts";
+export type { ToPNGOptions } from "./png.ts";
+export { renderSettled } from "./frame-loop.ts";
+export type { RenderSettledOptions } from "./frame-loop.ts";
+export { createNodeRenderer } from "./renderer.ts";
+export type { CreateNodeRendererOptions, NodeRenderer } from "./renderer.ts";

package/src/offscreen-target.ts

@@ -0,0 +1,170 @@
+import type { TgpuRoot } from "typegpu";
+import type { CanvasContext, RenderTarget } from "insomni/internal";
+import { createDepth, createMsaaColor } from "insomni/internal";
+import type { PostAaPass } from "insomni/internal";
+
+export interface OffscreenTargetOptions {
+  width: number;
+  height: number;
+  format?: GPUTextureFormat;
+  sampleCount?: number;
+}
+
+/**
+ * A {@link RenderTarget} that renders into an owned GPU texture (no canvas/
+ * swap chain). The texture is created with `COPY_SRC` usage so it can be read
+ * back to CPU via `copyTextureToBuffer`. `present()` is a no-op — readback is
+ * the caller's responsibility via `colorTexture`.
+ */
+export class OffscreenRenderTarget implements RenderTarget {
+  readonly format: GPUTextureFormat;
+  readonly context: CanvasContext;
+
+  private _width: number;
+  private _height: number;
+  private readonly sampleCount: number;
+  private readonly root: TgpuRoot;
+
+  /** The owned single-sample color texture. Used for GPU readback. */
+  private _colorTex: GPUTexture;
+  private _colorView: GPUTextureView;
+
+  /** Scratch texture for in-place FXAA (copy colorTex → scratch, FXAA scratch → colorTex). */
+  private _scratchTex: GPUTexture;
+  private _scratchView: GPUTextureView;
+
+  constructor(root: TgpuRoot, opts: OffscreenTargetOptions) {
+    this.root = root;
+    this._width = Math.max(1, Math.floor(opts.width));
+    this._height = Math.max(1, Math.floor(opts.height));
+    this.format = opts.format ?? navigator.gpu.getPreferredCanvasFormat();
+    this.sampleCount = opts.sampleCount ?? 1;
+
+    this._colorTex = this._createColorTexture();
+    this._colorView = this._colorTex.createView();
+
+    this._scratchTex = this._createScratchTexture();
+    this._scratchView = this._scratchTex.createView();
+
+    const depth = createDepth(root, this._width, this._height, this.sampleCount);
+    const msaa = createMsaaColor(root, this._width, this._height, this.format, this.sampleCount);
+
+    // Stub canvas — only width/height are accessed by the renderer.
+    const stubCanvas = { width: this._width, height: this._height } as unknown as HTMLCanvasElement;
+    // gpuContext is never accessed by the frame loop for an offscreen target.
+    const stubGpuContext = undefined as unknown as GPUCanvasContext;
+
+    this.context = {
+      canvas: stubCanvas,
+      gpuContext: stubGpuContext,
+      format: this.format,
+      width: this._width,
+      height: this._height,
+      sampleCount: this.sampleCount,
+      // colorTexture/colorView are MSAA textures (null when sampleCount <= 1)
+      colorTexture: msaa?.texture ?? null,
+      colorView: msaa?.view ?? null,
+      depthTexture: depth.depthTexture,
+      depthView: depth.depthView,
+      persistent: false,
+      backbuffer: null,
+      backbufferView: null,
+    };
+  }
+
+  get width(): number {
+    return this._width;
+  }
+
+  get height(): number {
+    return this._height;
+  }
+
+  /** The owned color texture — pass to `readPixels()` for CPU readback. */
+  get colorTexture(): GPUTexture {
+    return this._colorTex;
+  }
+
+  acquireColorView(): GPUTextureView {
+    return this._colorView;
+  }
+
+  present(encoder: GPUCommandEncoder, postAa?: PostAaPass | null): void {
+    if (!postAa) return; // legacy: readback reads colorTexture as-is
+    // No partial redraw offscreen: FXAA in place. copy color -> scratch, FXAA scratch -> color.
+    encoder.copyTextureToTexture(
+      { texture: this._colorTex },
+      { texture: this._scratchTex },
+      { width: this._width, height: this._height, depthOrArrayLayers: 1 },
+    );
+    postAa.encode(encoder, this._scratchView, this._colorView, this._width, this._height);
+  }
+
+  resize(width: number, height: number): void {
+    const w = Math.max(1, Math.floor(width));
+    const h = Math.max(1, Math.floor(height));
+    this._width = w;
+    this._height = h;
+
+    // Update context sizing fields (renderer reads these via frameCtx)
+    this.context.width = w;
+    this.context.height = h;
+    (this.context.canvas as unknown as { width: number; height: number }).width = w;
+    (this.context.canvas as unknown as { width: number; height: number }).height = h;
+
+    // Recreate owned color texture
+    this._colorTex.destroy();
+    this._colorTex = this._createColorTexture();
+    this._colorView = this._colorTex.createView();
+
+    // Recreate scratch texture
+    this._scratchTex.destroy();
+    this._scratchTex = this._createScratchTexture();
+    this._scratchView = this._scratchTex.createView();
+
+    // Recreate depth
+    this.context.depthTexture.destroy();
+    const depth = createDepth(this.root, w, h, this.sampleCount);
+    this.context.depthTexture = depth.depthTexture;
+    this.context.depthView = depth.depthView;
+
+    // Recreate MSAA if active
+    if (this.context.colorTexture) this.context.colorTexture.destroy();
+    const msaa = createMsaaColor(this.root, w, h, this.format, this.sampleCount);
+    this.context.colorTexture = msaa?.texture ?? null;
+    this.context.colorView = msaa?.view ?? null;
+  }
+
+  destroy(): void {
+    this._colorTex.destroy();
+    this._scratchTex.destroy();
+    this.context.depthTexture.destroy();
+    if (this.context.colorTexture) this.context.colorTexture.destroy();
+  }
+
+  private _createColorTexture(): GPUTexture {
+    return this.root.device.createTexture({
+      label: "insomni-node-offscreen-color",
+      size: [this._width, this._height],
+      format: this.format,
+      sampleCount: 1,
+      usage:
+        GPUTextureUsage.RENDER_ATTACHMENT |
+        GPUTextureUsage.COPY_SRC |
+        GPUTextureUsage.TEXTURE_BINDING,
+    });
+  }
+
+  private _createScratchTexture(): GPUTexture {
+    return this.root.device.createTexture({
+      label: "insomni-node-offscreen-scratch",
+      size: [this._width, this._height],
+      format: this.format,
+      sampleCount: 1,
+      usage:
+        GPUTextureUsage.RENDER_ATTACHMENT |
+        GPUTextureUsage.COPY_DST |
+        GPUTextureUsage.TEXTURE_BINDING,
+    });
+  }
+}

package/src/png.ts

@@ -0,0 +1,63 @@
+import { encode } from "fast-png";
+import type { PixelData } from "./read-pixels.ts";
+
+export interface ToPNGOptions {
+  /**
+   * Whether the pixel data has premultiplied alpha (insomni renders with
+   * premultiplied alpha by default). When true, each channel is divided by
+   * alpha before encoding so the PNG stores straight alpha.
+   * Default: true.
+   */
+  premultiplied?: boolean;
+}
+
+/**
+ * Encode a {@link PixelData} (tight RGBA Uint8Array) to a PNG buffer.
+ *
+ * When `premultiplied` is true (the default), the function unpremultiplies
+ * each pixel before encoding: `straight_c = alpha > 0 ? min(255, round(c * 255 / alpha)) : 0`.
+ *
+ * Returns a Uint8Array whose first 8 bytes are the PNG magic signature.
+ */
+export function toPNG(pixels: PixelData, opts: ToPNGOptions = {}): Uint8Array {
+  const { premultiplied = true } = opts;
+  const { data, width, height } = pixels;
+
+  let source = data;
+
+  if (premultiplied) {
+    // Unpremultiply into a fresh copy so we don't mutate the caller's buffer.
+    source = new Uint8Array(data.length);
+    for (let i = 0; i < data.length; i += 4) {
+      const a = data[i + 3];
+      if (a === 0) {
+        // Fully transparent — leave R/G/B as 0.
+        source[i] = 0;
+        source[i + 1] = 0;
+        source[i + 2] = 0;
+        source[i + 3] = 0;
+      } else if (a === 255) {
+        // Fully opaque — no-op.
+        source[i] = data[i];
+        source[i + 1] = data[i + 1];
+        source[i + 2] = data[i + 2];
+        source[i + 3] = 255;
+      } else {
+        source[i] = Math.min(255, Math.round((data[i] * 255) / a));
+        source[i + 1] = Math.min(255, Math.round((data[i + 1] * 255) / a));
+        source[i + 2] = Math.min(255, Math.round((data[i + 2] * 255) / a));
+        source[i + 3] = a;
+      }
+    }
+  }
+
+  const png = encode({
+    width,
+    height,
+    data: source,
+    channels: 4,
+    depth: 8,
+  });
+
+  return png;
+}

package/src/read-pixels.ts

@@ -0,0 +1,86 @@
+/**
+ * GPU texture → CPU pixel readback for Node.js.
+ *
+ * Mirrors the alignment/unstride logic from insomni's internal
+ * `pixel-readback.ts`, with an explicit `format` parameter so the caller can
+ * request BGRA→RGBA normalization. Output alpha state: whatever the renderer
+ * produced (premultiplied); unpremultiply happens downstream in `toPNG`.
+ */
+
+/** 256-byte alignment required by WebGPU `bytesPerRow` in `copyTextureToBuffer`. */
+const BYTES_PER_ROW_ALIGNMENT = 256;
+
+/** Bytes per RGBA pixel (8 bits per channel). */
+const BYTES_PER_PIXEL = 4;
+
+function alignUp(n: number, alignment: number): number {
+  return Math.ceil(n / alignment) * alignment;
+}
+
+export interface PixelData {
+  data: Uint8Array;
+  width: number;
+  height: number;
+}
+
+/**
+ * Read all pixels from a GPU texture into a tight Uint8Array (RGBA, row-major).
+ *
+ * - `format` drives the BGRA→RGBA channel swap: pass the texture's actual
+ *   format (e.g. `"bgra8unorm"`) so the output is always canonical RGBA.
+ * - The texture MUST have `GPUTextureUsage.COPY_SRC`.
+ * - Unmaps and destroys the staging buffer before resolving.
+ */
+export async function readPixels(
+  device: GPUDevice,
+  texture: GPUTexture,
+  width: number,
+  height: number,
+  format: GPUTextureFormat,
+): Promise<PixelData> {
+  const tightBytesPerRow = width * BYTES_PER_PIXEL;
+  const paddedBytesPerRow = alignUp(tightBytesPerRow, BYTES_PER_ROW_ALIGNMENT);
+  const stagingSize = paddedBytesPerRow * height;
+
+  const stagingBuffer = device.createBuffer({
+    label: "insomni-node-pixel-readback",
+    size: stagingSize,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+  });
+
+  const encoder = device.createCommandEncoder({ label: "insomni-node-readback" });
+  encoder.copyTextureToBuffer(
+    { texture, mipLevel: 0, origin: { x: 0, y: 0, z: 0 } },
+    { buffer: stagingBuffer, bytesPerRow: paddedBytesPerRow, rowsPerImage: height },
+    { width, height, depthOrArrayLayers: 1 },
+  );
+  device.queue.submit([encoder.finish()]);
+
+  await device.queue.onSubmittedWorkDone();
+  await stagingBuffer.mapAsync(GPUMapMode.READ, 0, stagingSize);
+
+  const mapped = new Uint8Array(stagingBuffer.getMappedRange(0, stagingSize));
+
+  // Unstride: copy only the tight row data (strip 256-byte-aligned padding).
+  const tight = new Uint8Array(width * height * BYTES_PER_PIXEL);
+  for (let row = 0; row < height; row++) {
+    const srcOffset = row * paddedBytesPerRow;
+    const dstOffset = row * tightBytesPerRow;
+    tight.set(mapped.subarray(srcOffset, srcOffset + tightBytesPerRow), dstOffset);
+  }
+
+  stagingBuffer.unmap();
+  stagingBuffer.destroy();
+
+  // Normalize BGRA → RGBA when the texture format is bgra8unorm (the typical
+  // preferred canvas format on macOS/Windows).
+  if (format === "bgra8unorm") {
+    for (let i = 0; i < tight.length; i += BYTES_PER_PIXEL) {
+      const b = tight[i];
+      tight[i] = tight[i + 2]; // R ← B
+      tight[i + 2] = b; // B ← R
+    }
+  }
+
+  return { data: tight, width, height };
+}

package/src/renderer.ts

@@ -0,0 +1,102 @@
+import { initGPU, createRenderer, type GPUHandle, type Layer } from "insomni";
+import { installNodeGPU } from "./gpu.ts";
+import { OffscreenRenderTarget } from "./offscreen-target.ts";
+import { readPixels, type PixelData } from "./read-pixels.ts";
+import { toPNG, type ToPNGOptions } from "./png.ts";
+import { renderSettled } from "./frame-loop.ts";
+
+export interface CreateNodeRendererOptions {
+  width: number;
+  height: number;
+  sampleCount?: number;
+  format?: GPUTextureFormat;
+  /**
+   * A pre-built {@link GPUHandle} to reuse. When omitted, `initGPU()` is
+   * called internally and the handle is owned by the returned renderer
+   * (destroyed on `dispose()`).
+   */
+  gpu?: GPUHandle;
+  /**
+   * Accepted for API symmetry but has no effect for offscreen targets — there
+   * is no swap chain to blit into. Defaults to `false`.
+   */
+  persistent?: boolean;
+}
+
+export interface NodeRenderer {
+  renderer: ReturnType<typeof createRenderer>;
+  target: OffscreenRenderTarget;
+  device: GPUDevice;
+  /**
+   * Render `layers` and wait for the GPU queue to drain.
+   * `maxFrames` extra ticks help async resources settle (default: 1).
+   */
+  frame(layers: Layer[], maxFrames?: number): Promise<void>;
+  /** Copy the rendered pixels to CPU as a tight RGBA Uint8Array. */
+  readPixels(): Promise<PixelData>;
+  /** Render → readback → PNG encode. Returns a Uint8Array PNG buffer. */
+  toPNG(opts?: ToPNGOptions): Promise<Uint8Array>;
+  /** Resize the renderer and offscreen target. */
+  resize(width: number, height: number): void;
+  /** Destroy the renderer, offscreen target, and (if owned) the GPU handle. */
+  dispose(): void;
+}
+
+/**
+ * Create a headless insomni renderer suitable for use in Node.js.
+ *
+ * Installs Dawn/WebGPU into the global scope (idempotent), acquires a GPU
+ * adapter+device via `initGPU`, builds an {@link OffscreenRenderTarget}, and
+ * wires a `Renderer2D` through it — canvas-free.
+ */
+export async function createNodeRenderer(
+  options: CreateNodeRendererOptions,
+): Promise<NodeRenderer> {
+  installNodeGPU();
+
+  const { width, height, sampleCount, gpu: providedGpu } = options;
+
+  const format = options.format ?? navigator.gpu.getPreferredCanvasFormat();
+  const ownedGpu = !providedGpu;
+  const handle = providedGpu ?? (await initGPU());
+
+  const target = new OffscreenRenderTarget(handle.root, { width, height, format, sampleCount });
+
+  // Pass a stub {width, height} object cast as HTMLCanvasElement — createRenderer
+  // only reads canvas.width and canvas.height (for OIT A-buffer sizing) when
+  // target is injected; it never touches the DOM canvas APIs.
+  const stubCanvas = { width, height } as unknown as HTMLCanvasElement;
+
+  const renderer = createRenderer(handle.root, stubCanvas, { target, format });
+
+  const self: NodeRenderer = {
+    renderer,
+    target,
+    device: handle.device,
+
+    async frame(layers: Layer[], maxFrames?: number): Promise<void> {
+      await renderSettled(renderer, layers, { maxFrames });
+    },
+
+    async readPixels(): Promise<PixelData> {
+      return readPixels(handle.device, target.colorTexture, target.width, target.height, format);
+    },
+
+    async toPNG(opts?: ToPNGOptions): Promise<Uint8Array> {
+      const pixels = await self.readPixels();
+      return toPNG(pixels, opts);
+    },
+
+    resize(w: number, h: number): void {
+      renderer.resize(w, h);
+    },
+
+    dispose(): void {
+      renderer.destroy();
+      target.destroy();
+      if (ownedGpu) handle.destroy();
+    },
+  };
+
+  return self;
+}