@woosh/meep-engine 3.9.0 → 3.11.0

package/src/shade/renderer/scene/serialization/deserialize_scene.js

@@ -1,521 +1,531 @@
-import { assert } from "../../../../core/assert.js";
-import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
-import { BinaryDataType } from "../../../../core/binary/type/BinaryDataType.js";
-import LinearModifier from "../../../../core/model/stat/LinearModifier.js";
-import { Sampler2D } from "../../../../engine/graphics/texture/sampler/Sampler2D.js";
-import { MeshletGeometry } from "../../geometry/MeshletGeometry.js";
-import { MeshletGeometrySerializationAdapter } from "../../geometry/MeshletGeometrySerializationAdapter.js";
-import { DirectionalLight } from "../../light/model/DirectionalLight.js";
-import { PointLight } from "../../light/model/PointLight.js";
-import { SpotLight } from "../../light/model/SpotLight.js";
-import { StandardShadeMaterial } from "../../material/StandardShadeMaterial.js";
-import { Mesh } from "../Mesh.js";
-import { ShadeTexture } from "../../texture/ShadeTexture.js";
-import { ShadeImage } from "../../texture/source/ShadeImage.js";
-import { decode_image_source_hdr } from "./decode_image_source_hdr.js";
-import { LightTypeSerializationIndex } from "./LightTypeSerializationIndex.js";
-import { STANDARD_MATERIAL_SERIALIZED_BYTE_SIZE } from "./STANDARD_MATERIAL_SERIALIZED_BYTE_SIZE.js";
-
-const NULL_TEXTURE_INDEX = 0xFFFFFFFF;
-
-/**
- * Reverse lookup: index → BinaryDataType string
- * @type {Object<number, string>}
- */
-const DataTypeFromIndex = {
-    0: BinaryDataType.Uint8,
-    1: BinaryDataType.Uint16,
-    2: BinaryDataType.Uint32,
-    3: BinaryDataType.Int8,
-    4: BinaryDataType.Int16,
-    5: BinaryDataType.Int32,
-    6: BinaryDataType.Float32,
-    7: BinaryDataType.Float64,
-    8: BinaryDataType.Float16,
-};
-
-/**
- * Decode a uint32 back into a Color (inverse of Color.toUint32 / rgb2uint32).
- *
- * Format v2+, written with meep-engine >= 2.157 whose rgb2uint32 is the straight layout:
- *   bits 31..24 = R,  23..16 = G,  15..8 = B,  7..0 = A
- *
- * @param {Color} color
- * @param {number} v uint32 value
- */
-function color_from_uint32(color, v) {
-    const a = (v & 0xFF) / 255;
-    const b = ((v >>> 8) & 0xFF) / 255;
-    const g = ((v >>> 16) & 0xFF) / 255;
-    const r = ((v >>> 24) & 0xFF) / 255;
-
-    color.set(r, g, b, a);
-}
-
-
-/**
- * Read raw AVIF bytes from the buffer without decoding.
- *
- * @param {BinaryBuffer} buffer
- * @returns {ArrayBuffer}
- */
-function read_image_source_bytes(buffer) {
-    const byte_length = buffer.readUint32();
-
-    const slice = buffer.data.slice(buffer.position, buffer.position + byte_length);
-
-    // advance cursor
-    buffer.skip(byte_length);
-
-    return slice;
-}
-
-/**
- * Decode an AVIF blob to an ImageBitmap using the browser's HW-accelerated decoder.
- * Used for LDR (Uint8) image sources.
- *
- * @param {ArrayBuffer} avif_buffer
- * @returns {Promise<ImageBitmap>}
- */
-async function decode_image_source_default(avif_buffer) {
-    const blob = new Blob([avif_buffer], { type: "image/avif" });
-    return createImageBitmap(blob, {
-        colorSpaceConversion: 'none',
-        premultiplyAlpha: 'none',
-    });
-}
-
-/**
- * Scan the raw ISOBMFF structure of the AVIF to detect PQ HDR Transfer Characteristics (ST 2084)
- * @param {ArrayBuffer} array_buffer
- * @returns {boolean}
- */
-function is_avif_hdr(array_buffer) {
-    const bytes = new Uint8Array(array_buffer);
-    // Scan for 'colr' (c, o, l, r) followed by 'nclx'
-    for (let i = 0; i < bytes.length - 16; i++) {
-        // 'colr'
-        if (bytes[i] === 99 && bytes[i + 1] === 111 && bytes[i + 2] === 108 && bytes[i + 3] === 114) {
-            // 'nclx'
-            if (bytes[i + 4] === 110 && bytes[i + 5] === 99 && bytes[i + 6] === 108 && bytes[i + 7] === 120) {
-                // transfer_characteristics is bytes 10 and 11 after 'colr'
-                const transfer_characteristics = (bytes[i + 10] << 8) | bytes[i + 11];
-                if (transfer_characteristics === 16) { // PQ (ST 2084)
-                    return true;
-                }
-            }
-        }
-    }
-    return false;
-}
-
-/**
- * @param {BinaryBuffer} buffer
- * @param {ShadeTexture[]} textures  indexed texture table
- * @param {StandardShadeMaterial} material
- */
-function material_read_standard(buffer, material, textures) {
-    // texture indices
-    const albedo_index = buffer.readUint32();
-    const normal_index = buffer.readUint32();
-    const orm_index = buffer.readUint32();
-    const emissive_index = buffer.readUint32();
-
-    material.texture_albedo = albedo_index !== NULL_TEXTURE_INDEX ? textures[albedo_index] : undefined;
-    material.texture_normal = normal_index !== NULL_TEXTURE_INDEX ? textures[normal_index] : undefined;
-    material.texture_orm = orm_index !== NULL_TEXTURE_INDEX ? textures[orm_index] : undefined;
-    material.texture_emissive = emissive_index !== NULL_TEXTURE_INDEX ? textures[emissive_index] : undefined;
-
-    // colors and factors as floats (HDR-safe), including transmission/ior
-
-    material.diffuse_color.set(
-        buffer.readFloat32(),
-        buffer.readFloat32(),
-        buffer.readFloat32(),
-        buffer.readFloat32()
-    );
-
-    material.roughness_factor = buffer.readFloat32();
-    material.metallic_factor = buffer.readFloat32();
-
-    material.emissive_factor.set(
-        buffer.readFloat32(),
-        buffer.readFloat32(),
-        buffer.readFloat32(),
-        buffer.readFloat32()
-    );
-
-    material.transmission_factor = buffer.readFloat32();
-    material.ior_factor = buffer.readFloat32();
-
-    const ambient_a = buffer.readFloat32();
-    const ambient_b = buffer.readFloat32();
-    material.ambient_factors = new LinearModifier(ambient_a, ambient_b);
-}
-
-/**
- * @param {BinaryBuffer} buffer
- * @returns {Light}
- */
-function deserialize_light(buffer) {
-    const light_type = buffer.readUint8();
-
-    let light;
-
-    if (light_type === LightTypeSerializationIndex.DirectionalLight) {
-        light = new DirectionalLight();
-    } else if (light_type === LightTypeSerializationIndex.PointLight) {
-        light = new PointLight();
-    } else if (light_type === LightTypeSerializationIndex.SpotLight) {
-        light = new SpotLight();
-    } else {
-        throw new Error(`Unsupported light type: ${light_type}`);
-    }
-
-    const light_matrix = new Float32Array(16);
-    buffer.readFloat32Array(light_matrix, 0, 16);
-    light.transform_global.fromMatrix(light_matrix);
-
-    light.intensity = buffer.readFloat32();
-
-    const color_uint32 = buffer.readUint32();
-    color_from_uint32(light.color, color_uint32);
-
-    light.radius = buffer.readFloat32();
-    light.near_clip_distance = buffer.readFloat32();
-
-    if (light_type === LightTypeSerializationIndex.DirectionalLight) {
-        // no extra data
-    } else if (light_type === LightTypeSerializationIndex.PointLight) {
-        light.distance = buffer.readFloat32();
-    } else if (light_type === LightTypeSerializationIndex.SpotLight) {
-        light.distance = buffer.readFloat32();
-        light.angle = buffer.readFloat32();
-        light.penumbra = buffer.readFloat32();
-    }
-
-    return light;
-}
-
-/**
- * Deserialize a scene from a BinaryBuffer that was produced by {@link serialize_scene}.
- *
- * @param {BinaryBuffer} buffer  positioned at the start of the serialized data
- * @param {Scene} scene  an empty Scene instance to populate
- * @returns {Promise<Scene>}
- */
-export async function deserialize_scene(buffer, scene) {
-
-    const adapter_geometry = new MeshletGeometrySerializationAdapter();
-
-
-    const format_tag = buffer.readASCIICharacters(5);
-    if (format_tag !== "SHADE") {
-        throw new Error(`Unsupported wrong format tag: "${format_tag}", expected "SHADE"`);
-    }
-
-    // No backward compatibility by design: refusing an old file beats silently loading
-    // wrong data. v1 predates the meep 2.157 color-encoding fix, the explicit
-    // texture→image indices and the float material factors — re-export old scenes.
-    const format_version = buffer.readUint32();
-    if (format_version !== 2) {
-        throw new Error(`Unsupported format version: ${format_version}, expected 2`);
-    }
-
-    // ── Meshes (header pass — geometry/material indices are resolved later) ──
-
-    const mesh_count = buffer.readUint32();
-
-    /**
-     * Temporary records for meshes before geometry/material resolution
-     * @type {{name: string, material_index: number, geometry_index: number, transform: Float32Array}[]}
-     */
-    const mesh_records = [];
-
-    for (let i = 0; i < mesh_count; i++) {
-        const name = buffer.readUTF8String();
-        const material_index = buffer.readUint32();
-        const geometry_index = buffer.readUint32();
-
-        const transform = new Float32Array(16);
-        buffer.readFloat32Array(transform, 0, 16);
-
-        mesh_records.push({ name, material_index, geometry_index, transform });
-    }
-
-    // ── Geometries ──
-
-    const geometry_count = buffer.readUint32();
-
-    /** @type {MeshletGeometry[]} */
-    const geometries = [];
-
-    for (let i = 0; i < geometry_count; i++) {
-        const geometry = new MeshletGeometry();
-        adapter_geometry.deserialize(buffer, geometry);
-        geometries.push(geometry);
-    }
-
-    // ── Materials (first pass — texture indices stored, resolved after textures) ──
-
-    const material_count = buffer.readUint32();
-
-    /**
-     * Temporary records: material objects + the buffer state needed for
-     * the standard-material texture fields (which reference textures by index).
-     *
-     * We read everything except the standard fields into the material now,
-     * and defer the standard fields until we have the texture array.
-     */
-
-    /** @type {{ material: StandardShadeMaterial, buffer_position: number }[]} */
-    const material_records = [];
-
-    for (let i = 0; i < material_count; i++) {
-        const material = new StandardShadeMaterial();
-        material.name = buffer.readUTF8String();
-        material.transparency_mode = buffer.readUint32();
-        material.draw_mode = buffer.readUint32();
-        material.draw_side = buffer.readUint32();
-
-        // Remember position — we need textures resolved first
-        const pos = buffer.position;
-
-        // Skip past the standard material payload so we can continue reading the rest of the
-        // stream in order. The distance must match material_write_standard exactly (v2 layout,
-        // colours/factors as f32) — see STANDARD_MATERIAL_SERIALIZED_BYTE_SIZE.
-        buffer.position = pos + STANDARD_MATERIAL_SERIALIZED_BYTE_SIZE;
-
-        material_records.push({ material, buffer_position: pos });
-    }
-
-    // ── Textures (first pass — image link deferred) ──
-
-    const texture_count = buffer.readUint32();
-
-    /** @type {{ texture: ShadeTexture }[]} */
-    const texture_records = [];
-
-    for (let i = 0; i < texture_count; i++) {
-        const texture = new ShadeTexture();
-        texture.label = buffer.readUTF8String();
-        texture.flags = buffer.readUint32();
-
-        texture.dimensions = buffer.readUint8();
-
-        texture.minFilter = buffer.readUint8();
-        texture.magFilter = buffer.readUint8();
-        texture.mipmapFilter = buffer.readUint8();
-
-        texture.wrapS = buffer.readUint8();
-        texture.wrapT = buffer.readUint8();
-        texture.wrapR = buffer.readUint8();
-
-        texture.mipmapGenerationFilter = buffer.readUint32();
-
-        // explicit image reference — images are deduplicated, several textures may share one
-        const image_index = buffer.readUint32();
-
-        texture_records.push({ texture, image_index });
-    }
-
-    // ── Images ──
-
-    const image_count = buffer.readUint32();
-
-    /**
-     * Partially constructed images — source will be attached after image sources are decoded.
-     * @type {{ image: ShadeImage, source_index: number }[]}
-     */
-    const image_records = [];
-
-    for (let i = 0; i < image_count; i++) {
-        const width = buffer.readUint32();
-        const height = buffer.readUint32();
-        const depth = buffer.readUint32();
-        const source_index = buffer.readUint32();
-        const data_type_index = buffer.readUint32();
-        const channel_count = buffer.readUint32();
-        const flags = buffer.readUint32();
-
-        const normalized = (flags & 1) !== 0;
-        const data_type = DataTypeFromIndex[data_type_index];
-
-        const image = new ShadeImage();
-        image.width = width;
-        image.height = height;
-        image.depth = depth;
-        image.data_type = data_type;
-        image.channel_count = channel_count;
-        image.normalized = normalized;
-
-        const color_space_value = (flags >>> 4) & 0xF;
-        image.color_space = color_space_value;
-
-        image_records.push({ image, source_index });
-    }
-
-    // ── Image Sources (read raw AVIF blobs) ──
-
-    const source_count = buffer.readUint32();
-
-    /** @type {ArrayBuffer[]} */
-    const raw_source_buffers = [];
-
-    for (let i = 0; i < source_count; i++) {
-        raw_source_buffers.push(read_image_source_bytes(buffer));
-    }
-
-    // Decode all sources: HW path for LDR, WASM + inverse PQ for HDR
-    const image_source_promises = [];
-
-    for (let i = 0; i < source_count; i++) {
-        const buffer = raw_source_buffers[i];
-
-        const is_hdr = is_avif_hdr(buffer);
-
-        let p;
-        if (is_hdr) {
-            p = decode_image_source_hdr(buffer);
-        } else {
-            p = decode_image_source_default(buffer);
-        }
-
-        image_source_promises.push(p);
-    }
-
-    /** @type {(ImageBitmap|Sampler2D)[]} */
-    const image_sources = await Promise.all(image_source_promises);
-
-    // ── Link images → sources ──
-
-    /** @type {ShadeImage[]} */
-    const images = [];
-
-    for (const { image, source_index } of image_records) {
-        image.source = image_sources[source_index];
-
-        if (image.source && image.source.isSampler2D) {
-            image.channel_count = image.source.itemSize;
-            image.data_type = BinaryDataType.Float16; // TODO infer from data type if necessary
-        }
-
-        images.push(image);
-    }
-
-    // ── Link textures → images ──
-    // v2 carries an explicit image index per texture (images are deduplicated, several
-    // textures may share one). v1 assumed positional texture[i] → image[i], which only
-    // holds when no two textures share an image — kept for compatibility.
-
-    /** @type {ShadeTexture[]} */
-    const textures = [];
-
-    for (let i = 0; i < texture_count; i++) {
-        const { texture, image_index } = texture_records[i];
-
-        const image = images[image_index];
-        assert.defined(image, `image for texture ${i} (image_index ${image_index})`);
-
-        // ShadeTexture.from() is the factory that sets the private #image field
-        // We reconstruct via the factory since #image is private
-        const rebuilt = ShadeTexture.from(image);
-
-        // Copy all the non-image properties we read from the stream
-        rebuilt.label = texture.label;
-        rebuilt.flags = texture.flags;
-        rebuilt.dimensions = texture.dimensions;
-        rebuilt.minFilter = texture.minFilter;
-        rebuilt.magFilter = texture.magFilter;
-        rebuilt.mipmapFilter = texture.mipmapFilter;
-        rebuilt.wrapS = texture.wrapS;
-        rebuilt.wrapT = texture.wrapT;
-        rebuilt.wrapR = texture.wrapR;
-        rebuilt.mipmapGenerationFilter = texture.mipmapGenerationFilter;
-
-        textures.push(rebuilt);
-    }
-
-    // ── Resolve material standard fields (now that textures exist) ──
-
-    /** @type {StandardShadeMaterial[]} */
-    const materials = [];
-
-    for (const { material, buffer_position } of material_records) {
-        const saved_position = buffer.position;
-        buffer.position = buffer_position;
-
-        material_read_standard(buffer, material, textures);
-
-        buffer.position = saved_position;
-        materials.push(material);
-    }
-
-    // ── Lighting ──
-
-    // Environment texture
-    const environment_index = buffer.readUint32();
-    if (environment_index !== NULL_TEXTURE_INDEX) {
-        scene.lights.environment = textures[environment_index];
-    }
-
-    // Light elements
-    const light_count = buffer.readUint32();
-    for (let i = 0; i < light_count; i++) {
-        const light = deserialize_light(buffer);
-        scene.lights.add(light);
-    }
-
-    // ── Assemble Meshes ──
-
-    for (const record of mesh_records) {
-        const mesh = new Mesh();
-        mesh.name = record.name;
-        mesh.geometry = geometries[record.geometry_index];
-        mesh.material = materials[record.material_index];
-        // serialized transform is world-space; meshes deserialize without a parent, so
-        // local == global. Setting only transform_global would leave transform_local at
-        // identity, and the next updateMatrices() / GPU hierarchy pass (which recompose
-        // global from local TRS) would snap the mesh to the origin.
-        mesh.transform_local.fromMatrix(record.transform);
-        mesh.updateMatrices();
-
-        // Compute world-space bounds from geometry bounds + transform
-        mesh.updateBoundsBasic();
-
-        scene.instances.add(mesh);
-    }
-
-    return scene;
-}
-
-/**
- * Fetch a serialized scene binary from a URL and deserialize it into the given Scene.
- * Convenience wrapper for testing.
- *
- * @param {string} url   URL pointing to the binary blob produced by serialize_scene
- * @param {Scene} scene  an empty Scene instance to populate
- * @returns {Promise<Scene>}
- */
-export async function load_scene_from_url(url, scene) {
-    assert.defined(scene, 'scene');
-    assert.notNull(scene, 'scene');
-    assert.isObject(scene, 'scene');
-    assert.equal(scene.isScene, true, 'scene.isScene !== true');
-
-    assert.isString(url, 'url');
-
-    const response = await fetch(url);
-
-    if (!response.ok) {
-        throw new Error(`Failed to fetch scene: ${response.status} ${response.statusText}`);
-    }
-
-    const array_buffer = await response.arrayBuffer();
-
-    assert.defined(array_buffer, 'array_buffer');
-
-    const buffer = BinaryBuffer.fromArrayBuffer(array_buffer);
-
-    return deserialize_scene(buffer, scene);
-}
+import { assert } from "../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+import { BinaryDataType } from "../../../../core/binary/type/BinaryDataType.js";
+import LinearModifier from "../../../../core/model/stat/LinearModifier.js";
+import { Sampler2D } from "../../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { MeshletGeometry } from "../../geometry/MeshletGeometry.js";
+import { MeshletGeometrySerializationAdapter } from "../../geometry/MeshletGeometrySerializationAdapter.js";
+import { DirectionalLight } from "../../light/model/DirectionalLight.js";
+import { PointLight } from "../../light/model/PointLight.js";
+import { SpotLight } from "../../light/model/SpotLight.js";
+import { StandardShadeMaterial } from "../../material/StandardShadeMaterial.js";
+import { Mesh } from "../Mesh.js";
+import { ShadeTexture } from "../../texture/ShadeTexture.js";
+import { ShadeImage } from "../../texture/source/ShadeImage.js";
+import { avif_to_sampler2d } from "../../../../avif/native/api/avif_to_sampler2d.js";
+import { decode_image_source_hdr } from "./decode_image_source_hdr.js";
+import { LightTypeSerializationIndex } from "./LightTypeSerializationIndex.js";
+import { STANDARD_MATERIAL_SERIALIZED_BYTE_SIZE } from "./STANDARD_MATERIAL_SERIALIZED_BYTE_SIZE.js";
+
+const NULL_TEXTURE_INDEX = 0xFFFFFFFF;
+
+/**
+ * Reverse lookup: index → BinaryDataType string
+ * @type {Object<number, string>}
+ */
+const DataTypeFromIndex = {
+    0: BinaryDataType.Uint8,
+    1: BinaryDataType.Uint16,
+    2: BinaryDataType.Uint32,
+    3: BinaryDataType.Int8,
+    4: BinaryDataType.Int16,
+    5: BinaryDataType.Int32,
+    6: BinaryDataType.Float32,
+    7: BinaryDataType.Float64,
+    8: BinaryDataType.Float16,
+};
+
+/**
+ * Decode a uint32 back into a Color (inverse of Color.toUint32 / rgb_to_uint32).
+ *
+ * Format v2+, written with meep-engine >= 2.157 whose rgb_to_uint32 is the straight layout:
+ *   bits 31..24 = R,  23..16 = G,  15..8 = B,  7..0 = A
+ *
+ * @param {Color} color
+ * @param {number} v uint32 value
+ */
+function color_from_uint32(color, v) {
+    const a = (v & 0xFF) / 255;
+    const b = ((v >>> 8) & 0xFF) / 255;
+    const g = ((v >>> 16) & 0xFF) / 255;
+    const r = ((v >>> 24) & 0xFF) / 255;
+
+    color.set(r, g, b, a);
+}
+
+
+/**
+ * Read raw AVIF bytes from the buffer without decoding.
+ *
+ * @param {BinaryBuffer} buffer
+ * @returns {ArrayBuffer}
+ */
+function read_image_source_bytes(buffer) {
+    const byte_length = buffer.readUint32();
+
+    const slice = buffer.data.slice(buffer.position, buffer.position + byte_length);
+
+    // advance cursor
+    buffer.skip(byte_length);
+
+    return slice;
+}
+
+/**
+ * Decode an AVIF blob for LDR (Uint8) image sources.
+ *
+ * Prefers the browser's own decoder, which is hardware accelerated and hands back an ImageBitmap
+ * the GPU upload path can take directly. Where there is no such decoder — node, a worker without
+ * `createImageBitmap`, anything that is not a browser — meep's own decoder produces a sampler
+ * instead, which the same path already handles because the HDR sources arrive that way.
+ *
+ * @param {ArrayBuffer} avif_buffer
+ * @returns {Promise<ImageBitmap|Sampler2D>}
+ */
+async function decode_image_source_default(avif_buffer) {
+    if (typeof createImageBitmap === "undefined" || typeof Blob === "undefined") {
+        return avif_to_sampler2d(avif_buffer);
+    }
+
+    const blob = new Blob([avif_buffer], { type: "image/avif" });
+    return createImageBitmap(blob, {
+        colorSpaceConversion: 'none',
+        premultiplyAlpha: 'none',
+    });
+}
+
+/**
+ * Scan the raw ISOBMFF structure of the AVIF to detect PQ HDR Transfer Characteristics (ST 2084)
+ * @param {ArrayBuffer} array_buffer
+ * @returns {boolean}
+ */
+function is_avif_hdr(array_buffer) {
+    const bytes = new Uint8Array(array_buffer);
+    // Scan for 'colr' (c, o, l, r) followed by 'nclx'
+    for (let i = 0; i < bytes.length - 16; i++) {
+        // 'colr'
+        if (bytes[i] === 99 && bytes[i + 1] === 111 && bytes[i + 2] === 108 && bytes[i + 3] === 114) {
+            // 'nclx'
+            if (bytes[i + 4] === 110 && bytes[i + 5] === 99 && bytes[i + 6] === 108 && bytes[i + 7] === 120) {
+                // transfer_characteristics is bytes 10 and 11 after 'colr'
+                const transfer_characteristics = (bytes[i + 10] << 8) | bytes[i + 11];
+                if (transfer_characteristics === 16) { // PQ (ST 2084)
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+
+/**
+ * @param {BinaryBuffer} buffer
+ * @param {ShadeTexture[]} textures  indexed texture table
+ * @param {StandardShadeMaterial} material
+ */
+function material_read_standard(buffer, material, textures) {
+    // texture indices
+    const albedo_index = buffer.readUint32();
+    const normal_index = buffer.readUint32();
+    const orm_index = buffer.readUint32();
+    const emissive_index = buffer.readUint32();
+
+    material.texture_albedo = albedo_index !== NULL_TEXTURE_INDEX ? textures[albedo_index] : undefined;
+    material.texture_normal = normal_index !== NULL_TEXTURE_INDEX ? textures[normal_index] : undefined;
+    material.texture_orm = orm_index !== NULL_TEXTURE_INDEX ? textures[orm_index] : undefined;
+    material.texture_emissive = emissive_index !== NULL_TEXTURE_INDEX ? textures[emissive_index] : undefined;
+
+    // colors and factors as floats (HDR-safe), including transmission/ior
+
+    material.diffuse_color.set(
+        buffer.readFloat32(),
+        buffer.readFloat32(),
+        buffer.readFloat32(),
+        buffer.readFloat32()
+    );
+
+    material.roughness_factor = buffer.readFloat32();
+    material.metallic_factor = buffer.readFloat32();
+
+    material.emissive_factor.set(
+        buffer.readFloat32(),
+        buffer.readFloat32(),
+        buffer.readFloat32(),
+        buffer.readFloat32()
+    );
+
+    material.transmission_factor = buffer.readFloat32();
+    material.ior_factor = buffer.readFloat32();
+
+    const ambient_a = buffer.readFloat32();
+    const ambient_b = buffer.readFloat32();
+    material.ambient_factors = new LinearModifier(ambient_a, ambient_b);
+}
+
+/**
+ * @param {BinaryBuffer} buffer
+ * @returns {Light}
+ */
+function deserialize_light(buffer) {
+    const light_type = buffer.readUint8();
+
+    let light;
+
+    if (light_type === LightTypeSerializationIndex.DirectionalLight) {
+        light = new DirectionalLight();
+    } else if (light_type === LightTypeSerializationIndex.PointLight) {
+        light = new PointLight();
+    } else if (light_type === LightTypeSerializationIndex.SpotLight) {
+        light = new SpotLight();
+    } else {
+        throw new Error(`Unsupported light type: ${light_type}`);
+    }
+
+    const light_matrix = new Float32Array(16);
+    buffer.readFloat32Array(light_matrix, 0, 16);
+    light.transform_global.fromMatrix(light_matrix);
+
+    light.intensity = buffer.readFloat32();
+
+    const color_uint32 = buffer.readUint32();
+    color_from_uint32(light.color, color_uint32);
+
+    light.radius = buffer.readFloat32();
+    light.near_clip_distance = buffer.readFloat32();
+
+    if (light_type === LightTypeSerializationIndex.DirectionalLight) {
+        // no extra data
+    } else if (light_type === LightTypeSerializationIndex.PointLight) {
+        light.distance = buffer.readFloat32();
+    } else if (light_type === LightTypeSerializationIndex.SpotLight) {
+        light.distance = buffer.readFloat32();
+        light.angle = buffer.readFloat32();
+        light.penumbra = buffer.readFloat32();
+    }
+
+    return light;
+}
+
+/**
+ * Deserialize a scene from a BinaryBuffer that was produced by {@link serialize_scene}.
+ *
+ * @param {BinaryBuffer} buffer  positioned at the start of the serialized data
+ * @param {Scene} scene  an empty Scene instance to populate
+ * @returns {Promise<Scene>}
+ */
+export async function deserialize_scene(buffer, scene) {
+
+    const adapter_geometry = new MeshletGeometrySerializationAdapter();
+
+
+    const format_tag = buffer.readASCIICharacters(5);
+    if (format_tag !== "SHADE") {
+        throw new Error(`Unsupported wrong format tag: "${format_tag}", expected "SHADE"`);
+    }
+
+    // No backward compatibility by design: refusing an old file beats silently loading
+    // wrong data. v1 predates the meep 2.157 color-encoding fix, the explicit
+    // texture→image indices and the float material factors — re-export old scenes.
+    const format_version = buffer.readUint32();
+    if (format_version !== 2) {
+        throw new Error(`Unsupported format version: ${format_version}, expected 2`);
+    }
+
+    // ── Meshes (header pass — geometry/material indices are resolved later) ──
+
+    const mesh_count = buffer.readUint32();
+
+    /**
+     * Temporary records for meshes before geometry/material resolution
+     * @type {{name: string, material_index: number, geometry_index: number, transform: Float32Array}[]}
+     */
+    const mesh_records = [];
+
+    for (let i = 0; i < mesh_count; i++) {
+        const name = buffer.readUTF8String();
+        const material_index = buffer.readUint32();
+        const geometry_index = buffer.readUint32();
+
+        const transform = new Float32Array(16);
+        buffer.readFloat32Array(transform, 0, 16);
+
+        mesh_records.push({ name, material_index, geometry_index, transform });
+    }
+
+    // ── Geometries ──
+
+    const geometry_count = buffer.readUint32();
+
+    /** @type {MeshletGeometry[]} */
+    const geometries = [];
+
+    for (let i = 0; i < geometry_count; i++) {
+        const geometry = new MeshletGeometry();
+        adapter_geometry.deserialize(buffer, geometry);
+        geometries.push(geometry);
+    }
+
+    // ── Materials (first pass — texture indices stored, resolved after textures) ──
+
+    const material_count = buffer.readUint32();
+
+    /**
+     * Temporary records: material objects + the buffer state needed for
+     * the standard-material texture fields (which reference textures by index).
+     *
+     * We read everything except the standard fields into the material now,
+     * and defer the standard fields until we have the texture array.
+     */
+
+    /** @type {{ material: StandardShadeMaterial, buffer_position: number }[]} */
+    const material_records = [];
+
+    for (let i = 0; i < material_count; i++) {
+        const material = new StandardShadeMaterial();
+        material.name = buffer.readUTF8String();
+        material.transparency_mode = buffer.readUint32();
+        material.draw_mode = buffer.readUint32();
+        material.draw_side = buffer.readUint32();
+
+        // Remember position — we need textures resolved first
+        const pos = buffer.position;
+
+        // Skip past the standard material payload so we can continue reading the rest of the
+        // stream in order. The distance must match material_write_standard exactly (v2 layout,
+        // colours/factors as f32) — see STANDARD_MATERIAL_SERIALIZED_BYTE_SIZE.
+        buffer.position = pos + STANDARD_MATERIAL_SERIALIZED_BYTE_SIZE;
+
+        material_records.push({ material, buffer_position: pos });
+    }
+
+    // ── Textures (first pass — image link deferred) ──
+
+    const texture_count = buffer.readUint32();
+
+    /** @type {{ texture: ShadeTexture }[]} */
+    const texture_records = [];
+
+    for (let i = 0; i < texture_count; i++) {
+        const texture = new ShadeTexture();
+        texture.label = buffer.readUTF8String();
+        texture.flags = buffer.readUint32();
+
+        texture.dimensions = buffer.readUint8();
+
+        texture.minFilter = buffer.readUint8();
+        texture.magFilter = buffer.readUint8();
+        texture.mipmapFilter = buffer.readUint8();
+
+        texture.wrapS = buffer.readUint8();
+        texture.wrapT = buffer.readUint8();
+        texture.wrapR = buffer.readUint8();
+
+        texture.mipmapGenerationFilter = buffer.readUint32();
+
+        // explicit image reference — images are deduplicated, several textures may share one
+        const image_index = buffer.readUint32();
+
+        texture_records.push({ texture, image_index });
+    }
+
+    // ── Images ──
+
+    const image_count = buffer.readUint32();
+
+    /**
+     * Partially constructed images — source will be attached after image sources are decoded.
+     * @type {{ image: ShadeImage, source_index: number }[]}
+     */
+    const image_records = [];
+
+    for (let i = 0; i < image_count; i++) {
+        const width = buffer.readUint32();
+        const height = buffer.readUint32();
+        const depth = buffer.readUint32();
+        const source_index = buffer.readUint32();
+        const data_type_index = buffer.readUint32();
+        const channel_count = buffer.readUint32();
+        const flags = buffer.readUint32();
+
+        const normalized = (flags & 1) !== 0;
+        const data_type = DataTypeFromIndex[data_type_index];
+
+        const image = new ShadeImage();
+        image.width = width;
+        image.height = height;
+        image.depth = depth;
+        image.data_type = data_type;
+        image.channel_count = channel_count;
+        image.normalized = normalized;
+
+        const color_space_value = (flags >>> 4) & 0xF;
+        image.color_space = color_space_value;
+
+        image_records.push({ image, source_index });
+    }
+
+    // ── Image Sources (read raw AVIF blobs) ──
+
+    const source_count = buffer.readUint32();
+
+    /** @type {ArrayBuffer[]} */
+    const raw_source_buffers = [];
+
+    for (let i = 0; i < source_count; i++) {
+        raw_source_buffers.push(read_image_source_bytes(buffer));
+    }
+
+    // Decode all sources: the browser's decoder for LDR where there is one, meep's own — through
+    // the inverse transfer function — for HDR
+    const image_source_promises = [];
+
+    for (let i = 0; i < source_count; i++) {
+        const buffer = raw_source_buffers[i];
+
+        const is_hdr = is_avif_hdr(buffer);
+
+        let p;
+        if (is_hdr) {
+            p = decode_image_source_hdr(buffer);
+        } else {
+            p = decode_image_source_default(buffer);
+        }
+
+        image_source_promises.push(p);
+    }
+
+    /** @type {(ImageBitmap|Sampler2D)[]} */
+    const image_sources = await Promise.all(image_source_promises);
+
+    // ── Link images → sources ──
+
+    /** @type {ShadeImage[]} */
+    const images = [];
+
+    for (const { image, source_index } of image_records) {
+        image.source = image_sources[source_index];
+
+        if (image.source && image.source.isSampler2D) {
+            image.channel_count = image.source.itemSize;
+            image.data_type = BinaryDataType.Float16; // TODO infer from data type if necessary
+        }
+
+        images.push(image);
+    }
+
+    // ── Link textures → images ──
+    // v2 carries an explicit image index per texture (images are deduplicated, several
+    // textures may share one). v1 assumed positional texture[i] → image[i], which only
+    // holds when no two textures share an image — kept for compatibility.
+
+    /** @type {ShadeTexture[]} */
+    const textures = [];
+
+    for (let i = 0; i < texture_count; i++) {
+        const { texture, image_index } = texture_records[i];
+
+        const image = images[image_index];
+        assert.defined(image, `image for texture ${i} (image_index ${image_index})`);
+
+        // ShadeTexture.from() is the factory that sets the private #image field
+        // We reconstruct via the factory since #image is private
+        const rebuilt = ShadeTexture.from(image);
+
+        // Copy all the non-image properties we read from the stream
+        rebuilt.label = texture.label;
+        rebuilt.flags = texture.flags;
+        rebuilt.dimensions = texture.dimensions;
+        rebuilt.minFilter = texture.minFilter;
+        rebuilt.magFilter = texture.magFilter;
+        rebuilt.mipmapFilter = texture.mipmapFilter;
+        rebuilt.wrapS = texture.wrapS;
+        rebuilt.wrapT = texture.wrapT;
+        rebuilt.wrapR = texture.wrapR;
+        rebuilt.mipmapGenerationFilter = texture.mipmapGenerationFilter;
+
+        textures.push(rebuilt);
+    }
+
+    // ── Resolve material standard fields (now that textures exist) ──
+
+    /** @type {StandardShadeMaterial[]} */
+    const materials = [];
+
+    for (const { material, buffer_position } of material_records) {
+        const saved_position = buffer.position;
+        buffer.position = buffer_position;
+
+        material_read_standard(buffer, material, textures);
+
+        buffer.position = saved_position;
+        materials.push(material);
+    }
+
+    // ── Lighting ──
+
+    // Environment texture
+    const environment_index = buffer.readUint32();
+    if (environment_index !== NULL_TEXTURE_INDEX) {
+        scene.lights.environment = textures[environment_index];
+    }
+
+    // Light elements
+    const light_count = buffer.readUint32();
+    for (let i = 0; i < light_count; i++) {
+        const light = deserialize_light(buffer);
+        scene.lights.add(light);
+    }
+
+    // ── Assemble Meshes ──
+
+    for (const record of mesh_records) {
+        const mesh = new Mesh();
+        mesh.name = record.name;
+        mesh.geometry = geometries[record.geometry_index];
+        mesh.material = materials[record.material_index];
+        // serialized transform is world-space; meshes deserialize without a parent, so
+        // local == global. Setting only transform_global would leave transform_local at
+        // identity, and the next updateMatrices() / GPU hierarchy pass (which recompose
+        // global from local TRS) would snap the mesh to the origin.
+        mesh.transform_local.fromMatrix(record.transform);
+        mesh.updateMatrices();
+
+        // Compute world-space bounds from geometry bounds + transform
+        mesh.updateBoundsBasic();
+
+        scene.instances.add(mesh);
+    }
+
+    return scene;
+}
+
+/**
+ * Fetch a serialized scene binary from a URL and deserialize it into the given Scene.
+ * Convenience wrapper for testing.
+ *
+ * @param {string} url   URL pointing to the binary blob produced by serialize_scene
+ * @param {Scene} scene  an empty Scene instance to populate
+ * @returns {Promise<Scene>}
+ */
+export async function load_scene_from_url(url, scene) {
+    assert.defined(scene, 'scene');
+    assert.notNull(scene, 'scene');
+    assert.isObject(scene, 'scene');
+    assert.equal(scene.isScene, true, 'scene.isScene !== true');
+
+    assert.isString(url, 'url');
+
+    const response = await fetch(url);
+
+    if (!response.ok) {
+        throw new Error(`Failed to fetch scene: ${response.status} ${response.statusText}`);
+    }
+
+    const array_buffer = await response.arrayBuffer();
+
+    assert.defined(array_buffer, 'array_buffer');
+
+    const buffer = BinaryBuffer.fromArrayBuffer(array_buffer);
+
+    return deserialize_scene(buffer, scene);
+}