@selvajs/visualization 1.7.0 → 1.7.1-beta.1

package/dist/parse.d.cts

@@ -4,6 +4,7 @@ import * as THREE from "three";
 export declare const meshPolicy: {
   clone(meshes: THREE.Object3D[]): THREE.Object3D[];
   release(meshes: THREE.Object3D[]): void;
+  byteSize(meshes: THREE.Object3D[]): number;
 };
 /**
  * Declared structurally rather than imported from `@selvajs/compute` — this package converts

package/dist/parse.d.ts

@@ -4,6 +4,7 @@ import * as THREE from "three";
 export declare const meshPolicy: {
   clone(meshes: THREE.Object3D[]): THREE.Object3D[];
   release(meshes: THREE.Object3D[]): void;
+  byteSize(meshes: THREE.Object3D[]): number;
 };
 /**
  * Declared structurally rather than imported from `@selvajs/compute` — this package converts

package/dist/parse.js

@@ -73,10 +73,24 @@ function cloneSceneObjects(meshes) {
 function releaseSceneObjects(meshes) {
 	meshes.forEach((root) => disposeObjectTree(root, { materials: false }));
 }
+/** Geometry bytes only: the memo's copies share materials and textures with the live scene. */
+function sceneObjectsByteSize(meshes) {
+	let bytes = 0;
+	const seen = /* @__PURE__ */ new Set();
+	for (const root of meshes) root.traverse((child) => {
+		const geometry = child.geometry;
+		if (!geometry || seen.has(geometry)) return;
+		seen.add(geometry);
+		for (const attribute of Object.values(geometry.attributes)) bytes += attribute.array.byteLength;
+		if (geometry.index) bytes += geometry.index.array.byteLength;
+	});
+	return bytes;
+}
 /** Structurally, not nominally, typed as `@selvajs/solve/client`'s `MeshPolicy<THREE.Object3D>` — avoids a dependency on solve. */
 const meshPolicy = {
 	clone: cloneSceneObjects,
-	release: releaseSceneObjects
+	release: releaseSceneObjects,
+	byteSize: sceneObjectsByteSize
 };
 /** Opacity < 1 flips `transparent` on. */
 function materialParams(color, opacity) {
@@ -760,6 +774,95 @@ function textureToDataUri(payload) {
 	for (let i = 0; i < data.byteLength; i += step) binary += String.fromCharCode(...data.subarray(i, i + step));
 	return `data:${mime};base64,${btoa(binary)}`;
 }
+// src/parse/webdisplay/batch/metadata.ts
+function metadataFail(message, context) {
+	return new VisualizationError(message, ErrorCodes.VALIDATION_ERROR, { context });
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Validates the batch's material and group/mesh metadata against the decoded geometry buffers
+* before any of it is used arithmetically. Throws on the first inconsistency — a material, group or
+* mesh that isn't an object, out-of-range `materialId`, non-integer or negative offsets/counts, or a
+* vertex/index window that overruns the buffers — so malformed or version-skewed metadata fails the
+* parse loudly instead of corrupting the render.
+*/
+function validateBatchMetadata(materials, groups, totalVertexCount, totalIndexCount) {
+	if (!Array.isArray(materials)) throw metadataFail("Batch materials must be an array.", { materials: typeof materials });
+	const badMaterial = materials.findIndex((material) => !isObject(material));
+	if (badMaterial !== -1) throw metadataFail("Each material entry must be an object.", { materialIndex: badMaterial });
+	const materialCount = materials.length;
+	if (!Array.isArray(groups)) throw metadataFail("Batch groups must be an array.", { groups: typeof groups });
+	groups.forEach((group, groupIndex) => {
+		if (!isObject(group) || !Array.isArray(group.meshes)) throw metadataFail("Each group must be an object with a meshes array.", { groupIndex });
+		if (!group.meshes.every(isObject)) throw metadataFail("Each mesh entry must be an object.", { groupIndex });
+	});
+	for (const group of groups) {
+		if (!Number.isInteger(group.materialId) || group.materialId < 0 || group.materialId >= materialCount) throw metadataFail("Group materialId out of range of the materials array.", {
+			materialId: group.materialId,
+			materialCount
+		});
+		for (const mesh of group.meshes) {
+			const fields = {
+				vertexStart: mesh.vertexStart,
+				vertexCount: mesh.vertexCount,
+				indexStart: mesh.indexStart,
+				indexCount: mesh.indexCount
+			};
+			for (const [field, value] of Object.entries(fields)) if (!Number.isInteger(value) || value < 0) throw metadataFail(`Mesh metadata field "${field}" must be a non-negative integer.`, {
+				meshName: mesh.name,
+				field,
+				value
+			});
+			if (mesh.vertexStart + mesh.vertexCount > totalVertexCount) throw metadataFail("Mesh vertex window exceeds the batch vertex buffer.", {
+				meshName: mesh.name,
+				vertexStart: mesh.vertexStart,
+				vertexCount: mesh.vertexCount,
+				totalVertexCount
+			});
+			if (mesh.indexStart + mesh.indexCount > totalIndexCount) throw metadataFail("Mesh index window exceeds the batch index buffer.", {
+				meshName: mesh.name,
+				indexStart: mesh.indexStart,
+				indexCount: mesh.indexCount,
+				totalIndexCount
+			});
+		}
+	}
+}
+/**
+* Error for an index outside its mesh's declared vertex window
+* `[vertexStart, vertexStart + vertexCount)`. Rebasing (`index - vertexStart`) writes into an
+* unsigned array, so an out-of-window index would otherwise wrap to ~4 billion and corrupt the
+* geometry. Range checks live inline in the copy loops (a function call per index measured
+* noticeably slower at millions of indices) — this only builds the failure.
+*/
+function indexOutOfWindow(indexValue, meshMeta) {
+	return metadataFail("Index references a vertex outside its mesh's vertex window.", {
+		meshName: meshMeta.name,
+		indexValue,
+		vertexStart: meshMeta.vertexStart,
+		vertexCount: meshMeta.vertexCount
+	});
+}
+/**
+* Reconstructs world-unit float32 positions from int16 quantized values:
+* `world = origin + (q + 32767) * scale`. No rotation — the Three scene uses Rhino's Z-up frame,
+* so vertices pass through as they arrived.
+*/
+function dequantizeInt16(q, origin, scale) {
+	const out = new Float32Array(q.length);
+	const ox = origin[0];
+	const oy = origin[1];
+	const oz = origin[2];
+	const sx = scale[0];
+	const sy = scale[1];
+	const sz = scale[2];
+	for (let i = 0; i < q.length; i += 3) {
+		out[i] = ox + (q[i] + 32767) * sx;
+		out[i + 1] = oy + (q[i + 1] + 32767) * sy;
+		out[i + 2] = oz + (q[i + 2] + 32767) * sz;
+	}
+	return out;
+}
 // src/parse/webdisplay/binary-parser.ts
 /** Second half of {@link parseBinaryMeshBatch}, for a caller that already holds the raw view. */
 function decodeRawMeshBatch(raw) {
@@ -831,6 +934,7 @@ function parseBinaryMeshBatchRaw(input) {
 	} catch (error) {
 		throw fail(`Failed to parse metadata JSON: ${error instanceof Error ? error.message : String(error)}`, { metadataLen });
 	}
+	if (!isMetadataShape(metadata)) throw fail("Metadata JSON must be an object whose materials and groups are arrays.", { metadataLen });
 	if (offset + 56 > bytes.byteLength) throw fail("Insufficient data to read geometry header.", {
 		expectedBytes: 56,
 		availableBytes: bytes.byteLength - offset,
@@ -921,6 +1025,12 @@ function parseBinaryMeshBatchRaw(input) {
 		colors
 	};
 }
+/** Missing `materials`/`groups` are allowed: the JSON envelope's copies fill them in. */
+function isMetadataShape(value) {
+	if (!isObject(value)) return false;
+	const { materials, groups } = value;
+	return (materials === void 0 || Array.isArray(materials)) && (groups === void 0 || Array.isArray(groups));
+}
 // src/parse/webdisplay/closed-solid.ts
 /**
 * True when every member of a geometry is a closed, consistently wound, outward-facing triangle
@@ -2284,84 +2394,6 @@ function applyVertexColorSRGBDecode(material) {
 			#endif`);
 	});
 }
-// src/parse/webdisplay/batch/metadata.ts
-function metadataFail(message, context) {
-	return new VisualizationError(message, ErrorCodes.VALIDATION_ERROR, { context });
-}
-/**
-* Validates the batch's group/mesh metadata against the decoded geometry buffers before any of it
-* is used arithmetically. Throws on the first inconsistency — out-of-range `materialId`,
-* non-integer or negative offsets/counts, or a vertex/index window that overruns the buffers — so
-* malformed or version-skewed metadata fails the parse loudly instead of corrupting the render.
-*/
-function validateGroupMetadata(groups, materialCount, totalVertexCount, totalIndexCount) {
-	for (const group of groups) {
-		if (!Number.isInteger(group.materialId) || group.materialId < 0 || group.materialId >= materialCount) throw metadataFail("Group materialId out of range of the materials array.", {
-			materialId: group.materialId,
-			materialCount
-		});
-		for (const mesh of group.meshes) {
-			const fields = {
-				vertexStart: mesh.vertexStart,
-				vertexCount: mesh.vertexCount,
-				indexStart: mesh.indexStart,
-				indexCount: mesh.indexCount
-			};
-			for (const [field, value] of Object.entries(fields)) if (!Number.isInteger(value) || value < 0) throw metadataFail(`Mesh metadata field "${field}" must be a non-negative integer.`, {
-				meshName: mesh.name,
-				field,
-				value
-			});
-			if (mesh.vertexStart + mesh.vertexCount > totalVertexCount) throw metadataFail("Mesh vertex window exceeds the batch vertex buffer.", {
-				meshName: mesh.name,
-				vertexStart: mesh.vertexStart,
-				vertexCount: mesh.vertexCount,
-				totalVertexCount
-			});
-			if (mesh.indexStart + mesh.indexCount > totalIndexCount) throw metadataFail("Mesh index window exceeds the batch index buffer.", {
-				meshName: mesh.name,
-				indexStart: mesh.indexStart,
-				indexCount: mesh.indexCount,
-				totalIndexCount
-			});
-		}
-	}
-}
-/**
-* Error for an index outside its mesh's declared vertex window
-* `[vertexStart, vertexStart + vertexCount)`. Rebasing (`index - vertexStart`) writes into an
-* unsigned array, so an out-of-window index would otherwise wrap to ~4 billion and corrupt the
-* geometry. Range checks live inline in the copy loops (a function call per index measured
-* noticeably slower at millions of indices) — this only builds the failure.
-*/
-function indexOutOfWindow(indexValue, meshMeta) {
-	return metadataFail("Index references a vertex outside its mesh's vertex window.", {
-		meshName: meshMeta.name,
-		indexValue,
-		vertexStart: meshMeta.vertexStart,
-		vertexCount: meshMeta.vertexCount
-	});
-}
-/**
-* Reconstructs world-unit float32 positions from int16 quantized values:
-* `world = origin + (q + 32767) * scale`. No rotation — the Three scene uses Rhino's Z-up frame,
-* so vertices pass through as they arrived.
-*/
-function dequantizeInt16(q, origin, scale) {
-	const out = new Float32Array(q.length);
-	const ox = origin[0];
-	const oy = origin[1];
-	const oz = origin[2];
-	const sx = scale[0];
-	const sy = scale[1];
-	const sz = scale[2];
-	for (let i = 0; i < q.length; i += 3) {
-		out[i] = ox + (q[i] + 32767) * sx;
-		out[i + 1] = oy + (q[i + 1] + 32767) * sy;
-		out[i + 2] = oz + (q[i + 2] + 32767) * sz;
-	}
-	return out;
-}
 // src/parse/webdisplay/batch/merge.ts
 /**
 * Split a material group into one sub-group per layer, preserving mesh order.
@@ -2751,7 +2783,7 @@ function buildMeshesFromParsed(parsed, opts) {
 	const materialsSrc = parsed.metadata.materials ?? fallback?.materials ?? [];
 	const groups = parsed.metadata.groups ?? fallback?.groups ?? [];
 	const isFloat32 = (parsed.flags & 1) !== 0;
-	validateGroupMetadata(groups, materialsSrc.length, parsed.vertices.length / 3, parsed.indices.length);
+	validateBatchMetadata(materialsSrc, groups, parsed.vertices.length / 3, parsed.indices.length);
 	const worldVertices = isFloat32 ? parsed.vertices : dequantizeInt16(parsed.vertices, parsed.origin, parsed.scale);
 	if (debug) {
 		const wireBytes = parsed.vertices.byteLength + parsed.indices.byteLength;
@@ -2839,7 +2871,7 @@ function buildFromFinishedCache(container, opts) {
 	const { jobs, jobRefs } = planJobs(groups, opts.mergeByMaterial);
 	const cached = getFinishedBatch(container.geometryBlob, jobs);
 	if (!cached) return null;
-	validateGroupMetadata(groups, materialsSrc.length, cached.vertexCount, cached.indexCount);
+	validateBatchMetadata(materialsSrc, groups, cached.vertexCount, cached.indexCount);
 	return meshesFromBuilt(cached, jobRefs, materialsSrc, opts.material);
 }
 /** One job per merged group or per unmerged mesh, with a parallel ref list to unwrap results by index. */
@@ -2891,7 +2923,7 @@ async function tryBuildViaAssembly(opened, opts) {
 	if (indexCount / 3 < 5e4) return null;
 	const materialsSrc = raw.metadata.materials ?? opts.fallback?.materials ?? [];
 	const groups = raw.metadata.groups ?? opts.fallback?.groups ?? [];
-	validateGroupMetadata(groups, materialsSrc.length, raw.vertexCount, indexCount);
+	validateBatchMetadata(materialsSrc, groups, raw.vertexCount, indexCount);
 	const { jobs, jobRefs } = planJobs(groups, opts.mergeByMaterial);
 	const assembled = await assemble(raw, jobs, opened.source);
 	if (!assembled) {
@@ -2931,7 +2963,15 @@ async function assemble(raw, jobs, source) {
 		colors: raw.colors,
 		jobs
 	};
-	if (!worker) return assembleGeometries(input).map((geometry, i) => finishGeometry(geometry, jobs[i].windows));
+	if (!worker) {
+		let geometries;
+		try {
+			geometries = assembleGeometries(input);
+		} catch (error) {
+			throw new VisualizationError(error instanceof Error ? error.message : String(error), ErrorCodes.VALIDATION_ERROR, { originalError: error instanceof Error ? error : void 0 });
+		}
+		return geometries.map((geometry, i) => finishGeometry(geometry, jobs[i].windows));
+	}
 	if (!ownsBuffer(raw, source)) {
 		input.vertexData = raw.vertexData.slice();
 		input.indexData = raw.indexData.slice();