wesl-gpu 0.1.1

package/README.md

@@ -0,0 +1,4 @@
+# wesl-gpu
+
+Reusable WebGPU helpers extracted from `wgsl-test` and `wesl-toy` for use in both Node.js and browser environments. 
+

package/dist/index.js

@@ -0,0 +1,495 @@
+import { CompositeResolver, RecordResolver, link } from "wesl";
+import { withTextureCopy } from "thimbleberry";
+
+//#region src/DeviceCache.ts
+/**
+* WeakMap cache for GPUDevice-based caching
+*
+* GPUDevices are weakly held to avoid memory leaks.
+*/
+var DeviceCache = class {
+	cache = /* @__PURE__ */ new WeakMap();
+	get(device, key) {
+		return this.cache.get(device)?.get(key);
+	}
+	set(device, key, value) {
+		let deviceCache = this.cache.get(device);
+		if (!deviceCache) {
+			deviceCache = /* @__PURE__ */ new Map();
+			this.cache.set(device, deviceCache);
+		}
+		deviceCache.set(key, value);
+	}
+};
+
+//#endregion
+//#region src/ErrorScopes.ts
+/**
+* Runs a function with WebGPU error scopes, automatically handling push/pop/check.
+* Throws if any validation, out-of-memory, or internal errors occur.
+*/
+async function withErrorScopes(device, fn) {
+	device.pushErrorScope("internal");
+	device.pushErrorScope("out-of-memory");
+	device.pushErrorScope("validation");
+	const result = await fn();
+	const validationError = await device.popErrorScope();
+	const oomError = await device.popErrorScope();
+	const internalError = await device.popErrorScope();
+	if (validationError) throw new Error(`WebGPU validation error: ${validationError.message}`);
+	if (oomError) throw new Error(`WebGPU out-of-memory error: ${oomError.message}`);
+	if (internalError) throw new Error(`WebGPU internal error: ${internalError.message}`);
+	return result;
+}
+
+//#endregion
+//#region src/ExampleTextures.ts
+const textureCache = new DeviceCache();
+const samplerCache = new DeviceCache();
+/** Create texture filled with solid color. Internally cached. */
+function solidTexture(device, color, width, height) {
+	return cachedTexture(device, `solid:${color.join(",")}:${width}x${height}`, `test-texture-solid-${color.join(",")}`, width, height, (data) => {
+		for (let i = 0; i < width * height; i++) {
+			data[i * 4 + 0] = Math.round(color[0] * 255);
+			data[i * 4 + 1] = Math.round(color[1] * 255);
+			data[i * 4 + 2] = Math.round(color[2] * 255);
+			data[i * 4 + 3] = Math.round(color[3] * 255);
+		}
+	});
+}
+/** Create gradient texture. Direction: 'horizontal' (default) or 'vertical'. */
+function gradientTexture(device, width, height, direction = "horizontal") {
+	return cachedTexture(device, `gradient:${direction}:${width}x${height}`, `test-texture-gradient-${direction}`, width, height, (data) => {
+		for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+			const idx = (y * width + x) * 4;
+			const gradient = direction === "horizontal" ? x / (width - 1) : y / (height - 1);
+			const value = Math.round(gradient * 255);
+			data[idx + 0] = value;
+			data[idx + 1] = value;
+			data[idx + 2] = value;
+			data[idx + 3] = 255;
+		}
+	});
+}
+/** Create checkerboard pattern. cellSize: pixels per cell (default: width/4). */
+function checkerboardTexture(device, width, height, cellSize) {
+	const cell = cellSize ?? Math.floor(width / 4);
+	return cachedTexture(device, `checkerboard:${cell}:${width}x${height}`, `test-texture-checkerboard-${cell}`, width, height, (data) => {
+		for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+			const idx = (y * width + x) * 4;
+			const value = (Math.floor(x / cell) + Math.floor(y / cell)) % 2 === 0 ? 0 : 255;
+			data[idx + 0] = value;
+			data[idx + 1] = value;
+			data[idx + 2] = value;
+			data[idx + 3] = 255;
+		}
+	});
+}
+/** Create sampler. Default: linear filtering with clamp-to-edge. Internally cached. */
+function createSampler(device, options) {
+	const { addressMode = "clamp-to-edge", filterMode = "linear" } = options ?? {};
+	const cacheKey = `${addressMode}:${filterMode}`;
+	const cached = samplerCache.get(device, cacheKey);
+	if (cached) return cached;
+	const sampler = device.createSampler({
+		addressModeU: addressMode,
+		addressModeV: addressMode,
+		magFilter: filterMode,
+		minFilter: filterMode
+	});
+	samplerCache.set(device, cacheKey, sampler);
+	return sampler;
+}
+/** Create radial gradient texture (white center to black edge). */
+function radialGradientTexture(device, size) {
+	const cacheKey = `radial:${size}`;
+	const centerX = size / 2;
+	const centerY = size / 2;
+	const maxRadius = Math.sqrt(centerX * centerX + centerY * centerY);
+	return cachedTexture(device, cacheKey, `test-texture-radial-${size}`, size, size, (data) => {
+		for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+			const idx = (y * size + x) * 4;
+			const dx = x - centerX;
+			const dy = y - centerY;
+			const distance = Math.sqrt(dx * dx + dy * dy);
+			const gradient = 1 - Math.min(distance / maxRadius, 1);
+			const value = Math.round(gradient * 255);
+			data[idx + 0] = value;
+			data[idx + 1] = value;
+			data[idx + 2] = value;
+			data[idx + 3] = 255;
+		}
+	});
+}
+/** Create edge pattern texture with sharp vertical, horizontal, and diagonal lines. */
+function edgePatternTexture(device, size) {
+	const cacheKey = `edges:${size}`;
+	const lineWidth = 2;
+	return cachedTexture(device, cacheKey, `test-texture-edges-${size}`, size, size, (data) => {
+		for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+			const idx = (y * size + x) * 4;
+			const value = Math.abs(x - size / 2) < lineWidth || Math.abs(y - size / 2) < lineWidth || Math.abs(x - y) < lineWidth || Math.abs(x - (size - 1 - y)) < lineWidth ? 255 : 0;
+			data[idx + 0] = value;
+			data[idx + 1] = value;
+			data[idx + 2] = value;
+			data[idx + 3] = 255;
+		}
+	});
+}
+/** Create color bars texture (RGB primaries and secondaries). */
+function colorBarsTexture(device, size) {
+	const cacheKey = `colorbars:${size}`;
+	const colors = [
+		[
+			255,
+			0,
+			0
+		],
+		[
+			255,
+			255,
+			0
+		],
+		[
+			0,
+			255,
+			0
+		],
+		[
+			0,
+			255,
+			255
+		],
+		[
+			0,
+			0,
+			255
+		],
+		[
+			255,
+			0,
+			255
+		]
+	];
+	const barWidth = size / colors.length;
+	return cachedTexture(device, cacheKey, `test-texture-colorbars-${size}`, size, size, (data) => {
+		for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+			const idx = (y * size + x) * 4;
+			const color = colors[Math.min(Math.floor(x / barWidth), colors.length - 1)];
+			data[idx + 0] = color[0];
+			data[idx + 1] = color[1];
+			data[idx + 2] = color[2];
+			data[idx + 3] = 255;
+		}
+	});
+}
+/** Create seeded noise pattern (deterministic). */
+function noiseTexture(device, size, seed = 42) {
+	return cachedTexture(device, `noise:${size}:${seed}`, `test-texture-noise-${size}`, size, size, (data) => {
+		let rng = seed;
+		const random = () => {
+			rng |= 0;
+			rng = rng + 1831565813 | 0;
+			let t = Math.imul(rng ^ rng >>> 15, 1 | rng);
+			t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+			return ((t ^ t >>> 14) >>> 0) / 4294967296;
+		};
+		for (let i = 0; i < size * size * 4; i += 4) {
+			const value = Math.round(random() * 255);
+			data[i + 0] = value;
+			data[i + 1] = value;
+			data[i + 2] = value;
+			data[i + 3] = 255;
+		}
+	});
+}
+/** Common helper for creating cached textures with custom data generation. */
+function cachedTexture(device, cacheKey, label, width, height, generateData) {
+	const cached = textureCache.get(device, cacheKey);
+	if (cached) return cached;
+	const texture = device.createTexture({
+		label,
+		size: {
+			width,
+			height,
+			depthOrArrayLayers: 1
+		},
+		format: "rgba8unorm",
+		usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
+	});
+	const data = new Uint8Array(width * height * 4);
+	generateData(data, width, height);
+	device.queue.writeTexture({ texture }, data, { bytesPerRow: width * 4 }, {
+		width,
+		height
+	});
+	textureCache.set(device, cacheKey, texture);
+	return texture;
+}
+
+//#endregion
+//#region src/FullscreenVertex.ts
+/** Number of vertices drawn for fullscreen quad using triangle-strip topology */
+const fullscreenVertexCount = 4;
+/** Fullscreen triangle vertex shader that covers viewport with 3 vertices, no vertex buffer needed */
+const fullscreenTriangleVertex = `
+  @vertex
+  fn vs_main(@builtin(vertex_index) idx: u32) -> @builtin(position) vec4f {
+    // Covers viewport with 3 vertices, no vertex buffer needed
+    var pos: vec2f;
+    if (idx == 0u) {
+      pos = vec2f(-1.0, -1.0);
+    } else if (idx == 1u) {
+      pos = vec2f(3.0, -1.0);
+    } else {
+      pos = vec2f(-1.0, 3.0);
+    }
+    return vec4f(pos, 0.0, 1.0);
+  }`;
+
+//#endregion
+//#region src/RenderUniforms.ts
+/**
+* Creates a standard uniform buffer for running test fragment shaders.
+*
+* @param outputSize - Output texture dimensions (becomes uniforms.resolution)
+* @param uniforms - User-provided uniform values (time, mouse)
+* @returns GPUBuffer containing uniform data
+*/
+function renderUniformBuffer(device, outputSize, uniforms = {}) {
+	const resolution = outputSize;
+	const time = uniforms.time ?? 0;
+	const mouse = uniforms.mouse ?? [0, 0];
+	const buffer = device.createBuffer({
+		label: "standard-uniforms",
+		size: 32,
+		usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+	});
+	const data = new Float32Array([
+		resolution[0],
+		resolution[1],
+		time,
+		0,
+		mouse[0],
+		mouse[1],
+		0,
+		0
+	]);
+	device.queue.writeBuffer(buffer, 0, data);
+	return buffer;
+}
+/**
+* Updates an existing uniform buffer with new values.
+* Use this for per-frame updates in render loops (avoids buffer recreation).
+*
+* @param buffer - Existing uniform buffer to update
+* @param device - GPU device
+* @param resolution - Output texture dimensions
+* @param time - Elapsed time in seconds
+* @param mouse - Mouse position [0,1] normalized coords
+*/
+function updateRenderUniforms(buffer, device, resolution, time, mouse = [0, 0]) {
+	const data = new Float32Array([
+		resolution[0],
+		resolution[1],
+		time,
+		0,
+		mouse[0],
+		mouse[1],
+		0,
+		0
+	]);
+	device.queue.writeBuffer(buffer, 0, data);
+}
+/**
+* return the WGSL struct for use in shaders as test::Uniforms.
+*
+* @returns virtual library object for passing to compileShader()
+*/
+function createUniformsVirtualLib() {
+	return { test: () => `
+      struct Uniforms {
+        resolution: vec2f,  // Output viewport dimensions
+        time: f32,          // Elapsed time in seconds
+        mouse: vec2f,       // Mouse position [0,1] normalized coords
+      }
+    ` };
+}
+
+//#endregion
+//#region src/FragmentPipeline.ts
+/** Combined: link WESL source and create pipeline in one step. */
+async function linkAndCreatePipeline(params) {
+	const module = await linkFragmentShader(params);
+	return createFragmentPipeline({
+		device: params.device,
+		module,
+		format: params.format,
+		layout: params.layout
+	});
+}
+/**
+* Link a WESL/WGSL fragment shader to a shader module.
+* Adds:
+* - vertex shader that covers the viewport with a fullscreen triangle
+* - a virtual module containing a std uniform buffer (for size, etc.)
+*/
+async function linkFragmentShader(params) {
+	const { device, fragmentSource, bundles = [], resolver } = params;
+	const { conditions, constants, packageName } = params;
+	const fullSource = `${fragmentSource}\n\n${fullscreenTriangleVertex}`;
+	let sourceParams;
+	if (resolver) sourceParams = { resolver: new CompositeResolver([new RecordResolver({ main: fullSource }, { packageName }), resolver]) };
+	else sourceParams = { weslSrc: { main: fullSource } };
+	return (await link({
+		...sourceParams,
+		rootModuleName: "main",
+		packageName,
+		libs: bundles,
+		virtualLibs: createUniformsVirtualLib(),
+		conditions,
+		constants
+	})).createShaderModule(device);
+}
+/** Create fullscreen fragment render pipeline from a shader module. */
+function createFragmentPipeline(params) {
+	const { device, module, format, layout = "auto" } = params;
+	return device.createRenderPipeline({
+		layout,
+		vertex: { module },
+		fragment: {
+			module,
+			targets: [{ format }]
+		},
+		primitive: { topology: "triangle-list" }
+	});
+}
+
+//#endregion
+//#region src/FragmentRender.ts
+/** Execute one fullscreen fragment render pass to target view. */
+function renderFrame(params) {
+	const { device, pipeline, bindGroup, targetView } = params;
+	const encoder = device.createCommandEncoder();
+	const pass = encoder.beginRenderPass({ colorAttachments: [{
+		view: targetView,
+		clearValue: {
+			r: 0,
+			g: 0,
+			b: 0,
+			a: 1
+		},
+		loadOp: "clear",
+		storeOp: "store"
+	}] });
+	pass.setPipeline(pipeline);
+	if (bindGroup) pass.setBindGroup(0, bindGroup);
+	pass.draw(3);
+	pass.end();
+	device.queue.submit([encoder.finish()]);
+}
+
+//#endregion
+//#region src/SimpleRender.ts
+/**
+* Executes a render pipeline with the given shader module.
+* Creates a texture with the specified format, renders to it, and returns all pixel data.
+* @returns output texture contents in a flattened array (rows flattened, color channels interleaved).
+*/
+async function simpleRender(params) {
+	const { device, module } = params;
+	const { outputFormat = "rgba32float", size = [1, 1] } = params;
+	const { textures = [], samplers = [], uniformBuffer } = params;
+	return await withErrorScopes(device, async () => {
+		const texture = device.createTexture({
+			label: "fragment-test-output",
+			size: {
+				width: size[0],
+				height: size[1],
+				depthOrArrayLayers: 1
+			},
+			format: outputFormat,
+			usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC
+		});
+		const bindings = uniformBuffer || textures.length > 0 ? createBindGroup(device, uniformBuffer, textures, samplers) : void 0;
+		const pipelineLayout = bindings ? device.createPipelineLayout({ bindGroupLayouts: [bindings.layout] }) : "auto";
+		renderFrame({
+			device,
+			pipeline: device.createRenderPipeline({
+				layout: pipelineLayout,
+				vertex: { module },
+				fragment: {
+					module,
+					targets: [{ format: outputFormat }]
+				},
+				primitive: { topology: "triangle-list" }
+			}),
+			bindGroup: bindings?.bindGroup,
+			targetView: texture.createView()
+		});
+		const data = await withTextureCopy(device, texture, (texData) => Array.from(texData));
+		texture.destroy();
+		uniformBuffer?.destroy();
+		return data;
+	});
+}
+/**
+* Create bind group with optional uniforms, textures, and samplers.
+* Binding layout: 0=uniform buffer (if provided), 1..n=textures, n+1..n+m=samplers.
+* Samplers must be length 1 (reused for all textures) or match textures.length exactly.
+*/
+function createBindGroup(device, uniformBuffer, textures = [], samplers = []) {
+	if (textures.length > 0 && samplers.length > 0) {
+		if (samplers.length !== 1 && samplers.length !== textures.length) throw new Error(`Invalid sampler count: expected 1 or ${textures.length} samplers for ${textures.length} textures, got ${samplers.length}`);
+	}
+	const entries = [];
+	const bindGroupEntries = [];
+	if (uniformBuffer) {
+		entries.push({
+			binding: 0,
+			visibility: GPUShaderStage.FRAGMENT,
+			buffer: { type: "uniform" }
+		});
+		bindGroupEntries.push({
+			binding: 0,
+			resource: { buffer: uniformBuffer }
+		});
+	}
+	textures.forEach((texture, i) => {
+		const binding = i + 1;
+		entries.push({
+			binding,
+			visibility: GPUShaderStage.FRAGMENT,
+			texture: { sampleType: "float" }
+		});
+		bindGroupEntries.push({
+			binding,
+			resource: texture.createView()
+		});
+	});
+	const singleSampler = samplers.length === 1 ? samplers[0] : void 0;
+	for (let i = 0; i < textures.length; i++) {
+		const binding = textures.length + i + 1;
+		const sampler = singleSampler ?? samplers[i];
+		entries.push({
+			binding,
+			visibility: GPUShaderStage.FRAGMENT,
+			sampler: { type: "filtering" }
+		});
+		bindGroupEntries.push({
+			binding,
+			resource: sampler
+		});
+	}
+	const layout = device.createBindGroupLayout({ entries });
+	return {
+		layout,
+		bindGroup: device.createBindGroup({
+			layout,
+			entries: bindGroupEntries
+		})
+	};
+}
+
+//#endregion
+export { DeviceCache, checkerboardTexture, colorBarsTexture, createBindGroup, createSampler, createUniformsVirtualLib, edgePatternTexture, fullscreenTriangleVertex, fullscreenVertexCount, gradientTexture, linkAndCreatePipeline, linkFragmentShader, noiseTexture, radialGradientTexture, renderFrame, renderUniformBuffer, simpleRender, solidTexture, updateRenderUniforms, withErrorScopes };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "wesl-gpu",
+  "description": "Browser-compatible WebGPU utilities for shader testing and rendering",
+  "version": "0.1.1",
+  "type": "module",
+  "repository": "github:wgsl-tooling-wg/wesl-js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "thimbleberry": "^0.2.10",
+    "wesl": "0.6.47"
+  },
+  "devDependencies": {
+    "@webgpu/types": "^0.1.65"
+  },
+  "keywords": [
+    "rendering",
+    "shader",
+    "testing",
+    "WebGPU",
+    "WESL",
+    "WGSL"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "cross-env FORCE_COLOR=1 vitest",
+    "test:once": "vitest run",
+    "typecheck": "tsgo"
+  },
+  "main": "./dist/index.js"
+}

package/src/DeviceCache.ts

@@ -0,0 +1,21 @@
+/**
+ * WeakMap cache for GPUDevice-based caching
+ *
+ * GPUDevices are weakly held to avoid memory leaks.
+ */
+export class DeviceCache<T> {
+  private cache = new WeakMap<GPUDevice, Map<string, T>>();
+
+  get(device: GPUDevice, key: string): T | undefined {
+    return this.cache.get(device)?.get(key);
+  }
+
+  set(device: GPUDevice, key: string, value: T): void {
+    let deviceCache = this.cache.get(device);
+    if (!deviceCache) {
+      deviceCache = new Map();
+      this.cache.set(device, deviceCache);
+    }
+    deviceCache.set(key, value);
+  }
+}

package/src/ErrorScopes.ts

@@ -0,0 +1,30 @@
+/**
+ * Runs a function with WebGPU error scopes, automatically handling push/pop/check.
+ * Throws if any validation, out-of-memory, or internal errors occur.
+ */
+export async function withErrorScopes<T>(
+  device: GPUDevice,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  device.pushErrorScope("internal");
+  device.pushErrorScope("out-of-memory");
+  device.pushErrorScope("validation");
+
+  const result = await fn();
+
+  const validationError = await device.popErrorScope();
+  const oomError = await device.popErrorScope();
+  const internalError = await device.popErrorScope();
+
+  if (validationError) {
+    throw new Error(`WebGPU validation error: ${validationError.message}`);
+  }
+  if (oomError) {
+    throw new Error(`WebGPU out-of-memory error: ${oomError.message}`);
+  }
+  if (internalError) {
+    throw new Error(`WebGPU internal error: ${internalError.message}`);
+  }
+
+  return result;
+}

package/src/ExampleTextures.ts

@@ -0,0 +1,293 @@
+import { DeviceCache } from "./DeviceCache.ts";
+
+/* Texture and sampler creation helpers with internal caching for test performance */
+
+export interface SamplerOptions {
+  addressMode?: "clamp-to-edge" | "repeat" | "mirror-repeat";
+  filterMode?: "nearest" | "linear";
+}
+
+const textureCache = new DeviceCache<GPUTexture>();
+const samplerCache = new DeviceCache<GPUSampler>();
+
+/** Create texture filled with solid color. Internally cached. */
+export function solidTexture(
+  device: GPUDevice,
+  color: [r: number, g: number, b: number, a: number],
+  width: number,
+  height: number,
+): GPUTexture {
+  const cacheKey = `solid:${color.join(",")}:${width}x${height}`;
+  return cachedTexture(
+    device,
+    cacheKey,
+    `test-texture-solid-${color.join(",")}`,
+    width,
+    height,
+    data => {
+      for (let i = 0; i < width * height; i++) {
+        data[i * 4 + 0] = Math.round(color[0] * 255);
+        data[i * 4 + 1] = Math.round(color[1] * 255);
+        data[i * 4 + 2] = Math.round(color[2] * 255);
+        data[i * 4 + 3] = Math.round(color[3] * 255);
+      }
+    },
+  );
+}
+
+/** Create gradient texture. Direction: 'horizontal' (default) or 'vertical'. */
+export function gradientTexture(
+  device: GPUDevice,
+  width: number,
+  height: number,
+  direction: "horizontal" | "vertical" = "horizontal",
+): GPUTexture {
+  const cacheKey = `gradient:${direction}:${width}x${height}`;
+  return cachedTexture(
+    device,
+    cacheKey,
+    `test-texture-gradient-${direction}`,
+    width,
+    height,
+    data => {
+      for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+          const idx = (y * width + x) * 4;
+          const gradient =
+            direction === "horizontal" ? x / (width - 1) : y / (height - 1);
+          const value = Math.round(gradient * 255);
+          data[idx + 0] = value;
+          data[idx + 1] = value;
+          data[idx + 2] = value;
+          data[idx + 3] = 255;
+        }
+      }
+    },
+  );
+}
+
+/** Create checkerboard pattern. cellSize: pixels per cell (default: width/4). */
+export function checkerboardTexture(
+  device: GPUDevice,
+  width: number,
+  height: number,
+  cellSize?: number,
+): GPUTexture {
+  const cell = cellSize ?? Math.floor(width / 4);
+  const cacheKey = `checkerboard:${cell}:${width}x${height}`;
+  return cachedTexture(
+    device,
+    cacheKey,
+    `test-texture-checkerboard-${cell}`,
+    width,
+    height,
+    data => {
+      for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+          const idx = (y * width + x) * 4;
+          const cellX = Math.floor(x / cell);
+          const cellY = Math.floor(y / cell);
+          const isBlack = (cellX + cellY) % 2 === 0;
+          const value = isBlack ? 0 : 255;
+          data[idx + 0] = value;
+          data[idx + 1] = value;
+          data[idx + 2] = value;
+          data[idx + 3] = 255;
+        }
+      }
+    },
+  );
+}
+
+/** Create sampler. Default: linear filtering with clamp-to-edge. Internally cached. */
+export function createSampler(
+  device: GPUDevice,
+  options?: SamplerOptions,
+): GPUSampler {
+  const { addressMode = "clamp-to-edge", filterMode = "linear" } =
+    options ?? {};
+  const cacheKey = `${addressMode}:${filterMode}`;
+  const cached = samplerCache.get(device, cacheKey);
+  if (cached) return cached;
+
+  const sampler = device.createSampler({
+    addressModeU: addressMode,
+    addressModeV: addressMode,
+    magFilter: filterMode,
+    minFilter: filterMode,
+  });
+
+  samplerCache.set(device, cacheKey, sampler);
+  return sampler;
+}
+
+/** Create radial gradient texture (white center to black edge). */
+export function radialGradientTexture(
+  device: GPUDevice,
+  size: number,
+): GPUTexture {
+  const cacheKey = `radial:${size}`;
+  const centerX = size / 2;
+  const centerY = size / 2;
+  const maxRadius = Math.sqrt(centerX * centerX + centerY * centerY);
+  return cachedTexture(
+    device,
+    cacheKey,
+    `test-texture-radial-${size}`,
+    size,
+    size,
+    data => {
+      for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+          const idx = (y * size + x) * 4;
+          const dx = x - centerX;
+          const dy = y - centerY;
+          const distance = Math.sqrt(dx * dx + dy * dy);
+          const gradient = 1.0 - Math.min(distance / maxRadius, 1.0);
+          const value = Math.round(gradient * 255);
+          data[idx + 0] = value;
+          data[idx + 1] = value;
+          data[idx + 2] = value;
+          data[idx + 3] = 255;
+        }
+      }
+    },
+  );
+}
+
+/** Create edge pattern texture with sharp vertical, horizontal, and diagonal lines. */
+export function edgePatternTexture(
+  device: GPUDevice,
+  size: number,
+): GPUTexture {
+  const cacheKey = `edges:${size}`;
+  const lineWidth = 2;
+  return cachedTexture(
+    device,
+    cacheKey,
+    `test-texture-edges-${size}`,
+    size,
+    size,
+    data => {
+      for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+          const idx = (y * size + x) * 4;
+          const isLine =
+            Math.abs(x - size / 2) < lineWidth ||
+            Math.abs(y - size / 2) < lineWidth ||
+            Math.abs(x - y) < lineWidth ||
+            Math.abs(x - (size - 1 - y)) < lineWidth;
+          const value = isLine ? 255 : 0;
+          data[idx + 0] = value;
+          data[idx + 1] = value;
+          data[idx + 2] = value;
+          data[idx + 3] = 255;
+        }
+      }
+    },
+  );
+}
+
+/** Create color bars texture (RGB primaries and secondaries). */
+export function colorBarsTexture(device: GPUDevice, size: number): GPUTexture {
+  const cacheKey = `colorbars:${size}`;
+  const colors = [
+    [255, 0, 0],
+    [255, 255, 0],
+    [0, 255, 0],
+    [0, 255, 255],
+    [0, 0, 255],
+    [255, 0, 255],
+  ];
+  const barWidth = size / colors.length;
+  return cachedTexture(
+    device,
+    cacheKey,
+    `test-texture-colorbars-${size}`,
+    size,
+    size,
+    data => {
+      for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+          const idx = (y * size + x) * 4;
+          const barIndex = Math.min(
+            Math.floor(x / barWidth),
+            colors.length - 1,
+          );
+          const color = colors[barIndex];
+          data[idx + 0] = color[0];
+          data[idx + 1] = color[1];
+          data[idx + 2] = color[2];
+          data[idx + 3] = 255;
+        }
+      }
+    },
+  );
+}
+
+/** Create seeded noise pattern (deterministic). */
+export function noiseTexture(
+  device: GPUDevice,
+  size: number,
+  seed = 42,
+): GPUTexture {
+  const cacheKey = `noise:${size}:${seed}`;
+  return cachedTexture(
+    device,
+    cacheKey,
+    `test-texture-noise-${size}`,
+    size,
+    size,
+    data => {
+      let rng = seed;
+      // Simple seeded PRNG (mulberry32)
+      const random = () => {
+        rng |= 0;
+        rng = (rng + 0x6d2b79f5) | 0;
+        let t = Math.imul(rng ^ (rng >>> 15), 1 | rng);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+      };
+      for (let i = 0; i < size * size * 4; i += 4) {
+        const value = Math.round(random() * 255);
+        data[i + 0] = value;
+        data[i + 1] = value;
+        data[i + 2] = value;
+        data[i + 3] = 255;
+      }
+    },
+  );
+}
+
+/** Common helper for creating cached textures with custom data generation. */
+function cachedTexture(
+  device: GPUDevice,
+  cacheKey: string,
+  label: string,
+  width: number,
+  height: number,
+  generateData: (data: Uint8Array, width: number, height: number) => void,
+): GPUTexture {
+  const cached = textureCache.get(device, cacheKey);
+  if (cached) return cached;
+
+  const texture = device.createTexture({
+    label,
+    size: { width, height, depthOrArrayLayers: 1 },
+    format: "rgba8unorm",
+    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+  });
+
+  const data = new Uint8Array(width * height * 4);
+  generateData(data, width, height);
+
+  device.queue.writeTexture(
+    { texture },
+    data,
+    { bytesPerRow: width * 4 },
+    { width, height },
+  );
+
+  textureCache.set(device, cacheKey, texture);
+  return texture;
+}

package/src/FragmentPipeline.ts

@@ -0,0 +1,104 @@
+import type { LinkParams, ModuleResolver, WeslBundle } from "wesl";
+import { CompositeResolver, link, RecordResolver } from "wesl";
+import { fullscreenTriangleVertex } from "./FullscreenVertex.ts";
+import { createUniformsVirtualLib } from "./RenderUniforms.ts";
+
+export interface LinkFragmentParams {
+  device: GPUDevice;
+
+  /** Fragment shader source (vertex shader is auto-provided) */
+  fragmentSource: string;
+
+  /** WESL library bundles for dependencies */
+  bundles?: WeslBundle[];
+
+  /** Resolver for lazy file loading (e.g., useSourceShaders mode in tests) */
+  resolver?: ModuleResolver;
+
+  /** Conditional compilation flags */
+  conditions?: Record<string, boolean>;
+
+  /** Compile-time constants */
+  constants?: Record<string, string | number>;
+
+  /** Package name (allows imports to mention the current package by name instead of package::) */
+  packageName?: string;
+}
+
+export interface LinkAndCreateParams extends LinkFragmentParams {
+  format: GPUTextureFormat;
+  layout?: GPUPipelineLayout | "auto";
+}
+
+/** Combined: link WESL source and create pipeline in one step. */
+export async function linkAndCreatePipeline(
+  params: LinkAndCreateParams,
+): Promise<GPURenderPipeline> {
+  const module = await linkFragmentShader(params);
+  return createFragmentPipeline({
+    device: params.device,
+    module,
+    format: params.format,
+    layout: params.layout,
+  });
+}
+
+/**
+ * Link a WESL/WGSL fragment shader to a shader module.
+ * Adds:
+ * - vertex shader that covers the viewport with a fullscreen triangle
+ * - a virtual module containing a std uniform buffer (for size, etc.)
+ */
+export async function linkFragmentShader(
+  params: LinkFragmentParams,
+): Promise<GPUShaderModule> {
+  const { device, fragmentSource, bundles = [], resolver } = params;
+  const { conditions, constants, packageName } = params;
+
+  const fullSource = `${fragmentSource}\n\n${fullscreenTriangleVertex}`;
+
+  // Use provided resolver or fall back to simple weslSrc
+  let sourceParams: Pick<LinkParams, "resolver" | "weslSrc">;
+  if (resolver) {
+    const srcResolver = new RecordResolver(
+      { main: fullSource },
+      { packageName },
+    );
+    sourceParams = { resolver: new CompositeResolver([srcResolver, resolver]) };
+  } else {
+    sourceParams = { weslSrc: { main: fullSource } };
+  }
+
+  const linked = await link({
+    ...sourceParams,
+    rootModuleName: "main",
+    packageName,
+    libs: bundles,
+    virtualLibs: createUniformsVirtualLib(),
+    conditions,
+    constants,
+  });
+
+  return linked.createShaderModule(device);
+}
+
+interface CreatePipelineParams {
+  device: GPUDevice;
+  module: GPUShaderModule;
+  format: GPUTextureFormat;
+  layout?: GPUPipelineLayout | "auto";
+}
+
+/** Create fullscreen fragment render pipeline from a shader module. */
+function createFragmentPipeline(
+  params: CreatePipelineParams,
+): GPURenderPipeline {
+  const { device, module, format, layout = "auto" } = params;
+
+  return device.createRenderPipeline({
+    layout,
+    vertex: { module },
+    fragment: { module, targets: [{ format }] },
+    primitive: { topology: "triangle-list" },
+  });
+}

package/src/FragmentRender.ts

@@ -0,0 +1,30 @@
+export interface RenderFrameParams {
+  device: GPUDevice;
+  pipeline: GPURenderPipeline;
+  bindGroup?: GPUBindGroup;
+  targetView: GPUTextureView;
+}
+
+/** Execute one fullscreen fragment render pass to target view. */
+export function renderFrame(params: RenderFrameParams): void {
+  const { device, pipeline, bindGroup, targetView } = params;
+
+  const encoder = device.createCommandEncoder();
+  const pass = encoder.beginRenderPass({
+    colorAttachments: [
+      {
+        view: targetView,
+        clearValue: { r: 0, g: 0, b: 0, a: 1 },
+        loadOp: "clear",
+        storeOp: "store",
+      },
+    ],
+  });
+
+  pass.setPipeline(pipeline);
+  if (bindGroup) pass.setBindGroup(0, bindGroup);
+  pass.draw(3);
+  pass.end();
+
+  device.queue.submit([encoder.finish()]);
+}

package/src/FullscreenVertex.ts

@@ -0,0 +1,18 @@
+/** Number of vertices drawn for fullscreen quad using triangle-strip topology */
+export const fullscreenVertexCount = 4;
+
+/** Fullscreen triangle vertex shader that covers viewport with 3 vertices, no vertex buffer needed */
+export const fullscreenTriangleVertex = `
+  @vertex
+  fn vs_main(@builtin(vertex_index) idx: u32) -> @builtin(position) vec4f {
+    // Covers viewport with 3 vertices, no vertex buffer needed
+    var pos: vec2f;
+    if (idx == 0u) {
+      pos = vec2f(-1.0, -1.0);
+    } else if (idx == 1u) {
+      pos = vec2f(3.0, -1.0);
+    } else {
+      pos = vec2f(-1.0, 3.0);
+    }
+    return vec4f(pos, 0.0, 1.0);
+  }`;

package/src/RenderUniforms.ts

@@ -0,0 +1,106 @@
+import type { VirtualLibraryFn } from "wesl";
+
+/** User provided uniform values */
+export interface RenderUniforms {
+  /** Elapsed time in seconds (default: 0.0) */
+  time?: number;
+
+  /** Mouse position in [0,1] normalized coords (default: [0.0, 0.0]) */
+  mouse?: [number, number];
+
+  // Note: resolution is auto-populated from size parameter
+  // resolution?: [number, number];
+}
+
+/**
+ * Creates a standard uniform buffer for running test fragment shaders.
+ *
+ * @param outputSize - Output texture dimensions (becomes uniforms.resolution)
+ * @param uniforms - User-provided uniform values (time, mouse)
+ * @returns GPUBuffer containing uniform data
+ */
+export function renderUniformBuffer(
+  device: GPUDevice,
+  outputSize: [number, number],
+  uniforms: RenderUniforms = {},
+): GPUBuffer {
+  const resolution = outputSize;
+  const time = uniforms.time ?? 0.0;
+  const mouse = uniforms.mouse ?? [0.0, 0.0];
+
+  // WGSL struct layout with alignment:
+  // struct Uniforms {
+  //   resolution: vec2f,  // offset 0, size 8
+  //   time: f32,          // offset 8, size 4
+  //   // implicit padding    offset 12, size 4 (for vec2f alignment)
+  //   mouse: vec2f,       // offset 16, size 8
+  //   // struct padding      offset 24, size 8 (uniform buffer requires 16-byte struct alignment)
+  // }
+  // Total: 32 bytes
+  const buffer = device.createBuffer({
+    label: "standard-uniforms",
+    size: 32,
+    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+  });
+
+  const data = new Float32Array([
+    resolution[0],
+    resolution[1],
+    time,
+    0.0, // implicit padding for vec2f alignment
+    mouse[0],
+    mouse[1],
+    0.0, // struct padding to 32 bytes
+    0.0, // struct padding to 32 bytes
+  ]);
+
+  device.queue.writeBuffer(buffer, 0, data);
+  return buffer;
+}
+
+/**
+ * Updates an existing uniform buffer with new values.
+ * Use this for per-frame updates in render loops (avoids buffer recreation).
+ *
+ * @param buffer - Existing uniform buffer to update
+ * @param device - GPU device
+ * @param resolution - Output texture dimensions
+ * @param time - Elapsed time in seconds
+ * @param mouse - Mouse position [0,1] normalized coords
+ */
+export function updateRenderUniforms(
+  buffer: GPUBuffer,
+  device: GPUDevice,
+  resolution: [number, number],
+  time: number,
+  mouse: [number, number] = [0.0, 0.0],
+): void {
+  const data = new Float32Array([
+    resolution[0],
+    resolution[1],
+    time,
+    0.0, // padding for vec2f alignment
+    mouse[0],
+    mouse[1],
+    0.0, // struct padding
+    0.0, // struct padding
+  ]);
+  device.queue.writeBuffer(buffer, 0, data);
+}
+
+/**
+ * return the WGSL struct for use in shaders as test::Uniforms.
+ *
+ * @returns virtual library object for passing to compileShader()
+ */
+export function createUniformsVirtualLib(): Record<string, VirtualLibraryFn> {
+  return {
+    test: () => `
+      struct Uniforms {
+        resolution: vec2f,  // Output viewport dimensions
+        time: f32,          // Elapsed time in seconds
+        mouse: vec2f,       // Mouse position [0,1] normalized coords
+      }
+    `,
+  };
+}

package/src/SimpleRender.ts

@@ -0,0 +1,139 @@
+import { withTextureCopy } from "thimbleberry";
+import { withErrorScopes } from "./ErrorScopes.ts";
+import { renderFrame } from "./FragmentRender.ts";
+
+export interface SimpleRenderParams {
+  device: GPUDevice;
+
+  /** shader module to run, presumed to have one vertex and one fragment entry */
+  module: GPUShaderModule;
+
+  /** format of the output texture. default "rgba32float" */
+  outputFormat?: GPUTextureFormat;
+
+  /** size of the output texture. default [1, 1]
+   * Use [2, 2] for derivative tests
+   * Use [512, 512] for visual image tests */
+  size?: [number, number];
+
+  /** Input textures to bind in group 0.
+   * Bindings: textures at [1..n], samplers at [n+1..n+m]. */
+  textures?: GPUTexture[];
+
+  /** Samplers for the input textures.
+   * Must be length 1 (reused for all textures) or match textures.length exactly. */
+  samplers?: GPUSampler[];
+
+  /** pass these uniforms to the shader in group 0 binding 0 */
+  uniformBuffer?: GPUBuffer;
+}
+
+/**
+ * Executes a render pipeline with the given shader module.
+ * Creates a texture with the specified format, renders to it, and returns all pixel data.
+ * @returns output texture contents in a flattened array (rows flattened, color channels interleaved).
+ */
+export async function simpleRender(
+  params: SimpleRenderParams,
+): Promise<number[]> {
+  const { device, module } = params;
+  const { outputFormat = "rgba32float", size = [1, 1] } = params;
+  const { textures = [], samplers = [], uniformBuffer } = params;
+
+  return await withErrorScopes(device, async () => {
+    const texture = device.createTexture({
+      label: "fragment-test-output",
+      size: { width: size[0], height: size[1], depthOrArrayLayers: 1 },
+      format: outputFormat,
+      usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
+    });
+    const bindings =
+      uniformBuffer || textures.length > 0
+        ? createBindGroup(device, uniformBuffer, textures, samplers)
+        : undefined;
+    const pipelineLayout = bindings
+      ? device.createPipelineLayout({ bindGroupLayouts: [bindings.layout] })
+      : "auto";
+    const pipeline = device.createRenderPipeline({
+      layout: pipelineLayout,
+      vertex: { module },
+      fragment: { module, targets: [{ format: outputFormat }] },
+      primitive: { topology: "triangle-list" },
+    });
+    renderFrame({
+      device,
+      pipeline,
+      bindGroup: bindings?.bindGroup,
+      targetView: texture.createView(),
+    });
+    const data = await withTextureCopy(device, texture, texData =>
+      Array.from(texData),
+    );
+    texture.destroy();
+    uniformBuffer?.destroy();
+    return data;
+  });
+}
+
+/**
+ * Create bind group with optional uniforms, textures, and samplers.
+ * Binding layout: 0=uniform buffer (if provided), 1..n=textures, n+1..n+m=samplers.
+ * Samplers must be length 1 (reused for all textures) or match textures.length exactly.
+ */
+export function createBindGroup(
+  device: GPUDevice,
+  uniformBuffer: GPUBuffer | undefined,
+  textures: GPUTexture[] = [],
+  samplers: GPUSampler[] = [],
+): { layout: GPUBindGroupLayout; bindGroup: GPUBindGroup } {
+  // Validate sampler count
+  if (textures.length > 0 && samplers.length > 0) {
+    if (samplers.length !== 1 && samplers.length !== textures.length) {
+      throw new Error(
+        `Invalid sampler count: expected 1 or ${textures.length} samplers for ${textures.length} textures, got ${samplers.length}`,
+      );
+    }
+  }
+
+  const entries: GPUBindGroupLayoutEntry[] = [];
+  const bindGroupEntries: GPUBindGroupEntry[] = [];
+
+  if (uniformBuffer) {
+    entries.push({
+      binding: 0,
+      visibility: GPUShaderStage.FRAGMENT,
+      buffer: { type: "uniform" },
+    });
+    bindGroupEntries.push({ binding: 0, resource: { buffer: uniformBuffer } });
+  }
+
+  textures.forEach((texture, i) => {
+    const binding = i + 1;
+    entries.push({
+      binding,
+      visibility: GPUShaderStage.FRAGMENT,
+      texture: { sampleType: "float" },
+    });
+    bindGroupEntries.push({ binding, resource: texture.createView() });
+  });
+
+  // If only one sampler provided, reuse it for all textures
+  const singleSampler = samplers.length === 1 ? samplers[0] : undefined;
+  for (let i = 0; i < textures.length; i++) {
+    const binding = textures.length + i + 1;
+    const sampler = singleSampler ?? samplers[i];
+    entries.push({
+      binding,
+      visibility: GPUShaderStage.FRAGMENT,
+      sampler: { type: "filtering" },
+    });
+    bindGroupEntries.push({ binding, resource: sampler });
+  }
+
+  const layout = device.createBindGroupLayout({ entries });
+  const bindGroup = device.createBindGroup({
+    layout,
+    entries: bindGroupEntries,
+  });
+  return { layout, bindGroup };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./DeviceCache.ts";
+export * from "./ErrorScopes.ts";
+export * from "./ExampleTextures.ts";
+export * from "./FragmentPipeline.ts";
+export * from "./FragmentRender.ts";
+export * from "./FullscreenVertex.ts";
+export * from "./RenderUniforms.ts";
+export * from "./SimpleRender.ts";

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.browser.json"
+}