@aura3d/assets 1.1.0 → 1.3.0

package/src/GLTFLoader.ts

@@ -387,6 +387,8 @@ export interface GLTFRuntimeMaterialKey {
 }
 
 export interface GLTFMorphTargetAsset {
+  /** Morph target / blendshape name (from `mesh.extras.targetNames`), when authored. */
+  readonly name?: string;
   readonly positions: readonly (readonly [number, number, number])[];
   readonly normals: readonly (readonly [number, number, number])[];
   readonly tangents: readonly (readonly [number, number, number])[];
@@ -842,13 +844,15 @@ export class GLTFLoader implements AssetLoader<GLTFAsset> {
         const typedTangents = tangents.map((tangent) => [tangent[0] ?? 0, tangent[1] ?? 0, tangent[2] ?? 0, tangent[3] ?? 1] as const);
         const typedColors = colors.map((color) => [color[0] ?? 1, color[1] ?? 1, color[2] ?? 1, color[3] ?? 1] as const);
         const typedJoints = joints.map((joint) => [joint[0] ?? 0, joint[1] ?? 0, joint[2] ?? 0, joint[3] ?? 0] as const);
+        const weightNormalization: SkinWeightNormalizationStats = { degenerate: 0, rescaled: 0 };
         const typedWeights = weights.map((weight) => normalizeSkinWeights([
           weight[0] ?? 0,
           weight[1] ?? 0,
           weight[2] ?? 0,
           weight[3] ?? 0
-        ], meshIndex, primitiveIndex));
-        const morphTargets = readMorphTargets(json, buffers, primitive, positions.length, meshIndex, primitiveIndex, accessorCache);
+        ], weightNormalization));
+        reportSkinWeightNormalization(meshIndex, primitiveIndex, weightNormalization);
+        const morphTargets = readMorphTargets(json, buffers, primitive, positions.length, meshIndex, primitiveIndex, accessorCache, readMorphTargetNames(mesh));
         const resolvedPrimitive = resolvePrimitiveMode(primitive, indices?.map((index) => index[0] ?? 0), positions.length, meshIndex, primitiveIndex);
         const geometry = createGeometryAsset(typedPositions, resolvedPrimitive.indices);
         return {
@@ -1459,7 +1463,8 @@ function readMorphTargets(
   vertexCount: number,
   meshIndex: number,
   primitiveIndex: number,
-  accessorCache: GLTFAccessorReadCache
+  accessorCache: GLTFAccessorReadCache,
+  targetNames: readonly string[] = []
 ): readonly GLTFMorphTargetAsset[] {
   if (primitive.targets === undefined) {
     return [];
@@ -1481,7 +1486,9 @@ function readMorphTargets(
     if (tangents.length > 0 && tangents.length !== vertexCount) {
       throw new Error(`glTF mesh ${meshIndex} primitive ${primitiveIndex} morph target ${targetIndex} TANGENT count mismatch`);
     }
+    const name = targetNames[targetIndex];
     return {
+      ...(typeof name === "string" && name.length > 0 ? { name } : {}),
       positions: positions.map((position) => [position[0] ?? 0, position[1] ?? 0, position[2] ?? 0] as const),
       normals: normals.map((normal) => [normal[0] ?? 0, normal[1] ?? 0, normal[2] ?? 0] as const),
       tangents: tangents.map((tangent) => [tangent[0] ?? 0, tangent[1] ?? 0, tangent[2] ?? 0] as const)
@@ -1489,6 +1496,17 @@ function readMorphTargets(
   });
 }
 
+// glTF stores morph-target names in `mesh.extras.targetNames` (a parallel array). Read them so the
+// runtime can expose named morph influences instead of bare indices.
+function readMorphTargetNames(mesh: GLTFMesh): readonly string[] {
+  const extras = (mesh as { extras?: Record<string, unknown> }).extras;
+  const names = extras?.targetNames;
+  if (Array.isArray(names) && names.every((n) => typeof n === "string")) {
+    return names as readonly string[];
+  }
+  return [];
+}
+
 function validateMorphTargetDescriptor(
   target: Readonly<Record<string, number>>,
   meshIndex: number,
@@ -1866,27 +1884,67 @@ function validateQuantizedAttributeComponentType(
   );
 }
 
-function normalizeSkinWeights(
+export interface SkinWeightNormalizationStats {
+  degenerate: number;
+  rescaled: number;
+}
+
+const SKIN_WEIGHT_DEGENERATE_EPSILON = 1e-6;
+
+/**
+ * Normalize a single vertex's 4 skin weights so they sum to 1.
+ *
+ * Real-world catalog GLBs (Objaverse/Sketchfab) frequently ship denormalized,
+ * negative, or all-zero WEIGHTS_0 values. Rather than hard-failing the whole
+ * asset, sanitize per vertex: negative/non-finite components are clamped to 0,
+ * a degenerate (near-zero) sum collapses to a rigid binding `[1, 0, 0, 0]`, and
+ * any other sum is rescaled to 1. The optional `stats` accumulator lets callers
+ * surface a single diagnostic per primitive instead of one per vertex.
+ *
+ * Component proportions are preserved regardless of the source accessor
+ * componentType (FLOAT 5126, or normalized UNSIGNED_BYTE 5121 / UNSIGNED_SHORT
+ * 5123), so integer-encoded weights normalize correctly without extra handling.
+ */
+export function normalizeSkinWeights(
   weights: readonly [number, number, number, number],
-  meshIndex: number,
-  primitiveIndex: number
+  stats?: SkinWeightNormalizationStats
 ): readonly [number, number, number, number] {
-  if (weights.some((weight) => !Number.isFinite(weight) || weight < 0)) {
-    throw new Error(`glTF mesh ${meshIndex} primitive ${primitiveIndex} WEIGHTS_0 must contain finite non-negative values`);
+  const sanitized: [number, number, number, number] = [
+    Number.isFinite(weights[0]) && weights[0] > 0 ? weights[0] : 0,
+    Number.isFinite(weights[1]) && weights[1] > 0 ? weights[1] : 0,
+    Number.isFinite(weights[2]) && weights[2] > 0 ? weights[2] : 0,
+    Number.isFinite(weights[3]) && weights[3] > 0 ? weights[3] : 0
+  ];
+  const sum = sanitized[0] + sanitized[1] + sanitized[2] + sanitized[3];
+  if (sum < SKIN_WEIGHT_DEGENERATE_EPSILON) {
+    if (stats) stats.degenerate += 1;
+    return [1, 0, 0, 0] as const;
   }
-  const sum = weights[0] + weights[1] + weights[2] + weights[3];
-  if (sum <= 0) {
-    throw new Error(`glTF mesh ${meshIndex} primitive ${primitiveIndex} WEIGHTS_0 must sum to a positive value`);
+  if (Math.abs(sum - 1) <= 1e-5) {
+    return sanitized as readonly [number, number, number, number];
   }
-  if (Math.abs(sum - 1) <= 1e-5) return weights;
+  if (stats) stats.rescaled += 1;
   return [
-    weights[0] / sum,
-    weights[1] / sum,
-    weights[2] / sum,
-    weights[3] / sum
+    sanitized[0] / sum,
+    sanitized[1] / sum,
+    sanitized[2] / sum,
+    sanitized[3] / sum
   ] as const;
 }
 
+function reportSkinWeightNormalization(
+  meshIndex: number,
+  primitiveIndex: number,
+  stats: SkinWeightNormalizationStats
+): void {
+  if (stats.degenerate === 0 && stats.rescaled === 0) return;
+  if (typeof console === "undefined" || typeof console.warn !== "function") return;
+  console.warn(
+    `glTF mesh ${meshIndex} primitive ${primitiveIndex} WEIGHTS_0 normalized: ` +
+      `${stats.degenerate} degenerate vertex(es) set to [1,0,0,0], ${stats.rescaled} rescaled to sum 1`
+  );
+}
+
 function createCameraAssets(json: GLTFJson): readonly GLTFCameraAsset[] {
   return (json.cameras ?? []).map((camera, index) => {
     if (camera.type === "perspective") {

package/src/GLTFRenderResources.ts

@@ -80,6 +80,13 @@ export interface GLTFRenderResourceOptions {
   readonly sceneIndex?: GLTFSceneCreateOptions["sceneIndex"];
   readonly sceneName?: GLTFSceneCreateOptions["sceneName"];
   readonly materialRenderStateOverrides?: readonly GLTFMaterialRenderStateOverride[];
+  /**
+   * When `true`, a texture that fails to fetch/decode aborts the whole asset load
+   * (legacy behavior). When omitted/`false` (default), the loader logs a warning
+   * and substitutes a neutral 1x1 texture so the material falls back to its
+   * `baseColorFactor` and the rest of the asset still loads.
+   */
+  readonly failOnMissingTexture?: boolean;
 }
 
 export interface GLTFMaterialRenderStateOverride {
@@ -392,7 +399,16 @@ export async function createGLTFRenderResources(
       return texture;
     } catch (error) {
       textureByImage.delete(cacheKey);
-      throw error;
+      if (options.failOnMissingTexture) {
+        throw error;
+      }
+      const reason = error instanceof Error ? error.message : String(error);
+      warnMissingGLTFTexture(textureAsset.name, image.uri, reason);
+      const fallback = createFallbackTexture(textureAsset.name, colorSpace);
+      const fallbackPromise = Promise.resolve(fallback);
+      textureByImage.set(cacheKey, fallbackPromise);
+      setTextureLibraryEntry(textureLibrary, textureAsset.name, colorSpace, fallback);
+      return fallback;
     }
   };
 
@@ -1534,7 +1550,15 @@ function createDefaultGLTFMaterial(mesh: GLTFMeshAsset, options: { readonly inst
   return new PBRMaterial(defaults);
 }
 
-function renderStateForGLTFMaterial(
+/**
+ * baseColorFactor alpha at or above this value is treated as fully opaque when
+ * deciding whether a `BLEND` material is a spurious-blend (ghost) case. 8-bit
+ * authoring rounds 255/255 to 1.0 but tools occasionally emit 0.996 (254/255),
+ * so we allow a small epsilon while still catching genuine fades.
+ */
+const BLEND_OPAQUE_ALPHA_THRESHOLD = 0.996;
+
+export function renderStateForGLTFMaterial(
   material: GLTFMaterialAsset,
   overrides: readonly GLTFMaterialRenderStateOverride[] = []
 ): Partial<RenderState> {
@@ -1550,9 +1574,40 @@ function renderStateForGLTFMaterial(
 }
 
 function requiresTransparentRenderState(material: GLTFMaterialAsset): boolean {
-  if (material.alphaMode === "BLEND") return true;
+  if (material.alphaMode === "BLEND") return !isEffectivelyOpaqueBlendMaterial(material);
   if (material.alphaMode !== "OPAQUE") return false;
   if (usesUnbackedScalarTransmission(material)) return false;
+  return materialHasTransmissionOrVolume(material);
+}
+
+/**
+ * Many catalog GLBs (notably Sketchfab exports) spuriously tag fully opaque
+ * materials with `alphaMode: "BLEND"`. The standard glTF blend equation over a
+ * fully opaque surface (baseColorFactor alpha == 1, no texel alpha in use) is a
+ * no-op, but enabling blend disables depth writes — so those characters render
+ * as translucent "ghosts" with broken depth sorting.
+ *
+ * When a BLEND material is provably opaque we treat it as OPAQUE (blend off,
+ * depthWrite on). The check is deliberately conservative: anything that could
+ * carry real transparency — alpha factor < 1, transmission/volume, or a
+ * meaningful alphaCutoff — keeps blending.
+ *
+ * Known edge case: a baseColorTexture's own alpha channel cannot be inspected
+ * here (images are decoded asynchronously and channel-usage is not tracked on
+ * the material), so a BLEND material that relies purely on per-texel texture
+ * alpha while keeping baseColorFactor alpha == 1 would be flattened to opaque.
+ * That pattern is rare in the wild (such assets normally use MASK or set the
+ * factor alpha < 1), and the override path (renderStateOverrides /
+ * GLTFMaterialRenderStateOverride) remains available to force blend back on.
+ */
+function isEffectivelyOpaqueBlendMaterial(material: GLTFMaterialAsset): boolean {
+  if (material.alphaMode !== "BLEND") return false;
+  if (material.baseColorFactor[3] < BLEND_OPAQUE_ALPHA_THRESHOLD) return false;
+  if (materialHasTransmissionOrVolume(material)) return false;
+  return true;
+}
+
+function materialHasTransmissionOrVolume(material: GLTFMaterialAsset): boolean {
   return (material.transmission?.factor ?? 0) > 0.001
     || (material.diffuseTransmission?.factor ?? 0) > 0.001
     || (material.volume?.thicknessFactor ?? 0) > 0.001
@@ -2096,10 +2151,54 @@ function isKTX2BasisImage(image: GLTFImageAsset): boolean {
   return image.mimeType === "image/ktx2" || /\.ktx2(?:[?#]|$)/i.test(image.uri ?? "");
 }
 
+function createFallbackTexture(label: string, colorSpace: GLTFTextureColorSpace): Texture {
+  return new Texture({
+    width: 1,
+    height: 1,
+    colorSpace,
+    label: `${label} (missing-texture-fallback)`,
+    data: new Uint8Array([255, 255, 255, 255])
+  });
+}
+
+function warnMissingGLTFTexture(textureName: string, imageUri: string | undefined, reason: string): void {
+  if (typeof console === "undefined" || typeof console.warn !== "function") return;
+  const source = imageUri ? ` (${imageUri})` : "";
+  console.warn(
+    `glTF texture "${textureName}"${source} could not be loaded; falling back to baseColorFactor. Reason: ${reason}`
+  );
+}
+
 function resolveImageUrl(assetUrl: string, imageUri: string): string {
   if (/^(?:data:|blob:|https?:|file:)/i.test(imageUri)) return imageUri;
   if (assetUrl.startsWith("data:")) {
     throw new Error(`Relative glTF image uri ${imageUri} cannot be resolved from a data URL asset`);
   }
-  return new URL(imageUri, assetUrl).toString();
+  return new URL(imageUri, resolveAbsoluteAssetBase(assetUrl)).toString();
+}
+
+/**
+ * Derive an absolute base URL for resolving relative texture URIs.
+ *
+ * Catalog assets are often loaded from root-relative paths (e.g.
+ * `/aura-assets/x.glb`). `new URL(uri, base)` requires `base` to be absolute, so
+ * a bare relative `assetUrl` throws `Failed to construct 'URL': Invalid base URL`.
+ * If the asset URL is already absolute we use it directly; otherwise we resolve it
+ * against the document/origin base when running in a browser, falling back to a
+ * synthetic `file:///` origin so resolution never throws in non-browser contexts.
+ */
+function resolveAbsoluteAssetBase(assetUrl: string): string {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(assetUrl)) return assetUrl;
+  const documentBase =
+    (typeof document !== "undefined" && document.baseURI) ||
+    (typeof location !== "undefined" && location.href) ||
+    undefined;
+  if (documentBase) {
+    try {
+      return new URL(assetUrl, documentBase).toString();
+    } catch {
+      // fall through to synthetic base below
+    }
+  }
+  return new URL(assetUrl, "file:///").toString();
 }

package/src/browser-index.ts

@@ -25,7 +25,9 @@ export type {
   GLTFSceneAnalysisEvidence,
   GLTFSceneAnalysisOptions
 } from "./SceneAnalysisFixtures";
-export { GLTFLoader } from "./GLTFLoader";
+export { GLTFLoader, normalizeSkinWeights } from "./GLTFLoader";
+export { autoFitGLTFScene, computeAutoFitTransform } from "./GLTFAutoFit";
+export type { AutoFitOptions, AutoFitTransform, GLTFUpAxis } from "./GLTFAutoFit";
 export type {
   GLTFAsset,
   GLTFCameraAsset,
@@ -57,7 +59,8 @@ export type {
   GLTFTextureAsset,
   GLTFTransmissionMaterialExtension,
   GLTFVolumeMaterialExtension,
-  SerializedGLTFAsset
+  SerializedGLTFAsset,
+  SkinWeightNormalizationStats
 } from "./GLTFLoader";
 export { inspectGLTFAsset } from "./AssetInspection";
 export type {
@@ -89,7 +92,7 @@ export type {
   GLTFExtensionSupportFamily,
   GLTFExtensionSupportStatus
 } from "./GLTFExtensionSupport";
-export { createGLTFSceneAnimationMixer, createGLTFSceneAnimationRuntime, GLTFImportedSkeletonIKController, GLTFSceneAnimationCloneSampler, GLTFSceneAnimationMixerBinding, GLTFSceneAnimationRuntime, GLTFSceneMorphTargetController } from "./GLTFAnimationRuntime";
+export { createGLTFSceneAnimationMixer, createGLTFSceneAnimationRuntime, GLTFImportedSkeletonIKController, GLTFSceneAnimationCloneSampler, GLTFSceneAnimationMixerBinding, GLTFSceneAnimationRuntime, GLTFSceneMorphTargetController, resolveGLTFClipName } from "./GLTFAnimationRuntime";
 export type {
   GLTFImportedSkeletonIKControllerOptions,
   GLTFImportedSkeletonIKControllerSnapshot,
@@ -108,7 +111,9 @@ export type {
   GLTFSceneAnimationRuntimeOptions,
   GLTFSceneAnimationRuntimeSnapshot,
   GLTFSceneMorphTargetControllerOptions,
-  GLTFSceneMorphTargetControllerSnapshot
+  GLTFSceneMorphTargetControllerSnapshot,
+  GLTFScenePose,
+  GLTFScenePoseBoneTransform
 } from "./GLTFAnimationRuntime";
 export {
   DEFAULT_GLTF_RENDER_ENVIRONMENT_LIGHTING,

package/src/index.ts

@@ -49,13 +49,15 @@ export type {
   GLTFExtensionSupportFamily,
   GLTFExtensionSupportStatus
 } from "./GLTFExtensionSupport";
-export { createGLTFSceneAnimationMixer, createGLTFSceneAnimationRuntime, GLTFImportedSkeletonIKController, GLTFSceneAnimationCloneSampler, GLTFSceneAnimationMixerBinding, GLTFSceneAnimationRuntime, GLTFSceneMorphTargetController } from "./GLTFAnimationRuntime";
+export { createGLTFSceneAnimationMixer, createGLTFSceneAnimationRuntime, GLTFImportedSkeletonIKController, GLTFSceneAnimationCloneSampler, GLTFSceneAnimationMixerBinding, GLTFSceneAnimationRuntime, GLTFSceneMorphTargetController, resolveGLTFClipName } from "./GLTFAnimationRuntime";
 export type {
   GLTFImportedSkeletonIKControllerOptions,
   GLTFImportedSkeletonIKControllerSnapshot,
   GLTFImportedSkeletonIKOptions,
   GLTFImportedSkeletonIKResult,
   GLTFSceneAnimationApplyResult,
+  GLTFSceneAnimationClipSample,
+  GLTFSceneAnimationClipBoneMask,
   GLTFSceneAnimationActionSnapshot,
   GLTFSceneAnimationCloneSample,
   GLTFSceneAnimationCloneSampleResult,
@@ -68,7 +70,9 @@ export type {
   GLTFSceneAnimationRuntimeOptions,
   GLTFSceneAnimationRuntimeSnapshot,
   GLTFSceneMorphTargetControllerOptions,
-  GLTFSceneMorphTargetControllerSnapshot
+  GLTFSceneMorphTargetControllerSnapshot,
+  GLTFScenePose,
+  GLTFScenePoseBoneTransform
 } from "./GLTFAnimationRuntime";
 export { AssetHandle } from "./AssetHandle";
 export type { AssetHandleOptions, AssetHandleStatus } from "./AssetHandle";
@@ -225,7 +229,9 @@ export type {
 } from "./CarConceptMaterialStability";
 export { ImageLoader } from "./ImageLoader";
 export type { ImageAsset } from "./ImageLoader";
-export { GLTFLoader } from "./GLTFLoader";
+export { GLTFLoader, normalizeSkinWeights } from "./GLTFLoader";
+export { autoFitGLTFScene, computeAutoFitTransform } from "./GLTFAutoFit";
+export type { AutoFitOptions, AutoFitTransform, GLTFUpAxis } from "./GLTFAutoFit";
 export type {
   GLTFAsset,
   GLTFCameraAsset,
@@ -238,6 +244,7 @@ export type {
   GLTFLightAsset,
   GLTFLoaderOptions,
   GLTFLoaderDiagnostics,
+  SkinWeightNormalizationStats,
   GLTFMaterialAsset,
   GLTFMaterialVariantAsset,
   GLTFMaterialVariantMappingAsset,
@@ -267,7 +274,8 @@ export {
   createDefaultGLTFHdrStudioPreviewEnvironmentLighting,
   createGLTFRenderResourceDiagnostics,
   createGLTFRenderResources,
-  createGLTFRenderSource
+  createGLTFRenderSource,
+  renderStateForGLTFMaterial
 } from "./GLTFRenderResources";
 export type {
   DecodedGLTFImage,

package/tests/assets.test.ts

@@ -1,6 +1,88 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { AssetManager, GLTFLoader, OBJLoader, type AssetLoader } from "../src/index";
+import {
+  AssetManager,
+  computeAutoFitTransform,
+  GLTFLoader,
+  normalizeSkinWeights,
+  OBJLoader,
+  resolveGLTFClipName,
+  type AssetLoader
+} from "../src/index";
+
+test("normalizeSkinWeights collapses degenerate (zero-sum) weights to a rigid binding", () => {
+  const stats = { degenerate: 0, rescaled: 0 };
+  assert.deepEqual(normalizeSkinWeights([0, 0, 0, 0], stats), [1, 0, 0, 0]);
+  assert.equal(stats.degenerate, 1);
+  assert.equal(stats.rescaled, 0);
+});
+
+test("normalizeSkinWeights rescales denormalized weights to sum 1 (FLOAT)", () => {
+  const stats = { degenerate: 0, rescaled: 0 };
+  const result = normalizeSkinWeights([2, 2, 0, 0], stats);
+  assert.deepEqual(result, [0.5, 0.5, 0, 0]);
+  assert.equal(stats.rescaled, 1);
+});
+
+test("normalizeSkinWeights rescales integer-encoded weights regardless of componentType scale", () => {
+  // UNSIGNED_BYTE-style raw values (sum 255) and UNSIGNED_SHORT-style (sum 65535)
+  // both normalize by proportion to the same result.
+  assert.deepEqual(normalizeSkinWeights([255, 0, 0, 0]), [1, 0, 0, 0]);
+  assert.deepEqual(normalizeSkinWeights([32767, 32768, 0, 0]).map((value) => Math.round(value * 100) / 100), [0.5, 0.5, 0, 0]);
+});
+
+test("normalizeSkinWeights clamps negative and non-finite components to zero", () => {
+  assert.deepEqual(normalizeSkinWeights([1, -1, Number.NaN, Number.POSITIVE_INFINITY]), [1, 0, 0, 0]);
+});
+
+test("normalizeSkinWeights leaves already-normalized weights untouched", () => {
+  const stats = { degenerate: 0, rescaled: 0 };
+  assert.deepEqual(normalizeSkinWeights([0.6, 0.4, 0, 0], stats), [0.6, 0.4, 0, 0]);
+  assert.equal(stats.degenerate, 0);
+  assert.equal(stats.rescaled, 0);
+});
+
+test("resolveGLTFClipName matches exact (case/format-insensitive) first", () => {
+  assert.equal(resolveGLTFClipName("Idle", ["Walk", "idle", "Run"]), "idle");
+  assert.equal(resolveGLTFClipName("walk-cycle", ["Run", "Walk_Cycle"]), "Walk_Cycle");
+});
+
+test("resolveGLTFClipName resolves via synonym groups", () => {
+  assert.equal(resolveGLTFClipName("idle", ["Loops", "Sprint"]), "Loops");
+  assert.equal(resolveGLTFClipName("run", ["Loops", "Sprint"]), "Sprint");
+  assert.equal(resolveGLTFClipName("wave", ["Greet", "Static"]), "Greet");
+});
+
+test("resolveGLTFClipName falls back to substring then first clip", () => {
+  assert.equal(resolveGLTFClipName("walk", ["WalkForward", "Run"]), "WalkForward");
+  assert.equal(resolveGLTFClipName("nonexistent", ["Take 001", "Other"]), "Take 001");
+  assert.equal(resolveGLTFClipName("anything", []), undefined);
+});
+
+test("computeAutoFitTransform scales tall and tiny models to the target height", () => {
+  const big = computeAutoFitTransform({ min: [-900, 0, -900], max: [900, 1821, 900] }, { targetHeight: 1.6 });
+  assert.ok(Math.abs(big.fittedHeight - 1.6) < 1e-6);
+  assert.ok(big.scale < 0.01);
+
+  const tiny = computeAutoFitTransform({ min: [-0.5, 0, -0.5], max: [0.5, 1, 0.5] });
+  assert.ok(Math.abs(tiny.fittedHeight - 1.6) < 1e-6);
+  assert.ok(tiny.scale > 1);
+});
+
+test("computeAutoFitTransform recenters feet to y=0 and centers x/z", () => {
+  const fit = computeAutoFitTransform({ min: [2, 4, 6], max: [4, 6, 8] }, { targetHeight: 2 });
+  // height 2 -> scale 1; center (3,5,7), floor y=4
+  assert.equal(fit.scale, 1);
+  assert.deepEqual(fit.translation, [-3, -4, -7]);
+});
+
+test("computeAutoFitTransform applies z-up correction", () => {
+  const fit = computeAutoFitTransform({ min: [-1, -1, 0], max: [1, 1, 4] }, { upAxis: "z", targetHeight: 4 });
+  assert.equal(fit.upAxisCorrection, "z-to-y");
+  // after z->y rotation the source z-extent (4) becomes height -> scale 1
+  assert.ok(Math.abs(fit.fittedHeight - 4) < 1e-6);
+  assert.notDeepEqual(fit.rotation, [0, 0, 0, 1]);
+});
 
 test("AssetManager shares duplicate in-flight loads and releases cached handles", async () => {
   let loads = 0;