docs(GltfLoader): document Promise requirement, rejection propagation, and add @param/@returns to resolveUri

[Copilot]

The resolveUri JSDoc was silent on the async contract: it didn't state the callback must return a Promise, didn't document that rejections propagate out of loadGltf, and had no @param or @returns tags.

src/core/GltfLoader.ts

• Added explicit statement that the callback must return a Promise
• Documented that rejections propagate directly from loadGltf
• Added @param uri — incorporates the previously orphaned percent-decoding failure note
• Added @returns — Promise<ArrayBuffer> resolving to raw buffer bytes
• Reorganized body for logical flow: security warning → description → contract → param/returns

/**
 * @security Never perform additional URI decoding or resolution inside this callback.
 * The loader has already validated and best-effort percent-decoded the URI;
 * re-decoding may re-introduce path-traversal or SSRF vulnerabilities.
 *
 * Optional async callback invoked to resolve external buffer URIs referenced by the
 * glTF asset (non-`data:` references found in `buffers[].uri`).
 * Required when loading plain `.gltf` files that reference external `.bin` files.
 *
 * The callback **must** return a `Promise` that resolves to the raw bytes of the
 * referenced buffer. Rejections propagate directly from `loadGltf`.
 *
 * @param uri The raw URI string extracted from the glTF JSON, already validated
 *   against the loader's URI whitelist and best-effort percent-decoded. If
 *   percent-decoding fails due to invalid percent-encoding, the original URI string
 *   (with invalid sequences preserved) may be passed instead. Do **not** perform
 *   additional URI resolution or decoding inside this callback.
 * @returns A `Promise` resolving to the buffer's raw bytes as an `ArrayBuffer`.
 */
resolveUri?: (uri: string) => Promise<ArrayBuffer>;

tests/gltf.test.ts

Four new JSDoc-contract tests added to the existing GltfLoaderOptions JSDoc describe block, asserting that the source contains the Promise requirement, rejection propagation statement, @param uri, and @returns tags.

[Copilot]

Pull request overview

Improves the GltfLoaderOptions.resolveUri documentation to clearly specify its async Promise contract, how failures propagate, and to add explicit @param/@returns tags; adds tests to lock in those documentation requirements.

Changes:

• Expanded resolveUri JSDoc to require a Promise<ArrayBuffer>, document rejection propagation, and add @param uri / @returns.
• Reorganized the JSDoc block for clearer security → contract → tags flow.
• Added tests asserting the presence of the new JSDoc contract statements and tags in the source.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/core/GltfLoader.ts	Updates resolveUri JSDoc contract (Promise requirement, rejection propagation, param/returns).
tests/gltf.test.ts	Adds JSDoc “contract” tests that assert the updated documentation content is present.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.