@sequent-org/ifc-viewer 1.2.4-ci.45.0 → 1.2.4-ci.47.0

package/src/model-loading/loaders/GltfModelLoader.js

@@ -0,0 +1,316 @@
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
+import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
+
+/**
+ * glTF / GLB loader.
+ *
+ * Notes (important for diagnostics):
+ * - .glb is usually self-contained (good for <input type="file">).
+ * - .gltf often references external .bin / textures. That works well for URL loading
+ *   (served by dev server), but when selecting a single .gltf file from disk, those
+ *   external resources will likely be missing. We log a warning in that case.
+ */
+export class GltfModelLoader {
+  /**
+   * @param {{ basisTranscoderPath?: string, basisTranscoderCdnPath?: string }} [options]
+   */
+  constructor(options = {}) {
+    this.id = 'gltf';
+    this.extensions = ['.gltf', '.glb'];
+    this._options = {
+      // 1) Try local (consumer can host these files), 2) fallback to CDN.
+      basisTranscoderPath: options.basisTranscoderPath || '/three/basis/',
+      basisTranscoderCdnPath: options.basisTranscoderCdnPath || 'https://unpkg.com/three@0.149.0/examples/jsm/libs/basis/',
+    };
+    /** @type {KTX2Loader|null} */
+    this._ktx2 = null;
+    this._loader = new GLTFLoader();
+    try { this._loader.setMeshoptDecoder?.(MeshoptDecoder); } catch (_) {}
+  }
+
+  /**
+   * @param {File} file
+   * @param {any} ctx
+   */
+  async loadFile(file, ctx) {
+    const logger = ctx?.logger || console;
+    const name = file?.name || '';
+    const lower = name.toLowerCase();
+
+    logger?.log?.('[GltfModelLoader] loadFile', { name, size: file?.size });
+
+    // GLB: parse ArrayBuffer
+    if (lower.endsWith('.glb')) {
+      const buf = await file.arrayBuffer();
+      const preJson = this._tryReadJsonFromGlb(buf, logger);
+      await this._autoConfigureDecoders(preJson, ctx, logger);
+      const gltf = await this._parse(buf, '');
+      this._logExtensions(gltf, logger);
+      await this._applyPbrSpecGlossCompat(gltf, logger);
+      this._logSummary(gltf, logger, name);
+      return {
+        object3D: gltf.scene,
+        format: this.id,
+        name,
+        replacedInViewer: false,
+        capabilities: { kind: 'generic' },
+      };
+    }
+
+    // GLTF: parse JSON string (external resources likely missing for File input)
+    if (lower.endsWith('.gltf')) {
+      logger?.warn?.('[GltfModelLoader] .gltf selected from disk: external .bin/textures may be missing (consider loading via URL from /public/).');
+      const text = await file.text();
+      let preJson = null;
+      try { preJson = JSON.parse(text); } catch (_) { preJson = null; }
+      await this._autoConfigureDecoders(preJson, ctx, logger);
+      const gltf = await this._parse(text, '');
+      this._logExtensions(gltf, logger);
+      await this._applyPbrSpecGlossCompat(gltf, logger);
+      this._logSummary(gltf, logger, name);
+      return {
+        object3D: gltf.scene,
+        format: this.id,
+        name,
+        replacedInViewer: false,
+        capabilities: { kind: 'generic' },
+      };
+    }
+
+    throw new Error(`GltfModelLoader: unsupported file: ${name}`);
+  }
+
+  /**
+   * @param {string} url
+   * @param {any} ctx
+   */
+  async loadUrl(url, ctx) {
+    const logger = ctx?.logger || console;
+    logger?.log?.('[GltfModelLoader] loadUrl', { url });
+    // For URL we usually can't cheaply pre-read JSON without double fetching.
+    // Configure decoders "optimistically" (KTX2/Meshopt) so needed extensions work.
+    await this._autoConfigureDecoders(null, ctx, logger);
+    const gltf = await this._loader.loadAsync(url);
+    this._logExtensions(gltf, logger);
+    await this._applyPbrSpecGlossCompat(gltf, logger);
+    this._logSummary(gltf, logger, String(url || ''));
+    return {
+      object3D: gltf.scene,
+      format: this.id,
+      name: String(url || ''),
+      replacedInViewer: false,
+      capabilities: { kind: 'generic' },
+    };
+  }
+
+  _parse(data, path) {
+    return new Promise((resolve, reject) => {
+      this._loader.parse(
+        data,
+        path || '',
+        (gltf) => resolve(gltf),
+        (err) => reject(err),
+      );
+    });
+  }
+
+  _logSummary(gltf, logger, name) {
+    try {
+      const scene = gltf?.scene;
+      let meshes = 0;
+      scene?.traverse?.((n) => { if (n?.isMesh) meshes++; });
+      logger?.log?.('[GltfModelLoader] parsed', {
+        name,
+        scene: scene ? { type: scene.type, children: Array.isArray(scene.children) ? scene.children.length : undefined } : null,
+        meshes,
+        animations: Array.isArray(gltf?.animations) ? gltf.animations.length : 0,
+      });
+    } catch (_) {}
+  }
+
+  _logExtensions(gltf, logger) {
+    try {
+      const json = gltf?.parser?.json;
+      if (!json) return;
+      const used = Array.isArray(json.extensionsUsed) ? json.extensionsUsed.slice().sort() : [];
+      const required = Array.isArray(json.extensionsRequired) ? json.extensionsRequired.slice().sort() : [];
+      if (!used.length && !required.length) return;
+      logger?.log?.('[GltfModelLoader] glTF extensions', { used, required });
+    } catch (_) {}
+  }
+
+  _tryReadJsonFromGlb(arrayBuffer, logger) {
+    try {
+      const u8 = new Uint8Array(arrayBuffer);
+      const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+      if (dv.byteLength < 20) return null;
+      // magic 'glTF' = 0x46546C67 (little-endian in file)
+      const magic = dv.getUint32(0, true);
+      if (magic !== 0x46546c67) return null;
+      const version = dv.getUint32(4, true);
+      if (version < 2) return null;
+      const totalLength = dv.getUint32(8, true);
+      if (!Number.isFinite(totalLength) || totalLength <= 0) return null;
+
+      let offset = 12;
+      while (offset + 8 <= dv.byteLength) {
+        const chunkLength = dv.getUint32(offset, true);
+        const chunkType = dv.getUint32(offset + 4, true);
+        offset += 8;
+        if (offset + chunkLength > dv.byteLength) break;
+        // JSON chunk type 'JSON' = 0x4E4F534A
+        if (chunkType === 0x4E4F534A) {
+          const bytes = u8.subarray(offset, offset + chunkLength);
+          const text = new TextDecoder().decode(bytes);
+          return JSON.parse(text);
+        }
+        offset += chunkLength;
+      }
+      return null;
+    } catch (e) {
+      logger?.warn?.('[GltfModelLoader] failed to pre-read GLB JSON chunk', e);
+      return null;
+    }
+  }
+
+  async _autoConfigureDecoders(preJson, ctx, logger) {
+    // Meshopt is already set in constructor (best-effort).
+    // KTX2/BasisU: enable if we can, because users may load glb with KHR_texture_basisu.
+    const used = Array.isArray(preJson?.extensionsUsed) ? preJson.extensionsUsed : null;
+    const required = Array.isArray(preJson?.extensionsRequired) ? preJson.extensionsRequired : null;
+    const needsBasisu =
+      (used ? used.includes('KHR_texture_basisu') : true) ||
+      (required ? required.includes('KHR_texture_basisu') : false);
+    if (!needsBasisu) return;
+
+    const renderer = ctx?.viewer?.renderer || ctx?.renderer || null;
+    if (!renderer) {
+      // We can still set loader, but detectSupport needs renderer. Keep it lazy.
+      logger?.warn?.('[GltfModelLoader] KTX2Loader not fully initialized (no renderer in ctx). BasisU textures may be unavailable.');
+      return;
+    }
+
+    if (!this._ktx2) this._ktx2 = new KTX2Loader();
+
+    // Try local path first; if missing — fallback to CDN.
+    const localPath = this._options.basisTranscoderPath;
+    const cdnPath = this._options.basisTranscoderCdnPath;
+
+    const hasLocal = await this._checkTranscoderAvailable(localPath);
+    const basePath = hasLocal ? localPath : cdnPath;
+    if (!hasLocal) {
+      logger?.warn?.('[GltfModelLoader] Basis transcoder not found at local path, using CDN fallback', { localPath, cdnPath });
+    }
+
+    try {
+      this._ktx2.setTranscoderPath(basePath);
+      await this._ktx2.detectSupport(renderer);
+      this._loader.setKTX2Loader?.(this._ktx2);
+      logger?.log?.('[GltfModelLoader] KTX2Loader enabled', { transcoderPath: basePath });
+    } catch (e) {
+      logger?.warn?.('[GltfModelLoader] KTX2Loader init failed; BasisU textures may be unavailable', e);
+    }
+  }
+
+  async _checkTranscoderAvailable(basePath) {
+    try {
+      if (typeof fetch !== 'function') return false;
+      const p = String(basePath || '');
+      if (!p) return false;
+      const url = (p.endsWith('/') ? p : (p + '/')) + 'basis_transcoder.wasm';
+      const res = await fetch(url, { method: 'HEAD' });
+      return !!res && res.ok;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  /**
+   * Compatibility: KHR_materials_pbrSpecularGlossiness
+   *
+   * Some glb files (including some system-provided samples) use the legacy
+   * spec/gloss workflow extension. Newer GLTFLoader versions may not convert it.
+   * We map the most visible parts (diffuseFactor/diffuseTexture) onto the already
+   * created MeshStandardMaterial, so the model is not "white".
+   *
+   * @private
+   */
+  async _applyPbrSpecGlossCompat(gltf, logger) {
+    const parser = gltf?.parser;
+    const json = parser?.json;
+    const materialDefs = json?.materials;
+    if (!parser || !Array.isArray(materialDefs) || materialDefs.length === 0) return;
+
+    // Fast check: extension used?
+    let any = false;
+    for (const md of materialDefs) {
+      if (md?.extensions?.KHR_materials_pbrSpecularGlossiness) { any = true; break; }
+    }
+    if (!any) return;
+
+    let patched = 0;
+    let patchedWithTexture = 0;
+    let texCoordNonZero = 0;
+
+    try {
+      const materials = await parser.getDependencies('material');
+      for (let i = 0; i < materialDefs.length; i++) {
+        const ext = materialDefs[i]?.extensions?.KHR_materials_pbrSpecularGlossiness;
+        if (!ext) continue;
+        const mat = materials?.[i];
+        if (!mat) continue;
+
+        // diffuseFactor: [r,g,b,a]
+        const df = Array.isArray(ext.diffuseFactor) ? ext.diffuseFactor : null;
+        if (df && df.length >= 3 && mat?.color?.setRGB) {
+          const r = Number(df[0]); const g = Number(df[1]); const b = Number(df[2]);
+          if (Number.isFinite(r) && Number.isFinite(g) && Number.isFinite(b)) {
+            mat.color.setRGB(r, g, b);
+          }
+          if (df.length >= 4) {
+            const a = Number(df[3]);
+            if (Number.isFinite(a)) {
+              mat.opacity = Math.min(1, Math.max(0, a));
+              mat.transparent = mat.opacity < 0.999;
+            }
+          }
+        }
+
+        // diffuseTexture: { index, texCoord? }
+        const dt = ext.diffuseTexture;
+        const texIndex = dt?.index;
+        if (Number.isInteger(texIndex)) {
+          try {
+            const tex = await parser.getDependency('texture', texIndex);
+            if (tex) {
+              mat.map = tex;
+              patchedWithTexture++;
+              const tc = dt?.texCoord;
+              if (tc != null && Number(tc) !== 0) texCoordNonZero++;
+            }
+          } catch (_) {}
+        }
+
+        // Approximate conversion hints (optional): make it less "plastic"
+        try {
+          if ('metalness' in mat) mat.metalness = 0.0;
+          if ('roughness' in mat && typeof ext.glossinessFactor === 'number') {
+            mat.roughness = Math.min(1, Math.max(0, 1 - ext.glossinessFactor));
+          }
+        } catch (_) {}
+
+        try { mat.needsUpdate = true; } catch (_) {}
+        patched++;
+      }
+    } catch (_) {
+      return;
+    }
+
+    if (texCoordNonZero > 0) {
+      logger?.warn?.('[GltfModelLoader] KHR_materials_pbrSpecularGlossiness uses non-zero texCoord; multi-UV mapping may require extra handling in this three.js revision.', { texCoordNonZero });
+    }
+    logger?.log?.('[GltfModelLoader] KHR_materials_pbrSpecularGlossiness compat applied', { patched, patchedWithTexture });
+  }
+}
+

package/src/model-loading/loaders/IfcModelLoader.js

@@ -0,0 +1,77 @@
+import { IfcService } from "../../ifc/IfcService.js";
+
+/**
+ * IFC loader adapter.
+ *
+ * Notes:
+ * - Reuses existing IfcService (for stability and to keep IFC-specific capabilities intact).
+ * - IfcService currently integrates with Viewer internally via viewer.replaceWithModel().
+ *   Therefore, this loader returns replacedInViewer=true to prevent double replace.
+ */
+export class IfcModelLoader {
+  /**
+   * @param {IfcService|null} ifcService - optional externally managed service
+   */
+  constructor(ifcService = null) {
+    this.id = 'ifc';
+    this.extensions = ['.ifc', '.ifs', '.ifczip', '.zip'];
+    /** @type {IfcService|null} */
+    this._ifc = ifcService;
+  }
+
+  /**
+   * @param {any} ctx
+   * @returns {IfcService}
+   */
+  _getService(ctx) {
+    if (this._ifc) return this._ifc;
+    const viewer = ctx?.viewer;
+    if (!viewer) throw new Error('IfcModelLoader: ctx.viewer is required');
+    const wasmUrl = ctx?.wasmUrl || null;
+    const svc = new IfcService(viewer, wasmUrl);
+    svc.init();
+    this._ifc = svc;
+    return svc;
+  }
+
+  /**
+   * @param {File} file
+   * @param {any} ctx
+   */
+  async loadFile(file, ctx) {
+    const ifc = this._getService(ctx);
+    const model = await ifc.loadFile(file);
+    if (!model) throw new Error('IFC loadFile returned null');
+    return {
+      object3D: model,
+      format: this.id,
+      name: file?.name || '',
+      replacedInViewer: true,
+      capabilities: {
+        kind: 'ifc',
+        ifcService: ifc,
+      },
+    };
+  }
+
+  /**
+   * @param {string} url
+   * @param {any} ctx
+   */
+  async loadUrl(url, ctx) {
+    const ifc = this._getService(ctx);
+    const model = await ifc.loadUrl(url);
+    if (!model) throw new Error('IFC loadUrl returned null');
+    return {
+      object3D: model,
+      format: this.id,
+      name: String(url || ''),
+      replacedInViewer: true,
+      capabilities: {
+        kind: 'ifc',
+        ifcService: ifc,
+      },
+    };
+  }
+}
+

package/src/model-loading/loaders/ObjModelLoader.js

@@ -0,0 +1,310 @@
+import { LoadingManager } from "three";
+import { MTLLoader } from "three/examples/jsm/loaders/MTLLoader.js";
+import { OBJLoader } from "three/examples/jsm/loaders/OBJLoader.js";
+
+/**
+ * OBJ loader with optional MTL support.
+ *
+ * Multi-file behavior (for <input multiple>):
+ * - User may select:
+ *   - only .obj  -> load OBJ without MTL
+ *   - .obj + .mtl (+ textures) -> apply MTL and resolve textures from selected files
+ *
+ * Important: browser cannot access "neighbor" files unless the user selected them.
+ */
+export class ObjModelLoader {
+  constructor() {
+    this.id = 'obj';
+    this.extensions = ['.obj'];
+    // For file picker convenience (accept=): allow selecting MTL + common textures.
+    this.associatedExtensions = ['.mtl', '.png', '.jpg', '.jpeg', '.webp', '.bmp', '.gif', '.tga'];
+  }
+
+  async loadFile(file, ctx) {
+    // Fallback: single OBJ only
+    return await this.loadFiles([file], ctx);
+  }
+
+  /**
+   * @param {File[]|FileList} files
+   * @param {any} ctx
+   */
+  async loadFiles(files, ctx) {
+    const logger = ctx?.logger || console;
+    const arr = Array.from(files || []).filter(Boolean);
+    if (!arr.length) throw new Error('ObjModelLoader: no files');
+
+    const objFile = this._pickObj(arr);
+    if (!objFile) {
+      throw new Error(`ObjModelLoader: .obj not found in selection: ${arr.map((f) => f?.name).filter(Boolean).join(', ')}`);
+    }
+
+    const base = this._basenameNoExt(objFile.name);
+    const mtlFile =
+      arr.find((f) => this._isExt(f?.name, '.mtl') && this._basenameNoExt(f.name).toLowerCase() === base.toLowerCase())
+      || arr.find((f) => this._isExt(f?.name, '.mtl'));
+
+    const fileMap = this._buildFileMap(arr);
+    const urlMap = new Map();
+    const revokeAll = () => {
+      try { for (const u of urlMap.values()) URL.revokeObjectURL(u); } catch (_) {}
+    };
+    const getBlobUrl = (key) => {
+      const k = String(key || '').toLowerCase();
+      if (!k) return null;
+      if (urlMap.has(k)) return urlMap.get(k);
+      const f = fileMap.get(k);
+      if (!f) return null;
+      const u = URL.createObjectURL(f);
+      urlMap.set(k, u);
+      return u;
+    };
+
+    // URL modifier: map any relative texture file name to the selected files
+    const manager = new LoadingManager();
+    /** @type {Set<string>} */
+    const failedUrls = new Set();
+    /** @type {Set<string>} */
+    const requestedBasenames = new Set();
+    // Track loader-level failures (useful when MTL parsing doesn't reveal all refs)
+    manager.onError = (url) => {
+      try {
+        const raw = String(url || '');
+        const clean = raw.split('#')[0].split('?')[0];
+        const parts = clean.replace(/\\/g, '/').split('/');
+        const last = (parts[parts.length - 1] || '').trim();
+        if (last) failedUrls.add(last);
+      } catch (_) {}
+    };
+    manager.setURLModifier((url) => {
+      try {
+        const raw = String(url || '');
+        // Strip query/hash and keep last segment
+        const clean = raw.split('#')[0].split('?')[0];
+        const parts = clean.replace(/\\/g, '/').split('/');
+        const last = (parts[parts.length - 1] || '').trim();
+        if (!last) return raw;
+        requestedBasenames.add(last);
+        const key = last.toLowerCase();
+        const blob = getBlobUrl(key);
+        return blob || raw;
+      } catch (_) {
+        return url;
+      }
+    });
+
+    try {
+      logger?.log?.('[ObjModelLoader] loadFiles', {
+        obj: objFile.name,
+        mtl: mtlFile ? mtlFile.name : null,
+        files: arr.map((f) => f?.name).filter(Boolean),
+      });
+
+      // If MTL exists, parse and apply materials
+      let materials = null;
+      let missingTextures = [];
+      if (mtlFile) {
+        const mtlText = await mtlFile.text();
+        // Diagnostics: detect missing referenced textures in MTL
+        try {
+          const refs = this._extractTextureRefsFromMtl(mtlText);
+          missingTextures = this._findMissingRefs(refs, fileMap);
+          if (missingTextures.length) {
+            logger?.warn?.('[ObjModelLoader] MTL references missing texture files (select them too):', missingTextures);
+          }
+        } catch (_) {}
+        const mtlLoader = new MTLLoader(manager);
+        materials = mtlLoader.parse(mtlText, '');
+        // IMPORTANT: preload loads textures asynchronously via manager.
+        // We must NOT revoke blob: URLs until these loads finish.
+        try { materials.preload(); } catch (_) {}
+      }
+
+      const objText = await objFile.text();
+      const objLoader = new OBJLoader(manager);
+      if (materials) objLoader.setMaterials(materials);
+      const obj = objLoader.parse(objText);
+
+      // Wait a bit for async texture loads to complete before revoking blob URLs.
+      // If there are no textures, onLoad can fire immediately; otherwise it will fire when all are done.
+      await this._waitManagerIdle(manager, 2500);
+
+      // Diagnostics: mesh/material counts
+      try {
+        let meshes = 0;
+        let mats = 0;
+        obj.traverse?.((n) => {
+          if (!n?.isMesh) return;
+          meshes++;
+          const m = n.material;
+          mats += Array.isArray(m) ? m.length : (m ? 1 : 0);
+        });
+        logger?.log?.('[ObjModelLoader] parsed', { obj: objFile.name, meshes, materials: mats, hasMtl: !!mtlFile });
+      } catch (_) {}
+
+      // Merge "missing by parse" + "failed at load time"
+      const missingAll = Array.from(new Set([...(missingTextures || []), ...Array.from(failedUrls.values())]));
+      if (missingAll.length) {
+        logger?.warn?.('[ObjModelLoader] missing assets (select these files too):', missingAll);
+      } else if (mtlFile) {
+        // If MTL exists but no maps got attached, warn proactively
+        try {
+          let withMap = 0;
+          obj.traverse?.((n) => {
+            if (!n?.isMesh) return;
+            const m = n.material;
+            const arrM = Array.isArray(m) ? m : [m];
+            for (const mi of arrM) if (mi?.map) withMap++;
+          });
+          if (withMap === 0) {
+            logger?.warn?.('[ObjModelLoader] MTL loaded, but no texture maps attached. Ensure you selected all referenced image files.', {
+              requested: Array.from(requestedBasenames.values()).slice(0, 30),
+            });
+          }
+        } catch (_) {}
+      }
+
+      return {
+        object3D: obj,
+        format: this.id,
+        name: objFile.name,
+        replacedInViewer: false,
+        capabilities: {
+          kind: 'generic',
+          hasMtl: !!mtlFile,
+          missingAssets: missingAll,
+        },
+      };
+    } finally {
+      // We keep URLs until manager finishes async texture loads (or timeout above).
+      revokeAll();
+    }
+  }
+
+  _pickObj(arr) {
+    // Prefer .obj; if multiple, take first
+    return arr.find((f) => this._isExt(f?.name, '.obj')) || null;
+  }
+
+  _isExt(name, ext) {
+    const n = String(name || '').toLowerCase();
+    return n.endsWith(String(ext).toLowerCase());
+  }
+
+  _basenameNoExt(name) {
+    const n = String(name || '');
+    const base = n.split(/[/\\]/).pop() || n;
+    const i = base.lastIndexOf('.');
+    return (i >= 0) ? base.slice(0, i) : base;
+  }
+
+  _buildFileMap(arr) {
+    // Map by basename only (common in MTL references)
+    const map = new Map();
+    for (const f of arr) {
+      const full = String(f?.name || '');
+      if (!full) continue;
+      const base = (full.split(/[/\\]/).pop() || full).toLowerCase();
+      if (!map.has(base)) map.set(base, f);
+    }
+    return map;
+  }
+
+  _extractTextureRefsFromMtl(mtlText) {
+    // Parse only texture map statements. We keep basenames; actual resolve happens via URLModifier.
+    const text = String(mtlText || '');
+    const lines = text.split(/\r?\n/);
+    const out = new Set();
+
+    for (let line of lines) {
+      line = String(line || '').trim();
+      if (!line || line.startsWith('#')) continue;
+      // strip inline comment
+      const hash = line.indexOf('#');
+      if (hash >= 0) line = line.slice(0, hash).trim();
+      if (!line) continue;
+
+      // Tokenize while keeping simple quoted paths
+      // Most MTL files are simple: last token is path, options before it.
+      const tokens = line.match(/"[^"]+"|\S+/g) || [];
+      if (tokens.length < 2) continue;
+      const keyword = String(tokens[0] || '').toLowerCase();
+      // Typical texture statements (robust to tabs/multiple spaces)
+      const isTexKeyword = (
+        keyword === 'map_kd' ||
+        keyword === 'map_ka' ||
+        keyword === 'map_ks' ||
+        keyword === 'map_ke' ||
+        keyword === 'map_ns' ||
+        keyword === 'map_d' ||
+        keyword === 'map_bump' ||
+        keyword === 'bump' ||
+        keyword === 'disp' ||
+        keyword === 'decal' ||
+        keyword === 'refl'
+      );
+      if (!isTexKeyword) continue;
+
+      // Remove the statement keyword
+      tokens.shift();
+
+      // Remove known options and their args (best-effort)
+      const rest = [];
+      for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (!t) continue;
+        if (t.startsWith('-')) {
+          // options with 1-3 numeric args are common
+          const opt = t.toLowerCase();
+          const skipArgs = (opt === '-o' || opt === '-s' || opt === '-t') ? 3
+            : (opt === '-mm') ? 2
+            : (opt === '-bm') ? 1
+            : (opt === '-imfchan') ? 1
+            : (opt === '-type') ? 1
+            : 0;
+          i += skipArgs;
+          continue;
+        }
+        rest.push(t);
+      }
+      if (!rest.length) continue;
+
+      const rawPath = rest[rest.length - 1].replace(/^"|"$/g, '');
+      const base = (rawPath.split(/[/\\]/).pop() || rawPath).trim();
+      if (!base) continue;
+      out.add(base);
+    }
+
+    return Array.from(out.values());
+  }
+
+  _findMissingRefs(refBasenames, fileMap) {
+    const missing = [];
+    for (const b of (refBasenames || [])) {
+      const key = String(b || '').toLowerCase();
+      if (!key) continue;
+      if (!fileMap.has(key)) missing.push(b);
+    }
+    return missing;
+  }
+
+  _waitManagerIdle(manager, timeoutMs = 2000) {
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = () => {
+        if (done) return;
+        done = true;
+        resolve();
+      };
+      try {
+        const prevOnLoad = manager.onLoad;
+        manager.onLoad = () => {
+          try { prevOnLoad?.(); } catch (_) {}
+          finish();
+        };
+      } catch (_) {}
+      setTimeout(finish, Math.max(0, Number(timeoutMs) || 0));
+    });
+  }
+}
+