fix: detect .json files in IFCLoader.load() with helpful error message

web-ifc-three/src/IFCLoader.ts

@@ -11,6 +11,13 @@ class IFCLoader extends Loader {
         this.ifcManager = new IFCManager();
     }
 
+    /**
+     * Loads an IFC file from a given URL.
+     * @param url URL of the IFC file or blob URL.
+     * @param onLoad Callback when the IFC model is loaded.
+     * @param onProgress Optional progress callback.
+     * @param onError Optional error callback.
+     */
     load(
         url: any,
         onLoad: (ifc: IFCModel) => void,
@@ -19,6 +26,29 @@ class IFCLoader extends Loader {
     ) {
         const scope = this;
 
+        // Detect JSON files and provide a helpful error message.
+        // Users often try to load JSON files (produced by ifc-to-json) directly,
+        // but web-ifc-three only supports binary IFC files for geometry.
+        const urlString = typeof url === 'string' ? url : '';
+        if (urlString.endsWith('.json')) {
+            const error = new Error(
+                'Cannot load ".json" files directly with IFCLoader. ' +
+                'The IFCLoader is designed to load binary IFC files (.ifc) for geometry. ' +
+                'If you are trying to load a JSON file produced by "ifc-to-json", ' +
+                'please note that JSON files contain property/metadata only (not geometry) ' +
+                'and must be loaded alongside an IFC file using addModelJSONData(). ' +
+                'See the documentation for the correct workflow: ' +
+                'https://ifcjs.github.io/info/docs/Guide/web-ifc/Introduction'
+            );
+            if (onError) {
+                onError(error);
+            } else {
+                console.error(error);
+            }
+            scope.manager.itemError(url);
+            return;
+        }
+
         const loader = new FileLoader(scope.manager);
         this.onProgress = onProgress;
         loader.setPath(scope.path);