@motion-core/motion-gpu 0.4.2 → 0.6.0

package/src/lib/core/renderer.ts

@@ -17,7 +17,16 @@ import {
 	toTextureData
 } from './textures.js';
 import { packUniformsInto } from './uniforms.js';
+import {
+	buildComputeShaderSourceWithMap,
+	buildPingPongComputeShaderSourceWithMap,
+	extractWorkgroupSize,
+	storageTextureSampleScalarType
+} from './compute-shader.js';
+import { createComputeStorageBindGroupCache } from './compute-bindgroup-cache.js';
+import { normalizeStorageBufferDefinition } from './storage-buffers.js';
 import type {
+	AnyPass,
 	RenderPass,
 	RenderPassInputSlot,
 	RenderPassOutputSlot,
@@ -25,6 +34,8 @@ import type {
 	RenderTarget,
 	Renderer,
 	RendererOptions,
+	StorageBufferAccess,
+	StorageBufferType,
 	TextureSource,
 	TextureUpdateMode,
 	TextureValue
@@ -52,6 +63,7 @@ interface RuntimeTextureBinding {
 	key: string;
 	samplerBinding: number;
 	textureBinding: number;
+	fragmentVisible: boolean;
 	sampler: GPUSampler;
 	fallbackTexture: GPUTexture;
 	fallbackView: GPUTextureView;
@@ -86,11 +98,28 @@ interface RuntimeRenderTarget {
 	format: GPUTextureFormat;
 }
 
+/**
+ * Runtime ping-pong storage textures for a single logical target key.
+ */
+interface PingPongTexturePair {
+	target: string;
+	format: GPUTextureFormat;
+	width: number;
+	height: number;
+	textureA: GPUTexture;
+	viewA: GPUTextureView;
+	textureB: GPUTexture;
+	viewB: GPUTextureView;
+	bindGroupLayout: GPUBindGroupLayout;
+	readAWriteBBindGroup: GPUBindGroup | null;
+	readBWriteABindGroup: GPUBindGroup | null;
+}
+
 /**
  * Cached pass properties used to validate render-graph cache correctness.
  */
 interface RenderGraphPassSnapshot {
-	pass: RenderPass;
+	pass: AnyPass;
 	enabled: RenderPass['enabled'];
 	needsSwap: RenderPass['needsSwap'];
 	input: RenderPass['input'];
@@ -118,6 +147,19 @@ function getTextureBindings(index: number): {
 	};
 }
 
+/**
+ * Maps WGSL scalar texture type to WebGPU sampled texture bind-group sample type.
+ */
+function toGpuTextureSampleType(type: 'f32' | 'u32' | 'i32'): GPUTextureSampleType {
+	if (type === 'u32') {
+		return 'uint';
+	}
+	if (type === 'i32') {
+		return 'sint';
+	}
+	return 'float';
+}
+
 /**
  * Resizes canvas backing store to match client size and DPR.
  */
@@ -149,6 +191,7 @@ async function assertCompilation(
 	options?: {
 		lineMap?: ShaderLineMap;
 		fragmentSource?: string;
+		computeSource?: string;
 		includeSources?: Record<string, string>;
 		defineBlockSource?: string;
 		materialSource?: {
@@ -159,6 +202,8 @@ async function assertCompilation(
 			functionName?: string;
 		} | null;
 		runtimeContext?: ShaderCompilationRuntimeContext;
+		errorPrefix?: string;
+		shaderStage?: 'fragment' | 'compute';
 	}
 ): Promise<void> {
 	const info = await module.getCompilationInfo();
@@ -189,11 +234,14 @@ async function assertCompilation(
 			return `[${contextLabel.join(' | ')}] ${diagnostic.message}`;
 		})
 		.join('\n');
-	const error = new Error(`WGSL compilation failed:\n${summary}`);
+	const prefix = options?.errorPrefix ?? 'WGSL compilation failed';
+	const error = new Error(`${prefix}:\n${summary}`);
 	throw attachShaderCompilationDiagnostics(error, {
 		kind: 'shader-compilation',
+		...(options?.shaderStage !== undefined ? { shaderStage: options.shaderStage } : {}),
 		diagnostics,
 		fragmentSource: options?.fragmentSource ?? '',
+		...(options?.computeSource !== undefined ? { computeSource: options.computeSource } : {}),
 		includeSources: options?.includeSources ?? {},
 		...(options?.defineBlockSource !== undefined
 			? { defineBlockSource: options.defineBlockSource }
@@ -207,8 +255,66 @@ function toSortedUniqueStrings(values: string[]): string[] {
 	return Array.from(new Set(values)).sort((a, b) => a.localeCompare(b));
 }
 
+function extractGeneratedLineFromComputeError(message: string): number | null {
+	const lineMatch = message.match(/\bline\s+(\d+)\b/i);
+	if (lineMatch) {
+		const parsed = Number.parseInt(lineMatch[1] ?? '', 10);
+		if (Number.isFinite(parsed) && parsed > 0) {
+			return parsed;
+		}
+	}
+
+	const colonMatch = message.match(/:(\d+):\d+/);
+	if (colonMatch) {
+		const parsed = Number.parseInt(colonMatch[1] ?? '', 10);
+		if (Number.isFinite(parsed) && parsed > 0) {
+			return parsed;
+		}
+	}
+
+	return null;
+}
+
+function toComputeCompilationError(input: {
+	error: unknown;
+	lineMap: ShaderLineMap;
+	computeSource: string;
+	runtimeContext: ShaderCompilationRuntimeContext;
+}): Error {
+	const baseError =
+		input.error instanceof Error ? input.error : new Error(String(input.error ?? 'Unknown error'));
+	const generatedLine = extractGeneratedLineFromComputeError(baseError.message) ?? 0;
+	const sourceLocation = generatedLine > 0 ? (input.lineMap[generatedLine] ?? null) : null;
+	const diagnostics = [
+		{
+			generatedLine,
+			message: baseError.message,
+			sourceLocation
+		}
+	];
+	const sourceLabel = formatShaderSourceLocation(sourceLocation);
+	const generatedLineLabel = generatedLine > 0 ? `generated WGSL line ${generatedLine}` : null;
+	const contextLabel = [sourceLabel, generatedLineLabel].filter((value) => Boolean(value));
+	const summary =
+		contextLabel.length > 0
+			? `[${contextLabel.join(' | ')}] ${baseError.message}`
+			: baseError.message;
+	const wrapped = new Error(`Compute shader compilation failed:\n${summary}`);
+
+	return attachShaderCompilationDiagnostics(wrapped, {
+		kind: 'shader-compilation',
+		shaderStage: 'compute',
+		diagnostics,
+		fragmentSource: '',
+		computeSource: input.computeSource,
+		includeSources: {},
+		materialSource: null,
+		runtimeContext: input.runtimeContext
+	});
+}
+
 function buildPassGraphSnapshot(
-	passes: RenderPass[] | undefined
+	passes: AnyPass[] | undefined
 ): NonNullable<ShaderCompilationRuntimeContext['passGraph']> {
 	const declaredPasses = passes ?? [];
 	let enabledPassCount = 0;
@@ -221,9 +327,13 @@ function buildPassGraphSnapshot(
 		}
 
 		enabledPassCount += 1;
-		const needsSwap = pass.needsSwap ?? true;
-		const input = pass.input ?? 'source';
-		const output = pass.output ?? (needsSwap ? 'target' : 'source');
+		if ('isCompute' in pass && (pass as { isCompute?: boolean }).isCompute === true) {
+			continue;
+		}
+		const rp = pass as RenderPass;
+		const needsSwap = rp.needsSwap ?? true;
+		const input = rp.input ?? 'source';
+		const output = rp.output ?? (needsSwap ? 'target' : 'source');
 		inputs.push(input);
 		outputs.push(output);
 	}
@@ -625,13 +735,22 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 	try {
 		const runtimeContext = buildShaderCompilationRuntimeContext(options);
 		const convertLinearToSrgb = shouldConvertLinearToSrgb(options.outputColorSpace, format);
+		const fragmentTextureKeys = options.textureKeys.filter(
+			(key) => options.textureDefinitions[key]?.fragmentVisible !== false
+		);
 		const builtShader = buildShaderSourceWithMap(
 			options.fragmentWgsl,
 			options.uniformLayout,
-			options.textureKeys,
+			fragmentTextureKeys,
 			{
 				convertLinearToSrgb,
-				fragmentLineMap: options.fragmentLineMap
+				fragmentLineMap: options.fragmentLineMap,
+				...(options.storageBufferKeys !== undefined
+					? { storageBufferKeys: options.storageBufferKeys }
+					: {}),
+				...(options.storageBufferDefinitions !== undefined
+					? { storageBufferDefinitions: options.storageBufferDefinitions }
+					: {})
 			}
 		);
 		const shaderModule = device.createShaderModule({ code: builtShader.code });
@@ -650,13 +769,22 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 			options.textureDefinitions,
 			options.textureKeys
 		);
-		const textureBindings = options.textureKeys.map((key, index): RuntimeTextureBinding => {
+		const storageBufferKeys = options.storageBufferKeys ?? [];
+		const storageBufferDefinitions = options.storageBufferDefinitions ?? {};
+		const storageTextureKeys = options.storageTextureKeys ?? [];
+		const storageTextureKeySet = new Set(storageTextureKeys);
+		const fragmentTextureIndexByKey = new Map(
+			fragmentTextureKeys.map((key, index) => [key, index] as const)
+		);
+		const textureBindings = options.textureKeys.map((key): RuntimeTextureBinding => {
 			const config = normalizedTextureDefinitions[key];
 			if (!config) {
 				throw new Error(`Missing texture definition for "${key}"`);
 			}
 
-			const { samplerBinding, textureBinding } = getTextureBindings(index);
+			const fragmentTextureIndex = fragmentTextureIndexByKey.get(key);
+			const fragmentVisible = fragmentTextureIndex !== undefined;
+			const { samplerBinding, textureBinding } = getTextureBindings(fragmentTextureIndex ?? 0);
 			const sampler = device.createSampler({
 				magFilter: config.filter,
 				minFilter: config.filter,
@@ -665,7 +793,11 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 				addressModeV: config.addressModeV,
 				maxAnisotropy: config.filter === 'linear' ? config.anisotropy : 1
 			});
-			const fallbackTexture = createFallbackTexture(device, config.format);
+			// Storage textures use a safe fallback format — the fallback is never
+			// sampled because storage textures are eagerly allocated with their
+			// real format/dimensions. Non-storage textures use their own format.
+			const fallbackFormat = config.storage ? 'rgba8unorm' : config.format;
+			const fallbackTexture = createFallbackTexture(device, fallbackFormat);
 			registerInitializationCleanup(() => {
 				fallbackTexture.destroy();
 			});
@@ -675,6 +807,7 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 				key,
 				samplerBinding,
 				textureBinding,
+				fragmentVisible,
 				sampler,
 				fallbackTexture,
 				fallbackView,
@@ -701,14 +834,86 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 				runtimeBinding.defaultUpdate = config.update;
 			}
 
+			// Storage textures: eagerly create GPU texture with explicit dimensions
+			if (config.storage && config.width && config.height) {
+				const storageUsage =
+					GPUTextureUsage.TEXTURE_BINDING |
+					GPUTextureUsage.STORAGE_BINDING |
+					GPUTextureUsage.COPY_DST;
+				const storageTexture = device.createTexture({
+					size: { width: config.width, height: config.height, depthOrArrayLayers: 1 },
+					format: config.format,
+					usage: storageUsage
+				});
+				registerInitializationCleanup(() => {
+					storageTexture.destroy();
+				});
+				runtimeBinding.texture = storageTexture as unknown as GPUTexture;
+				runtimeBinding.view = storageTexture.createView();
+				runtimeBinding.width = config.width;
+				runtimeBinding.height = config.height;
+			}
+
 			return runtimeBinding;
 		});
+		const textureBindingByKey = new Map(textureBindings.map((binding) => [binding.key, binding]));
+		const fragmentTextureBindings = textureBindings.filter((binding) => binding.fragmentVisible);
+
+		const computeStorageBufferLayoutEntries: GPUBindGroupLayoutEntry[] = storageBufferKeys.map(
+			(key, index) => {
+				const def = storageBufferDefinitions[key];
+				const access = def?.access ?? 'read-write';
+				const bufferType: GPUBufferBindingType =
+					access === 'read' ? 'read-only-storage' : 'storage';
+				return {
+					binding: index,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: bufferType }
+				};
+			}
+		);
+		const computeStorageBufferTopologyKey = storageBufferKeys
+			.map((key) => `${key}:${storageBufferDefinitions[key]?.access ?? 'read-write'}`)
+			.join('|');
+
+		const computeStorageTextureLayoutEntries: GPUBindGroupLayoutEntry[] = storageTextureKeys.map(
+			(key, index) => {
+				const config = normalizedTextureDefinitions[key];
+				return {
+					binding: index,
+					visibility: GPUShaderStage.COMPUTE,
+					storageTexture: {
+						access: 'write-only' as GPUStorageTextureAccess,
+						format: (config?.format ?? 'rgba8unorm') as GPUTextureFormat,
+						viewDimension: '2d'
+					}
+				};
+			}
+		);
+		const computeStorageTextureTopologyKey = storageTextureKeys
+			.map((key) => `${key}:${normalizedTextureDefinitions[key]?.format ?? 'rgba8unorm'}`)
+			.join('|');
+
+		const computeStorageBufferBindGroupCache = createComputeStorageBindGroupCache(device);
+		const computeStorageTextureBindGroupCache = createComputeStorageBindGroupCache(device);
 
 		const bindGroupLayout = device.createBindGroupLayout({
-			entries: createBindGroupLayoutEntries(textureBindings)
+			entries: createBindGroupLayoutEntries(fragmentTextureBindings)
 		});
+		const fragmentStorageBindGroupLayout =
+			storageBufferKeys.length > 0
+				? device.createBindGroupLayout({
+						entries: storageBufferKeys.map((_, index) => ({
+							binding: index,
+							visibility: GPUShaderStage.FRAGMENT,
+							buffer: { type: 'read-only-storage' as GPUBufferBindingType }
+						}))
+					})
+				: null;
 		const pipelineLayout = device.createPipelineLayout({
-			bindGroupLayouts: [bindGroupLayout]
+			bindGroupLayouts: fragmentStorageBindGroupLayout
+				? [bindGroupLayout, fragmentStorageBindGroupLayout]
+				: [bindGroupLayout]
 		});
 
 		const pipeline = device.createRenderPipeline({
@@ -773,6 +978,372 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 		});
 		let blitBindGroupByView = new WeakMap<GPUTextureView, GPUBindGroup>();
 
+		// ── Storage buffer allocation ────────────────────────────────────────
+		const storageBufferMap = new Map<string, GPUBuffer>();
+		const pingPongTexturePairs = new Map<string, PingPongTexturePair>();
+
+		for (const key of storageBufferKeys) {
+			const definition = storageBufferDefinitions[key];
+			if (!definition) {
+				continue;
+			}
+			const normalized = normalizeStorageBufferDefinition(definition);
+			const buffer = device.createBuffer({
+				size: normalized.size,
+				usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
+			});
+			registerInitializationCleanup(() => {
+				buffer.destroy();
+			});
+			if (definition.initialData) {
+				const data = definition.initialData;
+				device.queue.writeBuffer(
+					buffer,
+					0,
+					data.buffer as ArrayBuffer,
+					data.byteOffset,
+					data.byteLength
+				);
+			}
+			storageBufferMap.set(key, buffer);
+		}
+		const fragmentStorageBindGroup =
+			fragmentStorageBindGroupLayout && storageBufferKeys.length > 0
+				? device.createBindGroup({
+						layout: fragmentStorageBindGroupLayout,
+						entries: storageBufferKeys.map((key, index) => {
+							const buffer = storageBufferMap.get(key);
+							if (!buffer) {
+								throw new Error(`Storage buffer "${key}" not allocated.`);
+							}
+							return { binding: index, resource: { buffer } };
+						})
+					})
+				: null;
+
+		const ensurePingPongTexturePair = (target: string): PingPongTexturePair => {
+			const existing = pingPongTexturePairs.get(target);
+			if (existing) {
+				return existing;
+			}
+
+			const config = normalizedTextureDefinitions[target];
+			if (!config || !config.storage) {
+				throw new Error(
+					`PingPongComputePass target "${target}" must reference a texture declared with storage:true.`
+				);
+			}
+			if (!config.width || !config.height) {
+				throw new Error(
+					`PingPongComputePass target "${target}" requires explicit texture width and height.`
+				);
+			}
+
+			const usage =
+				GPUTextureUsage.TEXTURE_BINDING |
+				GPUTextureUsage.STORAGE_BINDING |
+				GPUTextureUsage.COPY_DST;
+			const textureA = device.createTexture({
+				size: { width: config.width, height: config.height, depthOrArrayLayers: 1 },
+				format: config.format,
+				usage
+			});
+			const textureB = device.createTexture({
+				size: { width: config.width, height: config.height, depthOrArrayLayers: 1 },
+				format: config.format,
+				usage
+			});
+			registerInitializationCleanup(() => {
+				textureA.destroy();
+			});
+			registerInitializationCleanup(() => {
+				textureB.destroy();
+			});
+
+			const sampleScalarType = storageTextureSampleScalarType(config.format);
+			const sampleType = toGpuTextureSampleType(sampleScalarType);
+			const bindGroupLayout = device.createBindGroupLayout({
+				entries: [
+					{
+						binding: 0,
+						visibility: GPUShaderStage.COMPUTE,
+						texture: {
+							sampleType,
+							viewDimension: '2d',
+							multisampled: false
+						}
+					},
+					{
+						binding: 1,
+						visibility: GPUShaderStage.COMPUTE,
+						storageTexture: {
+							access: 'write-only' as GPUStorageTextureAccess,
+							format: config.format as GPUTextureFormat,
+							viewDimension: '2d'
+						}
+					}
+				]
+			});
+
+			const pair: PingPongTexturePair = {
+				target,
+				format: config.format as GPUTextureFormat,
+				width: config.width,
+				height: config.height,
+				textureA,
+				viewA: textureA.createView(),
+				textureB,
+				viewB: textureB.createView(),
+				bindGroupLayout,
+				readAWriteBBindGroup: null,
+				readBWriteABindGroup: null
+			};
+			pingPongTexturePairs.set(target, pair);
+			return pair;
+		};
+
+		// ── Compute pipeline setup ──────────────────────────────────────────
+		interface ComputePipelineEntry {
+			pipeline: GPUComputePipeline;
+			bindGroup: GPUBindGroup;
+			workgroupSize: [number, number, number];
+			computeSource: string;
+		}
+		const computePipelineCache = new Map<string, ComputePipelineEntry>();
+
+		const buildComputePipelineEntry = (buildOptions: {
+			computeSource: string;
+			pingPongTarget?: string;
+			pingPongFormat?: GPUTextureFormat;
+		}): ComputePipelineEntry => {
+			const cacheKey =
+				buildOptions.pingPongTarget && buildOptions.pingPongFormat
+					? `pingpong:${buildOptions.pingPongTarget}:${buildOptions.pingPongFormat}:${buildOptions.computeSource}`
+					: `compute:${buildOptions.computeSource}`;
+			const cached = computePipelineCache.get(cacheKey);
+			if (cached) {
+				return cached;
+			}
+
+			const storageBufferDefs: Record<
+				string,
+				{ type: StorageBufferType; access: StorageBufferAccess }
+			> = {};
+			for (const key of storageBufferKeys) {
+				const def = storageBufferDefinitions[key];
+				if (def) {
+					const norm = normalizeStorageBufferDefinition(def);
+					storageBufferDefs[key] = { type: norm.type, access: norm.access };
+				}
+			}
+			const storageTextureDefs: Record<string, { format: GPUTextureFormat }> = {};
+			for (const key of storageTextureKeys) {
+				const texDef = options.textureDefinitions[key];
+				if (texDef?.format) {
+					storageTextureDefs[key] = { format: texDef.format };
+				}
+			}
+
+			const isPingPongPipeline = Boolean(
+				buildOptions.pingPongTarget && buildOptions.pingPongFormat
+			);
+			const builtComputeShader = isPingPongPipeline
+				? buildPingPongComputeShaderSourceWithMap({
+						compute: buildOptions.computeSource,
+						uniformLayout: options.uniformLayout,
+						storageBufferKeys,
+						storageBufferDefinitions: storageBufferDefs,
+						target: buildOptions.pingPongTarget!,
+						targetFormat: buildOptions.pingPongFormat!
+					})
+				: buildComputeShaderSourceWithMap({
+						compute: buildOptions.computeSource,
+						uniformLayout: options.uniformLayout,
+						storageBufferKeys,
+						storageBufferDefinitions: storageBufferDefs,
+						storageTextureKeys,
+						storageTextureDefinitions: storageTextureDefs
+					});
+
+			const computeShaderModule = device.createShaderModule({ code: builtComputeShader.code });
+			const workgroupSize = extractWorkgroupSize(buildOptions.computeSource);
+
+			// Compute bind group layout: group(0)=uniforms, group(1)=storage buffers, group(2)=storage textures
+			const computeUniformBGL = device.createBindGroupLayout({
+				entries: [
+					{
+						binding: FRAME_BINDING,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: 'uniform', minBindingSize: 16 }
+					},
+					{
+						binding: UNIFORM_BINDING,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: 'uniform' }
+					}
+				]
+			});
+
+			const storageBGL =
+				computeStorageBufferLayoutEntries.length > 0
+					? device.createBindGroupLayout({ entries: computeStorageBufferLayoutEntries })
+					: null;
+
+			const storageTextureBGLEntries: GPUBindGroupLayoutEntry[] = isPingPongPipeline
+				? [
+						{
+							binding: 0,
+							visibility: GPUShaderStage.COMPUTE,
+							texture: {
+								sampleType: toGpuTextureSampleType(
+									storageTextureSampleScalarType(buildOptions.pingPongFormat!)
+								),
+								viewDimension: '2d',
+								multisampled: false
+							}
+						},
+						{
+							binding: 1,
+							visibility: GPUShaderStage.COMPUTE,
+							storageTexture: {
+								access: 'write-only' as GPUStorageTextureAccess,
+								format: buildOptions.pingPongFormat!,
+								viewDimension: '2d'
+							}
+						}
+					]
+				: computeStorageTextureLayoutEntries;
+			const storageTextureBGL =
+				storageTextureBGLEntries.length > 0
+					? device.createBindGroupLayout({ entries: storageTextureBGLEntries })
+					: null;
+
+			// Bind group layout indices must match shader @group() indices:
+			// group(0) = uniforms, group(1) = storage buffers, group(2) = storage textures.
+			// When a group is unused, insert an empty placeholder to keep indices aligned.
+			const bindGroupLayouts: GPUBindGroupLayout[] = [computeUniformBGL];
+			if (storageBGL || storageTextureBGL) {
+				bindGroupLayouts.push(storageBGL ?? device.createBindGroupLayout({ entries: [] }));
+			}
+			if (storageTextureBGL) {
+				bindGroupLayouts.push(storageTextureBGL);
+			}
+
+			const computePipelineLayout = device.createPipelineLayout({ bindGroupLayouts });
+			let pipeline: GPUComputePipeline;
+			try {
+				pipeline = device.createComputePipeline({
+					layout: computePipelineLayout,
+					compute: {
+						module: computeShaderModule,
+						entryPoint: 'compute'
+					}
+				});
+			} catch (error) {
+				throw toComputeCompilationError({
+					error,
+					lineMap: builtComputeShader.lineMap,
+					computeSource: buildOptions.computeSource,
+					runtimeContext
+				});
+			}
+
+			// Build uniform bind group for compute (group 0)
+			const computeUniformBindGroup = device.createBindGroup({
+				layout: computeUniformBGL,
+				entries: [
+					{ binding: FRAME_BINDING, resource: { buffer: frameBuffer } },
+					{ binding: UNIFORM_BINDING, resource: { buffer: uniformBuffer } }
+				]
+			});
+
+			const entry: ComputePipelineEntry = {
+				pipeline,
+				bindGroup: computeUniformBindGroup,
+				workgroupSize,
+				computeSource: buildOptions.computeSource
+			};
+			computePipelineCache.set(cacheKey, entry);
+			return entry;
+		};
+
+		// Helper to get the storage bind group for dispatch
+		const getComputeStorageBindGroup = (): GPUBindGroup | null => {
+			if (computeStorageBufferLayoutEntries.length === 0) {
+				return null;
+			}
+			const resources: GPUBuffer[] = storageBufferKeys.map((key) => {
+				const buffer = storageBufferMap.get(key);
+				if (!buffer) {
+					throw new Error(`Storage buffer "${key}" not allocated.`);
+				}
+				return buffer;
+			});
+			const storageEntries: GPUBindGroupEntry[] = resources.map((buffer, index) => {
+				return { binding: index, resource: { buffer } };
+			});
+			return computeStorageBufferBindGroupCache.getOrCreate({
+				topologyKey: computeStorageBufferTopologyKey,
+				layoutEntries: computeStorageBufferLayoutEntries,
+				bindGroupEntries: storageEntries,
+				resourceRefs: resources
+			});
+		};
+
+		// Helper to get the storage texture bind group for compute dispatch (group 2)
+		const getComputeStorageTextureBindGroup = (): GPUBindGroup | null => {
+			if (computeStorageTextureLayoutEntries.length === 0) {
+				return null;
+			}
+			const resources: GPUTextureView[] = storageTextureKeys.map((key) => {
+				const binding = textureBindingByKey.get(key);
+				if (!binding || !binding.texture) {
+					throw new Error(`Storage texture "${key}" not allocated.`);
+				}
+				return binding.view;
+			});
+			const bgEntries: GPUBindGroupEntry[] = resources.map((view, index) => {
+				return { binding: index, resource: view };
+			});
+
+			return computeStorageTextureBindGroupCache.getOrCreate({
+				topologyKey: computeStorageTextureTopologyKey,
+				layoutEntries: computeStorageTextureLayoutEntries,
+				bindGroupEntries: bgEntries,
+				resourceRefs: resources
+			});
+		};
+
+		// Helper to get ping-pong storage texture bind group for compute dispatch (group 2)
+		const getPingPongStorageTextureBindGroup = (
+			target: string,
+			readFromA: boolean
+		): GPUBindGroup => {
+			const pair = ensurePingPongTexturePair(target);
+			if (readFromA) {
+				if (!pair.readAWriteBBindGroup) {
+					pair.readAWriteBBindGroup = device.createBindGroup({
+						layout: pair.bindGroupLayout,
+						entries: [
+							{ binding: 0, resource: pair.viewA },
+							{ binding: 1, resource: pair.viewB }
+						]
+					});
+				}
+				return pair.readAWriteBBindGroup;
+			}
+			if (!pair.readBWriteABindGroup) {
+				pair.readBWriteABindGroup = device.createBindGroup({
+					layout: pair.bindGroupLayout,
+					entries: [
+						{ binding: 0, resource: pair.viewB },
+						{ binding: 1, resource: pair.viewA }
+					]
+				});
+			}
+			return pair.readBWriteABindGroup;
+		};
+
 		const frameBuffer = device.createBuffer({
 			size: 16,
 			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
@@ -802,7 +1373,7 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 				{ binding: UNIFORM_BINDING, resource: { buffer: uniformBuffer } }
 			];
 
-			for (const binding of textureBindings) {
+			for (const binding of fragmentTextureBindings) {
 				entries.push({
 					binding: binding.samplerBinding,
 					resource: binding.sampler
@@ -891,14 +1462,18 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 				return false;
 			}
 
+			let textureUsage =
+				GPUTextureUsage.TEXTURE_BINDING |
+				GPUTextureUsage.COPY_DST |
+				GPUTextureUsage.RENDER_ATTACHMENT;
+			if (storageTextureKeySet.has(binding.key)) {
+				textureUsage |= GPUTextureUsage.STORAGE_BINDING;
+			}
 			const texture = device.createTexture({
 				size: { width, height, depthOrArrayLayers: 1 },
 				format,
 				mipLevelCount,
-				usage:
-					GPUTextureUsage.TEXTURE_BINDING |
-					GPUTextureUsage.COPY_DST |
-					GPUTextureUsage.RENDER_ATTACHMENT
+				usage: textureUsage
 			});
 			registerInitializationCleanup(() => {
 				texture.destroy();
@@ -924,6 +1499,8 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 		};
 
 		for (const binding of textureBindings) {
+			// Skip storage textures — they are eagerly allocated and not source-driven
+			if (storageTextureKeySet.has(binding.key)) continue;
 			const defaultSource = normalizedTextureDefinitions[binding.key]?.source ?? null;
 			updateTextureBinding(binding, defaultSource, 'always');
 		}
@@ -942,18 +1519,18 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 		let configuredWidth = 0;
 		let configuredHeight = 0;
 		const runtimeRenderTargets = new Map<string, RuntimeRenderTarget>();
-		const activePasses: RenderPass[] = [];
-		const lifecyclePreviousSet = new Set<RenderPass>();
-		const lifecycleNextSet = new Set<RenderPass>();
-		const lifecycleUniquePasses: RenderPass[] = [];
-		let lifecyclePassesRef: RenderPass[] | null = null;
+		const activePasses: AnyPass[] = [];
+		const lifecyclePreviousSet = new Set<AnyPass>();
+		const lifecycleNextSet = new Set<AnyPass>();
+		const lifecycleUniquePasses: AnyPass[] = [];
+		let lifecyclePassesRef: AnyPass[] | null = null;
 		let passWidth = 0;
 		let passHeight = 0;
 
 		/**
 		 * Resolves active render pass list for current frame.
 		 */
-		const resolvePasses = (): RenderPass[] => {
+		const resolvePasses = (): AnyPass[] => {
 			return options.getPasses?.() ?? options.passes ?? [];
 		};
 
@@ -968,7 +1545,7 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 		 * Checks whether cached render-graph plan can be reused for this frame.
 		 */
 		const isGraphPlanCacheValid = (
-			passes: RenderPass[],
+			passes: AnyPass[],
 			clearColor: [number, number, number, number]
 		): boolean => {
 			if (!cachedGraphPlan) {
@@ -994,6 +1571,7 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 
 			for (let index = 0; index < passes.length; index += 1) {
 				const pass = passes[index];
+				const rp = pass as Partial<RenderPass>;
 				const snapshot = cachedGraphPasses[index];
 				if (!pass || !snapshot || snapshot.pass !== pass) {
 					return false;
@@ -1001,16 +1579,16 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 
 				if (
 					snapshot.enabled !== pass.enabled ||
-					snapshot.needsSwap !== pass.needsSwap ||
-					snapshot.input !== pass.input ||
-					snapshot.output !== pass.output ||
-					snapshot.clear !== pass.clear ||
-					snapshot.preserve !== pass.preserve
+					snapshot.needsSwap !== rp.needsSwap ||
+					snapshot.input !== rp.input ||
+					snapshot.output !== rp.output ||
+					snapshot.clear !== rp.clear ||
+					snapshot.preserve !== rp.preserve
 				) {
 					return false;
 				}
 
-				const passClearColor = pass.clearColor;
+				const passClearColor = rp.clearColor;
 				const hasPassClearColor = passClearColor !== undefined;
 				if (snapshot.hasClearColor !== hasPassClearColor) {
 					return false;
@@ -1035,7 +1613,7 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 		 * Updates render-graph cache with current pass set.
 		 */
 		const updateGraphPlanCache = (
-			passes: RenderPass[],
+			passes: AnyPass[],
 			clearColor: [number, number, number, number],
 			graphPlan: RenderGraphPlan
 		): void => {
@@ -1049,18 +1627,19 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 
 			let index = 0;
 			for (const pass of passes) {
-				const passClearColor = pass.clearColor;
+				const rp = pass as Partial<RenderPass>;
+				const passClearColor = rp.clearColor;
 				const hasPassClearColor = passClearColor !== undefined;
 				const snapshot = cachedGraphPasses[index];
 				if (!snapshot) {
 					cachedGraphPasses[index] = {
 						pass,
 						enabled: pass.enabled,
-						needsSwap: pass.needsSwap,
-						input: pass.input,
-						output: pass.output,
-						clear: pass.clear,
-						preserve: pass.preserve,
+						needsSwap: rp.needsSwap,
+						input: rp.input,
+						output: rp.output,
+						clear: rp.clear,
+						preserve: rp.preserve,
 						hasClearColor: hasPassClearColor,
 						clearColor0: passClearColor?.[0] ?? 0,
 						clearColor1: passClearColor?.[1] ?? 0,
@@ -1073,11 +1652,11 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 
 				snapshot.pass = pass;
 				snapshot.enabled = pass.enabled;
-				snapshot.needsSwap = pass.needsSwap;
-				snapshot.input = pass.input;
-				snapshot.output = pass.output;
-				snapshot.clear = pass.clear;
-				snapshot.preserve = pass.preserve;
+				snapshot.needsSwap = rp.needsSwap;
+				snapshot.input = rp.input;
+				snapshot.output = rp.output;
+				snapshot.clear = rp.clear;
+				snapshot.preserve = rp.preserve;
 				snapshot.hasClearColor = hasPassClearColor;
 				snapshot.clearColor0 = passClearColor?.[0] ?? 0;
 				snapshot.clearColor1 = passClearColor?.[1] ?? 0;
@@ -1090,7 +1669,7 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 		/**
 		 * Synchronizes pass lifecycle callbacks and resize notifications.
 		 */
-		const syncPassLifecycle = (passes: RenderPass[], width: number, height: number): void => {
+		const syncPassLifecycle = (passes: AnyPass[], width: number, height: number): void => {
 			const resized = passWidth !== width || passHeight !== height;
 			if (!resized && lifecyclePassesRef === passes && passes.length === activePasses.length) {
 				let isSameOrder = true;
@@ -1292,7 +1871,8 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 			renderMode,
 			uniforms,
 			textures,
-			canvasSize
+			canvasSize,
+			pendingStorageWrites
 		}) => {
 			if (deviceLostMessage) {
 				throw new Error(deviceLostMessage);
@@ -1361,9 +1941,11 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 
 			let bindGroupDirty = false;
 			for (const binding of textureBindings) {
+				// Storage textures are managed by compute passes, skip source-driven updates
+				if (storageTextureKeySet.has(binding.key)) continue;
 				const nextTexture =
 					textures[binding.key] ?? normalizedTextureDefinitions[binding.key]?.source ?? null;
-				if (updateTextureBinding(binding, nextTexture, renderMode)) {
+				if (updateTextureBinding(binding, nextTexture, renderMode) && binding.fragmentVisible) {
 					bindGroupDirty = true;
 				}
 			}
@@ -1372,6 +1954,23 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 				bindGroup = createBindGroup();
 			}
 
+			// Apply pending storage buffer writes
+			if (pendingStorageWrites) {
+				for (const write of pendingStorageWrites) {
+					const buffer = storageBufferMap.get(write.name);
+					if (buffer) {
+						const data = write.data;
+						device.queue.writeBuffer(
+							buffer,
+							write.offset,
+							data.buffer as ArrayBuffer,
+							data.byteOffset,
+							data.byteLength
+						);
+					}
+				}
+			}
+
 			const commandEncoder = device.createCommandEncoder();
 			const passes = resolvePasses();
 			const clearColor = options.getClearColor();
@@ -1402,6 +2001,98 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 					: null;
 			const sceneOutput = slots ? slots.source : canvasSurface;
 
+			// Dispatch compute passes BEFORE scene render so storage textures
+			// and buffers are up-to-date when the fragment shader samples them.
+			if (slots) {
+				for (const step of graphPlan.steps) {
+					if (step.kind !== 'compute') {
+						continue;
+					}
+					const computePass = step.pass as {
+						isCompute?: boolean;
+						getCompute?: () => string;
+						resolveDispatch?: (ctx: {
+							width: number;
+							height: number;
+							time: number;
+							delta: number;
+							workgroupSize: [number, number, number];
+						}) => [number, number, number];
+						getWorkgroupSize?: () => [number, number, number];
+						isPingPong?: boolean;
+						getTarget?: () => string;
+						getCurrentOutput?: () => string;
+						getIterations?: () => number;
+						advanceFrame?: () => void;
+					};
+					if (
+						computePass.getCompute &&
+						computePass.resolveDispatch &&
+						computePass.getWorkgroupSize
+					) {
+						const computeSource = computePass.getCompute();
+						const pingPongTarget =
+							computePass.isPingPong && computePass.getTarget ? computePass.getTarget() : undefined;
+						if (computePass.isPingPong && !pingPongTarget) {
+							throw new Error('PingPongComputePass must provide a target texture key.');
+						}
+						const pingPongPair = pingPongTarget ? ensurePingPongTexturePair(pingPongTarget) : null;
+						const pipelineEntry = buildComputePipelineEntry({
+							computeSource,
+							...(pingPongPair
+								? {
+										pingPongTarget: pingPongPair.target,
+										pingPongFormat: pingPongPair.format
+									}
+								: {})
+						});
+						const workgroupSize = computePass.getWorkgroupSize();
+						const storageBindGroup = getComputeStorageBindGroup();
+						const storageTextureBindGroup = getComputeStorageTextureBindGroup();
+						const iterations =
+							computePass.isPingPong && computePass.getIterations ? computePass.getIterations() : 1;
+						const currentOutput =
+							computePass.isPingPong && computePass.getCurrentOutput
+								? computePass.getCurrentOutput()
+								: null;
+						const readFromAAtIterationZero =
+							pingPongPair && currentOutput ? currentOutput !== `${pingPongPair.target}B` : true;
+
+						for (let iter = 0; iter < iterations; iter += 1) {
+							const dispatch = computePass.resolveDispatch({
+								width,
+								height,
+								time,
+								delta,
+								workgroupSize
+							});
+							const cPass = commandEncoder.beginComputePass();
+							cPass.setPipeline(pipelineEntry.pipeline);
+							cPass.setBindGroup(0, pipelineEntry.bindGroup);
+							if (storageBindGroup) {
+								cPass.setBindGroup(1, storageBindGroup);
+							}
+							if (pingPongPair) {
+								const readFromA =
+									iter % 2 === 0 ? readFromAAtIterationZero : !readFromAAtIterationZero;
+								cPass.setBindGroup(
+									2,
+									getPingPongStorageTextureBindGroup(pingPongPair.target, readFromA)
+								);
+							} else if (storageTextureBindGroup) {
+								cPass.setBindGroup(2, storageTextureBindGroup);
+							}
+							cPass.dispatchWorkgroups(dispatch[0], dispatch[1], dispatch[2]);
+							cPass.end();
+						}
+
+						if (computePass.isPingPong && computePass.advanceFrame) {
+							computePass.advanceFrame();
+						}
+					}
+				}
+			}
+
 			const scenePass = commandEncoder.beginRenderPass({
 				colorAttachments: [
 					{
@@ -1420,6 +2111,9 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 
 			scenePass.setPipeline(pipeline);
 			scenePass.setBindGroup(0, bindGroup);
+			if (fragmentStorageBindGroup) {
+				scenePass.setBindGroup(1, fragmentStorageBindGroup);
+			}
 			scenePass.draw(3);
 			scenePass.end();
 
@@ -1448,10 +2142,15 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 				};
 
 				for (const step of graphPlan.steps) {
+					// Compute passes already dispatched above
+					if (step.kind === 'compute') {
+						continue;
+					}
+
 					const input = resolveStepSurface(step.input);
 					const output = resolveStepSurface(step.output);
 
-					step.pass.render({
+					(step.pass as RenderPass).render({
 						device,
 						commandEncoder,
 						source: slots.source,
@@ -1467,7 +2166,12 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 						clear: step.clear,
 						clearColor: step.clearColor,
 						preserve: step.preserve,
-						beginRenderPass: (passOptions) => {
+						beginRenderPass: (passOptions?: {
+							clear?: boolean;
+							clearColor?: [number, number, number, number];
+							preserve?: boolean;
+							view?: GPUTextureView;
+						}) => {
 							const clear = passOptions?.clear ?? step.clear;
 							const clearColor = passOptions?.clearColor ?? step.clearColor;
 							const preserve = passOptions?.preserve ?? step.preserve;
@@ -1510,11 +2214,27 @@ export async function createRenderer(options: RendererOptions): Promise<Renderer
 		initializationCleanups.length = 0;
 		return {
 			render,
+			getStorageBuffer: (name: string): GPUBuffer | undefined => {
+				return storageBufferMap.get(name);
+			},
+			getDevice: (): GPUDevice => {
+				return device;
+			},
 			destroy: () => {
 				isDestroyed = true;
 				device.removeEventListener('uncapturederror', handleUncapturedError);
 				frameBuffer.destroy();
 				uniformBuffer.destroy();
+				for (const buffer of storageBufferMap.values()) {
+					buffer.destroy();
+				}
+				storageBufferMap.clear();
+				for (const pair of pingPongTexturePairs.values()) {
+					pair.textureA.destroy();
+					pair.textureB.destroy();
+				}
+				pingPongTexturePairs.clear();
+				computePipelineCache.clear();
 				destroyRenderTexture(sourceSlotTarget);
 				destroyRenderTexture(targetSlotTarget);
 				for (const target of runtimeRenderTargets.values()) {