@motion-core/motion-gpu 0.4.1 → 0.5.0

package/src/lib/core/compute-shader.ts

@@ -0,0 +1,326 @@
+import type { StorageBufferAccess, StorageBufferType, UniformLayout } from './types.js';
+
+/**
+ * Regex contract for compute entrypoint.
+ * Matches: @compute @workgroup_size(...) fn compute(
+ * with @builtin(global_invocation_id) parameter.
+ */
+export const COMPUTE_ENTRY_CONTRACT = /@compute\s+@workgroup_size\s*\([^)]+\)\s*fn\s+compute\s*\(/;
+
+/**
+ * Regex to extract @workgroup_size values.
+ */
+const WORKGROUP_SIZE_PATTERN =
+	/@workgroup_size\s*\(\s*(\d+)(?:\s*,\s*(\d+))?(?:\s*,\s*(\d+))?\s*\)/;
+
+/**
+ * Regex to verify @builtin(global_invocation_id) parameter.
+ */
+const GLOBAL_INVOCATION_ID_PATTERN = /@builtin\s*\(\s*global_invocation_id\s*\)/;
+const WORKGROUP_DIMENSION_MIN = 1;
+const WORKGROUP_DIMENSION_MAX = 65535;
+
+function extractComputeParamList(compute: string): string | null {
+	const computeFnIndex = compute.indexOf('fn compute');
+	if (computeFnIndex === -1) {
+		return null;
+	}
+
+	const openParenIndex = compute.indexOf('(', computeFnIndex);
+	if (openParenIndex === -1) {
+		return null;
+	}
+
+	let depth = 0;
+	for (let index = openParenIndex; index < compute.length; index += 1) {
+		const char = compute[index];
+		if (char === '(') {
+			depth += 1;
+			continue;
+		}
+
+		if (char === ')') {
+			depth -= 1;
+			if (depth === 0) {
+				return compute.slice(openParenIndex + 1, index);
+			}
+		}
+	}
+
+	return null;
+}
+
+function assertWorkgroupDimension(value: number): void {
+	if (
+		!Number.isFinite(value) ||
+		!Number.isInteger(value) ||
+		value < WORKGROUP_DIMENSION_MIN ||
+		value > WORKGROUP_DIMENSION_MAX
+	) {
+		throw new Error(
+			`@workgroup_size dimensions must be integers in range ${WORKGROUP_DIMENSION_MIN}-${WORKGROUP_DIMENSION_MAX}, got ${value}.`
+		);
+	}
+}
+
+/**
+ * Default uniform field used when no custom uniforms are provided in compute.
+ */
+const DEFAULT_UNIFORM_FIELD = 'motiongpu_unused: vec4f,';
+
+/**
+ * Validates compute shader user code matches the compute contract.
+ *
+ * @param compute - User compute shader WGSL source.
+ * @throws {Error} When shader does not match the compute contract.
+ */
+export function assertComputeContract(compute: string): void {
+	if (!COMPUTE_ENTRY_CONTRACT.test(compute)) {
+		throw new Error(
+			'Compute shader must declare `@compute @workgroup_size(...) fn compute(...)`. ' +
+				'Ensure the function is named `compute` and includes @compute and @workgroup_size annotations.'
+		);
+	}
+
+	const params = extractComputeParamList(compute);
+	if (!params || !GLOBAL_INVOCATION_ID_PATTERN.test(params)) {
+		throw new Error('Compute shader must include a `@builtin(global_invocation_id)` parameter.');
+	}
+
+	extractWorkgroupSize(compute);
+}
+
+/**
+ * Extracts @workgroup_size values from WGSL compute shader.
+ *
+ * @param compute - Validated compute shader source.
+ * @returns Tuple [x, y, z] with defaults of 1 for omitted dimensions.
+ */
+export function extractWorkgroupSize(compute: string): [number, number, number] {
+	const match = compute.match(WORKGROUP_SIZE_PATTERN);
+	if (!match) {
+		throw new Error('Could not extract @workgroup_size from compute shader source.');
+	}
+
+	const x = Number.parseInt(match[1] ?? '1', 10);
+	const y = Number.parseInt(match[2] ?? '1', 10);
+	const z = Number.parseInt(match[3] ?? '1', 10);
+	assertWorkgroupDimension(x);
+	assertWorkgroupDimension(y);
+	assertWorkgroupDimension(z);
+
+	return [x, y, z];
+}
+
+/**
+ * Maps StorageBufferAccess to WGSL var qualifier.
+ */
+function toWgslAccessMode(access: StorageBufferAccess): string {
+	switch (access) {
+		case 'read':
+			return 'read';
+		case 'read-write':
+			return 'read_write';
+		default:
+			throw new Error(`Unsupported storage buffer access mode "${String(access)}".`);
+	}
+}
+
+/**
+ * Builds WGSL struct fields for uniforms used in compute shader preamble.
+ */
+function buildUniformStructForCompute(layout: UniformLayout): string {
+	if (layout.entries.length === 0) {
+		return DEFAULT_UNIFORM_FIELD;
+	}
+
+	return layout.entries.map((entry) => `${entry.name}: ${entry.type},`).join('\n\t');
+}
+
+/**
+ * Builds storage buffer binding declarations for compute shader.
+ *
+ * @param storageBufferKeys - Sorted buffer keys.
+ * @param definitions - Type/access definitions per key.
+ * @param groupIndex - Bind group index for storage buffers.
+ * @returns WGSL binding declaration string.
+ */
+export function buildComputeStorageBufferBindings(
+	storageBufferKeys: string[],
+	definitions: Record<string, { type: StorageBufferType; access: StorageBufferAccess }>,
+	groupIndex: number
+): string {
+	if (storageBufferKeys.length === 0) {
+		return '';
+	}
+
+	const declarations: string[] = [];
+
+	for (let index = 0; index < storageBufferKeys.length; index += 1) {
+		const key = storageBufferKeys[index];
+		if (key === undefined) {
+			continue;
+		}
+
+		const definition = definitions[key];
+		if (!definition) {
+			continue;
+		}
+
+		const accessMode = toWgslAccessMode(definition.access);
+		declarations.push(
+			`@group(${groupIndex}) @binding(${index}) var<storage, ${accessMode}> ${key}: ${definition.type};`
+		);
+	}
+
+	return declarations.join('\n');
+}
+
+/**
+ * Builds storage texture binding declarations for compute shader.
+ *
+ * @param storageTextureKeys - Sorted storage texture keys.
+ * @param definitions - Format definitions per key.
+ * @param groupIndex - Bind group index for storage textures.
+ * @returns WGSL binding declaration string.
+ */
+export function buildComputeStorageTextureBindings(
+	storageTextureKeys: string[],
+	definitions: Record<string, { format: GPUTextureFormat }>,
+	groupIndex: number
+): string {
+	if (storageTextureKeys.length === 0) {
+		return '';
+	}
+
+	const declarations: string[] = [];
+
+	for (let index = 0; index < storageTextureKeys.length; index += 1) {
+		const key = storageTextureKeys[index];
+		if (key === undefined) {
+			continue;
+		}
+
+		const definition = definitions[key];
+		if (!definition) {
+			continue;
+		}
+
+		declarations.push(
+			`@group(${groupIndex}) @binding(${index}) var ${key}: texture_storage_2d<${definition.format}, write>;`
+		);
+	}
+
+	return declarations.join('\n');
+}
+
+/**
+ * Maps storage texture format to sampled texture scalar type for `texture_2d<T>`.
+ */
+export function storageTextureSampleScalarType(format: GPUTextureFormat): 'f32' | 'u32' | 'i32' {
+	const normalized = String(format).toLowerCase();
+	if (normalized.endsWith('uint')) {
+		return 'u32';
+	}
+	if (normalized.endsWith('sint')) {
+		return 'i32';
+	}
+	return 'f32';
+}
+
+/**
+ * Assembles compute shader WGSL for ping-pong workflows.
+ *
+ * Exposes two generated bindings under group(2):
+ * - `${target}A`: sampled read texture (`texture_2d<T>`)
+ * - `${target}B`: storage write texture (`texture_storage_2d<format, write>`)
+ */
+export function buildPingPongComputeShaderSource(options: {
+	compute: string;
+	uniformLayout: UniformLayout;
+	storageBufferKeys: string[];
+	storageBufferDefinitions: Record<
+		string,
+		{ type: StorageBufferType; access: StorageBufferAccess }
+	>;
+	target: string;
+	targetFormat: GPUTextureFormat;
+}): string {
+	const uniformFields = buildUniformStructForCompute(options.uniformLayout);
+	const storageBufferBindings = buildComputeStorageBufferBindings(
+		options.storageBufferKeys,
+		options.storageBufferDefinitions,
+		1
+	);
+	const sampledType = storageTextureSampleScalarType(options.targetFormat);
+	const pingPongTextureBindings = [
+		`@group(2) @binding(0) var ${options.target}A: texture_2d<${sampledType}>;`,
+		`@group(2) @binding(1) var ${options.target}B: texture_storage_2d<${options.targetFormat}, write>;`
+	].join('\n');
+
+	return `struct MotionGPUFrame {
+	time: f32,
+	delta: f32,
+	resolution: vec2f,
+};
+
+struct MotionGPUUniforms {
+	${uniformFields}
+};
+
+@group(0) @binding(0) var<uniform> motiongpuFrame: MotionGPUFrame;
+@group(0) @binding(1) var<uniform> motiongpuUniforms: MotionGPUUniforms;
+${storageBufferBindings ? '\n' + storageBufferBindings : ''}
+${pingPongTextureBindings ? '\n' + pingPongTextureBindings : ''}
+
+${options.compute}
+`;
+}
+
+/**
+ * Assembles full compute shader WGSL with preamble.
+ *
+ * @param options - Compute shader build options.
+ * @returns Complete WGSL source for compute stage.
+ */
+export function buildComputeShaderSource(options: {
+	compute: string;
+	uniformLayout: UniformLayout;
+	storageBufferKeys: string[];
+	storageBufferDefinitions: Record<
+		string,
+		{ type: StorageBufferType; access: StorageBufferAccess }
+	>;
+	storageTextureKeys: string[];
+	storageTextureDefinitions: Record<string, { format: GPUTextureFormat }>;
+}): string {
+	const uniformFields = buildUniformStructForCompute(options.uniformLayout);
+	const storageBufferBindings = buildComputeStorageBufferBindings(
+		options.storageBufferKeys,
+		options.storageBufferDefinitions,
+		1
+	);
+	const storageTextureBindings = buildComputeStorageTextureBindings(
+		options.storageTextureKeys,
+		options.storageTextureDefinitions,
+		2
+	);
+
+	return `struct MotionGPUFrame {
+	time: f32,
+	delta: f32,
+	resolution: vec2f,
+};
+
+struct MotionGPUUniforms {
+	${uniformFields}
+};
+
+@group(0) @binding(0) var<uniform> motiongpuFrame: MotionGPUFrame;
+@group(0) @binding(1) var<uniform> motiongpuUniforms: MotionGPUUniforms;
+${storageBufferBindings ? '\n' + storageBufferBindings : ''}
+${storageTextureBindings ? '\n' + storageTextureBindings : ''}
+
+${options.compute}
+`;
+}

package/src/lib/core/current-value.ts

@@ -0,0 +1,64 @@
+/**
+ * Minimal subscribe contract used by MotionGPU core.
+ */
+export interface Subscribable<T> {
+	subscribe: (run: (value: T) => void) => () => void;
+}
+
+/**
+ * Readable value with synchronous access to the latest value.
+ */
+export interface CurrentReadable<T> extends Subscribable<T> {
+	readonly current: T;
+}
+
+/**
+ * Writable extension of {@link CurrentReadable}.
+ */
+export interface CurrentWritable<T> extends CurrentReadable<T> {
+	set: (value: T) => void;
+	update: (updater: (value: T) => T) => void;
+}
+
+/**
+ * Creates a writable value with immediate subscription semantics.
+ */
+export function createCurrentWritable<T>(
+	initialValue: T,
+	onChange?: (value: T) => void
+): CurrentWritable<T> {
+	let current = initialValue;
+	const subscribers = new Set<(value: T) => void>();
+
+	const notify = (value: T): void => {
+		for (const run of subscribers) {
+			run(value);
+		}
+	};
+
+	const set = (value: T): void => {
+		if (Object.is(current, value)) {
+			return;
+		}
+		current = value;
+		notify(value);
+		onChange?.(value);
+	};
+
+	return {
+		get current() {
+			return current;
+		},
+		subscribe(run) {
+			subscribers.add(run);
+			run(current);
+			return () => {
+				subscribers.delete(run);
+			};
+		},
+		set,
+		update(updater) {
+			set(updater(current));
+		}
+	};
+}

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

@@ -0,0 +1,236 @@
+import type { MaterialSourceLocation } from './material-preprocess.js';
+
+/**
+ * Source metadata for material declaration callsite.
+ */
+export interface MaterialSourceMetadata {
+	component?: string;
+	file?: string;
+	line?: number;
+	column?: number;
+	functionName?: string;
+}
+
+/**
+ * One WGSL compiler diagnostic enriched with source-location metadata.
+ */
+export interface ShaderCompilationDiagnostic {
+	generatedLine: number;
+	message: string;
+	linePos?: number;
+	lineLength?: number;
+	sourceLocation: MaterialSourceLocation | null;
+}
+
+/**
+ * Runtime context snapshot captured for shader compilation diagnostics.
+ */
+export interface ShaderCompilationRuntimeContext {
+	materialSignature?: string;
+	passGraph?: {
+		passCount: number;
+		enabledPassCount: number;
+		inputs: string[];
+		outputs: string[];
+	};
+	activeRenderTargets: string[];
+}
+
+/**
+ * Structured payload attached to WGSL compilation errors.
+ */
+export interface ShaderCompilationDiagnosticsPayload {
+	kind: 'shader-compilation';
+	diagnostics: ShaderCompilationDiagnostic[];
+	fragmentSource: string;
+	includeSources: Record<string, string>;
+	defineBlockSource?: string;
+	materialSource: MaterialSourceMetadata | null;
+	runtimeContext?: ShaderCompilationRuntimeContext;
+}
+
+type MotionGPUErrorWithDiagnostics = Error & {
+	motiongpuDiagnostics?: unknown;
+};
+
+function isMaterialSourceMetadata(value: unknown): value is MaterialSourceMetadata {
+	if (value === null || typeof value !== 'object') {
+		return false;
+	}
+
+	const record = value as Record<string, unknown>;
+	if (record.component !== undefined && typeof record.component !== 'string') {
+		return false;
+	}
+	if (record.file !== undefined && typeof record.file !== 'string') {
+		return false;
+	}
+	if (record.functionName !== undefined && typeof record.functionName !== 'string') {
+		return false;
+	}
+	if (record.line !== undefined && typeof record.line !== 'number') {
+		return false;
+	}
+	if (record.column !== undefined && typeof record.column !== 'number') {
+		return false;
+	}
+
+	return true;
+}
+
+function isMaterialSourceLocation(value: unknown): value is MaterialSourceLocation | null {
+	if (value === null) {
+		return true;
+	}
+
+	if (typeof value !== 'object') {
+		return false;
+	}
+
+	const record = value as Record<string, unknown>;
+	const kind = record.kind;
+	if (kind !== 'fragment' && kind !== 'include' && kind !== 'define') {
+		return false;
+	}
+
+	return typeof record.line === 'number';
+}
+
+function isShaderCompilationDiagnostic(value: unknown): value is ShaderCompilationDiagnostic {
+	if (value === null || typeof value !== 'object') {
+		return false;
+	}
+
+	const record = value as Record<string, unknown>;
+	if (typeof record.generatedLine !== 'number') {
+		return false;
+	}
+	if (typeof record.message !== 'string') {
+		return false;
+	}
+	if (record.linePos !== undefined && typeof record.linePos !== 'number') {
+		return false;
+	}
+	if (record.lineLength !== undefined && typeof record.lineLength !== 'number') {
+		return false;
+	}
+	if (!isMaterialSourceLocation(record.sourceLocation)) {
+		return false;
+	}
+
+	return true;
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+
+function isShaderCompilationRuntimeContext(
+	value: unknown
+): value is ShaderCompilationRuntimeContext {
+	if (value === null || typeof value !== 'object') {
+		return false;
+	}
+
+	const record = value as Record<string, unknown>;
+	if (record.materialSignature !== undefined && typeof record.materialSignature !== 'string') {
+		return false;
+	}
+	if (!isStringArray(record.activeRenderTargets)) {
+		return false;
+	}
+	const passGraph = record.passGraph;
+	if (passGraph === undefined) {
+		return true;
+	}
+	if (passGraph === null || typeof passGraph !== 'object') {
+		return false;
+	}
+
+	const passGraphRecord = passGraph as Record<string, unknown>;
+	if (typeof passGraphRecord.passCount !== 'number') {
+		return false;
+	}
+	if (typeof passGraphRecord.enabledPassCount !== 'number') {
+		return false;
+	}
+	if (!isStringArray(passGraphRecord.inputs) || !isStringArray(passGraphRecord.outputs)) {
+		return false;
+	}
+
+	return true;
+}
+
+/**
+ * Attaches structured diagnostics payload to an Error.
+ */
+export function attachShaderCompilationDiagnostics(
+	error: Error,
+	payload: ShaderCompilationDiagnosticsPayload
+): Error {
+	(error as MotionGPUErrorWithDiagnostics).motiongpuDiagnostics = payload;
+	return error;
+}
+
+/**
+ * Extracts structured diagnostics payload from unknown error value.
+ */
+export function getShaderCompilationDiagnostics(
+	error: unknown
+): ShaderCompilationDiagnosticsPayload | null {
+	if (!(error instanceof Error)) {
+		return null;
+	}
+
+	const payload = (error as MotionGPUErrorWithDiagnostics).motiongpuDiagnostics;
+	if (payload === null || typeof payload !== 'object') {
+		return null;
+	}
+
+	const record = payload as Record<string, unknown>;
+	if (record.kind !== 'shader-compilation') {
+		return null;
+	}
+	if (
+		!Array.isArray(record.diagnostics) ||
+		!record.diagnostics.every(isShaderCompilationDiagnostic)
+	) {
+		return null;
+	}
+	if (typeof record.fragmentSource !== 'string') {
+		return null;
+	}
+	if (record.defineBlockSource !== undefined && typeof record.defineBlockSource !== 'string') {
+		return null;
+	}
+	if (record.includeSources === null || typeof record.includeSources !== 'object') {
+		return null;
+	}
+	const includeSources = record.includeSources as Record<string, unknown>;
+	if (Object.values(includeSources).some((value) => typeof value !== 'string')) {
+		return null;
+	}
+	if (record.materialSource !== null && !isMaterialSourceMetadata(record.materialSource)) {
+		return null;
+	}
+	if (
+		record.runtimeContext !== undefined &&
+		!isShaderCompilationRuntimeContext(record.runtimeContext)
+	) {
+		return null;
+	}
+
+	return {
+		kind: 'shader-compilation',
+		diagnostics: record.diagnostics as ShaderCompilationDiagnostic[],
+		fragmentSource: record.fragmentSource,
+		includeSources: includeSources as Record<string, string>,
+		...(record.defineBlockSource !== undefined
+			? { defineBlockSource: record.defineBlockSource as string }
+			: {}),
+		materialSource: (record.materialSource ?? null) as MaterialSourceMetadata | null,
+		...(record.runtimeContext !== undefined
+			? { runtimeContext: record.runtimeContext as ShaderCompilationRuntimeContext }
+			: {})
+	};
+}