pelican-engine 0.0.0-stage → 0.3.1

package/lib/renderer/render-textures.js

@@ -0,0 +1,155 @@
+import * as THREE from "three/webgpu";
+import * as TSL from "three/tsl";
+const fail = (code, detail) => { throw new Error(`TC_RENDER_TEXTURE_${code}: ${detail} Repair: Bind a live managed texture and use an initialized WebGPU backend.`); };
+/** Three owns presentation textures; the compute executor owns the source versions. */
+export function createRenderTextureBridge(renderer, source, resources) {
+    const backend = renderer.backend, device = backend.device;
+    const entries = new Map();
+    let disposed = false, allocations = 0, releases = 0, copies = 0, bytes = 0;
+    const active = () => { if (disposed)
+        fail("DISPOSED", "Texture bridge was disposed."); if (renderer.backend !== backend || backend.isWebGLBackend || !device || backend.device !== device)
+        fail("CAPABILITY", "Managed render textures require WebGPU."); };
+    const allocate = (width, height) => {
+        if (![width, height].every(value => Number.isSafeInteger(value) && value > 0 && value <= device.limits.maxTextureDimension2D))
+            fail("SIZE", "Texture dimensions exceed actual device limits.");
+        const texture = new THREE.StorageTexture(width, height);
+        texture.name = "Pelican managed render texture";
+        texture.format = THREE.RGBAFormat;
+        texture.type = THREE.FloatType;
+        texture.minFilter = THREE.NearestFilter;
+        texture.magFilter = THREE.NearestFilter;
+        texture.generateMipmaps = false;
+        texture.flipY = false;
+        texture.colorSpace = THREE.NoColorSpace;
+        try {
+            renderer.initTexture(texture);
+        }
+        catch (error) {
+            texture.dispose();
+            throw error;
+        }
+        allocations++;
+        return texture;
+    };
+    const get = (material, name) => {
+        active();
+        const descriptor = resources(material.name)[name] ?? fail("UNBOUND", material.name + ":" + name);
+        const shape = descriptor.texture;
+        if (!shape || descriptor.type !== "vec4" || descriptor.values.length !== shape.width * shape.height)
+            return fail("RESOURCE", "Invalid managed texture descriptor.");
+        let slots = entries.get(material);
+        if (!slots) {
+            slots = new Map();
+            entries.set(material, slots);
+        }
+        let entry = slots.get(name);
+        if (!entry) {
+            const texture = allocate(shape.width, shape.height);
+            entry = { material, name, texture, width: shape.width, height: shape.height, size: TSL.uniform(new THREE.Vector2(shape.width, shape.height)), nodes: [] };
+            slots.set(name, entry);
+        }
+        return entry;
+    };
+    return {
+        prepare(material, slots) { for (const name of Object.keys(slots))
+            get(material, name); },
+        node(material, name, uv, sampler) {
+            const entry = get(material, name), size = entry.size;
+            const finite = uv.x.equal(uv.x).and(uv.y.equal(uv.y)).and(TSL.abs(uv.x).lessThanEqual(3.402823e38)).and(TSL.abs(uv.y).lessThanEqual(3.402823e38));
+            const safe = TSL.select(finite, uv, TSL.vec2(0));
+            const normalize = (value, wrap = "clamp") => wrap === "repeat" ? value.sub(value.floor()) : wrap === "mirror" ? TSL.float(1).sub(TSL.abs(value.sub(value.mul(0.5).floor().mul(2)).sub(1))) : TSL.clamp(value, 0, 1);
+            const address = (value, length, wrap = "clamp") => {
+                if (wrap === "clamp")
+                    return TSL.clamp(value, 0, length.sub(1));
+                const period = wrap === "mirror" ? length.mul(2) : length;
+                const cell = value.sub(value.div(period).floor().mul(period));
+                return wrap === "mirror" ? TSL.min(cell, length.mul(2).sub(1).sub(cell)) : cell;
+            };
+            const read = (x, y) => {
+                const coord = TSL.ivec2(address(x, size.x, sampler.wrapU), address(y, size.y, sampler.wrapV));
+                const node = TSL.textureLoad(entry.texture, coord);
+                node.updateMatrix = false;
+                node.mergeable = false;
+                entry.nodes.push(node);
+                return node.level(TSL.float(0));
+            };
+            const x = normalize(safe.x, sampler.wrapU).mul(size.x), y = normalize(safe.y, sampler.wrapV).mul(size.y);
+            let value;
+            if (sampler.filter === "nearest")
+                value = read(x.floor(), y.floor());
+            else {
+                const px = x.sub(0.5), py = y.sub(0.5), bx = px.floor(), by = py.floor(), wx = px.fract(), wy = py.fract();
+                value = TSL.mix(TSL.mix(read(bx, by), read(bx.add(1), by), wx), TSL.mix(read(bx, by.add(1)), read(bx.add(1), by.add(1)), wx), wy);
+            }
+            return TSL.select(finite, value, TSL.vec4(0));
+        },
+        update() {
+            if (!entries.size)
+                return;
+            active();
+            const owner = source() ?? fail("CAPABILITY", "Missing compute texture executor.");
+            const planned = [];
+            for (const [material, slots] of entries) {
+                const current = resources(material.name);
+                for (const entry of slots.values()) {
+                    const descriptor = current[entry.name] ?? fail("UNBOUND", material.name + ":" + entry.name);
+                    if (!descriptor.texture || descriptor.type !== "vec4" || descriptor.values.length !== descriptor.texture.width * descriptor.texture.height)
+                        fail("RESOURCE", "Invalid managed texture descriptor.");
+                    planned.push({ entry, descriptor });
+                }
+            }
+            const encoder = device.createCommandEncoder({ label: "Pelican managed render texture copies" }), staged = [];
+            try {
+                for (const { entry, descriptor } of planned) {
+                    if (entry.key === descriptor.key && entry.revision === descriptor.revision)
+                        continue;
+                    const view = owner.textureResident(descriptor), shape = descriptor.texture;
+                    if (view.width !== shape.width || view.height !== shape.height || view.revision !== descriptor.revision || view.texture.format !== "rgba32float" || !(view.texture.usage & GPUTextureUsage.COPY_SRC))
+                        fail("RESOURCE", "Executor returned an incompatible texture.");
+                    const replacement = entry.width !== view.width || entry.height !== view.height;
+                    const texture = replacement ? allocate(view.width, view.height) : entry.texture;
+                    staged.push({ entry, descriptor, texture, ...(replacement ? { previous: entry.texture } : {}) });
+                    const target = backend.get(texture).texture ?? fail("RESOURCE", "Three did not allocate the render texture.");
+                    if (target === view.texture || target.format !== "rgba32float" || !(target.usage & GPUTextureUsage.COPY_DST))
+                        fail("RESOURCE", "Render destination is incompatible or aliases the compute source.");
+                    encoder.copyTextureToTexture({ texture: view.texture }, { texture: target }, { width: view.width, height: view.height, depthOrArrayLayers: 1 });
+                }
+                if (staged.length)
+                    device.queue.submit([encoder.finish()]);
+            }
+            catch (error) {
+                for (const item of staged)
+                    if (item.previous) {
+                        item.texture.dispose();
+                        releases++;
+                    }
+                throw error;
+            }
+            for (const item of staged) {
+                const shape = item.descriptor.texture;
+                if (item.previous) {
+                    item.entry.texture = item.texture;
+                    item.entry.width = shape.width;
+                    item.entry.height = shape.height;
+                    item.entry.size.value.set(shape.width, shape.height);
+                    for (const node of item.entry.nodes)
+                        node.value = item.texture;
+                    item.entry.material.needsUpdate = true;
+                    item.previous.dispose();
+                    releases++;
+                }
+                item.entry.key = item.descriptor.key;
+                item.entry.revision = item.descriptor.revision;
+                copies++;
+                bytes += shape.width * shape.height * 16;
+            }
+        },
+        inspect() { return { disposed, slots: [...entries.values()].reduce((n, m) => n + m.size, 0), allocations, released: releases, liveTextures: allocations - releases, gpuCopies: copies, gpuCopyBytes: bytes, cpuResultUploads: 0, bindings: [...entries.values()].flatMap(slots => [...slots.values()].map(e => ({ target: e.material.name, name: e.name, width: e.width, height: e.height, key: e.key, revision: e.revision }))) }; },
+        dispose() { if (disposed)
+            return; disposed = true; for (const slots of entries.values())
+            for (const entry of slots.values()) {
+                entry.texture.dispose();
+                releases++;
+            } entries.clear(); },
+    };
+}

package/lib/renderer/startup.js

@@ -0,0 +1,50 @@
+export function startupPolicy(development, search) {
+    const automation = development && new URLSearchParams(search).get("automation") === "1";
+    return { automation, playing: !automation };
+}
+/** Diagnostic descriptions distinguish capability from lazy renderer allocation. */
+export function inspectTraceCapabilities(data) {
+    const compute = data.backend === "webgpu";
+    const legacy = compute && data.legacyProbe;
+    const modern = compute && !data.legacyProbe;
+    return {
+        tracer: !compute ? false : legacy ? "legacy software-triangle-BVH" : data.surfaceInitialized ? "WebGPU surface triangle-BVH" : "WebGPU surface triangle-BVH (lazy initialization)",
+        tracerInitialized: compute && (legacy || data.surfaceInitialized),
+        hardwareRT: false,
+        denoiser: modern ? "motion-reprojected temporal history + spatial a-trous; complete quality matrix unaccepted" : false,
+        hybrid: !compute ? false : legacy ? "legacy raster + traced image compositing prototype" : "raster primary visibility + actual shadow and secondary rays",
+        pathBounces: data.maxBounces,
+        tracedLights: !compute ? false : legacy ? "legacy first authored light only" : "all captured point/directional/ambient/hemisphere lights",
+        textures: data.gameplay ? (modern ? "supported GLB PBR textures in raster and surface tracing; see documented limits" : "GLB PBR and base-color textures in raster") : "no authored texture assets",
+        experimentalProbes: "Four small CPU simulations and finite world probe are M0 debug sidecars, not M1 production modules",
+    };
+}
+/** Explicit progress deadline; startup and commands never require a user focus/key event. */
+export async function boundedOperation(promise, label, timeoutMs = 30000) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new Error("TC_GPU_TIMEOUT_CONFIG: Invalid timeout.");
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve(promise),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`TC_GPU_TIMEOUT: ${label} did not complete within ${timeoutMs} ms; no click or key is required to continue.`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+export function runtimeStatus(data) {
+    const state = data.faulted
+        ? "faulted"
+        : data.playing
+            ? "running"
+            : data.automation
+                ? "paused · automation"
+                : "paused";
+    const backend = data.backend === "webgl2" ? "WebGL2" : data.backend === "uninitialized" ? "Initializing" : "WebGPU";
+    return `Pelican Engine · ${data.mode}\n${backend} · ${data.triangles} triangles · tick ${data.tick}\n${state}`;
+}

package/lib/renderer/surface-capture.js

@@ -0,0 +1,199 @@
+import * as THREE from "three/webgpu";
+import { extractSurfaceScene, createSurfaceTextureCache, createSurfaceMeshCache, sampleSurfaceTexture, } from "./surface.js";
+import { createTexturePixelProvider } from "./texture-pixels.js";
+import { createVertexDeformer } from "./vertex-graphs.js";
+/** One owner per rendered content generation; no mutations to borrowed scene/materials. */
+export function createSurfaceCapture() {
+    const pixels = createTexturePixelProvider(), textureCache = createSurfaceTextureCache(), meshCache = createSurfaceMeshCache(), adapters = new Map();
+    let disposed = false;
+    const adapter = (material, knownColorGraphs, graphs) => {
+        const candidate = material;
+        if (!candidate.isNodeMaterial)
+            return undefined;
+        const physical = candidate
+            .isMeshPhysicalNodeMaterial === true;
+        if ((!candidate.isMeshStandardNodeMaterial ||
+            candidate.type !== "MeshStandardNodeMaterial") &&
+            (!physical || candidate.type !== "MeshPhysicalNodeMaterial"))
+            throw new Error("TC_TRACE_MATERIAL: Node material requires an explicit engine surface adapter.");
+        for (const [key, value] of Object.entries(candidate))
+            if (key.endsWith("Node") &&
+                value &&
+                typeof value === "object" &&
+                value.isNode) {
+                const binding = graphs?.get(material);
+                const supported = binding &&
+                    {
+                        colorNode: "baseColor",
+                        emissiveNode: "emissive",
+                        roughnessNode: "roughness",
+                        metalnessNode: "metalness",
+                        opacityNode: "opacity",
+                        normalNode: "normalWorld",
+                    }[key];
+                if (!(supported && binding.graphs[supported]) &&
+                    !(key === "positionNode" && binding?.vertex) &&
+                    (key !== "colorNode" || !knownColorGraphs.has(material)))
+                    throw new Error("TC_TRACE_NODE_GRAPH: Unsupported node override " + key);
+            }
+        let copy = adapters.get(material);
+        if (!copy) {
+            copy = physical
+                ? new THREE.MeshPhysicalMaterial()
+                : new THREE.MeshStandardMaterial();
+            adapters.set(material, copy);
+        }
+        if (copy instanceof THREE.MeshPhysicalMaterial)
+            copy.copy(candidate);
+        else
+            copy.copy(candidate);
+        // colorNode replaces materialColor; opacityNode replaces materialOpacity.
+        if (candidate.colorNode)
+            copy.map = null;
+        if (graphs?.get(material)?.graphs.opacity) {
+            copy.transparent = true;
+            copy.opacity = 1;
+            copy.alphaMap = null;
+        }
+        return copy;
+    };
+    return {
+        capture(scene, knownColorGraphs = new Set(), graphs, options = {}) {
+            if (disposed)
+                throw new Error("TC_TRACE_CAPTURE_DISPOSED");
+            scene.updateMatrixWorld(true);
+            const vertexDiagnostics = [];
+            const vertexTextures = new Map();
+            const hasVertex = graphs && [...graphs.values()].some(binding => binding.vertex);
+            const vertexDeformer = hasVertex ? createVertexDeformer(graphs, (binding, asset, uv) => {
+                const texture = binding.textures.get(asset);
+                if (!texture)
+                    throw new Error("TC_VERTEX_TEXTURE: " + binding.id + ":" + asset);
+                let snapshot = vertexTextures.get(texture);
+                if (!snapshot) {
+                    snapshot = textureCache.getSnapshot(texture, pixels.decode, vertexDiagnostics);
+                    vertexTextures.set(texture, snapshot);
+                }
+                return sampleSurfaceTexture(snapshot, uv);
+            }) : undefined;
+            let snapshot = extractSurfaceScene(scene, {
+                textureCache,
+                meshCache,
+                decodedTextureProvider: pixels.decode,
+                materialAdapter: (material) => adapter(material, knownColorGraphs, graphs),
+                ...(vertexDeformer ? { vertexDeformer } : {}),
+                ...(options.geometryOnly ? { meshFilter: (mesh) => (Array.isArray(mesh.material) ? mesh.material : [mesh.material]).some(material => graphs?.get(material)?.vertex) } : {}),
+            });
+            if (graphs?.size) {
+                const byUuid = new Map([...graphs].map(([material, binding]) => [material.uuid, binding]));
+                for (const triangle of snapshot.triangles) {
+                    const binding = byUuid.get(triangle.materialUuid);
+                    if (!binding)
+                        continue;
+                    for (const graph of [...Object.values(binding.graphs), ...Object.values(binding.vertex ?? {})])
+                        for (const input of graph.requiredInputs ?? []) {
+                            const attribute = input === "uv" ? "uv0" : input === "uv1" ? "uv1" : undefined;
+                            if (attribute &&
+                                triangle.vertices.some((vertex) => !vertex[attribute]))
+                                throw Error("TC_GRAPH_UV: Material " +
+                                    binding.id +
+                                    " requires " +
+                                    input +
+                                    " on object " +
+                                    triangle.objectUuid +
+                                    " geometry " +
+                                    triangle.geometryUuid);
+                        }
+                }
+                const diagnostics = [...snapshot.diagnostics, ...vertexDiagnostics], textures = [...snapshot.textures];
+                const present = new Set(textures.map((texture) => texture.uuid));
+                for (const binding of graphs.values())
+                    for (const graph of [...Object.values(binding.graphs), ...Object.values(binding.vertex ?? {})])
+                        for (const id of graph.textureIds ?? []) {
+                            if (Object.hasOwn(graph.textureSlots ?? {}, id))
+                                continue;
+                            const texture = binding.textures.get(id);
+                            if (!texture)
+                                throw Error("TC_GRAPH_TEXTURE: " + binding.id + ":" + id);
+                            if (present.has(texture.uuid))
+                                continue;
+                            textures.push(textureCache.getSnapshot(texture, pixels.decode, diagnostics));
+                            present.add(texture.uuid);
+                        }
+                snapshot = Object.freeze({
+                    ...snapshot,
+                    textures: Object.freeze(textures),
+                    diagnostics: Object.freeze(diagnostics),
+                });
+            }
+            const lights = [];
+            const identities = [];
+            scene.traverseVisible((object) => {
+                if (options.geometryOnly)
+                    return;
+                if (!(object instanceof THREE.Light))
+                    return;
+                const color = object.color.clone().multiplyScalar(object.intensity), position = object.getWorldPosition(new THREE.Vector3());
+                if (object instanceof THREE.PointLight) {
+                    lights.push(...position.toArray(), 0, ...color.toArray(), object.distance, 0, 0, 0, object.decay);
+                }
+                else if (object instanceof THREE.DirectionalLight) {
+                    object.target.updateWorldMatrix(true, false);
+                    const direction = position
+                        .sub(object.target.getWorldPosition(new THREE.Vector3()))
+                        .normalize();
+                    lights.push(...direction.toArray(), 1, ...color.toArray(), 0, 0, 0, 0, 0);
+                }
+                else if (object instanceof THREE.HemisphereLight) {
+                    const direction = position.normalize(), ground = object.groundColor
+                        .clone()
+                        .multiplyScalar(object.intensity);
+                    lights.push(...direction.toArray(), 2, ...color.toArray(), 0, ...ground.toArray(), 0);
+                }
+                else if (object instanceof THREE.AmbientLight) {
+                    lights.push(0, 1, 0, 3, ...color.toArray(), 0, 0, 0, 0, 0);
+                }
+                else
+                    throw new Error("TC_TRACE_LIGHT: Unsupported light type " + object.type);
+                identities.push(object.uuid);
+            });
+            return {
+                surface: snapshot,
+                lights: new Float32Array(lights),
+                lightIds: identities,
+                environment: scene.background instanceof THREE.Color
+                    ? scene.background.toArray()
+                    : [0, 0, 0],
+                environmentTexture: scene.environment?.uuid ?? null,
+            };
+        },
+        inspect() {
+            return {
+                disposed,
+                adaptedMaterials: adapters.size,
+                pixels: pixels.inspect(),
+                textures: textureCache.inspect(),
+                meshes: meshCache.inspect(),
+            };
+        },
+        clear() {
+            for (const material of adapters.values())
+                material.dispose();
+            adapters.clear();
+            pixels.clear();
+            textureCache.clear();
+            meshCache.clear();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const material of adapters.values())
+                material.dispose();
+            adapters.clear();
+            pixels.dispose();
+            textureCache.dispose();
+            meshCache.dispose();
+        },
+    };
+}

package/lib/renderer/surface-gpu.js

@@ -0,0 +1,270 @@
+import * as THREE from "three";
+/** Private storage-buffer ABI, all fields occupy vec4-aligned float32 slots. */
+export const SURFACE_GPU_ABI = 1;
+export const SURFACE_TRIANGLE_FLOATS = 72;
+export const SURFACE_MATERIAL_FLOATS = 32;
+export const SURFACE_TEXTURE_FLOATS = 24;
+const fail = (code, message) => {
+    throw new Error(code + ": " + message);
+};
+function finite(value, label) {
+    if (!Number.isFinite(value) || !Number.isFinite(Math.fround(value)))
+        fail("TC_SURFACE_GPU_NUMBER", label + " is not representable as float32.");
+    return value;
+}
+function indexMap(values) {
+    const result = new Map();
+    values.forEach((value, index) => {
+        if (result.has(value.uuid))
+            fail("TC_SURFACE_GPU_ID", "Duplicate content identity " + value.uuid);
+        result.set(value.uuid, index);
+    });
+    return result;
+}
+function reference(map, id) {
+    if (id === undefined)
+        return -1;
+    const index = map.get(id);
+    if (index === undefined)
+        fail("TC_SURFACE_GPU_REFERENCE", "Missing content " + id);
+    return index;
+}
+export function packSurfaceGeometry(snapshot, ordered = snapshot.triangles, volumeIds = new Map()) {
+    const materials = indexMap(snapshot.materials), textures = new Map(snapshot.textures.map((texture) => [texture.uuid, texture]));
+    const output = new Float32Array(ordered.length * SURFACE_TRIANGLE_FLOATS);
+    for (let index = 0; index < ordered.length; index++) {
+        const triangle = ordered[index], materialIndex = reference(materials, triangle.materialUuid), material = snapshot.materials[materialIndex], offset = index * SURFACE_TRIANGLE_FLOATS;
+        for (const textureId of Object.values(material.maps)) {
+            const texture = textures.get(textureId);
+            if (!texture)
+                fail("TC_SURFACE_GPU_REFERENCE", "Missing material texture " + textureId);
+            for (const vertex of triangle.vertices)
+                if ((texture.channel === 0 ? vertex.uv0 : vertex.uv1) === undefined)
+                    fail("TC_SURFACE_GPU_UV", "Triangle is missing texture channel " + texture.channel);
+        }
+        const color = triangle.instanceColor ?? [1, 1, 1], tangent = triangle.vertices.every((vertex) => vertex.tangent !== undefined);
+        for (let vertex = 0; vertex < 3; vertex++) {
+            const data = triangle.vertices[vertex], positionW = vertex === 0 ? materialIndex : color[vertex - 1], normalW = vertex === 0
+                ? color[2]
+                : vertex === 1
+                    ? material.vertexColors
+                        ? 1
+                        : 0
+                    : tangent
+                        ? 1
+                        : 0;
+            output.set([...data.position, positionW], offset + vertex * 4);
+            output.set([...data.normal, normalW], offset + 12 + vertex * 4);
+            output.set([...(data.uv0 ?? [0, 0]), ...(data.uv1 ?? [0, 0])], offset + 24 + vertex * 4);
+            output.set(data.color ?? [1, 1, 1, 1], offset + 36 + vertex * 4);
+            output.set(data.tangent ?? [0, 0, 0, 0], offset + 48 + vertex * 4);
+        }
+        for (let column = 0; column < 3; column++)
+            output.set([...triangle.normalMatrix.slice(column * 3, column * 3 + 3), 0], offset + 60 + column * 4);
+        const m = triangle.normalMatrix;
+        const scales = [0, 3, 6].map((index) => Math.hypot(m[index], m[index + 1], m[index + 2]));
+        const normalized = m.map((value, index) => value / scales[Math.floor(index / 3)]);
+        const determinant = normalized[0] *
+            (normalized[4] * normalized[8] - normalized[5] * normalized[7]) -
+            normalized[3] *
+                (normalized[1] * normalized[8] - normalized[2] * normalized[7]) +
+            normalized[6] *
+                (normalized[1] * normalized[5] - normalized[2] * normalized[4]);
+        if (!Number.isFinite(determinant) || determinant === 0)
+            fail("TC_SURFACE_GPU_NORMAL_MATRIX", "Singular normal matrix.");
+        output[offset + 63] = determinant > 0 ? 1 : -1;
+        output[offset + 67] =
+            volumeIds.get(JSON.stringify([triangle.objectUuid, triangle.instanceId])) ?? 0;
+    }
+    for (const value of output)
+        finite(value, "Triangle data");
+    return output;
+}
+export function packSurfaceResources(snapshot) {
+    const materialIds = indexMap(snapshot.materials), textureIds = indexMap(snapshot.textures), materials = new Float32Array(snapshot.materials.length * SURFACE_MATERIAL_FLOATS), textures = new Float32Array(snapshot.textures.length * SURFACE_TEXTURE_FLOATS);
+    let texelWords = 0;
+    for (const texture of snapshot.textures) {
+        if (!texture.pixels ||
+            texture.pixels.length !== texture.width * texture.height * 4)
+            fail("TC_SURFACE_GPU_PIXELS", "Missing decoded pixels for " + texture.uuid);
+        if (!Number.isSafeInteger(texture.width) ||
+            !Number.isSafeInteger(texture.height) ||
+            texture.width < 1 ||
+            texture.height < 1)
+            fail("TC_SURFACE_GPU_TEXTURE", "Invalid dimensions for " + texture.uuid);
+        texelWords +=
+            texture.width *
+                texture.height *
+                (texture.pixelEncoding === "float32" ? 4 : 1);
+    }
+    if (!Number.isSafeInteger(texelWords) || texelWords > 0x3fffffff)
+        fail("TC_SURFACE_GPU_TEXTURE", "Texture storage exceeds addressable buffer layout.");
+    const texels = new Uint32Array(texelWords), floatBits = new Float32Array(texels.buffer), textureWords = new Uint32Array(textures.buffer);
+    let word = 0;
+    snapshot.textures.forEach((texture, index) => {
+        const float = texture.pixelEncoding === "float32", srgb = texture.colorSpace === THREE.SRGBColorSpace;
+        if (![
+            THREE.SRGBColorSpace,
+            THREE.LinearSRGBColorSpace,
+            THREE.NoColorSpace,
+        ].includes(texture.colorSpace))
+            fail("TC_SURFACE_GPU_COLOR_SPACE", "Unsupported color space " + texture.colorSpace);
+        const wrap = (mode) => mode === THREE.RepeatWrapping
+            ? 1
+            : mode === THREE.MirroredRepeatWrapping
+                ? 2
+                : mode === THREE.ClampToEdgeWrapping
+                    ? 0
+                    : fail("TC_SURFACE_GPU_WRAP", "Unsupported wrapping " + mode);
+        const nearest = [
+            THREE.NearestFilter,
+            THREE.NearestMipmapNearestFilter,
+            THREE.NearestMipmapLinearFilter,
+        ].includes(texture.magFilter), linear = [
+            THREE.LinearFilter,
+            THREE.LinearMipmapNearestFilter,
+            THREE.LinearMipmapLinearFilter,
+        ].includes(texture.magFilter);
+        if (!nearest && !linear)
+            fail("TC_SURFACE_GPU_FILTER", "Unsupported magnification filter " + texture.magFilter);
+        const offset = index * SURFACE_TEXTURE_FLOATS, m = texture.matrix;
+        // SurfaceTexture.pixels already uses uploaded texture row order. Never flip twice.
+        textures.set([
+            word,
+            texture.width,
+            texture.height,
+            texture.channel,
+            wrap(texture.wrapS),
+            wrap(texture.wrapT),
+            linear ? 1 : 0,
+            (float ? 1 : 0) | (srgb ? 2 : 0),
+            m[0],
+            m[1],
+            m[2],
+            0,
+            m[3],
+            m[4],
+            m[5],
+            0,
+            m[6],
+            m[7],
+            m[8],
+            0,
+            texture.minFilter,
+            texture.anisotropy,
+            texture.generateMipmaps ? 1 : 0,
+            0,
+        ], offset);
+        textureWords.set([
+            word,
+            texture.width,
+            texture.height,
+            texture.channel,
+            wrap(texture.wrapS),
+            wrap(texture.wrapT),
+            linear ? 1 : 0,
+            (float ? 1 : 0) | (srgb ? 2 : 0),
+        ], offset);
+        for (let pixel = 0; pixel < texture.width * texture.height; pixel++) {
+            if (float) {
+                for (let channel = 0; channel < 4; channel++)
+                    floatBits[word++] = finite(texture.pixels[pixel * 4 + channel], "Float texture sample");
+            }
+            else {
+                let value = 0;
+                for (let channel = 0; channel < 4; channel++) {
+                    const normalized = finite(texture.pixels[pixel * 4 + channel], "UNORM texture sample");
+                    if (normalized < 0 || normalized > 1)
+                        fail("TC_SURFACE_GPU_UNORM", "UNORM texture sample outside [0,1].");
+                    value |= Math.round(normalized * 255) << (channel * 8);
+                }
+                texels[word++] = value >>> 0;
+            }
+        }
+    });
+    materials.set(packSurfaceMaterialTable(snapshot));
+    for (const value of [...materials, ...textures])
+        finite(value, "Resource data");
+    return {
+        abi: 1,
+        materials,
+        textures,
+        texels,
+        materialIds: [...materialIds.keys()],
+        textureIds: [...textureIds.keys()],
+        limitations: [
+            "Buffer ABI and exact source texels only; shader, BSDF and graphics acceptance require separate integration.",
+            "Texture metadata retains minification/mip parameters; this packer does not generate a mip chain.",
+        ],
+    };
+}
+/** Numeric reference for shader upload/readback tests; sRGB decoding precedes filtering. */
+export function unpackSurfaceTexel(resources, textureIndex, x, y) {
+    if (!Number.isInteger(textureIndex) ||
+        textureIndex < 0 ||
+        textureIndex >= resources.textureIds.length)
+        return fail("TC_SURFACE_GPU_TEXEL", "Invalid texture index.");
+    const metadata = resources.textures.subarray(textureIndex * SURFACE_TEXTURE_FLOATS, (textureIndex + 1) * SURFACE_TEXTURE_FLOATS);
+    const words = new Uint32Array(resources.textures.buffer, resources.textures.byteOffset + textureIndex * SURFACE_TEXTURE_FLOATS * 4, metadata.length);
+    if (metadata.length !== SURFACE_TEXTURE_FLOATS ||
+        !Number.isInteger(x) ||
+        !Number.isInteger(y) ||
+        x < 0 ||
+        y < 0 ||
+        x >= words[1] ||
+        y >= words[2])
+        return fail("TC_SURFACE_GPU_TEXEL", "Invalid texture coordinates.");
+    const flags = words[7], offset = words[0] + (y * words[1] + x) * (flags & 1 ? 4 : 1);
+    const floats = new Float32Array(resources.texels.buffer, resources.texels.byteOffset, resources.texels.length);
+    const output = [0, 1, 2, 3].map((channel) => flags & 1
+        ? floats[offset + channel]
+        : ((resources.texels[offset] >>> (channel * 8)) & 255) / 255);
+    if (flags & 2)
+        for (let channel = 0; channel < 3; channel++) {
+            const value = output[channel];
+            output[channel] =
+                value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+        }
+    return output;
+}
+export function packSurfaceMaterialTable(snapshot) {
+    const textureIds = indexMap(snapshot.textures), materials = new Float32Array(snapshot.materials.length * SURFACE_MATERIAL_FLOATS);
+    snapshot.materials.forEach((material, index) => {
+        const map = (slot) => reference(textureIds, material.maps[slot]);
+        materials.set([
+            ...material.baseColor,
+            material.roughness,
+            material.metalness,
+            material.alphaTest,
+            material.aoMapIntensity,
+            ...material.emissive,
+            material.emissiveIntensity,
+            map("map"),
+            map("alphaMap"),
+            map("normalMap"),
+            map("roughnessMap"),
+            map("metalnessMap"),
+            map("aoMap"),
+            map("emissiveMap"),
+            material.side === "double" ? 2 : material.side === "back" ? 1 : 0,
+            ...material.normalScale,
+            material.normalMapType === THREE.ObjectSpaceNormalMap ? 1 : 0,
+            material.alphaMode === "blend"
+                ? 2
+                : material.alphaMode === "mask"
+                    ? 1
+                    : 0,
+            material.transmission ?? 0,
+            material.ior ?? 1.5,
+            (material.transmission ?? 0) > 0
+                ? (material.attenuationDistance ?? 0)
+                : map("specularIntensityMap") + 1,
+            1 - (material.specularIntensity ?? 1),
+            ...((material.transmission ?? 0) > 0 ? (material.attenuationColor ?? [1, 1, 1]) : (material.specularColor ?? [1, 1, 1])),
+            (material.transmission ?? 0) > 0 ? 0 : map("specularColorMap") + 1,
+        ], index * SURFACE_MATERIAL_FLOATS);
+    });
+    for (const value of materials)
+        finite(value, "Material data");
+    return materials;
+}