@haiyue/extensions 0.1.0

package/src/gltf/GltfExtensionAdapter.ts

@@ -0,0 +1,340 @@
+import type { PbrMaterialState, PbrTextureSlot } from '@haiyue/engine/material';
+import type { GltfAsset, GltfMaterial, GltfPrimitive, GltfTextureInfo } from './GltfSchema';
+
+export type GltfExtensionSupport = 'supported' | 'partial' | 'unsupported';
+
+export interface GltfExtensionCapability {
+  readonly support: GltfExtensionSupport;
+  readonly note: string;
+}
+
+export interface GltfMaterialTextureBinding {
+  readonly slot: PbrTextureSlot;
+  readonly textureInfo: GltfTextureInfo;
+  readonly path: string;
+}
+
+export interface GltfMaterialExtensionContext {
+  readonly gltf: GltfAsset;
+  readonly material: GltfMaterial;
+  readonly primitive: GltfPrimitive;
+  readonly materialPath: string;
+  readonly extensionData: unknown;
+}
+
+export type GltfMaterialStatePatch = Readonly<Partial<Omit<PbrMaterialState,
+  | 'baseColorTexture'
+  | 'metallicRoughnessTexture'
+  | 'normalTexture'
+  | 'occlusionTexture'
+  | 'emissiveTexture'
+  | 'clearcoatTexture'
+  | 'clearcoatRoughnessTexture'
+  | 'clearcoatNormalTexture'
+  | 'specularTexture'
+  | 'specularColorTexture'
+  | 'sheenColorTexture'
+  | 'sheenRoughnessTexture'
+  | 'transmissionTexture'
+  | 'thicknessTexture'
+  | 'textureMappings'
+  | 'samplers'
+  | 'sampler'
+>>>;
+
+export interface GltfMaterialExtensionPatch {
+  /** Pure material parameters. Texture ownership must use `textures`. */
+  readonly state?: GltfMaterialStatePatch;
+  readonly textures?: readonly GltfMaterialTextureBinding[];
+}
+
+export interface GltfMaterialVariantReference {
+  readonly name: string;
+  readonly materialIndex: number;
+}
+
+export interface GltfPrimitiveExtensionContext {
+  readonly gltf: GltfAsset;
+  readonly primitive: GltfPrimitive;
+  readonly rootExtensionData: unknown;
+  readonly primitiveExtensionData: unknown;
+}
+
+/**
+ * A stateless glTF extension adapter. Hooks return declarative patches and
+ * references; resource ownership and concrete material creation stay in the
+ * loader and engine respectively.
+ */
+export interface GltfExtensionAdapter {
+  readonly extension: string;
+  readonly capability: GltfExtensionCapability;
+  readonly extendMaterial?: (context: GltfMaterialExtensionContext) => GltfMaterialExtensionPatch | null;
+  readonly collectMaterialVariantNames?: (gltf: GltfAsset, rootExtensionData: unknown) => readonly string[];
+  readonly collectMaterialVariants?: (context: GltfPrimitiveExtensionContext) => readonly GltfMaterialVariantReference[];
+}
+
+const clearcoatAdapter: GltfExtensionAdapter = Object.freeze({
+  extension: 'KHR_materials_clearcoat',
+  capability: Object.freeze({ support: 'supported', note: 'Imported as a native layered PBR clearcoat lobe.' }),
+  extendMaterial(context: GltfMaterialExtensionContext) {
+    const clearcoat = context.extensionData as NonNullable<GltfMaterial['extensions']>['KHR_materials_clearcoat'];
+    if (!clearcoat) return null;
+    const basePath = `${context.materialPath}.extensions.KHR_materials_clearcoat`;
+    const textures: GltfMaterialTextureBinding[] = [];
+    if (clearcoat.clearcoatTexture) textures.push({
+      slot: 'clearcoat',
+      textureInfo: clearcoat.clearcoatTexture,
+      path: `${basePath}.clearcoatTexture`,
+    });
+    if (clearcoat.clearcoatRoughnessTexture) textures.push({
+      slot: 'clearcoatRoughness',
+      textureInfo: clearcoat.clearcoatRoughnessTexture,
+      path: `${basePath}.clearcoatRoughnessTexture`,
+    });
+    if (clearcoat.clearcoatNormalTexture) textures.push({
+      slot: 'clearcoatNormal',
+      textureInfo: clearcoat.clearcoatNormalTexture,
+      path: `${basePath}.clearcoatNormalTexture`,
+    });
+    return {
+      state: {
+        clearcoatFactor: clearcoat.clearcoatFactor ?? 0,
+        clearcoatRoughnessFactor: clearcoat.clearcoatRoughnessFactor ?? 0,
+        clearcoatNormalScale: clearcoat.clearcoatNormalTexture?.scale ?? 1,
+      },
+      textures: Object.freeze(textures),
+    };
+  },
+});
+
+const iorAdapter: GltfExtensionAdapter = Object.freeze({
+  extension: 'KHR_materials_ior',
+  capability: Object.freeze({ support: 'supported', note: 'Imported into the native dielectric Fresnel IOR parameter.' }),
+  extendMaterial(context: GltfMaterialExtensionContext) {
+    const ior = context.extensionData as NonNullable<GltfMaterial['extensions']>['KHR_materials_ior'];
+    if (!ior) return null;
+    return { state: { ior: ior.ior ?? 1.5 } };
+  },
+});
+
+const specularAdapter: GltfExtensionAdapter = Object.freeze({
+  extension: 'KHR_materials_specular',
+  capability: Object.freeze({ support: 'supported', note: 'Imported into the native dielectric specular BRDF.' }),
+  extendMaterial(context: GltfMaterialExtensionContext) {
+    const specular = context.extensionData as NonNullable<GltfMaterial['extensions']>['KHR_materials_specular'];
+    if (!specular) return null;
+    const basePath = `${context.materialPath}.extensions.KHR_materials_specular`;
+    const textures: GltfMaterialTextureBinding[] = [];
+    if (specular.specularTexture) textures.push({
+      slot: 'specular',
+      textureInfo: specular.specularTexture,
+      path: `${basePath}.specularTexture`,
+    });
+    if (specular.specularColorTexture) textures.push({
+      slot: 'specularColor',
+      textureInfo: specular.specularColorTexture,
+      path: `${basePath}.specularColorTexture`,
+    });
+    return {
+      state: {
+        specularFactor: specular.specularFactor ?? 1,
+        specularColorFactor: specular.specularColorFactor ?? [1, 1, 1],
+      },
+      textures: Object.freeze(textures),
+    };
+  },
+});
+
+const sheenAdapter: GltfExtensionAdapter = Object.freeze({
+  extension: 'KHR_materials_sheen',
+  capability: Object.freeze({ support: 'supported', note: 'Imported as a native Charlie sheen layer with direct-light and IBL energy compensation.' }),
+  extendMaterial(context: GltfMaterialExtensionContext) {
+    const sheen = context.extensionData as NonNullable<GltfMaterial['extensions']>['KHR_materials_sheen'];
+    if (!sheen) return null;
+    const basePath = `${context.materialPath}.extensions.KHR_materials_sheen`;
+    const textures: GltfMaterialTextureBinding[] = [];
+    if (sheen.sheenColorTexture) textures.push({
+      slot: 'sheenColor',
+      textureInfo: sheen.sheenColorTexture,
+      path: `${basePath}.sheenColorTexture`,
+    });
+    if (sheen.sheenRoughnessTexture) textures.push({
+      slot: 'sheenRoughness',
+      textureInfo: sheen.sheenRoughnessTexture,
+      path: `${basePath}.sheenRoughnessTexture`,
+    });
+    return {
+      state: {
+        sheenColorFactor: sheen.sheenColorFactor ?? [0, 0, 0],
+        sheenRoughnessFactor: sheen.sheenRoughnessFactor ?? 0,
+      },
+      textures: Object.freeze(textures),
+    };
+  },
+});
+
+const transmissionAdapter: GltfExtensionAdapter = Object.freeze({
+  extension: 'KHR_materials_transmission',
+  capability: Object.freeze({
+    support: 'supported',
+    note: 'Imported into the native screen-space scene-color path; combined Sheen keeps factor BRDF but omits Sheen texture sampling to stay within the WebGPU minimum binding budget.',
+  }),
+  extendMaterial(context: GltfMaterialExtensionContext) {
+    const transmission = context.extensionData as NonNullable<GltfMaterial['extensions']>['KHR_materials_transmission'];
+    if (!transmission) return null;
+    const basePath = `${context.materialPath}.extensions.KHR_materials_transmission`;
+    return {
+      state: { transmissionFactor: transmission.transmissionFactor ?? 0 },
+      textures: transmission.transmissionTexture ? Object.freeze([{
+        slot: 'transmission' as const,
+        textureInfo: transmission.transmissionTexture,
+        path: `${basePath}.transmissionTexture`,
+      }]) : Object.freeze([]),
+    };
+  },
+});
+
+const volumeAdapter: GltfExtensionAdapter = Object.freeze({
+  extension: 'KHR_materials_volume',
+  capability: Object.freeze({ support: 'supported', note: 'Imported with thickness and Beer-Lambert attenuation in the native transmission path.' }),
+  extendMaterial(context: GltfMaterialExtensionContext) {
+    const volume = context.extensionData as NonNullable<GltfMaterial['extensions']>['KHR_materials_volume'];
+    if (!volume) return null;
+    const basePath = `${context.materialPath}.extensions.KHR_materials_volume`;
+    return {
+      state: {
+        thicknessFactor: volume.thicknessFactor ?? 0,
+        attenuationDistance: volume.attenuationDistance ?? Infinity,
+        attenuationColor: volume.attenuationColor ?? [1, 1, 1],
+      },
+      textures: volume.thicknessTexture ? Object.freeze([{
+        slot: 'thickness' as const,
+        textureInfo: volume.thicknessTexture,
+        path: `${basePath}.thicknessTexture`,
+      }]) : Object.freeze([]),
+    };
+  },
+});
+
+const variantsAdapter: GltfExtensionAdapter = Object.freeze({
+  extension: 'KHR_materials_variants',
+  capability: Object.freeze({ support: 'supported', note: 'Imported as native PBR material variants.' }),
+  collectMaterialVariantNames(gltf: GltfAsset, rootExtensionData: unknown) {
+    void gltf;
+    const definitions = (rootExtensionData as NonNullable<GltfAsset['extensions']>['KHR_materials_variants'])?.variants ?? [];
+    return Object.freeze(definitions.map(variant => variant.name));
+  },
+  collectMaterialVariants(context: GltfPrimitiveExtensionContext) {
+    const definitions = (context.rootExtensionData as NonNullable<GltfAsset['extensions']>['KHR_materials_variants'])?.variants ?? [];
+    const mappings = (context.primitiveExtensionData as NonNullable<GltfPrimitive['extensions']>['KHR_materials_variants'])?.mappings ?? [];
+    const result: GltfMaterialVariantReference[] = [];
+    for (const mapping of mappings) {
+      for (const variantIndex of mapping.variants) {
+        const name = definitions[variantIndex]?.name;
+        if (name) result.push(Object.freeze({ name, materialIndex: mapping.material }));
+      }
+    }
+    return Object.freeze(result);
+  },
+});
+
+function capabilityAdapter(
+  extension: string,
+  support: GltfExtensionSupport,
+  note: string,
+): GltfExtensionAdapter {
+  return Object.freeze({ extension, capability: Object.freeze({ support, note }) });
+}
+
+export const DEFAULT_GLTF_EXTENSION_ADAPTERS: readonly GltfExtensionAdapter[] = Object.freeze([
+  capabilityAdapter('KHR_draco_mesh_compression', 'supported', 'Decoded through the configured Draco decoder.'),
+  variantsAdapter,
+  clearcoatAdapter,
+  iorAdapter,
+  specularAdapter,
+  sheenAdapter,
+  transmissionAdapter,
+  volumeAdapter,
+  capabilityAdapter('KHR_materials_anisotropy', 'partial', 'The base PBR material is imported, but anisotropy shading is not rendered.'),
+  capabilityAdapter('KHR_texture_basisu', 'supported', 'Imported through the KTX2/Basis texture path.'),
+  capabilityAdapter('KHR_texture_transform', 'supported', 'Applied per PBR texture slot in the shader.'),
+]);
+
+/** Resolves an immutable per-load adapter set; user adapters replace defaults by extension id. */
+export function resolveGltfExtensionAdapters(
+  customAdapters: readonly GltfExtensionAdapter[] = [],
+): readonly GltfExtensionAdapter[] {
+  const adapters = new Map(DEFAULT_GLTF_EXTENSION_ADAPTERS.map(adapter => [adapter.extension, adapter]));
+  for (const adapter of customAdapters) {
+    const extension = adapter.extension.trim();
+    if (!extension) throw new TypeError('GltfExtensionAdapter.extension must not be empty.');
+    adapters.set(extension, Object.freeze({
+      ...adapter,
+      extension,
+      capability: Object.freeze({ ...adapter.capability }),
+    }));
+  }
+  return Object.freeze([...adapters.values()]);
+}
+
+export function createGltfExtensionCapabilities(
+  adapters: readonly GltfExtensionAdapter[],
+): Readonly<Record<string, GltfExtensionCapability>> {
+  return Object.freeze(Object.fromEntries(adapters.map(adapter => [adapter.extension, adapter.capability])));
+}
+
+export function collectGltfMaterialExtensionPatches(
+  gltf: GltfAsset,
+  material: GltfMaterial | null,
+  primitive: GltfPrimitive,
+  materialPath: string,
+  adapters: readonly GltfExtensionAdapter[],
+): readonly GltfMaterialExtensionPatch[] {
+  if (!material) return Object.freeze([]);
+  const patches: GltfMaterialExtensionPatch[] = [];
+  for (const adapter of adapters) {
+    if (!adapter.extendMaterial) continue;
+    const extensionData = material.extensions?.[adapter.extension];
+    if (extensionData === undefined) continue;
+    const patch = adapter.extendMaterial({ gltf, material, primitive, materialPath, extensionData });
+    if (patch) patches.push(patch);
+  }
+  return Object.freeze(patches);
+}
+
+export function collectGltfMaterialVariantReferences(
+  gltf: GltfAsset,
+  primitive: GltfPrimitive,
+  adapters: readonly GltfExtensionAdapter[],
+): readonly GltfMaterialVariantReference[] {
+  const result: GltfMaterialVariantReference[] = [];
+  for (const adapter of adapters) {
+    if (!adapter.collectMaterialVariants) continue;
+    const rootExtensionData = gltf.extensions?.[adapter.extension];
+    const primitiveExtensionData = primitive.extensions?.[adapter.extension];
+    if (rootExtensionData === undefined && primitiveExtensionData === undefined) continue;
+    result.push(...adapter.collectMaterialVariants({ gltf, primitive, rootExtensionData, primitiveExtensionData }));
+  }
+  return Object.freeze(result);
+}
+
+export function collectGltfMaterialVariantNames(
+  gltf: GltfAsset,
+  adapters: readonly GltfExtensionAdapter[],
+): readonly string[] {
+  const names = new Set<string>();
+  for (const adapter of adapters) {
+    if (!adapter.collectMaterialVariantNames) continue;
+    const rootExtensionData = gltf.extensions?.[adapter.extension];
+    if (rootExtensionData === undefined) continue;
+    for (const name of adapter.collectMaterialVariantNames(gltf, rootExtensionData)) {
+      if (name) names.add(name);
+    }
+  }
+  for (const mesh of gltf.meshes ?? []) {
+    for (const primitive of mesh.primitives) {
+      for (const variant of collectGltfMaterialVariantReferences(gltf, primitive, adapters)) names.add(variant.name);
+    }
+  }
+  return Object.freeze([...names]);
+}

package/src/gltf/GltfLoaderContract.ts

@@ -0,0 +1,333 @@
+import type { AssetHandle, AssetManager } from '@haiyue/engine/assets';
+import type { Entity, Geometry3D } from '@haiyue/engine';
+import type { Transform3D } from '@haiyue/engine/components';
+import {
+  isGltfAsset,
+  isRecord,
+  type GltfAnimationInterpolation,
+  type GltfAsset,
+} from './GltfSchema';
+import {
+  DEFAULT_GLTF_EXTENSION_ADAPTERS,
+  createGltfExtensionCapabilities,
+  type GltfExtensionAdapter,
+  type GltfExtensionCapability,
+} from './GltfExtensionAdapter';
+import type {
+  GltfCompatibilityExtensionEntry,
+  GltfCompatibilityReport,
+  GltfPrimitiveCompatibilityInput,
+} from './GltfCompatibilityReport';
+
+export type {
+  GltfCompatibilityExtensionEntry,
+  GltfCompatibilityIssue,
+  GltfCompatibilityPerformanceSummary,
+  GltfCompatibilityReport,
+  GltfCompatibilityStatus,
+  GltfPrimitiveBoundsCompatibilityEntry,
+  GltfPrimitiveBoundsSupport,
+  GltfPrimitiveUvSemanticCompatibilityEntry,
+  GltfTextureCompatibilityEntry,
+  GltfTextureMipmapSource,
+} from './GltfCompatibilityReport';
+export type { GltfAnimationInterpolation } from './GltfSchema';
+export type {
+  GltfExtensionAdapter,
+  GltfExtensionCapability,
+  GltfExtensionSupport,
+} from './GltfExtensionAdapter';
+
+export interface LoadedGltfModel {
+  root: Entity;
+  animations: GltfAnimationInfo[];
+  animationClips: GltfAnimationClip[];
+  assetStats: GltfAssetStats;
+  loadMetrics: GltfLoadMetrics;
+  objectUrls: string[];
+  assetHandles: AssetHandle<unknown>[];
+  materialVariants: readonly string[];
+  warnings: readonly GltfLoadWarning[];
+  extensionReport: GltfExtensionReport;
+  compatibilityReport: GltfCompatibilityReport;
+}
+
+export type GltfExtensionReportEntry = GltfCompatibilityExtensionEntry;
+
+export interface GltfExtensionReport {
+  readonly fullySupported: boolean;
+  readonly entries: readonly GltfExtensionReportEntry[];
+}
+
+export const GLTF_EXTENSION_CAPABILITIES: Readonly<Record<string, GltfExtensionCapability>> =
+  createGltfExtensionCapabilities(DEFAULT_GLTF_EXTENSION_ADAPTERS);
+
+export interface GltfLoadWarning {
+  readonly code: 'W_GLTF_PARTIAL_OPTIONAL_EXTENSION' | 'W_GLTF_UNSUPPORTED_OPTIONAL_EXTENSION';
+  readonly message: string;
+  readonly extension: string;
+  readonly path: string;
+}
+
+export interface GltfAnimationInfo {
+  name: string;
+  duration: number;
+  channelCount: number;
+}
+
+export type GltfAnimationPath = 'translation' | 'rotation' | 'scale' | 'weights';
+
+export interface GltfAnimationTarget {
+  entity: Entity;
+  transform: Transform3D;
+  translation: [number, number, number];
+  rotation: [number, number, number, number];
+  scale: [number, number, number];
+  weights: number[];
+  morphPrimitives: GltfMorphPrimitiveRuntime[];
+}
+
+export interface GltfMorphPrimitiveRuntime {
+  geometry: Geometry3D;
+  basePositions: Float32Array;
+  baseNormals: Float32Array | null;
+  positionTargets: Float32Array[];
+  normalTargets: Float32Array[];
+}
+
+export interface GltfAnimationChannelRuntime {
+  target: GltfAnimationTarget;
+  path: GltfAnimationPath;
+  interpolation: GltfAnimationInterpolation;
+  valueSize: number;
+  input: Float32Array;
+  output: Float32Array;
+  sampleA: Float32Array;
+  sampleB: Float32Array;
+  sampleOut: Float32Array;
+  quatScratch: Float32Array;
+}
+
+export interface GltfAnimationClip {
+  name: string;
+  duration: number;
+  channels: GltfAnimationChannelRuntime[];
+  skinnedPrimitives: GltfSkinnedPrimitiveRuntime[];
+  stateCache: Map<GltfAnimationTarget, GltfAnimationTargetState>;
+  activeStates: GltfAnimationTargetState[];
+}
+
+export interface GltfAnimationTargetState {
+  target: GltfAnimationTarget;
+  translation: Float32Array;
+  rotation: Float32Array;
+  scale: Float32Array;
+  matrix: Float32Array<ArrayBuffer>;
+  active: boolean;
+}
+
+export interface GltfAssetStats {
+  meshCount: number;
+  primitiveCount: number;
+  materialCount: number;
+  textureCount: number;
+  imageCount: number;
+  animationCount: number;
+}
+
+export interface GltfLoadPhaseTimings {
+  readonly fetchMs: number;
+  readonly workerParseMs: number;
+  readonly dracoDecodeMs: number;
+  readonly geometryPreparationMs: number;
+  readonly instantiateMs: number;
+  readonly textureDecodeTranscodeUploadMs: number;
+  readonly totalMs: number;
+}
+
+export interface GltfLoadMetrics {
+  readonly timings: GltfLoadPhaseTimings;
+  readonly sourceBytes: number;
+  readonly decodedGeometryBytes: number;
+  readonly workerTransferBytes: number;
+  readonly workerTransferBufferCount: number;
+}
+
+export interface GltfLoadDiagnostics {
+  onDracoDecode?(durationMs: number, decodedBytes: number): void;
+}
+
+export interface LoadGltfOptions {
+  scene?: number | null;
+  baseColorFactor?: [number, number, number, number];
+  dracoDecoder?: DracoDecoderModule | Promise<DracoDecoderModule> | DracoDecoderFactory | null;
+  dracoDecoderConfig?: DracoDecoderConfig;
+  assetManager?: AssetManager | null;
+  assetWorker?: GltfAssetWorker | null;
+  signal?: AbortSignal;
+  onWarning?: (warning: GltfLoadWarning) => void;
+  diagnostics?: GltfLoadDiagnostics;
+  extensionAdapters?: readonly GltfExtensionAdapter[];
+}
+
+export interface GltfAssetWorker {
+  loadParsedAsset(src: string, options?: { signal?: AbortSignal; dracoDecoderConfig?: DracoDecoderConfig }): Promise<GltfParsedAsset>;
+}
+
+export interface GltfParsedAsset {
+  gltf: GltfAsset;
+  binaryChunk: ArrayBuffer | null;
+  buffers: ArrayBuffer[];
+  baseUrl: string;
+  geometryPayloads?: GltfGeometryPayloadMatrix;
+  metrics?: GltfParsedAssetMetrics;
+}
+
+export interface GltfParsedAssetMetrics {
+  readonly fetchMs: number;
+  readonly parseMs: number;
+  readonly workerParseMs: number;
+  readonly dracoDecodeMs: number;
+  readonly geometryPreparationMs: number;
+  readonly sourceBytes: number;
+  readonly workerTransferBytes: number;
+  readonly workerTransferBufferCount: number;
+}
+
+export function isGltfParsedAsset(value: unknown): value is GltfParsedAsset {
+  if (!isRecord(value)) return false;
+  if (!isGltfAsset(value.gltf)) return false;
+  if (!(value.binaryChunk === null || value.binaryChunk instanceof ArrayBuffer)) return false;
+  if (!Array.isArray(value.buffers) || !value.buffers.every(buffer => buffer instanceof ArrayBuffer)) return false;
+  if (typeof value.baseUrl !== 'string') return false;
+  if (value.geometryPayloads !== undefined && !isGeometryPayloadMatrix(value.geometryPayloads)) return false;
+  return value.metrics === undefined || isParsedAssetMetrics(value.metrics);
+}
+
+export type GltfGeometryPayloadMatrix = Array<Array<GltfPrimitiveGeometryPayload | null>>;
+
+export interface GltfPrimitiveGeometryPayload {
+  positions: Float32Array;
+  indices?: Uint16Array | Uint32Array;
+  normals?: Float32Array;
+  textureCoordinates: Array<{ set: number; data: Float32Array }>;
+  joints?: Uint16Array | Uint32Array;
+  weights?: Float32Array;
+  positionTargets: Float32Array[];
+  normalTargets: Float32Array[];
+}
+
+export interface DracoDecoderConfig {
+  scriptUrl?: string;
+  locateFile?: (path: string, prefix: string) => string;
+  wasmBinary?: ArrayBuffer | Uint8Array;
+}
+
+export interface DracoDecoderArray {
+  GetValue(index: number): number;
+  size(): number;
+}
+
+export interface DracoPointAttribute { size(): number; }
+export interface DracoStatus { ok(): boolean; error_msg(): string; }
+export interface DracoMesh { num_faces(): number; num_points(): number; }
+
+export interface DracoDecoder {
+  DecodeBufferToMesh(buffer: unknown, mesh: DracoMesh): DracoStatus;
+  GetAttributeByUniqueId(mesh: DracoMesh, uniqueId: number): DracoPointAttribute;
+  GetAttributeFloatForAllPoints(mesh: DracoMesh, attribute: DracoPointAttribute, out: DracoDecoderArray): boolean;
+  GetAttributeUInt16ForAllPoints?(mesh: DracoMesh, attribute: DracoPointAttribute, out: DracoDecoderArray): boolean;
+  GetAttributeUInt32ForAllPoints?(mesh: DracoMesh, attribute: DracoPointAttribute, out: DracoDecoderArray): boolean;
+  GetFaceFromMesh(mesh: DracoMesh, faceIndex: number, out: DracoDecoderArray): boolean;
+}
+
+export interface DracoDecoderModule {
+  Decoder: new () => DracoDecoder;
+  DecoderBuffer: new () => { Init(data: Uint8Array, byteLength: number): void };
+  Mesh: new () => DracoMesh;
+  DracoFloat32Array: new () => DracoDecoderArray;
+  DracoUInt16Array?: new () => DracoDecoderArray;
+  DracoUInt32Array?: new () => DracoDecoderArray;
+  DracoInt32Array: new () => DracoDecoderArray;
+  destroy(object: unknown): void;
+}
+
+export type DracoDecoderFactory = (config?: DracoDecoderConfig) => Promise<DracoDecoderModule> | DracoDecoderModule;
+
+export interface DracoPrimitiveGeometry {
+  positions: Float32Array;
+  normals?: Float32Array;
+  textureCoordinates: Array<{ set: number; data: Float32Array }>;
+  joints?: Uint16Array | Uint32Array;
+  weights?: Float32Array;
+  indices: Uint16Array | Uint32Array;
+}
+
+export interface GltfLoadContext {
+  baseUrl: string;
+  assetIdentity: string;
+  objectUrls: string[];
+  imageSources: Map<number, string>;
+  sharedImageSources: boolean;
+  preloadedTextures: Map<string, GPUTexture>;
+  animationTargets: Map<number, GltfAnimationTarget>;
+  skinnedPrimitives: GltfSkinnedPrimitiveRuntime[];
+  pendingSkinnedPrimitives: GltfPendingSkinnedPrimitive[];
+  assetHandles: AssetHandle<unknown>[];
+  geometryPayloads?: GltfGeometryPayloadMatrix;
+  compatibilityPrimitives: GltfPrimitiveCompatibilityInput[];
+  extensionAdapters: readonly GltfExtensionAdapter[];
+}
+
+export interface GltfPendingSkinnedPrimitive {
+  skinIndex: number;
+  geometry: Geometry3D;
+  meshEntity: Entity;
+  joints: Uint16Array | Uint32Array;
+  weights: Float32Array;
+}
+
+export interface GltfSkinnedPrimitiveRuntime {
+  geometry: Geometry3D;
+  meshEntity: Entity;
+  jointTargets: Array<GltfAnimationTarget | null>;
+  inverseBindMatrices: Float32Array[];
+  jointMatrices: Float32Array;
+  inverseMeshWorldScratch: Float32Array;
+  jointMatrixScratch: Float32Array;
+  skinMatrixScratch: Float32Array;
+  lastMeshWorldVersion: number;
+  lastGeometryVersion: number;
+  lastJointWorldVersions: Int32Array;
+}
+
+function isGeometryPayloadMatrix(value: unknown): value is GltfGeometryPayloadMatrix {
+  return Array.isArray(value) && value.every(mesh => Array.isArray(mesh) && mesh.every(payload => {
+    if (payload === null) return true;
+    if (!isRecord(payload) || !(payload.positions instanceof Float32Array)) return false;
+    if (payload.indices !== undefined && !(payload.indices instanceof Uint16Array) && !(payload.indices instanceof Uint32Array)) return false;
+    if (payload.normals !== undefined && !(payload.normals instanceof Float32Array)) return false;
+    if (!Array.isArray(payload.textureCoordinates)
+      || !payload.textureCoordinates.every(entry => isRecord(entry)
+        && typeof entry.set === 'number'
+        && Number.isInteger(entry.set)
+        && entry.set >= 0
+        && entry.data instanceof Float32Array)) return false;
+    if (!Array.isArray(payload.positionTargets) || !payload.positionTargets.every(target => target instanceof Float32Array)) return false;
+    return Array.isArray(payload.normalTargets) && payload.normalTargets.every(target => target instanceof Float32Array);
+  }));
+}
+
+function isParsedAssetMetrics(value: unknown): value is GltfParsedAssetMetrics {
+  if (!isRecord(value)) return false;
+  return [
+    'fetchMs',
+    'parseMs',
+    'workerParseMs',
+    'dracoDecodeMs',
+    'geometryPreparationMs',
+    'sourceBytes',
+    'workerTransferBytes',
+    'workerTransferBufferCount',
+  ].every(key => typeof value[key] === 'number' && Number.isFinite(value[key]) && value[key] >= 0);
+}