@ifc-lite/export 2.3.0 → 2.4.1

package/dist/merged-exporter.js

@@ -9,6 +9,7 @@ import { convertStepLine, needsConversion } from './schema-converter.js';
 import { assembleStepBytes } from './step-serialization.js';
 import { getCompleteEntityIndex, getMaxExpressId } from './entity-iteration.js';
 import { StepExporter } from './step-exporter.js';
+import { rescaleEntityLengths, computeNormalizeFactor } from './unit-normalize.js';
 /** Entity types forming shared infrastructure (deduplicated across models). */
 const SHARED_INFRASTRUCTURE_TYPES = new Set([
     'IFCUNITASSIGNMENT',
@@ -71,6 +72,14 @@ function isRelationshipType(typeUpper) {
 }
 /** Relative tolerance for comparing two length unit scale factors. */
 const UNIT_SCALE_TOLERANCE = 1e-6;
+/** SI prefix multipliers, for resolving prefixed area/volume units (rarely used). */
+const SI_PREFIX_MULTIPLIERS = {
+    ATTO: 1e-18, FEMTO: 1e-15, PICO: 1e-12, NANO: 1e-9, MICRO: 1e-6, MILLI: 1e-3,
+    CENTI: 1e-2, DECI: 1e-1, DECA: 1e1, HECTO: 1e2, KILO: 1e3, MEGA: 1e6,
+    GIGA: 1e9, TERA: 1e12, PETA: 1e15, EXA: 1e18,
+};
+/** Source schemas the IFC4 length registry does not fully cover (see #1475 review). */
+const NORMALIZE_UNCOVERED_SCHEMAS = new Set(['IFC4X3', 'IFC5']);
 /**
  * True when a mutation view carries pending edits the exporter would bake.
  *
@@ -93,6 +102,19 @@ function viewHasMutations(view) {
     const created = typeof view.getNewEntities === 'function' ? view.getNewEntities() : [];
     return created.length > 0;
 }
+/**
+ * Drop models with no usable source (nothing to emit): a cache-restored or
+ * metadata-only store can reach the merge with an empty `.source`. The emit loop
+ * already skips them, but the primary model (`models[0]`) and the unit/offset
+ * setup must be computed over the SAME set — otherwise an empty model at index 0
+ * would poison the primary unit/scale that later models normalize against. When
+ * every model is empty the original list is kept so a valid (empty) file is still
+ * produced rather than throwing.
+ */
+function withUsableSource(models) {
+    const usable = models.filter(m => m.dataStore.source && m.dataStore.source.length > 0);
+    return usable.length > 0 ? usable : models;
+}
 /**
  * Merges multiple IFC models into a single STEP file.
  *
@@ -116,14 +138,15 @@ function viewHasMutations(view) {
  *    fresh deterministic GlobalId so the file has no duplicate-GlobalId errors
  *    and no relationship membership is lost.
  *
- * Conformance trade-off: when federation triggers, the file contains more than
- * one IfcProject, which intentionally relaxes the IfcSingleProjectInstance
- * EXPRESS rule (SIZEOF(IfcProject) <= 1). This is the only way to keep two
- * different length units in one STEP file without rewriting every length-valued
- * coordinate, and it is strictly better than the previous silent mis-scale.
- * `MergeExportResult.stats.warnings` flags it; pass
- * `unitReconciliation: 'assume-shared'` to force a single project when units
- * are already normalised.
+ * Conformance trade-off: when federation triggers (under the default `'auto'`),
+ * the file contains more than one IfcProject, which intentionally relaxes the
+ * IfcSingleProjectInstance EXPRESS rule (SIZEOF(IfcProject) <= 1). This preserves
+ * both units without rewriting coordinates, and is strictly better than a silent
+ * mis-scale. `MergeExportResult.stats.warnings` flags it. To instead get one
+ * ordinary single-unit IfcProject, pass `unitReconciliation: 'normalize'` — it
+ * rescales every length-valued datum of the differing-unit models into the first
+ * model's unit (see {@link ./unit-normalize.ts}). Use `'assume-shared'` only when
+ * the caller has already normalised units.
  *
  * Limitation: federation only unifies a model against the *first* model's unit
  * group. Two non-first models that share a unit different from the first are
@@ -147,7 +170,7 @@ export class MergedExporter {
             throw new Error('MergedExporter.export() cannot apply pending edits — baking needs the async parser. ' +
                 'Use exportAsync() for merged export with mutations.');
         }
-        const models = this.models;
+        const models = withUsableSource(this.models);
         const setup = this.buildMergeSetup(options, models);
         const allEntityLines = [];
         // Tracks every GlobalId already emitted → its final express id + unit scale,
@@ -156,6 +179,8 @@ export class MergedExporter {
         const guidToFinalId = new Map();
         let isFirstModel = true;
         let federatedModelCount = 0;
+        let normalizedModelCount = 0;
+        const normalizeWarnings = new Set();
         for (const model of models) {
             const offset = setup.modelOffsets.get(model.id);
             const source = model.dataStore.source;
@@ -165,19 +190,21 @@ export class MergedExporter {
             // walk and the emit loop both reach every entity the source defines.
             const completeIndex = getCompleteEntityIndex(model.dataStore);
             const includedEntityIds = this.computeIncludedEntityIds(model, options, completeIndex, source);
-            const modelScale = this.resolveUnitScale(model);
-            const compatible = isFirstModel || setup.assumeShared
-                || this.unitsCompatible(modelScale, setup.primaryScale);
-            if (!isFirstModel && !compatible)
+            const mode = this.resolveModelMode(model, isFirstModel, setup);
+            if (!isFirstModel && !mode.compatible)
                 federatedModelCount++;
-            const plan = this.planModel(model, completeIndex, isFirstModel, compatible, setup, guidToFinalId);
+            if (mode.normalized) {
+                normalizedModelCount++;
+                this.collectNormalizeCaveats(model, normalizeWarnings);
+            }
+            const plan = this.planModel(model, completeIndex, isFirstModel, mode.compatible, mode.lengthFactor, setup, guidToFinalId);
             const sourceSchema = model.dataStore.schemaVersion || 'IFC4';
             for (const [expressId, entityRef] of completeIndex) {
                 if (includedEntityIds !== null && !includedEntityIds.has(expressId))
                     continue;
                 if (plan.skipEntityIds.has(expressId))
                     continue;
-                const line = this.renderEntity(expressId, entityRef, source, offset, plan, sourceSchema, schema, guidToFinalId, modelScale);
+                const line = this.renderEntity(expressId, entityRef, source, offset, plan, sourceSchema, schema, guidToFinalId, mode);
                 if (line !== null)
                     allEntityLines.push(line);
             }
@@ -189,7 +216,7 @@ export class MergedExporter {
         const content = assembleStepBytes(header, allEntityLines);
         return {
             content,
-            stats: this.buildStats(allEntityLines.length, content.byteLength, federatedModelCount),
+            stats: this.buildStats(allEntityLines.length, content.byteLength, federatedModelCount, normalizedModelCount, normalizeWarnings),
         };
     }
     /**
@@ -206,7 +233,7 @@ export class MergedExporter {
         // Bake each model's pending edits into its source bytes before merging, so
         // federated export round-trips mutations like single-model export. Models
         // without edits pass through unchanged (no export/parse cost).
-        const models = await this.bakeMutatedModels();
+        const models = withUsableSource(await this.bakeMutatedModels());
         const setup = this.buildMergeSetup(options, models);
         const allEntityLines = [];
         const guidToFinalId = new Map();
@@ -218,6 +245,8 @@ export class MergedExporter {
         let isFirstModel = true;
         let entitiesProcessed = 0;
         let federatedModelCount = 0;
+        let normalizedModelCount = 0;
+        const normalizeWarnings = new Set();
         const YIELD_INTERVAL = 2000;
         if (onProgress)
             onProgress({ phase: 'preparing', percent: 0, entitiesProcessed: 0, entitiesTotal: totalEntities });
@@ -237,12 +266,14 @@ export class MergedExporter {
             }
             const completeIndex = getCompleteEntityIndex(model.dataStore);
             const includedEntityIds = this.computeIncludedEntityIds(model, options, completeIndex, source);
-            const modelScale = this.resolveUnitScale(model);
-            const compatible = isFirstModel || setup.assumeShared
-                || this.unitsCompatible(modelScale, setup.primaryScale);
-            if (!isFirstModel && !compatible)
+            const mode = this.resolveModelMode(model, isFirstModel, setup);
+            if (!isFirstModel && !mode.compatible)
                 federatedModelCount++;
-            const plan = this.planModel(model, completeIndex, isFirstModel, compatible, setup, guidToFinalId);
+            if (mode.normalized) {
+                normalizedModelCount++;
+                this.collectNormalizeCaveats(model, normalizeWarnings);
+            }
+            const plan = this.planModel(model, completeIndex, isFirstModel, mode.compatible, mode.lengthFactor, setup, guidToFinalId);
             const sourceSchema = model.dataStore.schemaVersion || 'IFC4';
             let entityCount = 0;
             for (const [expressId, entityRef] of completeIndex) {
@@ -250,7 +281,7 @@ export class MergedExporter {
                     continue;
                 if (plan.skipEntityIds.has(expressId))
                     continue;
-                const line = this.renderEntity(expressId, entityRef, source, offset, plan, sourceSchema, schema, guidToFinalId, modelScale);
+                const line = this.renderEntity(expressId, entityRef, source, offset, plan, sourceSchema, schema, guidToFinalId, mode);
                 if (line !== null)
                     allEntityLines.push(line);
                 entityCount++;
@@ -282,7 +313,7 @@ export class MergedExporter {
         }
         return {
             content,
-            stats: this.buildStats(allEntityLines.length, content.byteLength, federatedModelCount),
+            stats: this.buildStats(allEntityLines.length, content.byteLength, federatedModelCount, normalizedModelCount, normalizeWarnings),
         };
     }
     /**
@@ -331,17 +362,37 @@ export class MergedExporter {
     /**
      * Assemble the result stats, including any federation conformance warnings.
      */
-    buildStats(totalEntityCount, fileSize, federatedModelCount) {
+    buildStats(totalEntityCount, fileSize, federatedModelCount, normalizedModelCount, normalizeWarnings) {
         const warnings = [];
         if (federatedModelCount > 0) {
             warnings.push(`${federatedModelCount} model(s) had a length unit differing from the first model and were ` +
                 `federated as separate IfcProject roots to keep their geometry correctly scaled. The output ` +
                 `therefore contains ${federatedModelCount + 1} IfcProject instances, which intentionally relaxes ` +
                 `the IfcSingleProjectInstance rule (SIZEOF(IfcProject) <= 1). Some single-project viewers may ` +
-                `only show the first project. Pass unitReconciliation:'assume-shared' to force one project when ` +
-                `units are already normalised.`);
+                `only show the first project. Pass unitReconciliation:'normalize' to rescale them into one ` +
+                `single-unit project, or 'assume-shared' when units are already normalised.`);
+        }
+        warnings.push(...normalizeWarnings);
+        return { modelCount: this.models.length, totalEntityCount, fileSize, federatedModelCount, normalizedModelCount, warnings };
+    }
+    /**
+     * Record advisories for a model being normalized. The rescaler derives its
+     * length-attribute map from the IFC4 schema registry, so it may not cover
+     * length attributes introduced by newer schemas (IFC4X3 alignment / linear
+     * referencing), and it deliberately leaves georeferencing untouched.
+     */
+    collectNormalizeCaveats(model, warnings) {
+        const schema = (model.dataStore.schemaVersion ?? '').toUpperCase();
+        if (NORMALIZE_UNCOVERED_SCHEMAS.has(schema)) {
+            warnings.add(`Model "${model.name}" (${schema}) was normalized using the IFC4 length-attribute schema; ` +
+                `length values on ${schema}-specific entities (e.g. alignment / linear-referencing segment ` +
+                `lengths and radii) may not have been rescaled. Verify infrastructure geometry.`);
+        }
+        if (this.findEntitiesByType(model.dataStore, 'IFCMAPCONVERSION').length > 0) {
+            warnings.add(`Model "${model.name}" carries georeferencing (IfcMapConversion), which normalize leaves ` +
+                `untouched. If the model was georeferenced in its own unit, review the merged coordinate ` +
+                `operation.`);
         }
-        return { modelCount: this.models.length, totalEntityCount, fileSize, federatedModelCount, warnings };
     }
     /**
      * Build the ifc-lite provenance header. Merged files have no single source
@@ -374,16 +425,126 @@ export class MergedExporter {
             nextAvailableId += getMaxExpressId(getCompleteEntityIndex(model.dataStore));
         }
         const firstModel = models[0];
+        const primaryScale = this.resolveUnitScale(firstModel);
         return {
             modelOffsets,
             firstModelOffset: modelOffsets.get(firstModel.id),
             firstModelInfraMap: this.findInfrastructureEntities(firstModel.dataStore),
             firstProjectIds: this.findEntitiesByType(firstModel.dataStore, 'IFCPROJECT'),
             spatialLookup: this.buildSpatialLookup(firstModel.dataStore),
-            primaryScale: this.resolveUnitScale(firstModel),
+            primaryScale,
+            primaryAreaScale: this.resolveDerivedUnitScale(firstModel.dataStore, 'AREAUNIT', primaryScale, 2),
+            primaryVolumeScale: this.resolveDerivedUnitScale(firstModel.dataStore, 'VOLUMEUNIT', primaryScale, 3),
             assumeShared: options.unitReconciliation === 'assume-shared',
+            normalize: options.unitReconciliation === 'normalize',
+            mergeSites: options.mergeSites,
+            mergeBuildings: options.mergeBuildings,
+            mergeStoreys: options.mergeStoreys,
         };
     }
+    /**
+     * Decide how one model folds into the merge from its length unit and the
+     * reconciliation mode.
+     *
+     * - The primary model, `assume-shared`, and any model that already shares the
+     *   primary unit are unified with no rescale.
+     * - Under `normalize`, a differing-unit model is unified *and* rescaled: every
+     *   length-valued datum is multiplied by `primaryScale`-relative factor so its
+     *   geometry stays correct under the single shared unit.
+     * - Otherwise (`auto`) a differing-unit model is federated (kept as its own
+     *   project + units), leaving its raw coordinates untouched.
+     *
+     * Area/volume reconciliation is gated on the length unit differing: a model that
+     * shares the primary's length unit is treated as fully compatible (factors 1).
+     * A model that pairs a matching length unit with a *divergent* area/volume unit
+     * (a non-conformant combination no mainstream exporter emits) is not rescaled.
+     */
+    resolveModelMode(model, isFirstModel, setup) {
+        const modelScale = this.resolveUnitScale(model);
+        if (isFirstModel || setup.assumeShared || this.unitsCompatible(modelScale, setup.primaryScale)) {
+            return { compatible: true, lengthFactor: 1, areaFactor: 1, volumeFactor: 1, effectiveScale: modelScale, normalized: false };
+        }
+        if (setup.normalize) {
+            // Each dimension is converted by the ratio of its own declared unit, not by
+            // powers of the length factor — IFC declares area/volume units independently
+            // (Revit: millimetre lengths but square-/cubic-metre areas/volumes).
+            const modelArea = this.resolveDerivedUnitScale(model.dataStore, 'AREAUNIT', modelScale, 2);
+            const modelVolume = this.resolveDerivedUnitScale(model.dataStore, 'VOLUMEUNIT', modelScale, 3);
+            return {
+                compatible: true,
+                lengthFactor: computeNormalizeFactor(modelScale, setup.primaryScale),
+                areaFactor: computeNormalizeFactor(modelArea, setup.primaryAreaScale),
+                volumeFactor: computeNormalizeFactor(modelVolume, setup.primaryVolumeScale),
+                effectiveScale: setup.primaryScale,
+                normalized: true,
+            };
+        }
+        // auto: federate the differing-unit model, coordinates untouched.
+        return { compatible: false, lengthFactor: 1, areaFactor: 1, volumeFactor: 1, effectiveScale: modelScale, normalized: false };
+    }
+    /**
+     * Resolve a model's declared AREAUNIT / VOLUMEUNIT scale (SI m² / m³ per unit)
+     * by walking IfcProject → IfcUnitAssignment. Falls back to the length-derived
+     * unit (`lengthScale ** power`) when the model declares no explicit area/volume
+     * unit — the IFC default. A prefixed SI area/volume unit (rare) applies the
+     * prefix once (buildingSMART / IfcOpenShell convention).
+     */
+    resolveDerivedUnitScale(dataStore, wantType, lengthScale, power) {
+        const fallback = Math.pow(lengthScale, power);
+        const projectIds = this.findEntitiesByType(dataStore, 'IFCPROJECT');
+        if (projectIds.length === 0)
+            return fallback;
+        // IfcProject.UnitsInContext = attr 8 → IfcUnitAssignment.
+        const unitsAttr = this.extractStepAttribute(projectIds[0], dataStore, 8);
+        const assignMatch = unitsAttr?.match(/^#(\d+)$/);
+        if (!assignMatch)
+            return fallback;
+        // IfcUnitAssignment.Units = attr 0 (a list of unit refs).
+        const listAttr = this.extractStepAttribute(parseInt(assignMatch[1], 10), dataStore, 0);
+        if (!listAttr)
+            return fallback;
+        for (const m of listAttr.matchAll(/#(\d+)/g)) {
+            const uid = parseInt(m[1], 10);
+            const uref = dataStore.entityIndex.byId.get(uid);
+            const utype = (uref?.type ?? '').toUpperCase();
+            if (utype === 'IFCSIUNIT') {
+                // IfcSIUnit: [1] UnitType, [2] Prefix, [3] Name.
+                if (this.normalizeEnum(this.extractStepAttribute(uid, dataStore, 1)) !== wantType)
+                    continue;
+                const prefixRaw = this.extractStepAttribute(uid, dataStore, 2);
+                if (!prefixRaw || prefixRaw === '$' || prefixRaw === '*')
+                    return 1.0; // square/cubic metre
+                const mult = SI_PREFIX_MULTIPLIERS[this.normalizeEnum(prefixRaw)];
+                return mult !== undefined ? mult : 1.0;
+            }
+            if (utype === 'IFCCONVERSIONBASEDUNIT') {
+                // IfcConversionBasedUnit: [1] UnitType, [2] Name, [3] ConversionFactor.
+                if (this.normalizeEnum(this.extractStepAttribute(uid, dataStore, 1)) !== wantType)
+                    continue;
+                const convMatch = this.extractStepAttribute(uid, dataStore, 3)?.match(/^#(\d+)$/);
+                if (convMatch) {
+                    // IfcMeasureWithUnit.ValueComponent = attr 0 (e.g. IFCAREAMEASURE(0.0929)).
+                    const num = this.parseMeasureNumber(this.extractStepAttribute(parseInt(convMatch[1], 10), dataStore, 0));
+                    if (num !== undefined && num > 0)
+                        return num;
+                }
+                return fallback;
+            }
+        }
+        return fallback;
+    }
+    /** Uppercase an enum token, stripping the STEP `.ENUM.` dots. `''` for nullish. */
+    normalizeEnum(raw) {
+        return (raw ?? '').replace(/\./g, '').trim().toUpperCase();
+    }
+    /** Extract the number from a bare real or a typed measure token (`IFCAREAMEASURE(0.09)`). */
+    parseMeasureNumber(raw) {
+        if (!raw)
+            return undefined;
+        const typed = raw.match(/\(([^)]*)\)\s*$/);
+        const n = Number((typed ? typed[1] : raw).trim());
+        return Number.isFinite(n) ? n : undefined;
+    }
     /**
      * Resolve a model's length unit scale (raw IFC length → metres). Prefers an
      * explicit `lengthUnitScale` on the input, else the value the parser stamped
@@ -429,10 +590,10 @@ export class MergedExporter {
      * Plan how a model's entities are remapped, skipped, or re-stamped, given
      * whether it shares the primary model's length unit (`compatible`).
      *
-     * Compatible (or `assume-shared`) models are unified into the primary project:
-     * their IfcProject, shared infrastructure, and matching spatial structure are
-     * deduplicated, and a rooted entity repeating an already-emitted GlobalId is
-     * unified to that one instance.
+     * Compatible models (same unit, `assume-shared`, or `normalize`d into the
+     * primary unit) are unified into the primary project: their IfcProject, shared
+     * infrastructure, and matching spatial structure are deduplicated, and a rooted
+     * entity repeating an already-emitted GlobalId is unified to that one instance.
      *
      * Incompatible (federated) models keep their own project, units, contexts and
      * spatial structure so their coordinates stay correctly scaled; a rooted
@@ -440,7 +601,7 @@ export class MergedExporter {
      * deterministic GlobalId, since the two cannot be the same instance across
      * different unit spaces.
      */
-    planModel(model, completeIndex, isFirstModel, compatible, setup, guidToFinalId) {
+    planModel(model, completeIndex, isFirstModel, compatible, lengthFactor, setup, guidToFinalId) {
         const source = model.dataStore.source;
         const sharedRemap = new Map();
         const skipEntityIds = new Set();
@@ -471,7 +632,9 @@ export class MergedExporter {
                 }
             }
             // Unify spatial hierarchy: match Site, Building, Storey to first model.
-            this.unifySpatialEntities(model.dataStore, setup.spatialLookup, setup.firstModelOffset, sharedRemap, skipEntityIds);
+            // Under normalize, this model's raw elevations are in its own unit, so the
+            // elevation match is done in the primary unit (rawElevation * lengthFactor).
+            this.unifySpatialEntities(model.dataStore, setup.spatialLookup, setup.firstModelOffset, lengthFactor, sharedRemap, skipEntityIds, setup);
             // Skip IfcRelAggregates that become fully redundant after unification.
             this.skipRedundantRelAggregates(model.dataStore, sharedRemap, skipEntityIds);
         }
@@ -513,7 +676,7 @@ export class MergedExporter {
      * and register the emitted GlobalId so later models can reconcile against it.
      * Returns `null` when schema conversion drops the entity.
      */
-    renderEntity(localId, entityRef, source, offset, plan, sourceSchema, targetSchema, guidToFinalId, modelScale) {
+    renderEntity(localId, entityRef, source, offset, plan, sourceSchema, targetSchema, guidToFinalId, mode) {
         const entityText = safeUtf8Decode(source, entityRef.byteOffset, entityRef.byteOffset + entityRef.byteLength);
         // Remap ids. Fast path: the first model (offset 0, no remaps) is byte-identical.
         let finalText;
@@ -528,6 +691,13 @@ export class MergedExporter {
         if (mintedGuid !== undefined) {
             finalText = this.replaceGlobalId(finalText, mintedGuid);
         }
+        // Normalize units: rescale every length/area/volume-valued datum into the
+        // primary unit. Done on the SOURCE-schema text (entityRef.type), before any
+        // schema conversion, so the schema-derived attribute indices line up. Touches
+        // only numeric literals, so id remaps and the GlobalId re-stamp above are safe.
+        if (mode.lengthFactor !== 1 || mode.areaFactor !== 1 || mode.volumeFactor !== 1) {
+            finalText = rescaleEntityLengths(finalText, entityRef.type.toUpperCase(), mode.lengthFactor, mode.areaFactor, mode.volumeFactor);
+        }
         if (needsConversion(sourceSchema, targetSchema)) {
             const converted = convertStepLine(finalText, sourceSchema, targetSchema);
             if (converted === null)
@@ -544,7 +714,7 @@ export class MergedExporter {
             const emittedGuid = this.readLeadingGuid(finalText)
                 ?? mintedGuid ?? plan.localGuids.get(localId);
             if (emittedGuid !== undefined) {
-                guidToFinalId.set(emittedGuid, { finalId: localId + offset, scale: modelScale });
+                guidToFinalId.set(emittedGuid, { finalId: localId + offset, scale: mode.effectiveScale });
             }
         }
         return finalText;
@@ -746,58 +916,62 @@ export class MergedExporter {
      * to the first model's equivalents. Matched entities are remapped and
      * their duplicate entity is skipped from output.
      *
-     * Matching strategy:
-     * - Sites/Buildings: by name (case-insensitive), or if only one in each model
-     * - Storeys: by name first, then by elevation (tolerance ±0.5 model units)
+     * Matching strategy per container type is driven by
+     * {@link MergeExportOptions.mergeSites} / `mergeBuildings` / `mergeStoreys`
+     * (all optional; omitted keeps the pre-existing combined heuristic):
+     * - Sites/Buildings: `'single'` (ignore name, unify iff exactly one in each
+     *   model), `'by-name'` (name only, no fallback), or omitted — name first,
+     *   else single-instance fallback.
+     * - Storeys: `'by-name'`, `'by-elevation'` (tolerance ±0.5 model units), or
+     *   `'by-name-then-elevation'` (default, also the omitted behavior).
      */
-    unifySpatialEntities(dataStore, lookup, firstModelOffset, sharedRemap, skipEntityIds) {
-        // Unify IfcSite
+    unifySpatialEntities(dataStore, lookup, firstModelOffset, elevationFactor, sharedRemap, skipEntityIds, mergeModes) {
+        // Unify IfcSite. matchedFirstSites guards against two of this model's
+        // sites (e.g. duplicate/identically-named) both matching the same
+        // first-model target — only the first claims it, the second is kept as
+        // its own root instead of silently losing its spatial sub-tree.
         const sites = this.findEntitiesByType(dataStore, 'IFCSITE');
+        const matchedFirstSites = new Set();
         for (const id of sites) {
-            const name = this.extractEntityName(id, dataStore);
-            let match;
-            if (name)
-                match = lookup.sitesByName.get(name.toLowerCase());
-            // If single site in both models, unify regardless of name
-            if (match === undefined && sites.length === 1 && lookup.siteIds.length === 1) {
-                match = lookup.siteIds[0];
-            }
+            const match = this.matchRootContainer(id, dataStore, mergeModes.mergeSites, sites.length, lookup.sitesByName, lookup.siteIds, matchedFirstSites);
             if (match !== undefined) {
+                matchedFirstSites.add(match);
                 sharedRemap.set(id, match + firstModelOffset);
                 skipEntityIds.add(id);
             }
         }
-        // Unify IfcBuilding
+        // Unify IfcBuilding — same already-matched guard as sites.
         const buildings = this.findEntitiesByType(dataStore, 'IFCBUILDING');
+        const matchedFirstBuildings = new Set();
         for (const id of buildings) {
-            const name = this.extractEntityName(id, dataStore);
-            let match;
-            if (name)
-                match = lookup.buildingsByName.get(name.toLowerCase());
-            if (match === undefined && buildings.length === 1 && lookup.buildingIds.length === 1) {
-                match = lookup.buildingIds[0];
-            }
+            const match = this.matchRootContainer(id, dataStore, mergeModes.mergeBuildings, buildings.length, lookup.buildingsByName, lookup.buildingIds, matchedFirstBuildings);
             if (match !== undefined) {
+                matchedFirstBuildings.add(match);
                 sharedRemap.set(id, match + firstModelOffset);
                 skipEntityIds.add(id);
             }
         }
-        // Unify IfcBuildingStorey — name match first, then elevation fallback
+        // Unify IfcBuildingStorey — mode-driven name/elevation matching
+        const storeyMode = mergeModes.mergeStoreys ?? 'by-name-then-elevation';
         const matchedFirstStoreys = new Set();
         for (const id of this.findEntitiesByType(dataStore, 'IFCBUILDINGSTOREY')) {
             const name = this.extractEntityName(id, dataStore);
             let match;
-            // Try name match
-            if (name) {
+            // Name match (skipped entirely under 'by-elevation')
+            if (storeyMode !== 'by-elevation' && name) {
                 const candidate = lookup.storeysByName.get(name.toLowerCase());
                 if (candidate !== undefined && !matchedFirstStoreys.has(candidate)) {
                     match = candidate;
                 }
             }
-            // Fallback: match by elevation
-            if (match === undefined) {
-                const elevation = this.extractStoreyElevation(id, dataStore);
-                if (elevation !== undefined) {
+            // Elevation match (skipped entirely under 'by-name'). The candidate's raw
+            // elevation is in this model's unit; scale it into the primary unit so the
+            // comparison (and the ±0.5 m tolerance) is unit-consistent under normalize
+            // (factor 1 otherwise).
+            if (match === undefined && storeyMode !== 'by-name') {
+                const rawElevation = this.extractStoreyElevation(id, dataStore);
+                if (rawElevation !== undefined) {
+                    const elevation = rawElevation * elevationFactor;
                     for (const entry of lookup.storeysByElevation) {
                         if (matchedFirstStoreys.has(entry.expressId))
                             continue;
@@ -816,6 +990,39 @@ export class MergedExporter {
             }
         }
     }
+    /**
+     * Match one IfcSite/IfcBuilding instance against the first model's
+     * equivalents, per {@link mergeMode}:
+     * - `'single'`: ignore name — unify iff both models contribute exactly one.
+     * - `'by-name'`: name match only, no single-instance fallback.
+     * - omitted: name match, else single-instance fallback (pre-existing heuristic).
+     *
+     * `matchedFirst` excludes first-model targets already claimed by an earlier
+     * entity in this same model's loop — without it, two of this model's sites
+     * (or buildings) sharing a name/being the sole instance would both resolve
+     * to the same target, and the second would be dropped (skipped + remapped)
+     * rather than kept as its own root.
+     */
+    matchRootContainer(id, dataStore, mergeMode, countInThisModel, firstModelByName, firstModelIds, matchedFirst) {
+        const bySingle = () => {
+            if (countInThisModel !== 1 || firstModelIds.length !== 1)
+                return undefined;
+            const candidate = firstModelIds[0];
+            return matchedFirst.has(candidate) ? undefined : candidate;
+        };
+        const byName = () => {
+            const name = this.extractEntityName(id, dataStore);
+            if (!name)
+                return undefined;
+            const candidate = firstModelByName.get(name.toLowerCase());
+            return candidate !== undefined && !matchedFirst.has(candidate) ? candidate : undefined;
+        };
+        if (mergeMode === 'single')
+            return bySingle();
+        if (mergeMode === 'by-name')
+            return byName();
+        return byName() ?? bySingle();
+    }
     /**
      * Skip IfcRelAggregates that become fully redundant after spatial unification.
      *