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

package/src/parse-skin.ts

@@ -0,0 +1,238 @@
+// parse-skin.ts - glTF skin parser (feat-20260523-skin-skeleton-animation M0).
+//
+// Implements parseSkin(): parses glTF `skins[]` array into GltfSkeletonRecord[]
+// with IBM (inverse bind matrices) and jointPaths (Name-component path from
+// scene root). Used by parseGltfWithBin to populate GltfDoc.
+//
+// Decision anchors:
+//   - plan-strategy D-1 (3-asset separation: IBM / skin binding / animation clip)
+//   - plan-strategy D-2 (skin index dedupe via reimport reuse managed by toAssetPack)
+//   - requirements AC-03 (skin index dedupe), AC-05 (jointPaths + Name missing fail-fast)
+//   - requirements AC-10 (IR extension), AC-27 (BindPose static AABB)
+//   - plan-strategy D-11 (BindPose AABB importer-phase, per-frame zero cost)
+//   - charter P3 (fail-fast on invalid data)
+
+import { decodeF32Accessor } from './accessor/decode-accessor.js';
+import { err, type GltfError, gltfErr, ok, type Result } from './errors.js';
+import { buildNodeParentMap, resolveNamedNodePath } from './node-path.js';
+
+/** Maximum joints per skin (glTF spec practical limit). */
+const MAX_JOINTS = 256;
+
+/**
+ * Skeleton intermediate representation produced by parseSkin.
+ *
+ * Each entry corresponds to one glTF skin[] index. `jointPaths` is a
+ * parallel array to the skeleton's joints; each path is the sequence of
+ * Name-component values from the scene root to the joint node.
+ */
+export interface GltfSkeletonRecord {
+  /** Number of joints in this skeleton (= IBM length / 16). */
+  readonly jointCount: number;
+  /** Inverse bind matrices, Float32Array of length jointCount * 16. */
+  readonly inverseBindMatrices: Float32Array;
+  /** Per-joint Name path from scene root (parallel to joints array). */
+  readonly jointPaths: readonly string[];
+}
+
+interface SkinJson {
+  readonly name?: string;
+  readonly joints: readonly number[];
+  readonly inverseBindMatrices?: number;
+}
+
+interface NodeJson {
+  readonly name?: string;
+  readonly mesh?: number;
+  readonly children?: readonly number[];
+  readonly skin?: number;
+}
+
+interface AccessorJson {
+  readonly bufferView?: number;
+  readonly componentType: number;
+  readonly type: string;
+  readonly count: number;
+  readonly byteOffset?: number;
+}
+
+interface BufferViewJson {
+  readonly buffer: number;
+  readonly byteOffset?: number;
+  readonly byteLength: number;
+  readonly byteStride?: number;
+}
+
+const SKIN_ACCESSOR_TYPES = ['MAT4'] as const;
+
+/** Build a column-major mat4 identity Float32Array (16 floats). */
+function identityMat4(): Float32Array {
+  const m = new Float32Array(16);
+  m[0] = 1;
+  m[5] = 1;
+  m[10] = 1;
+  m[15] = 1;
+  return m;
+}
+
+/**
+ * Build the jointPath for a single joint: find the Name-component path from
+ * the root of the scene graph to the joint node.
+ *
+ * Uses recursive BFS-like upward traversal: for each joint node index,
+ * find the node's name and verify it's reachable from root.
+ * Returns the sequence of names from root to joint.
+ *
+ * On first miss (node has no name), emits 'gltf-skin-joint-name-missing'.
+ */
+function resolveJointPath(
+  nodeIndex: number,
+  nodes: readonly NodeJson[],
+  parentOf: ReadonlyMap<number, number>,
+  skinIndex: number,
+  jointPathIndex: number,
+): Result<readonly string[], GltfError> {
+  const path = resolveNamedNodePath(nodes, parentOf, nodeIndex);
+  if (!path.ok) {
+    return err(
+      gltfErr('gltf-skin-joint-name-missing', {
+        reason: path.reason,
+        skinIndex,
+        jointPathIndex,
+        nodeIndex: path.nodeIndex,
+      }),
+    );
+  }
+  return ok(path.value);
+}
+
+/**
+ * Parse glTF skins[] array into GltfSkeletonRecord[].
+ *
+ * For each skin:
+ * 1. Decode IBM accessor (or fill identity if absent)
+ * 2. Resolve jointPaths from scene node hierarchy
+ * 3. Fail-fast on joint count > MAX_JOINTS or missing joint names
+ */
+export function parseSkin(
+  skinsJson: readonly SkinJson[] | undefined,
+  nodesJson: readonly NodeJson[],
+  accessors: readonly AccessorJson[],
+  bufferViews: readonly BufferViewJson[],
+  buffers: readonly Uint8Array[],
+): Result<readonly GltfSkeletonRecord[], GltfError> {
+  if (skinsJson === undefined || skinsJson.length === 0) {
+    return ok([]);
+  }
+
+  const records: GltfSkeletonRecord[] = [];
+  const parentOf = buildNodeParentMap(nodesJson);
+
+  for (let skinIdx = 0; skinIdx < skinsJson.length; skinIdx++) {
+    const skin = skinsJson[skinIdx];
+    if (skin === undefined) continue;
+
+    const joints = skin.joints;
+    if (joints.length > MAX_JOINTS) {
+      return err(
+        gltfErr('gltf-skin-joint-count-exceeded', {
+          skinIndex: skinIdx,
+          jointCount: joints.length,
+          maxJoints: MAX_JOINTS,
+        }),
+      );
+    }
+
+    // Decode IBM, or fill identity matrix.
+    let ibm: Float32Array;
+    if (skin.inverseBindMatrices !== undefined) {
+      const ibmAccIdx = skin.inverseBindMatrices;
+      const ibmAcc = accessors[ibmAccIdx];
+      if (ibmAcc === undefined) {
+        return err(
+          gltfErr('gltf-buffer-out-of-bounds', {
+            accessor: ibmAccIdx,
+            byteOffset: 0,
+            byteLength: 0,
+            bufferIndex: 0,
+          }),
+        );
+      }
+      const ibmResult = decodeF32Accessor(
+        ibmAccIdx,
+        ibmAcc,
+        SKIN_ACCESSOR_TYPES,
+        bufferViews,
+        buffers,
+      );
+      if (!ibmResult.ok) return err(ibmResult.error);
+      ibm = ibmResult.value;
+    } else {
+      // Fill identity: each joint gets a 4x4 identity.
+      ibm = new Float32Array(joints.length * 16);
+      for (let j = 0; j < joints.length; j++) {
+        ibm.set(identityMat4(), j * 16);
+      }
+    }
+
+    // Resolve jointPaths.
+    const jointPaths: string[] = [];
+    for (let j = 0; j < joints.length; j++) {
+      const jointNodeIndex = joints[j];
+      if (jointNodeIndex === undefined) continue;
+      const pathResult = resolveJointPath(jointNodeIndex, nodesJson, parentOf, skinIdx, j);
+      if (!pathResult.ok) return err(pathResult.error);
+      jointPaths.push(pathResult.value.join('/'));
+    }
+
+    records.push({
+      jointCount: joints.length,
+      inverseBindMatrices: ibm,
+      jointPaths,
+    });
+  }
+
+  return ok(records);
+}
+
+/**
+ * Compute the BindPose static AABB for a skinned mesh's vertex positions.
+ *
+ * At bind pose, joint_bind = IBM^{-1}, so skinning collapses:
+ *   world_pos = Sum(w_i * joint_bind_i * IBM_i * local_pos) = local_pos
+ * Therefore the BindPose AABB is simply the local position bounds.
+ *
+ * Per-frame zero cost: stored in mesh asset metadata at importer time.
+ * Dynamic AABB for animated poses is deferred to OOS-skin-dyn-bounds.
+ *
+ * Returns { min: [x,y,z], max: [x,y,z] } or undefined if positions is empty.
+ */
+export function computeBindPoseAABB(positions: Float32Array):
+  | {
+      readonly min: readonly [number, number, number];
+      readonly max: readonly [number, number, number];
+    }
+  | undefined {
+  if (positions.length < 3) return undefined;
+  let minX = positions[0] ?? 0;
+  let minY = positions[1] ?? 0;
+  let minZ = positions[2] ?? 0;
+  let maxX = minX;
+  let maxY = minY;
+  let maxZ = minZ;
+  for (let i = 3; i < positions.length; i += 3) {
+    const x = positions[i] ?? 0;
+    const y = positions[i + 1] ?? 0;
+    const z = positions[i + 2] ?? 0;
+    if (x < minX) minX = x;
+    if (y < minY) minY = y;
+    if (z < minZ) minZ = z;
+    if (x > maxX) maxX = x;
+    if (y > maxY) maxY = y;
+    if (z > maxZ) maxZ = z;
+  }
+  return { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+}
+
+/** Re-export MAX_JOINTS for use by downstream modules. */
+export { MAX_JOINTS };

package/src/reimport-reuse-meta.ts

@@ -0,0 +1,134 @@
+// reimport-reuse-meta.ts - two-stage GUID matching for reimport-stable
+// `<source>.meta.json` with `importer: 'gltf'` (w13).
+//
+// Matching algorithm (plan-strategy decision section 2.4 + bevy comparison
+// wiki section 3):
+//
+//   For each new item produced by parseGltf in source iteration order:
+//     stage 1: existing entry with same (kind, name, indexFallback)  -> reuse
+//     stage 2: existing entry with same (kind, indexFallback) only   -> reuse
+//     fallback: AssetGuid.random() (UUIDv7 monotonic clock)
+//
+// Double-name hazard: when the SAME (kind, name) pair appears more than
+// once in the new items list, stage 1 cannot disambiguate. The producer
+// returns a structured source-key conflict before it can mint GUIDs or
+// publish output; sourceIndex remains a locator and is never promoted to
+// identity.
+//
+// AC anchors:
+//   - AC-05: byte-identical reimport when nothing changes (stage 1 reuse path)
+//   - AC-06: double-name conflict returns a structured source-key error
+//   - AC-13: reimport idempotency overall (no spurious GUID churn)
+
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { err, ok, type Result } from './errors.js';
+import {
+  deriveGltfSourceKeys,
+  type GltfSourceKeyError,
+  sourceKeyForGltfOutput,
+} from './source-key.js';
+import { type GltfDocItemLike, subAssetKey } from './sub-asset-key.js';
+
+export type { SubAssetKey } from './sub-asset-key.js';
+export { subAssetKey };
+export type GltfDocItem = GltfDocItemLike;
+
+/** Subset of `<source>.meta.json` fields (importer=gltf arm) touched by the reuse algorithm. */
+export interface GltfSubAssetEntry {
+  readonly guid: string;
+  readonly sourceIndex: number;
+  readonly kind: string;
+  readonly sourceKey?: string;
+  /** Optional display name copied from the current glTF output. */
+  readonly name?: string;
+}
+
+export interface GltfMetaJson {
+  readonly schemaVersion: 1;
+  readonly kind: 'external-asset-package';
+  readonly importer: 'gltf';
+  readonly source: string;
+  readonly subAssets: readonly GltfSubAssetEntry[];
+  readonly sourceOverrides?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  readonly sourceOverrideDescriptors?: readonly import('@forgeax/engine-types').SourceOverrideDescriptor[];
+  readonly importSettings: {
+    readonly defaultSceneIndex: number;
+    readonly standardMaterialGuid?: string;
+    readonly downscaleMaxDimension?: number;
+    readonly diagnostics: {
+      readonly nodeNames: readonly string[];
+      readonly unsupportedExtensions: readonly string[];
+      readonly matrixTrsCoexistNodes: readonly number[];
+    };
+  };
+}
+
+export interface ReimportReuseValue {
+  readonly subAssets: readonly GltfSubAssetEntry[];
+}
+
+export type ReimportReuseResult = Result<ReimportReuseValue, GltfSourceKeyError>;
+
+/**
+ * Apply the two-stage reuse algorithm to a freshly parsed item list.
+ * Returns the new `subAssets[]` array (preserving item order), or a
+ * structured source-key conflict before any output is published.
+ *
+ * Pure function: no fs / network / global state. `AssetGuid.random()` is
+ * the only entropy source; deterministic in absence of new items.
+ */
+export function reimportReuseMeta(
+  items: readonly GltfDocItem[],
+  existingMeta: GltfMetaJson | undefined,
+): ReimportReuseResult {
+  const sourceKeys = deriveGltfSourceKeys(items);
+  if (!sourceKeys.ok) return err(sourceKeys.error);
+
+  const stage1Index = new Map<string, GltfSubAssetEntry>();
+  const stage2Index = new Map<string, GltfSubAssetEntry>();
+  if (existingMeta !== undefined) {
+    for (const entry of existingMeta.subAssets) {
+      // Source names are display metadata, not identity. Semantic sourceKey
+      // remains the stage-1 identity and (kind, sourceIndex) remains the
+      // stage-2 locator fallback.
+      if (entry.sourceKey !== undefined) stage1Index.set(entry.sourceKey, entry);
+      stage2Index.set(`${entry.kind} ${entry.sourceIndex}`, entry);
+    }
+  }
+
+  const subAssets: GltfSubAssetEntry[] = [];
+  for (const item of items) {
+    const sourceKey = sourceKeyForGltfOutput(item);
+    const indexKey = `${item.kind} ${item.sourceIndex}`;
+    let reused: GltfSubAssetEntry | undefined;
+
+    // Stage 1: semantic sourceKey match. Names are copied from the current
+    // source output below, but never participate in identity matching.
+    if (sourceKey !== undefined) reused = stage1Index.get(sourceKey);
+    // Stage 2: (kind, indexFallback) only.
+    if (reused === undefined) {
+      reused = stage2Index.get(indexKey);
+    }
+
+    if (reused !== undefined) {
+      subAssets.push({
+        guid: reused.guid,
+        sourceIndex: item.sourceIndex,
+        kind: item.kind,
+        ...(sourceKey === undefined ? {} : { sourceKey }),
+        ...(item.name === undefined ? {} : { name: item.name }),
+      });
+    } else {
+      const fresh = AssetGuid.random();
+      subAssets.push({
+        guid: AssetGuid.format(fresh),
+        sourceIndex: item.sourceIndex,
+        kind: item.kind,
+        ...(sourceKey === undefined ? {} : { sourceKey }),
+        ...(item.name === undefined ? {} : { name: item.name }),
+      });
+    }
+  }
+
+  return ok({ subAssets });
+}

package/src/serialize-meta.ts

@@ -0,0 +1,24 @@
+// @forgeax/engine-gltf/src/serialize-meta.ts — byte-stable meta JSON
+// serialization (sorted-keys, LF ending) for the
+// `<source>.meta.json` sidecar. Extracted from cli-gltf.ts so it can
+// be re-exported from the package barrel as a reusable library
+// function (plan-strategy D-3; feat-20260705-editor-core-engine-convergence-store-ts-decompose AC-04).
+//
+// Anchors: plan-strategy D-3, requirements AC-04, research F-7.
+
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value !== null && typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = sortKeysDeep(obj[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+export function serializeMetaJson(meta: unknown): string {
+  return `${JSON.stringify(sortKeysDeep(meta), null, 2)}\n`;
+}

package/src/source-key.ts

@@ -0,0 +1,106 @@
+import type { GltfDocItemLike } from './sub-asset-key.js';
+
+interface GltfSourceKeyErrorBase {
+  readonly expected: string;
+  readonly hint: string;
+}
+
+export interface GltfSourceKeyConflictEntry {
+  readonly kind: string;
+  readonly name: string | null;
+  readonly sourceIndex: number;
+}
+
+export type GltfSourceKeyError =
+  | (GltfSourceKeyErrorBase & {
+      readonly code: 'missing-source-key';
+      readonly detail: { readonly sourceIndices: readonly number[] };
+    })
+  | (GltfSourceKeyErrorBase & {
+      readonly code: 'duplicate-source-key' | 'ambiguous-source-key';
+      readonly detail: {
+        readonly key: string;
+        readonly sourceIndices: readonly number[];
+        readonly entries: readonly GltfSourceKeyConflictEntry[];
+      };
+    })
+  | (GltfSourceKeyErrorBase & {
+      readonly code: 'mesh-material-slot-topology-change';
+      readonly detail: {
+        readonly sourceIndices: readonly number[];
+        readonly previousIndices: readonly number[];
+      };
+    });
+
+export type GltfSourceKeyErrorCode = GltfSourceKeyError['code'];
+
+export type GltfSourceKeyResult =
+  | { readonly ok: true; readonly keys: readonly string[]; readonly conflicts: readonly [] }
+  | { readonly ok: false; readonly error: GltfSourceKeyError };
+
+/** Derive a semantic glTF key; sourceIndex and source path are never inputs. */
+export function sourceKeyForGltfOutput(
+  item: Pick<GltfDocItemLike, 'kind' | 'name'>,
+): string | undefined {
+  const kind = item.kind.trim();
+  if (kind.length === 0) return undefined;
+  const name = item.name?.trim();
+  return name === undefined || name.length === 0 ? kind : `${kind}:${name}`;
+}
+
+/** Require every output in a multi-output declaration to carry a unique key. */
+export function deriveGltfSourceKeys(items: readonly GltfDocItemLike[]): GltfSourceKeyResult {
+  const keys = items.map((item) => sourceKeyForGltfOutput(item));
+  const missing = items
+    .map((item, index) => (keys[index] === undefined ? item.sourceIndex : undefined))
+    .filter((index): index is number => index !== undefined);
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      error: {
+        code: 'missing-source-key',
+        expected: 'every glTF output needs a stable semantic kind or name',
+        hint: 'publish a semantic kind/name key; do not use sourceIndex',
+        detail: { sourceIndices: missing },
+      },
+    };
+  }
+
+  const seen = new Map<string, GltfDocItemLike>();
+  for (let index = 0; index < keys.length; index++) {
+    const key = keys[index];
+    if (key === undefined) continue;
+    const current = items[index];
+    if (current === undefined) continue;
+    const prior = seen.get(key);
+    if (prior !== undefined) {
+      const entry = (item: GltfDocItemLike): GltfSourceKeyConflictEntry => {
+        const name = item.name?.trim();
+        return {
+          kind: item.kind.trim(),
+          name: name === undefined || name.length === 0 ? null : name,
+          sourceIndex: item.sourceIndex,
+        };
+      };
+      const ambiguous = key === current.kind.trim();
+      return {
+        ok: false,
+        error: {
+          code: ambiguous ? 'ambiguous-source-key' : 'duplicate-source-key',
+          expected: 'sourceKey values must be unique within one glTF package',
+          hint: ambiguous
+            ? 'name each otherwise anonymous output; do not use sourceIndex'
+            : 'rename duplicate outputs before publishing topology facts',
+          detail: {
+            key,
+            sourceIndices: [prior.sourceIndex, current.sourceIndex],
+            entries: [entry(prior), entry(current)],
+          },
+        },
+      };
+    }
+    seen.set(key, current);
+  }
+
+  return { ok: true, keys: keys as string[], conflicts: [] };
+}

package/src/sub-asset-key.ts

@@ -0,0 +1,61 @@
+// sub-asset-key.ts - sub-asset addressing key (w13).
+//
+// `subAssetKey` builds the deterministic three-tuple
+// `{ kind, name, indexFallback }` from a parsed GltfDoc item; the tuple
+// is the input to the two-stage matching algorithm in
+// `reimport-reuse-meta.ts`. Pure function, no I/O.
+//
+// `indexFallback` literal shape: `${pluralKind}/${sourceIndex}` (per
+// plan-decisions.md L-2 and bevy_gltf comparison wiki section 3 - forgeax
+// keeps the bevy `meshes/<i>` style anchor as the second-stage match key).
+// Pluralisation is closed: glTF 2.0 sub-asset categories are `mesh`,
+// `material`, `scene`, `node`, `texture`, `image`, `sampler`, `animation`,
+// `camera`, `skin`. Tier-B v1 only emits the first three; the closed map
+// fails closed for unrecognised inputs (charter proposition 4 explicit
+// failure - any new kind the importer learns to emit MUST be registered
+// here, otherwise the build break is the warning).
+
+export interface GltfDocItemLike {
+  readonly kind: string;
+  readonly sourceIndex: number;
+  readonly name?: string;
+}
+
+export interface SubAssetKey {
+  readonly kind: string;
+  readonly name: string | null;
+  readonly indexFallback: string;
+}
+
+const PLURAL: Readonly<Record<string, string>> = {
+  mesh: 'meshes',
+  material: 'materials',
+  scene: 'scenes',
+  node: 'nodes',
+  texture: 'textures',
+  image: 'images',
+  sampler: 'samplers',
+  animation: 'animations',
+  camera: 'cameras',
+  skin: 'skins',
+  skeleton: 'skeletons',
+  'animation-clip': 'animation-clips',
+};
+
+function pluraliseKind(kind: string): string {
+  const known = PLURAL[kind];
+  if (known !== undefined) return known;
+  // Unknown kinds fall back to a naive `+s` so `subAssetKey` stays total
+  // (no exception path); the importer will normally never emit an
+  // unknown kind because parseGltf only constructs items from the closed
+  // Tier-B list.
+  return `${kind}s`;
+}
+
+export function subAssetKey(item: GltfDocItemLike): SubAssetKey {
+  return {
+    kind: item.kind,
+    name: item.name ?? null,
+    indexFallback: `${pluraliseKind(item.kind)}/${item.sourceIndex}`,
+  };
+}

package/src/to-asset-pack.ts

@@ -0,0 +1,8 @@
+// to-asset-pack.ts - toAssetPack re-export shell (w17).
+//
+// `toAssetPack` itself lives in parse-gltf.ts (shares the GltfDoc IR
+// closure with parseGltf / parseGlb). This file is the named entry point
+// listed in plan-tasks.json target files; it re-exports the surface so
+// the package layout matches plan-strategy section 3.1 / gltf_pkg.Pure.
+
+export { toAssetPack } from './parse-gltf.js';

package/src/transform.ts

@@ -0,0 +1,117 @@
+// transform.ts - decomposeNodeTransform (w11).
+//
+// glTF 2.0 spec section 3.7 (node):
+//   - node.matrix     : 16 floats column-major (mutually exclusive with TRS,
+//                       per spec, but real-world DCC tools occasionally
+//                       export both - forgeax tolerates this with stderr
+//                       warn + diagnostics record per requirements section
+//                       boundary cases)
+//   - node.translation: VEC3 (default identity translation)
+//   - node.rotation   : VEC4 quaternion (default identity rotation)
+//   - node.scale      : VEC3 (default identity scale)
+//
+// This wrapper hides the math package's in-place 3-arg `mat4.decompose`
+// signature behind a POD readonly tuple return so the importer surface
+// stays Vec3/Quat brand-free at the API boundary (charter proposition 5
+// consistent abstraction; plan-strategy decision section 2.7 / OQ-2).
+
+import { mat4, quat, vec3 } from '@forgeax/engine-math';
+
+/** glTF VEC3 literal accepted by node.translation / node.scale. */
+export type Vec3Tuple = readonly [number, number, number];
+/** glTF VEC4 quaternion literal accepted by node.rotation. */
+export type Vec4Tuple = readonly [number, number, number, number];
+
+/** Minimal node JSON shape touched by the decomposer. */
+export interface NodeTransformJson {
+  readonly matrix?: readonly number[];
+  readonly translation?: readonly number[];
+  readonly rotation?: readonly number[];
+  readonly scale?: readonly number[];
+}
+
+/** Mutable diagnostics accumulator (writes to .matrixTrsCoexistNodes only). */
+export interface TransformDiagnostics {
+  matrixTrsCoexistNodes: number[];
+}
+
+export interface DecomposedTransform {
+  readonly translation: Vec3Tuple;
+  readonly rotation: Vec4Tuple;
+  readonly scale: Vec3Tuple;
+}
+
+const IDENTITY: DecomposedTransform = {
+  translation: [0, 0, 0] as const,
+  rotation: [0, 0, 0, 1] as const,
+  scale: [1, 1, 1] as const,
+};
+
+function tuple3(arr: readonly number[] | undefined, fallback: Vec3Tuple): Vec3Tuple {
+  if (arr === undefined || arr.length < 3) return fallback;
+  return [arr[0] ?? fallback[0], arr[1] ?? fallback[1], arr[2] ?? fallback[2]];
+}
+
+function tuple4(arr: readonly number[] | undefined, fallback: Vec4Tuple): Vec4Tuple {
+  if (arr === undefined || arr.length < 4) return fallback;
+  return [
+    arr[0] ?? fallback[0],
+    arr[1] ?? fallback[1],
+    arr[2] ?? fallback[2],
+    arr[3] ?? fallback[3],
+  ];
+}
+
+/**
+ * Decompose a glTF node's transform into a POD readonly TRS triple.
+ *
+ * Decision tree:
+ *   1. matrix present                -> mat4.decompose 3-arg in-place; if
+ *                                       any TRS field is also present,
+ *                                       stderr warn + push nodeIndex into
+ *                                       diagnostics.matrixTrsCoexistNodes.
+ *   2. only TRS fields present       -> use them verbatim (defaults filled).
+ *   3. nothing present               -> identity (0/0/0, 0/0/0/1, 1/1/1).
+ *
+ * Return type is `readonly` POD tuple, deliberately not Vec3/Quat from
+ * @forgeax/engine-math, so the importer's IR stays brand-free
+ * (plan-strategy decision section 2.7 / OQ-2).
+ */
+export function decomposeNodeTransform(
+  node: NodeTransformJson,
+  nodeIndex: number,
+  diagnostics: TransformDiagnostics,
+): DecomposedTransform {
+  const hasMatrix = node.matrix !== undefined && node.matrix.length === 16;
+  const hasTrs =
+    node.translation !== undefined || node.rotation !== undefined || node.scale !== undefined;
+
+  if (hasMatrix) {
+    if (hasTrs) {
+      console.error(`[warn] node[${nodeIndex}] has both matrix and TRS, matrix takes precedence`);
+      diagnostics.matrixTrsCoexistNodes.push(nodeIndex);
+    }
+    const out_t = vec3.create();
+    const out_r = quat.create();
+    const out_s = vec3.create(1, 1, 1);
+    // node.matrix is glTF column-major float[16]; mat4.decompose accepts
+    // Mat4Like (any indexable [0..15] number container).
+    const m = node.matrix as readonly number[];
+    mat4.decompose(out_t, out_r, out_s, m as unknown as Parameters<typeof mat4.decompose>[3]);
+    return {
+      translation: [out_t[0] ?? 0, out_t[1] ?? 0, out_t[2] ?? 0] as const,
+      rotation: [out_r[0] ?? 0, out_r[1] ?? 0, out_r[2] ?? 0, out_r[3] ?? 1] as const,
+      scale: [out_s[0] ?? 1, out_s[1] ?? 1, out_s[2] ?? 1] as const,
+    };
+  }
+
+  if (!hasTrs) {
+    return IDENTITY;
+  }
+
+  return {
+    translation: tuple3(node.translation, IDENTITY.translation),
+    rotation: tuple4(node.rotation, IDENTITY.rotation),
+    scale: tuple3(node.scale, IDENTITY.scale),
+  };
+}