@openusd-wasm/utils 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 KeJun <https://github.com/kejunmao>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @openusd-wasm/utils
+
+Shared utilities for browser and worker OpenUSD workflows backed by
+`@openusd-wasm/pxr`.
+
+```ts
+import { toLayerRelativeAssetPath } from '@openusd-wasm/utils'
+
+refs.AddReference(toLayerRelativeAssetPath('assets/gearbox.usdz'), '')
+```
+
+## Asset References
+
+When generating USDA files that reference assets written next to the layer,
+author explicit layer-relative asset paths. OpenUSD treats
+`@assets/model.usdz@` as a search-path asset, while `@./assets/model.usdz@`
+is anchored to the current layer directory and packages without transient
+`0/model.usdz` remap warnings.
+
+## Asset Resolution
+
+`autoResolveAssetFiles` and `autoResolveTextureFiles` scan USD references and
+metadata, fetch same-origin relative assets, and return virtual filesystem
+entries that can be written next to the root layer before opening or packaging
+with OpenUSD.
+
+`findPackageRootLayer`, `createPackageTextureResolver`, and
+`createTextureResolverFromEntries` help inspect stored USDZ packages and map
+packaged image entries to object URLs.

package/dist/openusd_utils.d.ts

@@ -0,0 +1,39 @@
+import { Pxr } from "@openusd-wasm/pxr";
+
+//#region src/types.d.ts
+interface USDAssetResolverOptions {
+  sourcePath?: string;
+  fileName?: string;
+  autoResolveAssets?: boolean;
+  assetSearchExtensions?: string[];
+  assetSearchRoots?: string[];
+  maxAssetReferences?: number;
+  maxAssetReferenceDepth?: number;
+}
+interface USDAssetValue {
+  path?: string;
+  resolvedPath?: string;
+  url?: string;
+}
+interface USDTextureResolverContext<TMaterial = unknown, TShader = unknown> {
+  sourcePath: string;
+  material?: TMaterial;
+  shader?: TShader;
+}
+type USDTextureResolver<TMaterial = unknown, TShader = unknown> = (asset: USDAssetValue, context: USDTextureResolverContext<TMaterial, TShader>) => string | null | undefined;
+//#endregion
+//#region src/asset-resolver.d.ts
+declare function toLayerRelativeAssetPath(assetPath: string): string;
+declare function autoResolveAssetFiles(pxr: Pxr, rootFilePath: string, options: USDAssetResolverOptions): Promise<Record<string, Uint8Array>>;
+declare function autoResolveTextureFiles(metadata: unknown, existingFiles: Record<string, Uint8Array>, options: USDAssetResolverOptions): Promise<Record<string, Uint8Array>>;
+declare function createTextureResolverFromEntries(entries: Map<string, Uint8Array>): {
+  resolve: USDTextureResolver;
+  urls: Map<string, string>;
+} | null;
+declare function createPackageTextureResolver(data: Uint8Array): {
+  resolve: USDTextureResolver;
+  urls: Map<string, string>;
+} | null;
+declare function findPackageRootLayer(data: Uint8Array): string | null;
+//#endregion
+export { type USDAssetResolverOptions, type USDAssetValue, type USDTextureResolver, type USDTextureResolverContext, autoResolveAssetFiles, autoResolveTextureFiles, createPackageTextureResolver, createTextureResolverFromEntries, findPackageRootLayer, toLayerRelativeAssetPath };

package/dist/openusd_utils.js

@@ -0,0 +1,466 @@
+//#region src/asset-resolver.ts
+const DEFAULT_ASSET_SEARCH_EXTENSIONS = [
+	".usd",
+	".usda",
+	".usdc",
+	".usdz",
+	".png",
+	".jpg",
+	".jpeg",
+	".webp",
+	".ktx2",
+	".exr",
+	".hdr",
+	".mdl"
+];
+const DEFAULT_ASSET_SEARCH_ROOTS = [
+	"resource",
+	"resources",
+	"asset",
+	"assets",
+	"img",
+	"image",
+	"images",
+	"texture",
+	"textures",
+	"material",
+	"materials"
+];
+const DEFAULT_MAX_ASSET_REFERENCES = 80;
+const DEFAULT_MAX_ASSET_REFERENCE_DEPTH = 4;
+const DEFAULT_PACKAGE_REMAP_ALIAS_COUNT = 16;
+const USD_LAYER_EXTENSIONS = new Set([
+	".usd",
+	".usda",
+	".usdc"
+]);
+const TEXTURE_DIRECTORY_NAMES = new Set([
+	"img",
+	"image",
+	"images",
+	"texture",
+	"textures"
+]);
+const ABSOLUTE_OR_SCHEME_PATH_PATTERN = /^(?:\/|[A-Za-z][A-Za-z0-9+.-]*:)/;
+function toFetchableUrl(value) {
+	try {
+		const url = new URL(value, globalThis.location?.href);
+		return url.protocol === "http:" || url.protocol === "https:" || url.protocol === "file:" ? url.href : null;
+	} catch {
+		return null;
+	}
+}
+function normalizeFsRelativePath(path) {
+	const parts = [];
+	for (const part of path.replaceAll("\\", "/").split("/")) {
+		if (!part || part === ".") continue;
+		if (part === "..") {
+			parts.pop();
+			continue;
+		}
+		parts.push(part);
+	}
+	return parts.join("/");
+}
+function toLayerRelativeAssetPath(assetPath) {
+	if (!assetPath || assetPath.startsWith("./") || assetPath.startsWith("../") || ABSOLUTE_OR_SCHEME_PATH_PATTERN.test(assetPath)) return assetPath;
+	return `./${assetPath}`;
+}
+function dirname(path) {
+	const normalized = normalizeFsRelativePath(path);
+	const index = normalized.lastIndexOf("/");
+	return index === -1 ? "" : normalized.slice(0, index);
+}
+function joinRelativePath(base, path) {
+	return normalizeFsRelativePath(base ? `${base}/${path}` : path);
+}
+function joinFsPath(base, path) {
+	return `${base.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+function fsDirname(path) {
+	const normalized = path.replace(/\/+$/, "");
+	const index = normalized.lastIndexOf("/");
+	if (index <= 0) return "/";
+	return normalized.slice(0, index);
+}
+function extensionOf(path) {
+	const match = /\.([A-Za-z0-9]+)$/.exec(path.split(/[?#]/)[0] ?? path);
+	return match ? `.${match[1]?.toLowerCase()}` : "";
+}
+function contentTypeForPath(path) {
+	switch (extensionOf(path)) {
+		case ".png": return "image/png";
+		case ".jpg":
+		case ".jpeg": return "image/jpeg";
+		case ".webp": return "image/webp";
+		default: return "application/octet-stream";
+	}
+}
+function baseName(path) {
+	return normalizeFsRelativePath(path).split("/").pop() ?? "";
+}
+function fileNameForSource(sourcePath) {
+	const name = (sourcePath.split(/[?#]/)[0] ?? sourcePath).split("/").filter(Boolean).pop();
+	return name && /\.[a-z0-9]+$/i.test(name) ? name : "scene.usda";
+}
+function toArrayBuffer(data) {
+	const buffer = new ArrayBuffer(data.byteLength);
+	new Uint8Array(buffer).set(data);
+	return buffer;
+}
+function trimAssetReference(value) {
+	let ref = value.trim();
+	if (!ref || ref.length > 220) return null;
+	ref = ref.replace(/^[@<"']+/, "").replace(/[@>"')\]},;]+$/g, "");
+	if (!ref || ref.startsWith("#") || ref.startsWith("$")) return null;
+	if (/^[A-Za-z]:[\\/]/.test(ref)) return null;
+	if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(ref)) return null;
+	if (ref.startsWith("/")) return null;
+	if (/[\0\r\n\t\f\v]/.test(ref)) return null;
+	if (!/^[ A-Za-z0-9._~!$&'()+,;=@/-]+$/.test(ref)) return null;
+	return ref;
+}
+function buildExtensionVariants(path, searchExtensions) {
+	const normalized = normalizeFsRelativePath(path);
+	if (!normalized) return [];
+	if (extensionOf(normalized)) return [normalized];
+	return [...searchExtensions.map((extension) => `${normalized}${extension}`), normalized];
+}
+function buildPackageRemapAliases(sourceRelativePath, assetPath) {
+	const extension = extensionOf(assetPath);
+	if (!extension || USD_LAYER_EXTENSIONS.has(extension)) return [];
+	const name = baseName(assetPath);
+	if (!name) return [];
+	const aliasDirs = new Set([dirname(sourceRelativePath)]);
+	const assetDir = dirname(assetPath);
+	const assetParentDir = dirname(assetDir);
+	const assetTextureDir = baseName(assetDir).toLowerCase();
+	if (TEXTURE_DIRECTORY_NAMES.has(assetTextureDir)) aliasDirs.add(assetParentDir);
+	return unique([...aliasDirs].flatMap((aliasDir) => Array.from({ length: DEFAULT_PACKAGE_REMAP_ALIAS_COUNT }, (_, index) => joinRelativePath(aliasDir, `${index}/${name}`))));
+}
+function addPackageRemapAliases(files, aliases, data, ownedAliases, aliasConflicts, existingFiles = {}) {
+	for (const alias of aliases) {
+		if (aliasConflicts.has(alias)) continue;
+		const existingInput = existingFiles[alias];
+		if (existingInput && existingInput !== data) {
+			aliasConflicts.add(alias);
+			continue;
+		}
+		const existing = files[alias];
+		if (existing && existing !== data) {
+			if (ownedAliases.has(alias)) {
+				delete files[alias];
+				ownedAliases.delete(alias);
+			}
+			aliasConflicts.add(alias);
+			continue;
+		}
+		if (!existing) {
+			files[alias] = data;
+			ownedAliases.add(alias);
+		}
+	}
+}
+function unique(values) {
+	return [...new Set(values)];
+}
+function uniqueFileCount(files) {
+	return new Set(Object.values(files)).size;
+}
+function firstPathSegment(path) {
+	return normalizeFsRelativePath(path).split("/")[0] ?? "";
+}
+function normalizeSearchRoots(roots) {
+	return unique((roots ?? DEFAULT_ASSET_SEARCH_ROOTS).map((root) => normalizeFsRelativePath(root)).filter(Boolean));
+}
+function inferReferencedSearchRoots(refs, searchRoots) {
+	const rootSet = new Set(searchRoots);
+	return unique(refs.map((ref) => firstPathSegment(ref)).filter((segment) => rootSet.has(segment)));
+}
+function buildFetchAttempts(ref, sourceUrl, sourceRelativePath, searchExtensions, rootSourceUrl, searchRoots) {
+	const sourceDir = dirname(sourceRelativePath);
+	const attempts = [];
+	const seen = /* @__PURE__ */ new Set();
+	const normalizedRef = normalizeFsRelativePath(ref);
+	const isDotRelative = /^\.{1,2}\//.test(ref);
+	const candidates = [];
+	function addCandidate(fsPath, fetchPath, baseUrl, aliases = []) {
+		const normalizedFsPath = normalizeFsRelativePath(fsPath);
+		if (!normalizedFsPath) return;
+		candidates.push({
+			fsPath: normalizedFsPath,
+			fetchPath,
+			baseUrl,
+			aliases: unique([
+				normalizedRef,
+				normalizedFsPath,
+				...aliases
+			].filter(Boolean))
+		});
+	}
+	if (!isDotRelative) {
+		for (const root of searchRoots) if (normalizedRef !== root && !normalizedRef.startsWith(`${root}/`)) addCandidate(`${root}/${normalizedRef}`, `${root}/${normalizedRef}`, rootSourceUrl);
+	}
+	addCandidate(joinRelativePath(sourceDir, ref), ref, sourceUrl);
+	if (!isDotRelative && sourceDir) addCandidate(normalizedRef, normalizedRef, rootSourceUrl);
+	for (const candidate of candidates) {
+		const fsAliases = new Set(candidate.aliases);
+		for (const pathWithExtension of buildExtensionVariants(candidate.fsPath, searchExtensions)) {
+			const extension = extensionOf(pathWithExtension);
+			fsAliases.add(pathWithExtension);
+			const fetchPath = extensionOf(candidate.fetchPath) ? candidate.fetchPath : `${candidate.fetchPath}${extension}`;
+			try {
+				const url = new URL(fetchPath, candidate.baseUrl).href;
+				if (seen.has(url)) continue;
+				seen.add(url);
+				attempts.push({
+					url,
+					fsPaths: [...fsAliases],
+					sourceRelativePath: pathWithExtension,
+					packageRemapAliases: buildPackageRemapAliases(sourceRelativePath, pathWithExtension)
+				});
+			} catch {}
+		}
+	}
+	return attempts;
+}
+async function fetchBinary(url) {
+	try {
+		const response = await fetch(url);
+		if (!response.ok) return null;
+		return new Uint8Array(await response.arrayBuffer());
+	} catch {
+		return null;
+	}
+}
+function extractedAssetReferences(extracted) {
+	return unique([
+		...extracted.subLayers,
+		...extracted.references,
+		...extracted.payloads
+	].map((ref) => trimAssetReference(ref)).filter((ref) => !!ref));
+}
+function isQueueableUsdLayer(path) {
+	return USD_LAYER_EXTENSIONS.has(extensionOf(path));
+}
+function shouldFetchAssetReference(ref, searchExtensions) {
+	const extension = extensionOf(ref);
+	return !extension || searchExtensions.includes(extension);
+}
+function existingFsPath(pxr, directory, relativePaths, files) {
+	for (const relativePath of relativePaths) if (files[relativePath] || pxr.FS.exists(joinFsPath(directory, relativePath))) return relativePath;
+	return null;
+}
+function urlForSourceRelativePath(sourceRelativePath, rootSourceUrl) {
+	try {
+		return new URL(sourceRelativePath, rootSourceUrl).href;
+	} catch {
+		return rootSourceUrl;
+	}
+}
+function queueUsdLayer(queue, queuedLayers, pxr, directory, sourceRelativePath, sourceUrl, rootSourceUrl, searchRoots, depth) {
+	if (!isQueueableUsdLayer(sourceRelativePath)) return;
+	const filePath = joinFsPath(directory, sourceRelativePath);
+	if (!pxr.FS.exists(filePath)) return;
+	const queueKey = sourceRelativePath;
+	if (queuedLayers.has(queueKey)) return;
+	queuedLayers.add(queueKey);
+	queue.push({
+		filePath,
+		sourceUrl,
+		rootSourceUrl,
+		sourceRelativePath,
+		searchRoots,
+		depth
+	});
+}
+async function autoResolveAssetFiles(pxr, rootFilePath, options) {
+	const sourcePath = options.sourcePath ?? "";
+	if (options.autoResolveAssets === false || !sourcePath) return {};
+	const sourceUrl = toFetchableUrl(sourcePath);
+	if (!sourceUrl) return {};
+	const searchExtensions = options.assetSearchExtensions ?? DEFAULT_ASSET_SEARCH_EXTENSIONS;
+	const configuredSearchRoots = normalizeSearchRoots(options.assetSearchRoots);
+	const maxFiles = options.maxAssetReferences ?? DEFAULT_MAX_ASSET_REFERENCES;
+	const maxDepth = options.maxAssetReferenceDepth ?? DEFAULT_MAX_ASSET_REFERENCE_DEPTH;
+	const rootRelativePath = normalizeFsRelativePath(options.fileName ?? fileNameForSource(sourcePath));
+	const directory = fsDirname(rootFilePath);
+	const files = {};
+	const ownedPackageAliases = /* @__PURE__ */ new Set();
+	const packageAliasConflicts = /* @__PURE__ */ new Set();
+	const fetchedUrls = /* @__PURE__ */ new Set();
+	const queuedLayers = /* @__PURE__ */ new Set();
+	const queue = [{
+		filePath: rootFilePath,
+		sourceUrl,
+		rootSourceUrl: sourceUrl,
+		sourceRelativePath: rootRelativePath,
+		searchRoots: inferReferencedSearchRoots([rootRelativePath], configuredSearchRoots),
+		depth: 0
+	}];
+	queuedLayers.add(rootRelativePath);
+	while (queue.length > 0 && uniqueFileCount(files) < maxFiles) {
+		const item = queue.shift();
+		if (!item || item.depth > maxDepth) continue;
+		const refs = extractedAssetReferences(pxr.UsdUtils.ExtractExternalReferences(item.filePath)).filter((ref) => shouldFetchAssetReference(ref, searchExtensions));
+		const itemSearchRoots = unique([
+			...item.searchRoots,
+			...inferReferencedSearchRoots(refs, configuredSearchRoots),
+			...inferReferencedSearchRoots([item.sourceRelativePath], configuredSearchRoots)
+		]);
+		for (const ref of refs) {
+			if (uniqueFileCount(files) >= maxFiles) break;
+			for (const attempt of buildFetchAttempts(ref, item.sourceUrl, item.sourceRelativePath, searchExtensions, item.rootSourceUrl, itemSearchRoots)) {
+				const existingPath = existingFsPath(pxr, directory, [attempt.sourceRelativePath], files);
+				if (existingPath) {
+					if (item.depth < maxDepth) queueUsdLayer(queue, queuedLayers, pxr, directory, existingPath, urlForSourceRelativePath(existingPath, item.rootSourceUrl), item.rootSourceUrl, itemSearchRoots, item.depth + 1);
+					break;
+				}
+				if (fetchedUrls.has(attempt.url)) continue;
+				fetchedUrls.add(attempt.url);
+				const data = await fetchBinary(attempt.url);
+				if (!data) continue;
+				for (const fsPath of attempt.fsPaths) {
+					ownedPackageAliases.delete(fsPath);
+					files[fsPath] = data;
+					if (isQueueableUsdLayer(fsPath)) pxr.FS.writeFile(joinFsPath(directory, fsPath), data);
+				}
+				addPackageRemapAliases(files, attempt.packageRemapAliases, data, ownedPackageAliases, packageAliasConflicts);
+				if (item.depth < maxDepth) queueUsdLayer(queue, queuedLayers, pxr, directory, attempt.sourceRelativePath, attempt.url, item.rootSourceUrl, itemSearchRoots, item.depth + 1);
+				break;
+			}
+		}
+	}
+	return files;
+}
+function isMetadataAssetReference(value, searchExtensions) {
+	if (/^(blob|data):/i.test(value)) return false;
+	if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(value)) return false;
+	if (value.startsWith("/")) return false;
+	return searchExtensions.includes(extensionOf(value));
+}
+function collectMetadataAssetReferences(value, searchExtensions, refs = /* @__PURE__ */ new Set()) {
+	if (!value) return refs;
+	if (Array.isArray(value)) {
+		for (const item of value) collectMetadataAssetReferences(item, searchExtensions, refs);
+		return refs;
+	}
+	if (typeof value !== "object") return refs;
+	const asset = value;
+	for (const item of [asset.path, asset.url]) if (typeof item === "string" && isMetadataAssetReference(item, searchExtensions)) refs.add(item);
+	for (const item of Object.values(value)) collectMetadataAssetReferences(item, searchExtensions, refs);
+	return refs;
+}
+async function autoResolveTextureFiles(metadata, existingFiles, options) {
+	const sourcePath = options.sourcePath ?? "";
+	if (options.autoResolveAssets === false || !sourcePath) return {};
+	const sourceUrl = toFetchableUrl(sourcePath);
+	if (!sourceUrl) return {};
+	const searchExtensions = options.assetSearchExtensions ?? DEFAULT_ASSET_SEARCH_EXTENSIONS;
+	const configuredSearchRoots = normalizeSearchRoots(options.assetSearchRoots);
+	const textureRefs = [...collectMetadataAssetReferences(metadata, searchExtensions)];
+	const searchRoots = unique([...inferReferencedSearchRoots(Object.keys(existingFiles), configuredSearchRoots), ...inferReferencedSearchRoots(textureRefs, configuredSearchRoots)]);
+	const maxFiles = options.maxAssetReferences ?? DEFAULT_MAX_ASSET_REFERENCES;
+	const remainingFiles = Math.max(maxFiles - uniqueFileCount(existingFiles), 0);
+	if (remainingFiles === 0) return {};
+	const rootRelativePath = normalizeFsRelativePath(options.fileName ?? fileNameForSource(sourcePath));
+	const files = {};
+	const ownedPackageAliases = /* @__PURE__ */ new Set();
+	const packageAliasConflicts = /* @__PURE__ */ new Set();
+	const fetchedUrls = /* @__PURE__ */ new Set();
+	let resolvedFiles = 0;
+	for (const ref of textureRefs) {
+		if (resolvedFiles >= remainingFiles) break;
+		for (const attempt of buildFetchAttempts(ref, sourceUrl, rootRelativePath, searchExtensions, sourceUrl, searchRoots)) {
+			if (attempt.fsPaths.some((path) => existingFiles[path] || files[path])) break;
+			if (fetchedUrls.has(attempt.url)) continue;
+			fetchedUrls.add(attempt.url);
+			const data = await fetchBinary(attempt.url);
+			if (!data) continue;
+			for (const fsPath of attempt.fsPaths) {
+				ownedPackageAliases.delete(fsPath);
+				files[fsPath] = data;
+			}
+			addPackageRemapAliases(files, attempt.packageRemapAliases, data, ownedPackageAliases, packageAliasConflicts, existingFiles);
+			resolvedFiles += 1;
+			break;
+		}
+	}
+	return files;
+}
+function readZipEntryName(data, start, length) {
+	return new TextDecoder().decode(data.subarray(start, start + length));
+}
+function extractStoredZipEntries(data) {
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	const entries = /* @__PURE__ */ new Map();
+	let offset = 0;
+	while (offset + 30 <= data.byteLength) {
+		if (view.getUint32(offset, true) !== 67324752) break;
+		const method = view.getUint16(offset + 8, true);
+		const compressedSize = view.getUint32(offset + 18, true);
+		const fileNameLength = view.getUint16(offset + 26, true);
+		const extraLength = view.getUint16(offset + 28, true);
+		const nameStart = offset + 30;
+		const dataStart = nameStart + fileNameLength + extraLength;
+		const dataEnd = dataStart + compressedSize;
+		if (dataEnd > data.byteLength) break;
+		const name = normalizeFsRelativePath(readZipEntryName(data, nameStart, fileNameLength));
+		if (name && method === 0) entries.set(name, data.slice(dataStart, dataEnd));
+		offset = dataEnd;
+	}
+	return entries;
+}
+function createTextureResolverFromEntries(entries) {
+	if (typeof Blob === "undefined" || typeof URL === "undefined" || typeof URL.createObjectURL !== "function") return null;
+	const imageEntries = new Map([...entries].filter(([path]) => [
+		".png",
+		".jpg",
+		".jpeg",
+		".webp"
+	].includes(extensionOf(path))));
+	if (imageEntries.size === 0) return null;
+	const byBaseName = /* @__PURE__ */ new Map();
+	for (const path of imageEntries.keys()) {
+		const name = baseName(path);
+		byBaseName.set(name, byBaseName.has(name) ? null : path);
+	}
+	const urls = /* @__PURE__ */ new Map();
+	const urlForEntry = (path) => {
+		const entry = imageEntries.get(path);
+		if (!entry) return null;
+		let url = urls.get(path);
+		if (!url) {
+			url = URL.createObjectURL(new Blob([toArrayBuffer(entry)], { type: contentTypeForPath(path) }));
+			urls.set(path, url);
+		}
+		return url;
+	};
+	const resolvePath = (value) => {
+		if (!value) return null;
+		const normalized = normalizeFsRelativePath(value.split(/[?#]/)[0] ?? value);
+		if (!normalized) return null;
+		if (imageEntries.has(normalized)) return urlForEntry(normalized);
+		const suffixMatches = [...imageEntries.keys()].filter((path) => path.endsWith(`/${normalized}`));
+		if (suffixMatches.length === 1 && suffixMatches[0]) return urlForEntry(suffixMatches[0]);
+		const virtualFsMatches = [...imageEntries.keys()].filter((path) => normalized.endsWith(`/${path}`));
+		if (virtualFsMatches.length === 1 && virtualFsMatches[0]) return urlForEntry(virtualFsMatches[0]);
+		const uniqueBaseName = byBaseName.get(baseName(normalized));
+		return uniqueBaseName ? urlForEntry(uniqueBaseName) : null;
+	};
+	return {
+		urls,
+		resolve(asset) {
+			return resolvePath(asset.resolvedPath) ?? resolvePath(asset.path) ?? resolvePath(asset.url) ?? null;
+		}
+	};
+}
+function createPackageTextureResolver(data) {
+	return createTextureResolverFromEntries(extractStoredZipEntries(data));
+}
+function findPackageRootLayer(data) {
+	for (const path of extractStoredZipEntries(data).keys()) if (USD_LAYER_EXTENSIONS.has(extensionOf(path))) return path;
+	return null;
+}
+//#endregion
+export { autoResolveAssetFiles, autoResolveTextureFiles, createPackageTextureResolver, createTextureResolverFromEntries, findPackageRootLayer, toLayerRelativeAssetPath };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@openusd-wasm/utils",
+  "type": "module",
+  "version": "0.0.2",
+  "description": "Shared OpenUSD WebAssembly utilities for asset resolution and USDZ packaging workflows.",
+  "license": "MIT",
+  "homepage": "https://github.com/openusd-wasm/openusd-pxr-wasm",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openusd-wasm/openusd-pxr-wasm.git",
+    "directory": "packages/utils"
+  },
+  "main": "./dist/openusd_utils.js",
+  "module": "./dist/openusd_utils.js",
+  "types": "./dist/openusd_utils.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/openusd_utils.d.ts",
+      "import": "./dist/openusd_utils.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@openusd-wasm/pxr": "0.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "debug": "tsdown --sourcemap",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}