@motion-core/motion-gpu 0.2.0 → 0.4.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Svelte](https://img.shields.io/badge/Svelte-5-orange.svg)](https://svelte.dev)
+[![React](https://img.shields.io/badge/React-18%2B-149eca.svg)](https://react.dev)
 [![WebGPU](https://img.shields.io/badge/Shaders-WGSL-blueviolet.svg)](https://gpuweb.github.io/gpuweb/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-blue.svg)](https://www.typescriptlang.org)
 [![npm](https://img.shields.io/badge/npm-@motion--core%2Fmotion--gpu-red.svg)](https://www.npmjs.com/package/@motion-core/motion-gpu)
@@ -12,7 +13,7 @@
 
 **A tiny WebGPU runtime for writing Shadertoy-style fullscreen shaders in pure WGSL.**
 
-`@motion-core/motion-gpu` ships a framework-agnostic core plus a Svelte 5 adapter for building fullscreen shader pipelines using WebGPU and WGSL.
+`@motion-core/motion-gpu` ships a framework-agnostic core plus Svelte 5 and React adapters for building fullscreen shader pipelines using WebGPU and WGSL.
 It provides a minimal runtime loop, scheduler, and render graph designed specifically for fragment-driven GPU programs.
 
 Unlike general-purpose 3D engines, Motion GPU focuses on a very narrow problem: **running fullscreen fragment shaders and multi-pass GPU pipelines**.
@@ -119,6 +120,39 @@ Also exports runtime/core types:
 
 ---
 
+## React adapter
+
+`@motion-core/motion-gpu/react` exposes the runtime API for React:
+
+- `FragCanvas`
+- `defineMaterial`
+- `useMotionGPU`
+- `useFrame`
+- `useTexture`
+- `ShaderPass`
+- `BlitPass`
+- `CopyPass`
+
+Also exports runtime/core types:
+
+- uniforms
+- textures
+- render passes
+- scheduler
+- loader types
+
+---
+
+`@motion-core/motion-gpu/react/advanced` re-exports everything above, plus:
+
+- `useMotionGPUUserContext`
+- `useSetMotionGPUUserContext`
+- `setMotionGPUUserContext`
+- `applySchedulerPreset`
+- `captureSchedulerDebugSnapshot`
+
+---
+
 ## Framework-agnostic core
 
 `@motion-core/motion-gpu` (and explicit alias `@motion-core/motion-gpu/core`) exposes adapter-building primitives:
@@ -144,6 +178,7 @@ Also exports runtime/core types:
 # Requirements
 
 - Svelte 5 is required only for the Svelte adapter entrypoints (`/svelte`, `/svelte/advanced`)
+- React 18+ is required only for the React adapter entrypoints (`/react`, `/react/advanced`)
 - A browser/runtime with WebGPU support
 - Secure context (`https://` or `localhost`)
 
@@ -157,6 +192,12 @@ npm i @motion-core/motion-gpu
 
 ---
 
+# AI Documentation
+
+MotionGPU documentation is also available for AI tools via [Context7](https://context7.com/motion-core/motion-gpu).
+
+---
+
 # Quick Start
 
 ## 1. Create a material and render it
@@ -182,6 +223,30 @@ fn frag(uv: vec2f) -> vec4f {
 
 ---
 
+### React equivalent
+
+```tsx
+import { FragCanvas, defineMaterial } from '@motion-core/motion-gpu/react';
+
+const material = defineMaterial({
+	fragment: `
+fn frag(uv: vec2f) -> vec4f {
+	return vec4f(uv.x, uv.y, 0.25, 1.0);
+}
+`
+});
+
+export function App() {
+	return (
+		<div style={{ width: '100vw', height: '100vh' }}>
+			<FragCanvas material={material} />
+		</div>
+	);
+}
+```
+
+---
+
 ## 2. Add animated uniforms via `useFrame`
 
 ```svelte
@@ -219,6 +284,18 @@ fn frag(uv: vec2f) -> vec4f {
 </script>
 ```
 
+```tsx
+import { useFrame } from '@motion-core/motion-gpu/react';
+
+export function Runtime() {
+	useFrame((state) => {
+		state.setUniform('uTime', state.time);
+	});
+
+	return null;
+}
+```
+
 ---
 
 # Core Runtime Model

package/dist/core/current-value.js

@@ -10,6 +10,9 @@ export function createCurrentWritable(initialValue, onChange) {
         }
     };
     const set = (value) => {
+        if (Object.is(current, value)) {
+            return;
+        }
         current = value;
         notify(value);
         onChange?.(value);

package/dist/core/error-diagnostics.d.ts

@@ -19,6 +19,19 @@ export interface ShaderCompilationDiagnostic {
     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.
  */
@@ -29,6 +42,7 @@ export interface ShaderCompilationDiagnosticsPayload {
     includeSources: Record<string, string>;
     defineBlockSource?: string;
     materialSource: MaterialSourceMetadata | null;
+    runtimeContext?: ShaderCompilationRuntimeContext;
 }
 /**
  * Attaches structured diagnostics payload to an Error.

package/dist/core/error-diagnostics.js

@@ -56,6 +56,39 @@ function isShaderCompilationDiagnostic(value) {
     }
     return true;
 }
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+function isShaderCompilationRuntimeContext(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    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;
+    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.
  */
@@ -98,6 +131,10 @@ export function getShaderCompilationDiagnostics(error) {
     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,
@@ -106,6 +143,9 @@ export function getShaderCompilationDiagnostics(error) {
         ...(record.defineBlockSource !== undefined
             ? { defineBlockSource: record.defineBlockSource }
             : {}),
-        materialSource: (record.materialSource ?? null)
+        materialSource: (record.materialSource ?? null),
+        ...(record.runtimeContext !== undefined
+            ? { runtimeContext: record.runtimeContext }
+            : {})
     };
 }

package/dist/core/error-report.d.ts

@@ -2,6 +2,14 @@
  * Runtime phase in which an error occurred.
  */
 export type MotionGPUErrorPhase = 'initialization' | 'render';
+/**
+ * Stable machine-readable error category code.
+ */
+export type MotionGPUErrorCode = 'WEBGPU_UNAVAILABLE' | 'WEBGPU_ADAPTER_UNAVAILABLE' | 'WEBGPU_CONTEXT_UNAVAILABLE' | 'WGSL_COMPILATION_FAILED' | 'WEBGPU_DEVICE_LOST' | 'WEBGPU_UNCAPTURED_ERROR' | 'BIND_GROUP_MISMATCH' | 'TEXTURE_USAGE_INVALID' | 'TEXTURE_REQUEST_FAILED' | 'TEXTURE_DECODE_UNAVAILABLE' | 'TEXTURE_REQUEST_ABORTED' | 'MOTIONGPU_RUNTIME_ERROR';
+/**
+ * Severity level for user-facing diagnostics.
+ */
+export type MotionGPUErrorSeverity = 'error' | 'fatal';
 /**
  * One source-code line displayed in diagnostics snippet.
  */
@@ -20,10 +28,35 @@ export interface MotionGPUErrorSource {
     column?: number;
     snippet: MotionGPUErrorSourceLine[];
 }
+/**
+ * Optional runtime context captured with diagnostics payload.
+ */
+export interface MotionGPUErrorContext {
+    materialSignature?: string;
+    passGraph?: {
+        passCount: number;
+        enabledPassCount: number;
+        inputs: string[];
+        outputs: string[];
+    };
+    activeRenderTargets: string[];
+}
 /**
  * Structured error payload used by UI diagnostics.
  */
 export interface MotionGPUErrorReport {
+    /**
+     * Stable machine-readable category code.
+     */
+    code: MotionGPUErrorCode;
+    /**
+     * Severity level used by diagnostics UIs and telemetry.
+     */
+    severity: MotionGPUErrorSeverity;
+    /**
+     * Whether runtime may recover without full renderer re-creation.
+     */
+    recoverable: boolean;
     /**
      * Short category title.
      */
@@ -56,6 +89,10 @@ export interface MotionGPUErrorReport {
      * Optional source context for shader-related diagnostics.
      */
     source: MotionGPUErrorSource | null;
+    /**
+     * Optional runtime context snapshot (material/pass graph/render targets).
+     */
+    context: MotionGPUErrorContext | null;
 }
 /**
  * Converts unknown errors to a consistent, display-ready error report.

package/dist/core/error-report.js

@@ -98,53 +98,107 @@ function formatDiagnosticMessage(entry) {
 function classifyErrorMessage(message) {
     if (message.includes('WebGPU is not available in this browser')) {
         return {
+            code: 'WEBGPU_UNAVAILABLE',
+            severity: 'fatal',
+            recoverable: false,
             title: 'WebGPU unavailable',
             hint: 'Use a browser with WebGPU enabled (latest Chrome/Edge/Safari TP) and secure context.'
         };
     }
     if (message.includes('Unable to acquire WebGPU adapter')) {
         return {
+            code: 'WEBGPU_ADAPTER_UNAVAILABLE',
+            severity: 'fatal',
+            recoverable: false,
             title: 'WebGPU adapter unavailable',
             hint: 'GPU adapter request failed. Check browser permissions, flags and device support.'
         };
     }
     if (message.includes('Canvas does not support webgpu context')) {
         return {
+            code: 'WEBGPU_CONTEXT_UNAVAILABLE',
+            severity: 'error',
+            recoverable: true,
             title: 'Canvas cannot create WebGPU context',
             hint: 'Make sure this canvas is attached to DOM and not using an unsupported context option.'
         };
     }
     if (message.includes('WGSL compilation failed')) {
         return {
+            code: 'WGSL_COMPILATION_FAILED',
+            severity: 'error',
+            recoverable: true,
             title: 'WGSL compilation failed',
             hint: 'Check WGSL line numbers below and verify struct/binding/function signatures.'
         };
     }
     if (message.includes('WebGPU device lost') || message.includes('Device Lost')) {
         return {
+            code: 'WEBGPU_DEVICE_LOST',
+            severity: 'fatal',
+            recoverable: false,
             title: 'WebGPU device lost',
             hint: 'GPU device/context was lost. Recreate the renderer and check OS/GPU stability.'
         };
     }
     if (message.includes('WebGPU uncaptured error')) {
         return {
+            code: 'WEBGPU_UNCAPTURED_ERROR',
+            severity: 'error',
+            recoverable: true,
             title: 'WebGPU uncaptured error',
             hint: 'A GPU command failed asynchronously. Review details and validate resource/state usage.'
         };
     }
     if (message.includes('CreateBindGroup') || message.includes('bind group layout')) {
         return {
+            code: 'BIND_GROUP_MISMATCH',
+            severity: 'error',
+            recoverable: true,
             title: 'Bind group mismatch',
             hint: 'Bindings in shader and runtime resources are out of sync. Verify uniforms/textures layout.'
         };
     }
     if (message.includes('Destination texture needs to have CopyDst')) {
         return {
+            code: 'TEXTURE_USAGE_INVALID',
+            severity: 'error',
+            recoverable: true,
             title: 'Invalid texture usage flags',
             hint: 'Texture used as upload destination must include CopyDst (and often RenderAttachment).'
         };
     }
+    if (message.includes('Texture request failed')) {
+        return {
+            code: 'TEXTURE_REQUEST_FAILED',
+            severity: 'error',
+            recoverable: true,
+            title: 'Texture request failed',
+            hint: 'Verify texture URL, CORS policy and response status before retrying.'
+        };
+    }
+    if (message.includes('createImageBitmap is not available in this runtime')) {
+        return {
+            code: 'TEXTURE_DECODE_UNAVAILABLE',
+            severity: 'fatal',
+            recoverable: false,
+            title: 'Texture decode unavailable',
+            hint: 'Runtime lacks createImageBitmap support. Use a browser/runtime with image bitmap decoding.'
+        };
+    }
+    if (message.toLowerCase().includes('texture request was aborted')) {
+        return {
+            code: 'TEXTURE_REQUEST_ABORTED',
+            severity: 'error',
+            recoverable: true,
+            title: 'Texture request aborted',
+            hint: 'Texture load was cancelled. Retry the request when source inputs stabilize.'
+        };
+    }
     return {
+        code: 'MOTIONGPU_RUNTIME_ERROR',
+        severity: 'error',
+        recoverable: true,
         title: 'MotionGPU render error',
         hint: 'Review technical details below. If issue persists, isolate shader/uniform/texture changes.'
     };
@@ -167,6 +221,7 @@ export function toMotionGPUErrorReport(error, phase) {
     const defaultMessage = rawLines[0] ?? rawMessage;
     const defaultDetails = rawLines.slice(1);
     const source = buildSourceFromDiagnostics(error);
+    const context = shaderDiagnostics?.runtimeContext ?? null;
     const message = shaderDiagnostics && shaderDiagnostics.diagnostics[0]
         ? formatDiagnosticMessage(shaderDiagnostics.diagnostics[0])
         : defaultMessage;
@@ -178,6 +233,9 @@ export function toMotionGPUErrorReport(error, phase) {
         : [];
     const classification = classifyErrorMessage(rawMessage);
     return {
+        code: classification.code,
+        severity: classification.severity,
+        recoverable: classification.recoverable,
         title: classification.title,
         message,
         hint: classification.hint,
@@ -185,6 +243,7 @@ export function toMotionGPUErrorReport(error, phase) {
         stack,
         rawMessage,
         phase,
-        source
+        source,
+        context
     };
 }

package/dist/core/index.d.ts

@@ -11,7 +11,7 @@ export { createMotionGPURuntimeLoop } from './runtime-loop.js';
 export { loadTexturesFromUrls } from './texture-loader.js';
 export { BlitPass, CopyPass, ShaderPass } from '../passes/index.js';
 export type { CurrentReadable, CurrentWritable, Subscribable } from './current-value.js';
-export type { MotionGPUErrorPhase, MotionGPUErrorReport, MotionGPUErrorSource, MotionGPUErrorSourceLine } from './error-report.js';
+export type { MotionGPUErrorCode, MotionGPUErrorContext, MotionGPUErrorPhase, MotionGPUErrorReport, MotionGPUErrorSeverity, MotionGPUErrorSource, MotionGPUErrorSourceLine } from './error-report.js';
 export type { FrameCallback, FrameKey, FrameProfilingSnapshot, FrameRegistry, FrameRunTimings, FrameScheduleSnapshot, FrameStage, FrameStageCallback, FrameTask, FrameTaskInvalidation, FrameTaskInvalidationToken, FrameTimingStats, UseFrameOptions, UseFrameResult } from './frame-registry.js';
 export type { FragMaterial, FragMaterialInput, MaterialDefineValue, MaterialDefines, MaterialIncludes, ResolvedMaterial, TypedMaterialDefineValue } from './material.js';
 export type { MotionGPURuntimeLoop, MotionGPURuntimeLoopOptions } from './runtime-loop.js';

package/dist/core/material-preprocess.d.ts

@@ -44,11 +44,11 @@ export interface PreprocessedMaterialFragment {
 /**
  * Validates and normalizes define entries.
  */
-export declare function normalizeDefines(defines: MaterialDefines | undefined): MaterialDefines;
+export declare function normalizeDefines<TDefineKey extends string>(defines: MaterialDefines<TDefineKey> | undefined): MaterialDefines<TDefineKey>;
 /**
  * Validates include map identifiers and source chunks.
  */
-export declare function normalizeIncludes(includes: MaterialIncludes | undefined): MaterialIncludes;
+export declare function normalizeIncludes<TIncludeKey extends string>(includes: MaterialIncludes<TIncludeKey> | undefined): MaterialIncludes<TIncludeKey>;
 /**
  * Converts one define declaration to WGSL `const`.
  */
@@ -56,8 +56,8 @@ export declare function toDefineLine(key: string, value: MaterialDefineValue): s
 /**
  * Preprocesses material fragment with deterministic define/include expansion and line mapping.
  */
-export declare function preprocessMaterialFragment(input: {
+export declare function preprocessMaterialFragment<TDefineKey extends string, TIncludeKey extends string>(input: {
     fragment: string;
-    defines?: MaterialDefines;
-    includes?: MaterialIncludes;
+    defines?: MaterialDefines<TDefineKey>;
+    includes?: MaterialIncludes<TIncludeKey>;
 }): PreprocessedMaterialFragment;

package/dist/core/material-preprocess.js

@@ -44,10 +44,7 @@ export function normalizeDefines(defines) {
             continue;
         }
         const normalized = normalizeTypedDefine(name, value);
-        resolved[name] = Object.freeze({
-            type: normalized.type,
-            value: normalized.value
-        });
+        resolved[name] = Object.freeze(normalized);
     }
     return resolved;
 }

package/dist/core/material.d.ts

@@ -5,16 +5,25 @@ import type { TextureDefinitionMap, UniformMap } from './types.js';
 /**
  * Typed compile-time define declaration.
  */
-export interface TypedMaterialDefineValue {
+export type TypedMaterialDefineValue = {
     /**
      * WGSL scalar type.
      */
-    type: 'bool' | 'f32' | 'i32' | 'u32';
+    type: 'bool';
     /**
      * Literal value for the selected WGSL type.
      */
-    value: boolean | number;
-}
+    value: boolean;
+} | {
+    /**
+     * WGSL scalar type.
+     */
+    type: 'f32' | 'i32' | 'u32';
+    /**
+     * Literal value for the selected WGSL type.
+     */
+    value: number;
+};
 /**
  * Allowed value types for WGSL `const` define injection.
  */
@@ -22,15 +31,15 @@ export type MaterialDefineValue = boolean | number | TypedMaterialDefineValue;
 /**
  * Define map keyed by uniform-compatible identifier names.
  */
-export type MaterialDefines = Record<string, MaterialDefineValue>;
+export type MaterialDefines<TKey extends string = string> = Record<TKey, MaterialDefineValue>;
 /**
  * Include map keyed by include identifier used in `#include <name>` directives.
  */
-export type MaterialIncludes = Record<string, string>;
+export type MaterialIncludes<TKey extends string = string> = Record<TKey, string>;
 /**
  * External material input accepted by {@link defineMaterial}.
  */
-export interface FragMaterialInput {
+export interface FragMaterialInput<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string> {
     /**
      * User WGSL source containing `frag(uv: vec2f) -> vec4f`.
      */
@@ -38,24 +47,24 @@ export interface FragMaterialInput {
     /**
      * Initial uniform values.
      */
-    uniforms?: UniformMap;
+    uniforms?: UniformMap<TUniformKey>;
     /**
      * Texture definitions keyed by texture uniform name.
      */
-    textures?: TextureDefinitionMap;
+    textures?: TextureDefinitionMap<TTextureKey>;
     /**
      * Optional compile-time define constants injected into WGSL.
      */
-    defines?: MaterialDefines;
+    defines?: MaterialDefines<TDefineKey>;
     /**
      * Optional WGSL include chunks used by `#include <name>` directives.
      */
-    includes?: MaterialIncludes;
+    includes?: MaterialIncludes<TIncludeKey>;
 }
 /**
  * Normalized and immutable material declaration consumed by `FragCanvas`.
  */
-export interface FragMaterial {
+export interface FragMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string> {
     /**
      * User WGSL source containing `frag(uv: vec2f) -> vec4f`.
      */
@@ -63,24 +72,24 @@ export interface FragMaterial {
     /**
      * Initial uniform values.
      */
-    readonly uniforms: Readonly<UniformMap>;
+    readonly uniforms: Readonly<UniformMap<TUniformKey>>;
     /**
      * Texture definitions keyed by texture uniform name.
      */
-    readonly textures: Readonly<TextureDefinitionMap>;
+    readonly textures: Readonly<TextureDefinitionMap<TTextureKey>>;
     /**
      * Optional compile-time define constants injected into WGSL.
      */
-    readonly defines: Readonly<MaterialDefines>;
+    readonly defines: Readonly<MaterialDefines<TDefineKey>>;
     /**
      * Optional WGSL include chunks used by `#include <name>` directives.
      */
-    readonly includes: Readonly<MaterialIncludes>;
+    readonly includes: Readonly<MaterialIncludes<TIncludeKey>>;
 }
 /**
  * Fully resolved, immutable material snapshot used for renderer creation/caching.
  */
-export interface ResolvedMaterial {
+export interface ResolvedMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TIncludeKey extends string = string> {
     /**
      * Final fragment WGSL after define injection.
      */
@@ -92,11 +101,11 @@ export interface ResolvedMaterial {
     /**
      * Cloned uniforms.
      */
-    uniforms: UniformMap;
+    uniforms: UniformMap<TUniformKey>;
     /**
      * Cloned texture definitions.
      */
-    textures: TextureDefinitionMap;
+    textures: TextureDefinitionMap<TTextureKey>;
     /**
      * Resolved packed uniform layout.
      */
@@ -104,7 +113,7 @@ export interface ResolvedMaterial {
     /**
      * Sorted texture keys.
      */
-    textureKeys: string[];
+    textureKeys: TTextureKey[];
     /**
      * Deterministic JSON signature for cache invalidation.
      */
@@ -116,7 +125,7 @@ export interface ResolvedMaterial {
     /**
      * Normalized include sources map.
      */
-    includeSources: MaterialIncludes;
+    includeSources: MaterialIncludes<TIncludeKey>;
     /**
      * Deterministic define block source used for diagnostics mapping.
      */
@@ -147,11 +156,11 @@ export declare function applyMaterialDefines(fragment: string, defines: Material
  * @param input - User material declaration.
  * @returns Frozen material object safe to share and cache.
  */
-export declare function defineMaterial(input: FragMaterialInput): FragMaterial;
+export declare function defineMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string>(input: FragMaterialInput<TUniformKey, TTextureKey, TDefineKey, TIncludeKey>): FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey>;
 /**
  * Resolves a material to renderer-ready data and a deterministic signature.
  *
  * @param material - Material input created via {@link defineMaterial}.
  * @returns Resolved material with packed uniform layout, sorted texture keys and cache signature.
  */
-export declare function resolveMaterial(material: FragMaterial): ResolvedMaterial;
+export declare function resolveMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string>(material: FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey>): ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey>;

package/dist/core/material.js

@@ -6,12 +6,17 @@ import { normalizeDefines, normalizeIncludes, preprocessMaterialFragment, toDefi
  */
 const FRAGMENT_FUNCTION_SIGNATURE_PATTERN = /\bfn\s+frag\s*\(\s*([^)]*?)\s*\)\s*->\s*([A-Za-z_][A-Za-z0-9_<>\s]*)\s*(?:\{|$)/m;
 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.
- */
 const resolvedMaterialCache = new WeakMap();
 const preprocessedFragmentCache = new WeakMap();
 const materialSourceMetadataCache = new WeakMap();
+function getCachedResolvedMaterial(material) {
+    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;
+}
 const STACK_TRACE_CHROME_PATTERN = /^\s*at\s+(?:(.*?)\s+\()?(.+?):(\d+):(\d+)\)?$/;
 const STACK_TRACE_FIREFOX_PATTERN = /^(.*?)@(.+?):(\d+):(\d+)$/;
 function getPathBasename(path) {
@@ -204,9 +209,11 @@ function resolveTextures(textures) {
     const resolved = {};
     for (const [name, definition] of Object.entries(textures ?? {})) {
         assertUniformName(name);
+        const source = definition?.source;
+        const normalizedSource = cloneTextureValue(source);
         const clonedDefinition = {
             ...(definition ?? {}),
-            source: cloneTextureValue(definition?.source)
+            ...(source !== undefined ? { source: normalizedSource } : {})
         };
         resolved[name] = Object.freeze(clonedDefinition);
     }
@@ -296,8 +303,8 @@ export function defineMaterial(input) {
     const source = Object.freeze(resolveSourceMetadata(undefined));
     const preprocessed = preprocessMaterialFragment({
         fragment,
-        defines: defines,
-        includes: includes
+        defines,
+        includes
     });
     const material = Object.freeze({
         fragment,
@@ -318,7 +325,7 @@ export function defineMaterial(input) {
  */
 export function resolveMaterial(material) {
     assertDefinedMaterial(material);
-    const cached = resolvedMaterialCache.get(material);
+    const cached = getCachedResolvedMaterial(material);
     if (cached) {
         return cached;
     }