@loaders.gl/scene 5.0.0-alpha.9 → 5.0.0-beta.10

package/src/stl/parse-stl.ts

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+// loaders.gl
+import type {Mesh} from '@loaders.gl/core/schema';
+import {deduceMeshSchema, getMeshBoundingBox} from '@loaders.gl/core/schema-utils';
+
+/** Parses ASCII or little-endian binary STL without changing authored normals. */
+export function parseSTL(data: ArrayBuffer): Mesh {
+  const view = new DataView(data);
+  const binary = data.byteLength >= 84 && 84 + view.getUint32(80, true) * 50 === data.byteLength;
+  let positions: Float32Array;
+  let normals: Float32Array;
+  let header: string;
+  if (binary) {
+    const triangleCount = view.getUint32(80, true);
+    positions = new Float32Array(triangleCount * 9);
+    normals = new Float32Array(triangleCount * 9);
+    header = new TextDecoder().decode(data.slice(0, 80));
+    for (let triangle = 0; triangle < triangleCount; triangle++) {
+      const offset = 84 + triangle * 50;
+      for (let component = 0; component < 9; component++) {
+        positions[triangle * 9 + component] = view.getFloat32(offset + 12 + component * 4, true);
+        normals[triangle * 9 + component] = view.getFloat32(offset + (component % 3) * 4, true);
+      }
+    }
+  } else {
+    const lines = new TextDecoder()
+      .decode(data)
+      .trim()
+      .split(/\r?\n/)
+      .map(line => line.trim())
+      .filter(Boolean);
+    const vertices: number[] = [];
+    const normalValues: number[] = [];
+    header = lines[0] || '';
+    let lineIndex = 0;
+    while (lineIndex < lines.length) {
+      if (!/^solid(?:\s|$)/i.test(lines[lineIndex++]))
+        throw new Error('STL: expected solid header or exact binary length');
+      while (lineIndex < lines.length && !/^endsolid(?:\s|$)/i.test(lines[lineIndex])) {
+        const normal = parseVector(lines[lineIndex++], 'facet normal');
+        if (!/^outer\s+loop$/i.test(lines[lineIndex++] || ''))
+          throw new Error('STL: expected outer loop');
+        for (let vertex = 0; vertex < 3; vertex++) {
+          vertices.push(...parseVector(lines[lineIndex++], 'vertex'));
+          normalValues.push(...normal);
+        }
+        if (
+          !/^endloop$/i.test(lines[lineIndex++] || '') ||
+          !/^endfacet$/i.test(lines[lineIndex++] || '')
+        )
+          throw new Error('STL: incomplete facet');
+      }
+      if (lineIndex >= lines.length) throw new Error('STL: missing endsolid');
+      lineIndex++;
+    }
+    if (!lines.length) throw new Error('STL: empty input');
+    positions = new Float32Array(vertices);
+    normals = new Float32Array(normalValues);
+  }
+  if (!positions.every(Number.isFinite) || !normals.every(Number.isFinite))
+    throw new Error('STL: non-finite coordinates');
+  const attributes = {POSITION: {value: positions, size: 3}, NORMAL: {value: normals, size: 3}};
+  return {
+    topology: 'triangle-list',
+    mode: 4,
+    attributes,
+    schema: deduceMeshSchema(attributes),
+    header: {
+      vertexCount: positions.length / 3,
+      boundingBox: getMeshBoundingBox(attributes) ?? undefined
+    },
+    loaderData: {header, format: binary ? 'binary' : 'ascii'}
+  };
+}
+
+/** Reads exactly three finite decimal components after an ASCII record prefix. */
+function parseVector(line: string | undefined, prefix: string): number[] {
+  const tokens = line?.split(/\s+/) || [];
+  const prefixTokens = prefix.split(' ');
+  const components = tokens.slice(prefixTokens.length);
+  if (
+    prefixTokens.some((token, index) => tokens[index]?.toLowerCase() !== token) ||
+    components.length !== 3 ||
+    components.some(value => !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(value))
+  ) {
+    throw new Error(`STL: invalid ${prefix} record`);
+  }
+  return components.map(Number);
+}

package/src/stl-loader-types.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+/** Package version injected by the build. */
+// @ts-ignore __VERSION__ is injected during compilation.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+// loaders.gl
+import type {Mesh} from '@loaders.gl/core/schema';
+
+/** Loads the STL parser on demand. */
+async function preload() {
+  const {STLLoaderWithParser} = await import('@loaders.gl/scene/stl-loader');
+  return STLLoaderWithParser;
+}
+
+/** Metadata-only loader for ASCII and binary STL triangle meshes. */
+export const STLLoader = {
+  name: 'STL',
+  id: 'stl',
+  module: 'scene',
+  version: VERSION,
+  extensions: ['stl'],
+  mimeTypes: ['model/stl'],
+  binary: true,
+  dataType: null as unknown as Mesh,
+  batchType: null as never,
+  options: {},
+  preload
+} as const;

package/src/stl-loader.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+// loaders.gl
+import {STLLoader} from './stl-loader-types';
+import {parseSTL} from './stl/parse-stl';
+const {preload: _preload, ...metadata} = STLLoader;
+/** Parser-bearing STL loader returning renderer-independent triangle meshes. */
+export const STLLoaderWithParser = {
+  ...metadata,
+  parse: async (data: ArrayBuffer) => parseSTL(data),
+  parseSync: parseSTL
+} as const;

package/src/usd/index.ts

@@ -0,0 +1,16 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {USDLoader} from './usd-loader-types';
+export type {
+  USDAssetPath,
+  USDAttribute,
+  USDEmbeddedAsset,
+  USDLoaderOptions,
+  USDPrim,
+  USDScenePath,
+  USDStage,
+  USDValue,
+  USDVariant
+} from './lib/usd-types';

package/src/{lib → usd/lib}/parse-usd.ts

@@ -1,11 +1,20 @@
-// loaders.gl
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
+import {parseUSDC} from './parse-usdc';
+// loaders.gl
 
-import type {LoaderContext} from '@loaders.gl/loader-utils';
+import type {LoaderContext} from '@loaders.gl/core/loader-utils';
 import {parseUSDA} from './parse-usda';
 import {parseUSDZArchive} from './parse-usdz';
-import type {USDAssetPath, USDLoaderOptions, USDPrim, USDStage, USDValue} from './usd-types';
+import type {
+  USDAssetPath,
+  USDEmbeddedAsset,
+  USDLoaderOptions,
+  USDPrim,
+  USDStage,
+  USDValue,
+  USDVariant
+} from './usd-types';
 
 type USDParseEnvironment = {
   /** Fetch implementation used for external layers. */
@@ -54,23 +63,45 @@ export async function parseUSD(
   let stage: USDStage;
   if (isZIPArchive(data)) {
     const archive = parseUSDZArchive(data);
-    const rootFilename = Array.from(archive.keys()).find(filename => /\.usda?$/i.test(filename));
-    if (!rootFilename) {
-      throw new Error('USDZ archives with binary USDC root layers are not implemented yet.');
+    const rootFilename = archive.keys().next().value;
+    if (!rootFilename || !/\.(?:usd[ac]?)$/i.test(rootFilename)) {
+      throw new Error('USDZ archive has no supported USD root layer.');
     }
 
     const archiveBase = 'https://usd.archive/';
+    const assets: Record<string, USDEmbeddedAsset> = Object.create(null);
     for (const [filename, content] of archive) {
-      environment.archiveFiles.set(new URL(filename, archiveBase).href, content);
+      const assetUrl = new URL(filename, archiveBase);
+      if (
+        filename.startsWith('/') ||
+        /^[a-z][a-z\d+.-]*:/i.test(filename) ||
+        filename.includes('\\') ||
+        /[\u0000-\u001f\u007f]/.test(filename) ||
+        filename.trim() !== filename ||
+        filename.split('/').some(segment => {
+          const normalizedSegment = segment.replace(/%2e/gi, '.');
+          return normalizedSegment === '.' || normalizedSegment === '..';
+        }) ||
+        assetUrl.origin !== new URL(archiveBase).origin ||
+        assetUrl.search ||
+        assetUrl.hash ||
+        assets[assetUrl.href]
+      ) {
+        throw new Error(`USDZ entry "${filename}" has an ambiguous package URL.`);
+      }
+      environment.archiveFiles.set(assetUrl.href, content);
+      assets[assetUrl.href] = createEmbeddedAsset(filename, content);
     }
     const rootUrl = new URL(rootFilename, archiveBase).href;
     stage = parseUSDLayer(archive.get(rootFilename)!, rootUrl);
     stage.format = 'usdz';
+    stage.assets = assets;
   } else {
     stage = parseUSDLayer(data, url);
   }
 
   if (stage.url) {
+    setAttributeSourceUrls(stage, stage.url);
     environment.layers.add(stage.url);
   }
   if (environment.options.usd?.compose !== false) {
@@ -83,6 +114,14 @@ export async function parseUSD(
   return stage;
 }
 
+/** Retains encoded file data and a conservative filename-based image MIME hint. */
+function createEmbeddedAsset(path: string, data: ArrayBuffer): USDEmbeddedAsset {
+  const extension = path.slice(path.lastIndexOf('.') + 1).toLowerCase();
+  const mimeType =
+    extension === 'png' ? 'image/png' : /^(?:jpe?g)$/.test(extension) ? 'image/jpeg' : undefined;
+  return mimeType ? {path, data, mimeType} : {path, data};
+}
+
 /** Selects a source location suitable for resolving referenced layers. */
 function getSourceLocation(
   configuredLocation: string | undefined,
@@ -126,11 +165,32 @@ const USD_LOADER_DEFAULT_OPTIONS = {
 function parseUSDLayer(data: ArrayBuffer, url?: string): USDStage {
   const signature = TEXT_DECODER.decode(data.slice(0, 8));
   if (signature === CRATE_SIGNATURE) {
-    throw new Error('Binary USDC crate layers are not implemented yet; use ASCII USDA layers.');
+    return parseUSDC(data, url);
   }
   return parseUSDA(TEXT_DECODER.decode(data), url);
 }
 
+/** Retains each attribute's authored layer before composition merges prims from different files. */
+function setAttributeSourceUrls(stage: USDStage, sourceUrl: string): void {
+  const pendingContents: (USDPrim | USDVariant)[] = [...stage.rootPrims];
+  while (pendingContents.length) {
+    const contents = pendingContents.pop()!;
+    for (const attribute of Object.values(contents.attributes)) {
+      attribute.sourceUrl = sourceUrl;
+    }
+    for (const child of contents.children) {
+      pendingContents.push(child);
+    }
+    if ('variants' in contents) {
+      for (const variants of Object.values(contents.variants)) {
+        for (const variant of Object.values(variants)) {
+          pendingContents.push(variant);
+        }
+      }
+    }
+  }
+}
+
 /** Recursively applies variants, references, overrides, and class filtering. */
 async function composePrims(
   prims: USDPrim[],
@@ -227,6 +287,7 @@ async function loadReferencedStage(
         content = response.arrayBuffer();
       }
       const stage = parseUSDLayer(await content, url);
+      setAttributeSourceUrls(stage, url);
       environment.layers.add(url);
       return stage;
     })();

package/src/usd/lib/parse-usdc.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import {USDCParser} from '../libs/usdc-parser.js';
+import type {USDPrim, USDStage, USDValue} from './usd-types';
+
+/** Decodes the supported binary crate subset into the same stage model as USDA. */
+export function parseUSDC(data: ArrayBuffer, url?: string): USDStage {
+  if (data.byteLength < 88 || data.byteLength > 64 * 1024 * 1024)
+    throw new Error('USDC: invalid input size');
+  const bytes = new Uint8Array(data);
+  if (bytes[8] !== 0 || bytes[9] !== 8 || bytes[10] !== 0)
+    throw new Error('USDC: initial decoder requires crate version 0.8.0');
+  const reader = new DataView(data);
+  const table = reader.getBigUint64(16, true);
+  if (table > BigInt(data.byteLength - 8)) throw new Error('USDC: invalid section table');
+  const offset = Number(table),
+    count = reader.getBigUint64(offset, true);
+  if (count > 16n || offset + 8 + Number(count) * 32 > data.byteLength)
+    throw new Error('USDC: invalid section table length');
+  const sectionNames = new Set<string>();
+  for (let index = 0; index < Number(count); index++) {
+    const entry = offset + 8 + index * 32;
+    const nameBytes = bytes.subarray(entry, entry + 16);
+    const terminator = nameBytes.indexOf(0);
+    const name = new TextDecoder().decode(
+      nameBytes.subarray(0, terminator < 0 ? nameBytes.length : terminator)
+    );
+    if (sectionNames.has(name)) throw new Error('USDC: duplicate section');
+    sectionNames.add(name);
+    const start = reader.getBigUint64(entry + 16, true),
+      size = reader.getBigUint64(entry + 24, true);
+    if (start < 88n || start + size > BigInt(data.byteLength))
+      throw new Error('USDC: section out of bounds');
+  }
+  for (const name of ['TOKENS', 'STRINGS', 'FIELDS', 'FIELDSETS', 'PATHS', 'SPECS'])
+    if (!sectionNames.has(name)) throw new Error('USDC: missing required section');
+  const {specsByPath} = new USDCParser().parseData(data);
+  const prims = new Map<string, USDPrim>();
+  for (const [path, specification] of Object.entries(specsByPath)) {
+    if (specification.specType === 7 && path === '/') continue;
+    if (specification.specType === 1 || specification.specType === 8) continue;
+    if (specification.specType !== 6 || !/^\/(?:[A-Za-z_][\w:]*\/)*[A-Za-z_][\w:]*$/.test(path))
+      throw new Error('USDC: unsupported prim specification');
+    const fields = specification.fields;
+    const specifier = fields.specifier ?? 0;
+    if (specifier !== 0 && specifier !== 1 && specifier !== 2)
+      throw new Error('USDC: invalid prim specifier');
+    const metadata = convertFields(
+      fields,
+      new Set(['specifier', 'typeName', 'primChildren', 'properties'])
+    );
+    prims.set(path, {
+      name: path.slice(path.lastIndexOf('/') + 1),
+      path,
+      sourceUrl: url,
+      type: String(fields.typeName || ''),
+      specifier: (['def', 'over', 'class'] as const)[specifier],
+      attributes: Object.create(null),
+      metadata,
+      variants: Object.create(null),
+      children: []
+    });
+  }
+  const roots: USDPrim[] = [];
+  for (const prim of prims.values()) {
+    const parentPath = prim.path.slice(0, prim.path.lastIndexOf('/'));
+    if (!parentPath) roots.push(prim);
+    else {
+      const parent = prims.get(parentPath);
+      if (!parent) throw new Error('USDC: missing parent prim');
+      parent.children.push(prim);
+    }
+  }
+  orderPrims(roots, specsByPath['/']?.fields.primChildren);
+  for (const prim of prims.values())
+    orderPrims(prim.children, specsByPath[prim.path]?.fields.primChildren);
+  for (const [path, specification] of Object.entries(specsByPath)) {
+    if (specification.specType !== 1 && specification.specType !== 8) continue;
+    const separator = path.indexOf('.');
+    const prim = prims.get(path.slice(0, separator));
+    if (separator < 0 || !prim) throw new Error('USDC: property has no owning prim');
+    const name = path.slice(separator + 1),
+      fields = specification.fields;
+    const type = specification.specType === 8 ? 'rel' : String(fields.typeName || '');
+    const value = convertAttributeValue(
+      specification.specType === 8 ? fields.targetPaths : fields.default,
+      type
+    );
+    const metadata = convertFields(
+      fields,
+      new Set(['typeName', 'default', 'targetPaths', 'timeSamples'])
+    );
+    if (fields.timeSamples !== undefined)
+      metadata.timeSamples = convertTimeSamples(fields.timeSamples, type);
+    prim.attributes[name] = {
+      name,
+      type,
+      value,
+      metadata
+    };
+  }
+  return {
+    format: 'usdc',
+    url,
+    metadata: convertFields(specsByPath['/']?.fields || {}, new Set(['primChildren'])),
+    rootPrims: roots,
+    layers: []
+  };
+}
+
+/** Converts raw field dictionaries while retaining authored values and time samples. */
+function convertFields(
+  fields: Record<string, unknown>,
+  excluded: Set<string>
+): Record<string, USDValue> {
+  const result: Record<string, USDValue> = Object.create(null);
+  for (const [name, value] of Object.entries(fields))
+    if (!excluded.has(name)) result[name] = convertValue(value);
+  return result;
+}
+
+/** Converts decoded typed arrays to the existing renderer-independent USD value contract. */
+function convertValue(value: unknown): USDValue {
+  if (value === undefined || value === null) return null;
+  if (typeof value === 'number' || typeof value === 'string' || typeof value === 'boolean')
+    return value;
+  if (Array.isArray(value)) return value.map(convertValue);
+  if (ArrayBuffer.isView(value) && !(value instanceof DataView))
+    return Array.from(value as unknown as ArrayLike<number>);
+  if (typeof value === 'object') return convertFields(value as Record<string, unknown>, new Set());
+  throw new Error('USDC: unsupported decoded value');
+}
+
+/** Preserves USDA-compatible asset/path values and vector-array tuple boundaries. */
+function convertAttributeValue(raw: unknown, type: string): USDValue {
+  const value = convertValue(raw);
+  if (type === 'asset' && typeof value === 'string') return {assetPath: value};
+  if (type === 'rel' && Array.isArray(value))
+    return value.map(path => (typeof path === 'string' ? {path} : path));
+  const tuple =
+    /^(?:(?:point|normal|vector|color|texCoord)([234])[fdh]|(?:float|double|half|int)([234]))\[\]$/.exec(
+      type
+    );
+  if (tuple && Array.isArray(value)) {
+    const components = Number(tuple[1] || tuple[2]);
+    if (value.length % components) throw new Error('USDC: incomplete vector tuple');
+    const tuples: USDValue[] = [];
+    for (let offset = 0; offset < value.length; offset += components)
+      tuples.push(value.slice(offset, offset + components));
+    return tuples;
+  }
+  return value;
+}
+
+/** Applies authored child-name order while retaining any other decoded specifications. */
+function orderPrims(prims: USDPrim[], names: unknown): void {
+  if (names === undefined) return;
+  if (!Array.isArray(names)) throw new Error('USDC: invalid primChildren order');
+  const remaining = new Map(prims.map(prim => [prim.name, prim]));
+  const ordered: USDPrim[] = [];
+  for (const name of names) {
+    const prim = typeof name === 'string' ? remaining.get(name) : undefined;
+    if (!prim) throw new Error('USDC: invalid primChildren reference');
+    ordered.push(prim);
+    remaining.delete(name as string);
+  }
+  for (const prim of remaining.values()) ordered.push(prim);
+  for (let index = 0; index < ordered.length; index++) prims[index] = ordered[index];
+}
+
+/** Converts every authored sample through the same type-aware path as an attribute default. */
+function convertTimeSamples(raw: unknown, type: string): USDValue {
+  if (!raw || typeof raw !== 'object') throw new Error('USDC: invalid time samples');
+  const samples = raw as {
+    /** Authored sample coordinates. */
+    times?: unknown;
+    /** Authored sample values before type-aware conversion. */
+    values?: unknown;
+  };
+  const times = convertValue(samples.times);
+  if (
+    !Array.isArray(times) ||
+    !Array.isArray(samples.values) ||
+    times.length !== samples.values.length
+  )
+    throw new Error('USDC: invalid time samples');
+  return {times, values: samples.values.map(value => convertAttributeValue(value, type))};
+}

package/src/{lib → usd/lib}/parse-usdz.ts

@@ -12,20 +12,29 @@ export function parseUSDZArchive(arrayBuffer: ArrayBuffer): Map<string, ArrayBuf
   const directoryOffset = findCentralDirectory(view);
   const entryCount = view.getUint16(directoryOffset + 10, true);
   let entryOffset = view.getUint32(directoryOffset + 16, true);
+  const dataLimit = entryOffset;
   const files = new Map<string, ArrayBuffer>();
   const textDecoder = new TextDecoder();
+  let extractedByteLength = 0;
 
   for (let entryIndex = 0; entryIndex < entryCount; entryIndex++) {
+    if (entryOffset + 46 > directoryOffset) {
+      throw new Error('USDZ archive contains a truncated ZIP central-directory entry.');
+    }
     if (view.getUint32(entryOffset, true) !== CENTRAL_DIRECTORY_ENTRY) {
       throw new Error('USDZ archive contains an invalid ZIP central-directory entry.');
     }
 
     const compression = view.getUint16(entryOffset + 10, true);
     const compressedLength = view.getUint32(entryOffset + 20, true);
+    const uncompressedLength = view.getUint32(entryOffset + 24, true);
     const filenameLength = view.getUint16(entryOffset + 28, true);
     const extraLength = view.getUint16(entryOffset + 30, true);
     const commentLength = view.getUint16(entryOffset + 32, true);
     const localOffset = view.getUint32(entryOffset + 42, true);
+    if (entryOffset + 46 + filenameLength + extraLength + commentLength > directoryOffset) {
+      throw new Error('USDZ archive contains a truncated ZIP filename or extra field.');
+    }
     const filename = textDecoder.decode(
       new Uint8Array(arrayBuffer, entryOffset + 46, filenameLength)
     );
@@ -33,6 +42,9 @@ export function parseUSDZArchive(arrayBuffer: ArrayBuffer): Map<string, ArrayBuf
     if (compression !== 0) {
       throw new Error(`USDZ entry "${filename}" is compressed; USDZ requires stored ZIP entries.`);
     }
+    if (localOffset + 30 > dataLimit || compressedLength !== uncompressedLength) {
+      throw new Error(`USDZ entry "${filename}" has invalid stored ZIP bounds.`);
+    }
     if (view.getUint32(localOffset, true) !== LOCAL_FILE_HEADER) {
       throw new Error(`USDZ entry "${filename}" has an invalid local ZIP header.`);
     }
@@ -40,6 +52,22 @@ export function parseUSDZArchive(arrayBuffer: ArrayBuffer): Map<string, ArrayBuf
     const localNameLength = view.getUint16(localOffset + 26, true);
     const localExtraLength = view.getUint16(localOffset + 28, true);
     const contentOffset = localOffset + 30 + localNameLength + localExtraLength;
+    if ((view.getUint16(entryOffset + 8, true) | view.getUint16(localOffset + 6, true)) & 1) {
+      throw new Error(`USDZ entry "${filename}" is encrypted.`);
+    }
+    if (
+      contentOffset + compressedLength > dataLimit ||
+      view.getUint16(localOffset + 8, true) !== 0 ||
+      textDecoder.decode(new Uint8Array(arrayBuffer, localOffset + 30, localNameLength)) !==
+        filename ||
+      files.has(filename)
+    ) {
+      throw new Error(`USDZ entry "${filename}" has invalid or duplicate stored ZIP data.`);
+    }
+    extractedByteLength += compressedLength;
+    if (extractedByteLength > arrayBuffer.byteLength) {
+      throw new Error('USDZ archive exceeds its stored data budget.');
+    }
     files.set(filename, arrayBuffer.slice(contentOffset, contentOffset + compressedLength));
     entryOffset += 46 + filenameLength + extraLength + commentLength;
   }

package/src/{lib → usd/lib}/usd-types.ts

@@ -1,8 +1,8 @@
-// loaders.gl
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
+// loaders.gl
 
-import type {LoaderOptions} from '@loaders.gl/loader-utils';
+import type {LoaderOptions} from '@loaders.gl/core/loader-utils';
 
 /** Reference to an external OpenUSD layer and optional prim within that layer. */
 export type USDAssetPath = {
@@ -31,6 +31,8 @@ export type USDValue =
 
 /** Parsed OpenUSD attribute declaration. */
 export type USDAttribute = {
+  /** URL of the layer that authored this attribute, retained through composition. */
+  sourceUrl?: string;
   /** Attribute name. */
   name: string;
   /** Authored OpenUSD type name. */
@@ -73,10 +75,20 @@ export type USDPrim = {
   children: USDPrim[];
 };
 
+/** Encoded file extracted from a USDZ package, without image decoding or renderer objects. */
+export type USDEmbeddedAsset = {
+  /** Original archive-relative filename, including its directories. */
+  readonly path: string;
+  /** Exact stored bytes, owned by the returned stage rather than the input archive. */
+  readonly data: ArrayBuffer;
+  /** MIME type hint inferred from a PNG or JPEG filename; other formats omit this field. */
+  readonly mimeType?: string;
+};
+
 /** Parsed OpenUSD stage. */
 export type USDStage = {
   /** Container format used for the root layer. */
-  format: 'usda' | 'usdz';
+  format: 'usda' | 'usdc' | 'usdz';
   /** URL of the root layer when available. */
   url?: string;
   /** Root-layer metadata. */
@@ -85,6 +97,8 @@ export type USDStage = {
   rootPrims: USDPrim[];
   /** URLs of all layers used to compose the stage. */
   layers: string[];
+  /** USDZ files keyed by resolved package URL; absent for standalone layers. Includes layers and textures. */
+  assets?: Record<string, USDEmbeddedAsset>;
 };
 
 /** Options for {@link USDLoader}. */

package/src/usd/libs/README.md

@@ -0,0 +1,27 @@
+# USDC decoder source
+
+`usdc-parser.js` is adapted from THREE.js r187, commit/tag r187:
+https://github.com/mrdoob/three.js/blob/r187/examples/jsm/loaders/usd/USDCParser.js
+
+Copyright © 2010–2026 three.js authors; MIT terms are in THREE-LICENSE.
+This renderer-free source has no imports or package dependencies. It remains
+vendored JavaScript; the adjacent declaration and handwritten parse-usdc.ts
+adapter define the checked TypeScript boundary. Existing libs build/coverage
+policy applies to this vendored decoder; adapter code remains fully instrumented.
+
+Local changes bound aggregate allocations, integer precision and seek offsets,
+support bounded dictionary values and reject unsupported list operations/encoding cases, validate LZ4
+copies, use null-prototype dictionaries and correct signed inline integers.
+The adapter restricts crate versions, validates section bounds, and converts the
+supported specifications into USDStage. Broader upstream behavior is not promised.
+
+Dictionary decoding uses string-table keys and forward offsets to complete value
+representations, retaining false, empty strings, empty dictionaries and asset paths.
+It rejects duplicate/invalid keys, cycles, nesting beyond 64, and unsupported
+complex dictionary value types. These checks extend the r187 source while
+preserving its MIT attribution; no THREE runtime is imported.
+
+The authored-value extension decodes inline half and signed/unsigned 64-bit scalars,
+string arrays, and compressed half/double arrays. Dictionary array support is an
+explicit allowlist; unsupported representations fail before payload decoding.
+Half integer compression uses ties-to-even rounding, and lookup indices are checked.

package/src/usd/libs/THREE-LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright © 2010-2026 three.js authors
+
+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/src/usd/libs/usdc-parser.d.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+/** Typed boundary around the pinned, dependency-free THREE r187 crate decoder. */
+export class USDCParser {
+  /** Decodes binary crate specifications; unsupported value encodings throw. */
+  parseData(buffer: ArrayBuffer): {
+    /** Specifications keyed by absolute Sdf path. */
+    specsByPath: Record<
+      string,
+      {
+        /** SdfSpecType numeric identifier. */
+        specType: number;
+        /** Authored field values before USDStage conversion. */
+        fields: Record<string, unknown>;
+      }
+    >;
+  };
+}