@motion-core/motion-gpu 0.4.2 → 0.5.0

package/src/lib/core/error-report.ts

@@ -17,13 +17,22 @@ export type MotionGPUErrorCode =
 	| 'WEBGPU_ADAPTER_UNAVAILABLE'
 	| 'WEBGPU_CONTEXT_UNAVAILABLE'
 	| 'WGSL_COMPILATION_FAILED'
+	| 'MATERIAL_PREPROCESS_FAILED'
 	| 'WEBGPU_DEVICE_LOST'
 	| 'WEBGPU_UNCAPTURED_ERROR'
 	| 'BIND_GROUP_MISMATCH'
+	| 'RUNTIME_RESOURCE_MISSING'
+	| 'UNIFORM_VALUE_INVALID'
+	| 'STORAGE_BUFFER_OUT_OF_BOUNDS'
+	| 'STORAGE_BUFFER_READ_FAILED'
+	| 'RENDER_GRAPH_INVALID'
+	| 'PINGPONG_CONFIGURATION_INVALID'
 	| 'TEXTURE_USAGE_INVALID'
 	| 'TEXTURE_REQUEST_FAILED'
 	| 'TEXTURE_DECODE_UNAVAILABLE'
 	| 'TEXTURE_REQUEST_ABORTED'
+	| 'COMPUTE_COMPILATION_FAILED'
+	| 'COMPUTE_CONTRACT_INVALID'
 	| 'MOTIONGPU_RUNTIME_ERROR';
 
 /**
@@ -274,6 +283,50 @@ function classifyErrorMessage(
 		};
 	}
 
+	if (
+		message.includes('Invalid include directive in fragment shader.') ||
+		message.includes('Unknown include "') ||
+		message.includes('Circular include detected for "') ||
+		message.includes('Invalid define value for "') ||
+		message.includes('Invalid include "')
+	) {
+		return {
+			code: 'MATERIAL_PREPROCESS_FAILED',
+			severity: 'error',
+			recoverable: true,
+			title: 'Material preprocess failed',
+			hint: 'Validate #include keys, define values and include expansion order before retrying.'
+		};
+	}
+
+	if (message.includes('Compute shader compilation failed')) {
+		return {
+			code: 'COMPUTE_COMPILATION_FAILED',
+			severity: 'error',
+			recoverable: true,
+			title: 'Compute shader compilation failed',
+			hint: 'Check WGSL compute shader sources below and verify storage bindings.'
+		};
+	}
+
+	if (
+		message.includes(
+			'Compute shader must declare `@compute @workgroup_size(...) fn compute(...)`.'
+		) ||
+		message.includes('Compute shader must include a `@builtin(global_invocation_id)` parameter.') ||
+		message.includes('Could not extract @workgroup_size from compute shader source.') ||
+		message.includes('@workgroup_size dimensions must be integers in range') ||
+		message.includes('Unsupported storage buffer access mode "')
+	) {
+		return {
+			code: 'COMPUTE_CONTRACT_INVALID',
+			severity: 'error',
+			recoverable: true,
+			title: 'Compute contract is invalid',
+			hint: 'Ensure compute shader contract (@compute, @workgroup_size, global_invocation_id, storage access) is valid.'
+		};
+	}
+
 	if (message.includes('WebGPU device lost') || message.includes('Device Lost')) {
 		return {
 			code: 'WEBGPU_DEVICE_LOST',
@@ -304,6 +357,82 @@ function classifyErrorMessage(
 		};
 	}
 
+	if (message.includes('Storage buffer "') && message.includes('write out of bounds:')) {
+		return {
+			code: 'STORAGE_BUFFER_OUT_OF_BOUNDS',
+			severity: 'error',
+			recoverable: true,
+			title: 'Storage buffer write out of bounds',
+			hint: 'Ensure offset + write byte length does not exceed declared storage buffer size.'
+		};
+	}
+
+	if (
+		message.includes('Cannot read storage buffer "') ||
+		message.includes('Cannot read storage buffer: GPU device unavailable.') ||
+		message.includes('not allocated on GPU.')
+	) {
+		return {
+			code: 'STORAGE_BUFFER_READ_FAILED',
+			severity: 'error',
+			recoverable: true,
+			title: 'Storage buffer read failed',
+			hint: 'Readbacks require an initialized renderer, allocated GPU buffer and active device.'
+		};
+	}
+
+	if (
+		message.includes('Unknown uniform "') ||
+		message.includes('Unknown uniform type for "') ||
+		message.includes('Unknown texture "') ||
+		message.includes('Unknown storage buffer "') ||
+		message.includes('Missing definition for storage buffer "') ||
+		message.includes('Missing texture definition for "') ||
+		(message.includes('Storage buffer "') && message.includes('" not allocated.')) ||
+		(message.includes('Storage texture "') && message.includes('" not allocated.'))
+	) {
+		return {
+			code: 'RUNTIME_RESOURCE_MISSING',
+			severity: 'error',
+			recoverable: true,
+			title: 'Runtime resource binding failed',
+			hint: 'Check material declarations and runtime keys for uniforms, textures and storage resources.'
+		};
+	}
+
+	if (message.includes('Uniform ') && message.includes(' value must')) {
+		return {
+			code: 'UNIFORM_VALUE_INVALID',
+			severity: 'error',
+			recoverable: true,
+			title: 'Uniform value is invalid',
+			hint: 'Provide finite values with tuple/matrix sizes matching the uniform type.'
+		};
+	}
+
+	if (
+		message.includes('Render pass #') ||
+		message.includes('Render graph references unknown runtime target')
+	) {
+		return {
+			code: 'RENDER_GRAPH_INVALID',
+			severity: 'error',
+			recoverable: true,
+			title: 'Render graph configuration is invalid',
+			hint: 'Verify pass inputs/outputs, declared render targets and execution order.'
+		};
+	}
+
+	if (message.includes('PingPongComputePass must provide a target texture key.')) {
+		return {
+			code: 'PINGPONG_CONFIGURATION_INVALID',
+			severity: 'error',
+			recoverable: true,
+			title: 'Ping-pong compute pass is misconfigured',
+			hint: 'Configure a valid target texture key for PingPongComputePass.'
+		};
+	}
+
 	if (message.includes('Destination texture needs to have CopyDst')) {
 		return {
 			code: 'TEXTURE_USAGE_INVALID',

package/src/lib/core/frame-registry.ts

@@ -1003,7 +1003,8 @@ export function createFrameRegistry(options?: {
 				stop,
 				started: internalTask.startedStore,
 				unsubscribe: () => {
-					if (stage.tasks.delete(key)) {
+					const current = stage.tasks.get(key);
+					if (current === internalTask && stage.tasks.delete(key)) {
 						markScheduleDirty();
 					}
 				}

package/src/lib/core/index.ts

@@ -9,7 +9,13 @@ export { createCurrentWritable } from './current-value.js';
 export { createFrameRegistry } from './frame-registry.js';
 export { createMotionGPURuntimeLoop } from './runtime-loop.js';
 export { loadTexturesFromUrls } from './texture-loader.js';
-export { BlitPass, CopyPass, ShaderPass } from '../passes/index.js';
+export {
+	BlitPass,
+	CopyPass,
+	ShaderPass,
+	ComputePass,
+	PingPongComputePass
+} from '../passes/index.js';
 export type { CurrentReadable, CurrentWritable, Subscribable } from './current-value.js';
 export type {
 	MotionGPUErrorCode,
@@ -51,6 +57,8 @@ export type {
 	FrameInvalidationToken,
 	FrameState,
 	OutputColorSpace,
+	AnyPass,
+	ComputePassLike,
 	RenderPass,
 	RenderPassContext,
 	RenderPassFlags,
@@ -75,3 +83,12 @@ export type {
 	UniformType,
 	UniformValue
 } from './types.js';
+export type {
+	StorageBufferAccess,
+	StorageBufferDefinition,
+	StorageBufferDefinitionMap,
+	StorageBufferType,
+	ComputePassContext
+} from './types.js';
+export type { ComputePassOptions, ComputeDispatchContext } from '../passes/ComputePass.js';
+export type { PingPongComputePassOptions } from '../passes/PingPongComputePass.js';

package/src/lib/core/material-preprocess.ts

@@ -175,7 +175,8 @@ function expandChunk(
 	kind: 'fragment' | 'include',
 	includeName: string | undefined,
 	includes: Record<string, string>,
-	stack: string[]
+	stack: string[],
+	expandedIncludes: Set<string>
 ): { lines: string[]; mapEntries: MaterialSourceLocation[] } {
 	const sourceLines = source.split('\n');
 	const lines: string[] = [];
@@ -215,10 +216,19 @@ function expandChunk(
 			);
 		}
 
-		const nested = expandChunk(includeSource, 'include', includeKey, includes, [
-			...stack,
-			includeKey
-		]);
+		if (expandedIncludes.has(includeKey)) {
+			continue;
+		}
+		expandedIncludes.add(includeKey);
+
+		const nested = expandChunk(
+			includeSource,
+			'include',
+			includeKey,
+			includes,
+			[...stack, includeKey],
+			expandedIncludes
+		);
 		lines.push(...nested.lines);
 		mapEntries.push(...nested.mapEntries);
 	}
@@ -245,7 +255,8 @@ export function preprocessMaterialFragment<
 		'fragment',
 		undefined,
 		normalizedIncludes,
-		[]
+		[],
+		new Set()
 	);
 	const defineEntries = (
 		Object.entries(normalizedDefines) as Array<[TDefineKey, MaterialDefineValue]>

package/src/lib/core/material.ts

@@ -14,7 +14,10 @@ import {
 	type MaterialLineMap,
 	type PreprocessedMaterialFragment
 } from './material-preprocess.js';
+import { assertStorageBufferDefinition, assertStorageTextureFormat } from './storage-buffers.js';
 import type {
+	StorageBufferDefinition,
+	StorageBufferDefinitionMap,
 	TextureData,
 	TextureDefinition,
 	TextureDefinitionMap,
@@ -71,7 +74,8 @@ export interface FragMaterialInput<
 	TUniformKey extends string = string,
 	TTextureKey extends string = string,
 	TDefineKey extends string = string,
-	TIncludeKey extends string = string
+	TIncludeKey extends string = string,
+	TStorageBufferKey extends string = string
 > {
 	/**
 	 * User WGSL source containing `frag(uv: vec2f) -> vec4f`.
@@ -93,6 +97,10 @@ export interface FragMaterialInput<
 	 * Optional WGSL include chunks used by `#include <name>` directives.
 	 */
 	includes?: MaterialIncludes<TIncludeKey>;
+	/**
+	 * Optional storage buffer definitions for compute shaders.
+	 */
+	storageBuffers?: StorageBufferDefinitionMap<TStorageBufferKey>;
 }
 
 /**
@@ -102,7 +110,8 @@ export interface FragMaterial<
 	TUniformKey extends string = string,
 	TTextureKey extends string = string,
 	TDefineKey extends string = string,
-	TIncludeKey extends string = string
+	TIncludeKey extends string = string,
+	TStorageBufferKey extends string = string
 > {
 	/**
 	 * User WGSL source containing `frag(uv: vec2f) -> vec4f`.
@@ -124,6 +133,10 @@ export interface FragMaterial<
 	 * Optional WGSL include chunks used by `#include <name>` directives.
 	 */
 	readonly includes: Readonly<MaterialIncludes<TIncludeKey>>;
+	/**
+	 * Storage buffer definitions for compute shaders. Empty when not provided.
+	 */
+	readonly storageBuffers: Readonly<StorageBufferDefinitionMap<TStorageBufferKey>>;
 }
 
 /**
@@ -132,7 +145,8 @@ export interface FragMaterial<
 export interface ResolvedMaterial<
 	TUniformKey extends string = string,
 	TTextureKey extends string = string,
-	TIncludeKey extends string = string
+	TIncludeKey extends string = string,
+	TStorageBufferKey extends string = string
 > {
 	/**
 	 * Final fragment WGSL after define injection.
@@ -178,6 +192,14 @@ export interface ResolvedMaterial<
 	 * Source metadata used for diagnostics.
 	 */
 	source: Readonly<MaterialSourceMetadata> | null;
+	/**
+	 * Sorted storage buffer keys. Empty array when no storage buffers declared.
+	 */
+	storageBufferKeys: TStorageBufferKey[];
+	/**
+	 * Sorted storage texture keys (textures with storage: true).
+	 */
+	storageTextureKeys: TTextureKey[];
 }
 
 /**
@@ -190,8 +212,8 @@ const FRAGMENT_FUNCTION_NAME_PATTERN = /\bfn\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
 /**
  * Cache of resolved material snapshots keyed by immutable material instance.
  */
-type AnyFragMaterial = FragMaterial<string, string, string, string>;
-type AnyResolvedMaterial = ResolvedMaterial<string, string, string>;
+type AnyFragMaterial = FragMaterial<string, string, string, string, string>;
+type AnyResolvedMaterial = ResolvedMaterial<string, string, string, string>;
 
 const resolvedMaterialCache = new WeakMap<AnyFragMaterial, AnyResolvedMaterial>();
 const preprocessedFragmentCache = new WeakMap<AnyFragMaterial, PreprocessedMaterialFragment>();
@@ -200,17 +222,18 @@ const materialSourceMetadataCache = new WeakMap<AnyFragMaterial, MaterialSourceM
 function getCachedResolvedMaterial<
 	TUniformKey extends string,
 	TTextureKey extends string,
-	TIncludeKey extends string
+	TIncludeKey extends string,
+	TStorageBufferKey extends string
 >(
-	material: FragMaterial<TUniformKey, TTextureKey, string, TIncludeKey>
-): ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey> | null {
+	material: FragMaterial<TUniformKey, TTextureKey, string, TIncludeKey, TStorageBufferKey>
+): ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey, TStorageBufferKey> | null {
 	const cached = resolvedMaterialCache.get(material);
 	if (!cached) {
 		return null;
 	}
 
 	// Invariant: the cache key is the same material object used to produce this resolved payload.
-	return cached as ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey>;
+	return cached as ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey, TStorageBufferKey>;
 }
 
 const STACK_TRACE_CHROME_PATTERN = /^\s*at\s+(?:(.*?)\s+\()?(.+?):(\d+):(\d+)\)?$/;
@@ -576,10 +599,11 @@ export function defineMaterial<
 	TUniformKey extends string = string,
 	TTextureKey extends string = string,
 	TDefineKey extends string = string,
-	TIncludeKey extends string = string
+	TIncludeKey extends string = string,
+	TStorageBufferKey extends string = string
 >(
-	input: FragMaterialInput<TUniformKey, TTextureKey, TDefineKey, TIncludeKey>
-): FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey> {
+	input: FragMaterialInput<TUniformKey, TTextureKey, TDefineKey, TIncludeKey, TStorageBufferKey>
+): FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey, TStorageBufferKey> {
 	const fragment = resolveFragment(input.fragment);
 	const uniforms = Object.freeze(resolveUniforms(input.uniforms));
 	const textures = Object.freeze(resolveTextures(input.textures));
@@ -587,18 +611,60 @@ export function defineMaterial<
 	const includes = Object.freeze(resolveIncludes(input.includes));
 	const source = Object.freeze(resolveSourceMetadata(undefined));
 
+	// Validate and freeze storage buffers
+	const rawStorageBuffers =
+		input.storageBuffers ?? ({} as StorageBufferDefinitionMap<TStorageBufferKey>);
+	for (const [name, definition] of Object.entries(rawStorageBuffers) as Array<
+		[string, StorageBufferDefinition]
+	>) {
+		assertStorageBufferDefinition(name, definition);
+	}
+	const storageBuffers = Object.freeze(
+		Object.fromEntries(
+			Object.entries(rawStorageBuffers).map(([name, definition]) => {
+				const def = definition as StorageBufferDefinition;
+				const cloned: StorageBufferDefinition = {
+					size: def.size,
+					type: def.type,
+					...(def.access !== undefined ? { access: def.access } : {}),
+					...(def.initialData !== undefined
+						? { initialData: def.initialData.slice() as typeof def.initialData }
+						: {})
+				};
+				return [name, Object.freeze(cloned)];
+			})
+		)
+	) as Readonly<StorageBufferDefinitionMap<TStorageBufferKey>>;
+
+	// Validate storage textures
+	for (const [name, definition] of Object.entries(textures) as Array<[string, TextureDefinition]>) {
+		if (definition?.storage) {
+			if (!definition.format) {
+				throw new Error(`Texture "${name}" with storage:true requires a \`format\` field.`);
+			}
+			assertStorageTextureFormat(name, definition.format);
+		}
+	}
+
 	const preprocessed = preprocessMaterialFragment({
 		fragment,
 		defines,
 		includes
 	});
 
-	const material: FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey> = Object.freeze({
+	const material: FragMaterial<
+		TUniformKey,
+		TTextureKey,
+		TDefineKey,
+		TIncludeKey,
+		TStorageBufferKey
+	> = Object.freeze({
 		fragment,
 		uniforms,
 		textures,
 		defines,
-		includes
+		includes,
+		storageBuffers
 	});
 
 	preprocessedFragmentCache.set(material, preprocessed);
@@ -616,10 +682,11 @@ export function resolveMaterial<
 	TUniformKey extends string = string,
 	TTextureKey extends string = string,
 	TDefineKey extends string = string,
-	TIncludeKey extends string = string
+	TIncludeKey extends string = string,
+	TStorageBufferKey extends string = string
 >(
-	material: FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey>
-): ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey> {
+	material: FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey, TStorageBufferKey>
+): ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey, TStorageBufferKey> {
 	assertDefinedMaterial(material);
 
 	const cached = getCachedResolvedMaterial(material);
@@ -641,14 +708,26 @@ export function resolveMaterial<
 	const fragmentWgsl = preprocessed.fragment;
 	const textureConfig = buildTextureConfigSignature(textures, textureKeys);
 
+	const storageBufferKeys = Object.keys(
+		material.storageBuffers ?? {}
+	).sort() as TStorageBufferKey[];
+	const storageTextureKeys = textureKeys.filter(
+		(key) => (textures[key] as TextureDefinition)?.storage === true
+	);
+
 	const signature = JSON.stringify({
 		fragmentWgsl,
 		uniforms: uniformLayout.entries.map((entry) => `${entry.name}:${entry.type}`),
 		textureKeys,
-		textureConfig
+		textureConfig,
+		storageBufferKeys: storageBufferKeys.map((key) => {
+			const def = (material.storageBuffers as StorageBufferDefinitionMap)[key];
+			return `${key}:${def?.type ?? '?'}:${def?.size ?? 0}:${def?.access ?? 'read-write'}`;
+		}),
+		storageTextureKeys
 	});
 
-	const resolved: ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey> = {
+	const resolved: ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey, TStorageBufferKey> = {
 		fragmentWgsl,
 		fragmentLineMap: preprocessed.lineMap,
 		uniforms,
@@ -659,7 +738,9 @@ export function resolveMaterial<
 		fragmentSource: material.fragment,
 		includeSources: material.includes as MaterialIncludes<TIncludeKey>,
 		defineBlockSource: preprocessed.defineBlockSource,
-		source: materialSourceMetadataCache.get(material) ?? null
+		source: materialSourceMetadataCache.get(material) ?? null,
+		storageBufferKeys,
+		storageTextureKeys
 	};
 
 	resolvedMaterialCache.set(material, resolved);

package/src/lib/core/render-graph.ts

@@ -1,13 +1,17 @@
-import type { RenderPass, RenderPassInputSlot, RenderPassOutputSlot } from './types.js';
+import type { AnyPass, RenderPass, RenderPassInputSlot, RenderPassOutputSlot } from './types.js';
 
 /**
  * Resolved render-pass step with defaults applied.
  */
 export interface RenderGraphStep {
+	/**
+	 * Step kind. 'render' for existing passes, 'compute' for compute passes.
+	 */
+	kind: 'render' | 'compute';
 	/**
 	 * User pass instance.
 	 */
-	pass: RenderPass;
+	pass: AnyPass;
 	/**
 	 * Resolved input slot.
 	 */
@@ -65,7 +69,7 @@ function cloneClearColor(
  * @returns Resolved render graph plan.
  */
 export function planRenderGraph(
-	passes: RenderPass[] | undefined,
+	passes: AnyPass[] | undefined,
 	defaultClearColor: [number, number, number, number],
 	renderTargetSlots?: Iterable<string>
 ): RenderGraphPlan {
@@ -80,9 +84,27 @@ export function planRenderGraph(
 			continue;
 		}
 
-		const needsSwap = pass.needsSwap ?? true;
-		const input: RenderPassInputSlot = pass.input ?? 'source';
-		const output: RenderPassOutputSlot = pass.output ?? (needsSwap ? 'target' : 'source');
+		// Compute passes don't participate in slot routing
+		const isCompute = 'isCompute' in pass && (pass as { isCompute?: boolean }).isCompute === true;
+		if (isCompute) {
+			steps.push({
+				kind: 'compute',
+				pass,
+				input: 'source',
+				output: 'source',
+				needsSwap: false,
+				clear: false,
+				clearColor: cloneClearColor(defaultClearColor),
+				preserve: true
+			});
+			continue;
+		}
+
+		// After compute guard, pass is a render pass
+		const rp = pass as RenderPass;
+		const needsSwap = rp.needsSwap ?? true;
+		const input: RenderPassInputSlot = rp.input ?? 'source';
+		const output: RenderPassOutputSlot = rp.output ?? (needsSwap ? 'target' : 'source');
 
 		if (input === 'canvas') {
 			throw new Error(`Render pass #${enabledIndex} cannot read from "canvas".`);
@@ -108,11 +130,12 @@ export function planRenderGraph(
 			throw new Error(`Render pass #${enabledIndex} reads "${input}" before it is written.`);
 		}
 
-		const clear = pass.clear ?? false;
-		const clearColor = cloneClearColor(pass.clearColor ?? defaultClearColor);
-		const preserve = pass.preserve ?? true;
+		const clear = rp.clear ?? false;
+		const clearColor = cloneClearColor(rp.clearColor ?? defaultClearColor);
+		const preserve = rp.preserve ?? true;
 
 		steps.push({
+			kind: 'render',
 			pass,
 			input,
 			output,
@@ -136,6 +159,13 @@ export function planRenderGraph(
 		enabledIndex += 1;
 	}
 
+	// When steps exist (even compute-only) but no render pass changed
+	// finalOutput from 'canvas', the scene was drawn to 'source' and
+	// needs blitting to the canvas surface.
+	if (steps.length > 0 && enabledIndex === 0) {
+		finalOutput = 'source';
+	}
+
 	return {
 		steps,
 		finalOutput