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

package/src/image-color-space.ts

@@ -0,0 +1,104 @@
+// image-color-space.ts - sRGB / linear classifier for glTF images
+// (feat-20260608 M3 D-3 / requirements AC-08 + AC-13 + C-3).
+//
+// glTF 2.0 spec section 6.2 ("Material → Texture and Sampler") names which
+// texture slots are colour-encoded vs data-encoded:
+//   - sRGB    : baseColorTexture, emissiveTexture
+//   - linear  : metallicRoughnessTexture, normalTexture, occlusionTexture
+// MaterialIr carries baseColor / metallicRoughness / normal / emissive;
+// occlusion remains outside this Tier-C subset.
+// We pre-scan the doc so the gltfImporter knows each `images[]` row's
+// colorSpace before decoding (TextureAsset.colorSpace + .format derive
+// from this).
+//
+// Conflict resolution (requirements section 8 edge cases): when the same
+// glTF image is bound to multiple textures whose colour expectations
+// disagree, sRGB wins. baseColor leakage into a normal slot is far worse
+// than the inverse, and bevy_gltf takes the same stance (knowledge-base /
+// research finding §5.6).
+//
+// Orphan images (declared in `images[]` but unreferenced by any
+// `textures[]` entry) default to linear (no colour-encoded purpose
+// inferable; AC-13).
+//
+// Pure function, no I/O. Input = the parts of the parsed GltfDoc that
+// matter (images count, textures, materials); output = a Map keyed by
+// the image array index.
+
+export type ImageColorSpaceSrgbOrLinear = 'srgb' | 'linear';
+
+type TextureBinding = number | { readonly texture: number };
+
+/** Slim view of a parsed material the classifier reads (subset of MaterialIr). */
+export interface MaterialColorSpaceInput {
+  readonly baseColorTexture?: TextureBinding;
+  readonly metallicRoughnessTexture?: TextureBinding;
+  readonly normalTexture?: TextureBinding;
+  readonly emissiveTexture?: TextureBinding;
+  readonly occlusionTexture?: TextureBinding;
+}
+
+/** Slim view of a parsed `textures[]` row. */
+export interface TextureColorSpaceInput {
+  readonly source: number;
+}
+
+/**
+ * Inputs for {@link deriveTextureColorSpace}: just the parts of the parsed
+ * doc that the classifier reads. Decoupled from `GltfDoc` so the helper is
+ * trivially testable without building a full doc.
+ */
+export interface DeriveTextureColorSpaceInput {
+  readonly imageCount: number;
+  readonly textures: readonly TextureColorSpaceInput[] | undefined;
+  readonly materials: readonly MaterialColorSpaceInput[];
+}
+
+/**
+ * Walk the materials, follow each texture-slot binding back to the image
+ * it references, and produce `Map<imageIndex, 'srgb' | 'linear'>`. Slots
+ * disagreeing on the same image resolve to sRGB (see module header for
+ * the rationale). Orphan images default to linear.
+ */
+export function deriveTextureColorSpace(
+  input: DeriveTextureColorSpaceInput,
+): Map<number, ImageColorSpaceSrgbOrLinear> {
+  const result = new Map<number, ImageColorSpaceSrgbOrLinear>();
+  const textures = input.textures ?? [];
+
+  function imageOfTexture(binding: TextureBinding | undefined): number | undefined {
+    if (binding === undefined) return undefined;
+    const textureIndex = typeof binding === 'number' ? binding : binding.texture;
+    const tex = textures[textureIndex];
+    if (tex === undefined) return undefined;
+    return tex.source;
+  }
+
+  function record(imageIndex: number | undefined, colorSpace: ImageColorSpaceSrgbOrLinear): void {
+    if (imageIndex === undefined) return;
+    const prior = result.get(imageIndex);
+    if (prior === undefined) {
+      result.set(imageIndex, colorSpace);
+      return;
+    }
+    if (prior === 'srgb' || colorSpace === 'srgb') {
+      result.set(imageIndex, 'srgb');
+    }
+  }
+
+  for (const mat of input.materials) {
+    record(imageOfTexture(mat.baseColorTexture), 'srgb');
+    record(imageOfTexture(mat.emissiveTexture), 'srgb');
+    record(imageOfTexture(mat.metallicRoughnessTexture), 'linear');
+    record(imageOfTexture(mat.normalTexture), 'linear');
+    record(imageOfTexture(mat.occlusionTexture), 'linear');
+  }
+
+  for (let i = 0; i < input.imageCount; i++) {
+    if (!result.has(i)) {
+      result.set(i, 'linear');
+    }
+  }
+
+  return result;
+}

package/src/importer-entry.ts

@@ -0,0 +1,24 @@
+import { MeshoptDecoder } from 'meshoptimizer';
+import { createGltfImporter } from './gltf-importer.js';
+import type { GltfBufferViewDecodeCapability } from './meshopt-decode.js';
+
+await MeshoptDecoder.ready;
+
+/** Browser/build consumer capability for EXT_meshopt_compression. */
+export const meshoptDecoder: GltfBufferViewDecodeCapability = {
+  decode: ({ source, count, stride, mode, filter }) => {
+    const target = new Uint8Array(count * stride);
+    MeshoptDecoder.decodeGltfBuffer(target, count, stride, source, mode, filter);
+    return target;
+  },
+};
+
+/**
+ * Build-only glTF importer entry. The player-facing package remains free of
+ * the Meshopt WASM dependency; hosts opt into this entry when importing files.
+ */
+export const gltfImporter = createGltfImporter({
+  decode: meshoptDecoder.decode,
+});
+
+export { createGltfImporter } from './gltf-importer.js';

package/src/index.ts

@@ -0,0 +1,148 @@
+// @forgeax/engine-gltf - runtime glTF 2.0 importer (Tier-B subset).
+//
+// M2 surface: pure-function pipeline `parseGlb` / `parseGltf` /
+// `toAssetPack` plus helpers `parseGltfHeader` / `parseGlbChunks` /
+// `decodeAccessor` / `decomposeNodeTransform` / `subAssetKey` /
+// `reimportReuseMeta` / `checkExtensions`.
+// M3 adds the file-entry stubs `parseGltfFromFile` / `parseGlbFromFile`.
+//
+// Surface contract anchors:
+// - plan-strategy section 3.1 (component map gltf_pkg.Pure / Helpers / Errors)
+// - plan-strategy section 8 "Naming convention" (parseGlb / parseGltf /
+//   toAssetPack lowercase camel; gltf word lowercase)
+// - GltfErrorCode closed union + GltfErrorDetail discriminated
+//   detail live in @forgeax/engine-types as the SSOT (decision section
+//   2.3); the single-import surface re-exports them here.
+
+// Sub-asset POD SSOT re-exports (from @forgeax/engine-types; replaces
+// the old unprefixed Ir types which are now Gltf-prefixed exports above).
+export type {
+  AnimationChannelPod,
+  AnimationClipPod,
+  AnimationSamplerPod,
+  MaterialPod,
+  MeshPod,
+  MeshSubmeshPod,
+  SceneEntityPod,
+  ScenePod,
+  SkeletonPod,
+  SkinPod,
+  SkinVertexInfluencePod,
+  TexturePod,
+} from '@forgeax/engine-types';
+export type {
+  AccessorJson,
+  AccessorRole,
+  BufferViewJson,
+  ComponentTypeId,
+  DecodeAccessorInput,
+  DecodedAccessor,
+} from './accessor/decode-accessor.js';
+// Accessor decoder (w9).
+export { COMPONENT_TYPE, decodeAccessor } from './accessor/decode-accessor.js';
+export type { DecodeColorAccessorInput } from './accessor/decode-color.js';
+export { decodeColorAccessor } from './accessor/decode-color.js';
+export type { GltfBridgeContext, MaterialBridgeContext } from './bridge.js';
+// Bridge: gltfDocToSceneAsset + toMaterialAsset + meshIrToMeshAsset (SSOT for
+// hello-gltf + hello-gltf-instancing, feat-20260518 M3 w9; M3 Tier-C material
+// bridge; meshIrToMeshAsset excised from the hello-gltf demo in
+// feat-20260603-asset-import-loader-injection M2 w19).
+export { gltfDocToSceneAsset, meshIrToMeshAsset, toMaterialAsset } from './bridge.js';
+export type { ExtensionsCheckResult, GltfExtensionsJson } from './check-extensions.js';
+// KHR extensions gate (w14).
+export { checkExtensions, EXTENSION_ALLOWLIST } from './check-extensions.js';
+export type {
+  GltfAccessorTypeMismatchDetail,
+  GltfAnimationCubicsplineUnsupportedDetail,
+  GltfBufferOutOfBoundsDetail,
+  GltfColorAccessorMalformedDetail,
+  GltfColorAccessorUnsupportedDetail,
+  GltfError,
+  GltfErrorCode,
+  GltfErrorDetail,
+  GltfExtensionUnsupportedDetail,
+  GltfImageExtractFailedDetail,
+  GltfImageMimeUnsupportedDetail,
+  GltfInstancingCountMismatchDetail,
+  GltfMalformedHeaderDetail,
+  GltfMetaMissingDetail,
+  GltfMorphInvalidDetail,
+  GltfMorphUnsupportedDetail,
+  GltfSkinAttrAsymmetricDetail,
+  GltfSkinJointCountExceededDetail,
+  GltfSkinJointNameMissingDetail,
+  GltfTextureLoadFailedDetail,
+  GltfVersionUnsupportedDetail,
+  Result,
+} from './errors.js';
+// Errors / Result alias / factory (errors.ts SSOT re-exports).
+export { err, GLTF_ERROR_HINTS, gltfErr, ok } from './errors.js';
+// gltfImporter: the build-time `{ key: 'gltf', import }` Importer
+// (feat-20260603-asset-import-loader-injection M2 / w19).
+export { gltfImporter } from './gltf-importer.js';
+export type { GlbChunks } from './parse-glb-chunks.js';
+// Header / chunk parsers (w8).
+export { parseGlbChunks, parseGltfHeader } from './parse-glb-chunks.js';
+export type {
+  ExternalLoader,
+  GltfAssetPack,
+  GltfAssetPackResult,
+  GltfDiagnosticsIr,
+  GltfDoc,
+  GltfImageIr,
+  GltfMaterialIr,
+  GltfMeshIr,
+  GltfNodeIr,
+  GltfNormalTextureInfoIr,
+  GltfOcclusionTextureInfoIr,
+  GltfSamplerIr,
+  GltfSceneIr,
+  GltfTextureInfoIr,
+  GltfTextureIr,
+  GltfTextureTransformIr,
+  MeshJson,
+  MeshPrimitiveJson,
+  NodeInstancingIr,
+} from './parse-gltf.js';
+// Main pipeline (w15 + w17) + file-entry wrappers (w19).
+export { parseGlb, parseGltf, toAssetPack } from './parse-gltf.js';
+// File-entry wrappers (parseGltfFromFile / parseGlbFromFile) live in
+// `./node-file-entry.ts` and ship under the `./node` sub-entry to keep
+// the main entry browser-clean -- they touch `node:fs/promises` /
+// `node:path` via dynamic import and would otherwise trip vite's "module
+// externalized for browser compatibility" warning when consumers bundle
+// the demo for the browser. Node consumers:
+//
+//     import { parseGltfFromFile } from '@forgeax/engine-gltf/node';
+export type { GltfHeaderJson } from './parse-gltf-header.js';
+export type {
+  GltfDocItem,
+  GltfMetaJson,
+  GltfSubAssetEntry,
+  ReimportReuseResult,
+  ReimportReuseValue,
+  SubAssetKey,
+} from './reimport-reuse-meta.js';
+// Sub-asset key + reimport-reuse algorithm (w13).
+export {
+  reimportReuseMeta,
+  subAssetKey,
+} from './reimport-reuse-meta.js';
+// Byte-stable meta JSON serialization (D-3; AC-04).
+export { serializeMetaJson } from './serialize-meta.js';
+export type {
+  GltfSourceKeyConflictEntry,
+  GltfSourceKeyError,
+  GltfSourceKeyErrorCode,
+  GltfSourceKeyResult,
+} from './source-key.js';
+export { deriveGltfSourceKeys, sourceKeyForGltfOutput } from './source-key.js';
+export type {
+  DecomposedTransform,
+  NodeTransformJson,
+  TransformDiagnostics,
+  Vec3Tuple,
+  Vec4Tuple,
+} from './transform.js';
+// Node transform decomposer (w11).
+export { decomposeNodeTransform } from './transform.js';

package/src/meshopt-decode.ts

@@ -0,0 +1,200 @@
+import type { BufferViewJson } from './accessor/decode-accessor.js';
+import {
+  err,
+  GLTF_MESHOPT_FILTERS,
+  GLTF_MESHOPT_MODES,
+  type GltfError,
+  type GltfMeshoptFilter,
+  type GltfMeshoptMode,
+  gltfErr,
+  ok,
+  type Result,
+} from './errors.js';
+
+export type MeshoptMode = GltfMeshoptMode;
+export type MeshoptFilter = GltfMeshoptFilter;
+
+export interface MeshoptCompressionJson {
+  readonly buffer: number;
+  readonly byteOffset?: number;
+  readonly byteLength: number;
+  readonly byteStride: number;
+  readonly count: number;
+  readonly mode: MeshoptMode;
+  readonly filter?: MeshoptFilter;
+}
+
+export interface MeshoptBufferViewJson extends BufferViewJson {
+  readonly extensions?: {
+    readonly EXT_meshopt_compression?: MeshoptCompressionJson;
+  };
+}
+
+export interface GltfBufferViewDecodeCapability {
+  readonly decode: (input: {
+    readonly source: Uint8Array;
+    readonly count: number;
+    readonly stride: number;
+    readonly mode: MeshoptMode;
+    readonly filter: MeshoptFilter;
+  }) => Uint8Array | Promise<Uint8Array>;
+}
+
+export interface MeshoptProjection {
+  readonly bufferViews: readonly MeshoptBufferViewJson[];
+  readonly buffers: readonly Uint8Array[];
+  readonly decodedCount: number;
+}
+
+function viewBytes(
+  view: MeshoptBufferViewJson,
+  buffers: readonly Uint8Array[],
+): Uint8Array | undefined {
+  const buffer = buffers[view.buffer];
+  const offset = view.byteOffset ?? 0;
+  if (
+    buffer === undefined ||
+    view.byteLength <= 0 ||
+    offset < 0 ||
+    offset + view.byteLength > buffer.length
+  ) {
+    return undefined;
+  }
+  return buffer.subarray(offset, offset + view.byteLength);
+}
+
+function validMode(mode: string): mode is MeshoptMode {
+  return GLTF_MESHOPT_MODES.some((candidate) => candidate === mode);
+}
+
+function validFilter(filter: string): filter is MeshoptFilter {
+  return GLTF_MESHOPT_FILTERS.some((candidate) => candidate === filter);
+}
+
+function filterAllowed(mode: MeshoptMode, filter: MeshoptFilter): boolean {
+  return mode === 'ATTRIBUTES' || filter === 'NONE';
+}
+
+/**
+ * Resolve EXT_meshopt_compression bufferViews before any accessor consumer.
+ * Optional assets keep a valid core bufferView fallback when no decoder is
+ * installed; required or compressed-only assets fail with a structured error.
+ */
+export async function projectMeshoptBufferViews(
+  inputViews: readonly MeshoptBufferViewJson[],
+  inputBuffers: readonly Uint8Array[],
+  extensionsRequired: readonly string[],
+  capability?: GltfBufferViewDecodeCapability,
+): Promise<Result<MeshoptProjection, GltfError>> {
+  const buffers = [...inputBuffers];
+  const bufferViews = inputViews.map((view) => ({ ...view }));
+  let decodedCount = 0;
+
+  for (let index = 0; index < bufferViews.length; index++) {
+    const view = bufferViews[index];
+    if (view === undefined) continue;
+    const extension = view.extensions?.EXT_meshopt_compression;
+    if (extension === undefined) continue;
+
+    const filter = extension.filter ?? 'NONE';
+    if (
+      !validMode(extension.mode) ||
+      !validFilter(filter) ||
+      !filterAllowed(extension.mode, filter) ||
+      !Number.isInteger(extension.byteStride) ||
+      extension.byteStride <= 0 ||
+      !Number.isInteger(extension.count) ||
+      extension.count <= 0 ||
+      !Number.isInteger(extension.byteLength) ||
+      extension.byteLength <= 0
+    ) {
+      return err(
+        gltfErr('gltf-meshopt-decode-failed', {
+          bufferView: index,
+          actual: 'invalid mode/filter/stride/count/byteLength',
+          mode: validMode(extension.mode) ? extension.mode : 'ATTRIBUTES',
+          filter: validFilter(filter) ? filter : 'NONE',
+        }),
+      );
+    }
+
+    const fallback = viewBytes(view, buffers);
+    const required = extensionsRequired.includes('EXT_meshopt_compression');
+    if (capability === undefined && !required && fallback !== undefined) continue;
+    if (capability === undefined) {
+      return err(
+        gltfErr('gltf-meshopt-decoder-required', {
+          bufferView: index,
+          actual: required ? 'required' : 'compressed-only',
+          hasCoreFallback: fallback !== undefined,
+        }),
+      );
+    }
+
+    const compressedBuffer = buffers[extension.buffer];
+    const compressedOffset = extension.byteOffset ?? 0;
+    if (
+      compressedBuffer === undefined ||
+      !Number.isInteger(compressedOffset) ||
+      compressedOffset < 0 ||
+      compressedOffset + extension.byteLength > compressedBuffer.length
+    ) {
+      return err(
+        gltfErr('gltf-meshopt-decode-failed', {
+          bufferView: index,
+          actual: 'compressed range out of bounds',
+          mode: extension.mode,
+          filter,
+        }),
+      );
+    }
+
+    let decoded: Uint8Array;
+    try {
+      decoded = await capability.decode({
+        source: compressedBuffer.subarray(
+          compressedOffset,
+          compressedOffset + extension.byteLength,
+        ),
+        count: extension.count,
+        stride: extension.byteStride,
+        mode: extension.mode,
+        filter,
+      });
+    } catch (cause) {
+      return err(
+        gltfErr('gltf-meshopt-decode-failed', {
+          bufferView: index,
+          actual: `decoder rejected compressed range: ${cause instanceof Error ? cause.message : String(cause)}`,
+          mode: extension.mode,
+          filter,
+        }),
+      );
+    }
+
+    const expectedLength = extension.count * extension.byteStride;
+    if (!(decoded instanceof Uint8Array) || decoded.byteLength !== expectedLength) {
+      return err(
+        gltfErr('gltf-meshopt-decode-failed', {
+          bufferView: index,
+          actual: `decoded byteLength=${decoded?.byteLength ?? 'invalid'}, expected=${expectedLength}`,
+          mode: extension.mode,
+          filter,
+        }),
+      );
+    }
+
+    const decodedBufferIndex = buffers.length;
+    buffers.push(decoded);
+    const { extensions: _extensions, ...plainView } = view;
+    bufferViews[index] = {
+      ...plainView,
+      buffer: decodedBufferIndex,
+      byteOffset: 0,
+      byteLength: expectedLength,
+    };
+    decodedCount++;
+  }
+
+  return ok({ bufferViews, buffers, decodedCount });
+}

package/src/node-file-entry.ts

@@ -0,0 +1,98 @@
+// File-entry wrappers (Node-only, dynamic-import isolated).
+//
+// `parseGltfFromFile` / `parseGlbFromFile` are the only members of this
+// package that touch the filesystem. They live in this dedicated module so
+// the main entry (`index.ts`) stays browser-clean: the `node:fs/promises`
+// and `node:path` dynamic imports below would otherwise trip vite's
+// "module externalized for browser compatibility" warning when the demo
+// bundles `@forgeax/engine-gltf` for the browser even though it never
+// calls these helpers.
+//
+// Sidecar policy (feat-20260521 unify-sidecar-meta-dispatch-by-content):
+//   <name>.gltf -> <name>.gltf.meta.json
+//   <name>.glb  -> <name>.glb.meta.json
+//
+// Both wrappers add a single fail-fast pre-step: stat the sibling
+// `<source>.meta.json`; return `gltf-meta-missing` if absent (same code
+// surfaced by the vite-plugin and the console CLI dry-run, charter
+// proposition 5 consistent abstraction). Callers with an ArrayBuffer /
+// parsed JSON should keep using `parseGltf` / `parseGlb` directly.
+
+import { err, type GltfError, gltfErr, type Result } from './errors.js';
+import { type ExternalLoader, type GltfDoc, parseGlb, parseGltf } from './parse-gltf.js';
+
+interface FsLike {
+  readonly stat: (path: string) => Promise<unknown>;
+  readonly readFile: (path: string) => Promise<Buffer>;
+}
+
+interface PathLike {
+  readonly dirname: (p: string) => string;
+  readonly resolve: (...segments: string[]) => string;
+}
+
+async function loadFsModule(): Promise<FsLike> {
+  const mod = (await import('node:fs/promises')) as unknown as FsLike;
+  return mod;
+}
+
+async function loadPathModule(): Promise<PathLike> {
+  const mod = (await import('node:path')) as unknown as PathLike;
+  return mod;
+}
+
+async function statExists(fs: FsLike, path: string): Promise<boolean> {
+  try {
+    await fs.stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function metaPathFor(filePath: string): string {
+  return `${filePath}.meta.json`;
+}
+
+/**
+ * Parse a `.gltf` file from disk. Pre-step: stat the sibling
+ * `<source>.meta.json`; if missing, return `gltf-meta-missing` without
+ * reading the source bytes.
+ */
+export async function parseGltfFromFile(filePath: string): Promise<Result<GltfDoc, GltfError>> {
+  const fs = await loadFsModule();
+  const path = await loadPathModule();
+  const expectedMetaPath = metaPathFor(filePath);
+  if (!(await statExists(fs, expectedMetaPath))) {
+    return err(gltfErr('gltf-meta-missing', { filePath, expectedMetaPath }));
+  }
+  const text = (await fs.readFile(filePath)).toString('utf-8');
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch (_e) {
+    return err(gltfErr('gltf-malformed-header', { filePath, byteOffset: 0 }));
+  }
+  const baseDir = path.dirname(filePath);
+  const externalLoader: ExternalLoader = async (uri: string) => {
+    const abs = path.resolve(baseDir, uri);
+    const buf = await fs.readFile(abs);
+    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer;
+  };
+  return parseGltf(json, externalLoader, filePath);
+}
+
+/**
+ * Parse a `.glb` file from disk. Same fail-fast meta-stat pre-step as
+ * `parseGltfFromFile`.
+ */
+export async function parseGlbFromFile(filePath: string): Promise<Result<GltfDoc, GltfError>> {
+  const fs = await loadFsModule();
+  const expectedMetaPath = metaPathFor(filePath);
+  if (!(await statExists(fs, expectedMetaPath))) {
+    return err(gltfErr('gltf-meta-missing', { filePath, expectedMetaPath }));
+  }
+  const buf = await fs.readFile(filePath);
+  const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer;
+  return parseGlb(ab, filePath);
+}

package/src/node-path.ts

@@ -0,0 +1,41 @@
+export interface NamedNode {
+  readonly name?: string;
+  readonly children?: readonly number[];
+}
+
+export function buildNodeParentMap(nodes: readonly NamedNode[]): ReadonlyMap<number, number> {
+  const parents = new Map<number, number>();
+  for (let index = 0; index < nodes.length; index++) {
+    for (const child of nodes[index]?.children ?? []) parents.set(child, index);
+  }
+  return parents;
+}
+
+export function resolveNamedNodePath(
+  nodes: readonly NamedNode[],
+  parents: ReadonlyMap<number, number>,
+  nodeIndex: number,
+):
+  | { readonly ok: true; readonly value: readonly string[] }
+  | {
+      readonly ok: false;
+      readonly reason: 'name-missing' | 'hierarchy-cycle';
+      readonly nodeIndex: number;
+    } {
+  const reversed: string[] = [];
+  const visited = new Set<number>();
+  let current: number | undefined = nodeIndex;
+  while (current !== undefined) {
+    if (visited.has(current)) {
+      return { ok: false, reason: 'hierarchy-cycle', nodeIndex: current };
+    }
+    visited.add(current);
+    const name = nodes[current]?.name;
+    if (name === undefined || name.length === 0) {
+      return { ok: false, reason: 'name-missing', nodeIndex: current };
+    }
+    reversed.push(name);
+    current = parents.get(current);
+  }
+  return { ok: true, value: reversed.reverse() };
+}