@bldrs-ai/conway 1.389.1221 → 1.394.1504

package/compiled/src/ifc/ifc_geometry_extraction.js

@@ -1,19 +1,32 @@
 import { BlendMode, } from "../../dependencies/conway-geom/index.js";
+import { Uint32Sink } from "../step/parsing/uint32_sink.js";
+import { StepBufferNotResidentError } from "../step/step_buffer_provider.js";
 import { exponentToRoughness } from "../core/canonical_material.js";
 import { CanonicalMeshType } from "../core/canonical_mesh.js";
 import { yieldToEventLoop } from "../core/progress.js";
 import { ObjectPool } from "../core/native_pool.js";
 import { ExtractResult } from "../core/shared_constants.js";
-import { IfcArbitraryClosedProfileDef, IfcAxis2Placement2D, IfcAxis2Placement3D, IfcBooleanResult, IfcCartesianPointList2D, IfcCartesianPointList3D, IfcCartesianTransformationOperator3D, IfcCircleProfileDef, IfcColourRgb, IfcCompositeProfileDef, IfcExtrudedAreaSolid, IfcGridPlacement, IfcIndexedPolyCurve, IfcIndexedPolygonalFaceWithVoids, IfcLocalPlacement, IfcMappedItem, IfcOpeningElement, IfcOpeningStandardCase, IfcPolygonalFaceSet, IfcProduct, IfcReflectanceMethodEnum, IfcSpace, IfcSpecularExponent, IfcStyledItem, IfcSurfaceStyle, IfcSurfaceStyleRefraction, IfcSurfaceStyleRendering, IfcSurfaceStyleShading, IfcPresentationStyleAssignment, IfcSurfaceSide, IfcBooleanClippingResult, IfcCompositeCurve, IfcPolyline, IfcTrimmedCurve, IfcCartesianPoint, IfcParameterValue, IfcTrimmingPreference, IfcCircle, IfcHalfSpaceSolid, IfcPlane, IfcBoundingBox, IfcShellBasedSurfaceModel, IfcPolyLoop, IfcFacetedBrep, IfcRelAssociatesMaterial, IfcShapeRepresentation, IfcMaterialList, IfcMaterialDefinitionRepresentation, IfcMaterialLayerSetUsage, IfcMaterial, IfcRelVoidsElement, IfcRectangleProfileDef, IfcMaterialProfileSet, IfcMaterialConstituentSet, IfcMaterialConstituent, IfcMaterialProfile, IfcProject, IfcSIUnit, IfcSIPrefix, IfcUnitEnum, IfcSIUnitName, IfcConversionBasedUnit, IfcFaceBasedSurfaceModel, IfcArbitraryProfileDefWithVoids, IfcAdvancedBrep, IfcBSplineCurve, IfcBSplineSurface, IfcBSplineSurfaceWithKnots, IfcRationalBSplineSurfaceWithKnots, IfcCylindricalSurface, IfcSurfaceOfRevolution, IfcSurfaceOfLinearExtrusion, IfcRationalBSplineCurveWithKnots, IfcArbitraryOpenProfileDef, IfcBSplineCurveWithKnots, IfcEdgeLoop, IfcEdgeCurve, IfcVertexPoint, IfcRectangleHollowProfileDef, IfcEllipseProfileDef, IfcCircleHollowProfileDef, IfcIShapeProfileDef, IfcUShapeProfileDef, IfcDerivedProfileDef, IfcCartesianTransformationOperator2DnonUniform, IfcLShapeProfileDef, IfcCShapeProfileDef, IfcTShapeProfileDef, IfcZShapeProfileDef, IfcRelAggregates, IfcTriangulatedFaceSet, IfcPolygonalBoundedHalfSpace, IfcLine, IfcEllipse, IfcMaterialLayerSet, IfcSweptDiskSolid, IfcBlock, IfcRoundedRectangleProfileDef, IfcMaterialProfileSetUsage, IfcCompositeCurveSegment, IfcRevolvedAreaSolid, IfcFaceSurface, } from "./ifc4_gen/index.js";
+import { IfcArbitraryClosedProfileDef, IfcAxis2Placement2D, IfcAxis2Placement3D, IfcBooleanResult, IfcCartesianPointList2D, IfcCartesianPointList3D, IfcCartesianTransformationOperator3D, IfcCircleProfileDef, IfcColourRgb, IfcCompositeProfileDef, IfcDirection, IfcExtrudedAreaSolid, IfcGrid, IfcGridPlacement, IfcIndexedPolyCurve, IfcIndexedPolygonalFaceWithVoids, IfcLocalPlacement, IfcMappedItem, IfcOpeningElement, IfcOpeningStandardCase, IfcPolygonalFaceSet, IfcProduct, IfcReflectanceMethodEnum, IfcSpace, IfcSpecularExponent, IfcStyledItem, IfcSurfaceStyle, IfcSurfaceStyleRefraction, IfcSurfaceStyleRendering, IfcSurfaceStyleShading, IfcPresentationStyleAssignment, IfcSurfaceSide, IfcBooleanClippingResult, IfcCompositeCurve, IfcPolyline, IfcTrimmedCurve, IfcCartesianPoint, IfcParameterValue, IfcTrimmingPreference, IfcCircle, IfcHalfSpaceSolid, IfcPlane, IfcBoundingBox, IfcShellBasedSurfaceModel, IfcPolyLoop, IfcFacetedBrep, IfcRelAssociatesMaterial, IfcShapeRepresentation, IfcMaterialList, IfcMaterialDefinitionRepresentation, IfcMaterialLayerSetUsage, IfcMaterial, IfcRelVoidsElement, IfcRectangleProfileDef, IfcMaterialProfileSet, IfcMaterialConstituentSet, IfcMaterialConstituent, IfcMaterialProfile, IfcProject, IfcSIUnit, IfcSIPrefix, IfcUnitEnum, IfcSIUnitName, IfcConversionBasedUnit, IfcFaceBasedSurfaceModel, IfcArbitraryProfileDefWithVoids, IfcAdvancedBrep, IfcBSplineCurve, IfcBSplineSurface, IfcBSplineSurfaceWithKnots, IfcRationalBSplineSurfaceWithKnots, IfcCylindricalSurface, IfcSurfaceOfRevolution, IfcSurfaceOfLinearExtrusion, IfcRationalBSplineCurveWithKnots, IfcArbitraryOpenProfileDef, IfcBSplineCurveWithKnots, IfcEdgeLoop, IfcEdgeCurve, IfcVertexPoint, IfcRectangleHollowProfileDef, IfcEllipseProfileDef, IfcCircleHollowProfileDef, IfcIShapeProfileDef, IfcUShapeProfileDef, IfcDerivedProfileDef, IfcCartesianTransformationOperator2DnonUniform, IfcLShapeProfileDef, IfcCShapeProfileDef, IfcTShapeProfileDef, IfcZShapeProfileDef, IfcRelAggregates, IfcTriangulatedFaceSet, IfcPolygonalBoundedHalfSpace, IfcLine, IfcEllipse, IfcMaterialLayerSet, IfcSweptDiskSolid, IfcBlock, IfcRoundedRectangleProfileDef, IfcMaterialProfileSetUsage, IfcCompositeCurveSegment, IfcRevolvedAreaSolid, IfcFaceSurface, IfcVirtualGridIntersection, } from "./ifc4_gen/index.js";
 import EntityTypesIfc from "./ifc4_gen/entity_types_ifc.gen.js";
 import { IfcSceneBuilder } from "./ifc_scene_builder.js";
 import Logger from "../logging/logger.js";
+import { arraysToWasmHeap, arrayToWasmHeap, freeAll, wasmHeapView, withRelease, } from "../core/wasm_heap.js";
 import { REFLECTANCE_METHOD_PERMISSIVE, MATERIAL_RELATED_OBJECTS_PERMISSIVE } from "./ifc_parser_quirks.js";
 import { CsgOperationType } from "../core/csg_operations.js";
 import { MemoizationCapture, RegressionCaptureState } from "../core/regression_capture_state.js";
 // Await cadence for extractIFCGeometryDataAsync: long enough that yielding
 // doesn't dominate, short enough that browser paint + watchdogs stay live.
 const DEFAULT_GEOMETRY_YIELD_INTERVAL_MS = 50;
+// IfcVirtualGridIntersection.IntersectingAxes is LIST [2:2] and
+// OffsetDistances LIST [2:3], the third entry displacing the intersection
+// along the grid placement's z axis.
+const GRID_INTERSECTION_AXIS_COUNT = 2;
+const GRID_INTERSECTION_Z_OFFSET = 2;
+// Sine of the smallest angle two grid axes may cross at and still be treated
+// as intersecting. Grid axes cross at architectural angles, so this only has
+// to separate "crossing" from "drawn along each other" (or from an axis with
+// no length at all).
+const GRID_AXIS_PARALLEL_EPSILON = 1e-9;
 /**
  * Extract a specular highlight, converting specular exponents to a roughness value.
  *
@@ -108,23 +121,44 @@ export function extractColorOrFactorMultiply(from, surfaceColor, alpha = 1) {
  * Handles Geometry data extraction from a populated IfcStepModel
  * Can export to OBJ, GLTF (Draco), GLB (Draco)
  */
+/**
+ * Starting capacities for the reused polygonal-faceset sinks: enough that a
+ * typical faceset never reallocates, while still growing for outliers.
+ */
+/**
+ * Vtable coordinates of IfcPolygonalFaceSet.Faces and
+ * IfcIndexedPolygonalFace.CoordIndex, mirroring their generated
+ * getters. The equivalence test in uint32_sink.test.ts fails loudly if
+ * codegen ever moves them.
+ */
+const FACES_FIELD_OFFSET = 2;
+const FACES_FIELD_BASE_OFFSET = 1;
+const FACES_FIELD_DEPTH = 4;
+/** IfcRelAggregates.RelatedObjects — see IfcRelAggregates.gen.ts. */
+const REL_AGGREGATES_RELATED_OFFSET = 5;
+const REL_AGGREGATES_RELATED_BASE = 4;
+const REL_AGGREGATES_RELATED_DEPTH = 3;
+/** IfcRelAssociates.RelatedObjects — see IfcRelAssociates.gen.ts. */
+const REL_ASSOCIATES_RELATED_OFFSET = 4;
+const REL_ASSOCIATES_RELATED_BASE = 4;
+const REL_ASSOCIATES_RELATED_DEPTH = 2;
+const COORD_INDEX_FIELD_OFFSET = 0;
+const POLYGONAL_INDEX_SINK_CAPACITY = 65536;
+const POLYGONAL_FACE_SINK_CAPACITY = 16384;
 export class IfcGeometryExtraction {
-    /**
-     * Construct a geometry extraction from an IFC step model and conway model
-     *
-     * @param conwayModel The ConwayGeometry instance to use for geometry operations.
-     * @param model The IfcStepModel instance representing the IFC model.
-     * @param limitCSGDepth Whether to limit the depth of CSG operations.
-     * @param csgDepthLimit The maximum depth for CSG operations when limit CSG depth is used,
-     * or the maximum level for CSG memoization if it is not.
-     * @param lowMemoryMode Whether to enable low memory mode for geometry extraction.
-     */
     constructor(conwayModel, model, limitCSGDepth = true, csgDepthLimit = 20, lowMemoryMode = false) {
         this.conwayModel = conwayModel;
         this.model = model;
         this.limitCSGDepth = limitCSGDepth;
         this.csgDepthLimit = csgDepthLimit;
         this.lowMemoryMode = lowMemoryMode;
+        /* Reused across polygonal-faceset extractions; see extractPolygonalFaceSet. */
+        this.polygonalIndexSink_ = new Uint32Sink(POLYGONAL_INDEX_SINK_CAPACITY);
+        this.polygonalStartIndexSink_ = new Uint32Sink(POLYGONAL_FACE_SINK_CAPACITY);
+        this.polygonalFaceOffsetSink_ = new Uint32Sink(POLYGONAL_FACE_SINK_CAPACITY);
+        this.polygonalStartOffsetSink_ = new Uint32Sink(POLYGONAL_FACE_SINK_CAPACITY);
+        /* Guards the sinks against a re-entrant faceset extraction. */
+        this.polygonalSinksInUse_ = false;
         this.TWO_DIMENSIONS = 2;
         this.THREE_DIMENSIONS = 3;
         this.circleSegments = 12;
@@ -138,8 +172,28 @@ export class IfcGeometryExtraction {
          */
         this.geometryTypeCounts = new Map();
         this.csgDepth = 0;
+        /** When true, a product whose ObjectPlacement — or any record in its
+         * placement chain — is a dangling forward reference is treated as not
+         * yet extractable (the extraction throws, and the caller skips the
+         * product) instead of being silently extracted UNPLACED.
+         *
+         * Set by the parse-time preview channel's PREFIX extractions. A
+         * mid-parse prefix nulls dangling optional references
+         * (`nullOnErrors`), so a product whose placement record sits beyond
+         * the prefix — Revit writes placements near the end of the file, e.g.
+         * Snowdon's first door is record #5014 with its IFCLOCALPLACEMENT at
+         * #789283 — read as "no placement" and extracted at the origin. On a
+         * georeferenced model the preview then composed
+         * coordination x identity, emitting geometry ~425km from the model
+         * (Share#1744). The durable extraction runs on the full model, where
+         * nothing dangles, and keeps the classic lenient read. */
+        this.deferDanglingPlacements = false;
         this.freeVectorPolygonalFaces_ = [];
+        // Guards prepareExtractionMaps_ so the demand path and the whole-model
+        // walk can both trigger it without duplicating work.
+        this.extractionMapsPrepared_ = false;
         this.csgMemoization = !this.lowMemoryMode;
+        this.quietRecoverableLogging = false;
         this.materials = model.materials;
         this.scene = new IfcSceneBuilder(model, conwayModel, this.materials);
         this.voidMaterials = model.voidMaterials;
@@ -523,20 +577,173 @@ export class IfcGeometryExtraction {
             this.model.voidGeometry.add(canonicalMesh);
         }
     }
+    /**
+     * Hand a faceset's accumulated indices to wasm and register the
+     * resulting mesh. Shared by the fast reference-level path and the
+     * generated-getter fallback so they cannot diverge.
+     *
+     * @param entity The faceset.
+     * @param temporary Is this a temporary (preview//operand) extraction?
+     * @param isRelVoid Is this geometry a rel-void operand?
+     * @param allIndices Face indices, concatenated.
+     * @param allStartIndices Per-face start indices.
+     * @param polygonalFaceBufferOffsets Per-face offsets into allIndices.
+     * @param startIndicesBufferOffsets Per-face offsets into allStartIndices.
+     * @return {ExtractResult} The extraction result.
+     */
+    finishPolygonalFaceSet_(entity, temporary, isRelVoid, allIndices, allStartIndices, polygonalFaceBufferOffsets, startIndicesBufferOffsets) {
+        // Add the final entry
+        polygonalFaceBufferOffsets.push(allIndices.length);
+        startIndicesBufferOffsets.push(allStartIndices.length);
+        // Views over exactly the appended elements — no intermediate copy.
+        const indicesArray = allIndices.view;
+        const startIndicesArray = allStartIndices.view;
+        const polygonalFaceBufferOffsetsArray = polygonalFaceBufferOffsets.view;
+        const startIndicesBufferOffsetsArray = startIndicesBufferOffsets.view;
+        // All four together, so a failed allocation part-way through cannot strand
+        // the ones already taken. Everything after this point is inside the
+        // try/finally below, which is what actually guarantees they come back.
+        const [indicesArrayPtr, startIndicesArrayPtr, polygonalFaceBufferOffsetsArrayPtr, startIndicesBufferOffsetsArrayPtr,] = arraysToWasmHeap(this.wasmModule, [
+            indicesArray,
+            startIndicesArray,
+            polygonalFaceBufferOffsetsArray,
+            startIndicesBufferOffsetsArray,
+        ]);
+        // A throw here used to strand all four heap pointers plus the pooled
+        // parse buffer, once per faceset (15,777 on PSB — a leak large enough
+        // to cause the exhaustion it would then be blamed on). withRelease
+        // reclaims them; it suppresses a release failure only while something
+        // is already unwinding, so a wasm-runtime fault is not replaced by a
+        // generic teardown error in the per-record catch upstream.
+        const geometry = withRelease(() => {
+            const pointsParseBuffer = this.conwayModel.nativeParseBuffer();
+            // Packed triangulation: the four heap buffers are already the
+            // face index layout. Unpacking them into 9.1M IndexedPolygonalFace
+            // std::vectors was the rest of the PSB pump after #448, and is
+            // why feeding the ThreadPool lost (the pool was paying to copy
+            // those vectors).
+            const pointsArrayNative = withRelease(() => {
+                if (!entity.Coordinates.extractParseBuffer(0, 0, 0, pointsParseBuffer, this.wasmModule, true)) {
+                    pointsParseBuffer.resize(0);
+                }
+                return this.wasmModule.parseVertexVector(pointsParseBuffer);
+            }, () => this.conwayModel.freeParseBuffer(pointsParseBuffer));
+            return withRelease(() => this.conwayModel.getPolygonalFaceSetGeometryPacked(pointsArrayNative, indicesArrayPtr, polygonalFaceBufferOffsetsArrayPtr, polygonalFaceBufferOffsetsArray.length, startIndicesArrayPtr, startIndicesBufferOffsetsArrayPtr), () => pointsArrayNative.delete());
+        }, 
+        // freeAll, not four statements in one closure: there the first
+        // failure would abandon the other three.
+        () => freeAll(this.wasmModule, [
+            indicesArrayPtr,
+            startIndicesArrayPtr,
+            polygonalFaceBufferOffsetsArrayPtr,
+            startIndicesBufferOffsetsArrayPtr,
+        ]));
+        const canonicalMesh = {
+            type: CanonicalMeshType.BUFFER_GEOMETRY,
+            geometry: geometry,
+            localID: entity.localID,
+            model: this.model,
+            temporary: temporary,
+        };
+        if (!isRelVoid) {
+            this.model.geometry.add(canonicalMesh);
+        }
+        else {
+            this.model.voidGeometry.add(canonicalMesh);
+        }
+        return ExtractResult.COMPLETE;
+    }
+    /**
+     * Extract a polygonal faceset.
+     *
+     * The index sinks are extractor-scoped, so a nested faceset extraction
+     * reached from inside this one would silently clobber them. Nothing
+     * recurses there today, so this guards the invariant rather than a
+     * live bug — but the release must survive a throw: per-record
+     * extraction errors are caught upstream and are expected on malformed
+     * models, and a leaked flag would turn one bad record into a failure
+     * for every remaining faceset.
+     *
+     * @param entity The faceset.
+     * @param temporary Is this a temporary (preview/operand) extraction?
+     * @param isRelVoid Is this geometry a rel-void operand?
+     * @return {ExtractResult} The extraction result.
+     */
+    extractPolygonalFaceSet(entity, temporary = false, isRelVoid = false) {
+        if (this.polygonalSinksInUse_) {
+            throw new Error("extractPolygonalFaceSet re-entered: the shared index sinks are already in use");
+        }
+        this.polygonalSinksInUse_ = true;
+        try {
+            return this.extractPolygonalFaceSetGuarded_(entity, temporary, isRelVoid);
+        }
+        finally {
+            this.polygonalSinksInUse_ = false;
+        }
+    }
     /**
      * @param entity
      * @param temporary
      * @param isRelVoid
      * @return {ExtractResult}
      */
-    extractPolygonalFaceSet(entity, temporary = false, isRelVoid = false) {
+    extractPolygonalFaceSetGuarded_(entity, temporary, isRelVoid) {
         const result = ExtractResult.COMPLETE;
-        // Temporary storage for indices and start indices
-        const allIndices = [];
-        const allStartIndices = [];
-        const polygonalFaceBufferOffsets = [];
-        const startIndicesBufferOffsets = [];
-        let indicesPerFace = -1;
+        // Reusable typed sinks. A tessellated model can carry millions of
+        // IfcIndexedPolygonalFace records, and the boxed `Array< number >`
+        // this loop used to build per face — which the generated CoordIndex
+        // getter also cached on the face, keeping it alive — dominated both
+        // GC time and retained heap during extraction. Indices are parsed
+        // straight from the STEP buffer into these instead, reused across
+        // facesets.
+        const allIndices = this.polygonalIndexSink_;
+        const allStartIndices = this.polygonalStartIndexSink_;
+        const polygonalFaceBufferOffsets = this.polygonalFaceOffsetSink_;
+        const startIndicesBufferOffsets = this.polygonalStartOffsetSink_;
+        allIndices.reset();
+        allStartIndices.reset();
+        polygonalFaceBufferOffsets.reset();
+        startIndicesBufferOffsets.reset();
+        // Fast path: read each face's CoordIndex straight from its record,
+        // never constructing the 9M+ IfcIndexedPolygonalFace entities a
+        // large tessellated model would otherwise materialise (and retain,
+        // since the generated Faces getter caches them). It handles only
+        // plain, single-class IFCINDEXEDPOLYGONALFACE records; anything
+        // else (voided faces, inline elements, multi-mapped records)
+        // abandons the whole faceset back to the getter path below, so
+        // correctness never depends on the fast path's coverage.
+        let fastPathOk = true;
+        let hintLocalID;
+        const facesWalked = entity.forEachReferenceInField(FACES_FIELD_OFFSET, FACES_FIELD_BASE_OFFSET, FACES_FIELD_DEPTH, (expressID) => {
+            if (expressID === void 0) {
+                fastPathOk = false;
+                return false;
+            }
+            const localID = this.model.resolveExpressID(expressID, hintLocalID);
+            if (localID === void 0) {
+                fastPathOk = false;
+                return false;
+            }
+            const count = this.model.extractIntegerArrayByLocalIDInto(localID, COORD_INDEX_FIELD_OFFSET, EntityTypesIfc.IFCINDEXEDPOLYGONALFACE, allIndices);
+            if (count === void 0) {
+                fastPathOk = false;
+                return false;
+            }
+            hintLocalID = localID;
+            polygonalFaceBufferOffsets.push(allIndices.length - count);
+            startIndicesBufferOffsets.push(allStartIndices.length);
+            allStartIndices.push(0);
+            return true;
+        });
+        if (fastPathOk && facesWalked) {
+            this.finishPolygonalFaceSet_(entity, temporary, isRelVoid, allIndices, allStartIndices, polygonalFaceBufferOffsets, startIndicesBufferOffsets);
+            return result;
+        }
+        // Fallback: something in this faceset needs the generated getters.
+        allIndices.reset();
+        allStartIndices.reset();
+        polygonalFaceBufferOffsets.reset();
+        startIndicesBufferOffsets.reset();
         // Prepare indices and start indices for all faces
         entity.Faces.forEach((polygonalFace) => {
             // set the offets for the memory buffers so we can rebuild the
@@ -545,68 +752,29 @@ export class IfcGeometryExtraction {
             startIndicesBufferOffsets.push(allStartIndices.length);
             let coordIndex = 0;
             if (polygonalFace instanceof IfcIndexedPolygonalFaceWithVoids) {
-                indicesPerFace = polygonalFace.CoordIndex.length;
+                // Voided faces are rare; keep the straightforward getter path.
+                const indicesPerFace = polygonalFace.CoordIndex.length;
                 allStartIndices.push(0);
                 coordIndex += indicesPerFace;
-                allIndices.push(...polygonalFace.CoordIndex);
+                for (const index of polygonalFace.CoordIndex) {
+                    allIndices.push(index);
+                }
                 polygonalFace.InnerCoordIndices.forEach((innerIndices) => {
                     allStartIndices.push(coordIndex);
-                    allIndices.push(...innerIndices);
+                    for (const index of innerIndices) {
+                        allIndices.push(index);
+                    }
                     coordIndex += innerIndices.length;
                 });
             }
             else {
-                indicesPerFace = polygonalFace.CoordIndex.length;
+                // CoordIndex is vtable offset 0 on IfcIndexedPolygonalFace (see
+                // its generated getter) — parsed in place, never allocated or cached.
+                polygonalFace.extractIntegerArrayInto(0, 0, 3, allIndices);
                 allStartIndices.push(0);
-                allIndices.push(...polygonalFace.CoordIndex);
             }
         });
-        // Add the final entry
-        polygonalFaceBufferOffsets.push(allIndices.length);
-        startIndicesBufferOffsets.push(allStartIndices.length);
-        // Convert to typed arrays for transfer to WebAssembly
-        const indicesArray = new Uint32Array(allIndices);
-        const indicesArrayPtr = this.arrayToWasmHeap(indicesArray);
-        const startIndicesArray = new Uint32Array(allStartIndices);
-        const startIndicesArrayPtr = this.arrayToWasmHeap(startIndicesArray);
-        const polygonalFaceBufferOffsetsArray = new Uint32Array(polygonalFaceBufferOffsets);
-        const polygonalFaceBufferOffsetsArrayPtr = this.arrayToWasmHeap(polygonalFaceBufferOffsetsArray);
-        const startIndicesBufferOffsetsArray = new Uint32Array(startIndicesBufferOffsets);
-        const startIndicesBufferOffsetsArrayPtr = this.arrayToWasmHeap(startIndicesBufferOffsetsArray);
-        const polygonalFaceVector = this.wasmModule.buildIndexedPolygonalFaceVector(indicesArrayPtr, indicesArray.length, startIndicesArrayPtr, polygonalFaceBufferOffsetsArrayPtr, polygonalFaceBufferOffsets.length, startIndicesBufferOffsetsArrayPtr, startIndicesBufferOffsets.length);
-        const pointsParseBuffer = this.conwayModel.nativeParseBuffer();
-        if (!entity.Coordinates.extractParseBuffer(0, 0, 0, pointsParseBuffer, this.wasmModule, true)) {
-            pointsParseBuffer.resize(0);
-        }
-        const pointsArrayNative = this.wasmModule.parseVertexVector(pointsParseBuffer);
-        this.conwayModel.freeParseBuffer(pointsParseBuffer);
-        const parameters = {
-            indicesPerFace: indicesPerFace,
-            points: pointsArrayNative,
-            faces: polygonalFaceVector,
-        };
-        const geometry = this.conwayModel.getPolygonalFaceSetGeometry(parameters);
-        // free allocated wasm vectors
-        pointsArrayNative.delete();
-        this.wasmModule._free(indicesArrayPtr);
-        this.wasmModule._free(startIndicesArrayPtr);
-        this.wasmModule._free(polygonalFaceBufferOffsetsArrayPtr);
-        this.wasmModule._free(startIndicesBufferOffsetsArrayPtr);
-        polygonalFaceVector.delete();
-        const canonicalMesh = {
-            type: CanonicalMeshType.BUFFER_GEOMETRY,
-            geometry: geometry,
-            localID: entity.localID,
-            model: this.model,
-            temporary: temporary,
-        };
-        // add mesh to the list of mesh objects
-        if (!isRelVoid) {
-            this.model.geometry.add(canonicalMesh);
-        }
-        else {
-            this.model.voidGeometry.add(canonicalMesh);
-        }
+        this.finishPolygonalFaceSet_(entity, temporary, isRelVoid, allIndices, allStartIndices, polygonalFaceBufferOffsets, startIndicesBufferOffsets);
         return result;
     }
     /**
@@ -614,14 +782,7 @@ export class IfcGeometryExtraction {
      * @return {number} Pointer/memory address
      */
     arrayToWasmHeap(array) {
-        // Allocate memory for the array within the Wasm module
-        const bytesPerElement = array.BYTES_PER_ELEMENT;
-        const numBytes = array.length * bytesPerElement;
-        const arrayPtr = this.wasmModule._malloc(numBytes);
-        // Create a new Uint8Array view on the Wasm memory buffer, then set the array to it
-        const arrayWasm = new Uint8Array(this.wasmModule.HEAPU8.buffer, arrayPtr, numBytes);
-        arrayWasm.set(new Uint8Array(array.buffer));
-        return arrayPtr;
+        return arrayToWasmHeap(this.wasmModule, array);
     }
     /**
      * @param array
@@ -2646,9 +2807,13 @@ export class IfcGeometryExtraction {
             pointer = this.wasmModule._malloc(numBytes);
             capacity = maxPossibleFloats;
         }
-        // 2) Create a Float64Array view into WASM memory
-        // We only need to create a subarray up to the capacity
-        const wasmFloat64View = this.wasmModule.HEAPF64.subarray(pointer / bytesPerElement, pointer / bytesPerElement + capacity);
+        // 2) Create a Float64Array view into WASM memory, over the heap as it is
+        // after the _malloc above rather than over whatever view the module had
+        // cached before it - see wasm_heap.ts for why those can differ. Built
+        // rather than subarray'd off HEAPF64 for the same reason: subarray clamps
+        // an out-of-range window into a short one, and the set() loop below would
+        // then quietly write somewhere other than the allocation (#485).
+        const wasmFloat64View = wasmHeapView(this.wasmModule, Float64Array, pointer, capacity);
         // 3) Single pass to skip consecutive duplicates, fill up the wasm array
         let offset = 0;
         let prevLocalID = -1;
@@ -3893,6 +4058,341 @@ export class IfcGeometryExtraction {
             .getAxis2Placement3D(axis2Placement3DParameters);
         this.voidScene.addTransform(parentLocalId, axis2PlacementTransform.getValues(), axis2PlacementTransform);
     }
+    /**
+     * Resolve and extract a product's placement with dangling references
+     * treated as errors (deferDanglingPlacements mode).
+     *
+     * The model's `nullOnErrors` (default true) turns a reference to an
+     * unindexed record into a silent null, which is indistinguishable from
+     * a genuinely absent (`$`) optional attribute. On a mid-parse prefix
+     * that conflation is exactly wrong: "placement record not indexed
+     * yet" must defer the product, while "product has no placement" may
+     * extract unplaced, matching the classic path. Flipping
+     * `nullOnErrors` off for the duration makes the step layer throw on
+     * the dangling read (`extractElement`), anywhere in the chain —
+     * IFCLOCALPLACEMENT ancestors and their axis/point records included,
+     * since `extractPlacement` resolves them through the same layer.
+     *
+     * The throw intentionally propagates: the demand seam
+     * (`extractProductGeometryByLocalID` callers, the preview adapter's
+     * per-unit catch) already treats a throwing product as
+     * not-yet-extractable and leaves it to the durable pump — the IFC
+     * channel's forward-only unit cursor does not re-run passed
+     * ordinals. Nothing is memoized on the throwing path — the generated
+     * getters only cache on successful extraction — so an adapter mode
+     * that does retry (AP214's retryEmptyUnits, or a future IFC
+     * equivalent) re-reads cleanly against its longer prefix.
+     *
+     * @param product The product whose placement to resolve.
+     */
+    extractPlacementStrict_(product) {
+        const model = this.model;
+        const priorNullOnErrors = model.nullOnErrors;
+        model.nullOnErrors = false;
+        try {
+            const objectPlacement = product.ObjectPlacement;
+            if (objectPlacement !== null) {
+                this.extractPlacement(objectPlacement);
+            }
+        }
+        finally {
+            model.nullOnErrors = priorNullOnErrors;
+        }
+    }
+    /**
+     * Reduce a grid axis to an unbounded line in the plane of the grid's
+     * placement: a point on it, and its tangent there.
+     *
+     * Only the straight axis curves are handled — an IfcLine, or the single
+     * segment of a two-point IfcPolyline — which is what grid axes are in
+     * practice. Anything else returns undefined after warning, so the
+     * placement lands in errors.csv rather than being dropped in silence.
+     *
+     * `SameSense` is folded into the tangent because everything downstream is
+     * measured from it: the offset in IfcVirtualGridIntersection is normal to
+     * the tangent, and the tangent is also an IfcGridPlacement's default
+     * x-axis, so a reversed axis offsets to the other side and points the
+     * other way.
+     *
+     * @param axis The grid axis to reduce.
+     * @return {{x, y, dx, dy} | undefined} A point and (unnormalised) tangent
+     * in the grid's coordinate system, or undefined for an axis curve this
+     * does not handle.
+     */
+    static gridAxisLine(axis) {
+        const curve = axis.AxisCurve;
+        let x;
+        let y;
+        let dx;
+        let dy;
+        if (curve instanceof IfcPolyline) {
+            const points = curve.Points;
+            if (points.length !== 2) {
+                // A multi-segment axis needs the segment nearest the intersection
+                // picked per axis pair, which this does not do.
+                Logger.warning("IfcGridPlacement: grid axis IfcPolyline is not a single segment.", axis.expressID);
+                return void 0;
+            }
+            const start = points[0].Coordinates;
+            const end = points[1].Coordinates;
+            x = start[0];
+            y = start[1];
+            dx = end[0] - start[0];
+            dy = end[1] - start[1];
+        }
+        else if (curve instanceof IfcLine) {
+            const origin = curve.Pnt.Coordinates;
+            const direction = curve.Dir.Orientation.DirectionRatios;
+            // IfcVector.Magnitude scales the direction; the axis is unbounded
+            // here, so it changes neither the line nor the normalised tangent.
+            x = origin[0];
+            y = origin[1];
+            dx = direction[0];
+            dy = direction[1];
+        }
+        else {
+            Logger.warning(`IfcGridPlacement: unsupported grid axis curve, type: ${EntityTypesIfc[curve.type]}`, axis.expressID);
+            return void 0;
+        }
+        if (!axis.SameSense) {
+            dx = -dx;
+            dy = -dy;
+        }
+        return { x: x, y: y, dx: dx, dy: dy };
+    }
+    /**
+     * Resolve an IfcVirtualGridIntersection to a point in the coordinate system
+     * of the IfcGrid that owns its axes, along with the tangent of its first
+     * axis — which is the default x-axis of an IfcGridPlacement located here.
+     *
+     * Per IFC4 each axis is replaced by its offset curve before intersecting:
+     * OffsetDistances[n] is measured from axis n normal to its tangent,
+     * positive towards the tangent turned a quarter turn anti-clockwise. Both
+     * axes here are straight, so their offset curves are parallel to them and
+     * the tangents are unchanged. A third offset, when the file gives one,
+     * displaces the result along the grid placement's z axis.
+     *
+     * @param from The intersection to resolve.
+     * @return {{position, tangent} | undefined} The intersection point and the
+     * first axis' unit tangent, or undefined when the axes cannot be reduced to
+     * two lines that meet (warned at the point of failure).
+     */
+    resolveVirtualGridIntersection(from) {
+        const axes = from.IntersectingAxes;
+        if (axes.length < GRID_INTERSECTION_AXIS_COUNT) {
+            // LIST [2:2] in the schema, so this is a malformed or absent list.
+            Logger.warning("IfcGridPlacement: virtual grid intersection has fewer than two axes.", from.expressID);
+            return void 0;
+        }
+        const line0 = IfcGeometryExtraction.gridAxisLine(axes[0]);
+        const line1 = IfcGeometryExtraction.gridAxisLine(axes[1]);
+        if (line0 === void 0 || line1 === void 0) {
+            return void 0;
+        }
+        const length0 = Math.sqrt(line0.dx * line0.dx + line0.dy * line0.dy);
+        const length1 = Math.sqrt(line1.dx * line1.dx + line1.dy * line1.dy);
+        const cross = line0.dx * line1.dy - line0.dy * line1.dx;
+        // |cross| / (length0 * length1) is the sine of the angle between the
+        // axes, so the test is independent of the model's units. A zero-length
+        // tangent (a polyline whose two points coincide) also lands here,
+        // before it can divide its way into a NaN below.
+        if (Math.abs(cross) <= GRID_AXIS_PARALLEL_EPSILON * length0 * length1) {
+            Logger.warning("IfcGridPlacement: intersecting grid axes are parallel or degenerate.", from.expressID);
+            return void 0;
+        }
+        const offsets = from.OffsetDistances;
+        const offset0 = offsets[0] ?? 0;
+        const offset1 = offsets[1] ?? 0;
+        // Offset curve origins: the axis point pushed along the tangent's
+        // anti-clockwise normal, (-dy, dx) normalised.
+        const x0 = line0.x - (offset0 * line0.dy) / length0;
+        const y0 = line0.y + (offset0 * line0.dx) / length0;
+        const x1 = line1.x - (offset1 * line1.dy) / length1;
+        const y1 = line1.y + (offset1 * line1.dx) / length1;
+        // Parameter along the first offset curve where the two meet, from
+        // crossing (p1 - p0) + t * d0 = s * d1 with d1.
+        const t = ((x1 - x0) * line1.dy - (y1 - y0) * line1.dx) / cross;
+        return {
+            position: {
+                x: x0 + t * line0.dx,
+                y: y0 + t * line0.dy,
+                z: offsets[GRID_INTERSECTION_Z_OFFSET] ?? 0,
+            },
+            tangent: { x: line0.dx / length0, y: line0.dy / length0 },
+        };
+    }
+    /**
+     * The IfcGrid that lists a given axis, or undefined if no grid does.
+     *
+     * IfcGridAxis's route back to its grid is the PartOfU/PartOfV/PartOfW
+     * inverse attributes, and the generated schema layer carries no inverses,
+     * so this is a scan of every IfcGrid's axis lists, memoised. It is built on
+     * the first grid placement extracted and never at all for a model without
+     * one.
+     *
+     * @param axis The axis to look up.
+     * @return {IfcGrid | undefined} The grid listing the axis.
+     */
+    gridByAxis(axis) {
+        let gridByAxis = this.gridByAxis_;
+        if (gridByAxis === void 0) {
+            gridByAxis = new Map();
+            for (const grid of this.model.types(IfcGrid)) {
+                for (const gridAxis of grid.UAxes) {
+                    gridByAxis.set(gridAxis.localID, grid);
+                }
+                for (const gridAxis of grid.VAxes) {
+                    gridByAxis.set(gridAxis.localID, grid);
+                }
+                for (const gridAxis of grid.WAxes ?? []) {
+                    gridByAxis.set(gridAxis.localID, grid);
+                }
+            }
+            this.gridByAxis_ = gridByAxis;
+        }
+        return gridByAxis.get(axis.localID);
+    }
+    /**
+     * Extract an IfcGridPlacement, registering a transform against its local ID
+     * the same way the IfcLocalPlacement arm does — same scene, same
+     * memoisation, same composition onto the current parent.
+     *
+     * The origin is the virtual intersection of two grid axes and the x-axis
+     * comes from PlacementRefDirection (defaulting to the first axis' tangent),
+     * both expressed in the coordinate system of the IfcGrid that owns the
+     * axes. IfcGridPlacement has no PlacementRelTo of its own in IFC4, so that
+     * grid's object placement IS the parent: extracting it first leaves it as
+     * the scene's current transform, which `addTransform` then composes onto.
+     *
+     * @param from The grid placement to extract.
+     * @param isRelVoid Whether this placement is being resolved into the void
+     * scene rather than the main one.
+     */
+    extractGridPlacement(from, isRelVoid) {
+        const placementLocation = from.PlacementLocation;
+        const location = this.resolveVirtualGridIntersection(placementLocation);
+        if (location === void 0) {
+            // Warned where it failed, with the axis or curve responsible.
+            return;
+        }
+        let xAxisRef = { x: location.tangent.x, y: location.tangent.y, z: 0 };
+        const refDirection = from.PlacementRefDirection;
+        if (refDirection instanceof IfcDirection) {
+            const ratios = refDirection.DirectionRatios;
+            xAxisRef = { x: ratios[0], y: ratios[1], z: ratios[2] ?? 0 };
+        }
+        else if (refDirection instanceof IfcVirtualGridIntersection) {
+            // The x-axis runs from this placement's intersection to the reference
+            // one. If the reference cannot be resolved the resolver has already
+            // said why, and the schema's own default — the first axis' tangent —
+            // stands in.
+            const reference = this.resolveVirtualGridIntersection(refDirection);
+            if (reference !== void 0) {
+                xAxisRef = {
+                    x: reference.position.x - location.position.x,
+                    y: reference.position.y - location.position.y,
+                    z: reference.position.z - location.position.z,
+                };
+            }
+        }
+        // getAxis2Placement3D below is called with a forced z of (0,0,1) and
+        // normalizeX, and the native side (ConwayGeometryProcessor's
+        // getAxis2Placement3D) has no degeneracy guard of its own: an xAxisRef
+        // with nothing off that z has no component left after the projection,
+        // normalises to NaN, and addTransform then bakes the NaN into this
+        // placement and every descendant of it. Measured on data/grid_placement.ifc
+        // product E, whose x axis came out (NaN,NaN,NaN) before this guard.
+        //
+        // Two schema-reachable states produce it, and because z is exactly +Z both
+        // reduce to one test - the xy magnitude vanishing relative to the vector's
+        // own, in the same units-independent form as the axis-parallel check in
+        // resolveVirtualGridIntersection (a zero vector fails it too, 0 <= 0):
+        //
+        // - PlacementRefDirection is an IfcVirtualGridIntersection resolving to
+        //   the same point as PlacementLocation, so the difference above is the
+        //   zero vector;
+        // - PlacementRefDirection is IFCDIRECTION((0.,0.,1.)), parallel to the
+        //   forced z.
+        //
+        // The fallback is the schema's own default for an absent
+        // PlacementRefDirection, and it is already in hand and already known
+        // non-degenerate: resolveVirtualGridIntersection returns the first axis'
+        // tangent normalised, and only after rejecting a zero-length one.
+        const xAxisRefPlanar = Math.sqrt(xAxisRef.x * xAxisRef.x + xAxisRef.y * xAxisRef.y);
+        const xAxisRefLength = Math.sqrt(xAxisRefPlanar * xAxisRefPlanar + xAxisRef.z * xAxisRef.z);
+        if (xAxisRefPlanar <= GRID_AXIS_PARALLEL_EPSILON * xAxisRefLength) {
+            Logger.warning("IfcGridPlacement: the placement reference direction is parallel " +
+                "to the grid placement's z axis, or has no length - falling back " +
+                "to the schema default, the first axis' tangent.", from.expressID);
+            xAxisRef = { x: location.tangent.x, y: location.tangent.y, z: 0 };
+        }
+        // Two guarded regions rather than one, because the two reads degrade to
+        // DIFFERENT states and a single catch could only describe one of them
+        // truthfully. Neither may fail the product: dropping it entirely is
+        // strictly worse than the pre-implementation rendered-at-origin.
+        //
+        // Region 1 - the gridByAxis scan. It reads IfcGrid records, which are
+        // outside the forward-reference closure a windowed source pages for a
+        // product (the grid references the axes, not vice versa - see
+        // ensureResidentForProductExtract), so this is the read most likely to
+        // miss. Nothing has been applied when it throws, so the intersection
+        // lands in the current frame - the same degraded state the no-grid arm
+        // gives. gridByAxis memoises only a COMPLETE scan, so a later product on
+        // a fully resident model rebuilds rather than trusting a partial index.
+        let grid;
+        let gridScanned = false;
+        try {
+            grid = this.gridByAxis(placementLocation.IntersectingAxes[0]);
+            gridScanned = true;
+        }
+        catch (error) {
+            if (!(error instanceof StepBufferNotResidentError)) {
+                throw error;
+            }
+            Logger.warning("IfcGridPlacement: grid records are not resident on this " +
+                "windowed source - placing at the grid intersection in the " +
+                "current frame, without the grid's own placement.", from.expressID);
+        }
+        if (gridScanned && grid === void 0) {
+            // Axes belonging to no grid: the intersection is still a point, but
+            // there is no grid placement to measure it from, so it lands in
+            // whatever frame is current.
+            Logger.warning("IfcGridPlacement: no IfcGrid lists the axes of this placement.", from.expressID);
+        }
+        else if (grid !== void 0) {
+            // Region 2 - the grid's own placement chain. extractPlacement walks
+            // PlacementRelTo upwards and pushes a transform per level as it
+            // returns, so a residency miss PART WAY UP leaves some ancestors
+            // already applied. Region 1's message would be a lie about this state
+            // (it says the grid's placement was not applied at all), and the frame
+            // this placement then composes onto is partial rather than current.
+            try {
+                const gridPlacement = grid.ObjectPlacement;
+                if (gridPlacement !== null) {
+                    this.extractPlacement(gridPlacement, isRelVoid);
+                }
+            }
+            catch (error) {
+                if (!(error instanceof StepBufferNotResidentError)) {
+                    throw error;
+                }
+                Logger.warning("IfcGridPlacement: the grid's own placement chain is not fully " +
+                    "resident on this windowed source - it was applied as far as it " +
+                    "reads, so this placement composes onto a partial frame.", from.expressID);
+            }
+        }
+        const placementTransform = this.conwayModel.getAxis2Placement3D({
+            position: location.position,
+            // A grid is planar in its own placement, so this placement's z axis is
+            // the grid's z axis; only the x axis is steered here.
+            zAxisRef: { x: 0, y: 0, z: 1 },
+            xAxisRef: xAxisRef,
+            normalizeZ: false,
+            normalizeX: true,
+        });
+        const scene = isRelVoid ? this.voidScene : this.scene;
+        scene.addTransform(from.localID, placementTransform.getValues(), placementTransform);
+    }
     /**
      *
      * @param from
@@ -3931,8 +4431,7 @@ export class IfcGeometryExtraction {
             }
         }
         else if (from instanceof IfcGridPlacement) {
-            // TODO(nickcastel50) Implement IfcGridPlacement
-            // Logger.warning('IfcGridPlacement: unimplemented.')
+            this.extractGridPlacement(from, isRelVoid);
         }
     }
     /**
@@ -4211,14 +4710,53 @@ export class IfcGeometryExtraction {
         }
         return styledItemID;
     }
+    /**
+     * Handle an error raised while building the cross-product extraction
+     * maps. Each map sweep reads references off relationship entities
+     * (materials, styled items, rel-voids); a single malformed reference in
+     * a large real-world model (STEP where an entity reference is expected)
+     * must not abort the whole model's extraction. Both the whole-model walk
+     * and the demand path depend on map prep being tolerant here — the
+     * browser demand pump swallows per-batch extraction throws, so a model
+     * that renders in prod would otherwise hard-fail the headless regression
+     * batch. Honours the strict-mode escape hatch so a strict run still
+     * surfaces the error.
+     *
+     * @param context Short label for the relationship being processed.
+     * @param expressID The offending record's express ID (may be undefined).
+     * @param ex The caught value.
+     */
+    handleMapPrepError_(context, expressID, ex) {
+        if (ex instanceof Error) {
+            if (MATERIAL_RELATED_OBJECTS_PERMISSIVE) {
+                Logger.error(`Error processing ${context} expressID: ${expressID}, error: ${ex.message}`);
+            }
+            else {
+                throw ex;
+            }
+        }
+        else {
+            Logger.error(`Unknown exception processing ${context}.`);
+        }
+    }
     /**
      *
      */
     populateStyledItemsMap() {
         const styledItems = this.model.types(IfcStyledItem);
         for (const styledItem of styledItems) {
-            if (styledItem.Item !== null) {
-                this.materials.styledItemMap.set(styledItem.Item.localID, styledItem.localID);
+            try {
+                // IfcStyledItem.Item — same vtable slot as the generated
+                // getter's extractElement(0, 0, 1, true, ...). Hydrating Item
+                // would acquire the faceset record (often the packed geometry
+                // itself) for every styled item at once.
+                const itemLocalID = styledItem.extractReferenceLocalID(0, 0, 1, true);
+                if (itemLocalID !== null) {
+                    this.materials.styledItemMap.set(itemLocalID, styledItem.localID);
+                }
+            }
+            catch (ex) {
+                this.handleMapPrepError_("IfcStyledItem", styledItem.expressID, ex);
             }
         }
     }
@@ -4229,12 +4767,17 @@ export class IfcGeometryExtraction {
         // populate MaterialDefinitionsMap
         const materialDefinitionRepresentations = this.model.types(IfcMaterialDefinitionRepresentation);
         for (const materialDefinitionRep of materialDefinitionRepresentations) {
-            for (const representation of materialDefinitionRep.Representations) {
-                for (let itemIndex = 0; itemIndex < representation.Items.length; ++itemIndex) {
-                    // save mapping of IfcMaterial --> IfcStyledItem
-                    this.materials.materialDefinitionsMap.set(materialDefinitionRep.RepresentedMaterial.localID, representation.Items[itemIndex].localID);
+            try {
+                for (const representation of materialDefinitionRep.Representations) {
+                    for (let itemIndex = 0; itemIndex < representation.Items.length; ++itemIndex) {
+                        // save mapping of IfcMaterial --> IfcStyledItem
+                        this.materials.materialDefinitionsMap.set(materialDefinitionRep.RepresentedMaterial.localID, representation.Items[itemIndex].localID);
+                    }
                 }
             }
+            catch (ex) {
+                this.handleMapPrepError_("IfcMaterialDefinitionRepresentation", materialDefinitionRep.expressID, ex);
+            }
         }
     }
     /**
@@ -4244,17 +4787,22 @@ export class IfcGeometryExtraction {
         // populate relvoids map
         const relVoids = this.model.types(IfcRelVoidsElement);
         for (const relVoid of relVoids) {
-            // map product --> relvoids opening elements
-            const geometryLocalIDArray = this.productToVoidGeometryMap.get(relVoid.RelatingBuildingElement.localID);
-            if (geometryLocalIDArray === void 0) {
-                const localIDArray = [];
-                localIDArray.push(relVoid.RelatedOpeningElement.localID);
-                this.productToVoidGeometryMap.set(relVoid.RelatingBuildingElement.localID, localIDArray);
+            try {
+                // map product --> relvoids opening elements
+                const geometryLocalIDArray = this.productToVoidGeometryMap.get(relVoid.RelatingBuildingElement.localID);
+                if (geometryLocalIDArray === void 0) {
+                    const localIDArray = [];
+                    localIDArray.push(relVoid.RelatedOpeningElement.localID);
+                    this.productToVoidGeometryMap.set(relVoid.RelatingBuildingElement.localID, localIDArray);
+                }
+                else {
+                    // append to it
+                    geometryLocalIDArray.push(relVoid.RelatedOpeningElement.localID);
+                    this.productToVoidGeometryMap.set(relVoid.RelatingBuildingElement.localID, geometryLocalIDArray);
+                }
             }
-            else {
-                // append to it
-                geometryLocalIDArray.push(relVoid.RelatedOpeningElement.localID);
-                this.productToVoidGeometryMap.set(relVoid.RelatingBuildingElement.localID, geometryLocalIDArray);
+            catch (ex) {
+                this.handleMapPrepError_("IfcRelVoidsElement", relVoid.expressID, ex);
             }
         }
     }
@@ -4364,6 +4912,657 @@ export class IfcGeometryExtraction {
            fs.writeFileSync(outputFilePath, objContent, 'utf8')
         } */
     }
+    /**
+     * Local IDs of every IfcProduct that is a RelatedObject of any
+     * IfcRelAggregates — the exact set the rel-aggregates pass
+     * ({@link extractRelAggregateGeometry}) re-extracts with the relating
+     * object's master rel-voids.
+     *
+     * Both product walks SKIP these in their first pass and extract them
+     * only in the aggregates pass, for two invariants consumers rely on:
+     *   1. one scene instance per placement (the first-pass node plus the
+     *      re-extraction node used to coincide exactly — a duplicate draw
+     *      that z-fights), and
+     *   2. a part's canonical mesh content is never REPLACED after its
+     *      instances were already emitted — incremental consumers copy
+     *      content at delivery time, so a first-pass emission served the
+     *      uncut (or empty) content and the later replacement never
+     *      reached the screen (the ILNA missing-facades class).
+     *
+     * @return {Set<number>} product localIDs deferred to the aggregates
+     * pass; empty for models without IfcRelAggregates.
+     */
+    aggregateTargetLocalIDs() {
+        if (this.aggregateTargetLocalIDs_ !== void 0) {
+            return this.aggregateTargetLocalIDs_;
+        }
+        const targets = new Set();
+        const productTypes = new Set(IfcProduct.query);
+        for (const relAggregate of this.model.types(IfcRelAggregates)) {
+            try {
+                // RelatedObjects as express IDs — do not hydrate every child
+                // product (that paged most of the file during demand prep).
+                relAggregate.forEachReferenceInField(REL_AGGREGATES_RELATED_OFFSET, REL_AGGREGATES_RELATED_BASE, REL_AGGREGATES_RELATED_DEPTH, (expressID) => {
+                    if (expressID === void 0) {
+                        return true;
+                    }
+                    const relatedLocalID = this.model.resolveExpressID(expressID);
+                    if (relatedLocalID === void 0) {
+                        return true;
+                    }
+                    const typeID = this.model.typeIDOf(relatedLocalID);
+                    if (typeID !== void 0 && productTypes.has(typeID)) {
+                        targets.add(relatedLocalID);
+                    }
+                    return true;
+                });
+            }
+            catch {
+                // Malformed relationship rows are tolerated exactly like the
+                // aggregates pass itself tolerates them (permissive catch) —
+                // their targets simply stay in the first-pass walk.
+            }
+        }
+        this.aggregateTargetLocalIDs_ = targets;
+        return targets;
+    }
+    /**
+     * One-time extraction setup shared by the whole-model walk and the
+     * per-product demand path (Phase B2): linear scaling factor and the
+     * cross-product maps (materials, material definitions, rel-voids, styled
+     * items). Idempotent.
+     */
+    prepareExtractionMaps_() {
+        if (this.extractionMapsPrepared_) {
+            return;
+        }
+        this.extractionMapsPrepared_ = true;
+        this.extractLinearScalingFactor();
+        // populate relMaterialsMap
+        const relAssociatesMaterials = this.model.types(IfcRelAssociatesMaterial);
+        const productTypes = new Set(IfcProduct.query);
+        for (const relAssociateMaterial of relAssociatesMaterials) {
+            try {
+                // Read RelatingMaterial INSIDE the guard: a malformed material
+                // reference (e.g. a value where an entity ref is expected) throws
+                // "Value in STEP was incorrectly typed", and pulling this read above
+                // the try let one bad relationship abort the whole model's extraction
+                // instead of being tolerated like every other malformed relationship
+                // here. The rel-aggregates loop below already reads its RelatingObject
+                // inside its own try for exactly this reason.
+                const relatingMaterial = relAssociateMaterial.RelatingMaterial;
+                const materialLocalID = relatingMaterial.localID;
+                relAssociateMaterial.forEachReferenceInField(REL_ASSOCIATES_RELATED_OFFSET, REL_ASSOCIATES_RELATED_BASE, REL_ASSOCIATES_RELATED_DEPTH, (expressID) => {
+                    if (expressID === void 0) {
+                        return true;
+                    }
+                    const productLocalID = this.model.resolveExpressID(expressID);
+                    if (productLocalID === void 0) {
+                        return true;
+                    }
+                    const typeID = this.model.typeIDOf(productLocalID);
+                    if (typeID === EntityTypesIfc.IFCOPENINGELEMENT ||
+                        typeID === EntityTypesIfc.IFCSPACE ||
+                        typeID === EntityTypesIfc.IFCOPENINGSTANDARDCASE) {
+                        return true;
+                    }
+                    if (typeID !== void 0 && productTypes.has(typeID)) {
+                        this.materials.relMaterialsMap.set(productLocalID, materialLocalID);
+                    }
+                    return true;
+                });
+            }
+            catch (ex) {
+                // Reference the relationship record, not RelatingMaterial: the
+                // latter may be exactly what threw and would be undefined here.
+                this.handleMapPrepError_("IfcRelAssociatesMaterial", relAssociateMaterial.expressID, ex);
+            }
+        }
+        // populate MaterialDefinitionsMap
+        this.populateMaterialDefinitionsMap();
+        // populate relvoids map
+        this.populateRelVoidsMap();
+        // populate styled items map
+        this.populateStyledItemsMap();
+    }
+    /**
+     * Prepare for per-product demand extraction (Phase B2) without running the
+     * whole-model walk: populates the shared extraction maps so
+     * {@link extractProductGeometryByLocalID} can extract any single product.
+     * Idempotent; the whole-model walk shares the same preparation.
+     *
+     * @param lightweightPreview Preview-only preparation (parse-time
+     * preview generations): skips the relationship sweeps
+     * (rel-materials, rel-voids) whose entity materialization dominates
+     * preparation cost on large models — extracted products then miss
+     * openings and rel-bound materials, which preview consumers accept
+     * by contract. Styled-item and material-definition maps are kept
+     * (colors), as is the linear scaling factor.
+     */
+    prepareDemandExtraction(lightweightPreview = false) {
+        if (lightweightPreview && !this.extractionMapsPrepared_) {
+            this.extractionMapsPrepared_ = true;
+            this.extractLinearScalingFactor();
+            this.populateMaterialDefinitionsMap();
+            this.populateStyledItemsMap();
+            return;
+        }
+        this.prepareExtractionMaps_();
+    }
+    /**
+     * Extract one product's geometry into the scene by local ID — the demand
+     * path's entry (Phase B2). Requires {@link prepareDemandExtraction} (or a
+     * prior whole-model walk) so the shared maps exist.
+     *
+     * Note: this extracts a single product with its OWN voids. Products that
+     * are targets of IfcRelAggregates whose relating object carries rel-voids
+     * additionally need the whole-model walk's second pass
+     * ({@link extractRelAggregatesGeometry}) — the demand pump runs it once
+     * after the last product batch so pumped extractions converge to the
+     * classic walk exactly.
+     *
+     * @param localID The product's local ID.
+     * @return {boolean} True if the local ID was an IfcProduct and was
+     * extracted; false if it wasn't a product.
+     */
+    extractProductGeometryByLocalID(localID) {
+        this.prepareExtractionMaps_();
+        const element = this.model.getElementByLocalID(localID);
+        if (!(element instanceof IfcProduct)) {
+            return false;
+        }
+        this.extractProductGeometry(element);
+        return true;
+    }
+    /**
+     * Page in every record {@link prepareDemandExtraction} will read, so
+     * the relationship sweeps succeed on a windowed source. Call before
+     * the first prepare on a model whose source is external.
+     *
+     * Pins the prep-type records themselves (and a 1-hop of product /
+     * material records the relationship getters hydrate). Does **not**
+     * BFS-pin styled-item Item closures — those are facesets, and
+     * walking them here pulled most of the file into the windowed LRU
+     * before the first product extract.
+     *
+     * @return {Promise<Set<number>>} Pinned local IDs — caller must
+     * {@link StepModelBase.unpinLocalIDs} after prepare/extract.
+     */
+    async ensureResidentForDemandPrep() {
+        const pinned = new Set();
+        if (!this.model.isSourceExternal) {
+            return pinned;
+        }
+        // Small trees: project units, material-definition style stacks.
+        for (const type of [IfcProject, IfcMaterialDefinitionRepresentation]) {
+            for (const expressID of this.model.expressIDsOfTypes(type)) {
+                await this.model.ensureResidentClosureByExpressID(expressID, void 0, pinned);
+            }
+        }
+        const recordOnlyTypes = [
+            IfcRelAssociatesMaterial,
+            IfcRelVoidsElement,
+            IfcStyledItem,
+            IfcRelAggregates,
+        ];
+        for (const type of recordOnlyTypes) {
+            for (const expressID of this.model.expressIDsOfTypes(type)) {
+                const localID = this.model.resolveExpressID(expressID);
+                if (localID === void 0 || pinned.has(localID)) {
+                    continue;
+                }
+                await this.model.ensureResidentByLocalID(localID);
+                this.model.pinByLocalID(localID);
+                pinned.add(localID);
+            }
+        }
+        // Relationship getters hydrate the related product / material
+        // records (not their geometry). Pin that 1-hop so populate can
+        // read `.localID` without a full closure walk.
+        const oneHopTypes = [
+            IfcRelAssociatesMaterial,
+            IfcRelVoidsElement,
+        ];
+        for (const type of oneHopTypes) {
+            for (const expressID of this.model.expressIDsOfTypes(type)) {
+                const localID = this.model.resolveExpressID(expressID);
+                if (localID === void 0) {
+                    continue;
+                }
+                for (const refExpressID of this.model.referencedExpressIDs(localID)) {
+                    const refLocalID = this.model.resolveExpressID(refExpressID);
+                    if (refLocalID === void 0 || pinned.has(refLocalID)) {
+                        continue;
+                    }
+                    await this.model.ensureResidentByLocalID(refLocalID);
+                    this.model.pinByLocalID(refLocalID);
+                    pinned.add(refLocalID);
+                }
+            }
+        }
+        return pinned;
+    }
+    /**
+     * Page in the `#ref` closure a per-product extract will acquire,
+     * including this product's voids, bound materials and styled items
+     * (those are inverse — not written in the product record).
+     *
+     * @param localID The product's local ID.
+     * @param seen Optional set to extend.
+     * @param leafSpans Coalesced Faces[] pin ranges — caller unpins.
+     * @return {Promise<Set<number>>} Pinned local IDs — caller must unpin
+     * after extract.
+     */
+    async ensureResidentForProductExtract(localID, seen, leafSpans) {
+        if (!this.model.isSourceExternal) {
+            return seen ?? new Set();
+        }
+        // Paging failures are contained to their product (conway#526).
+        // `extractGeometryBatchAsync` prefetches a batch through one
+        // Promise.all, so a rejection here used to escape the pump and
+        // abort the entire load — a whole model lost to one unreadable
+        // product. The extract that follows already tolerates a product it
+        // cannot read (its own per-product catch logs and moves on), so
+        // degrading to "this product is missing" is both the smaller
+        // failure and the one the pipeline is already built for.
+        //
+        // Deliberately no retry: a second attempt sharing `seen` would
+        // re-claim nothing and re-ensure nothing, and giving it a fresh set
+        // would double-pin every record it re-walked — pins are refcounted
+        // but the caller unpins once per unique ID, so the surplus would
+        // hold those chunks resident for the model's life and grow the
+        // window without bound.
+        try {
+            return await this.ensureResidentForProductExtractUnguarded_(localID, seen, leafSpans);
+        }
+        catch (error) {
+            Logger.error(`Error paging product localID ${localID} for extract: ` +
+                `${error instanceof Error ? error.message : String(error)}`);
+            return seen ?? new Set();
+        }
+    }
+    /**
+     * {@link ensureResidentForProductExtract} without the per-product
+     * fault containment — split out so the guard cannot accidentally
+     * swallow a failure raised by its own bookkeeping.
+     *
+     * @param localID The product's local ID.
+     * @param seen Optional set to extend.
+     * @param leafSpans Coalesced Faces[] pin ranges — caller unpins.
+     * @return {Promise<Set<number>>} Pinned local IDs.
+     */
+    async ensureResidentForProductExtractUnguarded_(localID, seen, leafSpans) {
+        const extra = [];
+        const voids = this.productToVoidGeometryMap.get(localID);
+        if (voids !== void 0) {
+            extra.push(...voids);
+        }
+        const material = this.materials.relMaterialsMap.get(localID);
+        if (material !== void 0) {
+            extra.push(material);
+        }
+        // Facesets are visited but not scanned (Faces[] is a later span).
+        // Face records are spanned, not visited — 78k pins / 15s otherwise.
+        const isFace = (id) => {
+            const typeID = this.model.typeIDOf(id);
+            return typeID === EntityTypesIfc.IFCINDEXEDPOLYGONALFACE ||
+                typeID === EntityTypesIfc.IFCINDEXEDPOLYGONALFACEWITHVOIDS;
+        };
+        const descend = (id) => {
+            const typeID = this.model.typeIDOf(id);
+            return !isFace(id) &&
+                typeID !== EntityTypesIfc.IFCPOLYGONALFACESET &&
+                typeID !== EntityTypesIfc.IFCTRIANGULATEDFACESET;
+        };
+        // IDs THIS call claimed and awaited, as opposed to `visited`, which
+        // is the caller's shared set when a batch prefetches concurrently.
+        // Only the former may be read synchronously afterwards (conway#526).
+        const claimed = new Set();
+        const visited = await this.model.ensureResidentClosureByLocalID(localID, extra, seen, descend, leafSpans, isFace, claimed);
+        const styleExtra = [];
+        for (const visitedID of visited) {
+            const styled = this.materials.styledItemMap.get(visitedID);
+            if (styled !== void 0) {
+                styleExtra.push(styled);
+            }
+            const definition = this.materials.materialDefinitionsMap.get(visitedID);
+            if (definition !== void 0) {
+                styleExtra.push(definition);
+            }
+        }
+        if (styleExtra.length > 0) {
+            await this.model.ensureResidentClosureByLocalID(localID, styleExtra, visited, descend, leafSpans, isFace, claimed);
+        }
+        await this.ensureResidentVisitedFacesetPayloads_(claimed, visited, leafSpans);
+        return visited;
+    }
+    /**
+     * Page a faceset's Coordinates record and its Faces[] run as one
+     * or more tight address spans. The generic closure visits the
+     * faceset but does not scan Faces[].
+     *
+     * **Iterates `claimed`, not `visited`, and re-ensures before the
+     * scan** — both halves of conway#526. `referencedExpressIDs` is a
+     * SYNCHRONOUS acquire of the faceset's own bytes, and when a batch
+     * prefetches products concurrently through one shared `visited` set
+     * (`extractGeometryBatchAsync`'s Promise.all over 8 products), the
+     * closure walk skips any ID a sibling product already claimed. That
+     * sibling has pinned the range but its read may still be in flight,
+     * so scanning the shared set threw
+     * `StepBufferNotResidentError: STEP source range [...] is not
+     * resident` out of the prefetch and killed the whole load — a pin
+     * reserves a chunk against eviction, it does not make it resident.
+     * Iterating this call's own claims fixes that (and drops the
+     * quadratic re-scan of every sibling's facesets); the `await` below
+     * makes the guarantee local rather than inherited, since a resident
+     * chunk costs only a microtask there.
+     *
+     * @param claimed Faceset local IDs this call claimed and awaited.
+     * @param visited The (possibly shared) visited set — read for
+     * Coordinates de-duplication and extended with the ones pinned here,
+     * so the caller's unpin covers them.
+     * @param leafSpans Coalesced Faces[] pin ranges — caller unpins.
+     */
+    async ensureResidentVisitedFacesetPayloads_(claimed, visited, leafSpans) {
+        for (const localID of claimed) {
+            const typeID = this.model.typeIDOf(localID);
+            if (typeID !== EntityTypesIfc.IFCPOLYGONALFACESET &&
+                typeID !== EntityTypesIfc.IFCTRIANGULATEDFACESET) {
+                continue;
+            }
+            // Cheap when already resident (a Map hit and a microtask), and
+            // the difference between a guarantee and an assumption when the
+            // window has churned since this record was claimed.
+            await this.model.ensureResidentByLocalID(localID);
+            const refs = this.model.referencedExpressIDs(localID);
+            if (refs.length === 0) {
+                continue;
+            }
+            // First #ref is Coordinates (IfcTessellatedFaceSet). Pin it as a
+            // normal record — one IfcCartesianPointList3D, no child #refs.
+            const coordsLocalID = this.model.resolveExpressID(refs[0]);
+            if (coordsLocalID !== void 0 && !visited.has(coordsLocalID)) {
+                visited.add(coordsLocalID);
+                this.model.pinByLocalID(coordsLocalID);
+                await this.model.ensureResidentByLocalID(coordsLocalID);
+            }
+            if (refs.length < 2) {
+                continue;
+            }
+            const spans = this.model.spansOfExpressIDs(refs, 1);
+            for (const span of spans) {
+                this.model.pinAddressRange(span.address, span.length);
+                leafSpans?.push(span);
+                await this.model.ensureResidentRange(span.address, span.length);
+            }
+        }
+    }
+    /**
+     * Page in the records {@link extractRelAggregateGeometry} will
+     * acquire: the relationship, the relating product (and its voids)
+     * and every related product.
+     *
+     * @param relAggregate The relationship to prefetch.
+     * @return {Promise<Set<number>>} Pinned local IDs — caller must unpin
+     * after extract.
+     */
+    async ensureResidentForAggregateExtract(relAggregate, leafSpans) {
+        if (!this.model.isSourceExternal) {
+            return new Set();
+        }
+        // Pin the rel record, page its 1-hop so RelatingObject /
+        // RelatedObjects getters can hydrate, then walk each product
+        // through the bounded extract. The 1-hop IDs must NOT go into
+        // `pinned`/`seen` — that would skip their geometry closures.
+        // A full BFS of the rel used to follow every RelatedObject into
+        // Faces[] (the 78k-pin path) before descend could skip them.
+        const pinned = new Set();
+        const hop = [];
+        this.model.pinByLocalID(relAggregate.localID);
+        pinned.add(relAggregate.localID);
+        try {
+            await this.model.ensureResidentByLocalID(relAggregate.localID);
+            for (const expressID of this.model.referencedExpressIDs(relAggregate.localID)) {
+                const localID = this.model.resolveExpressID(expressID);
+                if (localID === void 0 || pinned.has(localID)) {
+                    continue;
+                }
+                this.model.pinByLocalID(localID);
+                hop.push(localID);
+                await this.model.ensureResidentByLocalID(localID);
+            }
+            const relating = relAggregate.RelatingObject;
+            if (relating !== null && relating !== void 0) {
+                await this.ensureResidentForProductExtract(relating.localID, pinned, leafSpans);
+            }
+            const related = relAggregate.RelatedObjects;
+            if (related !== null && related !== void 0) {
+                for (const product of related) {
+                    await this.ensureResidentForProductExtract(product.localID, pinned, leafSpans);
+                }
+            }
+            return pinned;
+        }
+        finally {
+            for (const localID of hop) {
+                this.model.unpinByLocalID(localID);
+            }
+        }
+    }
+    /**
+     * The whole-model walk's SECOND product pass, shared with the demand
+     * pump: for every IfcRelAggregates, re-extract the related products
+     * with the relating object's rel-voids as a master override. This
+     * re-extraction REPLACES the canonical mesh cached under each
+     * representation item's localID (the scene resolves geometry by
+     * localID at walk time), so aggregate parts whose parent carries
+     * openings end up CUT — a demand pump that only ran the per-product
+     * pass would leave them uncut and serve different GetGeometry content
+     * than the classic walk (the vyzn romana/DOWA scatter). Call exactly
+     * once, after every product has been extracted.
+     */
+    extractRelAggregatesGeometry() {
+        const relAggregates = this.model.types(IfcRelAggregates);
+        for (const relAggregate of relAggregates) {
+            this.extractRelAggregateGeometry(relAggregate);
+        }
+    }
+    /**
+     * Extract one IfcRelAggregates' related products with the relating
+     * object's ("master") rel-voids — the shared per-item body of the
+     * whole-model walk's rel-aggregates loop and
+     * {@link extractRelAggregatesGeometry}. Public so the deferred pump
+     * can run the pass incrementally (batch-budgeted) instead of as one
+     * end-of-load stall.
+     *
+     * @param relAggregate The rel-aggregates relationship to process.
+     */
+    extractRelAggregateGeometry(relAggregate) {
+        try {
+            // Note, this is required because the relating object
+            // can be where the rel-void is applied, so we
+            // used this as a top level over-ride for a rel-void.
+            // for all objects in the aggregate - CS
+            const relatingObject = relAggregate.RelatingObject;
+            const masterRelVoids = relatingObject instanceof IfcProduct ?
+                this.extractRelVoids(relatingObject) :
+                void 0;
+            const relatedObjects = relAggregate.RelatedObjects;
+            for (const productRepresentation of relatedObjects) {
+                if (productRepresentation instanceof IfcProduct) {
+                    this.extractProductGeometry(productRepresentation, masterRelVoids);
+                }
+            }
+            if (masterRelVoids !== void 0) {
+                masterRelVoids[0].delete();
+            }
+        }
+        catch (ex) {
+            if (ex instanceof Error) {
+                if (MATERIAL_RELATED_OBJECTS_PERMISSIVE) {
+                    Logger.error(`Error processing relAggregate\n\terror: ${ex.message}`, relAggregate.expressID);
+                }
+                else {
+                    throw ex;
+                }
+            }
+            else {
+                Logger.error("Unknown exception processing IfcRelAssociateMaterials.");
+            }
+        }
+    }
+    /**
+     * Extract one product's geometry into the scene: placement, material /
+     * style extraction, representation items (including mapped items) and
+     * rel-void application. The deduplicated body of the whole-model walk's
+     * two product loops (plain products + rel-aggregates), shared with the
+     * per-product demand path.
+     *
+     * @param product The product to extract.
+     * @param precomputedRelVoids Optional caller-owned rel-voids (the
+     * rel-aggregates "master" case): when supplied the caller retains
+     * ownership and this method does not delete the mesh vector; when
+     * omitted, voids are extracted per product and freed here.
+     */
+    extractProductGeometry(product, precomputedRelVoids) {
+        this.scene.clearParentStack();
+        const isSpace = product instanceof IfcOpeningElement ||
+            product instanceof IfcSpace ||
+            product instanceof IfcOpeningStandardCase;
+        if (this.deferDanglingPlacements) {
+            // Strict placement resolution for prefix extractions: dangling
+            // references throw here (see extractPlacementStrict_) and the
+            // demand seam reports the product as not-yet-extractable —
+            // instead of extracting the product unplaced. The IFC preview
+            // channel's forward-only cursor does not re-run a passed unit, so
+            // a deferred product simply never previews and the durable pump
+            // renders it; that is the existing contract for every product
+            // whose extraction throws on an unparsed forward reference, and
+            // an empty slot beats geometry at the wrong placement. This read
+            // must be the entity's FIRST ObjectPlacement access: the
+            // generated getters memoize, and a lenient read would cache null
+            // for a dangling reference.
+            this.extractPlacementStrict_(product);
+        }
+        else {
+            const objectPlacement = product.ObjectPlacement;
+            if (objectPlacement !== null) {
+                this.extractPlacement(objectPlacement);
+            }
+        }
+        const representations = product.Representation;
+        if (representations === null) {
+            return;
+        }
+        // extract styledItem material
+        const styledItemID = this.extractMaterialStyle(product);
+        let hasRelVoid = false;
+        const extractRelVoidsResult = precomputedRelVoids ?? this.extractRelVoids(product);
+        let relVoidsMeshVector;
+        let relVoidLocalIDs;
+        if (extractRelVoidsResult !== void 0) {
+            [relVoidsMeshVector, relVoidLocalIDs] = extractRelVoidsResult;
+        }
+        if (relVoidsMeshVector !== void 0) {
+            hasRelVoid = true;
+        }
+        if (styledItemID !== void 0) {
+            // optimization: extract the first representation item and cache
+            // the styleID to apply to the rest of the product geometry
+            const styledItem = this.model.getElementByLocalID(styledItemID);
+            let reusableStyleID;
+            for (const representation of representations.Representations) {
+                if (representation instanceof IfcShapeRepresentation) {
+                    // this check is essential -
+                    // if RepresentationIdentifier !== Body or Facetation we must skip it
+                    if (representation.RepresentationIdentifier !== "Body" &&
+                        representation.RepresentationIdentifier !== "Facetation") {
+                        continue;
+                    }
+                }
+                for (const item of representation.Items) {
+                    if (item instanceof IfcMappedItem) {
+                        this.extractMappedItem(item, product, hasRelVoid, isSpace);
+                    }
+                    else {
+                        try {
+                            this.extractRepresentationItem(item, product.localID, hasRelVoid, isSpace);
+                            if (hasRelVoid) {
+                                this.applyRelVoidToRepresentation(item, relVoidsMeshVector, product.localID, relVoidLocalIDs, void 0, isSpace);
+                            }
+                        }
+                        catch (error) {
+                            if (this.quietRecoverableLogging) {
+                                // Preview prefix: expected on a truncated tail — skip.
+                            }
+                            else if (error instanceof Error) {
+                                Logger.error(`Error extracting representation item\n\t${error.message}\n\tExpress ID: #${item.expressID}`);
+                            }
+                            else {
+                                Logger.error(`Error extracting representation item\n\tExpress ID: #${item.expressID}`);
+                            }
+                        }
+                    }
+                    const styledItemLocalID_ = this.materials.styledItemMap.get(item.localID);
+                    if (styledItemLocalID_ !== undefined) {
+                        const styledItem_ = this.model.getElementByLocalID(styledItemLocalID_);
+                        this.extractStyledItem(styledItem_);
+                    }
+                    else if (reusableStyleID !== void 0) {
+                        this.materials.addGeometryMapping(item.localID, reusableStyleID);
+                    }
+                    else if (styledItem instanceof IfcStyledItem) {
+                        // here we have the styled item, apply it to all geometry in this IfcProduct
+                        reusableStyleID = this.extractStyledItem(styledItem, item);
+                    }
+                }
+            }
+        }
+        else {
+            for (const representation of representations.Representations) {
+                if (representation instanceof IfcShapeRepresentation) {
+                    // this check is essential -
+                    // if RepresentationIdentifier !== Body or Facetation we must skip it
+                    if (representation.RepresentationIdentifier !== "Body" &&
+                        representation.RepresentationIdentifier !== "Facetation") {
+                        continue;
+                    }
+                }
+                for (const item of representation.Items) {
+                    if (item instanceof IfcMappedItem) {
+                        this.extractMappedItem(item, product, hasRelVoid, isSpace);
+                    }
+                    else {
+                        try {
+                            this.extractRepresentationItem(item, product.localID, hasRelVoid, isSpace);
+                            if (hasRelVoid) {
+                                this.applyRelVoidToRepresentation(item, relVoidsMeshVector, product.localID, relVoidLocalIDs, void 0, isSpace);
+                            }
+                            const styledItemLocalID_ = this.materials.styledItemMap.get(item.localID);
+                            if (styledItemLocalID_ !== void 0) {
+                                const styledItem_ = this.model.getElementByLocalID(styledItemLocalID_);
+                                this.extractStyledItem(styledItem_);
+                            }
+                        }
+                        catch (error) {
+                            if (this.quietRecoverableLogging) {
+                                // Preview prefix: expected on a truncated tail — skip.
+                            }
+                            else if (error instanceof Error) {
+                                Logger.error(`Error extracting representation item\n\t${error.message}\n\t${error.stack}\n\tExpress ID: #${item.localID}`);
+                            }
+                            else {
+                                Logger.error(`Unknown error extracting representation item Express ID: #${item.localID}`);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        if (precomputedRelVoids === void 0) {
+            relVoidsMeshVector?.delete();
+        }
+    }
     /**
      * Extract the geometry data from the IFC
      *
@@ -4444,10 +5643,7 @@ export class IfcGeometryExtraction {
      */
     *extractIFCGeometryDataIncremental() {
         let result = ExtractResult.INCOMPLETE;
-        this.extractLinearScalingFactor();
         const previousMemoizationState = this.model.elementMemoization;
-        // populate relMaterialsMap
-        const relAssociatesMaterials = this.model.types(IfcRelAssociatesMaterial);
         try {
             // 256 meg limit for memoization - smaller models get a big
             // win from memoization, but much larger models it uses far too much heap.
@@ -4456,317 +5652,54 @@ export class IfcGeometryExtraction {
             if (this.lowMemoryMode || this.model.bufferBytesize > MEMOIZATION_THRESHOLD) {
                 this.model.elementMemoization = false;
             }
-            for (const relAssociateMaterial of relAssociatesMaterials) {
-                const relatingMaterial = relAssociateMaterial.RelatingMaterial;
-                try {
-                    const relatedObjects = relAssociateMaterial.RelatedObjects;
-                    for (const relatedObject of relatedObjects) {
-                        const product = relatedObject;
-                        if (product instanceof IfcProduct) {
-                            if (product instanceof IfcOpeningElement ||
-                                product instanceof IfcSpace ||
-                                product instanceof IfcOpeningStandardCase) {
-                                continue;
-                            }
-                            // save mapping of IfcProduct --> IfcMaterial
-                            this.materials.relMaterialsMap.set(product.localID, relatingMaterial.localID);
-                        }
-                        else {
-                            //     Logger.warning(`type other than IfcProduct: ${EntityTypesIfc[product.type]}`)
-                        }
-                    }
-                }
-                catch (ex) {
-                    if (ex instanceof Error) {
-                        if (MATERIAL_RELATED_OBJECTS_PERMISSIVE) {
-                            Logger.error("Error processing relatingMaterial expressID: " +
-                                `${relatingMaterial.expressID}, error: ${ex.message}`);
-                        }
-                        else {
-                            throw ex;
-                        }
-                    }
-                    else {
-                        Logger.error("Unknown exception processing IfcRelAssociateMaterials.");
-                    }
-                }
-            }
-            // populate MaterialDefinitionsMap
-            this.populateMaterialDefinitionsMap();
-            // populate relvoids map
-            this.populateRelVoidsMap();
-            // populate styled items map
-            this.populateStyledItemsMap();
+            this.prepareExtractionMaps_();
             const products = this.model.types(IfcProduct);
             // Prefix-sum counts (no iteration/materialization) — see typeCount.
             // Slight over-count from multi-mapped elements just leaves the bar
             // shy of 100% until endPhase; fine for progress.
             const totalItems = this.model.typeCount(IfcProduct) + this.model.typeCount(IfcRelAggregates);
             let completedItems = 0;
+            // Products the aggregates pass re-extracts are SKIPPED here and
+            // extracted exactly once, below, with the master rel-voids — one
+            // scene instance per placement and no content replacement after
+            // emission (see aggregateTargetLocalIDs).
+            const aggregateTargets = this.aggregateTargetLocalIDs();
             for (const product of products) {
                 yield [++completedItems, totalItems];
-                this.scene.clearParentStack();
-                const isSpace = product instanceof IfcOpeningElement ||
-                    product instanceof IfcSpace ||
-                    product instanceof IfcOpeningStandardCase;
-                const objectPlacement = product.ObjectPlacement;
-                if (objectPlacement !== null) {
-                    this.extractPlacement(objectPlacement);
-                }
-                const representations = product.Representation;
-                if (representations !== null) {
-                    // extract styledItem material
-                    const styledItemID = this.extractMaterialStyle(product);
-                    let hasRelVoid = false;
-                    const extractRelVoidsResult = this.extractRelVoids(product);
-                    let relVoidsMeshVector;
-                    let relVoidLocalIDs;
-                    if (extractRelVoidsResult !== void 0) {
-                        [relVoidsMeshVector, relVoidLocalIDs] = extractRelVoidsResult;
-                    }
-                    if (relVoidsMeshVector !== void 0) {
-                        hasRelVoid = true;
-                    }
-                    if (styledItemID !== void 0) {
-                        // optimization: extract the first representation item and cache
-                        // the styleID to apply to the rest of the product geometry
-                        const styledItem = this.model.getElementByLocalID(styledItemID);
-                        let reusableStyleID;
-                        for (const representation of representations.Representations) {
-                            if (representation instanceof IfcShapeRepresentation) {
-                                // this check is essential -
-                                // if RepresentationIdentifier !== Body or Facetation we must skip it
-                                if (representation.RepresentationIdentifier !== "Body" &&
-                                    representation.RepresentationIdentifier !== "Facetation") {
-                                    continue;
-                                }
-                            }
-                            for (const item of representation.Items) {
-                                if (item instanceof IfcMappedItem) {
-                                    this.extractMappedItem(item, product, hasRelVoid, isSpace);
-                                }
-                                else {
-                                    try {
-                                        this.extractRepresentationItem(item, product.localID, hasRelVoid, isSpace);
-                                        if (hasRelVoid) {
-                                            this.applyRelVoidToRepresentation(item, relVoidsMeshVector, product.localID, relVoidLocalIDs, void 0, isSpace);
-                                        }
-                                    }
-                                    catch (error) {
-                                        if (error instanceof Error) {
-                                            Logger.error(`Error extracting representation item\n\t${error.message}\n\tExpress ID: #${item.expressID}`);
-                                        }
-                                        else {
-                                            Logger.error(`Error extracting representation item\n\tExpress ID: #${item.expressID}`);
-                                        }
-                                    }
-                                }
-                                const styledItemLocalID_ = this.materials.styledItemMap.get(item.localID);
-                                if (styledItemLocalID_ !== undefined) {
-                                    const styledItem_ = this.model.getElementByLocalID(styledItemLocalID_);
-                                    this.extractStyledItem(styledItem_);
-                                }
-                                else if (reusableStyleID !== void 0) {
-                                    this.materials.addGeometryMapping(item.localID, reusableStyleID);
-                                }
-                                else if (styledItem instanceof IfcStyledItem) {
-                                    // here we have the styled item, apply it to all geometry in this IfcProduct
-                                    reusableStyleID = this.extractStyledItem(styledItem, item);
-                                }
-                            }
-                        }
-                    }
-                    else {
-                        for (const representation of representations.Representations) {
-                            if (representation instanceof IfcShapeRepresentation) {
-                                // this check is essential -
-                                // if RepresentationIdentifier !== Body or Facetation we must skip it
-                                if (representation.RepresentationIdentifier !== "Body" &&
-                                    representation.RepresentationIdentifier !== "Facetation") {
-                                    continue;
-                                }
-                            }
-                            for (const item of representation.Items) {
-                                if (item instanceof IfcMappedItem) {
-                                    this.extractMappedItem(item, product, hasRelVoid, isSpace);
-                                }
-                                else {
-                                    try {
-                                        this.extractRepresentationItem(item, product.localID, hasRelVoid, isSpace);
-                                        if (hasRelVoid) {
-                                            this.applyRelVoidToRepresentation(item, relVoidsMeshVector, product.localID, relVoidLocalIDs, void 0, isSpace);
-                                        }
-                                        const styledItemLocalID_ = this.materials.styledItemMap.get(item.localID);
-                                        if (styledItemLocalID_ !== void 0) {
-                                            const styledItem_ = this.model.getElementByLocalID(styledItemLocalID_);
-                                            this.extractStyledItem(styledItem_);
-                                        }
-                                    }
-                                    catch (error) {
-                                        if (error instanceof Error) {
-                                            Logger.error(`Error extracting representation item\n\t${error.message}\n\t${error.stack}\n\tExpress ID: #${item.localID}`);
-                                        }
-                                        else {
-                                            Logger.error(`Unknown error extracting representation item Express ID: #${item.localID}`);
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                    }
-                    relVoidsMeshVector?.delete();
+                if (aggregateTargets.has(product.localID)) {
+                    continue;
                 }
-            }
-            const relAggregates = this.model.types(IfcRelAggregates);
-            for (const relAggregate of relAggregates) {
-                yield [++completedItems, totalItems];
                 try {
-                    // Note, this is required because the relating object
-                    // can be where the rel-void is applied, so we
-                    // used this as a top level over-ride for a rel-void.
-                    // for all objects in the aggregate - CS
-                    const relatingObject = relAggregate.RelatingObject;
-                    const masterRelVoids = relatingObject instanceof IfcProduct ?
-                        this.extractRelVoids(relatingObject) :
-                        void 0;
-                    const relatedObjects = relAggregate.RelatedObjects;
-                    for (const productRepresentation of relatedObjects) {
-                        if (productRepresentation instanceof IfcProduct) {
-                            const isSpace = productRepresentation instanceof IfcOpeningElement ||
-                                productRepresentation instanceof IfcSpace ||
-                                productRepresentation instanceof IfcOpeningStandardCase;
-                            const product = productRepresentation;
-                            this.scene.clearParentStack();
-                            const objectPlacement = product.ObjectPlacement;
-                            if (objectPlacement !== null) {
-                                this.extractPlacement(objectPlacement);
-                            }
-                            const representations = product.Representation;
-                            if (representations !== null) {
-                                // extract styledItem material
-                                const styledItemID = this.extractMaterialStyle(product);
-                                const extractRelVoidsResult = masterRelVoids ?? this.extractRelVoids(product);
-                                let hasRelVoid = false;
-                                let relVoidsMeshVector;
-                                let relVoidLocalIDs;
-                                if (extractRelVoidsResult !== void 0) {
-                                    [relVoidsMeshVector, relVoidLocalIDs] = extractRelVoidsResult;
-                                }
-                                if (relVoidsMeshVector !== void 0) {
-                                    hasRelVoid = true;
-                                }
-                                if (styledItemID !== void 0) {
-                                    // optimization: extract the first representation item and cache
-                                    // the styleID to apply to the rest of the product geometry
-                                    const styledItem = this.model.getElementByLocalID(styledItemID);
-                                    let reusableStyleID;
-                                    for (const representation of representations.Representations) {
-                                        if (representation instanceof IfcShapeRepresentation) {
-                                            // this check is essential -
-                                            // if RepresentationIdentifier !== Body or Facetation we must skip it
-                                            if (representation.RepresentationIdentifier !== "Body" &&
-                                                representation.RepresentationIdentifier !== "Facetation") {
-                                                continue;
-                                            }
-                                        }
-                                        for (const item of representation.Items) {
-                                            if (item instanceof IfcMappedItem) {
-                                                this.extractMappedItem(item, product, hasRelVoid, isSpace);
-                                            }
-                                            else {
-                                                try {
-                                                    this.extractRepresentationItem(item, product.localID, hasRelVoid, isSpace);
-                                                    if (hasRelVoid) {
-                                                        this.applyRelVoidToRepresentation(item, relVoidsMeshVector, product.localID, relVoidLocalIDs, void 0, isSpace);
-                                                    }
-                                                }
-                                                catch (error) {
-                                                    if (error instanceof Error) {
-                                                        Logger.error(`Error extracting rel aggregate representation item\n\t${error.message}\n\t${error.stack}\n\t Express ID: #${item.expressID}`);
-                                                    }
-                                                    else {
-                                                        Logger.error(`Unknown error extracting rel aggregate representation item Express ID: #${item.expressID}`);
-                                                    }
-                                                }
-                                            }
-                                            const styledItemLocalID_ = this.materials.styledItemMap.get(item.localID);
-                                            if (styledItemLocalID_ !== undefined) {
-                                                const styledItem_ = this.model.getElementByLocalID(styledItemLocalID_);
-                                                this.extractStyledItem(styledItem_);
-                                            }
-                                            else if (reusableStyleID !== void 0) {
-                                                this.materials.addGeometryMapping(item.localID, reusableStyleID);
-                                            }
-                                            else if (styledItem instanceof IfcStyledItem) {
-                                                // here we have the styled item, apply it to all geometry in this IfcProduct
-                                                reusableStyleID = this.extractStyledItem(styledItem, item);
-                                            }
-                                        }
-                                    }
-                                }
-                                else {
-                                    for (const representation of representations.Representations) {
-                                        if (representation instanceof IfcShapeRepresentation) {
-                                            // this check is essential -
-                                            // if RepresentationIdentifier !== Body or Facetation we must skip it
-                                            if (representation.RepresentationIdentifier !== "Body" &&
-                                                representation.RepresentationIdentifier !== "Facetation") {
-                                                continue;
-                                            }
-                                        }
-                                        for (const item of representation.Items) {
-                                            if (item instanceof IfcMappedItem) {
-                                                this.extractMappedItem(item, product, hasRelVoid, isSpace);
-                                            }
-                                            else {
-                                                try {
-                                                    this.extractRepresentationItem(item, product.localID, hasRelVoid, isSpace);
-                                                    if (hasRelVoid) {
-                                                        this.applyRelVoidToRepresentation(item, relVoidsMeshVector, product.localID, relVoidLocalIDs, void 0, isSpace);
-                                                    }
-                                                    const styledItemLocalID_ = this.materials.styledItemMap.get(item.localID);
-                                                    if (styledItemLocalID_ !== void 0) {
-                                                        const styledItem_ = this.model.getElementByLocalID(styledItemLocalID_);
-                                                        this.extractStyledItem(styledItem_);
-                                                    }
-                                                }
-                                                catch (error) {
-                                                    if (error instanceof Error) {
-                                                        Logger.error(`Error extracting rel aggregate representation item\n\t${error.message}\n\t${error.stack}\n\t Express ID: #${item.expressID}`);
-                                                    }
-                                                    else {
-                                                        Logger.error(`Unknown error extracting rel aggregate representation item Express ID: #${item.expressID}`);
-                                                    }
-                                                }
-                                            }
-                                        }
-                                    }
-                                }
-                                if (masterRelVoids === void 0) {
-                                    relVoidsMeshVector?.delete();
-                                }
-                            }
-                        }
-                    }
-                    if (masterRelVoids !== void 0) {
-                        masterRelVoids[0].delete();
-                    }
+                    this.extractProductGeometry(product);
                 }
                 catch (ex) {
+                    // A single malformed product must not abort the whole model. A
+                    // reference field carrying a value where an entity is expected
+                    // throws "Value in STEP was incorrectly typed" deep in material/
+                    // representation extraction; the rel-aggregates pass below already
+                    // tolerates this per-relationship, and the browser demand pump
+                    // swallows per-product throws, so a model that renders in prod
+                    // would otherwise hard-fail the headless regression batch. Skip
+                    // the offending product and continue; strict mode re-throws.
                     if (ex instanceof Error) {
                         if (MATERIAL_RELATED_OBJECTS_PERMISSIVE) {
-                            Logger.error("Error processing relAggregate\n\t" +
-                                `error: ${ex.message}\n\t express ID: #${relAggregate.expressID}`);
+                            Logger.error(`Error extracting product expressID: ${product.expressID}, ` +
+                                `error: ${ex.message}`);
                         }
                         else {
                             throw ex;
                         }
                     }
                     else {
-                        Logger.error("Unknown exception processing IfcRelAssociateMaterials.");
+                        Logger.error("Unknown exception extracting product.");
                     }
                 }
             }
+            const relAggregates = this.model.types(IfcRelAggregates);
+            for (const relAggregate of relAggregates) {
+                yield [++completedItems, totalItems];
+                this.extractRelAggregateGeometry(relAggregate);
+            }
             if (RegressionCaptureState.memoization !== MemoizationCapture.FULL) {
                 this.model.geometry.deleteTemporaries();
                 this.model.voidGeometry.deleteTemporaries();