@loaders.gl/scene 5.0.0-beta.2 → 5.0.0-beta.4

package/dist/obj-writer.cjs

@@ -27,7 +27,7 @@ module.exports = __toCommonJS(obj_writer_exports);
 // src/obj/obj-writer.ts
 var import_schema_utils = require("@loaders.gl/core/schema-utils");
 var import_obj_format = require("./obj-format.cjs");
-var VERSION = true ? "5.0.0-beta.2" : "latest";
+var VERSION = true ? "5.0.0-beta.4" : "latest";
 var OBJWriter = {
   ...import_obj_format.OBJFormat,
   dataType: null,

package/dist/usd/usd-loader-types.cjs

@@ -33,7 +33,7 @@ __export(usd_loader_types_exports, {
   USDLoader: () => USDLoader
 });
 module.exports = __toCommonJS(usd_loader_types_exports);
-var VERSION = true ? "5.0.0-beta.2" : "latest";
+var VERSION = true ? "5.0.0-beta.4" : "latest";
 async function preload() {
   const { USDLoaderWithParser } = await import("@loaders.gl/scene/usd-loader");
   return USDLoaderWithParser;

package/dist/usd/usd-loader-types.js

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // __VERSION__ is injected by babel-plugin-version-inline
 // @ts-ignore TS2304: Cannot find name '__VERSION__'.
-const VERSION = typeof "5.0.0-beta.2" !== 'undefined' ? "5.0.0-beta.2" : 'latest';
+const VERSION = typeof "5.0.0-beta.4" !== 'undefined' ? "5.0.0-beta.4" : 'latest';
 /** Loads the parser-bearing USD loader implementation. */
 async function preload() {
     const { USDLoaderWithParser } = await import('@loaders.gl/scene/usd-loader');

package/dist/usd-loader-types.cjs

@@ -35,7 +35,7 @@ __export(usd_loader_types_exports, {
 module.exports = __toCommonJS(usd_loader_types_exports);
 
 // src/usd/usd-loader-types.ts
-var VERSION = true ? "5.0.0-beta.2" : "latest";
+var VERSION = true ? "5.0.0-beta.4" : "latest";
 async function preload() {
   const { USDLoaderWithParser } = await import("@loaders.gl/scene/usd-loader");
   return USDLoaderWithParser;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loaders.gl/scene",
-  "version": "5.0.0-beta.2",
+  "version": "5.0.0-beta.4",
   "description": "glTF, GLB, OBJ, MTL, OpenUSD, and Draco geometry loaders and writers",
   "license": "MIT",
   "type": "module",
@@ -236,6 +236,11 @@
     "./draco-library-options": {
       "types": "./dist/draco-library-options.d.ts",
       "import": "./dist/draco-library-options.js"
+    },
+    "./materialx-loader": {
+      "types": "./dist/materialx-loader.d.ts",
+      "import": "./dist/materialx-loader.js",
+      "require": "./dist/materialx-loader.cjs"
     }
   },
   "sideEffects": false,
@@ -270,9 +275,10 @@
     "@loaders.gl/core": "~5.0.0-alpha.0"
   },
   "dependencies": {
-    "@loaders.gl/images": "5.0.0-beta.2",
-    "@math.gl/core": "5.0.0-beta.2",
-    "@math.gl/geometry": "5.0.0-beta.2",
+    "@loaders.gl/documents": "5.0.0-beta.4",
+    "@loaders.gl/images": "5.0.0-beta.4",
+    "@math.gl/core": "5.0.0-beta.4",
+    "@math.gl/geometry": "5.0.0-beta.4",
     "zod": "^4.1.12"
   },
   "devDependencies": {
@@ -281,5 +287,5 @@
   "optionalDependencies": {
     "draco3d": "1.5.7"
   },
-  "gitHead": "d259e5bc74caf8d75e808314b7fef2fa1bd70ff7"
+  "gitHead": "c9420f06e870fa353889d55b684e3588d24574c2"
 }

package/src/gltf/gltf-loader-types.ts

@@ -22,6 +22,12 @@ export type GLTFLoaderOptions = StrictLoaderOptions &
   GLBLoaderOptions &
   DracoLoaderOptions & {
     gltf?: ParseGLTFOptions;
+    /** Options forwarded to an injected SPZ loader. The source frame is always LUF for glTF. */
+    splats?: {
+      shape?: 'arrow-table';
+      sourceCoordinateSystem?: 'RUB' | 'LUF' | 'RUF' | 'UNSPECIFIED';
+      targetCoordinateSystem?: 'RUB' | 'LUF' | 'RUF' | 'UNSPECIFIED';
+    };
   };
 
 /** Preloads the parser-bearing glTF loader implementation. */

package/src/gltf/index.ts

@@ -29,7 +29,9 @@ export type {
   GLTF_KHR_texture_basisu,
   GLTF_KHR_meshopt_compression,
   GLTF_EXT_meshopt_compression,
-  GLTF_EXT_texture_webp
+  GLTF_EXT_texture_webp,
+  GLTF_EXT_texture_avif,
+  GLTF_MSFT_texture_dds
 } from './lib/types/gltf-json-schema';
 
 export type {GLTFShape, GLTFBoundingVolume} from './lib/types/gltf-shape-schema';
@@ -170,6 +172,7 @@ export {
   GLTFKHRMeshoptCompressionSchema,
   GLTFEXTMeshoptCompressionSchema,
   GLTFEXTTextureWebpSchema,
+  GLTFEXTTextureAvifSchema,
   GLTFMSFTTextureDdsSchema,
   GLTFShapeSchema,
   GLTFBoundingVolumeSchema

package/src/gltf/lib/api/gltf-extensions.ts

@@ -1,3 +1,4 @@
+import * as KHR_accessor_float64 from '../extensions/KHR_accessor_float64';
 // loaders.gl
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
@@ -25,6 +26,7 @@ import * as EXT_meshopt_compression from '../extensions/EXT_meshopt_compression'
 import * as KHR_meshopt_compression from '../extensions/KHR_meshopt_compression';
 import * as EXT_texture_webp from '../extensions/EXT_texture_webp';
 import * as EXT_texture_avif from '../extensions/EXT_texture_avif';
+import * as MSFT_texture_dds from '../extensions/MSFT_texture_dds';
 import * as KHR_texture_basisu from '../extensions/KHR_texture_basisu';
 import * as KHR_draco_mesh_compression from '../extensions/KHR_draco_mesh_compression';
 import * as KHR_texture_transform from '../extensions/KHR_texture_transform';
@@ -60,6 +62,7 @@ type GLTFExtensionPlugin = {
  * These are just extensions that can be handled fully or partially during loading.
  */
 export const EXTENSIONS: GLTFExtensionPlugin[] = [
+  KHR_accessor_float64,
   // 1.0
   // KHR_binary_gltf is handled separately - must be processed before other parsing starts
   // KHR_binary_gltf,
@@ -79,9 +82,11 @@ export const EXTENSIONS: GLTFExtensionPlugin[] = [
   EXT_mesh_polygon,
   MPEG_audio_spatial,
   KHR_audio_emitter,
-  EXT_texture_avif,
   EXT_texture_webp,
-  // Basisu should come after webp, we want basisu to be preferred if both are provided
+  EXT_texture_avif,
+  // Compressed textures take precedence over browser image formats when available.
+  MSFT_texture_dds,
+  // BasisU remains preferred when both compressed alternatives are provided.
   KHR_texture_basisu,
   KHR_lights_punctual,
   KHR_materials_unlit,

package/src/gltf/lib/extensions/EXT_texture_webp.ts

@@ -25,6 +25,9 @@ export const name = EXT_TEXTURE_WEBP;
 export function preprocess(gltfData: GLTFWithBuffers, options: GLTFLoaderOptions): void {
   const iterator = new GLTFIterator(gltfData);
 
+  // Avoid probing image capabilities for unrelated documents, including worker environments.
+  if (!iterator.hasExtension(EXT_TEXTURE_WEBP)) return;
+
   if (!isImageFormatSupported('image/webp')) {
     if (iterator.isExtensionRequired(EXT_TEXTURE_WEBP)) {
       throw new Error(`gltf: Required extension ${EXT_TEXTURE_WEBP} not supported by browser`);

package/src/gltf/lib/extensions/KHR_accessor_float64.ts

@@ -0,0 +1,22 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+import type {GLTFWithBuffers} from '../types/gltf-types';
+
+/** Draft extension enabling binary64 accessor components. */
+export const name = 'KHR_accessor_float64';
+
+/** Validate the declared extension without converting or removing binary64 data. */
+export function preprocess(gltf: GLTFWithBuffers): void {
+  const {json} = gltf;
+  if (!json.extensionsUsed?.includes(name) && !json.extensionsRequired?.includes(name)) return;
+  if (!json.extensionsUsed?.includes(name) || !json.extensionsRequired?.includes(name)) {
+    throw new Error(`${name}: must be declared in extensionsUsed and extensionsRequired.`);
+  }
+  for (const [index, accessor] of (json.accessors || []).entries()) {
+    if (accessor.componentType === 5130 && accessor.normalized) {
+      throw new Error(`${name}: accessor ${index} must not be normalized.`);
+    }
+  }
+}

package/src/gltf/lib/extensions/KHR_gaussian_splatting.ts

@@ -4,6 +4,8 @@
 
 /* eslint-disable camelcase */
 
+import {parseFromContext} from '@loaders.gl/core/loader-utils';
+import type {LoaderContext} from '@loaders.gl/core/loader-utils';
 import type {GLTF, GLTFMeshPrimitive} from '../types/gltf-json-schema';
 import type {GLTFWithBuffers} from '../types/gltf-types';
 import type {GLTFLoaderOptions} from '../../gltf-loader-types';
@@ -28,7 +30,12 @@ const REQUIRED_ATTRIBUTES = [
 ] as const;
 
 /** Validates Gaussian splat primitives while preserving all source JSON. */
-export async function decode(gltfData: GLTFWithBuffers, options: GLTFLoaderOptions): Promise<void> {
+export async function decode(
+  gltfData: GLTFWithBuffers,
+  options: GLTFLoaderOptions,
+  context?: LoaderContext
+): Promise<void> {
+  const loader = context?.loaders?.find(candidate => candidate.extensions?.includes('spz'));
   const descriptors = getGaussianSplatPrimitives(gltfData);
   const iterator = new GLTFIterator(gltfData);
   for (const [meshIndex, mesh] of (gltfData.json.meshes || []).entries()) {
@@ -53,12 +60,19 @@ export async function decode(gltfData: GLTFWithBuffers, options: GLTFLoaderOptio
           const bufferView = gltfData.json.bufferViews?.[compression.bufferView];
           if (bufferView && gltfData.buffers[bufferView.buffer]) {
             descriptor.compressedBytes = getBufferViewBytes(gltfData, compression.bufferView);
-          } else if (decoder) {
+          } else if (decoder || loader) {
             throw new Error(
               `KHR_gaussian_splatting: bufferView ${compression.bufferView} is not loaded for SPZ2 decoding.`
             );
           }
-          if (decoder && descriptor.compressedBytes) {
+          if (loader && context && descriptor.compressedBytes) {
+            descriptor.decoded = await parseFromContext(
+              descriptor.compressedBytes.buffer as ArrayBuffer,
+              loader,
+              {...options, splats: {...options.splats, sourceCoordinateSystem: 'LUF'}},
+              context
+            );
+          } else if (decoder && descriptor.compressedBytes) {
             descriptor.decoded = await decoder(descriptor.compressedBytes.buffer as ArrayBuffer, {
               sourceCoordinateSystem: 'LUF'
             });

package/src/gltf/lib/extensions/MSFT_texture_dds.ts

@@ -0,0 +1,52 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTFLoaderOptions} from '../../gltf-loader-types';
+import type {GLTFWithBuffers} from '../types/gltf-types';
+import type {GLTF_MSFT_texture_dds} from '../types/gltf-json-schema';
+import type {Loader, LoaderContext} from '@loaders.gl/core/loader-utils';
+import {GLTFIterator} from '../api/gltf-iterator';
+
+/** Name of the Microsoft DDS texture extension. */
+export const name = 'MSFT_texture_dds';
+
+/** Finds a DDS-capable loader supplied through the parent loader context. */
+export function getDDSLoader(context?: LoaderContext): Loader | undefined {
+  return context?.loaders?.find(
+    loader => loader.extensions?.includes('dds') || loader.mimeTypes?.includes('image/vnd-ms.dds')
+  );
+}
+
+/** Select DDS sources only when an application supplies a compatible loader. */
+export function preprocess(
+  gltf: GLTFWithBuffers,
+  _options: GLTFLoaderOptions,
+  context?: LoaderContext
+): void {
+  const iterator = new GLTFIterator(gltf);
+  if (!iterator.hasExtension(name)) return;
+  if (!getDDSLoader(context)) {
+    if (iterator.isExtensionRequired(name)) {
+      throw new Error('gltf: Required extension MSFT_texture_dds needs a DDS parser');
+    }
+    return;
+  }
+  for (const texture of iterator.textures) {
+    const extension = iterator.getExtension<GLTF_MSFT_texture_dds>(texture, name);
+    if (extension) texture.source = extension.source;
+  }
+}
+
+/** Remove DDS declarations only after image loading can identify the selected sources. */
+export async function decode(
+  gltf: GLTFWithBuffers,
+  options: GLTFLoaderOptions,
+  context?: LoaderContext
+): Promise<void> {
+  if (!getDDSLoader(context) || options.gltf?.loadImages === false) return;
+  const iterator = new GLTFIterator(gltf);
+  if (!iterator.hasExtension(name)) return;
+  for (const texture of iterator.textures) iterator.removeExtension(texture, name);
+  iterator.removeExtension(name);
+}

package/src/gltf/lib/extensions/utils/3d-tiles-utils.ts

@@ -197,7 +197,11 @@ export function getPrimitiveTextureData(
     const mimeType = json.images?.[imageIndex]?.mimeType;
     const parsedImage = scenegraph.gltf.images?.[imageIndex];
     // Checking for width is to prevent handling Un-processed images (e.g. [analyze] stage, where loadImages option is set to false)
-    if (parsedImage && typeof parsedImage.width !== 'undefined') {
+    if (
+      parsedImage &&
+      typeof parsedImage.width !== 'undefined' &&
+      !('compressed' in parsedImage && parsedImage.compressed)
+    ) {
       const textureData: number[] = [];
       for (let index = 0; index < textureCoordinates.length; index += 2) {
         const value = getImageValueByCoordinates(

package/src/gltf/lib/parsers/parse-gltf.ts

@@ -21,6 +21,7 @@ import {canonicalizeUrl, resolveUrl} from '../gltf-utils/resolve-url';
 import {findGLTFFileIndex, resolveGLTFFile} from '../gltf-utils/resolve-gltf-file';
 import {getTypedArrayForBufferView} from '../gltf-utils/get-typed-array';
 import {preprocessExtensions, decodeExtensions} from '../api/gltf-extensions';
+import {getDDSLoader} from '../extensions/MSFT_texture_dds';
 import {normalizeGLTFV1WithDeferredBuffers} from '../api/normalize-gltf-v1';
 
 /**  */
@@ -542,6 +543,34 @@ async function loadImage(
 
   const gltfOptions = getGLTFImageOptions(options, image.mimeType);
 
+  const ddsLoader = getDDSLoader(context);
+  const ddsSelected = Boolean(
+    ddsLoader &&
+      !options.gltf?.excludeExtensions?.includes('MSFT_texture_dds') &&
+      gltf.json.textures?.some(
+        texture =>
+          texture.source === index && texture.extensions?.MSFT_texture_dds?.source === index
+      )
+  );
+  if (ddsSelected) {
+    const levels = (await parseFromContext(
+      arrayBuffer,
+      ddsLoader!,
+      options,
+      context
+    )) as TextureLevel[];
+    assert(levels.length > 0, 'MSFT_texture_dds parser returned no texture levels');
+    gltf.images = gltf.images || [];
+    gltf.images[index] = {
+      compressed: true,
+      mipmaps: true,
+      width: levels[0].width,
+      height: levels[0].height,
+      data: levels
+    };
+    return;
+  }
+
   // Call `parse`
   let parsedImage = (await parseFromContext(
     arrayBuffer,

package/src/gltf/lib/types/gltf-ext-gaussian-splatting-schema.ts

@@ -41,6 +41,6 @@ export type GLTFGaussianSplatPrimitive = {
   compressedBufferView?: number;
   /** Preserved compressed SPZ2 bytes for native or GPU decoders. */
   compressedBytes?: Uint8Array;
-  /** Result returned by an injected SPZ2 decoder, when one was supplied. */
+  /** Result returned by an injected SPZ loader or legacy decoder, when supplied. */
   decoded?: unknown;
 };

package/src/gltf/lib/types/gltf-texture-procedurals.ts

@@ -0,0 +1,67 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+/** Serialized value types in the experimental procedural graph proposal. */
+export type GLTFProceduralValueType =
+  | 'boolean'
+  | 'float'
+  | 'integer'
+  | 'color3'
+  | 'color4'
+  | 'vector2'
+  | 'vector3'
+  | 'vector4'
+  | 'integer2'
+  | 'integer3'
+  | 'integer4'
+  | 'matrix3x3'
+  | 'matrix4x4'
+  | 'string'
+  | 'filename';
+
+/** Named graph port, retaining serialized connections without evaluating them. */
+export interface GLTFProceduralPort {
+  /** Port category. */
+  nodetype: 'input' | 'output';
+  /** Declared value type. */
+  type: GLTFProceduralValueType;
+  /** Authored constant; scalar numeric arrays are retained as authored. */
+  value?: boolean | string | number | number[];
+  /** Upstream processing node index. */
+  node?: number;
+  /** Name of a graph interface input. */
+  input?: string;
+  /** Name of the selected upstream output. */
+  output?: string;
+}
+
+/** Processing node in a procedural graph. */
+export interface GLTFProceduralNode {
+  /** Optional display name. */
+  name?: string;
+  /** MaterialX or custom node category; unknown categories are retained. */
+  nodetype: string;
+  /** Single output type, or multiple named outputs. */
+  type: GLTFProceduralValueType | 'multioutput';
+  /** Named input ports. */
+  inputs?: Record<string, GLTFProceduralPort>;
+  /** Named output ports. */
+  outputs: Record<string, GLTFProceduralPort>;
+}
+
+/** Flat procedural graph using the draft's named-port representation. */
+export interface GLTFProceduralGraph extends GLTFProceduralNode {
+  /** Graph category. */
+  nodetype: 'nodegraph';
+  /** Processing nodes addressed by index. */
+  nodes: GLTFProceduralNode[];
+}
+
+/** Procedural output attached to a material texture-info object. */
+export interface GLTFProceduralBinding {
+  /** Index into the root extension's procedurals array. */
+  index: number;
+  /** Selected output name; required for graphs with multiple outputs. */
+  output?: string;
+}

package/src/gltf/lib/types/gltf-types.ts

@@ -5,6 +5,7 @@
 /* eslint-disable camelcase */
 
 import {ImageType} from '@loaders.gl/images';
+import type {TextureLevel} from '@loaders.gl/core/schema';
 import type {GLTF} from './gltf-json-schema';
 import type {GLTFGaussianSplatPrimitive} from './gltf-ext-gaussian-splatting-schema';
 import type {GLTFSpatialAudio} from './gltf-mpeg-audio-spatial-schema';
@@ -50,6 +51,13 @@ export type GLTFExternalFile = GLTFExternalBuffer & {
 
 type GLTFExternalImage =
   | ImageType
+  | {
+      compressed: true;
+      mipmaps: true;
+      width: number;
+      height: number;
+      data: TextureLevel[];
+    }
   | {
       compressed: true;
       mipmaps: false;

package/src/gltf/lib/types/gltf-zod-schema.ts

@@ -539,6 +539,11 @@ export const GLTFEXTTextureWebpSchema = z
   .object({source: GLTFIdSchema, extras: z.unknown().optional()})
   .catchall(z.unknown());
 
+/** Zod schema for the EXT_texture_avif texture source extension. */
+export const GLTFEXTTextureAvifSchema = z
+  .object({source: GLTFIdSchema, extras: z.unknown().optional()})
+  .catchall(z.unknown());
+
 /** Zod schema for the MSFT_texture_dds extension. */
 export const GLTFMSFTTextureDdsSchema = z
   .object({source: GLTFIdSchema, extras: z.unknown().optional()})

package/src/gltf/schema.ts

@@ -22,3 +22,4 @@ export {
 export * from './lib/types/gltf-additional-extension-schemas';
 export * from './lib/types/gltf-audio-extension-schemas';
 export * from './lib/types/gltf-extension-schemas';
+export {GLTFEXTTextureAvifSchema} from './lib/types/gltf-zod-schema';

package/src/index.ts

@@ -20,3 +20,6 @@ export {DracoLoader, DracoWorkerLoader} from './draco/draco-loader-types';
 export {DracoFormat} from './draco/draco-format';
 export type * from './draco/index';
 export {DRACO_EXTERNAL_LIBRARIES, DRACO_EXTERNAL_LIBRARY_URLS} from './draco/draco-libraries';
+
+export {MaterialXLoader} from './materialx-loader-types';
+export type {MaterialXDocument, MaterialXElement} from './materialx/parse-materialx';

package/src/materialx/README.md

@@ -0,0 +1,5 @@
+# MaterialX parser
+
+Native XML parsing implementation for browsers and Node.js. `parseMaterialX` returns an ordered element tree retaining string attributes, named connections, custom node categories and unresolved includes. It rejects malformed XML, document types, and missing or unsupported major versions.
+
+This implementation does not resolve libraries, validate MaterialX node signatures, evaluate graphs, or generate shaders. The scene package exports MaterialXLoader with a materialx-loader implementation subpath.

package/src/materialx/parse-materialx.ts

@@ -0,0 +1,70 @@
+import {parseXMLSync} from '@loaders.gl/documents/xml-parser';
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+/** Authored MaterialX element, including extension categories and connection attributes. */
+export interface MaterialXElement {
+  /** XML element category, for example nodegraph, input, or multiply. */
+  category: string;
+  /** Authored string attributes; values are not coerced or evaluated. */
+  attributes: Record<string, string>;
+  /** Child elements in document order. */
+  children: MaterialXElement[];
+}
+
+/** Parsed MaterialX document. External includes remain unresolved. */
+export interface MaterialXDocument {
+  /** Authored MaterialX version. */
+  version: string;
+  /** MaterialX root element. */
+  root: MaterialXElement;
+}
+
+/**
+ * Parses a MaterialX XML document using the native documents XML parser.
+ * Preserves unknown categories, connection references and value strings.
+ * Does not load includes, resolve node definitions, or evaluate shader graphs.
+ */
+export function parseMaterialX(text: string): MaterialXDocument {
+  if (/<!DOCTYPE|<!ENTITY/i.test(text)) {
+    throw new Error('MaterialX: document types and entity declarations are unsupported.');
+  }
+  let element: OrderedXMLElement;
+  try {
+    element = parseXMLSync(text, {
+      preserveOrder: true,
+      parseAttributeValue: false,
+      trimValues: false
+    });
+  } catch (error) {
+    throw new Error('MaterialX: malformed XML.', {cause: error});
+  }
+  if (element.name !== 'materialx') {
+    throw new Error('MaterialX: expected a materialx root element.');
+  }
+  const version = element.attributes.version;
+  if (!version || !/^1\.\d+$/.test(version)) {
+    throw new Error('MaterialX: expected a MaterialX 1.x version.');
+  }
+  return {version, root: parseElement(element, 0)};
+}
+
+/** Ordered element representation returned by the XML parser. */
+interface OrderedXMLElement {
+  /** XML element name. */
+  name: string;
+  /** Authored string attributes. */
+  attributes: Record<string, string>;
+  /** Ordered child elements. */
+  children: OrderedXMLElement[];
+}
+
+/** Converts the native XML tree to MaterialX categories. */
+function parseElement(element: OrderedXMLElement, depth: number): MaterialXElement {
+  return {
+    category: element.name,
+    attributes: element.attributes,
+    children: element.children.map(child => parseElement(child, depth + 1))
+  };
+}

package/src/materialx/procedural-graph.ts

@@ -0,0 +1,94 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+
+/** Typed connection to one node output. */
+export interface ProceduralConnection {
+  /** Stable identifier of the upstream node. */
+  node: string;
+  /** Name of its output port. */
+  output: string;
+}
+
+/** Input supplied by a constant or another node. */
+export interface ProceduralInput {
+  /** Declared value type. */
+  type: string;
+  /** Constant value, retained without implicit conversion. */
+  value?: unknown;
+  /** Optional upstream connection. */
+  connection?: ProceduralConnection;
+}
+
+/** Renderer-independent operation with explicitly declared ports. */
+export interface ProceduralNode {
+  /** Stable node identifier, unique within the graph. */
+  id: string;
+  /** Operation identifier for a downstream implementation registry. */
+  operation: string;
+  /** Named inputs. */
+  inputs: Record<string, ProceduralInput>;
+  /** Named output value types. */
+  outputs: Record<string, string>;
+}
+
+/** Graph contract independent of GPU resources or shader languages. */
+export interface ProceduralGraph {
+  /** Nodes in authored order. */
+  nodes: ProceduralNode[];
+  /** Named graph outputs and their upstream connections. */
+  outputs: Record<string, ProceduralConnection>;
+}
+
+/**
+ * Validates explicit references and exact port types, returning dependency-first nodes.
+ * Does not infer conversions, resolve MaterialX definitions, or evaluate operations.
+ */
+export function orderProceduralGraph(graph: ProceduralGraph): ProceduralNode[] {
+  const nodes = new Map<string, ProceduralNode>();
+  for (const node of graph.nodes) {
+    if (!node.id || nodes.has(node.id))
+      throw new Error('Procedural graph: duplicate or empty node ID.');
+    nodes.set(node.id, node);
+  }
+  const dependencies = new Map<string, Set<string>>();
+  const dependents = new Map<string, string[]>();
+  for (const node of graph.nodes) {
+    const upstream = new Set<string>();
+    for (const input of Object.values(node.inputs)) {
+      if (!input.connection) continue;
+      if (Object.hasOwn(input, 'value'))
+        throw new Error('Procedural graph: connected input also has a value.');
+      const source = resolveOutput(input.connection);
+      if (source.outputs[input.connection.output] !== input.type) {
+        throw new Error('Procedural graph: incompatible connection types.');
+      }
+      upstream.add(source.id);
+    }
+    dependencies.set(node.id, upstream);
+    for (const identifier of upstream) {
+      const downstream = dependents.get(identifier) || [];
+      downstream.push(node.id);
+      dependents.set(identifier, downstream);
+    }
+  }
+  for (const output of Object.values(graph.outputs)) resolveOutput(output);
+  const ordered = graph.nodes.filter(node => dependencies.get(node.id)!.size === 0);
+  for (let index = 0; index < ordered.length; index++) {
+    for (const identifier of dependents.get(ordered[index].id) || []) {
+      const upstream = dependencies.get(identifier)!;
+      upstream.delete(ordered[index].id);
+      if (!upstream.size) ordered.push(nodes.get(identifier)!);
+    }
+  }
+  if (ordered.length !== graph.nodes.length) throw new Error('Procedural graph: cycle detected.');
+  return ordered;
+
+  /** Resolves an explicitly named output without accepting inherited properties. */
+  function resolveOutput(connection: ProceduralConnection): ProceduralNode {
+    const node = nodes.get(connection.node);
+    if (!node || !Object.hasOwn(node.outputs, connection.output)) {
+      throw new Error('Procedural graph: missing node or output.');
+    }
+    return node;
+  }
+}

package/src/materialx-loader-types.ts

@@ -0,0 +1,24 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+import type {MaterialXDocument} from './materialx/parse-materialx';
+
+/** Loads the parser-bearing MaterialX implementation. */
+async function preload() {
+  const {MaterialXLoaderWithParser} = await import('@loaders.gl/scene/materialx-loader');
+  return MaterialXLoaderWithParser;
+}
+
+/** Metadata-only loader for MaterialX XML documents. */
+export const MaterialXLoader = {
+  name: 'MaterialX',
+  id: 'materialx',
+  module: 'scene',
+  version: 'latest',
+  extensions: ['mtlx'],
+  mimeTypes: ['application/xml'],
+  text: true,
+  dataType: null as unknown as MaterialXDocument,
+  batchType: null as never,
+  options: {},
+  preload
+} as const;