@forgeax/engine-gltf 0.0.0-dev.8d955ade1c79

package/src/parse-gltf.ts

@@ -0,0 +1,1731 @@
+// parse-gltf.ts - JSON-side glTF importer entry (w17).
+//
+// w17 lands the full parseGltf main function plus parseGlb / toAssetPack
+// siblings. The helpers exported here include both the surface API
+// (parseGltf / parseGlb / toAssetPack) and a few mesh / scene utilities
+// the main path uses internally.
+
+import { mat4, quat, vec3 } from '@forgeax/engine-math';
+import {
+  IMPORT_ERROR_HINTS,
+  ImportError,
+  MESH_MATERIAL_SLOT_SOURCE_OVERRIDE_PAYLOAD_SCHEMA,
+  type MeshMaterialSlotTopologyEntry,
+  reconcileMeshMaterialSlotTopology,
+} from '@forgeax/engine-types';
+import {
+  type AccessorJson,
+  type BufferViewJson,
+  COMPONENT_TYPE,
+  decodeAccessor,
+} from './accessor/decode-accessor.js';
+import { decodeColorAccessor } from './accessor/decode-color.js';
+import { checkExtensions, type GltfExtensionsJson } from './check-extensions.js';
+import { Base64DecodeError, dataUriBase64Payload, decodeBase64 } from './data-uri.js';
+import { err, type GltfError, gltfErr, ok, type Result } from './errors.js';
+import {
+  type GltfBufferViewDecodeCapability,
+  type MeshoptBufferViewJson,
+  projectMeshoptBufferViews,
+} from './meshopt-decode.js';
+import { type GltfAnimationClipRecord, parseAnimation } from './parse-animation.js';
+import { parseGlbChunks } from './parse-glb-chunks.js';
+import { parseGltfHeader } from './parse-gltf-header.js';
+import { type GltfSkeletonRecord, parseSkin } from './parse-skin.js';
+import {
+  type GltfDocItem,
+  type GltfMetaJson,
+  type GltfSubAssetEntry,
+  reimportReuseMeta,
+} from './reimport-reuse-meta.js';
+import type { GltfSourceKeyError } from './source-key.js';
+import { type DecomposedTransform, decomposeNodeTransform } from './transform.js';
+
+export interface MeshPrimitiveJson {
+  readonly attributes?: Record<string, number>;
+  readonly indices?: number;
+  readonly material?: number;
+  readonly mode?: number;
+  readonly targets?: ReadonlyArray<Record<string, number>>;
+}
+
+export interface MeshJson {
+  readonly name?: string;
+  readonly weights?: readonly number[];
+  readonly primitives: readonly MeshPrimitiveJson[];
+}
+
+// === Tier-B v1 IR (GltfDoc) ===
+//
+// Shape: a denormalised view of the parsed glTF JSON, post-validation,
+// suitable for downstream `toAssetPack` and runtime AssetRegistry
+// hand-off. Math types are POD (number tuples), no Vec3/Quat brand at
+// the boundary (charter proposition 5).
+
+interface InstancingAttributes {
+  readonly TRANSLATION?: number;
+  readonly ROTATION?: number;
+  readonly SCALE?: number;
+}
+
+/**
+ * Decode EXT_mesh_gpu_instancing attributes for a single node.
+ *
+ * Cross-validates that all present TRS accessor counts agree (spec
+ * MUST clause "Extending nodes with instance attributes"). Missing
+ * accessors fall back to identity (translation=(0,0,0),
+ * rotation=(0,0,0,1), scale=(1,1,1)). Composes N column-major mat4 via
+ * @forgeax/engine-math `mat4.compose`, packing them into a single
+ * Float32Array of length N*16. Pure function: no fs / fetch / throw.
+ */
+function decodeNodeInstancing(
+  nodeIndex: number,
+  attributes: InstancingAttributes,
+  accessors: readonly AccessorJson[],
+  bufferViews: readonly BufferViewJson[],
+  buffers: readonly Uint8Array[],
+): Result<NodeInstancingIr, GltfError> {
+  const tIdx = attributes.TRANSLATION;
+  const rIdx = attributes.ROTATION;
+  const sIdx = attributes.SCALE;
+
+  let count: number | undefined;
+  const setOrCheck = (label: 'TRANSLATION' | 'ROTATION' | 'SCALE', n: number): GltfError | null => {
+    if (count === undefined) {
+      count = n;
+      return null;
+    }
+    if (n !== count) {
+      return gltfErr('gltf-instancing-count-mismatch', {
+        nodeIndex,
+        accessor: label,
+        expectedCount: count,
+        actualCount: n,
+      });
+    }
+    return null;
+  };
+
+  let tValues: Float32Array | undefined;
+  if (tIdx !== undefined) {
+    const acc = accessors[tIdx];
+    if (acc === undefined) return err(unknownAccessor(tIdx));
+    const e = setOrCheck('TRANSLATION', acc.count);
+    if (e !== null) return err(e);
+    const decoded = decodeAttributeAccessor(tIdx, acc, bufferViews, buffers);
+    if (!decoded.ok) return err(decoded.error);
+    tValues = decoded.value;
+  }
+  let rValues: Float32Array | undefined;
+  if (rIdx !== undefined) {
+    const acc = accessors[rIdx];
+    if (acc === undefined) return err(unknownAccessor(rIdx));
+    const e = setOrCheck('ROTATION', acc.count);
+    if (e !== null) return err(e);
+    const decoded = decodeAttributeAccessor(rIdx, acc, bufferViews, buffers);
+    if (!decoded.ok) return err(decoded.error);
+    rValues = decoded.value;
+  }
+  let sValues: Float32Array | undefined;
+  if (sIdx !== undefined) {
+    const acc = accessors[sIdx];
+    if (acc === undefined) return err(unknownAccessor(sIdx));
+    const e = setOrCheck('SCALE', acc.count);
+    if (e !== null) return err(e);
+    const decoded = decodeAttributeAccessor(sIdx, acc, bufferViews, buffers);
+    if (!decoded.ok) return err(decoded.error);
+    sValues = decoded.value;
+  }
+
+  const n = count ?? 0;
+  const transforms = new Float32Array(n * 16);
+  const tmp = mat4.create();
+  const tv = vec3.create();
+  const rv = quat.create();
+  rv[3] = 1;
+  const sv = vec3.create(1, 1, 1);
+  for (let i = 0; i < n; i++) {
+    if (tValues !== undefined) {
+      tv[0] = tValues[i * 3] ?? 0;
+      tv[1] = tValues[i * 3 + 1] ?? 0;
+      tv[2] = tValues[i * 3 + 2] ?? 0;
+    } else {
+      tv[0] = 0;
+      tv[1] = 0;
+      tv[2] = 0;
+    }
+    if (rValues !== undefined) {
+      rv[0] = rValues[i * 4] ?? 0;
+      rv[1] = rValues[i * 4 + 1] ?? 0;
+      rv[2] = rValues[i * 4 + 2] ?? 0;
+      rv[3] = rValues[i * 4 + 3] ?? 1;
+    } else {
+      rv[0] = 0;
+      rv[1] = 0;
+      rv[2] = 0;
+      rv[3] = 1;
+    }
+    if (sValues !== undefined) {
+      sv[0] = sValues[i * 3] ?? 1;
+      sv[1] = sValues[i * 3 + 1] ?? 1;
+      sv[2] = sValues[i * 3 + 2] ?? 1;
+    } else {
+      sv[0] = 1;
+      sv[1] = 1;
+      sv[2] = 1;
+    }
+    mat4.compose(tmp, tv, rv, sv);
+    for (let k = 0; k < 16; k++) {
+      transforms[i * 16 + k] = tmp[k] ?? 0;
+    }
+  }
+
+  return ok({ count: n, transforms });
+}
+
+function unknownAccessor(accessorIndex: number): GltfError {
+  return gltfErr('gltf-accessor-type-mismatch', {
+    accessorIndex,
+    reason: 'unknownComponentType',
+  });
+}
+
+function decodeAttributeAccessor(
+  accessorIndex: number,
+  accessor: AccessorJson,
+  bufferViews: readonly BufferViewJson[],
+  buffers: readonly Uint8Array[],
+): Result<Float32Array, GltfError> {
+  const view = bufferViews[accessor.bufferView ?? -1];
+  if (view === undefined) return err(unknownAccessor(accessorIndex));
+  const buf = buffers[view.buffer];
+  if (buf === undefined) return err(unknownAccessor(accessorIndex));
+  const decoded = decodeAccessor({
+    accessorIndex,
+    accessor,
+    bufferView: view,
+    buffer: buf,
+    role: 'attribute',
+  });
+  if (!decoded.ok) return err(decoded.error);
+  if (decoded.value.kind !== 'f32') return err(unknownAccessor(accessorIndex));
+  return ok(decoded.value.data);
+}
+
+export interface GltfMeshIr {
+  readonly name?: string;
+  readonly positions: Float32Array;
+  readonly normals?: Float32Array;
+  readonly texcoord0?: Float32Array;
+  /** TEXCOORD_1 per-vertex UV set 1 (Float32Array, 2 per vertex). feat-20260629-multi-uv-set-support m1-w2. */
+  readonly texcoord1?: Float32Array;
+  /** TEXCOORD_2 per-vertex UV set 2 (Float32Array, 2 per vertex). */
+  readonly texcoord2?: Float32Array;
+  /** TEXCOORD_3 per-vertex UV set 3 (Float32Array, 2 per vertex). */
+  readonly texcoord3?: Float32Array;
+  /** TEXCOORD_4 per-vertex UV set 4 (Float32Array, 2 per vertex). */
+  readonly texcoord4?: Float32Array;
+  /** TEXCOORD_5 per-vertex UV set 5 (Float32Array, 2 per vertex). */
+  readonly texcoord5?: Float32Array;
+  /** TEXCOORD_6 per-vertex UV set 6 (Float32Array, 2 per vertex). */
+  readonly texcoord6?: Float32Array;
+  /** TEXCOORD_7 per-vertex UV set 7 (Float32Array, 2 per vertex). */
+  readonly texcoord7?: Float32Array;
+  readonly tangents?: Float32Array;
+  /** COLOR_0 importer carrier; bridge projects it to the canonical color attribute. */
+  readonly colors0?: Float32Array;
+  /** JOINTS_0 per-vertex joint indices (Uint16Array, 4 per vertex). UBYTE source is width-converted to U16 at parse time (D-3). */
+  readonly joints0?: Uint16Array;
+  /** WEIGHTS_0 per-vertex skin weights (Float32Array, 4 per vertex). */
+  readonly weights0?: Float32Array;
+  readonly morphTargets?: readonly {
+    readonly position?: Float32Array;
+    readonly normal?: Float32Array;
+    readonly tangent?: Float32Array;
+  }[];
+  readonly morphWeights?: Float32Array;
+  /**
+   * Optional per-glTF-spec: when omitted, primitive declares non-indexed
+   * geometry (vertex buffer is consumed in vertex order, every 3 verts =
+   * 1 triangle for triangle-list). bridge.ts handles undefined by routing
+   * MeshAsset.indices to undefined and submesh.indexCount=0 (vertexCount
+   * carries the draw count for `pass.draw(vertexCount)`).
+   * bug-20260612 hello-skin visual layered gate: prior shape coerced
+   * undefined into Uint16Array(0) and tripped MeshAsset.indices !==
+   * undefined branches downstream into drawIndexed(0).
+   * U16 (incl. widened U8) or U32 — width preserved from the source accessor;
+   * bridge.ts narrows U32 to U16 when the merged maxIndex fits.
+   */
+  readonly indices?: Uint16Array | Uint32Array;
+  readonly materialIndex: number | null;
+  /**
+   * Owning glTF mesh index in the original document (`gltf.meshes[meshIndex]`).
+   * After OOS-7 flattening, multiple GltfMeshIr entries may share the same
+   * meshIndex (one per primitive). Bridge layer uses this to filter material
+   * collection per node, fixing the verify-r1 charter-defect where multi
+   * glTF-mesh documents would silently misalign materials across nodes.
+   */
+  readonly meshIndex: number;
+}
+
+export interface GltfTextureIr {
+  readonly sampler?: number;
+  readonly source: number;
+  readonly name?: string;
+}
+
+export interface GltfTextureTransformIr {
+  readonly offset?: readonly [number, number];
+  readonly rotation?: number;
+  readonly scale?: readonly [number, number];
+}
+
+export interface GltfTextureInfoIr {
+  readonly texture: number;
+  readonly sampler?: number;
+  readonly texCoord?: number;
+  readonly transform?: GltfTextureTransformIr;
+}
+
+export interface GltfNormalTextureInfoIr extends GltfTextureInfoIr {
+  readonly scale?: number;
+}
+
+export interface GltfOcclusionTextureInfoIr extends GltfTextureInfoIr {
+  readonly strength?: number;
+}
+
+export interface GltfImageIr {
+  readonly uri?: string;
+  readonly mimeType?: string;
+  readonly bufferView?: number;
+  readonly name?: string;
+}
+
+export interface GltfSamplerIr {
+  readonly magFilter?: number;
+  readonly minFilter?: number;
+  readonly wrapS: number;
+  readonly wrapT: number;
+  readonly name?: string;
+}
+
+export interface GltfMaterialIr {
+  readonly name?: string;
+  readonly baseColorFactor: readonly [number, number, number, number];
+  /** glTF emissiveFactor; omitted means the glTF default [0, 0, 0]. */
+  readonly emissiveFactor?: readonly [number, number, number];
+  readonly baseColorTexture?: GltfTextureInfoIr | number;
+  /** Texture binding for the emissive map. */
+  readonly emissiveTexture?: GltfTextureInfoIr | number;
+  readonly metallicFactor: number;
+  readonly roughnessFactor: number;
+  readonly metallicRoughnessTexture?: GltfTextureInfoIr | number;
+  readonly normalTexture?: GltfNormalTextureInfoIr | number;
+  readonly occlusionTexture?: GltfOcclusionTextureInfoIr | number;
+  /**
+   * glTF `alphaMode` (`'OPAQUE'` | `'MASK'` | `'BLEND'`). Absent -> `'OPAQUE'`
+   * (glTF spec default). Drives the bridge's transparent / alpha-test routing.
+   */
+  readonly alphaMode?: 'OPAQUE' | 'MASK' | 'BLEND';
+  /** glTF `alphaCutoff` (MASK-mode threshold; glTF spec default 0.5). */
+  readonly alphaCutoff?: number;
+  /**
+   * glTF `doubleSided`. Absent -> false (the glTF spec default). The bridge
+   * maps this to a no-cull material pass so reverse-facing glass and cards
+   * remain visible without changing their authored winding.
+   */
+  readonly doubleSided?: boolean;
+  /**
+   * baseColorTexture UV-set index (glTF `baseColorTexture.texCoord`). Absent
+   * -> 0. Selects which interleaved UV set the base-color sampler reads.
+   */
+  readonly baseColorTexCoord?: number;
+}
+
+export interface NodeInstancingIr {
+  /** Number of instances. All TRS attribute accessors share this count. */
+  readonly count: number;
+  /** N column-major mat4 transforms packed into one Float32Array (length = N*16). */
+  readonly transforms: Float32Array;
+}
+
+export type GltfPunctualLightType = 'directional' | 'point' | 'spot';
+
+export interface GltfPunctualLightIr {
+  readonly type: GltfPunctualLightType;
+  readonly color: readonly [number, number, number];
+  readonly intensity: number;
+  readonly range?: number;
+  readonly spot?: {
+    readonly innerConeAngle: number;
+    readonly outerConeAngle: number;
+  };
+}
+
+export interface GltfNodeIr {
+  readonly name?: string;
+  readonly transform: DecomposedTransform;
+  readonly meshIndex: number | null;
+  /** Node-authored morph weights override mesh defaults at instantiation. */
+  readonly morphWeights?: Float32Array;
+  /** Valid when node carries `skin` reference. Null when no skin. */
+  readonly skinIndex: number | null;
+  readonly children: readonly number[];
+  /** Present when node carries EXT_mesh_gpu_instancing (feat-20260518). */
+  readonly instancing?: NodeInstancingIr;
+  /** glTF camera index. Null when the node does not reference a camera. */
+  readonly camera: number | null;
+  /** KHR_lights_punctual light index. Null when the node has no light. */
+  readonly lightIndex?: number | null;
+}
+
+export interface GltfSceneIr {
+  readonly name?: string;
+  readonly nodes: readonly number[];
+}
+
+export interface GltfDiagnosticsIr {
+  readonly nodeNames: readonly string[];
+  readonly unsupportedExtensions: readonly string[];
+  readonly matrixTrsCoexistNodes: readonly number[];
+}
+
+export interface GltfDoc {
+  readonly meshes: readonly GltfMeshIr[];
+  readonly materials: readonly GltfMaterialIr[];
+  readonly nodes: readonly GltfNodeIr[];
+  readonly scenes: readonly GltfSceneIr[];
+  readonly textures: readonly GltfTextureIr[] | undefined;
+  readonly images: readonly GltfImageIr[] | undefined;
+  readonly samplers: readonly GltfSamplerIr[] | undefined;
+  readonly skeletons: readonly GltfSkeletonRecord[];
+  readonly animationClips: readonly GltfAnimationClipRecord[];
+  readonly defaultSceneIndex: number;
+  readonly diagnostics: GltfDiagnosticsIr;
+  /** KHR_lights_punctual author facts, kept in source units for the bridge. */
+  readonly lights?: readonly GltfPunctualLightIr[];
+  /** Raw extension projection retained for bridge-only hand-constructed docs. */
+  readonly extensions?: {
+    readonly KHR_lights_punctual?: {
+      readonly lights?: readonly GltfPunctualLightIr[];
+    };
+  };
+  /**
+   * Original glTF-mesh-index -> number of primitives that mesh expanded into
+   * (feat-20260608 round-2). parseGltf flattens N glTF meshes with M_i
+   * primitives into sum(M_i) GltfMeshIr entries; this map preserves the M_i so
+   * downstream consumers (gltfDocToSceneAsset's `meshPrimitiveCount` param)
+   * can map a glTF mesh index back to the flat-GltfMeshIr offset range without
+   * re-parsing JSON.
+   *
+   * Optional for backwards compatibility with hand-constructed test
+   * fixtures; producers from parseGltf / parseGlb always populate it.
+   */
+  readonly meshPrimitiveCount?: ReadonlyMap<number, number>;
+}
+
+interface BuffersJson {
+  readonly byteLength: number;
+  readonly uri?: string;
+}
+
+interface TextureTransformJson {
+  readonly offset?: readonly number[];
+  readonly rotation?: number;
+  readonly scale?: readonly number[];
+  readonly texCoord?: number;
+}
+
+interface TextureInfoJson {
+  readonly index: number;
+  readonly texCoord?: number;
+  readonly extensions?: {
+    readonly KHR_texture_transform?: TextureTransformJson;
+  };
+}
+
+interface NormalTextureInfoJson extends TextureInfoJson {
+  readonly scale?: number;
+}
+
+interface OcclusionTextureInfoJson extends TextureInfoJson {
+  readonly strength?: number;
+}
+
+interface RootGltfJson extends GltfExtensionsJson {
+  readonly asset?: { readonly version?: string };
+  readonly scene?: number;
+  readonly scenes?: ReadonlyArray<{ readonly name?: string; readonly nodes?: readonly number[] }>;
+  readonly nodes?: ReadonlyArray<{
+    readonly name?: string;
+    readonly mesh?: number;
+    readonly skin?: number;
+    readonly camera?: number;
+    readonly children?: readonly number[];
+    readonly matrix?: readonly number[];
+    readonly translation?: readonly number[];
+    readonly rotation?: readonly number[];
+    readonly scale?: readonly number[];
+    readonly weights?: readonly number[];
+    readonly extensions?: {
+      readonly KHR_lights_punctual?: {
+        readonly light?: number;
+      };
+      readonly EXT_mesh_gpu_instancing?: {
+        readonly attributes?: {
+          readonly TRANSLATION?: number;
+          readonly ROTATION?: number;
+          readonly SCALE?: number;
+        };
+      };
+    };
+  }>;
+  readonly extensions?: {
+    readonly KHR_lights_punctual?: {
+      readonly lights?: ReadonlyArray<{
+        readonly type?: string;
+        readonly color?: readonly number[];
+        readonly intensity?: number;
+        readonly range?: number;
+        readonly spot?: {
+          readonly innerConeAngle?: number;
+          readonly outerConeAngle?: number;
+        };
+      }>;
+    };
+  };
+  readonly skins?: ReadonlyArray<{
+    readonly name?: string;
+    readonly joints: readonly number[];
+    readonly inverseBindMatrices?: number;
+  }>;
+  readonly meshes?: readonly MeshJson[];
+  readonly materials?: ReadonlyArray<{
+    readonly name?: string;
+    readonly pbrMetallicRoughness?: {
+      readonly baseColorFactor?: readonly number[];
+      readonly baseColorTexture?: TextureInfoJson;
+      readonly metallicFactor?: number;
+      readonly roughnessFactor?: number;
+      readonly metallicRoughnessTexture?: TextureInfoJson;
+    };
+    readonly normalTexture?: NormalTextureInfoJson;
+    readonly emissiveFactor?: readonly number[];
+    readonly emissiveTexture?: TextureInfoJson;
+    readonly occlusionTexture?: OcclusionTextureInfoJson;
+    readonly alphaMode?: string;
+    readonly alphaCutoff?: number;
+    readonly doubleSided?: boolean;
+  }>;
+  readonly textures?: ReadonlyArray<{
+    readonly sampler?: number;
+    readonly source?: number;
+    readonly name?: string;
+  }>;
+  readonly images?: ReadonlyArray<{
+    readonly uri?: string;
+    readonly mimeType?: string;
+    readonly bufferView?: number;
+    readonly name?: string;
+  }>;
+  readonly samplers?: ReadonlyArray<{
+    readonly magFilter?: number;
+    readonly minFilter?: number;
+    readonly wrapS?: number;
+    readonly wrapT?: number;
+    readonly name?: string;
+  }>;
+  readonly accessors?: readonly AccessorJson[];
+  readonly bufferViews?: readonly BufferViewJson[];
+  readonly buffers?: readonly BuffersJson[];
+  readonly animations?: ReadonlyArray<{
+    readonly name?: string;
+    readonly channels: ReadonlyArray<{
+      readonly sampler: number;
+      readonly target: {
+        readonly node?: number;
+        readonly path: string;
+      };
+    }>;
+    readonly samplers: ReadonlyArray<{
+      readonly input: number;
+      readonly output: number;
+      readonly interpolation?: string;
+    }>;
+  }>;
+}
+
+function tuple2(values: readonly number[] | undefined): readonly [number, number] | undefined {
+  if (values === undefined || values.length < 2) return undefined;
+  return [values[0] ?? 0, values[1] ?? 0];
+}
+
+function parseTextureInfo(
+  info: TextureInfoJson,
+  textures: readonly GltfTextureIr[],
+): GltfTextureInfoIr {
+  const transformJson = info.extensions?.KHR_texture_transform;
+  const offset = tuple2(transformJson?.offset);
+  const scale = tuple2(transformJson?.scale);
+  const transform =
+    offset === undefined && transformJson?.rotation === undefined && scale === undefined
+      ? undefined
+      : {
+          ...(offset === undefined ? {} : { offset }),
+          ...(transformJson?.rotation === undefined ? {} : { rotation: transformJson.rotation }),
+          ...(scale === undefined ? {} : { scale }),
+        };
+  const sampler = textures[info.index]?.sampler;
+  return {
+    texture: info.index,
+    ...(sampler === undefined ? {} : { sampler }),
+    ...(info.texCoord === undefined && transformJson?.texCoord === undefined
+      ? {}
+      : { texCoord: transformJson?.texCoord ?? info.texCoord }),
+    ...(transform === undefined ? {} : { transform }),
+  };
+}
+
+export type ExternalLoader = (uri: string) => Promise<ArrayBuffer>;
+
+async function resolveBuffer(
+  buf: BuffersJson,
+  externalLoader: ExternalLoader,
+  binChunk: Uint8Array | undefined,
+): Promise<Uint8Array> {
+  if (buf.uri === undefined) {
+    // GLB BIN chunk slot.
+    if (binChunk === undefined) {
+      throw new Error('parseGltf: buffer 0 has no uri and no GLB BIN chunk available');
+    }
+    return binChunk;
+  }
+  const dataPayload = dataUriBase64Payload(buf.uri);
+  if (dataPayload !== undefined) {
+    return decodeBase64(dataPayload);
+  }
+  const arrayBuffer = await externalLoader(buf.uri);
+  return new Uint8Array(arrayBuffer);
+}
+
+interface ParseGltfInternalsContext {
+  readonly externalLoader: ExternalLoader;
+  readonly binChunk?: Uint8Array;
+  readonly filePath: string;
+  readonly meshopt?: GltfBufferViewDecodeCapability;
+}
+
+type GltfParseError = GltfError | ImportError;
+
+function invalidBufferDataUriError(
+  filePath: string,
+  bufferIndex: number,
+  cause: Base64DecodeError,
+): ImportError {
+  return new ImportError({
+    code: 'source-validation-failed',
+    expected: `glTF buffer ${bufferIndex} data URI to contain a valid base64 payload`,
+    hint: IMPORT_ERROR_HINTS['source-validation-failed'],
+    detail: {
+      diagnostics: [
+        {
+          code: 'gltf-buffer-data-uri-invalid',
+          severity: 'error',
+          sourcePath: filePath,
+          sourceRange: { start: 0, end: 0, line: 1, column: 1 },
+          rule: 'gltf-buffer-data-uri-base64',
+          expected: 'a valid base64 payload after ;base64,',
+          actual: `buffer ${bufferIndex}: ${cause.message}`,
+          hint: 'repair the buffer data URI or provide a valid external .bin sibling',
+        },
+      ],
+    },
+  });
+}
+
+export interface GltfParseOptions {
+  readonly meshopt?: GltfBufferViewDecodeCapability;
+}
+
+function parsePunctualLights(
+  json: RootGltfJson,
+  filePath: string,
+): Result<readonly GltfPunctualLightIr[], GltfError> {
+  const source = json.extensions?.KHR_lights_punctual?.lights ?? [];
+  const lights: GltfPunctualLightIr[] = [];
+  for (const light of source) {
+    const type = light?.type;
+    if (type !== 'directional' && type !== 'point' && type !== 'spot') {
+      return err(gltfErr('gltf-malformed-header', { filePath, byteOffset: 0 }));
+    }
+    const color = light.color ?? [1, 1, 1];
+    if (
+      color.length < 3 ||
+      color
+        .slice(0, 3)
+        .some(
+          (value) => typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1,
+        )
+    ) {
+      return err(gltfErr('gltf-malformed-header', { filePath, byteOffset: 0 }));
+    }
+    const intensity = light.intensity ?? 1;
+    if (typeof intensity !== 'number' || !Number.isFinite(intensity) || intensity < 0) {
+      return err(gltfErr('gltf-malformed-header', { filePath, byteOffset: 0 }));
+    }
+    const range = light.range;
+    if (
+      range !== undefined &&
+      (typeof range !== 'number' || !Number.isFinite(range) || range < 0)
+    ) {
+      return err(gltfErr('gltf-malformed-header', { filePath, byteOffset: 0 }));
+    }
+    let spot: GltfPunctualLightIr['spot'];
+    if (type === 'spot') {
+      const innerConeAngle = light.spot?.innerConeAngle ?? 0;
+      const outerConeAngle = light.spot?.outerConeAngle ?? Math.PI / 4;
+      if (
+        !Number.isFinite(innerConeAngle) ||
+        !Number.isFinite(outerConeAngle) ||
+        innerConeAngle < 0 ||
+        innerConeAngle >= outerConeAngle ||
+        outerConeAngle > Math.PI / 2
+      ) {
+        return err(gltfErr('gltf-malformed-header', { filePath, byteOffset: 0 }));
+      }
+      spot = { innerConeAngle, outerConeAngle };
+    }
+    lights.push({
+      type,
+      color: [color[0] ?? 1, color[1] ?? 1, color[2] ?? 1],
+      intensity,
+      ...(range === undefined || range === 0 ? {} : { range }),
+      ...(spot === undefined ? {} : { spot }),
+    });
+  }
+  return ok(lights);
+}
+
+async function parseGltfWithBin(
+  json: RootGltfJson,
+  ctx: ParseGltfInternalsContext,
+): Promise<Result<GltfDoc, GltfParseError>> {
+  const headerResult = parseGltfHeader(json, ctx.filePath);
+  if (!headerResult.ok) return err(headerResult.error);
+
+  const extResult = checkExtensions(json);
+  if (!extResult.ok) return err(extResult.error);
+  const unsupportedExtensions = extResult.value.unsupportedUsed;
+  const lightsResult = parsePunctualLights(json, ctx.filePath);
+  if (!lightsResult.ok) return err(lightsResult.error);
+
+  const meshesJson = json.meshes ?? [];
+
+  // Resolve buffers (data: URI / external / GLB BIN chunk).
+  const buffersJson = json.buffers ?? [];
+  const buffers: Uint8Array[] = [];
+  for (let i = 0; i < buffersJson.length; i++) {
+    const bufJson = buffersJson[i];
+    if (bufJson === undefined) continue;
+    try {
+      const bytes = await resolveBuffer(bufJson, ctx.externalLoader, ctx.binChunk);
+      buffers.push(bytes);
+    } catch (e) {
+      if (e instanceof Base64DecodeError) {
+        return err(invalidBufferDataUriError(ctx.filePath, i, e));
+      }
+      return err(
+        gltfErr('gltf-malformed-header', {
+          filePath: ctx.filePath,
+          byteOffset: 0,
+        }),
+      );
+    }
+  }
+
+  const accessors = json.accessors ?? [];
+  const rawBufferViews = json.bufferViews ?? [];
+  const projected = await projectMeshoptBufferViews(
+    rawBufferViews as readonly MeshoptBufferViewJson[],
+    buffers,
+    json.extensionsRequired ?? [],
+    ctx.meshopt,
+  );
+  if (!projected.ok) return err(projected.error);
+  const bufferViews = projected.value.bufferViews;
+  buffers.splice(0, buffers.length, ...projected.value.buffers);
+
+  const meshes: GltfMeshIr[] = [];
+  // feat-20260608 round-2: surface the original-glTF-mesh primitive counts so
+  // build-time consumers (gltfImporter scene arm) can hand them to
+  // gltfDocToSceneAsset's `meshPrimitiveCount` parameter without re-parsing
+  // the JSON. Without this, importGltf at gltf-importer.ts ~272 walks the
+  // already-flattened doc.meshes (one entry per primitive) and cannot
+  // reconstruct the gltfMesh -> primitiveCount map; the bridge then uses
+  // identity (gltfMeshIdx == flatIdx) and any multi-primitive .gltf imports
+  // misindex meshes after the first primitive.
+  const meshPrimitiveCount = new Map<number, number>();
+  for (let meshIndex = 0; meshIndex < meshesJson.length; meshIndex++) {
+    const meshJson = meshesJson[meshIndex];
+    if (meshJson === undefined) continue;
+    meshPrimitiveCount.set(meshIndex, meshJson.primitives.length);
+    for (const prim of meshJson.primitives) {
+      if (prim === undefined) continue;
+      const positionAccessorIndex = prim.attributes?.POSITION;
+      if (positionAccessorIndex === undefined) {
+        return err(
+          gltfErr('gltf-accessor-type-mismatch', {
+            accessorIndex: -1,
+            reason: 'unknownComponentType',
+          }),
+        );
+      }
+      const positionAccessor = accessors[positionAccessorIndex];
+      const positionBufferView = bufferViews[positionAccessor?.bufferView ?? -1];
+      if (positionAccessor === undefined || positionBufferView === undefined) {
+        return err(
+          gltfErr('gltf-buffer-out-of-bounds', {
+            accessor: positionAccessorIndex,
+            byteOffset: 0,
+            byteLength: 0,
+            bufferIndex: positionBufferView?.buffer ?? 0,
+          }),
+        );
+      }
+      const positionBuffer = buffers[positionBufferView.buffer];
+      if (positionBuffer === undefined) {
+        return err(
+          gltfErr('gltf-buffer-out-of-bounds', {
+            accessor: positionAccessorIndex,
+            byteOffset: positionBufferView.byteOffset ?? 0,
+            byteLength: positionBufferView.byteLength,
+            bufferIndex: positionBufferView.buffer,
+          }),
+        );
+      }
+      const positionDecoded = decodeAccessor({
+        accessorIndex: positionAccessorIndex,
+        accessor: positionAccessor,
+        bufferView: positionBufferView,
+        buffer: positionBuffer,
+        role: 'attribute',
+      });
+      if (!positionDecoded.ok) return err(positionDecoded.error);
+      if (positionDecoded.value.kind !== 'f32') {
+        return err(
+          gltfErr('gltf-accessor-type-mismatch', {
+            accessorIndex: positionAccessorIndex,
+            reason: 'unknownComponentType',
+          }),
+        );
+      }
+      const positionsDecoded = positionDecoded.value.data;
+      // Re-allocate over a fresh ArrayBuffer so the GltfMeshIr.positions type
+      // (`Float32Array<ArrayBuffer>`) holds without ArrayBufferLike leakage.
+      const positions = new Float32Array(positionsDecoded.length);
+      positions.set(positionsDecoded);
+
+      // Decode optional vertex attributes: NORMAL (VEC3), TEXCOORD_0 (VEC2),
+      // TANGENT (VEC4). Each uses the existing decodeAttributeAccessor helper.
+      // Missing attributes leave the GltfMeshIr field undefined.
+      const attrs = prim.attributes ?? {};
+
+      let colors0: Float32Array | undefined;
+      const colorIdx = attrs.COLOR_0;
+      if (colorIdx !== undefined) {
+        const colorAccessor = accessors[colorIdx];
+        const colorBufferView = bufferViews[colorAccessor?.bufferView ?? -1];
+        if (colorAccessor === undefined || colorBufferView === undefined) {
+          return err(
+            gltfErr('gltf-color-accessor-malformed', {
+              semantic: 'COLOR_0',
+              accessorIndex: colorIdx,
+              reason: 'reference',
+            }),
+          );
+        }
+        const colorBuffer = buffers[colorBufferView.buffer];
+        if (colorBuffer === undefined) {
+          return err(
+            gltfErr('gltf-color-accessor-malformed', {
+              semantic: 'COLOR_0',
+              accessorIndex: colorIdx,
+              reason: 'reference',
+            }),
+          );
+        }
+        const decoded = decodeColorAccessor({
+          accessorIndex: colorIdx,
+          accessor: colorAccessor,
+          bufferView: colorBufferView,
+          buffer: colorBuffer,
+          bufferIndex: colorBufferView.buffer,
+          semantic: 'COLOR_0',
+        });
+        if (!decoded.ok) return err(decoded.error);
+        if (decoded.value.length !== (positions.length / 3) * 4) {
+          return err(
+            gltfErr('gltf-color-accessor-malformed', {
+              semantic: 'COLOR_0',
+              accessorIndex: colorIdx,
+              reason: 'count',
+            }),
+          );
+        }
+        colors0 = decoded.value;
+      }
+
+      let normals: Float32Array | undefined;
+      const normalIdx = attrs.NORMAL;
+      if (normalIdx !== undefined) {
+        const acc = accessors[normalIdx];
+        if (acc !== undefined) {
+          const decoded = decodeAttributeAccessor(normalIdx, acc, bufferViews, buffers);
+          if (decoded.ok) {
+            const src = decoded.value;
+            const owned = new Float32Array(src.length);
+            owned.set(src);
+            normals = owned;
+          }
+        }
+      }
+
+      let texcoord0: Float32Array | undefined;
+      const texIdx = attrs.TEXCOORD_0;
+      if (texIdx !== undefined) {
+        const acc = accessors[texIdx];
+        if (acc !== undefined) {
+          const decoded = decodeAttributeAccessor(texIdx, acc, bufferViews, buffers);
+          if (decoded.ok) {
+            const src = decoded.value;
+            const owned = new Float32Array(src.length);
+            owned.set(src);
+            texcoord0 = owned;
+          }
+        }
+      }
+
+      // feat-20260629-multi-uv-set-support m1-w2: decode TEXCOORD_1..7
+      // using the same decodeAttributeAccessor→Float32Array pattern.
+      // Missing accessor → field stays undefined (no error, mirrors TEXCOORD_0).
+      // componentType non-FLOAT → decodeAttributeAccessor returns error already.
+      let texcoord1: Float32Array | undefined;
+      let texcoord2: Float32Array | undefined;
+      let texcoord3: Float32Array | undefined;
+      let texcoord4: Float32Array | undefined;
+      let texcoord5: Float32Array | undefined;
+      let texcoord6: Float32Array | undefined;
+      let texcoord7: Float32Array | undefined;
+      for (let k = 1; k <= 7; k++) {
+        const tcIdx = attrs[`TEXCOORD_${k}`];
+        if (tcIdx === undefined) continue;
+        const acc = accessors[tcIdx];
+        if (acc !== undefined) {
+          const decoded = decodeAttributeAccessor(tcIdx, acc, bufferViews, buffers);
+          if (decoded.ok) {
+            const src = decoded.value;
+            const owned = new Float32Array(src.length);
+            owned.set(src);
+            if (k === 1) texcoord1 = owned;
+            else if (k === 2) texcoord2 = owned;
+            else if (k === 3) texcoord3 = owned;
+            else if (k === 4) texcoord4 = owned;
+            else if (k === 5) texcoord5 = owned;
+            else if (k === 6) texcoord6 = owned;
+            else texcoord7 = owned;
+          }
+        }
+      }
+
+      let tangents: Float32Array | undefined;
+      const tanIdx = attrs.TANGENT;
+      if (tanIdx !== undefined) {
+        const acc = accessors[tanIdx];
+        if (acc !== undefined) {
+          const decoded = decodeAttributeAccessor(tanIdx, acc, bufferViews, buffers);
+          if (decoded.ok) {
+            const src = decoded.value;
+            const owned = new Float32Array(src.length);
+            owned.set(src);
+            tangents = owned;
+          }
+        }
+      }
+
+      const rawTargets = prim.targets ?? [];
+      for (const target of rawTargets) {
+        const colorTarget = target.COLOR_0;
+        if (colorTarget !== undefined) {
+          return err(
+            gltfErr('gltf-color-accessor-unsupported', {
+              semantic: 'COLOR_0',
+              accessorIndex: colorTarget,
+              reason: 'morph',
+            }),
+          );
+        }
+      }
+      const morphAttributeCount = rawTargets.reduce(
+        (count, target) =>
+          count +
+          (target.POSITION === undefined ? 0 : 1) +
+          (target.NORMAL === undefined ? 0 : 1) +
+          (target.TANGENT === undefined ? 0 : 1),
+        0,
+      );
+      const morphError = (
+        reason:
+          | 'target-count-exceeded'
+          | 'attribute-count-exceeded'
+          | 'attribute-length-mismatch'
+          | 'weights-length-mismatch'
+          | 'sparse-or-unsupported-accessor',
+      ) =>
+        err(
+          gltfErr('gltf-morph-invalid', {
+            meshIndex,
+            primitiveIndex: meshJson.primitives.indexOf(prim),
+            reason,
+            targetCount: rawTargets.length,
+            attributeCount: morphAttributeCount,
+            vertexCount: positions.length / 3,
+          }),
+        );
+      if (rawTargets.length > 8) return morphError('target-count-exceeded');
+      if (morphAttributeCount > 8) return morphError('attribute-count-exceeded');
+
+      const morphTargets: {
+        readonly position?: Float32Array;
+        readonly normal?: Float32Array;
+        readonly tangent?: Float32Array;
+      }[] = [];
+      for (const target of rawTargets) {
+        const output: {
+          position?: Float32Array;
+          normal?: Float32Array;
+          tangent?: Float32Array;
+        } = {};
+        for (const [key, accessorIndex] of Object.entries(target)) {
+          if (key !== 'POSITION' && key !== 'NORMAL' && key !== 'TANGENT') continue;
+          const targetAccessor = accessors[accessorIndex];
+          if (targetAccessor === undefined) return morphError('attribute-length-mismatch');
+          const decoded = decodeAttributeAccessor(
+            accessorIndex,
+            targetAccessor,
+            bufferViews,
+            buffers,
+          );
+          if (!decoded.ok) {
+            return morphError(
+              decoded.error.code === 'gltf-accessor-type-mismatch'
+                ? 'sparse-or-unsupported-accessor'
+                : 'attribute-length-mismatch',
+            );
+          }
+          const expected = (positions.length / 3) * (key === 'TANGENT' ? 4 : 3);
+          if (decoded.value.length !== expected) return morphError('attribute-length-mismatch');
+          const owned = new Float32Array(decoded.value.length);
+          owned.set(decoded.value);
+          if (key === 'POSITION') output.position = owned;
+          else if (key === 'NORMAL') output.normal = owned;
+          else output.tangent = owned;
+        }
+        morphTargets.push(output);
+      }
+      const meshWeights = meshJson.weights;
+      if (meshWeights !== undefined && meshWeights.length !== rawTargets.length) {
+        return morphError('weights-length-mismatch');
+      }
+
+      // JOINTS_0 / WEIGHTS_0 (feat-20260611 M1 w1): paired skinning attributes.
+      // glTF 2.0 spec section 3.7.2.1 requires the pair to appear together for
+      // any skinned primitive; lone presence -> gltf-skin-attr-asymmetric.
+      // JOINTS_0 componentType: UBYTE(5121) widen->U16 via decodeAccessor
+      // role='joints' (D-3 width-convert at parse), or USHORT(5123) standard
+      // U16 path. WEIGHTS_0 componentType: FLOAT(5126) standard F32 path.
+      const jointsIdx = attrs.JOINTS_0;
+      const weightsIdx = attrs.WEIGHTS_0;
+      const hasJoints = jointsIdx !== undefined;
+      const hasWeights = weightsIdx !== undefined;
+      if (hasJoints !== hasWeights) {
+        const primitiveIndex = meshJson.primitives.indexOf(prim);
+        return err(
+          gltfErr('gltf-skin-attr-asymmetric', {
+            meshIndex,
+            primitiveIndex,
+            hasJoints,
+            hasWeights,
+          }),
+        );
+      }
+      let joints0: Uint16Array | undefined;
+      let weights0: Float32Array | undefined;
+      if (hasJoints && hasWeights) {
+        const jointsAccessor = accessors[jointsIdx as number];
+        const jointsBufferView = bufferViews[jointsAccessor?.bufferView ?? -1];
+        if (jointsAccessor === undefined || jointsBufferView === undefined) {
+          return err(unknownAccessor(jointsIdx as number));
+        }
+        const jointsBuffer = buffers[jointsBufferView.buffer];
+        if (jointsBuffer === undefined) return err(unknownAccessor(jointsIdx as number));
+        const jointsDecoded = decodeAccessor({
+          accessorIndex: jointsIdx as number,
+          accessor: jointsAccessor,
+          bufferView: jointsBufferView,
+          buffer: jointsBuffer,
+          role: 'joints',
+        });
+        if (!jointsDecoded.ok) return err(jointsDecoded.error);
+        if (jointsDecoded.value.kind !== 'u16') {
+          return err(
+            gltfErr('gltf-accessor-type-mismatch', {
+              accessorIndex: jointsIdx as number,
+              reason: 'unknownComponentType',
+            }),
+          );
+        }
+        const src = jointsDecoded.value.data;
+        const owned = new Uint16Array(src.length);
+        owned.set(src);
+        joints0 = owned;
+
+        const weightsAccessor = accessors[weightsIdx as number];
+        const weightsBufferView = bufferViews[weightsAccessor?.bufferView ?? -1];
+        if (weightsAccessor === undefined || weightsBufferView === undefined) {
+          return err(unknownAccessor(weightsIdx as number));
+        }
+        const weightsBuffer = buffers[weightsBufferView.buffer];
+        if (weightsBuffer === undefined) return err(unknownAccessor(weightsIdx as number));
+        const weightsDecoded = decodeAccessor({
+          accessorIndex: weightsIdx as number,
+          accessor: weightsAccessor,
+          bufferView: weightsBufferView,
+          buffer: weightsBuffer,
+          role: 'attribute',
+        });
+        if (!weightsDecoded.ok) return err(weightsDecoded.error);
+        if (weightsDecoded.value.kind !== 'f32') {
+          return err(
+            gltfErr('gltf-accessor-type-mismatch', {
+              accessorIndex: weightsIdx as number,
+              reason: 'unknownComponentType',
+            }),
+          );
+        }
+        const wsrc = weightsDecoded.value.data;
+        const wowned = new Float32Array(wsrc.length);
+        wowned.set(wsrc);
+        weights0 = wowned;
+      }
+
+      // bug-20260612 hello-skin visual layered gate: glTF spec marks
+      // primitive.indices optional; undefined means non-indexed geometry.
+      // Leave indices undefined here; bridge.ts handles the non-indexed
+      // path by routing MeshAsset.indices to undefined.
+      let indices: Uint16Array | Uint32Array | undefined;
+      if (prim.indices !== undefined) {
+        const indexAccessor = accessors[prim.indices];
+        const indexBufferView = bufferViews[indexAccessor?.bufferView ?? -1];
+        if (indexAccessor === undefined || indexBufferView === undefined) {
+          return err(
+            gltfErr('gltf-buffer-out-of-bounds', {
+              accessor: prim.indices,
+              byteOffset: 0,
+              byteLength: 0,
+              bufferIndex: indexBufferView?.buffer ?? 0,
+            }),
+          );
+        }
+        const indexBuffer = buffers[indexBufferView.buffer];
+        if (indexBuffer === undefined) {
+          return err(
+            gltfErr('gltf-buffer-out-of-bounds', {
+              accessor: prim.indices,
+              byteOffset: indexBufferView.byteOffset ?? 0,
+              byteLength: indexBufferView.byteLength,
+              bufferIndex: indexBufferView.buffer,
+            }),
+          );
+        }
+        const indexDecoded = decodeAccessor({
+          accessorIndex: prim.indices,
+          accessor: indexAccessor,
+          bufferView: indexBufferView,
+          buffer: indexBuffer,
+          role: 'indices',
+        });
+        if (!indexDecoded.ok) return err(indexDecoded.error);
+        if (indexDecoded.value.kind === 'u16') {
+          // Re-allocate over a fresh ArrayBuffer so the GltfMeshIr.indices type
+          // (`Uint16Array<ArrayBuffer>`) holds without the underlying
+          // SharedArrayBuffer-friendly ArrayBufferLike slot leaking through.
+          const src = indexDecoded.value.data;
+          const owned = new Uint16Array(src.length);
+          owned.set(src);
+          indices = owned;
+        } else if (indexDecoded.value.kind === 'u32') {
+          // U32 indices ride through end-to-end: MeshAsset.indices is
+          // `Uint16Array | Uint32Array`, mesh-bin serializes iwidth=4, and
+          // the GPU runtime auto-selects 'uint32' via `instanceof Uint32Array`
+          // (createRenderer.ts). bridge.ts merges by value, so small meshes
+          // whose maxIndex < 65536 are losslessly narrowed to Uint16 there.
+          // Re-allocate over a fresh ArrayBuffer for the same reason as u16.
+          const src = indexDecoded.value.data;
+          const owned = new Uint32Array(src.length);
+          owned.set(src);
+          indices = owned;
+        } else {
+          return err(
+            gltfErr('gltf-accessor-type-mismatch', {
+              accessorIndex: prim.indices,
+              reason: 'unknownComponentType',
+            }),
+          );
+        }
+      }
+
+      const meshIr: GltfMeshIr = {
+        ...(meshJson.name === undefined ? {} : { name: meshJson.name }),
+        positions,
+        ...(normals === undefined ? {} : { normals }),
+        ...(texcoord0 === undefined ? {} : { texcoord0 }),
+        ...(texcoord1 === undefined ? {} : { texcoord1 }),
+        ...(texcoord2 === undefined ? {} : { texcoord2 }),
+        ...(texcoord3 === undefined ? {} : { texcoord3 }),
+        ...(texcoord4 === undefined ? {} : { texcoord4 }),
+        ...(texcoord5 === undefined ? {} : { texcoord5 }),
+        ...(texcoord6 === undefined ? {} : { texcoord6 }),
+        ...(texcoord7 === undefined ? {} : { texcoord7 }),
+        ...(tangents === undefined ? {} : { tangents }),
+        ...(colors0 === undefined ? {} : { colors0 }),
+        ...(joints0 === undefined ? {} : { joints0 }),
+        ...(weights0 === undefined ? {} : { weights0 }),
+        ...(morphTargets.length === 0 ? {} : { morphTargets }),
+        ...(meshWeights === undefined ? {} : { morphWeights: new Float32Array(meshWeights) }),
+        ...(indices === undefined ? {} : { indices }),
+        materialIndex: prim.material ?? null,
+        meshIndex,
+      };
+      meshes.push(meshIr);
+    }
+  }
+
+  // Textures, images, samplers (Tier-C: parse top-level arrays).
+  const texturesJson = json.textures ?? [];
+  const textures: GltfTextureIr[] = [];
+  for (const texJson of texturesJson) {
+    const texIr: GltfTextureIr = {
+      source: texJson.source ?? -1,
+      ...(texJson.sampler === undefined ? {} : { sampler: texJson.sampler }),
+      ...(texJson.name === undefined ? {} : { name: texJson.name }),
+    };
+    textures.push(texIr);
+  }
+
+  const imagesJson = json.images ?? [];
+  const images: GltfImageIr[] = [];
+  for (const imgJson of imagesJson) {
+    const mimeType = imgJson.mimeType;
+    if (mimeType !== undefined && mimeType !== 'image/jpeg' && mimeType !== 'image/png') {
+      return err(gltfErr('gltf-image-mime-unsupported', { mimeType }));
+    }
+    const imgIr: GltfImageIr = {
+      ...(imgJson.uri === undefined ? {} : { uri: imgJson.uri }),
+      ...(imgJson.mimeType === undefined ? {} : { mimeType: imgJson.mimeType }),
+      ...(imgJson.bufferView === undefined ? {} : { bufferView: imgJson.bufferView }),
+      ...(imgJson.name === undefined ? {} : { name: imgJson.name }),
+    };
+    images.push(imgIr);
+  }
+
+  // Load external image URIs via externalLoader.
+  for (const img of images) {
+    if (img.uri !== undefined) {
+      if (dataUriBase64Payload(img.uri) !== undefined) continue; // data: URI, skip external load
+      try {
+        await ctx.externalLoader(img.uri);
+      } catch (_e) {
+        return err(gltfErr('gltf-texture-load-failed', { uri: img.uri }));
+      }
+    }
+  }
+
+  const samplersJson = json.samplers ?? [];
+  const samplers: GltfSamplerIr[] = [];
+  for (const sampJson of samplersJson) {
+    samplers.push({
+      ...(sampJson.magFilter === undefined ? {} : { magFilter: sampJson.magFilter }),
+      ...(sampJson.minFilter === undefined ? {} : { minFilter: sampJson.minFilter }),
+      wrapS: sampJson.wrapS ?? 10497, // REPEAT (glTF default)
+      wrapT: sampJson.wrapT ?? 10497,
+      ...(sampJson.name === undefined ? {} : { name: sampJson.name }),
+    });
+  }
+
+  // Materials (Tier-C subset: metallic-roughness PBR + normal/emissive maps).
+  const materialsJson = json.materials ?? [];
+  const materials: GltfMaterialIr[] = [];
+  for (const matJson of materialsJson) {
+    const pbr = matJson.pbrMetallicRoughness;
+    const baseColor = pbr?.baseColorFactor ?? [1, 1, 1, 1];
+    const baseColor4: readonly [number, number, number, number] = [
+      baseColor[0] ?? 1,
+      baseColor[1] ?? 1,
+      baseColor[2] ?? 1,
+      baseColor[3] ?? 1,
+    ];
+
+    const alphaMode =
+      matJson.alphaMode === 'MASK' || matJson.alphaMode === 'BLEND' ? matJson.alphaMode : undefined;
+    const alphaCutoff = alphaMode === 'MASK' ? (matJson.alphaCutoff ?? 0.5) : undefined;
+    const emissiveFactor = matJson.emissiveFactor;
+    const emissiveFactor3: readonly [number, number, number] = [
+      emissiveFactor?.[0] ?? 0,
+      emissiveFactor?.[1] ?? 0,
+      emissiveFactor?.[2] ?? 0,
+    ];
+    materials.push({
+      ...(matJson.name === undefined ? {} : { name: matJson.name }),
+      baseColorFactor: baseColor4,
+      ...(emissiveFactor === undefined ? {} : { emissiveFactor: emissiveFactor3 }),
+      metallicFactor: pbr?.metallicFactor ?? 1.0,
+      roughnessFactor: pbr?.roughnessFactor ?? 1.0,
+      ...(pbr?.baseColorTexture === undefined
+        ? {}
+        : { baseColorTexture: parseTextureInfo(pbr.baseColorTexture, textures) }),
+      ...(pbr?.metallicRoughnessTexture === undefined
+        ? {}
+        : { metallicRoughnessTexture: parseTextureInfo(pbr.metallicRoughnessTexture, textures) }),
+      ...(matJson.normalTexture === undefined
+        ? {}
+        : {
+            normalTexture: {
+              ...parseTextureInfo(matJson.normalTexture, textures),
+              ...(matJson.normalTexture.scale === undefined
+                ? {}
+                : { scale: matJson.normalTexture.scale }),
+            },
+          }),
+      ...(matJson.occlusionTexture === undefined
+        ? {}
+        : {
+            occlusionTexture: {
+              ...parseTextureInfo(matJson.occlusionTexture, textures),
+              ...(matJson.occlusionTexture.strength === undefined
+                ? {}
+                : { strength: matJson.occlusionTexture.strength }),
+            },
+          }),
+      ...(matJson.emissiveTexture === undefined
+        ? {}
+        : { emissiveTexture: parseTextureInfo(matJson.emissiveTexture, textures) }),
+      ...(alphaMode === undefined ? {} : { alphaMode }),
+      ...(alphaCutoff === undefined ? {} : { alphaCutoff }),
+      ...(matJson.doubleSided === true ? { doubleSided: true } : {}),
+      ...(pbr?.baseColorTexture?.texCoord === undefined || pbr.baseColorTexture.texCoord === 0
+        ? {}
+        : { baseColorTexCoord: pbr.baseColorTexture.texCoord }),
+    });
+  }
+
+  // Nodes + diagnostics.
+  const diagnostics = {
+    nodeNames: [] as string[],
+    unsupportedExtensions: [...unsupportedExtensions] as string[],
+    matrixTrsCoexistNodes: [] as number[],
+  };
+  const nodes: GltfNodeIr[] = [];
+  const nodesJson = json.nodes ?? [];
+  for (let nodeIndex = 0; nodeIndex < nodesJson.length; nodeIndex++) {
+    const nodeJson = nodesJson[nodeIndex];
+    if (nodeJson === undefined) continue;
+    const transform = decomposeNodeTransform(nodeJson, nodeIndex, diagnostics);
+    if (nodeJson.name !== undefined) diagnostics.nodeNames.push(nodeJson.name);
+    const instancingExt = nodeJson.extensions?.EXT_mesh_gpu_instancing;
+    let instancing: NodeInstancingIr | undefined;
+    if (instancingExt !== undefined) {
+      const instancingResult = decodeNodeInstancing(
+        nodeIndex,
+        instancingExt.attributes ?? {},
+        accessors,
+        bufferViews,
+        buffers,
+      );
+      if (!instancingResult.ok) return err(instancingResult.error);
+      instancing = instancingResult.value;
+    }
+    const nodeMorphWeights =
+      nodeJson.weights === undefined ? undefined : new Float32Array(nodeJson.weights);
+    nodes.push({
+      ...(nodeJson.name === undefined ? {} : { name: nodeJson.name }),
+      transform,
+      meshIndex: nodeJson.mesh ?? null,
+      skinIndex: nodeJson.skin ?? null,
+      children: nodeJson.children ?? [],
+      camera: nodeJson.camera ?? null,
+      lightIndex: nodeJson.extensions?.KHR_lights_punctual?.light ?? null,
+      ...(instancing === undefined ? {} : { instancing }),
+      ...(nodeMorphWeights === undefined ? {} : { morphWeights: nodeMorphWeights }),
+    });
+  }
+
+  // Scenes.
+  const scenesJson = json.scenes ?? [];
+  const scenes: GltfSceneIr[] = scenesJson.map((s) => ({
+    ...(s.name === undefined ? {} : { name: s.name }),
+    nodes: s.nodes ?? [],
+  }));
+  const defaultSceneIndex = json.scene ?? 0;
+
+  // Skins (feat-20260523-skin-skeleton-animation M0).
+  const skinsJson = json.skins;
+  const skinResult = parseSkin(skinsJson, nodesJson, accessors, bufferViews, buffers);
+  if (!skinResult.ok) return err(skinResult.error);
+  const skeletons = skinResult.value;
+
+  // Animations (feat-20260523-skin-skeleton-animation M0).
+  const animationsJson = json.animations;
+  const animResult = parseAnimation(animationsJson, nodesJson, accessors, bufferViews, buffers);
+  if (!animResult.ok) return err(animResult.error);
+  const animationClips = animResult.value;
+
+  return ok({
+    meshes,
+    materials,
+    nodes,
+    scenes,
+    skeletons,
+    animationClips,
+    textures: textures.length > 0 ? textures : undefined,
+    images: images.length > 0 ? images : undefined,
+    samplers: samplers.length > 0 ? samplers : undefined,
+    defaultSceneIndex,
+    diagnostics: {
+      nodeNames: diagnostics.nodeNames,
+      unsupportedExtensions: diagnostics.unsupportedExtensions,
+      matrixTrsCoexistNodes: diagnostics.matrixTrsCoexistNodes,
+    },
+    meshPrimitiveCount,
+    lights: lightsResult.value,
+  });
+}
+
+/**
+ * Parse a glTF 2.0 JSON document. The `externalLoader` resolves
+ * `buffers[].uri` references that are NOT data: URIs (callers in Node
+ * land typically wrap fs.readFile; browser callers wrap fetch).
+ *
+ * Pure function modulo `externalLoader` (caller-provided I/O is the
+ * only side effect). No global state, no fs / network direct call.
+ */
+export async function parseGltfForImporter(
+  json: unknown,
+  externalLoader: ExternalLoader,
+  filePath: string,
+  options: GltfParseOptions = {},
+): Promise<Result<GltfDoc, GltfParseError>> {
+  if (json === null || typeof json !== 'object') {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: 0,
+      }),
+    );
+  }
+  return parseGltfWithBin(json as RootGltfJson, {
+    externalLoader,
+    filePath,
+    ...(options.meshopt === undefined ? {} : { meshopt: options.meshopt }),
+  });
+}
+
+function legacyParseResult(
+  result: Result<GltfDoc, GltfParseError>,
+  filePath: string,
+  byteOffset: number,
+): Result<GltfDoc, GltfError> {
+  if (result.ok) return ok(result.value);
+  if (result.error instanceof ImportError) {
+    return err(gltfErr('gltf-malformed-header', { filePath, byteOffset }));
+  }
+  return err(result.error);
+}
+
+export async function parseGltf(
+  json: unknown,
+  externalLoader: ExternalLoader,
+  filePath: string,
+  options: GltfParseOptions = {},
+): Promise<Result<GltfDoc, GltfError>> {
+  const result = await parseGltfForImporter(json, externalLoader, filePath, options);
+  return legacyParseResult(result, filePath, 0);
+}
+
+/**
+ * Parse a GLB 2.0 binary container: split into JSON + BIN chunks via
+ * `parseGlbChunks`, then run the JSON document through `parseGltf` with
+ * the BIN chunk wired in as buffer-0 backing storage.
+ */
+export async function parseGlbForImporter(
+  buffer: ArrayBuffer,
+  filePath: string,
+  options: GltfParseOptions = {},
+): Promise<Result<GltfDoc, GltfParseError>> {
+  const chunksResult = parseGlbChunks(buffer, filePath);
+  if (!chunksResult.ok) return err(chunksResult.error);
+  let json: unknown;
+  try {
+    json = JSON.parse(new TextDecoder().decode(chunksResult.value.jsonChunk));
+  } catch (_e) {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: 12,
+      }),
+    );
+  }
+  if (json === null || typeof json !== 'object') {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: 12,
+      }),
+    );
+  }
+  const externalLoader: ExternalLoader = async (uri: string) => {
+    throw new Error(`parseGlb: GLB containers must not reference external URIs (got ${uri})`);
+  };
+  return parseGltfWithBin(json as RootGltfJson, {
+    externalLoader,
+    ...(chunksResult.value.binChunk === undefined ? {} : { binChunk: chunksResult.value.binChunk }),
+    filePath,
+    ...(options.meshopt === undefined ? {} : { meshopt: options.meshopt }),
+  });
+}
+
+export async function parseGlb(
+  buffer: ArrayBuffer,
+  filePath: string,
+  options: GltfParseOptions = {},
+): Promise<Result<GltfDoc, GltfError>> {
+  const result = await parseGlbForImporter(buffer, filePath, options);
+  return legacyParseResult(result, filePath, 12);
+}
+
+export interface GltfAssetPack {
+  readonly meta: GltfMetaJson;
+  readonly subAssets: readonly GltfSubAssetEntry[];
+}
+
+export type GltfAssetPackResult = Result<GltfAssetPack, GltfSourceKeyError>;
+
+/**
+ * Project a parsed `GltfDoc` into the disk-shape `<source>.meta.json` plus
+ * the freshly minted `subAssets[]` list (UUIDv7 + reimport-reuse-meta
+ * two-stage match per plan-strategy section 2.4). Source-key conflicts are
+ * returned before GUID minting or serialization.
+ *
+ * `existingMeta` is the previously-written `<source>.meta.json` parsed back
+ * into memory (callers typically read + JSON.parse it before invoking).
+ * `undefined` triggers first-pass full-fresh GUID minting.
+ *
+ * Sub-asset ordering: meshes first, then materials, then scenes - the
+ * order is stable across reimports so AC-13 byte-identical holds when
+ * source content does not change. Stable semantic sourceKey values are
+ * assigned by the producer reuse boundary; sourceIndex remains a locator.
+ */
+export function toAssetPack(
+  doc: GltfDoc,
+  existingMeta: GltfMetaJson | undefined,
+  source: string,
+): GltfAssetPackResult {
+  const items: GltfDocItem[] = [];
+  // Mesh sub-assets are keyed on the *original glTF mesh-index*, not on the
+  // flat GltfMeshIr index. parseGltf flattens N glTF meshes with M_i primitives
+  // into sum(M_i) GltfMeshIr rows (each carries its owning meshIndex). The
+  // gltfImporter merges all primitives sharing a meshIndex into one MeshAsset
+  // with M_i Submesh entries (one per primitive), so the meta sidecar must
+  // emit exactly one `kind: 'mesh'` row per unique meshIndex — not one per
+  // flat GltfMeshIr row, which would over-emit M_i sub-assets per glTF mesh and
+  // desynchronise from runtime MeshRenderer.materials[].length.
+  const seenMeshIndices = new Set<number>();
+  for (const m of doc.meshes) {
+    if (m === undefined) continue;
+    if (seenMeshIndices.has(m.meshIndex)) continue;
+    seenMeshIndices.add(m.meshIndex);
+    items.push({
+      kind: 'mesh',
+      sourceIndex: m.meshIndex,
+      ...(m.name === undefined ? {} : { name: m.name }),
+    });
+  }
+  for (let i = 0; i < doc.materials.length; i++) {
+    const m = doc.materials[i];
+    if (m === undefined) continue;
+    items.push({
+      kind: 'material',
+      sourceIndex: i,
+      ...(m.name === undefined ? {} : { name: m.name }),
+    });
+  }
+  for (let i = 0; i < doc.scenes.length; i++) {
+    const s = doc.scenes[i];
+    if (s === undefined) continue;
+    items.push({
+      kind: 'scene',
+      sourceIndex: i,
+      ...(s.name === undefined ? {} : { name: s.name }),
+    });
+  }
+  // Texture sub-assets — one entry per `images[]` row (feat-20260608 M3 D-3,
+  // requirements G-2 / AC-13). Orphan images (declared but unreferenced by
+  // any `textures[]` row) still produce a sub-asset; the importer assigns
+  // them colorSpace 'linear' (no colour-encoded purpose inferable). Without
+  // this loop the meta carries no `kind: 'texture'` row, AssetRegistry
+  // never imports the bytes, and the runtime renders a white box (G-2).
+  const images = doc.images ?? [];
+  for (let i = 0; i < images.length; i++) {
+    const img = images[i];
+    if (img === undefined) continue;
+    items.push({
+      kind: 'texture',
+      sourceIndex: i,
+      ...(img.name === undefined ? {} : { name: img.name }),
+    });
+  }
+  const samplers = doc.samplers ?? [];
+  for (let i = 0; i < samplers.length; i++) {
+    const sampler = samplers[i];
+    if (sampler === undefined) continue;
+    items.push({
+      kind: 'sampler',
+      sourceIndex: i,
+      ...(sampler.name === undefined ? {} : { name: sampler.name }),
+    });
+  }
+  // Skeletons (feat-20260523-skin-skeleton-animation M0).
+  for (let i = 0; i < doc.skeletons.length; i++) {
+    items.push({ kind: 'skeleton', sourceIndex: i });
+  }
+  // Skin bindings (feat-20260523-skin-skeleton-animation M0).
+  // Emit one skin sub-asset per GltfSkeletonRecord (1:1 mapping).
+  for (let i = 0; i < doc.skeletons.length; i++) {
+    items.push({ kind: 'skin', sourceIndex: i });
+  }
+  // Animation clips (feat-20260523-skin-skeleton-animation M0).
+  for (let i = 0; i < doc.animationClips.length; i++) {
+    const clip = doc.animationClips[i];
+    if (clip === undefined) continue;
+    items.push({
+      kind: 'animation-clip',
+      sourceIndex: i,
+      ...(clip.name === undefined ? {} : { name: clip.name }),
+    });
+  }
+
+  const reuse = reimportReuseMeta(items, existingMeta);
+  if (!reuse.ok) return reuse;
+  const subAssetByKindIndex = new Map(
+    reuse.value.subAssets.map((entry) => [`${entry.kind}:${entry.sourceIndex}`, entry]),
+  );
+  const sourceOverrides: Record<string, Readonly<Record<string, unknown>>> = {
+    ...(existingMeta?.sourceOverrides ?? {}),
+  };
+  for (const meshIndex of seenMeshIndices) {
+    const meshOutput = subAssetByKindIndex.get(`mesh:${meshIndex}`);
+    if (meshOutput?.sourceKey === undefined) continue;
+    const materialSlots: MeshMaterialSlotTopologyEntry[] = [];
+    const slotByMaterial = new Map<number | null, number>();
+    const usedNames = new Set<string>();
+    const uniqueName = (raw: string): string => {
+      const base = raw.trim() || 'Material';
+      let candidate = base;
+      let suffix = 2;
+      while (usedNames.has(candidate)) candidate = `${base}_${suffix++}`;
+      usedNames.add(candidate);
+      return candidate;
+    };
+    for (const primitive of doc.meshes.filter((mesh) => mesh.meshIndex === meshIndex)) {
+      const materialIndex = primitive.materialIndex;
+      if (slotByMaterial.has(materialIndex)) continue;
+      const materialOutput =
+        materialIndex === null ? undefined : subAssetByKindIndex.get(`material:${materialIndex}`);
+      slotByMaterial.set(materialIndex, materialSlots.length);
+      materialSlots.push({
+        slotName: uniqueName(
+          materialIndex === null
+            ? 'Default'
+            : (doc.materials[materialIndex]?.name ?? `Material_${materialIndex}`),
+        ),
+        sourceKey:
+          materialIndex === null
+            ? 'gltf:default'
+            : (materialOutput?.sourceKey ?? `gltf:material:${materialIndex}`),
+        ...(materialOutput === undefined ? {} : { defaultMaterialGuid: materialOutput.guid }),
+      });
+    }
+    const previousPayload = existingMeta?.sourceOverrides?.[meshOutput.sourceKey];
+    const previousRaw = previousPayload?.materialSlots;
+    const previous = Array.isArray(previousRaw)
+      ? previousRaw.filter(
+          (slot): slot is MeshMaterialSlotTopologyEntry =>
+            slot !== null &&
+            typeof slot === 'object' &&
+            !Array.isArray(slot) &&
+            typeof (slot as { slotName?: unknown }).slotName === 'string',
+        )
+      : [];
+    const reconciled = reconcileMeshMaterialSlotTopology(materialSlots, previous);
+    if (!reconciled.ok) {
+      return err({
+        code: 'mesh-material-slot-topology-change',
+        expected: `unambiguous material slot identity for mesh ${meshOutput.guid}`,
+        hint: reconciled.error.hint,
+        detail: {
+          sourceIndices: reconciled.error.nextIndices,
+          previousIndices: reconciled.error.previousIndices,
+        },
+      });
+    }
+    sourceOverrides[meshOutput.sourceKey] = {
+      ...(previousPayload ?? {}),
+      materialSlots: reconciled.slots,
+    };
+  }
+  const meta: GltfMetaJson = {
+    schemaVersion: 1,
+    kind: 'external-asset-package',
+    importer: 'gltf',
+    source,
+    subAssets: reuse.value.subAssets,
+    ...(Object.keys(sourceOverrides).length === 0 ? {} : { sourceOverrides }),
+    sourceOverrideDescriptors: reuse.value.subAssets
+      .filter((entry) => entry.kind === 'mesh' && entry.sourceKey !== undefined)
+      .map((entry) => ({
+        sourceKey: entry.sourceKey as string,
+        semantic: 'mesh-material-slot-defaults' as const,
+        payloadSchema: MESH_MATERIAL_SLOT_SOURCE_OVERRIDE_PAYLOAD_SCHEMA,
+      })),
+    importSettings: {
+      defaultSceneIndex: doc.defaultSceneIndex,
+      ...(typeof existingMeta?.importSettings.standardMaterialGuid === 'string'
+        ? { standardMaterialGuid: existingMeta.importSettings.standardMaterialGuid }
+        : {}),
+      ...(existingMeta?.importSettings.downscaleMaxDimension !== undefined
+        ? { downscaleMaxDimension: existingMeta.importSettings.downscaleMaxDimension }
+        : {}),
+      diagnostics: {
+        nodeNames: doc.diagnostics.nodeNames,
+        unsupportedExtensions: doc.diagnostics.unsupportedExtensions,
+        matrixTrsCoexistNodes: doc.diagnostics.matrixTrsCoexistNodes,
+      },
+    },
+  };
+  return ok({ meta, subAssets: reuse.value.subAssets });
+}
+
+// Suppress unused-import warning; COMPONENT_TYPE is re-exported so
+// downstream consumers can grep the constants table from a single
+// import. (TS strict mode would otherwise drop the binding.)
+export { COMPONENT_TYPE };