@motion-core/motion-gpu 0.4.1 → 0.4.2

package/dist/svelte/use-texture.js

@@ -1,157 +1,135 @@
-import { onDestroy } from 'svelte';
-import { createCurrentWritable as currentWritable } from '../core/current-value.js';
-import { isAbortError, loadTexturesFromUrls } from '../core/texture-loader.js';
-import { toMotionGPUErrorReport } from '../core/error-report.js';
+import { toMotionGPUErrorReport } from "../core/error-report.js";
+import { createCurrentWritable } from "../core/current-value.js";
+import { isAbortError, loadTexturesFromUrls } from "../core/texture-loader.js";
+import { onDestroy } from "svelte";
+//#region src/lib/svelte/use-texture.ts
 /**
- * Normalizes unknown thrown values to an `Error` instance.
- */
+* Normalizes unknown thrown values to an `Error` instance.
+*/
 function toError(error) {
-    if (error instanceof Error) {
-        return error;
-    }
-    return new Error('Unknown texture loading error');
+	if (error instanceof Error) return error;
+	return /* @__PURE__ */ new Error("Unknown texture loading error");
 }
 /**
- * Releases GPU-side resources for a list of loaded textures.
- */
+* Releases GPU-side resources for a list of loaded textures.
+*/
 function disposeTextures(list) {
-    for (const texture of list ?? []) {
-        texture.dispose();
-    }
+	for (const texture of list ?? []) texture.dispose();
 }
 function mergeAbortSignals(primary, secondary) {
-    if (!secondary) {
-        return {
-            signal: primary,
-            dispose: () => { }
-        };
-    }
-    if (typeof AbortSignal.any === 'function') {
-        return {
-            signal: AbortSignal.any([primary, secondary]),
-            dispose: () => { }
-        };
-    }
-    const fallback = new AbortController();
-    let disposed = false;
-    const cleanup = () => {
-        if (disposed) {
-            return;
-        }
-        disposed = true;
-        primary.removeEventListener('abort', abort);
-        secondary.removeEventListener('abort', abort);
-    };
-    const abort = () => fallback.abort();
-    primary.addEventListener('abort', abort, { once: true });
-    secondary.addEventListener('abort', abort, { once: true });
-    return {
-        signal: fallback.signal,
-        dispose: cleanup
-    };
+	if (!secondary) return {
+		signal: primary,
+		dispose: () => {}
+	};
+	if (typeof AbortSignal.any === "function") return {
+		signal: AbortSignal.any([primary, secondary]),
+		dispose: () => {}
+	};
+	const fallback = new AbortController();
+	let disposed = false;
+	const cleanup = () => {
+		if (disposed) return;
+		disposed = true;
+		primary.removeEventListener("abort", abort);
+		secondary.removeEventListener("abort", abort);
+	};
+	const abort = () => fallback.abort();
+	primary.addEventListener("abort", abort, { once: true });
+	secondary.addEventListener("abort", abort, { once: true });
+	return {
+		signal: fallback.signal,
+		dispose: cleanup
+	};
 }
 /**
- * Loads textures from URLs and exposes reactive loading/error state.
- *
- * @param urlInput - URLs array or lazy URL provider.
- * @param optionsInput - Loader options object or lazy options provider.
- * @returns Reactive texture loading state with reload support.
- */
-export function useTexture(urlInput, optionsInput = {}) {
-    const textures = currentWritable(null);
-    const loading = currentWritable(true);
-    const error = currentWritable(null);
-    const errorReport = currentWritable(null);
-    let disposed = false;
-    let requestVersion = 0;
-    let activeController = null;
-    let runningLoad = null;
-    let reloadQueued = false;
-    const getUrls = typeof urlInput === 'function' ? urlInput : () => urlInput;
-    const getOptions = typeof optionsInput === 'function'
-        ? optionsInput
-        : () => optionsInput;
-    const executeLoad = async () => {
-        if (disposed) {
-            return;
-        }
-        const version = ++requestVersion;
-        const controller = new AbortController();
-        activeController = controller;
-        loading.set(true);
-        error.set(null);
-        errorReport.set(null);
-        const previous = textures.current;
-        const options = getOptions() ?? {};
-        const mergedSignal = mergeAbortSignals(controller.signal, options.signal);
-        try {
-            const loaded = await loadTexturesFromUrls(getUrls(), {
-                ...options,
-                signal: mergedSignal.signal
-            });
-            if (disposed || version !== requestVersion) {
-                disposeTextures(loaded);
-                return;
-            }
-            textures.set(loaded);
-            disposeTextures(previous);
-        }
-        catch (nextError) {
-            if (disposed || version !== requestVersion) {
-                return;
-            }
-            if (isAbortError(nextError)) {
-                return;
-            }
-            disposeTextures(previous);
-            textures.set(null);
-            const normalizedError = toError(nextError);
-            error.set(normalizedError);
-            errorReport.set(toMotionGPUErrorReport(normalizedError, 'initialization'));
-        }
-        finally {
-            if (!disposed && version === requestVersion) {
-                loading.set(false);
-            }
-            if (activeController === controller) {
-                activeController = null;
-            }
-            mergedSignal.dispose();
-        }
-    };
-    const runLoadLoop = async () => {
-        do {
-            reloadQueued = false;
-            await executeLoad();
-        } while (reloadQueued && !disposed);
-    };
-    const load = () => {
-        activeController?.abort();
-        if (runningLoad) {
-            reloadQueued = true;
-            return runningLoad;
-        }
-        const pending = runLoadLoop();
-        const trackedPending = pending.finally(() => {
-            if (runningLoad === trackedPending) {
-                runningLoad = null;
-            }
-        });
-        runningLoad = trackedPending;
-        return trackedPending;
-    };
-    void load();
-    onDestroy(() => {
-        disposed = true;
-        requestVersion += 1;
-        activeController?.abort();
-        disposeTextures(textures.current);
-    });
-    return {
-        textures,
-        loading,
-        error,
-        errorReport,
-        reload: load
-    };
+* Loads textures from URLs and exposes reactive loading/error state.
+*
+* @param urlInput - URLs array or lazy URL provider.
+* @param optionsInput - Loader options object or lazy options provider.
+* @returns Reactive texture loading state with reload support.
+*/
+function useTexture(urlInput, optionsInput = {}) {
+	const textures = createCurrentWritable(null);
+	const loading = createCurrentWritable(true);
+	const error = createCurrentWritable(null);
+	const errorReport = createCurrentWritable(null);
+	let disposed = false;
+	let requestVersion = 0;
+	let activeController = null;
+	let runningLoad = null;
+	let reloadQueued = false;
+	const getUrls = typeof urlInput === "function" ? urlInput : () => urlInput;
+	const getOptions = typeof optionsInput === "function" ? optionsInput : () => optionsInput;
+	const executeLoad = async () => {
+		if (disposed) return;
+		const version = ++requestVersion;
+		const controller = new AbortController();
+		activeController = controller;
+		loading.set(true);
+		error.set(null);
+		errorReport.set(null);
+		const previous = textures.current;
+		const options = getOptions() ?? {};
+		const mergedSignal = mergeAbortSignals(controller.signal, options.signal);
+		try {
+			const loaded = await loadTexturesFromUrls(getUrls(), {
+				...options,
+				signal: mergedSignal.signal
+			});
+			if (disposed || version !== requestVersion) {
+				disposeTextures(loaded);
+				return;
+			}
+			textures.set(loaded);
+			disposeTextures(previous);
+		} catch (nextError) {
+			if (disposed || version !== requestVersion) return;
+			if (isAbortError(nextError)) return;
+			disposeTextures(previous);
+			textures.set(null);
+			const normalizedError = toError(nextError);
+			error.set(normalizedError);
+			errorReport.set(toMotionGPUErrorReport(normalizedError, "initialization"));
+		} finally {
+			if (!disposed && version === requestVersion) loading.set(false);
+			if (activeController === controller) activeController = null;
+			mergedSignal.dispose();
+		}
+	};
+	const runLoadLoop = async () => {
+		do {
+			reloadQueued = false;
+			await executeLoad();
+		} while (reloadQueued && !disposed);
+	};
+	const load = () => {
+		activeController?.abort();
+		if (runningLoad) {
+			reloadQueued = true;
+			return runningLoad;
+		}
+		const trackedPending = runLoadLoop().finally(() => {
+			if (runningLoad === trackedPending) runningLoad = null;
+		});
+		runningLoad = trackedPending;
+		return trackedPending;
+	};
+	load();
+	onDestroy(() => {
+		disposed = true;
+		requestVersion += 1;
+		activeController?.abort();
+		disposeTextures(textures.current);
+	});
+	return {
+		textures,
+		loading,
+		error,
+		errorReport,
+		reload: load
+	};
 }
+//#endregion
+export { useTexture };
+
+//# sourceMappingURL=use-texture.js.map

package/dist/svelte/use-texture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-texture.js","names":[],"sources":["../../src/lib/svelte/use-texture.ts"],"sourcesContent":["import { onDestroy } from 'svelte';\nimport {\n\tcreateCurrentWritable as currentWritable,\n\ttype CurrentReadable\n} from '../core/current-value.js';\nimport {\n\tisAbortError,\n\tloadTexturesFromUrls,\n\ttype LoadedTexture,\n\ttype TextureLoadOptions\n} from '../core/texture-loader.js';\nimport { toMotionGPUErrorReport, type MotionGPUErrorReport } from '../core/error-report.js';\n\n/**\n * Reactive state returned by {@link useTexture}.\n */\nexport interface UseTextureResult {\n\t/**\n\t * Loaded textures or `null` when unavailable/failed.\n\t */\n\ttextures: CurrentReadable<LoadedTexture[] | null>;\n\t/**\n\t * `true` while an active load request is running.\n\t */\n\tloading: CurrentReadable<boolean>;\n\t/**\n\t * Last loading error.\n\t */\n\terror: CurrentReadable<Error | null>;\n\t/**\n\t * Last loading error normalized to MotionGPU diagnostics report shape.\n\t */\n\terrorReport: CurrentReadable<MotionGPUErrorReport | null>;\n\t/**\n\t * Reloads all textures using current URL input.\n\t */\n\treload: () => Promise<void>;\n}\n\n/**\n * Supported URL input variants for `useTexture`.\n */\nexport type TextureUrlInput = string[] | (() => string[]);\n\n/**\n * Supported options input variants for `useTexture`.\n */\nexport type TextureOptionsInput = TextureLoadOptions | (() => TextureLoadOptions);\n\n/**\n * Normalizes unknown thrown values to an `Error` instance.\n */\nfunction toError(error: unknown): Error {\n\tif (error instanceof Error) {\n\t\treturn error;\n\t}\n\n\treturn new Error('Unknown texture loading error');\n}\n\n/**\n * Releases GPU-side resources for a list of loaded textures.\n */\nfunction disposeTextures(list: LoadedTexture[] | null): void {\n\tfor (const texture of list ?? []) {\n\t\ttexture.dispose();\n\t}\n}\n\ninterface MergedAbortSignal {\n\tsignal: AbortSignal;\n\tdispose: () => void;\n}\n\nfunction mergeAbortSignals(\n\tprimary: AbortSignal,\n\tsecondary: AbortSignal | undefined\n): MergedAbortSignal {\n\tif (!secondary) {\n\t\treturn {\n\t\t\tsignal: primary,\n\t\t\tdispose: () => {}\n\t\t};\n\t}\n\n\tif (typeof AbortSignal.any === 'function') {\n\t\treturn {\n\t\t\tsignal: AbortSignal.any([primary, secondary]),\n\t\t\tdispose: () => {}\n\t\t};\n\t}\n\n\tconst fallback = new AbortController();\n\tlet disposed = false;\n\tconst cleanup = (): void => {\n\t\tif (disposed) {\n\t\t\treturn;\n\t\t}\n\t\tdisposed = true;\n\t\tprimary.removeEventListener('abort', abort);\n\t\tsecondary.removeEventListener('abort', abort);\n\t};\n\tconst abort = (): void => fallback.abort();\n\n\tprimary.addEventListener('abort', abort, { once: true });\n\tsecondary.addEventListener('abort', abort, { once: true });\n\n\treturn {\n\t\tsignal: fallback.signal,\n\t\tdispose: cleanup\n\t};\n}\n\n/**\n * Loads textures from URLs and exposes reactive loading/error state.\n *\n * @param urlInput - URLs array or lazy URL provider.\n * @param optionsInput - Loader options object or lazy options provider.\n * @returns Reactive texture loading state with reload support.\n */\nexport function useTexture(\n\turlInput: TextureUrlInput,\n\toptionsInput: TextureOptionsInput = {}\n): UseTextureResult {\n\tconst textures = currentWritable<LoadedTexture[] | null>(null);\n\tconst loading = currentWritable(true);\n\tconst error = currentWritable<Error | null>(null);\n\tconst errorReport = currentWritable<MotionGPUErrorReport | null>(null);\n\tlet disposed = false;\n\tlet requestVersion = 0;\n\tlet activeController: AbortController | null = null;\n\tlet runningLoad: Promise<void> | null = null;\n\tlet reloadQueued = false;\n\tconst getUrls = typeof urlInput === 'function' ? urlInput : () => urlInput;\n\tconst getOptions =\n\t\ttypeof optionsInput === 'function'\n\t\t\t? (optionsInput as () => TextureLoadOptions)\n\t\t\t: () => optionsInput;\n\n\tconst executeLoad = async (): Promise<void> => {\n\t\tif (disposed) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst version = ++requestVersion;\n\t\tconst controller = new AbortController();\n\t\tactiveController = controller;\n\t\tloading.set(true);\n\t\terror.set(null);\n\t\terrorReport.set(null);\n\n\t\tconst previous = textures.current;\n\t\tconst options = getOptions() ?? {};\n\t\tconst mergedSignal = mergeAbortSignals(controller.signal, options.signal);\n\t\ttry {\n\t\t\tconst loaded = await loadTexturesFromUrls(getUrls(), {\n\t\t\t\t...options,\n\t\t\t\tsignal: mergedSignal.signal\n\t\t\t});\n\t\t\tif (disposed || version !== requestVersion) {\n\t\t\t\tdisposeTextures(loaded);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\ttextures.set(loaded);\n\t\t\tdisposeTextures(previous);\n\t\t} catch (nextError) {\n\t\t\tif (disposed || version !== requestVersion) {\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tif (isAbortError(nextError)) {\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tdisposeTextures(previous);\n\t\t\ttextures.set(null);\n\t\t\tconst normalizedError = toError(nextError);\n\t\t\terror.set(normalizedError);\n\t\t\terrorReport.set(toMotionGPUErrorReport(normalizedError, 'initialization'));\n\t\t} finally {\n\t\t\tif (!disposed && version === requestVersion) {\n\t\t\t\tloading.set(false);\n\t\t\t}\n\t\t\tif (activeController === controller) {\n\t\t\t\tactiveController = null;\n\t\t\t}\n\t\t\tmergedSignal.dispose();\n\t\t}\n\t};\n\n\tconst runLoadLoop = async (): Promise<void> => {\n\t\tdo {\n\t\t\treloadQueued = false;\n\t\t\tawait executeLoad();\n\t\t} while (reloadQueued && !disposed);\n\t};\n\n\tconst load = (): Promise<void> => {\n\t\tactiveController?.abort();\n\t\tif (runningLoad) {\n\t\t\treloadQueued = true;\n\t\t\treturn runningLoad;\n\t\t}\n\n\t\tconst pending = runLoadLoop();\n\t\tconst trackedPending = pending.finally(() => {\n\t\t\tif (runningLoad === trackedPending) {\n\t\t\t\trunningLoad = null;\n\t\t\t}\n\t\t});\n\t\trunningLoad = trackedPending;\n\t\treturn trackedPending;\n\t};\n\n\tvoid load();\n\n\tonDestroy(() => {\n\t\tdisposed = true;\n\t\trequestVersion += 1;\n\t\tactiveController?.abort();\n\t\tdisposeTextures(textures.current);\n\t});\n\n\treturn {\n\t\ttextures,\n\t\tloading,\n\t\terror,\n\t\terrorReport,\n\t\treload: load\n\t};\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@motion-core/motion-gpu",
-	"version": "0.4.1",
+	"version": "0.4.2",
 	"description": "Framework-agnostic WebGPU runtime for fullscreen WGSL shaders with explicit Svelte and React adapter entrypoints.",
 	"keywords": [
 		"svelte",
@@ -66,11 +66,16 @@
 		}
 	},
 	"files": [
-		"dist"
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*",
+		"src/lib",
+		"!src/lib/**/*.test.*",
+		"!src/lib/**/*.spec.*"
 	],
 	"scripts": {
-		"build": "svelte-package -i src/lib -o dist && node ./scripts/build/transpile-react-tsx.mjs && node ./scripts/build/patch-webgpu-types-dts.mjs",
-		"build:watch": "svelte-package -i src/lib -o dist -w --preserve-output",
+		"build": "vite build --config ./vite.package.config.ts",
+		"build:watch": "vite build --watch --config ./vite.package.config.ts",
 		"prepack": "bun run build",
 		"check": "svelte-check --tsconfig ./tsconfig.json && publint",
 		"test": "vitest run",
@@ -113,8 +118,7 @@
 		"@eslint/compat": "^2.0.2",
 		"@eslint/js": "^10.0.1",
 		"@playwright/test": "^1.58.2",
-		"@sveltejs/package": "^2.5.0",
-		"@sveltejs/vite-plugin-svelte": "^6.2.4",
+		"@sveltejs/vite-plugin-svelte": "^7.0.0",
 		"@testing-library/react": "^16.3.0",
 		"@testing-library/svelte": "^5.2.8",
 		"@types/react": "^19.2.2",
@@ -133,10 +137,11 @@
 		"react": "^19.2.0",
 		"react-dom": "^19.2.0",
 		"svelte": "^5.51.0",
+		"svelte2tsx": "^0.7.51",
 		"svelte-check": "^4.3.6",
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.54.0",
-		"vite": "^7.3.1",
+		"vite": "^8.0.1",
 		"vitest": "^4.0.18"
 	}
 }

package/src/lib/advanced.ts

@@ -0,0 +1,6 @@
+/**
+ * Root advanced package entrypoint.
+ *
+ * Framework-agnostic advanced core entrypoint.
+ */
+export * from './core/advanced.js';

package/src/lib/core/advanced.ts

@@ -0,0 +1,12 @@
+/**
+ * Framework-agnostic advanced MotionGPU core entrypoint.
+ */
+export * from './index.js';
+export { applySchedulerPreset, captureSchedulerDebugSnapshot } from './scheduler-helpers.js';
+export type {
+	ApplySchedulerPresetOptions,
+	MotionGPUScheduler,
+	SchedulerDebugSnapshot,
+	SchedulerPreset,
+	SchedulerPresetConfig
+} from './scheduler-helpers.js';

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 }
+			: {})
+	};
+}