@ifc-lite/export 1.21.0 → 2.1.0

package/dist/merged-exporter.js

@@ -1,7 +1,7 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
-import { generateHeader } from '@ifc-lite/parser';
+import { generateHeader, deterministicGlobalId } from '@ifc-lite/parser';
 import { decodeIfcString } from '@ifc-lite/encoding';
 import { safeUtf8Decode } from '@ifc-lite/data';
 import { collectReferencedEntityIds, getVisibleEntityIds, collectStyleEntities } from './reference-collector.js';
@@ -14,18 +14,97 @@ const SHARED_INFRASTRUCTURE_TYPES = new Set([
     'IFCGEOMETRICREPRESENTATIONCONTEXT',
     'IFCGEOMETRICREPRESENTATIONSUBCONTEXT',
 ]);
+/**
+ * An IfcGloballyUniqueId is exactly 22 characters of the buildingSMART base64
+ * alphabet. We use this to recognise a rooted entity (IfcRoot subtype) by its
+ * first attribute. Geometry/list entities never carry a string there, but some
+ * non-rooted RESOURCE entities lead with a Name/Identifier string that can
+ * legitimately be 22 charset chars (e.g. a coded property key). Those are
+ * excluded by type ({@link NON_ROOTED_STRING_TYPES}) so their Name is never
+ * mistaken for a GlobalId — otherwise the GlobalId reconciliation could drop or
+ * rename them.
+ */
+const GLOBAL_ID_RE = /^[0-9A-Za-z_$]{22}$/;
+/**
+ * Non-IfcRoot entity types whose first attribute is (or can be) a quoted
+ * Name/Identifier string. They must NOT be treated as rooted by GlobalId, even
+ * when that string happens to be 22 charset characters. (IfcRoot property
+ * containers like IFCPROPERTYSET / IFCELEMENTQUANTITY are deliberately absent —
+ * they ARE rooted and carry a real GlobalId at attribute 0.)
+ *
+ * This is a best-effort denylist, not an exhaustive IfcRoot classifier — the
+ * merge works off raw STEP text and has no schema table. It covers the resource
+ * families that realistically appear in federated models; an unlisted
+ * string-leading resource type is only ever a problem if two models share an
+ * identical 22-char charset Name for it AND it collides, which is negligible. A
+ * miss in the other direction (treating a real root as non-rooted) is safe — it
+ * just skips one GlobalId reconciliation.
+ */
+const NON_ROOTED_STRING_TYPES = new Set([
+    // IfcSimpleProperty / IfcComplexProperty (IfcPropertyAbstraction — not rooted)
+    'IFCPROPERTYSINGLEVALUE', 'IFCPROPERTYENUMERATEDVALUE', 'IFCPROPERTYLISTVALUE',
+    'IFCPROPERTYBOUNDEDVALUE', 'IFCPROPERTYTABLEVALUE', 'IFCPROPERTYREFERENCEVALUE',
+    'IFCCOMPLEXPROPERTY',
+    // IfcPhysicalQuantity (not rooted)
+    'IFCQUANTITYLENGTH', 'IFCQUANTITYAREA', 'IFCQUANTITYVOLUME', 'IFCQUANTITYCOUNT',
+    'IFCQUANTITYWEIGHT', 'IFCQUANTITYTIME', 'IFCQUANTITYNUMBER', 'IFCPHYSICALCOMPLEXQUANTITY',
+    // Materials & their constituents (IfcMaterialDefinition — not rooted; lead with a Name)
+    'IFCMATERIAL', 'IFCMATERIALPROFILE', 'IFCMATERIALPROFILESET',
+    'IFCMATERIALCONSTITUENT', 'IFCMATERIALCONSTITUENTSET',
+    // Classification, library & document refs (IfcExternalInformation/Reference)
+    'IFCCLASSIFICATION', 'IFCCLASSIFICATIONREFERENCE',
+    'IFCLIBRARYINFORMATION', 'IFCLIBRARYREFERENCE', 'IFCEXTERNALREFERENCE',
+    'IFCDOCUMENTINFORMATION', 'IFCDOCUMENTREFERENCE',
+    // Constraints & approvals (lead with a Name/Identifier)
+    'IFCMETRIC', 'IFCOBJECTIVE', 'IFCAPPROVAL', 'IFCTABLE',
+    // Actors (IfcPerson/IfcOrganization lead with an Identification string)
+    'IFCPERSON', 'IFCORGANIZATION',
+    // Presentation layers, styles & text literals (lead with a Name/Literal string)
+    'IFCPRESENTATIONLAYERASSIGNMENT', 'IFCPRESENTATIONLAYERWITHSTYLE',
+    'IFCSURFACESTYLE', 'IFCCURVESTYLE', 'IFCTEXTSTYLE', 'IFCFILLAREASTYLE',
+    'IFCTEXTLITERAL', 'IFCTEXTLITERALWITHEXTENT',
+]);
+/** True for IfcRelationship subtypes (objectified relationships). */
+function isRelationshipType(typeUpper) {
+    return typeUpper.startsWith('IFCREL');
+}
+/** Relative tolerance for comparing two length unit scale factors. */
+const UNIT_SCALE_TOLERANCE = 1e-6;
 /**
  * Merges multiple IFC models into a single STEP file.
  *
  * Uses the same approach as IfcOpenShell's MergeProjects recipe, extended
- * with spatial hierarchy unification:
+ * with spatial hierarchy unification and unit-aware federation:
  * 1. First model's entities use their original IDs
  * 2. Subsequent models' IDs are offset to avoid collisions
- * 3. IfcProject is unified — all references remapped to the first model's project
- * 4. Spatial structure (Site, Building, Storey) is unified by name/elevation:
- *    matching entities are remapped to the first model's equivalents so that
- *    products from all models end up in the same unified tree
- * 5. Duplicate entities and shared infrastructure (units, contexts) are skipped
+ * 3. A model that shares the first model's length unit is *unified*: its
+ *    IfcProject is remapped to the first model's, spatial structure (Site,
+ *    Building, Storey) is unified by name/elevation, and shared infrastructure
+ *    (units, contexts) is deduplicated.
+ * 4. A model with a *different* length unit is *federated*: it keeps its own
+ *    IfcProject, IfcUnitAssignment and representation contexts, so its raw
+ *    coordinates remain correctly scaled rather than being reinterpreted under
+ *    the first model's unit (the mis-scale bug, issue #1332).
+ * 5. GlobalIds are reconciled, not blindly duplicated: a non-relationship
+ *    rooted entity that repeats a GlobalId already emitted *in the same unit
+ *    space* is unified (references remapped to the one instance). Otherwise —
+ *    a federated/different-unit instance, or an objectified relationship whose
+ *    payload (RelatedObjects) may differ — it is kept and re-stamped with a
+ *    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.
+ *
+ * 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
+ * each kept as independent projects (correct, just less deduplicated).
  */
 export class MergedExporter {
     models;
@@ -38,117 +117,39 @@ export class MergedExporter {
     export(options) {
         const onProgress = options.onProgress;
         const schema = (options.schema || 'IFC4');
-        // Generate header. Policy: a federated/merged file has no single source
-        // header to round-trip, so we deliberately emit an ifc-lite provenance
-        // header rather than picking one model's FILE_DESCRIPTION arbitrarily.
-        const header = generateHeader({
-            schema,
-            description: options.description || `Merged export of ${this.models.length} models from ifc-lite`,
-            author: options.author || '',
-            organization: options.organization || '',
-            application: options.application || 'ifc-lite',
-            filename: options.filename || 'merged.ifc',
-        });
+        const header = this.buildHeader(options, schema);
+        const setup = this.buildMergeSetup(options);
         const allEntityLines = [];
-        // Track ID offsets per model
-        let nextAvailableId = 1;
-        const modelOffsets = new Map();
-        // First pass: determine ID offsets. Span the COMPLETE entity set (incl.
-        // deferred property atoms) so the next model's offset clears every id this
-        // model will emit — otherwise a deferred atom at a high id collides.
-        for (const model of this.models) {
-            modelOffsets.set(model.id, nextAvailableId - 1); // offset = nextAvailableId - 1 so IDs start at nextAvailableId
-            nextAvailableId += getMaxExpressId(getCompleteEntityIndex(model.dataStore));
-        }
-        // Collect first model's info for deduplication
-        const firstModel = this.models[0];
-        const firstModelOffset = modelOffsets.get(firstModel.id);
-        const firstModelInfraMap = this.findInfrastructureEntities(firstModel.dataStore);
-        const firstProjectIds = this.findEntitiesByType(firstModel.dataStore, 'IFCPROJECT');
-        // Build spatial lookup from first model for Site/Building/Storey unification
-        const spatialLookup = this.buildSpatialLookup(firstModel.dataStore);
-        // Process each model
+        // Tracks every GlobalId already emitted → its final express id + unit scale,
+        // so later models can unify against (shared unit) or stay unique from
+        // (federated / different unit) it.
+        const guidToFinalId = new Map();
         let isFirstModel = true;
+        let federatedModelCount = 0;
         for (const model of this.models) {
-            const offset = modelOffsets.get(model.id);
+            const offset = setup.modelOffsets.get(model.id);
             const source = model.dataStore.source;
             if (!source || source.length === 0)
                 continue;
             // Complete view over byId + any deferred property atoms, so the closure
             // walk and the emit loop both reach every entity the source defines.
             const completeIndex = getCompleteEntityIndex(model.dataStore);
-            // Determine which entities to include
-            let includedEntityIds = null;
-            if (options.visibleOnly) {
-                const hiddenIds = options.hiddenEntityIdsByModel?.get(model.id) ?? new Set();
-                const isolatedIds = options.isolatedEntityIdsByModel?.get(model.id) ?? null;
-                const { roots, hiddenProductIds } = getVisibleEntityIds(model.dataStore, hiddenIds, isolatedIds);
-                includedEntityIds = collectReferencedEntityIds(roots, source, completeIndex, hiddenProductIds);
-                // Second pass: collect style entities that reference included geometry
-                collectStyleEntities(includedEntityIds, source, {
-                    byId: completeIndex,
-                    byType: model.dataStore.entityIndex.byType,
-                });
-            }
-            // Build remap table (references to remap) and skip set (entities to omit)
-            const sharedRemap = new Map();
-            const skipEntityIds = new Set();
-            if (!isFirstModel) {
-                // Remap this model's IfcProject references → first model's IfcProject.
-                const projectIds = this.findEntitiesByType(model.dataStore, 'IFCPROJECT');
-                if (firstProjectIds.length > 0) {
-                    for (const pid of projectIds) {
-                        sharedRemap.set(pid, firstProjectIds[0] + firstModelOffset);
-                        skipEntityIds.add(pid);
-                    }
-                }
-                // Remap and skip duplicate infrastructure (units, contexts)
-                const modelInfra = this.findInfrastructureEntities(model.dataStore);
-                for (const [type, firstIds] of firstModelInfraMap) {
-                    const thisIds = modelInfra.get(type);
-                    if (thisIds && firstIds.length > 0 && thisIds.length > 0) {
-                        sharedRemap.set(thisIds[0], firstIds[0] + firstModelOffset);
-                        skipEntityIds.add(thisIds[0]);
-                    }
-                }
-                // Unify spatial hierarchy: match Site, Building, Storey to first model
-                this.unifySpatialEntities(model.dataStore, spatialLookup, firstModelOffset, sharedRemap, skipEntityIds);
-                // Skip IfcRelAggregates that become fully redundant after unification.
-                // e.g. Model2's Project→Site becomes FirstProject→FirstSite which
-                // already exists from Model1, causing duplicate tree nodes.
-                this.skipRedundantRelAggregates(model.dataStore, sharedRemap, skipEntityIds);
-            }
-            // Emit entities for this model
+            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)
+                federatedModelCount++;
+            const plan = this.planModel(model, completeIndex, isFirstModel, compatible, setup, guidToFinalId);
+            const sourceSchema = model.dataStore.schemaVersion || 'IFC4';
             for (const [expressId, entityRef] of completeIndex) {
-                // Skip entities outside the visible closure
-                if (includedEntityIds !== null && !includedEntityIds.has(expressId)) {
+                if (includedEntityIds !== null && !includedEntityIds.has(expressId))
                     continue;
-                }
-                // Skip duplicate entities (project, infrastructure)
-                if (skipEntityIds.has(expressId)) {
+                if (plan.skipEntityIds.has(expressId))
                     continue;
-                }
-                // Get original entity text — safeUtf8Decode handles SAB-backed sources
-                const entityText = safeUtf8Decode(source, entityRef.byteOffset, entityRef.byteOffset + entityRef.byteLength);
-                // Remap IDs if this is not the first model or if offset is non-zero
-                let finalText;
-                if (offset === 0 && sharedRemap.size === 0) {
-                    finalText = entityText;
-                }
-                else {
-                    finalText = this.remapEntityText(entityText, offset, sharedRemap);
-                }
-                // Apply schema conversion if target differs from source
-                const sourceSchema = model.dataStore.schemaVersion || 'IFC4';
-                if (needsConversion(sourceSchema, schema)) {
-                    const converted = convertStepLine(finalText, sourceSchema, schema);
-                    if (converted !== null) {
-                        allEntityLines.push(converted);
-                    }
-                }
-                else {
-                    allEntityLines.push(finalText);
-                }
+                const line = this.renderEntity(expressId, entityRef, source, offset, plan, sourceSchema, schema, guidToFinalId, modelScale);
+                if (line !== null)
+                    allEntityLines.push(line);
             }
             isFirstModel = false;
         }
@@ -158,11 +159,7 @@ export class MergedExporter {
         const content = assembleStepBytes(header, allEntityLines);
         return {
             content,
-            stats: {
-                modelCount: this.models.length,
-                totalEntityCount: allEntityLines.length,
-                fileSize: content.byteLength,
-            },
+            stats: this.buildStats(allEntityLines.length, content.byteLength, federatedModelCount),
         };
     }
     /**
@@ -175,38 +172,23 @@ export class MergedExporter {
         const schema = (options.schema || 'IFC4');
         // See export(): merged files emit an ifc-lite provenance header by policy
         // (no single source header to preserve across federated models).
-        const header = generateHeader({
-            schema,
-            description: options.description || `Merged export of ${this.models.length} models from ifc-lite`,
-            author: options.author || '',
-            organization: options.organization || '',
-            application: options.application || 'ifc-lite',
-            filename: options.filename || 'merged.ifc',
-        });
+        const header = this.buildHeader(options, schema);
+        const setup = this.buildMergeSetup(options);
         const allEntityLines = [];
+        const guidToFinalId = new Map();
         // First pass: count total entities for progress
         let totalEntities = 0;
         for (const model of this.models) {
             totalEntities += getCompleteEntityIndex(model.dataStore).size;
         }
-        let nextAvailableId = 1;
-        const modelOffsets = new Map();
-        for (const model of this.models) {
-            modelOffsets.set(model.id, nextAvailableId - 1);
-            nextAvailableId += getMaxExpressId(getCompleteEntityIndex(model.dataStore));
-        }
-        const firstModel = this.models[0];
-        const firstModelOffset = modelOffsets.get(firstModel.id);
-        const firstModelInfraMap = this.findInfrastructureEntities(firstModel.dataStore);
-        const firstProjectIds = this.findEntitiesByType(firstModel.dataStore, 'IFCPROJECT');
-        const spatialLookup = this.buildSpatialLookup(firstModel.dataStore);
         let isFirstModel = true;
         let entitiesProcessed = 0;
+        let federatedModelCount = 0;
         const YIELD_INTERVAL = 2000;
         if (onProgress)
             onProgress({ phase: 'preparing', percent: 0, entitiesProcessed: 0, entitiesTotal: totalEntities });
         for (const model of this.models) {
-            const offset = modelOffsets.get(model.id);
+            const offset = setup.modelOffsets.get(model.id);
             const source = model.dataStore.source;
             if (!source || source.length === 0)
                 continue;
@@ -220,61 +202,23 @@ export class MergedExporter {
                 });
             }
             const completeIndex = getCompleteEntityIndex(model.dataStore);
-            let includedEntityIds = null;
-            if (options.visibleOnly) {
-                const hiddenIds = options.hiddenEntityIdsByModel?.get(model.id) ?? new Set();
-                const isolatedIds = options.isolatedEntityIdsByModel?.get(model.id) ?? null;
-                const { roots, hiddenProductIds } = getVisibleEntityIds(model.dataStore, hiddenIds, isolatedIds);
-                includedEntityIds = collectReferencedEntityIds(roots, source, completeIndex, hiddenProductIds);
-                collectStyleEntities(includedEntityIds, source, {
-                    byId: completeIndex,
-                    byType: model.dataStore.entityIndex.byType,
-                });
-            }
-            const sharedRemap = new Map();
-            const skipEntityIds = new Set();
-            if (!isFirstModel) {
-                const projectIds = this.findEntitiesByType(model.dataStore, 'IFCPROJECT');
-                if (firstProjectIds.length > 0) {
-                    for (const pid of projectIds) {
-                        sharedRemap.set(pid, firstProjectIds[0] + firstModelOffset);
-                        skipEntityIds.add(pid);
-                    }
-                }
-                const modelInfra = this.findInfrastructureEntities(model.dataStore);
-                for (const [type, firstIds] of firstModelInfraMap) {
-                    const thisIds = modelInfra.get(type);
-                    if (thisIds && firstIds.length > 0 && thisIds.length > 0) {
-                        sharedRemap.set(thisIds[0], firstIds[0] + firstModelOffset);
-                        skipEntityIds.add(thisIds[0]);
-                    }
-                }
-                this.unifySpatialEntities(model.dataStore, spatialLookup, firstModelOffset, sharedRemap, skipEntityIds);
-                this.skipRedundantRelAggregates(model.dataStore, sharedRemap, skipEntityIds);
-            }
+            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)
+                federatedModelCount++;
+            const plan = this.planModel(model, completeIndex, isFirstModel, compatible, setup, guidToFinalId);
+            const sourceSchema = model.dataStore.schemaVersion || 'IFC4';
             let entityCount = 0;
             for (const [expressId, entityRef] of completeIndex) {
                 if (includedEntityIds !== null && !includedEntityIds.has(expressId))
                     continue;
-                if (skipEntityIds.has(expressId))
+                if (plan.skipEntityIds.has(expressId))
                     continue;
-                const entityText = safeUtf8Decode(source, entityRef.byteOffset, entityRef.byteOffset + entityRef.byteLength);
-                let finalText;
-                if (offset === 0 && sharedRemap.size === 0) {
-                    finalText = entityText;
-                }
-                else {
-                    finalText = this.remapEntityText(entityText, offset, sharedRemap);
-                }
-                const sourceSchema = model.dataStore.schemaVersion || 'IFC4';
-                if (needsConversion(sourceSchema, schema)) {
-                    const converted = convertStepLine(finalText, sourceSchema, schema);
-                    if (converted !== null)
-                        allEntityLines.push(converted);
-                }
-                else {
-                    allEntityLines.push(finalText);
-                }
+                const line = this.renderEntity(expressId, entityRef, source, offset, plan, sourceSchema, schema, guidToFinalId, modelScale);
+                if (line !== null)
+                    allEntityLines.push(line);
                 entityCount++;
                 entitiesProcessed++;
                 // Yield to event loop every YIELD_INTERVAL entities
@@ -304,13 +248,311 @@ export class MergedExporter {
         }
         return {
             content,
-            stats: {
-                modelCount: this.models.length,
-                totalEntityCount: allEntityLines.length,
-                fileSize: content.byteLength,
-            },
+            stats: this.buildStats(allEntityLines.length, content.byteLength, federatedModelCount),
+        };
+    }
+    /**
+     * Assemble the result stats, including any federation conformance warnings.
+     */
+    buildStats(totalEntityCount, fileSize, federatedModelCount) {
+        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.`);
+        }
+        return { modelCount: this.models.length, totalEntityCount, fileSize, federatedModelCount, warnings };
+    }
+    /**
+     * Build the ifc-lite provenance header. Merged files have no single source
+     * header to round-trip, so we deliberately emit our own rather than picking
+     * one model's FILE_DESCRIPTION arbitrarily.
+     */
+    buildHeader(options, schema) {
+        return generateHeader({
+            schema,
+            description: options.description || `Merged export of ${this.models.length} models from ifc-lite`,
+            author: options.author || '',
+            organization: options.organization || '',
+            application: options.application || 'ifc-lite',
+            filename: options.filename || 'merged.ifc',
+        });
+    }
+    /**
+     * Compute the model-independent state shared by export()/exportAsync():
+     * per-model id offsets and the primary model's project/infra/spatial/unit info.
+     */
+    buildMergeSetup(options) {
+        // Determine ID offsets. Span the COMPLETE entity set (incl. deferred
+        // property atoms) so the next model's offset clears every id this model
+        // will emit — otherwise a deferred atom at a high id collides.
+        let nextAvailableId = 1;
+        const modelOffsets = new Map();
+        for (const model of this.models) {
+            modelOffsets.set(model.id, nextAvailableId - 1); // start at nextAvailableId
+            nextAvailableId += getMaxExpressId(getCompleteEntityIndex(model.dataStore));
+        }
+        const firstModel = this.models[0];
+        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),
+            assumeShared: options.unitReconciliation === 'assume-shared',
         };
     }
+    /**
+     * Resolve a model's length unit scale (raw IFC length → metres). Prefers an
+     * explicit `lengthUnitScale` on the input, else the value the parser stamped
+     * on the data store, else metres.
+     */
+    resolveUnitScale(model) {
+        const explicit = model.lengthUnitScale;
+        if (typeof explicit === 'number' && explicit > 0)
+            return explicit;
+        const fromStore = model.dataStore.lengthUnitScale;
+        if (typeof fromStore === 'number' && fromStore > 0)
+            return fromStore;
+        return 1.0;
+    }
+    /** True when two length unit scales are equal within relative tolerance. */
+    unitsCompatible(a, b) {
+        if (a === b)
+            return true;
+        const max = Math.max(Math.abs(a), Math.abs(b));
+        if (max === 0)
+            return true;
+        return Math.abs(a - b) <= max * UNIT_SCALE_TOLERANCE;
+    }
+    /**
+     * Resolve the set of express ids to include for a model under visibility
+     * filtering, or `null` when no filtering is requested (include everything).
+     */
+    computeIncludedEntityIds(model, options, completeIndex, source) {
+        if (!options.visibleOnly)
+            return null;
+        const hiddenIds = options.hiddenEntityIdsByModel?.get(model.id) ?? new Set();
+        const isolatedIds = options.isolatedEntityIdsByModel?.get(model.id) ?? null;
+        const { roots, hiddenProductIds } = getVisibleEntityIds(model.dataStore, hiddenIds, isolatedIds);
+        const included = collectReferencedEntityIds(roots, source, completeIndex, hiddenProductIds);
+        // Second pass: collect style entities that reference included geometry.
+        collectStyleEntities(included, source, {
+            byId: completeIndex,
+            byType: model.dataStore.entityIndex.byType,
+        });
+        return included;
+    }
+    /**
+     * 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.
+     *
+     * Incompatible (federated) models keep their own project, units, contexts and
+     * spatial structure so their coordinates stay correctly scaled; a rooted
+     * entity whose GlobalId collides with one already emitted is given a fresh
+     * deterministic GlobalId, since the two cannot be the same instance across
+     * different unit spaces.
+     */
+    planModel(model, completeIndex, isFirstModel, compatible, setup, guidToFinalId) {
+        const source = model.dataStore.source;
+        const sharedRemap = new Map();
+        const skipEntityIds = new Set();
+        const guidRewrite = new Map();
+        // One cheap pass to read each rooted entity's GlobalId (first attribute).
+        const localGuids = new Map();
+        for (const [id, ref] of completeIndex) {
+            const guid = this.extractGlobalIdFast(ref, source);
+            if (guid !== null)
+                localGuids.set(id, guid);
+        }
+        if (!isFirstModel && compatible) {
+            // Remap this model's IfcProject references → first model's IfcProject.
+            const projectIds = this.findEntitiesByType(model.dataStore, 'IFCPROJECT');
+            if (setup.firstProjectIds.length > 0) {
+                for (const pid of projectIds) {
+                    sharedRemap.set(pid, setup.firstProjectIds[0] + setup.firstModelOffset);
+                    skipEntityIds.add(pid);
+                }
+            }
+            // Remap and skip duplicate infrastructure (units, contexts).
+            const modelInfra = this.findInfrastructureEntities(model.dataStore);
+            for (const [type, firstIds] of setup.firstModelInfraMap) {
+                const thisIds = modelInfra.get(type);
+                if (thisIds && firstIds.length > 0 && thisIds.length > 0) {
+                    sharedRemap.set(thisIds[0], firstIds[0] + setup.firstModelOffset);
+                    skipEntityIds.add(thisIds[0]);
+                }
+            }
+            // Unify spatial hierarchy: match Site, Building, Storey to first model.
+            this.unifySpatialEntities(model.dataStore, setup.spatialLookup, setup.firstModelOffset, sharedRemap, skipEntityIds);
+            // Skip IfcRelAggregates that become fully redundant after unification.
+            this.skipRedundantRelAggregates(model.dataStore, sharedRemap, skipEntityIds);
+        }
+        if (!isFirstModel) {
+            // GlobalId reconciliation against everything emitted by earlier models.
+            const pendingMinted = new Set();
+            for (const [id, guid] of localGuids) {
+                if (skipEntityIds.has(id))
+                    continue; // already unified/deduped above
+                const prior = guidToFinalId.get(guid);
+                if (prior === undefined)
+                    continue; // first occurrence — kept as-is
+                // Unify (drop + remap refs to the one instance) ONLY when this is a
+                // physical/spatial root AND both this model and the emitter share the
+                // primary unit. Two conditions force "keep + re-stamp" instead:
+                //   - Objectified relationships (IfcRel*): same GlobalId does not imply
+                //     the same membership (e.g. a storey-containment listing different
+                //     elements per discipline), so dropping one would orphan elements.
+                //   - The colliding instance was emitted in a different unit space
+                //     (a federated model), so unifying would reinterpret coordinates —
+                //     the very mis-scale this fix prevents, reached transitively.
+                const type = (completeIndex.get(id)?.type ?? '').toUpperCase();
+                const emitterIsPrimaryUnit = this.unitsCompatible(prior.scale, setup.primaryScale);
+                const canUnify = compatible && emitterIsPrimaryUnit && !isRelationshipType(type);
+                if (canUnify) {
+                    sharedRemap.set(id, prior.finalId);
+                    skipEntityIds.add(id);
+                }
+                else {
+                    guidRewrite.set(id, this.mintUniqueGuid(guid, model.id, guidToFinalId, pendingMinted));
+                }
+            }
+        }
+        return { sharedRemap, skipEntityIds, guidRewrite, localGuids };
+    }
+    /**
+     * Render one source entity into its final STEP line: apply id offset + shared
+     * remaps, re-stamp a federated GlobalId if needed, apply schema conversion,
+     * 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) {
+        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;
+        if (offset === 0 && plan.sharedRemap.size === 0) {
+            finalText = entityText;
+        }
+        else {
+            finalText = this.remapEntityText(entityText, offset, plan.sharedRemap);
+        }
+        // Re-stamp the GlobalId for a federated entity whose id collides.
+        const mintedGuid = plan.guidRewrite.get(localId);
+        if (mintedGuid !== undefined) {
+            finalText = this.replaceGlobalId(finalText, mintedGuid);
+        }
+        if (needsConversion(sourceSchema, targetSchema)) {
+            const converted = convertStepLine(finalText, sourceSchema, targetSchema);
+            if (converted === null)
+                return null;
+            finalText = converted;
+        }
+        // Record the emitted GlobalId → final express id + unit scale, for rooted
+        // entities only. Read it from the FINAL line, not the source: schema
+        // conversion can replace an unsupported rooted type with an IFCPROXY that
+        // carries a freshly-minted GlobalId, so the source guid would be stale.
+        // Emitted entities are not sharedRemap keys, so their final id is
+        // localId + offset.
+        if (plan.localGuids.has(localId)) {
+            const emittedGuid = this.readLeadingGuid(finalText)
+                ?? mintedGuid ?? plan.localGuids.get(localId);
+            if (emittedGuid !== undefined) {
+                guidToFinalId.set(emittedGuid, { finalId: localId + offset, scale: modelScale });
+            }
+        }
+        return finalText;
+    }
+    /**
+     * Read the GlobalId (first quoted attribute) from an already-rendered STEP
+     * line. Used to register the id that was actually emitted, after any id
+     * remap, GlobalId re-stamp, or schema conversion. Returns null if the first
+     * quoted token is not a 22-char GlobalId.
+     */
+    readLeadingGuid(entityText) {
+        const open = entityText.indexOf('(');
+        if (open === -1)
+            return null;
+        const q1 = entityText.indexOf("'", open + 1);
+        if (q1 === -1)
+            return null;
+        const q2 = entityText.indexOf("'", q1 + 1);
+        if (q2 === -1)
+            return null;
+        const raw = entityText.slice(q1 + 1, q2);
+        return GLOBAL_ID_RE.test(raw) ? raw : null;
+    }
+    /**
+     * Mint a fresh, deterministic, collision-free GlobalId for an entity whose id
+     * collides. Seeded from the original GlobalId and the model's stable id so the
+     * output is reproducible and does not churn when an unrelated earlier model
+     * changes size; checked against both already-emitted ids and the ids minted
+     * so far for this model.
+     */
+    mintUniqueGuid(original, modelId, guidToFinalId, pendingMinted) {
+        let candidate = deterministicGlobalId(`${original}#${modelId}`);
+        let n = 0;
+        while (guidToFinalId.has(candidate) || pendingMinted.has(candidate)) {
+            candidate = deterministicGlobalId(`${original}#${modelId}#${n++}`);
+        }
+        pendingMinted.add(candidate);
+        return candidate;
+    }
+    /**
+     * Read an entity's GlobalId (first attribute) by decoding only its head.
+     * Returns the 22-char id for a rooted entity, or `null` for any entity whose
+     * first attribute is not a GlobalId (geometry, lists, property atoms, …).
+     */
+    extractGlobalIdFast(ref, source) {
+        // Non-rooted resource entities (property/quantity/material/style/actor …)
+        // lead with a Name string that can itself be 22 charset chars; never treat
+        // those as a GlobalId or reconciliation would drop/rename them.
+        if (NON_ROOTED_STRING_TYPES.has((ref.type ?? '').toUpperCase()))
+            return null;
+        // 128 bytes comfortably spans `#<id>=<LONGEST_TYPE_NAME>('<22-char id>'`,
+        // so the GlobalId is always fully inside the window.
+        const end = Math.min(ref.byteOffset + 128, ref.byteOffset + ref.byteLength);
+        const head = safeUtf8Decode(source, ref.byteOffset, end);
+        const open = head.indexOf('(');
+        if (open === -1)
+            return null;
+        let i = open + 1;
+        while (i < head.length && (head[i] === ' ' || head[i] === '\t' || head[i] === '\n' || head[i] === '\r'))
+            i++;
+        if (head[i] !== "'")
+            return null;
+        // A GlobalId never contains a quote (charset excludes it), so the next
+        // quote closes it.
+        const close = head.indexOf("'", i + 1);
+        if (close === -1)
+            return null;
+        const raw = head.slice(i + 1, close);
+        return GLOBAL_ID_RE.test(raw) ? raw : null;
+    }
+    /**
+     * Replace an entity's GlobalId (first quoted attribute) with `newGuid`.
+     * `newGuid` is a 22-char IFC id (no quote in its charset), so this is safe.
+     */
+    replaceGlobalId(entityText, newGuid) {
+        const open = entityText.indexOf('(');
+        if (open === -1)
+            return entityText;
+        const q1 = entityText.indexOf("'", open + 1);
+        if (q1 === -1)
+            return entityText;
+        const q2 = entityText.indexOf("'", q1 + 1);
+        if (q2 === -1)
+            return entityText;
+        return entityText.slice(0, q1 + 1) + newGuid + entityText.slice(q2);
+    }
     /**
      * Remap all #ID references in a STEP entity line.
      * Applies offset to all IDs, then overrides with specific remappings.