@hraness/slopcamera 3.2.7 → 3.3.1

package/apps/desktop/application/spatial-assets.ts

@@ -16,13 +16,17 @@ import {
 } from "../../../src/spatial-scene/contracts";
 import { spatialAssetClosureDigests } from "../../../src/spatial-scene/identity";
 import { evaluateSpatialGlb, parseSpatialGlb, type SpatialGlbModel } from "../../../src/spatial-scene/gltf";
+import { transformBounds } from "../../../src/spatial-scene/math";
+import { SpatialDerivationCandidateSchema, pbrMaterialMapAssetIds, type SpatialDerivationCandidate } from "../../../src/spatial-scene/material-lighting";
 import { canonicalJson, canonicalJsonSha256 } from "../core/canonical-json";
 import { SpatialWorldImportManifestSchema, SPATIAL_SPLAT_LIMITS } from "../contracts/spatial-world";
+import { SpatialAssetFactsV1Schema } from "../contracts/spatial-asset";
 import { inspectSpatialSpz } from "./spatial-spz";
+import { extractWorldProviderMetadata } from "./spatial-world-metadata";
 import { WorldLabsProvenanceSchema } from "./spatial-world-provenance";
 import {
   PreparedSpatialAssetSchema, SPATIAL_OVERLAY_LIMITS, SpatialOverlayCapabilityError, spatialTextRasterContentSha256,
-  spatialGeometryContentSha256, spatialVideoRasterContentSha256,
+  spatialGeometryContentSha256, spatialSplatContentTransform, spatialVideoRasterContentSha256,
   type PreparedSpatialAsset,
 } from "../html-overlay/spatial";
 import type { ApplicationProcessRunner } from "./context";
@@ -67,6 +71,8 @@ export interface SpatialAssetPreparationPorts {
 export interface SpatialAssetPreparationInput {
   readonly snapshots: readonly EvaluatedSpatialScene[];
   readonly exactSceneTimesUs?: readonly { readonly numerator: string; readonly denominator: string }[];
+  /** Beauty lut-grade assets not bound by any entity; decoded like other image rasters. */
+  readonly lutAssetIds?: readonly string[];
   /** Adapter-owned contained source root and private temporary workspace parent. */
   readonly assetRoot: string;
   readonly workspaceParent: string;
@@ -90,9 +96,43 @@ export interface PreparedSpatialAssets {
 const inputSchema = z.strictObject({
   snapshots: z.array(EvaluatedSpatialSceneSchema).min(1).max(SPATIAL_OVERLAY_LIMITS.frames),
   exactSceneTimesUs: z.array(z.strictObject({ numerator: z.string().regex(/^(?:0|[1-9]\d{0,23})$/u), denominator: z.string().regex(/^[1-9]\d{0,8}$/u) })).min(1).max(SPATIAL_OVERLAY_LIMITS.frames).optional(),
+  lutAssetIds: z.array(z.string().min(1).max(256)).max(64).optional(),
   assetRoot: z.string().min(1).max(4_096), workspaceParent: z.string().min(1).max(4_096),
 });
 const digest = (bytes: Uint8Array): string => createHash("sha256").update(bytes).digest("hex");
+export interface SpatialMaterialDerivationReceipt {
+  readonly kind: "slopcamera.spatial-material-derivation";
+  readonly schemaVersion: 1;
+  readonly candidate: SpatialDerivationCandidate;
+  readonly sourceSha256: string;
+  readonly outputSha256: string;
+  readonly provenanceSha256: string;
+  readonly width: number;
+  readonly height: number;
+  readonly output: Uint8Array;
+}
+
+/** Deterministic, local-only raster derivation. Output is an opaque PNG bound to exact source bytes and candidate provenance. */
+export async function deriveSpatialMaterialRaster(input: { readonly candidate: SpatialDerivationCandidate; readonly source: Uint8Array; readonly sourceSha256: string }): Promise<SpatialMaterialDerivationReceipt> {
+  const candidate = SpatialDerivationCandidateSchema.parse(input.candidate);
+  if (!(input.source instanceof Uint8Array) || input.source.byteLength < 1 || input.source.byteLength > SPATIAL_ASSET_PREPARATION_LIMITS.sourceBytes || digest(input.source) !== input.sourceSha256) throw new RangeError("Material derivation source bytes must match their exact bounded digest.");
+  const image = sharp(input.source, { failOn: "error", limitInputPixels: SPATIAL_ASSET_PREPARATION_LIMITS.rasterPixels, sequentialRead: true }).removeAlpha().toColourspace("b-w");
+  const metadata = await image.metadata();
+  if (metadata.width === undefined || metadata.height === undefined || metadata.width * metadata.height > SPATIAL_ASSET_PREPARATION_LIMITS.rasterPixels) throw new RangeError("Material derivation exceeds the decoded pixel budget.");
+  let output: Buffer;
+  if (candidate.method === "sobel-normal-from-height") {
+    const raw = await image.raw().toBuffer(); const rgba = Buffer.alloc(metadata.width * metadata.height * 4); const sample = (x: number, y: number) => raw[Math.max(0, Math.min(metadata.height - 1, y)) * metadata.width + Math.max(0, Math.min(metadata.width - 1, x))]! / 255;
+    for (let y = 0; y < metadata.height; y++) for (let x = 0; x < metadata.width; x++) { const gx = sample(x + 1, y) - sample(x - 1, y), gy = sample(x, y + 1) - sample(x, y - 1), length = Math.hypot(gx, gy, 1), at = (y * metadata.width + x) * 4; rgba[at] = Math.round((-.5 * gx / length + .5) * 255); rgba[at + 1] = Math.round((-.5 * gy / length + .5) * 255); rgba[at + 2] = Math.round((1 / length * .5 + .5) * 255); rgba[at + 3] = 255; }
+    output = await sharp(rgba, { raw: { width: metadata.width, height: metadata.height, channels: 4 } }).png({ compressionLevel: 9, adaptiveFiltering: false, palette: false }).toBuffer();
+  } else {
+    const raw = await image.raw().toBuffer();
+    if (candidate.method === "average-luminance-roughness") for (let index = 0; index < raw.length; index++) raw[index] = 255 - raw[index]!;
+    output = await sharp(raw, { raw: { width: metadata.width, height: metadata.height, channels: 1 } }).png({ compressionLevel: 9, adaptiveFiltering: false, palette: false }).toBuffer();
+  }
+  const outputBytes = Uint8Array.from(output), outputSha256 = digest(outputBytes);
+  const provenanceSha256 = canonicalJsonSha256({ domain: "slopcamera.spatial-material-derivation/v1", candidate, sourceSha256: input.sourceSha256, outputSha256, width: metadata.width, height: metadata.height });
+  return Object.freeze({ kind: "slopcamera.spatial-material-derivation", schemaVersion: 1, candidate, sourceSha256: input.sourceSha256, outputSha256, provenanceSha256, width: metadata.width, height: metadata.height, output: outputBytes });
+}
 function capability(name: string, message: string): never { throw new SpatialOverlayCapabilityError(name, message); }
 function aborted(signal: AbortSignal): void { if (signal.aborted) throw signal.reason instanceof Error ? signal.reason : new Error("Spatial asset preparation was cancelled."); }
 function utf8(bytes: Uint8Array): string { return new TextDecoder("utf-8", { fatal: true }).decode(bytes); }
@@ -341,9 +381,15 @@ export function spatialVideoTimeUs(entity: Extract<SpatialEntity, { kind: "video
 }
 
 /** Owns every temporary/native input until the consumer and all native calls settle. */
+export interface SpatialAssetPreparationOptions {
+  /** When true, an SPZ that fails inspection is skipped rather than aborting preparation. */
+  readonly tolerateSplatDecodeFailure?: boolean;
+}
+
 export async function withPreparedSpatialAssets<Result>(
   input: unknown, ports: SpatialAssetPreparationPorts, signal: AbortSignal,
   consume: (prepared: PreparedSpatialAssets) => Promise<Result>,
+  options: SpatialAssetPreparationOptions = {},
 ): Promise<Result> {
   const request = inputSchema.parse(createBoundedJsonSnapshot(input, SPATIAL_OVERLAY_LIMITS.requestBytes, "Spatial asset preparation request", { maximumDepth: 48, maximumValues: SPATIAL_OVERLAY_LIMITS.requestValues }).value);
   if (request.exactSceneTimesUs !== undefined && request.exactSceneTimesUs.length !== request.snapshots.length) throw new RangeError("Exact scene times must correspond one-to-one to snapshots.");
@@ -398,6 +444,24 @@ export async function withPreparedSpatialAssets<Result>(
     resources.set(name, { ...resource, absolutePath: path });
     return { resource, width: image.width, height: image.height, alpha: image.alpha };
   };
+  /** Verified image manifest → normalized PNG publication; shared by surfaces, environments, and material maps. */
+  const decodeImageRaster = async (asset: SpatialVerifiedAsset, label: string) => {
+    const interpretation = asset.manifest.interpretation;
+    if (interpretation.kind !== "image") throw new RangeError(`${label} requires an image asset interpretation.`);
+    let bytes = asset.bytes;
+    if (interpretation.mimeType === "image/png" && (bytes[0] !== 137 || bytes[1] !== 80 || bytes[2] !== 78 || bytes[3] !== 71)
+      || interpretation.mimeType === "image/jpeg" && (bytes[0] !== 255 || bytes[1] !== 216)) throw new RangeError("Image payload format differs from its declared MIME type.");
+    if (interpretation.mimeType === "image/svg+xml") {
+      const svg = inertSpatialSvg(utf8(bytes));
+      const resvg = new Resvg(svg, { font: { loadSystemFonts: false } });
+      dimensions(resvg.width, resvg.height);
+      bytes = resvg.render().asPng(); profiles.add("shape-only-svg-resvg-2.6.2");
+    }
+    const decoded = await raster(bytes, interpretation.alpha === "opaque");
+    if (decoded.width !== interpretation.width || decoded.height !== interpretation.height) throw new RangeError("Image dimensions differ from its interpretation.");
+    profiles.add("sdr-png-jpeg-sharp-0.35.3");
+    return publishRaster(decoded);
+  };
   const native = async (argv: readonly [string, ...string[]], maxOutputBytes = 16_384) => {
     aborted(signal);
     const result = await ports.runner.run(argv, { abortSignal: signal, timeoutMs: SPATIAL_ASSET_PREPARATION_LIMITS.nativeTimeoutMs, maxOutputBytes, stdin: "ignore" });
@@ -426,9 +490,18 @@ export async function withPreparedSpatialAssets<Result>(
           if (bytes.byteLength > SPATIAL_SPLAT_LIMITS.metadataBytes) throw new RangeError("Retained metadata exceeds its byte bound.");
           const captured = createBoundedJsonSnapshot(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)), SPATIAL_SPLAT_LIMITS.metadataBytes, "Retained world metadata", { maximumDepth: 24, maximumValues: 32_768 });
           const metadata = captured.value as Record<string, unknown>;
-          if (metadata.kind !== manifest.interpretation.schema || metadata.schemaVersion !== 1) throw new RangeError("Retained metadata does not match its declared schema.");
-          if (manifest.interpretation.schema === "slopcamera.spatial-world-import") SpatialWorldImportManifestSchema.parse(metadata);
-          else WorldLabsProvenanceSchema.parse(metadata);
+          const schema = manifest.interpretation.schema;
+          if (schema === "slopcamera.provider-metadata") {
+            // Raw provider bytes are retained verbatim — no slopcamera
+            // envelope to match. A recognized semantics_metadata shape proves
+            // the declaration; unknown keys stay tolerated and ignored.
+            extractWorldProviderMetadata(metadata);
+          } else {
+            if (metadata.kind !== schema || metadata.schemaVersion !== 1) throw new RangeError("Retained metadata does not match its declared schema.");
+            if (schema === "slopcamera.spatial-world-import") SpatialWorldImportManifestSchema.parse(metadata);
+            else if (schema === "slopcamera.spatial-asset-facts") SpatialAssetFactsV1Schema.parse(metadata);
+            else WorldLabsProvenanceSchema.parse(metadata);
+          }
         }
         const record = { manifest, manifestSha256: closures[manifest.assetId]!, bytes };
         verified.set(manifest.assetId, record);
@@ -441,6 +514,31 @@ export async function withPreparedSpatialAssets<Result>(
       const snapshot = request.snapshots[snapshotIndex]!, exactTime = exactTimes[snapshotIndex]!;
       aborted(signal);
       const entity = entry.entity;
+      // A procedural mesh's material map is a secondary binding: the entity
+      // still has no primary asset, so it bypasses the per-entity asset path.
+      const materialMaps = entity.kind !== "mesh" ? [] : entity.material.kind === "pbr"
+        ? pbrMaterialMapAssetIds(entity.material) : entity.material.map === undefined ? [] : [entity.material.map];
+      if (entity.kind === "mesh" && entity.geometry.kind !== "asset" && materialMaps.length > 0) {
+        let expectedDimensions: readonly [number, number] | undefined;
+        for (const materialMap of materialMaps) {
+          const mapAsset = verified.get(materialMap);
+          if (mapAsset === undefined) throw new RangeError(`Missing manifest for spatial asset ${materialMap}.`);
+          const mapKey = `${materialMap}:${entity.entityId}:static`;
+          let prepared = preparedAssets.get(mapKey);
+          if (prepared === undefined) {
+            const output = await decodeImageRaster(mapAsset, `Material map on ${entity.entityId}`);
+            prepared = PreparedSpatialAssetSchema.parse({ kind: "raster", assetId: materialMap,
+              assetManifestSha256: mapAsset.manifestSha256, entityId: entity.entityId, timeUs: null, ...output });
+            preparedAssets.set(mapKey, prepared);
+          }
+          if (prepared.kind !== "raster") throw new RangeError("PBR maps require exact prepared rasters.");
+          const current = [prepared.width, prepared.height] as const;
+          if (expectedDimensions !== undefined && (current[0] !== expectedDimensions[0] || current[1] !== expectedDimensions[1])) {
+            throw new RangeError(`PBR maps on ${entity.entityId} must have identical decoded dimensions.`);
+          }
+          expectedDimensions = current;
+        }
+      }
       if (entity.kind === "group" || entity.kind === "light" || entity.kind === "mesh" && entity.geometry.kind !== "asset") continue;
       const assetId = entity.kind === "text" ? entity.fontAssetId : entity.kind === "mesh" && entity.geometry.kind === "asset" ? entity.geometry.assetId : "assetId" in entity ? entity.assetId : "";
       const asset = verified.get(assetId);
@@ -450,14 +548,26 @@ export async function withPreparedSpatialAssets<Result>(
         if (interpretation.kind !== "splat" || interpretation.format !== "spz") capability("splat-format", "The qualified world profile accepts gzip SPZ v2/v3 only.");
         const key = `${assetId}:${entity.entityId}:splat`;
         if (preparedAssets.has(key)) continue;
-        const facts = await inspectSpatialSpz(asset.bytes, signal);
+        const inspected = await inspectSpatialSpz(asset.bytes, signal).catch((error: unknown) => {
+          if (options.tolerateSplatDecodeFailure) return undefined;
+          throw error;
+        });
+        // Audits may skip a splat that cannot be inspected: the rendered audit
+        // analyzer reports unsupported-kind when no bounds are supplied. Beauty
+        // rendering keeps the failure so invalid source does not render silently.
+        if (inspected === undefined) continue;
+        const { facts, modelBounds } = inspected;
+        // Entity-local enclosure: the same sourceUp→Y rotation and uniform
+        // metersPerUnit scale the renderer applies ahead of the entity
+        // transform, so the object-ID proxy and the geometric audit agree.
+        const bounds = transformBounds(spatialSplatContentTransform(interpretation), modelBounds);
         const name = `splat-${asset.manifestSha256.slice(0, 40)}`;
         const resource = { name, sha256: asset.manifest.payload.sha256, bytes: asset.bytes.byteLength, mediaType: "application/octet-stream", urlPath: `${name}.spz` };
         if (!resources.has(name)) {
           if (resources.size >= 64 || outputBytes + asset.bytes.byteLength > SPATIAL_ASSET_PREPARATION_LIMITS.outputBytes) throw new RangeError("Prepared splat resources exceed their byte budget.");
           resources.set(name, { ...resource, absolutePath: paths.get(assetId)! }); outputBytes += asset.bytes.byteLength;
         }
-        preparedAssets.set(key, PreparedSpatialAssetSchema.parse({ kind: "splat", assetId, entityId: entity.entityId, assetManifestSha256: asset.manifestSha256, resource, facts }));
+        preparedAssets.set(key, PreparedSpatialAssetSchema.parse({ kind: "splat", assetId, entityId: entity.entityId, assetManifestSha256: asset.manifestSha256, resource, facts, bounds }));
         profiles.add("slopcamera.spz-v2-v3-spark-2.1.0-full-resolution-v1");
         continue;
       }
@@ -478,12 +588,18 @@ export async function withPreparedSpatialAssets<Result>(
             images.set(image.resourceName, await publishRaster(await raster(image.bytes, image.opaque), image.resourceName));
           }
           const used = new Set<string>();
+          const textureSlots = ["texture", "normalTexture", "metallicRoughnessTexture", "occlusionTexture", "emissiveTexture", "clearcoatTexture", "clearcoatRoughnessTexture", "clearcoatNormalTexture", "transmissionTexture", "sheenColorTexture", "sheenRoughnessTexture", "anisotropyTexture"] as const;
           const primitives = geometry.primitives.map(primitive => {
-            if (primitive.texture === undefined) return primitive;
-            const image = images.get(primitive.texture.resource.name);
-            if (image === undefined) throw new RangeError("Geometry texture has no exact prepared image bytes.");
-            used.add(primitive.texture.resource.name);
-            return { ...primitive, texture: { ...primitive.texture, ...image } };
+            const resolved: Record<string, unknown> = { ...primitive };
+            for (const slot of textureSlots) {
+              const texture = primitive[slot];
+              if (texture === undefined) continue;
+              const image = images.get(texture.resource.name);
+              if (image === undefined) throw new RangeError("Geometry texture has no exact prepared image bytes.");
+              used.add(texture.resource.name);
+              resolved[slot] = { ...texture, ...image };
+            }
+            return resolved;
           });
           if (used.size !== images.size) throw new RangeError("Geometry preparer returned unused image bytes.");
           const resolved = PreparedSpatialAssetSchema.parse({ ...geometry, primitives });
@@ -497,21 +613,37 @@ export async function withPreparedSpatialAssets<Result>(
             ...(entity.geometry.nodeIndex === undefined ? {} : { nodeIndex: entity.geometry.nodeIndex }),
             ...(entity.geometry.materialMode === undefined ? {} : { materialMode: entity.geometry.materialMode }),
             ...(entity.geometry.clip === undefined ? {} : { clip: entity.geometry.clip }),
+            ...(entity.geometry.morphWeights === undefined ? {} : { morphWeights: entity.geometry.morphWeights }),
           });
+          const publishTexture = async (reference: { readonly imageIndex: number; readonly sampler: unknown; readonly transform?: { readonly offset: readonly [number, number]; readonly rotation: number; readonly scale: readonly [number, number] } } | undefined, opaque: boolean) => {
+            if (reference === undefined) return undefined;
+            const image = geometry.images.find(image => image.imageIndex === reference.imageIndex);
+            if (image === undefined) throw new RangeError("GLB texture image is missing.");
+            return { ...await publishRaster(await raster(image.bytes, opaque)), flipY: false, sampler: reference.sampler, ...(reference.transform === undefined ? {} : { uvTransform: reference.transform }) };
+          };
           const primitives: unknown[] = [];
           for (const primitive of geometry.primitives) {
             const { bounds: _bounds, material: sourceMaterial, ...base } = primitive;
-            let texture: unknown;
-            if (sourceMaterial?.baseColorTexture !== undefined) {
-              const source = sourceMaterial.baseColorTexture, image = geometry.images.find(image => image.imageIndex === source.imageIndex);
-              if (image === undefined) throw new RangeError("GLB texture image is missing.");
-              texture = { ...await publishRaster(await raster(image.bytes, sourceMaterial.alphaMode === "OPAQUE")), flipY: false, sampler: source.sampler };
-            }
+            const texture = await publishTexture(sourceMaterial?.baseColorTexture, sourceMaterial?.alphaMode === "OPAQUE");
+            const metallicRoughnessTexture = await publishTexture(sourceMaterial?.metallicRoughnessTexture, false);
+            const normalTexture = await publishTexture(sourceMaterial?.normalTexture, false);
+            const occlusionTexture = await publishTexture(sourceMaterial?.occlusionTexture, false);
+            const emissiveTexture = await publishTexture(sourceMaterial?.emissiveTexture, false);
+            const clearcoatTexture = await publishTexture(sourceMaterial?.clearcoat?.texture, false), clearcoatRoughnessTexture = await publishTexture(sourceMaterial?.clearcoat?.roughnessTexture, false), clearcoatNormalTexture = await publishTexture(sourceMaterial?.clearcoat?.normalTexture, false);
+            const transmissionTexture = await publishTexture(sourceMaterial?.transmission?.texture, false), sheenColorTexture = await publishTexture(sourceMaterial?.sheen?.colorTexture, false), sheenRoughnessTexture = await publishTexture(sourceMaterial?.sheen?.roughnessTexture, false), anisotropyTexture = await publishTexture(sourceMaterial?.anisotropy?.texture, false);
+            const physical = sourceMaterial === undefined ? undefined : { ...(sourceMaterial.emissiveLinear === undefined ? {} : { emissiveLinear: sourceMaterial.emissiveLinear }), ...(sourceMaterial.emissiveStrength === undefined ? {} : { emissiveStrength: sourceMaterial.emissiveStrength }), ...(sourceMaterial.clearcoat === undefined ? {} : { clearcoat: { factor: sourceMaterial.clearcoat.factor, roughness: sourceMaterial.clearcoat.roughness } }), ...(sourceMaterial.transmission === undefined ? {} : { transmission: sourceMaterial.transmission.factor }), ...(sourceMaterial.sheen === undefined ? {} : { sheen: { colorLinear: sourceMaterial.sheen.colorLinear, roughness: sourceMaterial.sheen.roughness } }), ...(sourceMaterial.anisotropy === undefined ? {} : { anisotropy: { strength: sourceMaterial.anisotropy.strength, rotation: sourceMaterial.anisotropy.rotation } }), ...(sourceMaterial.ior === undefined ? {} : { ior: sourceMaterial.ior }) };
             primitives.push({ ...base,
               ...(sourceMaterial === undefined ? {} : { material: { kind: "standard", color: "#ffffff", opacity: sourceMaterial.alphaMode === "OPAQUE" ? 1 : sourceMaterial.baseColorLinear[3], metalness: sourceMaterial.metalness, roughness: sourceMaterial.roughness },
                 linearColor: sourceMaterial.baseColorLinear.slice(0, 3), doubleSided: sourceMaterial.doubleSided, alphaMode: sourceMaterial.alphaMode,
                 ...(sourceMaterial.alphaMode === "MASK" ? { alphaCutoff: sourceMaterial.alphaCutoff } : {}) }),
               ...(texture === undefined ? {} : { texture }),
+              ...(metallicRoughnessTexture === undefined ? {} : { metallicRoughnessTexture }),
+              ...(normalTexture === undefined ? {} : { normalTexture, ...(sourceMaterial?.normalTexture?.scale === undefined ? {} : { normalScale: sourceMaterial.normalTexture.scale }) }),
+              ...(occlusionTexture === undefined ? {} : { occlusionTexture, ...(sourceMaterial?.occlusionTexture?.strength === undefined ? {} : { occlusionStrength: sourceMaterial.occlusionTexture.strength }) }),
+              ...(emissiveTexture === undefined ? {} : { emissiveTexture }),
+              ...(clearcoatTexture === undefined ? {} : { clearcoatTexture }), ...(clearcoatRoughnessTexture === undefined ? {} : { clearcoatRoughnessTexture }), ...(clearcoatNormalTexture === undefined ? {} : { clearcoatNormalTexture }),
+              ...(transmissionTexture === undefined ? {} : { transmissionTexture }), ...(sheenColorTexture === undefined ? {} : { sheenColorTexture }), ...(sheenRoughnessTexture === undefined ? {} : { sheenRoughnessTexture }), ...(anisotropyTexture === undefined ? {} : { anisotropyTexture }),
+              ...(physical === undefined ? {} : { physical }),
             });
           }
           const resolved = PreparedSpatialAssetSchema.parse({ kind: "geometry", assetId, entityId: entity.entityId,
@@ -534,20 +666,8 @@ export async function withPreparedSpatialAssets<Result>(
       if (preparedAssets.has(key)) continue;
       let output: Awaited<ReturnType<typeof publishRaster>>, sourceTimeUs: number | undefined;
       let videoEvidence: { sourceFrameIndex: number; sourcePresentationTimeUs: number; sourceTimestamp: string; sourcePts: number; sourceTimeBase: { numerator: string; denominator: string }; sourceExactTimeUs: { numerator: string; denominator: string } } | undefined;
-      if (entity.kind === "image") {
-        if (interpretation.kind !== "image") throw new RangeError("Image entity requires an image asset interpretation.");
-        let bytes = asset.bytes;
-        if (interpretation.mimeType === "image/png" && (bytes[0] !== 137 || bytes[1] !== 80 || bytes[2] !== 78 || bytes[3] !== 71)
-          || interpretation.mimeType === "image/jpeg" && (bytes[0] !== 255 || bytes[1] !== 216)) throw new RangeError("Image payload format differs from its declared MIME type.");
-        if (interpretation.mimeType === "image/svg+xml") {
-          const svg = inertSpatialSvg(utf8(bytes));
-          const resvg = new Resvg(svg, { font: { loadSystemFonts: false } });
-          dimensions(resvg.width, resvg.height);
-          bytes = resvg.render().asPng(); profiles.add("shape-only-svg-resvg-2.6.2");
-        }
-        const decoded = await raster(bytes, interpretation.alpha === "opaque");
-        if (decoded.width !== interpretation.width || decoded.height !== interpretation.height) throw new RangeError("Image dimensions differ from its interpretation.");
-        output = await publishRaster(decoded); profiles.add("sdr-png-jpeg-sharp-0.35.3");
+      if (entity.kind === "image" || entity.kind === "environment") {
+        output = await decodeImageRaster(asset, entity.kind === "image" ? "Image entity" : "Environment entity");
       } else if (entity.kind === "video") {
         if (interpretation.kind !== "video") throw new RangeError("Video entity requires a video asset interpretation.");
         if (ports.ffmpegCommand === undefined || ports.ffprobeCommand === undefined) capability("video-decoder", "Video surfaces require bound FFmpeg and FFprobe capabilities.");
@@ -656,6 +776,15 @@ export async function withPreparedSpatialAssets<Result>(
         ...(entity.kind === "video" ? { entityContentSha256: spatialVideoRasterContentSha256(entity) } : {}),
       }));
     }
+    for (const assetId of request.lutAssetIds ?? []) {
+      const key = `lut:${assetId}`;
+      if (preparedAssets.has(key)) continue;
+      const asset = verified.get(assetId);
+      if (asset === undefined) throw new RangeError(`Missing manifest for LUT asset ${assetId}.`);
+      const output = await decodeImageRaster(asset, `LUT asset ${assetId}`);
+      preparedAssets.set(key, PreparedSpatialAssetSchema.parse({ kind: "lut", assetId, assetManifestSha256: asset.manifestSha256, ...output }));
+      aborted(signal);
+    }
     aborted(signal);
     const prepared = [...preparedAssets.values()];
     completed = { value: await consume(Object.freeze({ preparedAssets: prepared, resources: [...resources.values()],