A file map keyed only by basename is insufficient when two folders both contain texture.png. Keep the relative directory structure or reject ambiguous input with a useful message.
Build a path-aware file inventory
Collect the files through the application's supported selection interface. Record each relative path, size, and file object. Preserve the distinction between the package root and a subdirectory containing the glTF file.
Normalize separators consistently for lookup, but do not silently collapse distinct paths into one. Detect collisions and missing path information before loading.
Identify the scene entry point explicitly when the selection contains several glTF files. Do not choose one merely because it appears first in a list.
Resolve requested URLs through one map
Use a shared loading manager for the asset's dependent resources. LoadingManager.setURLModifier provides a hook for mapping resource URLs to temporary object URLs.
Resolve a relative URI from the directory of the referring glTF document. Compare the normalized result with the selected-file inventory. Keep a cache so repeated references to the same file do not create unnecessary temporary URLs.
Handle data URIs and allowed external URLs deliberately. A local-file tool should not silently fetch unapproved remote dependencies when the user expects a self-contained local review.
Keep the package base path explicit
Pass the correct base context to the loader path used by the application. The GLTFLoader documentation distinguishes loading and parsing operations. Verify the installed API rather than assuming the same argument means a filesystem directory in every environment.
For an illustrative package, models/product.gltf may refer to ../textures/body.png. The lookup must resolve to the selected textures directory, not search randomly for any file called body.png.
Report the requested path when a dependency is absent. "Missing textures/body.png" gives the user a repair action. A generic model-failed message does not.
Test path resolution with a deliberately ambiguous package
Use a small package with models/product.gltf, textures/body.png, and accessories/body.png. Make the glTF reference one of those images explicitly. If both images map to the key body.png, lookup can silently choose the wrong one while the model still appears to load.
Resolve each URI against the referring document's directory, normalize it once, and verify that the result remains inside the selected package. Decode URI escapes consistently with the inventory, reject collisions, and retain case distinctions where required. Do not turn a missing local resource into an unannounced network fallback.
The URL modifier should return an object URL for the matched File and keep that URL alive until its consumer has finished. Track the URLs per attempt so cancellation and stale completions release their own resources without revoking URLs still used by the active asset.
Release temporary URLs after their work is complete
Track created object URLs as part of the load operation. Revoke them after the dependent consumers have finished, or when the operation is cancelled and no consumer still needs them.
Do not revoke a texture URL immediately after assigning it if decoding has not completed. Include failure and stale-request paths in cleanup.
Test nested folders, duplicate basenames, missing buffers, missing images, and filenames requiring URI decoding. Test the actual file-selection behavior of the target browser.
Accept the implementation when the complete local package loads without accidental network substitution and every missing resource produces a specific explanation. Keep the selected source files unchanged. Dependency resolution should make the package understandable, not conceal its incomplete contents.