@bldrs-ai/conway 1.389.1221 → 1.394.1504

package/compiled/src/compat/web-ifc/spatial_imposter.test.d.ts

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

package/compiled/src/compat/web-ifc/spatial_imposter.test.d.ts.map

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

package/compiled/src/compat/web-ifc/spatial_imposter.test.js

@@ -0,0 +1,467 @@
+/* eslint-disable no-magic-numbers */
+import * as fs from "fs";
+import { describe, expect, test } from "@jest/globals";
+import { openStreamedIfcModelFromStore } from "../../ifc/ifc_stream_open.js";
+import { InMemoryStepByteStore } from "../../step/step_buffer_provider.js";
+import EntityTypesIfc from "../../ifc/ifc4_gen/entity_types_ifc.gen.js";
+import { deriveCoordinationF64, mat4MultiplyF64, NORMALIZE_MAT_F64, } from "./coordination_f64.js";
+import { aabbBoxMatrix, aabbMostlyEqual, emitSpatialStructureImposters, shouldEmitSpatialNode, spatialImposterDepthCap, SPATIAL_IMPOSTER_COLOR, unionAabb, } from "./spatial_imposter.js";
+/**
+ * The axes an IfcAxis2Placement3D needs to state a rotation, as
+ * `[Axis (local +Z), RefDirection (local +X)]`.
+ *
+ * @param rotation The fixture's rotation knob.
+ * @return {PlacementAxes | undefined} The two direction ratios, or
+ * undefined for no rotation.
+ */
+function rotationAxes(rotation) {
+    if (rotation === void 0) {
+        return;
+    }
+    const radians = rotation.degrees * Math.PI / 180;
+    const cos = Math.cos(radians);
+    const sin = Math.sin(radians);
+    // Columns of the rotation matrix: Axis is its third (local +Z),
+    // RefDirection its first (local +X).
+    return rotation.axis === "z" ?
+        [[0, 0, 1], [cos, sin, 0]] :
+        [[0, -sin, cos], [1, 0, 0]];
+}
+/**
+ * Transform a point by the fixture's site rotation — what the composed
+ * placement chain must reproduce.
+ *
+ * @param rotation The fixture's rotation knob.
+ * @param point A point in the site's local frame.
+ * @return {[number, number, number]} The rotated point.
+ */
+function rotatePoint(rotation, point) {
+    if (rotation === void 0) {
+        return point;
+    }
+    const radians = rotation.degrees * Math.PI / 180;
+    const cos = Math.cos(radians);
+    const sin = Math.sin(radians);
+    const [x, y, z] = point;
+    return rotation.axis === "z" ?
+        [x * cos - y * sin, x * sin + y * cos, z] :
+        [x, y * cos - z * sin, y * sin + z * cos];
+}
+/**
+ * A minimal but schema-valid IFC4 spatial structure —
+ * Project/Site/Building/2 Storeys, two placed walls contained in each
+ * storey — with every placement and elevation a caller-chosen number.
+ * Carries no units and no geometry: the imposter walk reads placement
+ * chains only, and takes its scaling factor as an argument.
+ *
+ * @param fixture Placement/elevation knobs.
+ * @return {Uint8Array} The file bytes.
+ */
+function syntheticSpatialIfc(fixture) {
+    const lines = [];
+    let next = 1;
+    const push = (body) => {
+        const id = next++;
+        lines.push(`#${id}=${body};`);
+        return id;
+    };
+    const num = (value) => value.toFixed(4);
+    const guid = (seed) => `3vB2${String(seed).padStart(18, "0")}`;
+    // Direction ratios get more decimals than `num`'s four: they are
+    // trigonometric, and rounding cos(30 deg) at four places moves a
+    // sampled origin by ~1e-4 source units — enough to break assertions
+    // that compare a composed plate against the same rotation applied in
+    // double precision.
+    const direction = (ratios) => push(`IFCDIRECTION((${ratios.map((r) => r.toFixed(12)).join(",")}))`);
+    const ref = (ratios) => ratios !== void 0 ? `#${direction(ratios)}` : "$";
+    const placement = (relTo, x, y, z, axes, twoDimensional = false) => {
+        // A 2D placement's Location is a 2D point, and its only direction
+        // field is RefDirection — there is no Axis to state.
+        const point = twoDimensional ?
+            push(`IFCCARTESIANPOINT((${num(x)},${num(y)}))`) :
+            push(`IFCCARTESIANPOINT((${num(x)},${num(y)},${num(z)}))`);
+        const axis = twoDimensional ?
+            push(`IFCAXIS2PLACEMENT2D(#${point},$)`) :
+            push(`IFCAXIS2PLACEMENT3D(#${point},` +
+                `${ref(axes?.[0])},${ref(axes?.[1])})`);
+        return push(`IFCLOCALPLACEMENT(${relTo === void 0 ? "$" : `#${relTo}`},#${axis})`);
+    };
+    const sitePlacement = placement(void 0, ...fixture.siteOrigin, fixture.siteAxes ?? rotationAxes(fixture.siteRotation), fixture.sitePlacement2D === true);
+    const buildingPlacement = placement(sitePlacement, 0, 0, fixture.buildingZ);
+    const project = push(`IFCPROJECT('${guid(1)}',$,'P',$,$,$,$,$,$)`);
+    const site = push(`IFCSITE('${guid(2)}',$,'S',$,$,#${sitePlacement},$,$,.ELEMENT.,$,$,$,$,$)`);
+    const building = push(`IFCBUILDING('${guid(3)}',$,'B',$,$,#${buildingPlacement},$,$,.ELEMENT.,$,$,$)`);
+    const storeys = fixture.storeyElevations.map((elevation, index) => {
+        // Under the default the storey's own placement carries the same
+        // offset from the building datum that Elevation states — the
+        // ordinary authoring — so the two only disagree once the BUILDING is
+        // off world zero. Under 'datum' the placement says nothing and
+        // Elevation is the only record of the height.
+        const storeyPlacement = placement(buildingPlacement, 0, 0, fixture.storeyPlacementZ === "datum" ? 0 : elevation);
+        return push(`IFCBUILDINGSTOREY('${guid(10 + index)}',$,'L${index}',$,$,` +
+            `#${storeyPlacement},$,$,.ELEMENT.,${num(elevation)})`);
+    });
+    push(`IFCRELAGGREGATES('${guid(20)}',$,$,$,#${project},(#${site}))`);
+    push(`IFCRELAGGREGATES('${guid(21)}',$,$,$,#${site},(#${building}))`);
+    push(`IFCRELAGGREGATES('${guid(22)}',$,$,$,#${building},` +
+        `(${storeys.map((id) => `#${id}`).join(",")}))`);
+    storeys.forEach((storey, index) => {
+        const storeyPlacement = storey - 1;
+        // Whatever the storey placement does not say about the height, the
+        // contained walls have to say themselves — otherwise every storey's
+        // contents would pile up at the building datum, which is not a file
+        // any exporter produces.
+        const wallZ = fixture.storeyPlacementZ === "datum" ?
+            fixture.storeyElevations[index] : 0;
+        const wallA = push(`IFCWALL('${guid(30 + index * 2)}',$,$,$,$,` +
+            `#${placement(storeyPlacement, 0, 0, wallZ)},$,$,$)`);
+        const wallB = push(`IFCWALL('${guid(31 + index * 2)}',$,$,$,$,` +
+            `#${placement(storeyPlacement, ...fixture.wallOffset, wallZ)},$,$,$)`);
+        push(`IFCRELCONTAINEDINSPATIALSTRUCTURE('${guid(40 + index)}',$,$,$,` +
+            `(#${wallA},#${wallB}),#${storey})`);
+    });
+    const text = "ISO-10303-21;\n" +
+        "HEADER;\n" +
+        "FILE_DESCRIPTION((''),'2;1');\n" +
+        "FILE_NAME('synthetic.ifc','2026-01-01T00:00:00',(''),(''),'','','');\n" +
+        "FILE_SCHEMA(('IFC4'));\n" +
+        "ENDSEC;\n" +
+        "DATA;\n" +
+        `${lines.join("\n")}\n` +
+        "ENDSEC;\n" +
+        "END-ISO-10303-21;\n";
+    return new TextEncoder().encode(text);
+}
+/**
+ * Emit imposters for a synthetic fixture.
+ *
+ * @param fixture Placement/elevation knobs.
+ * @param linearScalingFactor Source units -> metres.
+ * @param coordinationMatrix Latched preview frame, or undefined to
+ * exercise the walk's own fallback derivation.
+ * @return {Promise<[PreviewMeshPayload[], IfcStepModel]>} Payloads and model.
+ */
+async function emitForFixture(fixture, linearScalingFactor, coordinationMatrix) {
+    const open = await openStreamedIfcModelFromStore(new InMemoryStepByteStore(syntheticSpatialIfc(fixture)), { pool: 4 * 1024 });
+    expect(open.model).toBeDefined();
+    const payloads = [];
+    await emitSpatialStructureImposters(open.model, (mesh) => payloads.push(mesh), coordinationMatrix, linearScalingFactor);
+    expect(payloads.length).toBeGreaterThan(0);
+    return [payloads, open.model];
+}
+/**
+ * @param payloads Emitted imposters.
+ * @param model The model they came from.
+ * @return {PreviewMeshPayload[]} Only the IfcBuildingStorey plates,
+ * ordered bottom-up.
+ */
+function storeyPlates(payloads, model) {
+    return payloads
+        .filter((payload) => model.typeIDOf(model.resolveExpressID(payload.expressID)) ===
+        EntityTypesIfc.IFCBUILDINGSTOREY)
+        .sort((a, b) => a.aabb.min[2] - b.aabb.min[2]);
+}
+/**
+ * @param actual A 16-element matrix.
+ * @param expected A 16-element matrix.
+ * @param digits Decimal places (jest's toBeCloseTo semantics).
+ */
+function expectMatrixClose(actual, expected, digits = 6) {
+    expect(actual).toHaveLength(16);
+    for (let where = 0; where < 16; ++where) {
+        expect(actual[where]).toBeCloseTo(expected[where], digits);
+    }
+}
+describe("spatial_imposter policy", () => {
+    test("depth cap is half the tree, rounded up", () => {
+        expect(spatialImposterDepthCap(0)).toBe(0);
+        expect(spatialImposterDepthCap(1)).toBe(1);
+        expect(spatialImposterDepthCap(4)).toBe(2);
+        expect(spatialImposterDepthCap(5)).toBe(3);
+    });
+    test("never emits spaces; always emits storeys; half-depth otherwise", () => {
+        expect(shouldEmitSpatialNode(4, 4, EntityTypesIfc.IFCSPACE)).toBe(false);
+        expect(shouldEmitSpatialNode(3, 4, EntityTypesIfc.IFCBUILDINGSTOREY)).toBe(true);
+        expect(shouldEmitSpatialNode(2, 4, EntityTypesIfc.IFCBUILDING)).toBe(true);
+        expect(shouldEmitSpatialNode(3, 4, EntityTypesIfc.IFCBUILDING)).toBe(false);
+        expect(shouldEmitSpatialNode(0, 4, EntityTypesIfc.IFCPROJECT)).toBe(true);
+    });
+    test("unionAabb and aabbMostlyEqual", () => {
+        const a = { min: [0, 0, 0], max: [10, 10, 4] };
+        const b = { min: [8, 8, 0], max: [12, 12, 4] };
+        const u = unionAabb(a, b);
+        expect(u.min).toEqual([0, 0, 0]);
+        expect(u.max).toEqual([12, 12, 4]);
+        expect(aabbMostlyEqual(a, a)).toBe(true);
+        expect(aabbMostlyEqual(a, b)).toBe(false);
+    });
+    test("imposter colour is black at 0.3 opacity", () => {
+        expect(SPATIAL_IMPOSTER_COLOR).toEqual({ x: 0, y: 0, z: 0, w: 0.3 });
+    });
+    test("aabbBoxMatrix stays in raw IFC space \u2014 no axis flip", () => {
+        const matrix = aabbBoxMatrix({ min: [0, 0, 0], max: [2, 4, 6] });
+        // translate(centre) * scale(size), column-major, Z-up preserved.
+        expect(matrix).toEqual([
+            2,
+            0,
+            0,
+            0,
+            0,
+            4,
+            0,
+            0,
+            0,
+            0,
+            6,
+            0,
+            1,
+            2,
+            3,
+            1,
+        ]);
+    });
+});
+describe("emitSpatialStructureImposters", () => {
+    test("index.ifc emits storey-scale wireframe boxes, not spaces", async () => {
+        const bytes = new Uint8Array(fs.readFileSync("data/index.ifc"));
+        const open = await openStreamedIfcModelFromStore(new InMemoryStepByteStore(bytes), { pool: 4 * 1024 });
+        const payloads = [];
+        const emitted = await emitSpatialStructureImposters(open.model, (mesh) => payloads.push(mesh));
+        expect(emitted).toBeGreaterThan(0);
+        expect(payloads).toHaveLength(emitted);
+        for (const payload of payloads) {
+            // Wireframe by request — `solid` stays in the payload contract but
+            // nothing sets it any more.
+            expect(payload.solid).toBeUndefined();
+            expect("solid" in payload).toBe(false);
+            expect(payload.aabb).toBeDefined();
+            expect(payload.geometryExpressID).toBe(-1);
+            expect(payload.color).toEqual(SPATIAL_IMPOSTER_COLOR);
+            expect(payload.flatTransformation).toHaveLength(16);
+        }
+        const types = new Set(payloads.map((p) => open.model.typeIDOf(open.model.resolveExpressID(p.expressID))));
+        expect(types.has(EntityTypesIfc.IFCSPACE)).toBe(false);
+    });
+});
+// conway#515: the plates used to be emitted in raw source units with a
+// locally baked Z-up -> Y-up flip and no coordination at all, so on a
+// millimetre model they came out 1000x oversized and on a georeferenced
+// one they sat a site-offset away from the meshes they were previewing.
+describe("emitSpatialStructureImposters coordination frame", () => {
+    /** Millimetres, 50km east / 30km north — well past the recentre budget. */
+    const MILLIMETRE_GEOREFERENCED = {
+        siteOrigin: [50000000, 30000000, 0],
+        buildingZ: 0,
+        storeyElevations: [0, 3000],
+        wallOffset: [8000, 6000],
+    };
+    const MM_TO_M = 0.001;
+    test("millimetre georeferenced plates compose under the latched frame", async () => {
+        // What the preview channel latches from a first geometry sitting on
+        // the site origin: identity placement, that point as the anchor.
+        const coordination = deriveCoordinationF64(void 0, { x: 50000000, y: 30000000, z: 0 }, NORMALIZE_MAT_F64, MM_TO_M);
+        const [payloads] = await emitForFixture(MILLIMETRE_GEOREFERENCED, MM_TO_M, coordination);
+        for (const payload of payloads) {
+            expectMatrixClose(payload.flatTransformation, mat4MultiplyF64(coordination, aabbBoxMatrix(payload.aabb)));
+            // In metres and near the origin, not 5e7 source units out.
+            expect(Math.abs(payload.flatTransformation[12])).toBeLessThan(100);
+            expect(Math.abs(payload.flatTransformation[13])).toBeLessThan(100);
+            expect(Math.abs(payload.flatTransformation[14])).toBeLessThan(100);
+            // Scale columns are metres too — the mm-oversize bug put these at
+            // 8000 x 6000 rather than 8 x 6.
+            for (let column = 0; column < 3; ++column) {
+                expect(Math.hypot(payload.flatTransformation[column * 4], payload.flatTransformation[column * 4 + 1], payload.flatTransformation[column * 4 + 2])).toBeLessThan(100);
+            }
+            // The reported box stays in raw IFC space for the consumer.
+            expect(payload.aabb.min[0]).toBeGreaterThan(10000000);
+        }
+    });
+    test("no latched frame: the fallback derivation recentres the same way", async () => {
+        const [payloads] = await emitForFixture(MILLIMETRE_GEOREFERENCED, MM_TO_M);
+        // Anchored on the spatial root's centre rather than a first
+        // geometry, but the same quantized policy: the 1km grid (1e6 source
+        // units here) puts the model back within a cell of the origin.
+        for (const payload of payloads) {
+            expect(Math.hypot(payload.flatTransformation[12], payload.flatTransformation[13], payload.flatTransformation[14])).toBeLessThan(1000);
+        }
+    });
+    test("near-origin metres model is not recentred (model-zero policy)", async () => {
+        const [payloads] = await emitForFixture({
+            siteOrigin: [10, 20, 0],
+            buildingZ: 0,
+            storeyElevations: [0, 3.5],
+            wallOffset: [8, 6],
+        }, 1);
+        for (const payload of payloads) {
+            // Inside LARGE_COORDINATE_BUDGET_M the policy recentres nothing,
+            // so the whole frame collapses to the Z-up -> Y-up normalize —
+            // which is exactly where the durable walk would put these.
+            expectMatrixClose(payload.flatTransformation, mat4MultiplyF64(NORMALIZE_MAT_F64, aabbBoxMatrix(payload.aabb)));
+            const centreX = (payload.aabb.min[0] + payload.aabb.max[0]) * 0.5;
+            expect(payload.flatTransformation[12]).toBeCloseTo(centreX, 9);
+        }
+    });
+    test("storey plates band on the building datum, not on bare elevation", async () => {
+        // Building datum 100m above world zero: Elevation says 0 and
+        // 3.5, but the plates belong at 100 and 103.5.
+        const [payloads, model] = await emitForFixture({
+            siteOrigin: [0, 0, 0],
+            buildingZ: 100,
+            storeyElevations: [0, 3.5],
+            wallOffset: [8, 6],
+        }, 1);
+        const plates = storeyPlates(payloads, model);
+        expect(plates).toHaveLength(2);
+        // Lower storey: floor at the placement, ceiling at the next
+        // storey's elevation delta above it.
+        expect(plates[0].aabb.min[2]).toBeCloseTo(100, 6);
+        expect(plates[0].aabb.max[2]).toBeCloseTo(103.5, 6);
+        // Upper storey: no next elevation, so MIN_EDGE thick.
+        expect(plates[1].aabb.min[2]).toBeCloseTo(103.5, 6);
+        expect(plates[1].aabb.max[2]).toBeCloseTo(104.5, 6);
+    });
+    test("storey plates keep their spacing when only Elevation states it", async () => {
+        // Every storey placement parked on the building datum, so the
+        // placement chain reports the same Z for both and Elevation is
+        // the only thing that separates them. Reading placement Z
+        // INSTEAD of elevation stacks both plates on 100; reading it as
+        // the datum elevation is measured from keeps them apart.
+        const [payloads, model] = await emitForFixture({
+            siteOrigin: [0, 0, 0],
+            buildingZ: 100,
+            storeyElevations: [0, 3.5],
+            wallOffset: [8, 6],
+            storeyPlacementZ: "datum",
+        }, 1);
+        const plates = storeyPlates(payloads, model);
+        expect(plates).toHaveLength(2);
+        expect(plates[0].aabb.min[2]).toBeCloseTo(100, 6);
+        expect(plates[1].aabb.min[2]).toBeCloseTo(103.5, 6);
+    });
+    // conway#517: the placement chain used to SUM Location translations
+    // and ignore rotation outright, so on a Revit export rotated to true
+    // north every sampled origin landed unrotated in raw model space while
+    // the durable meshes did not — the plate cloud read as a rotated ghost
+    // of the building. Both fixtures below fail against that composition.
+    describe("rotation-aware placement composition", () => {
+        /** Site rotated 30 deg about Z — Revit's true-north plan rotation. */
+        const ROTATED_SITE = {
+            siteOrigin: [0, 0, 0],
+            buildingZ: 0,
+            storeyElevations: [0, 3.5],
+            wallOffset: [8, 6],
+            siteRotation: { axis: "z", degrees: 30 },
+        };
+        /** Site tipped 30 deg about X, with the building datum 100 up. */
+        const TILTED_SITE = {
+            siteOrigin: [0, 0, 0],
+            buildingZ: 100,
+            storeyElevations: [0, 3.5],
+            wallOffset: [8, 6],
+            siteRotation: { axis: "x", degrees: 30 },
+        };
+        test("plan rotation: plate XY is the AABB of the ROTATED samples", async () => {
+            const [payloads, model] = await emitForFixture(ROTATED_SITE, 1);
+            const plates = storeyPlates(payloads, model);
+            expect(plates).toHaveLength(2);
+            // The two walls each storey contains, composed through the
+            // rotated site placement.
+            const cornerA = rotatePoint(ROTATED_SITE.siteRotation, [0, 0, 0]);
+            const cornerB = rotatePoint(ROTATED_SITE.siteRotation, [...ROTATED_SITE.wallOffset, 0]);
+            for (const plate of plates) {
+                expect(plate.aabb.min[0])
+                    .toBeCloseTo(Math.min(cornerA[0], cornerB[0]), 6);
+                expect(plate.aabb.max[0])
+                    .toBeCloseTo(Math.max(cornerA[0], cornerB[0]), 6);
+                expect(plate.aabb.min[1])
+                    .toBeCloseTo(Math.min(cornerA[1], cornerB[1]), 6);
+                expect(plate.aabb.max[1])
+                    .toBeCloseTo(Math.max(cornerA[1], cornerB[1]), 6);
+            }
+            // And specifically NOT the unrotated offset the translation-sum
+            // implementation produced: 6 m north instead of 9.2 m.
+            expect(plates[0].aabb.max[1])
+                .not.toBeCloseTo(ROTATED_SITE.wallOffset[1], 3);
+        });
+        test("tilt about X: storey floors band on the DATUM's world Z", async () => {
+            const [payloads, model] = await emitForFixture(TILTED_SITE, 1);
+            const plates = storeyPlates(payloads, model);
+            expect(plates).toHaveLength(2);
+            const rotation = TILTED_SITE.siteRotation;
+            const floorA = rotatePoint(rotation, [0, 0, 100]);
+            const floorB = rotatePoint(rotation, [...TILTED_SITE.wallOffset, 100]);
+            // Elevation is a length along the datum's own +Z, so a tilted
+            // datum puts the floor at cos(30) * the elevation, not at it.
+            expect(plates[0].aabb.min[2]).toBeCloseTo(floorA[2], 6);
+            expect(plates[1].aabb.min[2])
+                .toBeCloseTo(rotatePoint(rotation, [0, 0, 103.5])[2], 6);
+            // A Z-only fixture leaves the third matrix column at the
+            // identity; this one does not, so an Axis/RefDirection mixup
+            // shows up as Y bounds that never left zero.
+            expect(plates[0].aabb.min[1])
+                .toBeCloseTo(Math.min(floorA[1], floorB[1]), 6);
+            expect(plates[0].aabb.max[1])
+                .toBeCloseTo(Math.max(floorA[1], floorB[1]), 6);
+            // The translation-sum implementation put both floors at the
+            // bare elevations, 100 and 103.5.
+            expect(plates[0].aabb.min[2]).not.toBeCloseTo(100, 3);
+            expect(plates[1].aabb.min[2]).not.toBeCloseTo(103.5, 3);
+        });
+        test("an Axis with no RefDirection still yields a frame", async () => {
+            // Axis = world +X with RefDirection omitted: the IFC default
+            // RefDirection (1,0,0) is parallel to it, so a naive build finds a
+            // zero cross product. Falling all the way back to world axes there
+            // discards a perfectly good rotation; IFC's IfcFirstProjAxis
+            // substitutes a perpendicular reference instead, which sends local
+            // (a,b,c) to world (c,a,b).
+            const [payloads, model] = await emitForFixture({
+                siteOrigin: [0, 0, 0],
+                buildingZ: 0,
+                storeyElevations: [0, 3.5],
+                wallOffset: [8, 6],
+                siteAxes: [[1, 0, 0], void 0],
+            }, 1);
+            const plates = storeyPlates(payloads, model);
+            expect(plates).toHaveLength(2);
+            // Lower storey's walls: local (0,0,0) and (8,6,0) -> (0,0,0) and
+            // (0,8,6). X collapses, so the plate is MIN_EDGE thick about
+            // zero there; the identity fallback would have spanned 0..8.
+            const plate = plates[0].aabb;
+            expect((plate.min[0] + plate.max[0]) * 0.5).toBeCloseTo(0, 6);
+            expect(plate.max[0] - plate.min[0]).toBeCloseTo(1, 6);
+            expect(plate.max[1]).toBeCloseTo(8, 6);
+            expect(plate.max[2]).toBeCloseTo(6, 6);
+        });
+        test("a 2D relative placement does not break the chain", async () => {
+            // IfcLocalPlacement.RelativePlacement admits IfcAxis2Placement2D,
+            // whose field 1 is RefDirection (not Axis) and which has no field
+            // 2 at all. Reading the 3D direction fields unconditionally throws
+            // "too few fields in record"; that throw memoizes an undefined
+            // placement, and every DESCENDANT then composes in local
+            // coordinates — the site translation below silently disappears.
+            const [payloads, model] = await emitForFixture({
+                siteOrigin: [10, 20, 0],
+                buildingZ: 100,
+                storeyElevations: [0, 3.5],
+                wallOffset: [8, 6],
+                sitePlacement2D: true,
+            }, 1);
+            const plates = storeyPlates(payloads, model);
+            expect(plates).toHaveLength(2);
+            // The site's XY still reaches the storeys...
+            expect(plates[0].aabb.min[0]).toBeCloseTo(10, 6);
+            expect(plates[0].aabb.max[0]).toBeCloseTo(18, 6);
+            expect(plates[0].aabb.min[1]).toBeCloseTo(20, 6);
+            expect(plates[0].aabb.max[1]).toBeCloseTo(26, 6);
+            // ...and so does the building datum the elevations band on.
+            expect(plates[0].aabb.min[2]).toBeCloseTo(100, 6);
+            expect(plates[1].aabb.min[2]).toBeCloseTo(103.5, 6);
+        });
+    });
+    test("nothing emits `solid`", async () => {
+        const [payloads] = await emitForFixture(MILLIMETRE_GEOREFERENCED, MM_TO_M);
+        for (const payload of payloads) {
+            expect("solid" in payload).toBe(false);
+        }
+    });
+});

package/compiled/src/compat/web-ifc/store_preview_channel.d.ts

@@ -0,0 +1,187 @@
+import { ConwayGeometry } from "../../index.js";
+import { ColumnarIndexSink } from "../../step/parsing/columnar_index.js";
+import type { StepExternalByteStore } from "../../step/step_buffer_provider.js";
+import { PreviewMeshPayload } from "./streamed_preview_channel.js";
+/**
+ * Parse-time placed-mesh preview for a windowed (store-backed) open.
+ *
+ * Twin of {@link StreamedPreviewChannel}: same capture math and
+ * COORDINATE_TO_ORIGIN frame, same time-budgeted tick, but the prefix
+ * model pages product closures from `store` instead of a resident
+ * buffer. After each product the pins drop, so peak source residency
+ * stays the windowed LRU — not the file.
+ *
+ * It also runs the spatial-structure walk off its own prefix
+ * generations, so the building's skeleton goes up in the first seconds
+ * of a long parse rather than after it — see
+ * {@link maybeEmitEarlySpatialPlates_}.
+ */
+export declare class StorePreviewChannel {
+    private readonly store_;
+    private readonly sink_;
+    private readonly conwaywasm_;
+    private readonly coordinateToOrigin_;
+    private readonly onMesh_;
+    private readonly maxUnits;
+    private readonly maxBytes;
+    private readonly firstGenerationMinRecords;
+    coordinationMatrix?: number[];
+    private stopped_;
+    private emittedUnits_;
+    private emittedBytes_;
+    private unitOrdinal_;
+    private lastInlineTick_;
+    private tickIntervalMs_;
+    private lastSnapshotRecords_;
+    private lastFailedSnapshotRecords_;
+    lastFailReason?: string;
+    private tickBudgetMs_;
+    private tickMaxAttempts_;
+    /** Set once a prefix-generation spatial walk has emitted a plate. */
+    private earlyPlatesEmitted_;
+    /**
+     * Whether those plates were composed under the walk's own fallback
+     * frame because no preview instance had latched one yet. They get one
+     * re-emission on a later generation once a real frame exists — see
+     * {@link maybeEmitEarlySpatialPlates_}.
+     */
+    private earlyPlatesUsedFallbackFrame_;
+    private readonly emittedGeometry_;
+    private generation_?;
+    /**
+     * @param store_ External source (OPFS / file).
+     * @param sink_ Live columnar sink the parse is filling.
+     * @param conwaywasm_ Shared wasm wrapper.
+     * @param coordinateToOrigin_ Open COORDINATE_TO_ORIGIN.
+     * @param onMesh_ Preview consumer.
+     * @param maxUnits Cap on products preview-extracted.
+     * @param maxBytes Cap on copied payload bytes.
+     * @param firstGenerationMinRecords Records before the first snapshot.
+     */
+    constructor(store_: StepExternalByteStore, sink_: ColumnarIndexSink<number>, conwaywasm_: ConwayGeometry, coordinateToOrigin_: boolean, onMesh_: (mesh: PreviewMeshPayload) => void, maxUnits?: number, maxBytes?: number, firstGenerationMinRecords?: number);
+    get capped(): boolean;
+    get emittedUnits(): number;
+    /** Products the current generation would run (test seam). */
+    get productCount(): number;
+    /**
+     * Plates the prefix-generation spatial walk emitted, 0 while it has
+     * not succeeded (see {@link maybeEmitEarlySpatialPlates_}).
+     */
+    get earlyPlateCount(): number;
+    /**
+     * One cadence-gated, time-budgeted tick. No-op until the interval
+     * elapses or the index can support a generation. Safe to call from
+     * parse progress.
+     *
+     * **Cadence and budget interact once, not twice.** The interval is
+     * measured tick-start to tick-start (`lastInlineTick_` is stamped
+     * before the work, as on the streamed channel), so a tick that spends
+     * its whole budget shortens the gap to the next one by that budget
+     * rather than adding to it. And the decay is charged only to ticks
+     * that actually attempted a product: a tick that found no generation —
+     * which is every tick through the opening seconds of a big parse, when
+     * the index has not yet reached FIRST_GENERATION_MIN_RECORDS — used to
+     * decay the interval anyway, so by the time there was anything to
+     * extract the cadence had already cooled toward
+     * TICK_INTERVAL_MAX_MS. Deliberately divergent from
+     * {@link StreamedPreviewChannel}, which decays unconditionally; the
+     * cost is that a channel which never finds a generation keeps probing
+     * at TICK_INTERVAL_MS, and a probe that finds nothing is a record
+     * count compared against two thresholds.
+     *
+     * @return {Promise<void>} Settles when this tick's products (if any)
+     * are captured.
+     */
+    maybeTickAsync(): Promise<void>;
+    /**
+     * Attempt products until the time budget or the attempt cap runs out,
+     * whichever comes first.
+     *
+     * @return {Promise<number>} Products attempted this tick.
+     */
+    private tickBudgeted_;
+    /**
+     * After parse: extract a short burst so small files (and prefixes
+     * that never crossed a progress tick) still emit placed meshes
+     * before open returns.
+     *
+     * @return {Promise<void>} Settles when the burst ends.
+     */
+    flushAsync(): Promise<void>;
+    /** Drop the throwaway prefix generation. Idempotent. */
+    stop(): void;
+    /**
+     * Test seam: drain until the current sink is exhausted or a cap hits.
+     *
+     * @return {Promise<void>} Settles when idle.
+     */
+    drainForTest(): Promise<void>;
+    /**
+     * @return {Promise<boolean>} True when a product was attempted.
+     */
+    private tickOnce_;
+    /**
+     * @return {Promise<boolean>} True when a generation with pending units exists.
+     */
+    private ensureGeneration_;
+    /**
+     * Put the spatial skeleton up from a PREFIX generation, seconds into
+     * the parse instead of after it (conway#518).
+     *
+     * The spatial records sit at the file head on Revit exports — on PSB
+     * `IFCSITE` is record #211 — and a prefix generation is already
+     * everything the walk needs: a columns snapshot over a windowed
+     * provider, with `prepareDemandExtraction(true)` done, which is what
+     * makes `getLinearScalingFactor()` report real units rather than 1.
+     * So the plates can lead the first extracted product rather than
+     * trailing the whole parse, which is what the store path's three
+     * stacked latency gates (one product per tick, early products
+     * deferring on late placements, the walk waiting for the full index)
+     * added up to: a blank screen through the first ~60% of a 16.7 s
+     * parse.
+     *
+     * **Runs at most once successfully, on the parse's cooperative path.**
+     * The walk is reused as-is, with no internal budget: it awaits a
+     * residency ensure per spatial node and per sampled product placement
+     * (PRODUCT_SAMPLE per node), so its cost tracks the prefix's spatial
+     * tree, not the file. On the first qualifying generation that tree is
+     * small by construction — the storeys exist but few
+     * `IfcRelContainedInSpatialStructure` do — which is the same property
+     * that makes these early plates coarse. Retries are bounded without a
+     * counter: generations only rebuild on a GENERATION_GROWTH_FACTOR
+     * doubling of the index, so there are O(log records) of them.
+     *
+     * **The end-of-parse walk in the proxy is the refresh, not a
+     * duplicate.** It re-emits the same expressIDs with contained-product
+     * samples the prefix did not hold and under the frame the channel
+     * latched, and the consumer contract is that an `aabb` payload
+     * REPLACES the prior plate for its expressID. Double emission is the
+     * design; see PreviewMeshPayload.
+     *
+     * **Known gap in that contract, and it is a gap, not a subtlety.**
+     * Replacement only reaches nodes the final walk still emits, and the
+     * emit set is not stable between the two: `aabbMostlyEqual` collapses
+     * a single-child wrapper (Project over Site over Building) once its
+     * box matches its child's, which a prefix generation's degenerate
+     * boxes may not yet do. A wrapper emitted here and collapsed there is
+     * never replaced and never removed — the payload contract has no
+     * delete — so its early box lingers as one small plate until Share
+     * tears the preview scenery down at load end. Bounded (the wrapper
+     * chain is a handful of nodes, and the collapse needs exactly one
+     * child), but real. Closing it properly needs either a delete/
+     * generation channel in the payload contract or an emit set the two
+     * walks agree on, and both are consumer-side changes.
+     *
+     * @param model The prefix model.
+     * @param extraction Its prepared extraction.
+     * @return {Promise<void>} Settles when the walk has run or been skipped.
+     */
+    private maybeEmitEarlySpatialPlates_;
+    private disposeGeneration_;
+    /**
+     * Copy newly extracted instances out of wasm — same placement math
+     * as {@link StreamedPreviewChannel}.
+     */
+    private captureNewInstances_;
+}
+//# sourceMappingURL=store_preview_channel.d.ts.map

package/compiled/src/compat/web-ifc/store_preview_channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store_preview_channel.d.ts","sourceRoot":"","sources":["../../../../src/compat/web-ifc/store_preview_channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAY5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAA;AAGrE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAU5E,OAAO,EACL,kBAAkB,EAEnB,MAAM,4BAA4B,CAAA;AAuCnC;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAmB;IAoD1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IAzDvC,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;IAEpC,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,eAAe,CAAmB;IAC1C,OAAO,CAAC,oBAAoB,CAAI;IAChC,OAAO,CAAC,0BAA0B,CAAI;IACtC,cAAc,CAAC,EAAE,MAAM,CAAA;IAMvB,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,gBAAgB,CAAoB;IAE5C,qEAAqE;IACrE,OAAO,CAAC,mBAAmB,CAAI;IAE/B;;;;;OAKG;IACH,OAAO,CAAC,6BAA6B,CAAQ;IAE7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsB;IAEvD,OAAO,CAAC,WAAW,CAAC,CAKnB;IAED;;;;;;;;;OASG;gBAEkB,MAAM,EAAE,qBAAqB,EAC7B,KAAK,EAAE,iBAAiB,CAAE,MAAM,CAAE,EAClC,WAAW,EAAE,cAAc,EAC3B,mBAAmB,EAAE,OAAO,EAC5B,OAAO,EAAE,CAAE,IAAI,EAAE,kBAAkB,KAAM,IAAI,EAC7C,QAAQ,GAAE,MAAkC,EAC5C,QAAQ,GAAE,MAAkC,EAC5C,yBAAyB,GAAE,MAChB;IAGhC,IAAW,MAAM,IAAI,OAAO,CAG3B;IAED,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED,6DAA6D;IAC7D,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED;;;OAGG;IACH,IAAW,eAAe,IAAI,MAAM,CAEnC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,cAAc,IAAI,OAAO,CAAE,IAAI,CAAE;IAyB9C;;;;;OAKG;YACW,aAAa;IAmB3B;;;;;;OAMG;IACU,UAAU,IAAI,OAAO,CAAE,IAAI,CAAE;IAuB1C,wDAAwD;IACjD,IAAI,IAAI,IAAI;IAMnB;;;;OAIG;IACU,YAAY,IAAI,OAAO,CAAE,IAAI,CAAE;IAmB5C;;OAEG;YACW,SAAS;IAyCvB;;OAEG;YACW,iBAAiB;IAgF/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;YACW,4BAA4B;IAsE1C,OAAO,CAAC,kBAAkB;IAiB1B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;CA+H7B"}