@ifc-lite/server-client 1.24.0 → 2.1.0

package/dist/parquet-nullable.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Null-safe bulk extraction for a nullable numeric Arrow column.
+ *
+ * `Vector.toArray()` returns the column's raw values buffer directly (its
+ * fast path for a primitive type), and that buffer carries whatever bits sit
+ * at a NULL row's slot — 0 in practice for a Float64/Int column written by
+ * every writer this project has observed (DuckDB, parquet-wasm), not a
+ * detectable sentinel. `data-model-decoder.ts`'s own module doc cites
+ * `toArray()` as "10-20x faster" than per-row `.get(i)` for BULK STRING
+ * extraction; that justification does not carry over to a NULLABLE numeric
+ * column, where `.get(i)` is the only call that reports a null row as `null`
+ * instead of a real-looking `0`.
+ *
+ * Two server-emitted columns are nullable `Float64` today: spatial-node
+ * `elevation` (a storey whose elevation cannot be resolved, see
+ * `apps/server/src/services/data_model/spatial.rs`) and material
+ * `thickness` (every non-layer material association — single material,
+ * material list, material constituent — always has `thickness: None`, see
+ * `apps/server/src/services/data_model/materials.rs`). Both used to decode
+ * here as `0` instead of `undefined` — a legitimate "no elevation" storey or
+ * "not a layer" material silently reading as a real, wrong measurement.
+ */
+export declare function nullableFloat64Column(table: {
+    getChild(name: string): unknown;
+}, name: string): (number | null)[] | undefined;
+//# sourceMappingURL=parquet-nullable.d.ts.map

package/dist/parquet-nullable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parquet-nullable.d.ts","sourceRoot":"","sources":["../src/parquet-nullable.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAC1C,IAAI,EAAE,MAAM,GACX,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,CAU/B"}

package/dist/parquet-nullable.js

@@ -0,0 +1,36 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Null-safe bulk extraction for a nullable numeric Arrow column.
+ *
+ * `Vector.toArray()` returns the column's raw values buffer directly (its
+ * fast path for a primitive type), and that buffer carries whatever bits sit
+ * at a NULL row's slot — 0 in practice for a Float64/Int column written by
+ * every writer this project has observed (DuckDB, parquet-wasm), not a
+ * detectable sentinel. `data-model-decoder.ts`'s own module doc cites
+ * `toArray()` as "10-20x faster" than per-row `.get(i)` for BULK STRING
+ * extraction; that justification does not carry over to a NULLABLE numeric
+ * column, where `.get(i)` is the only call that reports a null row as `null`
+ * instead of a real-looking `0`.
+ *
+ * Two server-emitted columns are nullable `Float64` today: spatial-node
+ * `elevation` (a storey whose elevation cannot be resolved, see
+ * `apps/server/src/services/data_model/spatial.rs`) and material
+ * `thickness` (every non-layer material association — single material,
+ * material list, material constituent — always has `thickness: None`, see
+ * `apps/server/src/services/data_model/materials.rs`). Both used to decode
+ * here as `0` instead of `undefined` — a legitimate "no elevation" storey or
+ * "not a layer" material silently reading as a real, wrong measurement.
+ */
+export function nullableFloat64Column(table, name) {
+    const col = table.getChild(name);
+    if (!col)
+        return undefined;
+    const raw = col.toArray();
+    // The common case (no nulls in this column/payload) keeps the fast bulk path.
+    if (col.nullCount === 0)
+        return Array.from(raw);
+    return Array.from(raw, (value, i) => (col.get(i) === null ? null : value));
+}
+//# sourceMappingURL=parquet-nullable.js.map

package/dist/parquet-nullable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parquet-nullable.js","sourceRoot":"","sources":["../src/parquet-nullable.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,sEAAsE;AACtE,4DAA4D;AAE5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA0C,EAC1C,IAAY;IAEZ,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAGlB,CAAC;IACd,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;IAC1B,8EAA8E;IAC9E,IAAI,GAAG,CAAC,SAAS,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7E,CAAC"}

package/dist/parquet-rotation.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Per-instance rotation, shared by both Parquet transports (issues #3575, #3888).
+ *
+ * Split out of `parquet-tables.ts` to stay under that file's module-size
+ * budget (see `parquet-columns.ts` for the same reasoning applied to the
+ * shared trailing columns).
+ *
+ * The server dedupes rotated `IfcMappedItem` / shared-`IfcRepresentationMap`
+ * occurrences by storing ONE template mesh in a canonical/local frame and
+ * carrying each instance's rotation (row-major 3x3, `rot0..rot8`) alongside
+ * its `origin_x/y/z`. The optimized transport has done this since #3575 and the
+ * flat one since `-parquet-v6` (#3888); the columns, the frame and the
+ * reconstruction are identical, which is why this module is shared rather than
+ * copied. Reconstruction contract:
+ * `world = origin + R * template_position` — the SAME `origin`-only contract
+ * as before (#1841) when `R` is the identity, which is what the server emits
+ * for every instance it did not verify a rotation-aware placement for.
+ */
+import type { ArrowTableLike } from './parquet-tables.js';
+/** The nine `rot0..rot8` columns, present together or not at all. */
+export type RotationColumns = ArrayLike<number>[];
+/**
+ * Read the rotation columns, or `undefined` when the payload does not carry
+ * them — an optimized wire-version-2 payload (#3575), or a flat `-parquet-v5`
+ * blob (#3888). Callers then fall back to the identity rotation, which is
+ * exactly the behaviour those payloads were written for.
+ *
+ * `onAbsent` says what a MISSING or short block means to the caller, in the
+ * caller's own terms rather than in one transport's version numbering.
+ * `'identity'` is the reading above. `'throw'` is for a payload whose own
+ * header states the columns are there: the optimized format's version 3 is
+ * only emitted once a non-identity rotation has actually been written
+ * (`optimized_wire_version` in `parquet_instancing.rs`), so absence there is
+ * truncated wire data, and decoding it as identity would place a genuinely
+ * rotated occurrence at the wrong orientation with no signal why.
+ *
+ * The flat transport has no such header — it cannot tell a truncated v6 mesh
+ * table from a genuine v5 one — so it passes `'identity'`, which is right for
+ * the v5 case and no worse than throwing for the other.
+ */
+export declare function readRotationColumns(instanceArrow: ArrowTableLike, rowCount: number, onAbsent?: 'identity' | 'throw'): RotationColumns | undefined;
+/**
+ * Rotate `positions` (and, when present, `normals`) IN PLACE by row `index`'s
+ * 3x3 rotation. A no-op when the row is identity (translation-only or
+ * unverified placements — the overwhelming majority of rows on most models),
+ * so this costs nothing beyond the identity check for meshes #3575 did not
+ * touch.
+ *
+ * Normals get the SAME rotation matrix as positions, not its inverse
+ * transpose — correct for a rigid (orthogonal) rotation, which is what the
+ * server's per-vertex residual check (`RECOMPOSITION_TOLERANCE_M`) verifies
+ * before emitting a non-identity row. A non-uniform scale baked into the
+ * source `IfcCartesianTransformationOperator` would need the inverse
+ * transpose for normals specifically; this matches the convention the
+ * existing GPU-instancing wire format (`ifc_lite_geometry::instancing`)
+ * already uses, so it is not a new approximation this fix introduces.
+ *
+ * `isIdentityRow` already refuses to call a row with a NaN cell "identity"
+ * (`NaN !== 1` is true, so the row fails the comparison and falls through
+ * here) — a NaN can never silently render as an unrotated placement. But
+ * multiplying it through `rotateTriplets` would still corrupt every vertex
+ * of THIS instance to NaN, uncontrolled: no error, a mesh that may vanish
+ * or wreck a shared bounding-box computation with no signal why. A row that
+ * isn't finite is malformed wire data — the same class of fault
+ * `buildMeshesFromOptimizedTables` already fails loudly on for a bad
+ * mesh/material index — so it throws here too, instead of writing NaN
+ * silently into the buffer.
+ */
+export declare function applyInstanceRotation(positions: Float32Array, normals: Float32Array | undefined, rot: RotationColumns, index: number): void;
+//# sourceMappingURL=parquet-rotation.d.ts.map

package/dist/parquet-rotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parquet-rotation.d.ts","sourceRoot":"","sources":["../src/parquet-rotation.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;AAKlD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,cAAc,EAC7B,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,UAAU,GAAG,OAAoB,GAC1C,eAAe,GAAG,SAAS,CAe7B;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,MAAM,GACZ,IAAI,CAUN"}

package/dist/parquet-rotation.js

@@ -0,0 +1,96 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { numericColumn } from './parquet-columns.js';
+/** Row-major identity, hoisted so the per-mesh identity check allocates nothing. */
+const IDENTITY = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+/**
+ * Read the rotation columns, or `undefined` when the payload does not carry
+ * them — an optimized wire-version-2 payload (#3575), or a flat `-parquet-v5`
+ * blob (#3888). Callers then fall back to the identity rotation, which is
+ * exactly the behaviour those payloads were written for.
+ *
+ * `onAbsent` says what a MISSING or short block means to the caller, in the
+ * caller's own terms rather than in one transport's version numbering.
+ * `'identity'` is the reading above. `'throw'` is for a payload whose own
+ * header states the columns are there: the optimized format's version 3 is
+ * only emitted once a non-identity rotation has actually been written
+ * (`optimized_wire_version` in `parquet_instancing.rs`), so absence there is
+ * truncated wire data, and decoding it as identity would place a genuinely
+ * rotated occurrence at the wrong orientation with no signal why.
+ *
+ * The flat transport has no such header — it cannot tell a truncated v6 mesh
+ * table from a genuine v5 one — so it passes `'identity'`, which is right for
+ * the v5 case and no worse than throwing for the other.
+ */
+export function readRotationColumns(instanceArrow, rowCount, onAbsent = 'identity') {
+    const cols = [];
+    for (let i = 0; i < 9; i++) {
+        const col = numericColumn(instanceArrow, `rot${i}`);
+        if (!col || col.length < rowCount) {
+            if (onAbsent === 'throw') {
+                throw new Error('Malformed optimized Parquet geometry: format version 3 requires rot0..rot8 instance columns');
+            }
+            return undefined;
+        }
+        cols.push(col);
+    }
+    return cols;
+}
+/** `true` when row `index`'s rotation is exactly identity (the common case). */
+function isIdentityRow(rot, index) {
+    for (let i = 0; i < 9; i++) {
+        if (rot[i][index] !== IDENTITY[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Rotate `positions` (and, when present, `normals`) IN PLACE by row `index`'s
+ * 3x3 rotation. A no-op when the row is identity (translation-only or
+ * unverified placements — the overwhelming majority of rows on most models),
+ * so this costs nothing beyond the identity check for meshes #3575 did not
+ * touch.
+ *
+ * Normals get the SAME rotation matrix as positions, not its inverse
+ * transpose — correct for a rigid (orthogonal) rotation, which is what the
+ * server's per-vertex residual check (`RECOMPOSITION_TOLERANCE_M`) verifies
+ * before emitting a non-identity row. A non-uniform scale baked into the
+ * source `IfcCartesianTransformationOperator` would need the inverse
+ * transpose for normals specifically; this matches the convention the
+ * existing GPU-instancing wire format (`ifc_lite_geometry::instancing`)
+ * already uses, so it is not a new approximation this fix introduces.
+ *
+ * `isIdentityRow` already refuses to call a row with a NaN cell "identity"
+ * (`NaN !== 1` is true, so the row fails the comparison and falls through
+ * here) — a NaN can never silently render as an unrotated placement. But
+ * multiplying it through `rotateTriplets` would still corrupt every vertex
+ * of THIS instance to NaN, uncontrolled: no error, a mesh that may vanish
+ * or wreck a shared bounding-box computation with no signal why. A row that
+ * isn't finite is malformed wire data — the same class of fault
+ * `buildMeshesFromOptimizedTables` already fails loudly on for a bad
+ * mesh/material index — so it throws here too, instead of writing NaN
+ * silently into the buffer.
+ */
+export function applyInstanceRotation(positions, normals, rot, index) {
+    if (isIdentityRow(rot, index))
+        return;
+    const r = rot.map((col) => col[index]);
+    if (!r.every(Number.isFinite)) {
+        throw new Error(`Malformed Parquet geometry: non-finite rotation value for row ${index} (rot=[${r.join(', ')}])`);
+    }
+    rotateTriplets(positions, r);
+    if (normals)
+        rotateTriplets(normals, r);
+}
+function rotateTriplets(buf, r) {
+    for (let v = 0; v < buf.length; v += 3) {
+        const x = buf[v];
+        const y = buf[v + 1];
+        const z = buf[v + 2];
+        buf[v] = r[0] * x + r[1] * y + r[2] * z;
+        buf[v + 1] = r[3] * x + r[4] * y + r[5] * z;
+        buf[v + 2] = r[6] * x + r[7] * y + r[8] * z;
+    }
+}
+//# sourceMappingURL=parquet-rotation.js.map

package/dist/parquet-rotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parquet-rotation.js","sourceRoot":"","sources":["../src/parquet-rotation.ts"],"names":[],"mappings":"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"}

package/dist/parquet-stream-events.d.ts

@@ -0,0 +1,23 @@
+import type { ParquetBatch, ParquetStreamResult } from './types.js';
+/**
+ * Raised when an SSE parse stream ends with no terminal event.
+ *
+ * Shared by `parseStream` and the Parquet stream reader below so the two
+ * cannot drift apart by an article. The wording has to hold on BOTH paths,
+ * which it does: this reader throws on an `error` event at its own
+ * `case 'error'`, so it can only reach its `!stats || !metadata` check in the
+ * same state `parseStream`'s `!terminated` describes, the stream stopped
+ * without ever saying why. Not re-exported from the package index: it is an
+ * internal guarantee about two call sites, not part of the published surface.
+ */
+export declare const STREAM_ENDED_WITHOUT_TERMINAL_EVENT = "Stream ended without a complete event (connection dropped or the server failed mid-parse)";
+/**
+ * Drain a `parquet-stream` SSE response, decoding each batch and handing it to
+ * `onBatch` as it arrives.
+ *
+ * @param response - An OK response whose body is the SSE stream.
+ * @param onBatch - Called once per decoded batch, for immediate rendering.
+ * @param startedAt - `performance.now()` at request time, for the timing log.
+ */
+export declare function consumeParquetStream(response: Response, onBatch: (batch: ParquetBatch) => void, startedAt: number): Promise<ParquetStreamResult>;
+//# sourceMappingURL=parquet-stream-events.d.ts.map

package/dist/parquet-stream-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parquet-stream-events.d.ts","sourceRoot":"","sources":["../src/parquet-stream-events.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAEV,YAAY,EAEZ,mBAAmB,EAGpB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mCAAmC,8FAC6C,CAAC;AAE9F;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,EACtC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,CAAC,CA4G9B"}

package/dist/parquet-stream-events.js

@@ -0,0 +1,133 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * Reading the SSE body of `POST /api/v1/parse/parquet-stream`.
+ *
+ * Its own module because there are now TWO requests that answer with that
+ * stream and they must be consumed identically (issue #3901): the hash-only
+ * probe, which sends no file at all and replays from cache, and the multipart
+ * upload it falls back to. The server guarantees a hit replays the same events
+ * a live parse emits; duplicating this loop per call site is how that
+ * guarantee stops being observable on the client.
+ */
+import { decodeParquetGeometry } from './parquet-decoder.js';
+/**
+ * Raised when an SSE parse stream ends with no terminal event.
+ *
+ * Shared by `parseStream` and the Parquet stream reader below so the two
+ * cannot drift apart by an article. The wording has to hold on BOTH paths,
+ * which it does: this reader throws on an `error` event at its own
+ * `case 'error'`, so it can only reach its `!stats || !metadata` check in the
+ * same state `parseStream`'s `!terminated` describes, the stream stopped
+ * without ever saying why. Not re-exported from the package index: it is an
+ * internal guarantee about two call sites, not part of the published surface.
+ */
+export const STREAM_ENDED_WITHOUT_TERMINAL_EVENT = 'Stream ended without a complete event (connection dropped or the server failed mid-parse)';
+/**
+ * Drain a `parquet-stream` SSE response, decoding each batch and handing it to
+ * `onBatch` as it arrives.
+ *
+ * @param response - An OK response whose body is the SSE stream.
+ * @param onBatch - Called once per decoded batch, for immediate rendering.
+ * @param startedAt - `performance.now()` at request time, for the timing log.
+ */
+export async function consumeParquetStream(response, onBatch, startedAt) {
+    if (!response.body) {
+        throw new Error('No response body for streaming');
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let cache_key = '';
+    let total_meshes = 0;
+    let stats = null;
+    let metadata = null;
+    let symbolic_data;
+    // A thrown 'error' event (or any other exception mid-loop) must not
+    // leave the reader locked on `response.body` — mirrors the try/finally
+    // `parseStream` already uses for the same SSE-reading shape.
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Process complete SSE events
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || ''; // Keep incomplete line in buffer
+            for (const line of lines) {
+                if (!line.startsWith('data:'))
+                    continue;
+                const jsonStr = line.slice(5).trim();
+                if (!jsonStr)
+                    continue;
+                try {
+                    const event = JSON.parse(jsonStr);
+                    switch (event.type) {
+                        case 'start':
+                            cache_key = event.cache_key;
+                            console.log(`[client] Stream started: ${event.total_estimate} entities, cache_key: ${cache_key.substring(0, 16)}...`);
+                            break;
+                        case 'progress':
+                            // Progress events can be used for UI feedback
+                            break;
+                        case 'batch': {
+                            const decodeStart = performance.now();
+                            // Decode base64 Parquet data
+                            const binaryStr = atob(event.data);
+                            const bytes = new Uint8Array(binaryStr.length);
+                            for (let i = 0; i < binaryStr.length; i++) {
+                                bytes[i] = binaryStr.charCodeAt(i);
+                            }
+                            // Decode Parquet to meshes
+                            const meshes = await decodeParquetGeometry(bytes.buffer);
+                            const decodeTime = performance.now() - decodeStart;
+                            total_meshes += meshes.length;
+                            console.log(`[client] Batch #${event.batch_number}: ${meshes.length} meshes, decode: ${decodeTime.toFixed(0)}ms`);
+                            // Call the batch callback for immediate rendering
+                            onBatch({
+                                meshes,
+                                batch_number: event.batch_number,
+                                decode_time_ms: decodeTime,
+                            });
+                            break;
+                        }
+                        case 'complete': {
+                            stats = event.stats;
+                            metadata = event.metadata;
+                            symbolic_data = event.symbolic_data;
+                            const totalTime = performance.now() - startedAt;
+                            console.log(`[client] Stream complete: ${total_meshes} meshes in ${totalTime.toFixed(0)}ms`);
+                            break;
+                        }
+                        case 'error':
+                            throw new Error(`Stream error: ${event.message}`);
+                    }
+                }
+                catch (e) {
+                    if (e instanceof SyntaxError) {
+                        console.warn('[client] Failed to parse SSE event:', jsonStr);
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    if (!stats || !metadata) {
+        throw new Error(STREAM_ENDED_WITHOUT_TERMINAL_EVENT);
+    }
+    return {
+        cache_key,
+        total_meshes,
+        stats,
+        metadata,
+        symbolic_data,
+    };
+}
+//# sourceMappingURL=parquet-stream-events.js.map

package/dist/parquet-stream-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parquet-stream-events.js","sourceRoot":"","sources":["../src/parquet-stream-events.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAE/D;;;;;;;;;GASG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAU7D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAC9C,2FAA2F,CAAC;AAE9F;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAkB,EAClB,OAAsC,EACtC,SAAiB;IAEjB,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,KAAK,GAA2B,IAAI,CAAC;IACzC,IAAI,QAAQ,GAAyB,IAAI,CAAC;IAC1C,IAAI,aAAuC,CAAC;IAE5C,oEAAoE;IACpE,uEAAuE;IACvE,6DAA6D;IAC7D,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAEhB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAElD,8BAA8B;YAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,iCAAiC;YAE7D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;oBAAE,SAAS;gBAExC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACrC,IAAI,CAAC,OAAO;oBAAE,SAAS;gBAEvB,IAAI,CAAC;oBACH,MAAM,KAAK,GAAuB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;oBAEtD,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;wBACnB,KAAK,OAAO;4BACV,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;4BAC5B,OAAO,CAAC,GAAG,CAAC,4BAA4B,KAAK,CAAC,cAAc,yBAAyB,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;4BACtH,MAAM;wBAER,KAAK,UAAU;4BACb,8CAA8C;4BAC9C,MAAM;wBAER,KAAK,OAAO,CAAC,CAAC,CAAC;4BACb,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;4BACtC,6BAA6B;4BAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;4BACnC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;4BAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gCAC1C,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;4BACrC,CAAC;4BAED,2BAA2B;4BAC3B,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;4BACzD,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,WAAW,CAAC;4BAEnD,YAAY,IAAI,MAAM,CAAC,MAAM,CAAC;4BAC9B,OAAO,CAAC,GAAG,CAAC,mBAAmB,KAAK,CAAC,YAAY,KAAK,MAAM,CAAC,MAAM,oBAAoB,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;4BAElH,kDAAkD;4BAClD,OAAO,CAAC;gCACN,MAAM;gCACN,YAAY,EAAE,KAAK,CAAC,YAAY;gCAChC,cAAc,EAAE,UAAU;6BAC3B,CAAC,CAAC;4BACH,MAAM;wBACR,CAAC;wBAED,KAAK,UAAU,CAAC,CAAC,CAAC;4BAChB,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;4BACpB,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;4BAC1B,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;4BACpC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;4BAChD,OAAO,CAAC,GAAG,CAAC,6BAA6B,YAAY,cAAc,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;4BAC7F,MAAM;wBACR,CAAC;wBAED,KAAK,OAAO;4BACV,MAAM,IAAI,KAAK,CAAC,iBAAiB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;oBACtD,CAAC;gBACH,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,IAAI,CAAC,YAAY,WAAW,EAAE,CAAC;wBAC7B,OAAO,CAAC,IAAI,CAAC,qCAAqC,EAAE,OAAO,CAAC,CAAC;oBAC/D,CAAC;yBAAM,CAAC;wBACN,MAAM,CAAC,CAAC;oBACV,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;IAED,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IAED,OAAO;QACL,SAAS;QACT,YAAY;QACZ,KAAK;QACL,QAAQ;QACR,aAAa;KACd,CAAC;AACJ,CAAC"}

package/dist/parquet-tables.d.ts

@@ -24,10 +24,19 @@ export interface ArrowTableLike {
     getChild(name: string): ArrowColumnLike | null | undefined;
 }
 /**
- * Rebuild `MeshData[]` from the standard (non-instanced) three-table layout.
+ * Rebuild `MeshData[]` from the standard three-table layout.
  *
  * Positions/normals are already Y-up metres — the server applies the axis swap
  * once, in `services::axis` (issue #1841), so every transport agrees.
+ *
+ * "Non-instanced" until `-parquet-v6` (issue #3888): several mesh rows can now
+ * name the SAME `vertex_start`/`index_start` block, each placed by its own
+ * `origin_x/y/z` plus a `rot0..rot8` rotation (`world = origin + R * p`) — the
+ * rotation-aware sharing the optimized transport has carried since #3575. Two
+ * things follow, and both are what keeps a `-parquet-v5` blob decoding here
+ * unchanged: the rotation columns are ABSENT on v5, and absent means identity;
+ * and `origin` was zero on every v5 flat row, so folding it in was a no-op
+ * there and is load-bearing here.
  */
 export declare function buildMeshesFromTables(meshArrow: ArrowTableLike, vertexArrow: ArrowTableLike, indexArrow: ArrowTableLike): MeshData[];
 /** Tables + header flags of the optimized (instanced, quantized) layout. */
@@ -41,6 +50,7 @@ export interface OptimizedTables {
     hasNormals: boolean;
     /** Quantization divisor: metres = quantized / vertexMultiplier. */
     vertexMultiplier: number;
+    wireVersion: 2 | 3;
 }
 /**
  * Rebuild `MeshData[]` from the optimized instanced layout.

package/dist/parquet-tables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parquet-tables.d.ts","sourceRoot":"","sources":["../src/parquet-tables.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,GAAG,SAAS,CAAC;CAC5D;AAgDD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,cAAc,EACzB,WAAW,EAAE,cAAc,EAC3B,UAAU,EAAE,cAAc,GACzB,QAAQ,EAAE,CAmIZ;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,cAAc,CAAC;IAC9B,SAAS,EAAE,cAAc,CAAC;IAC1B,aAAa,EAAE,cAAc,CAAC;IAC9B,WAAW,EAAE,cAAc,CAAC;IAC5B,UAAU,EAAE,cAAc,CAAC;IAC3B,+EAA+E;IAC/E,UAAU,EAAE,OAAO,CAAC;IACpB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,eAAe,GAAG,QAAQ,EAAE,CAyKlF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,MAAM,EAAE,GAAG,WAAW,GAC9B,YAAY,CA0Cd"}
+{"version":3,"file":"parquet-tables.d.ts","sourceRoot":"","sources":["../src/parquet-tables.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,GAAG,SAAS,CAAC;CAC5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,cAAc,EACzB,WAAW,EAAE,cAAc,EAC3B,UAAU,EAAE,cAAc,GACzB,QAAQ,EAAE,CAyIZ;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,cAAc,CAAC;IAC9B,SAAS,EAAE,cAAc,CAAC;IAC1B,aAAa,EAAE,cAAc,CAAC;IAC9B,WAAW,EAAE,cAAc,CAAC;IAC5B,UAAU,EAAE,cAAc,CAAC;IAC3B,+EAA+E;IAC/E,UAAU,EAAE,OAAO,CAAC;IACpB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,eAAe,GAAG,QAAQ,EAAE,CAiLlF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,MAAM,EAAE,GAAG,WAAW,GAC9B,YAAY,CA0Cd"}

package/dist/parquet-tables.js

@@ -1,44 +1,22 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { meshColumns, numericColumn, readSourceId } from './parquet-columns.js';
+import { meshColumns, numericColumn, transformFields } from './parquet-columns.js';
+import { applyInstanceRotation, readRotationColumns } from './parquet-rotation.js';
 /**
- * The canonical per-mesh transform metadata, spread into the `MeshData` literal.
- *
- * `origin` is omitted when the frame IS the world origin and `geometry_class`
- * when it is 0 (occurrence), so a world-baked mesh decodes to exactly the shape
- * it had before these columns existed — and to the same shape on every
- * transport (JSON, standard Parquet, optimized Parquet).
- */
-function transformFields(index, cols) {
-    // A usable column can still carry a non-finite VALUE at this row. `||` alone
-    // misses it: an all-NaN triplet is already dropped, but a PARTIAL one
-    // (`[NaN, 5, 0]`) is truthy and the NaN would poison bounds math. Not a
-    // throw -- this file throws only for STRUCTURAL malformation.
-    const ox = cols.originX?.[index];
-    const oy = cols.originY?.[index];
-    const oz = cols.originZ?.[index];
-    const originFinite = Number.isFinite(ox) && Number.isFinite(oy) && Number.isFinite(oz);
-    const origin = originFinite && (ox || oy || oz) ? [ox, oy, oz] : undefined;
-    const geometry_class = cols.geometryClass?.[index] || undefined;
-    // Sentinel, not null (#3215): a nullable column's values buffer is undefined
-    // at null rows and parquet-wasm 0.7.x leaks the NEIGHBOURING row's id into it
-    // -- a material-less mesh decoded as `material_id: 902`, a real-looking id
-    // for another entity. Non-nullable means no validity bitmap to leak.
-    const geometry_item_id = readSourceId(cols.geometryItemId, index);
-    const material_id = readSourceId(cols.materialId, index);
-    return {
-        ...(origin ? { origin } : {}),
-        ...(geometry_class ? { geometry_class } : {}),
-        ...(geometry_item_id ? { geometry_item_id } : {}),
-        ...(material_id ? { material_id } : {}),
-    };
-}
-/**
- * Rebuild `MeshData[]` from the standard (non-instanced) three-table layout.
+ * Rebuild `MeshData[]` from the standard three-table layout.
  *
  * Positions/normals are already Y-up metres — the server applies the axis swap
  * once, in `services::axis` (issue #1841), so every transport agrees.
+ *
+ * "Non-instanced" until `-parquet-v6` (issue #3888): several mesh rows can now
+ * name the SAME `vertex_start`/`index_start` block, each placed by its own
+ * `origin_x/y/z` plus a `rot0..rot8` rotation (`world = origin + R * p`) — the
+ * rotation-aware sharing the optimized transport has carried since #3575. Two
+ * things follow, and both are what keeps a `-parquet-v5` blob decoding here
+ * unchanged: the rotation columns are ABSENT on v5, and absent means identity;
+ * and `origin` was zero on every v5 flat row, so folding it in was a no-op
+ * there and is load-bearing here.
  */
 export function buildMeshesFromTables(meshArrow, vertexArrow, indexArrow) {
     // Extract columns from mesh table
@@ -91,6 +69,10 @@ export function buildMeshesFromTables(meshArrow, vertexArrow, indexArrow) {
     // from servers predating them, where origin defaults to [0,0,0] and the
     // source ids simply do not appear.
     const cols = meshColumns(meshArrow, meshCount);
+    // Absent on every pre-#3888 payload. The flat transport has no version byte
+    // to tell a truncated v6 from a genuine v5, so absence reads as the identity
+    // it is on a v5 blob (see `readRotationColumns`).
+    const rotationCols = readRotationColumns(meshArrow, meshCount, 'identity');
     const meshes = new Array(meshCount);
     // Only consume the additive origin/geometry_class columns when all three
     // origin components are present AND parallel to the mesh rows — a short or
@@ -112,10 +94,8 @@ export function buildMeshesFromTables(meshArrow, vertexArrow, indexArrow) {
                 `(vertexStart=${vertexStart}, vertexCount=${vertexCount}, vertices=${posX.length}; ` +
                 `indexStart=${indexStart}, indexCount=${indexCount}, triangles=${idx0.length})`);
         }
-        // Reconstruct interleaved positions from columnar format
-        // OPTIMIZATION: Z-up to Y-up transform is now done server-side
-        // Server already transforms: X stays same, new Y = old Z, new Z = -old Y
-        // So we just copy directly without per-vertex transformation
+        // Reconstruct interleaved positions from columnar format. The server
+        // already applies the Z-up -> Y-up swap, so this just copies through.
         const positions = new Float32Array(vertexCount * 3);
         for (let v = 0; v < vertexCount; v++) {
             const srcIdx = vertexStart + v;
@@ -123,7 +103,7 @@ export function buildMeshesFromTables(meshArrow, vertexArrow, indexArrow) {
             positions[v * 3 + 1] = posY[srcIdx];
             positions[v * 3 + 2] = posZ[srcIdx];
         }
-        // Reconstruct interleaved normals (also pre-transformed server-side)
+        // Reconstruct interleaved normals (also pre-transformed server-side).
         const normals = new Float32Array(vertexCount * 3);
         for (let v = 0; v < vertexCount; v++) {
             const srcIdx = vertexStart + v;
@@ -131,9 +111,13 @@ export function buildMeshesFromTables(meshArrow, vertexArrow, indexArrow) {
             normals[v * 3 + 1] = normY[srcIdx];
             normals[v * 3 + 2] = normZ[srcIdx];
         }
-        // Reconstruct triangle indices from columnar format
-        const triangleCount = indexCount / 3;
-        const triangleStart = indexStart / 3;
+        // Rotate the shared block onto THIS occurrence before `origin` translates
+        // it (`world = origin + R * p`). A no-op on an identity row, which is every
+        // row of a v5 payload and every unshared row of a v6 one.
+        if (rotationCols)
+            applyInstanceRotation(positions, normals, rotationCols, i);
+        // Reconstruct triangle indices from columnar format.
+        const triangleCount = indexCount / 3, triangleStart = indexStart / 3;
         const indices = new Uint32Array(indexCount);
         for (let t = 0; t < triangleCount; t++) {
             const srcIdx = triangleStart + t;
@@ -222,6 +206,9 @@ export function buildMeshesFromOptimizedTables(tables) {
     const cols = meshColumns(instanceArrow, instanceCount);
     const meshes = new Array(instanceCount);
     const dequantMultiplier = 1.0 / vertexMultiplier;
+    // Wire version 3 states the columns are there (#3575), so absence is
+    // truncated data, not an older payload; version 2 predates them.
+    const rotationCols = readRotationColumns(instanceArrow, instanceCount, tables.wireVersion === 3 ? 'throw' : 'identity');
     // Additive per-instance origin/geometry_class columns (issue #1841): consume
     // only when present AND parallel to the instance rows.
     for (let i = 0; i < instanceCount; i++) {
@@ -249,9 +236,7 @@ export function buildMeshesFromOptimizedTables(tables) {
                 `vertices=${vertexX.length}; indexOffset=${indexOffset}, indexCount=${indexCount}, ` +
                 `indices=${indices.length})`);
         }
-        // Dequantize and reconstruct positions
-        // OPTIMIZATION: Z-up to Y-up transform is now done server-side for optimized format too
-        // Server already transforms before quantization, so we just dequantize directly
+        // Dequantize (the server already applied Z-up -> Y-up before quantizing).
         const positions = new Float32Array(vertexCount * 3);
         for (let v = 0; v < vertexCount; v++) {
             const srcIdx = vertexOffset + v;
@@ -264,25 +249,26 @@ export function buildMeshesFromOptimizedTables(tables) {
         for (let j = 0; j < indexCount; j++) {
             meshIndicesArray[j] = indices[indexOffset + j];
         }
-        // Reconstruct normals (pre-transformed server-side, or compute if not present)
-        let normals;
+        // Server-provided normals, read BEFORE rotating (#3575) so a flat
+        // recompute below, when absent, starts from already-rotated positions.
+        let providedNormals;
         if (hasNormals && normalX && normalY && normalZ) {
-            normals = new Float32Array(vertexCount * 3);
+            providedNormals = new Float32Array(vertexCount * 3);
             for (let v = 0; v < vertexCount; v++) {
                 const srcIdx = vertexOffset + v;
-                normals[v * 3] = normalX[srcIdx];
-                normals[v * 3 + 1] = normalY[srcIdx];
-                normals[v * 3 + 2] = normalZ[srcIdx];
+                providedNormals[v * 3] = normalX[srcIdx];
+                providedNormals[v * 3 + 1] = normalY[srcIdx];
+                providedNormals[v * 3 + 2] = normalZ[srcIdx];
             }
         }
-        else {
-            // Compute flat normals from triangle faces
-            normals = computeFlatNormals(positions, meshIndicesArray);
-        }
-        // Convert byte colors to float [0-1]. `positions` are the TEMPLATE-local
-        // vertices; `origin` (not baked in, to keep f32 precision at building scale)
-        // carries the per-instance placement so the renderer reconstructs
-        // world = origin + position — the same contract as the standard path.
+        // Rotate into this instance's own frame (#3575); no-op for identity rows.
+        if (rotationCols)
+            applyInstanceRotation(positions, providedNormals, rotationCols, i);
+        const normals = providedNormals ?? computeFlatNormals(positions, meshIndicesArray);
+        // Convert byte colors to float [0-1]. `origin` (not baked in, for f32
+        // precision at building scale) carries the remaining translation: world
+        // = origin + position, same contract as the standard path (#1841),
+        // extended with the rotation already applied to `positions` above.
         meshes[i] = {
             express_id: entityIds[i],
             ifc_type: ifcTypes?.get(i) ?? 'Unknown',