@bldrs-ai/conway 1.413.1255 → 1.416.1260

package/compiled/examples/browser-bundled.cjs

@@ -30,7 +30,7 @@ var import_node_process = require("node:process");
 var readline = __toESM(require("node:readline"), 1);
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.413.1255";
+var versionString = "Conway v1.416.1260";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";

package/compiled/examples/cli-bundled.cjs

@@ -14965,7 +14965,7 @@ ${t5.join("\n")}` : "";
 var import_process = require("process");
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.413.1255";
+var versionString = "Conway v1.416.1260";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {
@@ -87610,6 +87610,7 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
     this.geometryTypeCounts = /* @__PURE__ */ new Map();
     this.csgDepth = 0;
     this.freeVectorPolygonalFaces_ = [];
+    this.extractionMapsPrepared_ = false;
     this.csgMemoization = !this.lowMemoryMode;
     this.materials = model.materials;
     this.scene = new IfcSceneBuilder(model, conwayModel, this.materials);
@@ -91414,6 +91415,195 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
    */
   dumpGeometry(outputFilePath, geometry) {
   }
+  /**
+   * 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();
+    const relAssociatesMaterials = this.model.types(IfcRelAssociatesMaterial);
+    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;
+            }
+            this.materials.relMaterialsMap.set(product.localID, relatingMaterial.localID);
+          } else {
+          }
+        }
+      } catch (ex) {
+        if (ex instanceof Error) {
+          if (MATERIAL_RELATED_OBJECTS_PERMISSIVE) {
+            logger_default.error(`Error processing relatingMaterial expressID: ${relatingMaterial.expressID}, error: ${ex.message}`);
+          } else {
+            throw ex;
+          }
+        } else {
+          logger_default.error("Unknown exception processing IfcRelAssociateMaterials.");
+        }
+      }
+    }
+    this.populateMaterialDefinitionsMap();
+    this.populateRelVoidsMap();
+    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.
+   */
+  prepareDemandExtraction() {
+    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: products that are targets of IfcRelAggregates whose relating
+   * object carries rel-voids get those master voids only on the whole-model
+   * walk; the demand path extracts the product's own voids. The parity gate
+   * for this seam is the whole-model digest CI.
+   *
+   * @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;
+  }
+  /**
+   * 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;
+    const objectPlacement = product.ObjectPlacement;
+    if (objectPlacement !== null) {
+      this.extractPlacement(objectPlacement);
+    }
+    const representations = product.Representation;
+    if (representations === null) {
+      return;
+    }
+    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) {
+      const styledItem = this.model.getElementByLocalID(styledItemID);
+      let reusableStyleID;
+      for (const representation of representations.Representations) {
+        if (representation instanceof IfcShapeRepresentation) {
+          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_default.error(`Error extracting representation item
+	${error.message}
+	Express ID: #${item.expressID}`);
+              } else {
+                logger_default.error(`Error extracting representation item
+	Express ID: #${item.expressID}`);
+              }
+            }
+          }
+          const styledItemLocalID_ = this.materials.styledItemMap.get(item.localID);
+          if (styledItemLocalID_ !== void 0) {
+            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) {
+            reusableStyleID = this.extractStyledItem(styledItem, item);
+          }
+        }
+      }
+    } else {
+      for (const representation of representations.Representations) {
+        if (representation instanceof IfcShapeRepresentation) {
+          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_default.error(`Error extracting representation item
+	${error.message}
+	${error.stack}
+	Express ID: #${item.localID}`);
+              } else {
+                logger_default.error(`Unknown error extracting representation item Express ID: #${item.localID}`);
+              }
+            }
+          }
+        }
+      }
+    }
+    if (precomputedRelVoids === void 0) {
+      relVoidsMeshVector?.delete();
+    }
+  }
   /**
    * Extract the geometry data from the IFC
    *
@@ -91488,144 +91678,19 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
    */
   *extractIFCGeometryDataIncremental() {
     let result = ExtractResult.INCOMPLETE;
-    this.extractLinearScalingFactor();
     const previousMemoizationState = this.model.elementMemoization;
-    const relAssociatesMaterials = this.model.types(IfcRelAssociatesMaterial);
     try {
       const MEMOIZATION_THRESHOLD = 256 * 1024 * 1024;
       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;
-              }
-              this.materials.relMaterialsMap.set(product.localID, relatingMaterial.localID);
-            } else {
-            }
-          }
-        } catch (ex) {
-          if (ex instanceof Error) {
-            if (MATERIAL_RELATED_OBJECTS_PERMISSIVE) {
-              logger_default.error(`Error processing relatingMaterial expressID: ${relatingMaterial.expressID}, error: ${ex.message}`);
-            } else {
-              throw ex;
-            }
-          } else {
-            logger_default.error("Unknown exception processing IfcRelAssociateMaterials.");
-          }
-        }
-      }
-      this.populateMaterialDefinitionsMap();
-      this.populateRelVoidsMap();
-      this.populateStyledItemsMap();
+      this.prepareExtractionMaps_();
       const products = this.model.types(IfcProduct);
       const totalItems = this.model.typeCount(IfcProduct) + this.model.typeCount(IfcRelAggregates);
       let completedItems = 0;
       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) {
-          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) {
-            const styledItem = this.model.getElementByLocalID(styledItemID);
-            let reusableStyleID;
-            for (const representation of representations.Representations) {
-              if (representation instanceof IfcShapeRepresentation) {
-                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_default.error(`Error extracting representation item
-	${error.message}
-	Express ID: #${item.expressID}`);
-                    } else {
-                      logger_default.error(`Error extracting representation item
-	Express ID: #${item.expressID}`);
-                    }
-                  }
-                }
-                const styledItemLocalID_ = this.materials.styledItemMap.get(item.localID);
-                if (styledItemLocalID_ !== void 0) {
-                  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) {
-                  reusableStyleID = this.extractStyledItem(styledItem, item);
-                }
-              }
-            }
-          } else {
-            for (const representation of representations.Representations) {
-              if (representation instanceof IfcShapeRepresentation) {
-                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_default.error(`Error extracting representation item
-	${error.message}
-	${error.stack}
-	Express ID: #${item.localID}`);
-                    } else {
-                      logger_default.error(`Unknown error extracting representation item Express ID: #${item.localID}`);
-                    }
-                  }
-                }
-              }
-            }
-          }
-          relVoidsMeshVector?.delete();
-        }
+        this.extractProductGeometry(product);
       }
       const relAggregates = this.model.types(IfcRelAggregates);
       for (const relAggregate of relAggregates) {
@@ -91636,105 +91701,7 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
           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) {
-                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) {
-                  const styledItem = this.model.getElementByLocalID(styledItemID);
-                  let reusableStyleID;
-                  for (const representation of representations.Representations) {
-                    if (representation instanceof IfcShapeRepresentation) {
-                      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_default.error(`Error extracting rel aggregate representation item
-	${error.message}
-	${error.stack}
-	 Express ID: #${item.expressID}`);
-                          } else {
-                            logger_default.error(`Unknown error extracting rel aggregate representation item Express ID: #${item.expressID}`);
-                          }
-                        }
-                      }
-                      const styledItemLocalID_ = this.materials.styledItemMap.get(item.localID);
-                      if (styledItemLocalID_ !== void 0) {
-                        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) {
-                        reusableStyleID = this.extractStyledItem(styledItem, item);
-                      }
-                    }
-                  }
-                } else {
-                  for (const representation of representations.Representations) {
-                    if (representation instanceof IfcShapeRepresentation) {
-                      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_default.error(`Error extracting rel aggregate representation item
-	${error.message}
-	${error.stack}
-	 Express ID: #${item.expressID}`);
-                          } else {
-                            logger_default.error(`Unknown error extracting rel aggregate representation item Express ID: #${item.expressID}`);
-                          }
-                        }
-                      }
-                    }
-                  }
-                }
-                if (masterRelVoids === void 0) {
-                  relVoidsMeshVector?.delete();
-                }
-              }
+              this.extractProductGeometry(productRepresentation, masterRelVoids);
             }
           }
           if (masterRelVoids !== void 0) {

package/compiled/examples/cli-step-bundled.cjs

@@ -15943,7 +15943,7 @@ var ParsingBuffer = class {
 };
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.413.1255";
+var versionString = "Conway v1.416.1260";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {

package/compiled/examples/validator-bundled.cjs

@@ -944,7 +944,7 @@ var EntityTypesIfcCount = 909;
 var entity_types_ifc_gen_default = EntityTypesIfc;
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.413.1255";
+var versionString = "Conway v1.416.1260";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";

package/compiled/src/ifc/ifc_demand_extraction.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ifc_demand_extraction.test.d.ts.map

package/compiled/src/ifc/ifc_demand_extraction.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ifc_demand_extraction.test.d.ts","sourceRoot":"","sources":["../../../src/ifc/ifc_demand_extraction.test.ts"],"names":[],"mappings":""}

package/compiled/src/ifc/ifc_demand_extraction.test.js

@@ -0,0 +1,111 @@
+/* eslint-disable no-magic-numbers, @typescript-eslint/no-explicit-any */
+// Phase B2: per-product demand extraction must produce the same meshes the
+// whole-model walk produces — same products with geometry, same vertex and
+// index counts per product — since both now run the same deduplicated
+// per-product body (extractProductGeometry).
+import fs from "fs";
+import { beforeAll, describe, expect, test } from "@jest/globals";
+import { IfcGeometryExtraction } from "./ifc_geometry_extraction.js";
+import { ParseResult } from "../step/parsing/step_parser.js";
+import IfcStepParser from "./ifc_step_parser.js";
+import ParsingBuffer from "../parsing/parsing_buffer.js";
+import { ConwayGeometry } from "../../dependencies/conway-geom/index.js";
+import { ExtractResult } from "../core/shared_constants.js";
+import { IfcProduct } from "./ifc4_gen/index.js";
+let conwayGeometry;
+/**
+ * Parse a fresh model from index.ifc (models are stateful; each extraction
+ * mode gets its own).
+ *
+ * @return {IfcStepModel} The parsed model.
+ */
+function freshModel() {
+    const bytes = fs.readFileSync("data/index.ifc");
+    const input = new ParsingBuffer(bytes);
+    expect(IfcStepParser.Instance.parseHeader(input)[1])
+        .toBe(ParseResult.COMPLETE);
+    const [, model] = IfcStepParser.Instance.parseDataToModel(input);
+    expect(model).toBeDefined();
+    return model;
+}
+/**
+ * Collect per-localID mesh signatures (vertex + triangle counts) from a
+ * model's extracted geometry.
+ *
+ * @param extraction The extraction whose model geometry to summarise.
+ * @return {Map<number, string>} localID → "vertexCount/triangleCount".
+ */
+function meshSignatures(extraction) {
+    const signatures = new Map();
+    for (const mesh of extraction.model.geometry) {
+        const geometry = mesh.geometry;
+        if (geometry === void 0 || typeof geometry.getVertexCount !== "function") {
+            continue;
+        }
+        signatures.set(mesh.localID, `${geometry.getVertexCount()}/${geometry.getTriangleCount()}`);
+    }
+    return signatures;
+}
+beforeAll(async () => {
+    conwayGeometry = new ConwayGeometry();
+    expect(await conwayGeometry.initialize()).toBe(true);
+});
+describe("per-product demand extraction (Phase B2)", () => {
+    test("demand extraction over all products matches the whole-model walk", () => {
+        // Whole-model walk (the CI-anchored path).
+        const wholeExtraction = new IfcGeometryExtraction(conwayGeometry, freshModel());
+        expect(wholeExtraction.extractIFCGeometryData()[0])
+            .toBe(ExtractResult.COMPLETE);
+        const wholeSignatures = meshSignatures(wholeExtraction);
+        expect(wholeSignatures.size).toBeGreaterThan(0);
+        // Demand path: prepare once, then extract every product individually.
+        const demandModel = freshModel();
+        const demandExtraction = new IfcGeometryExtraction(conwayGeometry, demandModel);
+        demandExtraction.prepareDemandExtraction();
+        let extractedProducts = 0;
+        for (const product of demandModel.types(IfcProduct)) {
+            if (demandExtraction.extractProductGeometryByLocalID(product.localID)) {
+                ++extractedProducts;
+            }
+        }
+        expect(extractedProducts).toBeGreaterThan(0);
+        const demandSignatures = meshSignatures(demandExtraction);
+        // Same set of products with geometry, same mesh shape per product.
+        expect(demandSignatures).toEqual(wholeSignatures);
+    });
+    test("a single product extracts on demand without the whole-model walk", () => {
+        // Whole-model reference signatures (mesh localIDs key representation
+        // items, not products — so parity is checked per matching key).
+        const reference = new IfcGeometryExtraction(conwayGeometry, freshModel());
+        reference.extractIFCGeometryData();
+        const referenceSignatures = meshSignatures(reference);
+        const model = freshModel();
+        const extraction = new IfcGeometryExtraction(conwayGeometry, model);
+        // Extract single products on the fresh model until one yields a mesh —
+        // proving a lone product materialises without the whole-model walk.
+        let produced = 0;
+        for (const product of model.types(IfcProduct)) {
+            extraction.extractProductGeometryByLocalID(product.localID);
+            produced = meshSignatures(extraction).size;
+            if (produced > 0) {
+                break;
+            }
+        }
+        expect(produced).toBeGreaterThan(0);
+        expect(produced).toBeLessThan(referenceSignatures.size);
+        // Every mesh the single extraction produced matches the reference's
+        // mesh for the same key exactly.
+        for (const [localID, signature] of meshSignatures(extraction)) {
+            expect(referenceSignatures.get(localID)).toBe(signature);
+        }
+    });
+    test("a non-product local ID is refused", () => {
+        const model = freshModel();
+        const extraction = new IfcGeometryExtraction(conwayGeometry, model);
+        // localID 0 in index.ifc is not an IfcProduct (first record is a root
+        // non-product entity in this fixture; the assertion below guards that).
+        const first = model.getElementByLocalID(0);
+        expect(first instanceof IfcProduct).toBe(false);
+        expect(extraction.extractProductGeometryByLocalID(0)).toBe(false);
+    });
+});

package/compiled/src/ifc/ifc_geometry_extraction.d.ts

@@ -920,6 +920,53 @@ export declare class IfcGeometryExtraction {
      * @param geometry
      */
     dumpGeometry(outputFilePath: string, geometry: GeometryObject): void;
+    private extractionMapsPrepared_;
+    /**
+     * 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.
+     */
+    private prepareExtractionMaps_;
+    /**
+     * 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.
+     */
+    prepareDemandExtraction(): void;
+    /**
+     * 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: products that are targets of IfcRelAggregates whose relating
+     * object carries rel-voids get those master voids only on the whole-model
+     * walk; the demand path extracts the product's own voids. The parity gate
+     * for this seam is the whole-model digest CI.
+     *
+     * @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: number): boolean;
+    /**
+     * 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: IfcProduct, precomputedRelVoids?: [
+        NativeVectorGeometry,
+        number[]
+    ]): void;
     /**
      * Extract the geometry data from the IFC
      *