@ifc-lite/parser 2.1.7 → 2.1.9

package/dist/columnar-parser.js

@@ -4,402 +4,13 @@
 import { SpatialHierarchyBuilder } from './spatial-hierarchy-builder.js';
 import { EntityExtractor } from './entity-extractor.js';
 import { extractLengthUnitScale } from './unit-extractor.js';
-import { decodeIfcString } from '@ifc-lite/encoding';
 import { getAttributeNames, getInheritanceChain } from './ifc-schema.js';
 import { parsePropertyValue } from './on-demand-extractors.js';
-import { buildCompactEntityIndex } from './compact-entity-index.js';
+import { buildCompactEntityIndexAsync } from './compact-entity-index.js';
 import { StringTable, EntityTableBuilder, PropertyTableBuilder, QuantityTableBuilder, RelationshipGraphBuilder, RelationshipType, QuantityType, } from '@ifc-lite/data';
-// Pre-computed type sets for O(1) lookups
-const GEOMETRY_TYPES = new Set([
-    'IFCWALL', 'IFCWALLSTANDARDCASE', 'IFCDOOR', 'IFCWINDOW', 'IFCSLAB',
-    'IFCCOLUMN', 'IFCBEAM', 'IFCROOF', 'IFCSTAIR', 'IFCSTAIRFLIGHT',
-    'IFCRAILING', 'IFCRAMP', 'IFCRAMPFLIGHT', 'IFCPLATE', 'IFCMEMBER',
-    'IFCCURTAINWALL', 'IFCFOOTING', 'IFCPILE', 'IFCBUILDINGELEMENTPROXY',
-    'IFCFURNISHINGELEMENT', 'IFCFLOWSEGMENT', 'IFCFLOWTERMINAL',
-    'IFCFLOWCONTROLLER', 'IFCFLOWFITTING', 'IFCSPACE', 'IFCOPENINGELEMENT',
-    'IFCSITE', 'IFCBUILDING', 'IFCBUILDINGSTOREY',
-]);
-// IMPORTANT: This set MUST include ALL RelationshipType enum values to prevent semantic loss
-// Missing types will be skipped during parsing, causing incomplete relationship graphs
-const RELATIONSHIP_TYPES = new Set([
-    'IFCRELCONTAINEDINSPATIALSTRUCTURE', 'IFCRELAGGREGATES',
-    'IFCRELDEFINESBYPROPERTIES', 'IFCRELDEFINESBYTYPE',
-    'IFCRELASSOCIATESMATERIAL', 'IFCRELASSOCIATESCLASSIFICATION',
-    'IFCRELASSOCIATESDOCUMENT',
-    'IFCRELVOIDSELEMENT', 'IFCRELFILLSELEMENT',
-    'IFCRELCONNECTSPATHELEMENTS', 'IFCRELCONNECTSELEMENTS',
-    'IFCRELSPACEBOUNDARY',
-    'IFCRELASSIGNSTOGROUP', 'IFCRELASSIGNSTOPRODUCT',
-    'IFCRELREFERENCEDINSPATIALSTRUCTURE',
-]);
-// Map IFC relationship type strings to RelationshipType enum
-// MUST cover ALL RelationshipType enum values (14 types total)
-const REL_TYPE_MAP = {
-    'IFCRELCONTAINEDINSPATIALSTRUCTURE': RelationshipType.ContainsElements,
-    'IFCRELAGGREGATES': RelationshipType.Aggregates,
-    'IFCRELDEFINESBYPROPERTIES': RelationshipType.DefinesByProperties,
-    'IFCRELDEFINESBYTYPE': RelationshipType.DefinesByType,
-    'IFCRELASSOCIATESMATERIAL': RelationshipType.AssociatesMaterial,
-    'IFCRELASSOCIATESCLASSIFICATION': RelationshipType.AssociatesClassification,
-    'IFCRELASSOCIATESDOCUMENT': RelationshipType.AssociatesDocument,
-    'IFCRELVOIDSELEMENT': RelationshipType.VoidsElement,
-    'IFCRELFILLSELEMENT': RelationshipType.FillsElement,
-    'IFCRELCONNECTSPATHELEMENTS': RelationshipType.ConnectsPathElements,
-    'IFCRELCONNECTSELEMENTS': RelationshipType.ConnectsElements,
-    'IFCRELSPACEBOUNDARY': RelationshipType.SpaceBoundary,
-    'IFCRELASSIGNSTOGROUP': RelationshipType.AssignsToGroup,
-    'IFCRELASSIGNSTOPRODUCT': RelationshipType.AssignsToProduct,
-    'IFCRELREFERENCEDINSPATIALSTRUCTURE': RelationshipType.ReferencedInSpatialStructure,
-};
-const QUANTITY_TYPE_MAP = {
-    'IFCQUANTITYLENGTH': QuantityType.Length,
-    'IFCQUANTITYAREA': QuantityType.Area,
-    'IFCQUANTITYVOLUME': QuantityType.Volume,
-    'IFCQUANTITYCOUNT': QuantityType.Count,
-    'IFCQUANTITYWEIGHT': QuantityType.Weight,
-    'IFCQUANTITYTIME': QuantityType.Time,
-};
-// Types needed for spatial hierarchy (small subset)
-const SPATIAL_TYPES = new Set([
-    'IFCPROJECT', 'IFCSITE', 'IFCBUILDING', 'IFCBUILDINGSTOREY', 'IFCSPACE',
-    'IFCFACILITY', 'IFCFACILITYPART',
-    'IFCBRIDGE', 'IFCBRIDGEPART',
-    'IFCROAD', 'IFCROADPART',
-    'IFCRAILWAY', 'IFCRAILWAYPART',
-    'IFCMARINEFACILITY',
-]);
-// Relationship types needed for hierarchy and structural relationships
-const HIERARCHY_REL_TYPES = new Set([
-    'IFCRELAGGREGATES', 'IFCRELCONTAINEDINSPATIALSTRUCTURE',
-    'IFCRELDEFINESBYTYPE',
-    // Structural relationships (voids, fills, connections, groups)
-    'IFCRELVOIDSELEMENT', 'IFCRELFILLSELEMENT',
-    'IFCRELCONNECTSPATHELEMENTS', 'IFCRELCONNECTSELEMENTS',
-    'IFCRELSPACEBOUNDARY',
-    'IFCRELASSIGNSTOGROUP', 'IFCRELASSIGNSTOPRODUCT',
-    'IFCRELREFERENCEDINSPATIALSTRUCTURE',
-]);
-// Relationship types for on-demand property loading
-const PROPERTY_REL_TYPES = new Set([
-    'IFCRELDEFINESBYPROPERTIES',
-]);
-// Relationship types for on-demand classification/material loading
-const ASSOCIATION_REL_TYPES = new Set([
-    'IFCRELASSOCIATESCLASSIFICATION', 'IFCRELASSOCIATESMATERIAL',
-    'IFCRELASSOCIATESDOCUMENT',
-]);
-// Attributes to skip in extractAllEntityAttributes (shown elsewhere or non-displayable)
-const SKIP_DISPLAY_ATTRS = new Set(['GlobalId', 'OwnerHistory', 'ObjectPlacement', 'Representation', 'HasPropertySets', 'RepresentationMaps']);
-// Property-related entity types for on-demand extraction
-const PROPERTY_ENTITY_TYPES = new Set([
-    'IFCPROPERTYSET', 'IFCELEMENTQUANTITY',
-    'IFCPROPERTYSINGLEVALUE', 'IFCPROPERTYENUMERATEDVALUE',
-    'IFCPROPERTYBOUNDEDVALUE', 'IFCPROPERTYTABLEVALUE',
-    'IFCPROPERTYLISTVALUE', 'IFCPROPERTYREFERENCEVALUE',
-    'IFCQUANTITYLENGTH', 'IFCQUANTITYAREA', 'IFCQUANTITYVOLUME',
-    'IFCQUANTITYCOUNT', 'IFCQUANTITYWEIGHT', 'IFCQUANTITYTIME',
-]);
-function isIfcTypeLikeEntity(typeUpper) {
-    return typeUpper.endsWith('TYPE') || typeUpper.endsWith('STYLE');
-}
-// ==========================================
-// Byte-level helpers for fast extraction
-// These avoid per-entity TextDecoder calls by working on raw bytes.
-// ==========================================
-/**
- * Find the byte range of a quoted string at a specific attribute position in STEP entity bytes.
- * Returns [start, end) byte offsets (excluding quotes), or null if not found.
- *
- * @param buffer - The IFC file buffer
- * @param entityStart - byte offset of the entity
- * @param entityLen - byte length of the entity
- * @param attrIndex - 0-based attribute index (0=GlobalId, 2=Name)
- */
-function findQuotedAttrRange(buffer, entityStart, entityLen, attrIndex) {
-    const end = entityStart + entityLen;
-    let pos = entityStart;
-    // Skip to opening paren '(' after TYPE name
-    while (pos < end && buffer[pos] !== 0x28 /* ( */)
-        pos++;
-    if (pos >= end)
-        return null;
-    pos++; // skip '('
-    // Skip commas to reach the target attribute
-    if (attrIndex > 0) {
-        let toSkip = attrIndex;
-        let depth = 0;
-        let inStr = false;
-        while (pos < end && toSkip > 0) {
-            const ch = buffer[pos];
-            if (ch === 0x27 /* ' */) {
-                if (inStr && pos + 1 < end && buffer[pos + 1] === 0x27) {
-                    pos += 2;
-                    continue;
-                }
-                inStr = !inStr;
-            }
-            else if (!inStr) {
-                if (ch === 0x28)
-                    depth++;
-                else if (ch === 0x29)
-                    depth--;
-                else if (ch === 0x2C && depth === 0)
-                    toSkip--;
-            }
-            pos++;
-        }
-    }
-    // Skip whitespace
-    while (pos < end && (buffer[pos] === 0x20 || buffer[pos] === 0x09))
-        pos++;
-    // Check for quoted string
-    if (pos >= end || buffer[pos] !== 0x27 /* ' */)
-        return null;
-    pos++; // skip opening quote
-    const start = pos;
-    // Find closing quote (handle escaped quotes '')
-    while (pos < end) {
-        if (buffer[pos] === 0x27) {
-            if (pos + 1 < end && buffer[pos + 1] === 0x27) {
-                pos += 2;
-                continue;
-            }
-            break;
-        }
-        pos++;
-    }
-    return [start, pos];
-}
-/**
- * Batch extract GlobalId (attr[0]) and Name (attr[2]) for many entities using
- * only 2 TextDecoder.decode() calls total (one for all GlobalIds, one for all Names).
- *
- * This is ~100x faster than calling extractEntity() per entity for large batches
- * because it eliminates per-entity TextDecoder overhead which is significant in Firefox.
- *
- * Returns a Map from expressId → { globalId, name }.
- */
-function batchExtractGlobalIdAndName(buffer, refs) {
-    const result = new Map();
-    if (refs.length === 0)
-        return result;
-    // Phase 1: Scan byte ranges for GlobalId and Name positions (no string allocation)
-    const gidRanges = []; // [start, end) for each entity
-    const nameRanges = [];
-    const validIndices = []; // indices into refs for entities with valid ranges
-    for (let i = 0; i < refs.length; i++) {
-        const ref = refs[i];
-        const gidRange = findQuotedAttrRange(buffer, ref.byteOffset, ref.byteLength, 0);
-        const nameRange = findQuotedAttrRange(buffer, ref.byteOffset, ref.byteLength, 2);
-        gidRanges.push(gidRange ?? [0, 0]);
-        nameRanges.push(nameRange ?? [0, 0]);
-        validIndices.push(i);
-    }
-    // Phase 2: Concatenate all GlobalId bytes into one buffer, decode once
-    // Use null byte (0x00) as separator (never appears in IFC string content)
-    let totalGidBytes = 0;
-    let totalNameBytes = 0;
-    for (let i = 0; i < validIndices.length; i++) {
-        const [gs, ge] = gidRanges[i];
-        const [ns, ne] = nameRanges[i];
-        totalGidBytes += (ge - gs) + 1; // +1 for separator
-        totalNameBytes += (ne - ns) + 1;
-    }
-    const gidBuf = new Uint8Array(totalGidBytes);
-    const nameBuf = new Uint8Array(totalNameBytes);
-    let gidOffset = 0;
-    let nameOffset = 0;
-    for (let i = 0; i < validIndices.length; i++) {
-        const [gs, ge] = gidRanges[i];
-        const [ns, ne] = nameRanges[i];
-        if (ge > gs) {
-            gidBuf.set(buffer.subarray(gs, ge), gidOffset);
-            gidOffset += ge - gs;
-        }
-        gidBuf[gidOffset++] = 0; // null separator
-        if (ne > ns) {
-            nameBuf.set(buffer.subarray(ns, ne), nameOffset);
-            nameOffset += ne - ns;
-        }
-        nameBuf[nameOffset++] = 0;
-    }
-    // Phase 3: Two TextDecoder calls for ALL entities
-    const decoder = new TextDecoder();
-    const allGids = decoder.decode(gidBuf.subarray(0, gidOffset));
-    const allNames = decoder.decode(nameBuf.subarray(0, nameOffset));
-    const gids = allGids.split('\0');
-    const names = allNames.split('\0');
-    // Phase 4: Build result map
-    for (let i = 0; i < validIndices.length; i++) {
-        const ref = refs[validIndices[i]];
-        const rawName = names[i] || '';
-        result.set(ref.expressId, {
-            globalId: gids[i] || '',
-            name: rawName ? decodeIfcString(rawName) : '',
-        });
-    }
-    return result;
-}
-// ==========================================
-// Byte-level relationship scanners (numbers only, no TextDecoder)
-// ==========================================
-/**
- * Skip N commas at depth 0 in STEP bytes.
- */
-function skipCommas(buffer, start, end, count) {
-    let pos = start;
-    let remaining = count;
-    let depth = 0;
-    let inString = false;
-    while (pos < end && remaining > 0) {
-        const ch = buffer[pos];
-        if (ch === 0x27) {
-            if (inString && pos + 1 < end && buffer[pos + 1] === 0x27) {
-                pos += 2;
-                continue;
-            }
-            inString = !inString;
-        }
-        else if (!inString) {
-            if (ch === 0x28)
-                depth++;
-            else if (ch === 0x29)
-                depth--;
-            else if (ch === 0x2C && depth === 0)
-                remaining--;
-        }
-        pos++;
-    }
-    return pos;
-}
-/** Read a #ID entity reference as a number. Returns -1 if not an entity ref. */
-function readRefId(buffer, pos, end) {
-    while (pos < end && (buffer[pos] === 0x20 || buffer[pos] === 0x09))
-        pos++;
-    if (pos < end && buffer[pos] === 0x23) {
-        pos++;
-        let num = 0;
-        while (pos < end && buffer[pos] >= 0x30 && buffer[pos] <= 0x39) {
-            num = num * 10 + (buffer[pos] - 0x30);
-            pos++;
-        }
-        return [num, pos];
-    }
-    return [-1, pos];
-}
-/** Read a list of entity refs (#id1,#id2,...) or a single #id. Returns [ids, newPos]. */
-function readRefList(buffer, pos, end) {
-    while (pos < end && (buffer[pos] === 0x20 || buffer[pos] === 0x09))
-        pos++;
-    const ids = [];
-    if (pos < end && buffer[pos] === 0x28) {
-        pos++;
-        while (pos < end && buffer[pos] !== 0x29) {
-            while (pos < end && (buffer[pos] === 0x20 || buffer[pos] === 0x09 || buffer[pos] === 0x2C))
-                pos++;
-            if (pos < end && buffer[pos] === 0x23) {
-                const [id, np] = readRefId(buffer, pos, end);
-                if (id >= 0)
-                    ids.push(id);
-                pos = np;
-            }
-            else if (pos < end && buffer[pos] !== 0x29) {
-                pos++;
-            }
-        }
-    }
-    else if (pos < end && buffer[pos] === 0x23) {
-        const [id, np] = readRefId(buffer, pos, end);
-        if (id >= 0)
-            ids.push(id);
-        pos = np;
-    }
-    return [ids, pos];
-}
-/**
- * Extract relatingObject and relatedObjects from a relationship entity using byte-level scanning.
- * No TextDecoder needed - only extracts numeric entity IDs.
- */
-function extractRelFast(buffer, byteOffset, byteLength, typeUpper) {
-    const end = byteOffset + byteLength;
-    let pos = byteOffset;
-    while (pos < end && buffer[pos] !== 0x28)
-        pos++;
-    if (pos >= end)
-        return null;
-    pos++;
-    // Skip to attr[4] (all IfcRelationship subtypes have 4 shared IfcRoot+IfcRelationship attrs)
-    pos = skipCommas(buffer, pos, end, 4);
-    if (typeUpper === 'IFCRELCONTAINEDINSPATIALSTRUCTURE'
-        || typeUpper === 'IFCRELREFERENCEDINSPATIALSTRUCTURE'
-        || typeUpper === 'IFCRELDEFINESBYPROPERTIES'
-        || typeUpper === 'IFCRELDEFINESBYTYPE') {
-        // attr[4]=RelatedObjects, attr[5]=RelatingObject
-        const [related, rp] = readRefList(buffer, pos, end);
-        pos = rp;
-        while (pos < end && buffer[pos] !== 0x2C)
-            pos++;
-        pos++;
-        const [relating, _] = readRefId(buffer, pos, end);
-        if (relating < 0 || related.length === 0)
-            return null;
-        return { relatingObject: relating, relatedObjects: related };
-    }
-    else if (typeUpper === 'IFCRELASSIGNSTOGROUP' || typeUpper === 'IFCRELASSIGNSTOPRODUCT') {
-        const [related, rp] = readRefList(buffer, pos, end);
-        pos = skipCommas(buffer, rp, end, 2);
-        const [relating, _] = readRefId(buffer, pos, end);
-        if (relating < 0 || related.length === 0)
-            return null;
-        return { relatingObject: relating, relatedObjects: related };
-    }
-    else if (typeUpper === 'IFCRELCONNECTSELEMENTS' || typeUpper === 'IFCRELCONNECTSPATHELEMENTS') {
-        pos = skipCommas(buffer, pos, end, 1);
-        const [relating, rp2] = readRefId(buffer, pos, end);
-        pos = skipCommas(buffer, rp2, end, 1);
-        const [related, _] = readRefId(buffer, pos, end);
-        if (relating < 0 || related < 0)
-            return null;
-        return { relatingObject: relating, relatedObjects: [related] };
-    }
-    else {
-        // Default: attr[4]=RelatingObject, attr[5]=RelatedObject(s)
-        const [relating, rp] = readRefId(buffer, pos, end);
-        if (relating < 0)
-            return null;
-        pos = rp;
-        while (pos < end && buffer[pos] !== 0x2C)
-            pos++;
-        pos++;
-        const [related, _] = readRefList(buffer, pos, end);
-        if (related.length === 0)
-            return null;
-        return { relatingObject: relating, relatedObjects: related };
-    }
-}
-/**
- * Extract property rel data: attr[4]=relatedObjects, attr[5]=relatingDef.
- * Numbers only, no TextDecoder.
- */
-function extractPropertyRelFast(buffer, byteOffset, byteLength) {
-    const end = byteOffset + byteLength;
-    let pos = byteOffset;
-    while (pos < end && buffer[pos] !== 0x28)
-        pos++;
-    if (pos >= end)
-        return null;
-    pos++;
-    pos = skipCommas(buffer, pos, end, 4);
-    const [relatedObjects, rp] = readRefList(buffer, pos, end);
-    pos = rp;
-    while (pos < end && buffer[pos] !== 0x2C)
-        pos++;
-    pos++;
-    const [relatingDef, _] = readRefId(buffer, pos, end);
-    if (relatingDef < 0 || relatedObjects.length === 0)
-        return null;
-    return { relatedObjects, relatingDef };
-}
+import { batchExtractGlobalIdAndName } from './columnar-parser-attributes.js';
+import { GEOMETRY_TYPES, REL_TYPE_MAP, QUANTITY_TYPE_MAP, SPATIAL_TYPES, HIERARCHY_REL_TYPES, PROPERTY_REL_TYPES, ASSOCIATION_REL_TYPES, SKIP_DISPLAY_ATTRS, PROPERTY_ENTITY_TYPES, PROPERTY_CONTAINER_TYPES, isIfcTypeLikeEntity, } from './columnar-parser-indexes.js';
+import { extractRelFast, extractPropertyRelFast } from './columnar-parser-relationships.js';
 function detectSchemaVersion(buffer) {
     const headerEnd = Math.min(buffer.length, 2000);
     const headerText = new TextDecoder().decode(buffer.subarray(0, headerEnd)).toUpperCase();
@@ -413,6 +24,17 @@ function detectSchemaVersion(buffer) {
         return 'IFC2X3';
     return 'IFC4'; // Default fallback
 }
+function yieldToEventLoop() {
+    const maybeScheduler = globalThis.scheduler;
+    if (typeof maybeScheduler?.yield === 'function') {
+        return maybeScheduler.yield();
+    }
+    return new Promise((resolve) => {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => resolve();
+        channel.port2.postMessage(null);
+    });
+}
 export class ColumnarParser {
     /**
      * Parse IFC file into columnar data store
@@ -427,9 +49,14 @@ export class ColumnarParser {
         const totalEntities = entityRefs.length;
         // Phase timing for performance telemetry
         let phaseStart = startTime;
+        const emitDiagnostic = (message) => {
+            options.onDiagnostic?.(message);
+        };
         const logPhase = (name) => {
             const now = performance.now();
-            console.log(`[parseLite] ${name}: ${Math.round(now - phaseStart)}ms`);
+            const elapsed = Math.round(now - phaseStart);
+            console.log(`[parseLite] ${name}: ${elapsed}ms`);
+            emitDiagnostic(`${name}: ${elapsed}ms`);
             phaseStart = now;
         };
         options.onProgress?.({ phase: 'building', percent: 0 });
@@ -441,13 +68,20 @@ export class ColumnarParser {
         const quantityTableBuilder = new QuantityTableBuilder(strings);
         const relationshipGraphBuilder = new RelationshipGraphBuilder();
         logPhase('init builders');
-        // Build compact entity index (typed arrays instead of Map for ~3x memory reduction)
-        const compactByIdIndex = buildCompactEntityIndex(entityRefs);
-        logPhase('compact entity index');
         // Single pass: build byType index AND categorize entities simultaneously.
         // Uses a type-name cache to avoid calling .toUpperCase() on 4.4M refs
         // (only ~776 unique type names in IFC4).
         const byType = new Map();
+        const deferPropertyAtomIndex = options.deferPropertyAtomIndex === true;
+        const typeUpperCache = new Map();
+        const getTypeUpper = (type) => {
+            let upper = typeUpperCache.get(type);
+            if (upper === undefined) {
+                upper = type.toUpperCase();
+                typeUpperCache.set(type, upper);
+            }
+            return upper;
+        };
         const RELEVANT_ENTITY_PREFIXES = new Set([
             'IFCWALL', 'IFCSLAB', 'IFCBEAM', 'IFCCOLUMN', 'IFCPLATE', 'IFCDOOR', 'IFCWINDOW',
             'IFCROOF', 'IFCSTAIR', 'IFCRAILING', 'IFCRAMP', 'IFCFOOTING', 'IFCPILE',
@@ -455,6 +89,19 @@ export class ColumnarParser {
             'IFCFLOWSEGMENT', 'IFCFLOWTERMINAL', 'IFCFLOWCONTROLLER', 'IFCFLOWFITTING',
             'IFCSPACE', 'IFCOPENINGELEMENT', 'IFCSITE', 'IFCBUILDING', 'IFCBUILDINGSTOREY',
             'IFCPROJECT', 'IFCCOVERING', 'IFCANNOTATION', 'IFCGRID',
+            // Infrastructure entities needed by on-demand extraction and StepExporter.
+            // Without these, findPreferredGeometricRepresentationContextId() and
+            // findLengthUnitReference() fail because the entities are not in byId.
+            'IFCGEOMETRICREPRESENTATIONCONTEXT', 'IFCGEOMETRICREPRESENTATIONSUBCONTEXT',
+            'IFCUNITASSIGNMENT', 'IFCSIUNIT', 'IFCCONVERSIONBASEDUNIT',
+            'IFCDERIVEDUNIT', 'IFCDERIVEDUNITELEMENT', 'IFCMEASUREWITHUNIT',
+            'IFCDIMENSIONALEXPONENTS',
+            'IFCMAPCONVERSION', 'IFCPROJECTEDCRS',
+            'IFCMATERIALLAYER', 'IFCMATERIALLAYERSET', 'IFCMATERIALLAYERSETUSAGE',
+            'IFCMATERIALCONSTITUENTSET', 'IFCMATERIALCONSTITUENT',
+            'IFCMATERIALPROFILESET', 'IFCMATERIALPROFILE', 'IFCMATERIAL',
+            'IFCCLASSIFICATION', 'IFCCLASSIFICATIONREFERENCE',
+            'IFCDOCUMENTINFORMATION', 'IFCDOCUMENTREFERENCE',
         ]);
         // Category constants for the lookup cache
         const CAT_SKIP = 0, CAT_SPATIAL = 1, CAT_GEOMETRY = 2, CAT_HIERARCHY_REL = 3, CAT_PROPERTY_REL = 4, CAT_PROPERTY_ENTITY = 5, CAT_ASSOCIATION_REL = 6, CAT_TYPE_OBJECT = 7, CAT_RELEVANT = 8;
@@ -469,7 +116,7 @@ export class ColumnarParser {
             let cat = typeCategoryCache.get(type);
             if (cat !== undefined)
                 return cat;
-            const upper = type.toUpperCase();
+            const upper = getTypeUpper(type);
             if (SPATIAL_TYPES.has(upper) || isSubtypeOfAny(upper, SPATIAL_TYPES))
                 cat = CAT_SPATIAL;
             else if (GEOMETRY_TYPES.has(upper) || isSubtypeOfAny(upper, GEOMETRY_TYPES))
@@ -491,24 +138,48 @@ export class ColumnarParser {
             typeCategoryCache.set(type, cat);
             return cat;
         }
+        // Time-based yielding: yield to the main thread every ~80ms so geometry
+        // streaming callbacks can fire. This limits main-thread blocking to short
+        // bursts that don't starve geometry, while adding minimal overhead (~15 yields
+        // × ~1ms each ≈ 15ms total over the full parse).
+        const YIELD_INTERVAL_MS = Math.max(16, options.yieldIntervalMs ?? 80);
+        let lastYieldTime = performance.now();
+        const yieldIfNeeded = async () => {
+            const now = performance.now();
+            if (now - lastYieldTime >= YIELD_INTERVAL_MS) {
+                await yieldToEventLoop();
+                lastYieldTime = performance.now();
+            }
+        };
+        emitDiagnostic(`parseLite start: totalEntities=${totalEntities} yieldInterval=${YIELD_INTERVAL_MS}ms`);
         const spatialRefs = [];
         const geometryRefs = [];
         const relationshipRefs = [];
         const propertyRelRefs = [];
-        const propertyEntityRefs = [];
+        const propertyContainerRefs = [];
+        const propertyAtomRefs = [];
         const associationRelRefs = [];
         const typeObjectRefs = [];
         const otherRelevantRefs = [];
-        for (const ref of entityRefs) {
-            // Build byType index
-            let typeList = byType.get(ref.type);
-            if (!typeList) {
-                typeList = [];
-                byType.set(ref.type, typeList);
-            }
-            typeList.push(ref.expressId);
+        for (let i = 0; i < entityRefs.length; i++) {
+            if ((i & 0x3FF) === 0)
+                await yieldIfNeeded();
+            const ref = entityRefs[i];
             // Categorize (cached — .toUpperCase() called once per unique type)
             const cat = getCategory(ref.type);
+            const typeUpper = cat === CAT_PROPERTY_ENTITY ? getTypeUpper(ref.type) : '';
+            // ALL entities must be indexed in byType for on-demand extraction
+            // (e.g. IfcGeometricRepresentationContext, IfcSiUnit, IfcMaterialLayer).
+            // Only property atoms are optionally deferred for huge-file lazy loading.
+            const includeInPrimaryIndex = !deferPropertyAtomIndex || cat !== CAT_PROPERTY_ENTITY || PROPERTY_CONTAINER_TYPES.has(typeUpper);
+            if (includeInPrimaryIndex) {
+                let typeList = byType.get(ref.type);
+                if (!typeList) {
+                    typeList = [];
+                    byType.set(ref.type, typeList);
+                }
+                typeList.push(ref.expressId);
+            }
             if (cat === CAT_SPATIAL)
                 spatialRefs.push(ref);
             else if (cat === CAT_GEOMETRY)
@@ -517,8 +188,12 @@ export class ColumnarParser {
                 relationshipRefs.push(ref);
             else if (cat === CAT_PROPERTY_REL)
                 propertyRelRefs.push(ref);
-            else if (cat === CAT_PROPERTY_ENTITY)
-                propertyEntityRefs.push(ref);
+            else if (cat === CAT_PROPERTY_ENTITY) {
+                if (PROPERTY_CONTAINER_TYPES.has(typeUpper))
+                    propertyContainerRefs.push(ref);
+                else
+                    propertyAtomRefs.push(ref);
+            }
             else if (cat === CAT_ASSOCIATION_REL)
                 associationRelRefs.push(ref);
             else if (cat === CAT_TYPE_OBJECT)
@@ -526,7 +201,49 @@ export class ColumnarParser {
             else if (cat === CAT_RELEVANT)
                 otherRelevantRefs.push(ref);
         }
-        logPhase(`categorize ${totalEntities} → spatial:${spatialRefs.length} geom:${geometryRefs.length} rel:${relationshipRefs.length} propRel:${propertyRelRefs.length} assocRel:${associationRelRefs.length} type:${typeObjectRefs.length} other:${otherRelevantRefs.length}`);
+        logPhase(`categorize ${totalEntities} → spatial:${spatialRefs.length} geom:${geometryRefs.length} rel:${relationshipRefs.length} propRel:${propertyRelRefs.length} propContainers:${propertyContainerRefs.length} propAtoms:${propertyAtomRefs.length} assocRel:${associationRelRefs.length} type:${typeObjectRefs.length} other:${otherRelevantRefs.length}`);
+        // Pre-scan association rels to discover relatingRef target IDs (e.g.
+        // IfcClassificationReference, IfcMaterial, IfcDocumentReference).  These
+        // entities are typically categorised as CAT_SKIP and would otherwise be
+        // missing from the compact index, making on-demand extraction fail.
+        const associationTargetIds = new Set();
+        for (const ref of associationRelRefs) {
+            const result = extractPropertyRelFast(uint8Buffer, ref.byteOffset, ref.byteLength);
+            if (result)
+                associationTargetIds.add(result.relatingDef);
+        }
+        // Collect EntityRefs for association targets that aren't already categorised.
+        // Single O(n) pass over entityRefs filtered to the (small) target ID set.
+        const alreadyIndexedIds = new Set();
+        for (const arr of [spatialRefs, geometryRefs, relationshipRefs, propertyRelRefs,
+            propertyContainerRefs, associationRelRefs, typeObjectRefs, otherRelevantRefs,
+            ...(deferPropertyAtomIndex ? [] : [propertyAtomRefs])]) {
+            for (const r of arr)
+                alreadyIndexedIds.add(r.expressId);
+        }
+        const extraAssocRefs = [];
+        for (const ref of entityRefs) {
+            if (associationTargetIds.has(ref.expressId) && !alreadyIndexedIds.has(ref.expressId)) {
+                extraAssocRefs.push(ref);
+            }
+        }
+        logPhase(`association target pre-scan: ${associationTargetIds.size} targets, ${extraAssocRefs.length} extra refs`);
+        // ALL entity refs must be indexed in byId so that on-demand extraction
+        // can look up any entity by expressId (e.g. IfcUnitAssignment,
+        // IfcGeometricRepresentationContext, IfcSiUnit, IfcLocalPlacement, etc.).
+        // Only property atoms are optionally deferred for huge-file lazy loading.
+        const indexedRefs = deferPropertyAtomIndex
+            ? entityRefs.filter(ref => {
+                const cat = getCategory(ref.type);
+                return cat !== CAT_PROPERTY_ENTITY || PROPERTY_CONTAINER_TYPES.has(getTypeUpper(ref.type));
+            })
+            : entityRefs;
+        emitDiagnostic(`index input: indexedRefs=${indexedRefs.length} deferredPropertyAtoms=${deferPropertyAtomIndex ? propertyAtomRefs.length : 0} extraAssocTargets=${extraAssocRefs.length}`);
+        // Build compact entity index from only the refs that survive lite parsing.
+        // This avoids spending huge-file startup time indexing millions of skipped
+        // representation/helper entities that the viewer never queries.
+        const compactByIdIndex = await buildCompactEntityIndexAsync(indexedRefs);
+        logPhase('compact entity index');
         // Create entity table builder with EXACT capacity (not totalEntities which
         // includes millions of geometry-representation entities we don't store).
         // For a 14M entity file, this reduces allocation from ~546MB to ~20MB.
@@ -537,19 +254,6 @@ export class ColumnarParser {
             byId: compactByIdIndex,
             byType,
         };
-        // Time-based yielding: yield to the main thread every ~80ms so geometry
-        // streaming callbacks can fire. This limits main-thread blocking to short
-        // bursts that don't starve geometry, while adding minimal overhead (~15 yields
-        // × ~1ms each ≈ 15ms total over the full parse).
-        const YIELD_INTERVAL_MS = 80;
-        let lastYieldTime = performance.now();
-        const yieldIfNeeded = async () => {
-            const now = performance.now();
-            if (now - lastYieldTime >= YIELD_INTERVAL_MS) {
-                await new Promise(resolve => setTimeout(resolve, 0));
-                lastYieldTime = performance.now();
-            }
-        };
         // === TARGETED PARSING using batch byte-level extraction ===
         // Uses 2 TextDecoder.decode() calls total for ALL entity GlobalIds/Names
         // (instead of per-entity calls), and pure byte scanning for relationships.
@@ -571,28 +275,21 @@ export class ColumnarParser {
         await yieldIfNeeded();
         // Geometry + type object entities: batch extract GlobalId+Name with 2 TextDecoder calls
         options.onProgress?.({ phase: 'parsing geometry names', percent: 12 });
-        const geomData = batchExtractGlobalIdAndName(uint8Buffer, geometryRefs);
+        const geomData = await batchExtractGlobalIdAndName(uint8Buffer, geometryRefs, yieldIfNeeded);
         for (const [id, data] of geomData)
             parsedEntityData.set(id, data);
         await yieldIfNeeded();
-        const typeData = batchExtractGlobalIdAndName(uint8Buffer, typeObjectRefs);
+        const typeData = await batchExtractGlobalIdAndName(uint8Buffer, typeObjectRefs, yieldIfNeeded);
         for (const [id, data] of typeData)
             parsedEntityData.set(id, data);
         logPhase('batch geom GlobalId+Name');
         await yieldIfNeeded();
         // Relationships: byte-level scanning (numbers only, no TextDecoder)
         options.onProgress?.({ phase: 'parsing relationships', percent: 20 });
-        // Use a toUpperCase cache across relationship refs (same type name set)
-        const typeUpperCache = new Map();
-        const getTypeUpper = (type) => {
-            let u = typeUpperCache.get(type);
-            if (u === undefined) {
-                u = type.toUpperCase();
-                typeUpperCache.set(type, u);
-            }
-            return u;
-        };
-        for (const ref of relationshipRefs) {
+        for (let i = 0; i < relationshipRefs.length; i++) {
+            if ((i & 0x3FF) === 0)
+                await yieldIfNeeded();
+            const ref = relationshipRefs[i];
             const typeUpper = getTypeUpper(ref.type);
             const rel = extractRelFast(uint8Buffer, ref.byteOffset, ref.byteLength, typeUpper);
             if (rel) {
@@ -677,7 +374,7 @@ export class ColumnarParser {
         // This replaces 252K binary searches on the 14M compact entity index with O(1) Set lookups.
         const propertySetIds = new Set();
         const quantitySetIds = new Set();
-        for (const ref of propertyEntityRefs) {
+        for (const ref of propertyContainerRefs) {
             const tu = getTypeUpper(ref.type);
             if (tu === 'IFCPROPERTYSET')
                 propertySetIds.add(ref.expressId);
@@ -713,14 +410,16 @@ export class ColumnarParser {
                 }
             }
         }
-        console.log(`[parseLite] propertyRels: ${propertyRelRefs.length} rels, ${totalPropRelObjects} total relatedObjects`);
         await yieldIfNeeded();
         // Association rels: byte-level scanning, no addEdge (same reasoning as property rels)
         options.onProgress?.({ phase: 'parsing associations', percent: 95 });
         const onDemandClassificationMap = new Map();
         const onDemandMaterialMap = new Map();
         const onDemandDocumentMap = new Map();
-        for (const ref of associationRelRefs) {
+        for (let i = 0; i < associationRelRefs.length; i++) {
+            if ((i & 0x3FF) === 0)
+                await yieldIfNeeded();
+            const ref = associationRelRefs[i];
             const result = extractPropertyRelFast(uint8Buffer, ref.byteOffset, ref.byteLength);
             if (result) {
                 const { relatedObjects, relatingDef: relatingRef } = result;
@@ -759,12 +458,19 @@ export class ColumnarParser {
         // Rebuild relationship graph with ALL edges (hierarchy + property + association)
         const fullRelationshipGraph = relationshipGraphBuilder.build();
         logPhase('relationship graph build()');
+        let deferredEntityIndex;
+        if (deferPropertyAtomIndex && propertyAtomRefs.length > 0) {
+            options.onProgress?.({ phase: 'indexing property atoms', percent: 98 });
+            deferredEntityIndex = await buildCompactEntityIndexAsync(propertyAtomRefs, undefined, 1024, 2);
+            logPhase('deferred property atom index');
+        }
         const parseTime = performance.now() - startTime;
         options.onProgress?.({ phase: 'complete', percent: 100 });
         return {
             ...earlyStore,
             parseTime,
             relationships: fullRelationshipGraph,
+            deferredEntityIndex,
             onDemandPropertyMap,
             onDemandQuantityMap,
             onDemandClassificationMap,
@@ -778,7 +484,7 @@ export class ColumnarParser {
      */
     extractPropertiesOnDemand(store, entityId) {
         // Use on-demand extraction if map is available (preferred for single-entity access)
-        if (!store.onDemandPropertyMap) {
+        if (!store.onDemandPropertyMap || !store.source?.length) {
             // Fallback to pre-computed property table (e.g., server-parsed data)
             return store.properties.getForEntity(entityId);
         }
@@ -789,7 +495,7 @@ export class ColumnarParser {
         const extractor = new EntityExtractor(store.source);
         const result = [];
         for (const psetId of psetIds) {
-            const psetRef = store.entityIndex.byId.get(psetId);
+            const psetRef = getEntityRefFromStore(store, psetId);
             if (!psetRef)
                 continue;
             const psetEntity = extractor.extractEntity(psetRef);
@@ -804,7 +510,7 @@ export class ColumnarParser {
                 for (const propRef of hasProperties) {
                     if (typeof propRef !== 'number')
                         continue;
-                    const propEntityRef = store.entityIndex.byId.get(propRef);
+                    const propEntityRef = getEntityRefFromStore(store, propRef);
                     if (!propEntityRef)
                         continue;
                     const propEntity = extractor.extractEntity(propEntityRef);
@@ -830,7 +536,7 @@ export class ColumnarParser {
      */
     extractQuantitiesOnDemand(store, entityId) {
         // Use on-demand extraction if map is available (preferred for single-entity access)
-        if (!store.onDemandQuantityMap) {
+        if (!store.onDemandQuantityMap || !store.source?.length) {
             // Fallback to pre-computed quantity table (e.g., server-parsed data)
             return store.quantities.getForEntity(entityId);
         }
@@ -841,7 +547,7 @@ export class ColumnarParser {
         const extractor = new EntityExtractor(store.source);
         const result = [];
         for (const qsetId of qsetIds) {
-            const qsetRef = store.entityIndex.byId.get(qsetId);
+            const qsetRef = getEntityRefFromStore(store, qsetId);
             if (!qsetRef)
                 continue;
             const qsetEntity = extractor.extractEntity(qsetRef);
@@ -855,7 +561,7 @@ export class ColumnarParser {
                 for (const qtyRef of hasQuantities) {
                     if (typeof qtyRef !== 'number')
                         continue;
-                    const qtyEntityRef = store.entityIndex.byId.get(qtyRef);
+                    const qtyEntityRef = getEntityRefFromStore(store, qtyRef);
                     if (!qtyEntityRef)
                         continue;
                     const qtyEntity = extractor.extractEntity(qtyEntityRef);
@@ -896,6 +602,9 @@ export function extractQuantitiesOnDemand(store, entityId) {
     const parser = new ColumnarParser();
     return parser.extractQuantitiesOnDemand(store, entityId);
 }
+function getEntityRefFromStore(store, expressId) {
+    return store.entityIndex.byId.get(expressId) ?? store.deferredEntityIndex?.get(expressId);
+}
 /**
  * Extract entity attributes on-demand from source buffer
  * Returns globalId, name, description, objectType, tag for any IfcRoot-derived entity.