@jgengine/assets 0.18.1 → 0.21.0

package/dist/gltfMaterials.d.ts

@@ -0,0 +1,79 @@
+import type { GLTF } from "@gltf-transform/core";
+import type { MaterialTextureMetadata, MaterialTextureRole } from "@jgengine/core/material/materialAsset";
+/** Native material/texture extensions implemented by Three.js GLTFLoader r182. Decoders are still required. */
+export declare const GLTF_MATERIAL_EXTENSIONS_R182: readonly string[];
+/** A native glTF texture use; embedded images retain their source index instead of an invented URL. */
+export interface GltfMaterialTexture {
+    /** Bump is native normal perturbation, distinct from authored height displacement. */
+    role: MaterialTextureRole | "bump";
+    texture: number;
+    image: number;
+    sourceExtension?: string;
+    mimeType?: string;
+    bufferView?: number;
+    metadata: Omit<MaterialTextureMetadata, "url"> & {
+        url?: string;
+    };
+    /** Packed source channel meanings; anisotropy RG direction is remapped to [-1, 1]. */
+    channels: Readonly<Record<string, string>>;
+    /** Complete native textureInfo, including unrecognized extensions. */
+    native: GLTF.ITextureInfo;
+}
+/** One imported material with the native definition retained as an independent JSON snapshot. */
+export interface GltfImportedMaterial {
+    /** Stable within the pinned model bytes; duplicate or absent material names are safe. */
+    id: string;
+    index: number;
+    name?: string;
+    alphaMode: "OPAQUE" | "MASK" | "BLEND";
+    alphaCutoff: number;
+    doubleSided: boolean;
+    extensions: readonly string[];
+    textures: readonly GltfMaterialTexture[];
+    native: GLTF.IMaterial;
+}
+/** A primitive slot retains mesh and material indices even when display names collide. */
+export interface GltfMaterialSlot {
+    id: string;
+    mesh: number;
+    meshName?: string;
+    primitive: number;
+    material?: number;
+    materialId?: string;
+    materialName?: string;
+    nodes: readonly {
+        index: number;
+        name?: string;
+    }[];
+    uvSets: readonly number[];
+    hasNormals: boolean;
+    hasTangents: boolean;
+}
+/** Actionable fidelity warning or error; this inspector never changes imported surfaces. */
+export interface GltfMaterialDiagnostic {
+    severity: "warning" | "error";
+    code: "unsupported-extension" | "missing-uv" | "missing-tangent-space" | "incompatible-extensions" | "missing-transmission" | "different-direction-uv";
+    path: string;
+    message: string;
+}
+/** Native material inventory, primitive selectors, attribution, and renderer compatibility diagnostics. */
+export interface GltfMaterialInspection {
+    assetId: string;
+    materials: readonly GltfImportedMaterial[];
+    slots: readonly GltfMaterialSlot[];
+    diagnostics: readonly GltfMaterialDiagnostic[];
+    copyright?: string;
+    extras?: unknown;
+}
+/**
+ * Inventory validated glTF JSON without flattening slots, decoding compressed geometry, or changing materials.
+ * IDs use the supplied model namespace plus source indices, and remain stable while its pinned bytes remain stable.
+ * @capability gltf-material-inspection inspect native material slots, packed maps, attribution and compatibility
+ */
+export declare function inspectGltfMaterials(json: GLTF.IGLTF, assetId: string): GltfMaterialInspection;
+/**
+ * Inspect the JSON chunk of complete GLB v2 bytes, including models with compressed geometry.
+ * This measures material metadata only; it never decodes geometry or resolves image URLs.
+ * @capability gltf-material-inspection inspect material slots and texture metadata directly from complete GLB bytes
+ */
+export declare function inspectGlbMaterials(bytes: Uint8Array, assetId: string): GltfMaterialInspection;

package/dist/gltfMaterials.js

@@ -0,0 +1,183 @@
+/** Native material/texture extensions implemented by Three.js GLTFLoader r182. Decoders are still required. */
+export const GLTF_MATERIAL_EXTENSIONS_R182 = [
+    "KHR_materials_anisotropy", "KHR_materials_clearcoat", "KHR_materials_dispersion",
+    "KHR_materials_emissive_strength", "KHR_materials_ior", "KHR_materials_iridescence",
+    "KHR_materials_sheen", "KHR_materials_specular", "KHR_materials_transmission",
+    "KHR_materials_unlit", "KHR_materials_volume", "EXT_materials_bump",
+    "KHR_texture_transform", "KHR_texture_basisu", "EXT_texture_webp", "EXT_texture_avif",
+];
+const maps = {
+    pbrMetallicRoughness: [
+        ["color", "baseColorTexture", "srgb", "rgba", { rgb: "base color", a: "linear alpha coverage" }],
+        ["roughness", "metallicRoughnessTexture", "linear", "g", { g: "roughness", b: "metalness" }],
+        ["metalness", "metallicRoughnessTexture", "linear", "b", { g: "roughness", b: "metalness" }],
+    ],
+    material: [
+        ["normal", "normalTexture", "linear", "rgb", { rgb: "OpenGL tangent normal" }],
+        ["ao", "occlusionTexture", "linear", "r", { r: "ambient occlusion" }],
+        ["emissive", "emissiveTexture", "srgb", "rgb", { rgb: "emissive color" }],
+    ],
+    KHR_materials_sheen: [
+        ["sheenColor", "sheenColorTexture", "srgb", "rgb", { rgb: "sheen color" }],
+        ["sheenRoughness", "sheenRoughnessTexture", "linear", "a", { a: "sheen roughness" }],
+    ],
+    KHR_materials_anisotropy: [["anisotropy", "anisotropyTexture", "linear", "rgb", { rg: "tangent direction [-1, 1]", b: "anisotropy strength" }]],
+    KHR_materials_clearcoat: [
+        ["clearcoat", "clearcoatTexture", "linear", "r", { r: "clearcoat intensity" }],
+        ["clearcoatRoughness", "clearcoatRoughnessTexture", "linear", "g", { g: "clearcoat roughness" }],
+        ["clearcoatNormal", "clearcoatNormalTexture", "linear", "rgb", { rgb: "OpenGL tangent normal" }],
+    ],
+    KHR_materials_specular: [
+        ["specularIntensity", "specularTexture", "linear", "a", { a: "specular intensity" }],
+        ["specularColor", "specularColorTexture", "srgb", "rgb", { rgb: "specular color" }],
+    ],
+    KHR_materials_transmission: [["transmission", "transmissionTexture", "linear", "r", { r: "transmission" }]],
+    KHR_materials_volume: [["thickness", "thicknessTexture", "linear", "g", { g: "volume thickness" }]],
+    KHR_materials_iridescence: [
+        ["iridescence", "iridescenceTexture", "linear", "r", { r: "iridescence intensity" }],
+        ["iridescenceThickness", "iridescenceThicknessTexture", "linear", "g", { g: "iridescence thickness" }],
+    ],
+    EXT_materials_bump: [["bump", "bumpTexture", "linear", "r", { r: "normal perturbation height" }]],
+};
+const wraps = { 10497: "repeat", 33071: "clamp", 33648: "mirror" };
+const filters = { 9728: "nearest", 9729: "linear", 9984: "nearest-mipmap-nearest", 9985: "linear-mipmap-nearest", 9986: "nearest-mipmap-linear", 9987: "linear-mipmap-linear" };
+function binding(json, info, spec, path) {
+    const [role, , colorSpace, channel, channels] = spec;
+    const texture = json.textures?.[info.index];
+    if (!Number.isSafeInteger(info.index) || texture === undefined)
+        throw new Error(`${path}: missing texture ${info.index}`);
+    const sourceExtension = ["KHR_texture_basisu", "EXT_texture_webp", "EXT_texture_avif"].find((name) => texture.extensions?.[name] !== undefined);
+    const extension = sourceExtension === undefined ? undefined : texture.extensions?.[sourceExtension];
+    const imageIndex = extension?.source ?? texture.source;
+    const image = imageIndex === undefined ? undefined : json.images?.[imageIndex];
+    if (image === undefined || imageIndex === undefined || !Number.isSafeInteger(imageIndex))
+        throw new Error(`${path}: missing image ${imageIndex}`);
+    const transform = info.extensions?.KHR_texture_transform;
+    const uvSet = transform?.texCoord ?? info.texCoord ?? 0;
+    if (!Number.isInteger(uvSet) || uvSet < 0 || uvSet > 3)
+        throw new Error(`${path}: Three.js r182 supports UV sets 0–3; found ${uvSet}`);
+    const sampler = texture.sampler === undefined ? undefined : json.samplers?.[texture.sampler];
+    if (texture.sampler !== undefined && sampler === undefined)
+        throw new Error(`${path}: missing sampler ${texture.sampler}`);
+    const compression = sourceExtension === "KHR_texture_basisu" ? "basisu" : sourceExtension === "EXT_texture_webp" ? "webp" : image.mimeType === "image/ktx2" ? "ktx2" : undefined;
+    return {
+        role, texture: info.index, image: imageIndex, ...(sourceExtension === undefined ? {} : { sourceExtension }),
+        ...(image.mimeType === undefined ? {} : { mimeType: image.mimeType }),
+        ...(image.bufferView === undefined ? {} : { bufferView: image.bufferView }),
+        metadata: {
+            ...(image.uri === undefined ? {} : { url: image.uri }), colorSpace, channel, uvSet: uvSet,
+            ...(role === "normal" || role === "clearcoatNormal" ? { normalConvention: "opengl" } : {}),
+            ...(transform === undefined ? {} : { transform: {
+                    ...(transform.offset === undefined ? {} : { offset: [...transform.offset] }),
+                    ...(transform.scale === undefined ? {} : { scale: [...transform.scale] }),
+                    ...(transform.rotation === undefined ? {} : { rotation: transform.rotation }),
+                } }),
+            ...(sampler === undefined ? {} : { sampler: {
+                    wrapS: wraps[(sampler.wrapS ?? 10497)], wrapT: wraps[(sampler.wrapT ?? 10497)],
+                    ...(sampler.minFilter === undefined ? {} : { minFilter: filters[sampler.minFilter] }),
+                    ...(sampler.magFilter === undefined ? {} : { magFilter: filters[sampler.magFilter] }),
+                } }),
+            ...(compression === undefined ? {} : { compression }),
+        }, channels: { ...channels }, native: structuredClone(info),
+    };
+}
+/**
+ * Inventory validated glTF JSON without flattening slots, decoding compressed geometry, or changing materials.
+ * IDs use the supplied model namespace plus source indices, and remain stable while its pinned bytes remain stable.
+ * @capability gltf-material-inspection inspect native material slots, packed maps, attribution and compatibility
+ */
+export function inspectGltfMaterials(json, assetId) {
+    if (json?.asset?.version !== "2.0" || assetId.trim() === "")
+        throw new Error("Material inspection requires glTF 2.0 and a nonempty asset id");
+    const diagnostics = [];
+    const diagnostic = (severity, code, path, message) => diagnostics.push({ severity, code, path, message });
+    const supported = new Set([...GLTF_MATERIAL_EXTENSIONS_R182, "KHR_draco_mesh_compression", "EXT_meshopt_compression", "KHR_mesh_quantization", "KHR_lights_punctual"]);
+    for (const name of new Set([...(json.extensionsUsed ?? []), ...(json.extensionsRequired ?? [])])) {
+        if (!supported.has(name))
+            diagnostic(json.extensionsRequired?.includes(name) ? "error" : "warning", "unsupported-extension", "extensionsUsed", `${name} has no native Three.js r182 loader implementation; register a compatible loader plugin or retain the source asset outside this renderer`);
+    }
+    const materials = (json.materials ?? []).map((material, index) => {
+        const textures = [];
+        const extensions = Object.keys(material.extensions ?? {});
+        for (const [name, specs] of Object.entries(maps)) {
+            const source = name === "material" ? material : name === "pbrMetallicRoughness" ? material.pbrMetallicRoughness : material.extensions?.[name];
+            for (const spec of specs) {
+                const info = source?.[spec[1]];
+                if (info !== undefined)
+                    textures.push(binding(json, info, spec, `materials[${index}].${spec[1]}`));
+            }
+        }
+        if (extensions.includes("KHR_materials_unlit") && extensions.some((name) => /^KHR_materials_/.test(name) && name !== "KHR_materials_unlit"))
+            diagnostic("error", "incompatible-extensions", `materials[${index}]`, "Unlit materials cannot retain a physical surface response; choose one shading model");
+        if (extensions.includes("KHR_materials_pbrSpecularGlossiness") && extensions.some((name) => /^KHR_materials_/.test(name) && name !== "KHR_materials_pbrSpecularGlossiness" && name !== "KHR_materials_emissive_strength"))
+            diagnostic("error", "incompatible-extensions", `materials[${index}]`, "Legacy specular/glossiness cannot be combined with metallic/roughness physical material extensions");
+        if (extensions.includes("KHR_materials_volume") && !extensions.includes("KHR_materials_transmission"))
+            diagnostic("warning", "missing-transmission", `materials[${index}]`, "Volume thickness and attenuation require transmission to contribute to transmitted light");
+        const normal = textures.find((texture) => texture.role === "normal");
+        const direction = textures.find((texture) => texture.role === "anisotropy");
+        if (normal !== undefined && direction !== undefined && normal.metadata.uvSet !== direction.metadata.uvSet)
+            diagnostic("warning", "different-direction-uv", `materials[${index}]`, "Normal and anisotropy textures should share their tangent-space UV set");
+        return {
+            id: `${assetId}/material/${index}`, index, ...(material.name === undefined ? {} : { name: material.name }),
+            alphaMode: material.alphaMode ?? "OPAQUE", alphaCutoff: material.alphaCutoff ?? 0.5,
+            doubleSided: material.doubleSided ?? false, extensions, textures, native: structuredClone(material),
+        };
+    });
+    const slots = (json.meshes ?? []).flatMap((mesh, meshIndex) => mesh.primitives.map((primitive, primitiveIndex) => {
+        const material = primitive.material === undefined ? undefined : materials[primitive.material];
+        if (primitive.material !== undefined && material === undefined)
+            throw new Error(`meshes[${meshIndex}].primitives[${primitiveIndex}]: missing material ${primitive.material}`);
+        const uvSets = Object.keys(primitive.attributes).flatMap((name) => /^TEXCOORD_\d+$/.test(name) ? [Number(name.slice(9))] : []).sort((a, b) => a - b);
+        const hasNormals = primitive.attributes.NORMAL !== undefined;
+        const hasTangents = primitive.attributes.TANGENT !== undefined;
+        const path = `meshes[${meshIndex}].primitives[${primitiveIndex}]`;
+        for (const texture of material?.textures ?? [])
+            if ((!material?.extensions.includes("KHR_materials_unlit") || texture.role === "color") && !uvSets.includes(texture.metadata.uvSet ?? 0))
+                diagnostic("error", "missing-uv", path, `${texture.role} uses missing TEXCOORD_${texture.metadata.uvSet ?? 0}`);
+        if (material?.extensions.includes("KHR_materials_anisotropy") && !(hasNormals && hasTangents) && !material.textures.some((texture) => texture.role === "normal"))
+            diagnostic("error", "missing-tangent-space", path, "Anisotropy requires NORMAL and TANGENT attributes or a normal texture with UVs from which tangent space can be derived");
+        return {
+            id: `${assetId}/mesh/${meshIndex}/primitive/${primitiveIndex}`, mesh: meshIndex,
+            ...(mesh.name === undefined ? {} : { meshName: mesh.name }), primitive: primitiveIndex,
+            ...(material === undefined ? {} : { material: material.index, materialId: material.id, ...(material.name === undefined ? {} : { materialName: material.name }) }),
+            nodes: (json.nodes ?? []).flatMap((node, index) => node.mesh !== meshIndex ? [] : [{ index, ...(node.name === undefined ? {} : { name: node.name }) }]),
+            uvSets, hasNormals, hasTangents,
+        };
+    }));
+    return {
+        assetId, materials, slots, diagnostics,
+        ...(json.asset.copyright === undefined ? {} : { copyright: json.asset.copyright }),
+        ...(json.asset.extras === undefined ? {} : { extras: structuredClone(json.asset.extras) }),
+    };
+}
+/**
+ * Inspect the JSON chunk of complete GLB v2 bytes, including models with compressed geometry.
+ * This measures material metadata only; it never decodes geometry or resolves image URLs.
+ * @capability gltf-material-inspection inspect material slots and texture metadata directly from complete GLB bytes
+ */
+export function inspectGlbMaterials(bytes, assetId) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.length < 20 || view.getUint32(0, true) !== 0x46546c67 || view.getUint32(4, true) !== 2 || view.getUint32(8, true) !== bytes.length)
+        throw new Error("Material inspection requires complete GLB v2 bytes");
+    let json;
+    for (let offset = 12; offset < bytes.length;) {
+        if (offset + 8 > bytes.length)
+            throw new Error("Truncated GLB material chunk header");
+        const size = view.getUint32(offset, true);
+        const type = view.getUint32(offset + 4, true);
+        const start = offset + 8;
+        if (size % 4 !== 0 || start + size > bytes.length)
+            throw new Error("Invalid GLB material chunk length");
+        if (offset === 12 && type !== 0x4e4f534a)
+            throw new Error("First GLB chunk must contain JSON");
+        if (type === 0x4e4f534a) {
+            if (json !== undefined)
+                throw new Error("Duplicate GLB JSON chunk");
+            json = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(start, start + size)));
+        }
+        offset = start + size;
+    }
+    if (json === undefined)
+        throw new Error("Missing GLB material JSON");
+    return inspectGltfMaterials(json, assetId);
+}

package/dist/importSpec.d.ts

@@ -1,6 +1,6 @@
 /** Supported logical kinds for user-supplied assets. */
 export type AssetImportKind = "model" | "texture" | "material" | "sprite" | "spriteSheet" | "audio" | "font" | "hdri";
-/** A validated description of files to ingest into a game project. */
+/** A game-owned import description; paths are relative POSIX paths, roles are authored labels. */
 export interface AssetImportSpec {
     id: string;
     kind: AssetImportKind;
@@ -10,7 +10,7 @@ export interface AssetImportSpec {
     }[];
     meta?: Record<string, unknown>;
 }
-/** Result of validating an import description. */
+/** Result of validating an import description; a successful entry is an independent JSON snapshot. */
 export type ImportSpecValidation = {
     ok: true;
     entry: AssetImportSpec;
@@ -18,7 +18,16 @@ export type ImportSpecValidation = {
     ok: false;
     reason: string;
 };
-/** Validate the stable, serializable import contract before ingesting files. */
-export declare function validateImportSpec(spec: AssetImportSpec): ImportSpecValidation;
-/** Classify common asset bytes, using magic bytes and JSON sprite-sheet metadata. */
-export declare function classifyAssetFile(bytes: Uint8Array, filename: string): AssetImportKind | null;
+/**
+ * Validate untrusted import descriptions without filesystem access or path rewriting.
+ * Requires unique relative files, printable non-empty roles and plain JSON metadata (maximum depth 64).
+ * @capability asset-import-validation validate game-owned multi-file asset descriptions before ingest
+ */
+export declare function validateImportSpec(spec: unknown): ImportSpecValidation;
+/**
+ * Classify supported container headers from complete file bytes; filenames never override bytes.
+ * Recognizes GLB/glTF, PNG/JPEG/KTX2, Ogg/WAV/MP3, TTF/OTF/WOFF/WOFF2, HDR/EXR and JSON sprite sheets.
+ * This is format detection, not decoder validation. Images classify as texture; authors choose sprite/material in the spec.
+ * @capability asset-byte-classification identify custom asset formats from bytes instead of filename extensions
+ */
+export declare function classifyAssetFile(bytes: Uint8Array, _filename: string): AssetImportKind | null;

package/dist/importSpec.js

@@ -1,58 +1,230 @@
 const kinds = new Set(["model", "texture", "material", "sprite", "spriteSheet", "audio", "font", "hdri"]);
-const text = (bytes) => new TextDecoder().decode(bytes);
-/** Validate the stable, serializable import contract before ingesting files. */
+const decoder = new TextDecoder("utf-8", { fatal: true });
+function record(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return (prototype === Object.prototype || prototype === null)
+        && Object.values(Object.getOwnPropertyDescriptors(value)).every((descriptor) => "value" in descriptor && descriptor.enumerable);
+}
+function safePath(value) {
+    return value.length > 0 && value.trim() === value && !/[\\\u0000-\u001f\u007f:%?#]/.test(value)
+        && value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+function jsonData(value, ancestors = new Set(), depth = 0) {
+    if (depth > 64)
+        return false;
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object" || ancestors.has(value))
+        return false;
+    if (!Array.isArray(value) && !record(value))
+        return false;
+    if (Reflect.ownKeys(value).some((key) => typeof key === "symbol")
+        || Object.values(Object.getOwnPropertyDescriptors(value)).some((descriptor) => !("value" in descriptor)))
+        return false;
+    ancestors.add(value);
+    const valid = Array.isArray(value)
+        ? Object.keys(value).length === value.length && Array.from(value).every((item) => jsonData(item, ancestors, depth + 1))
+        : Object.values(value).every((item) => jsonData(item, ancestors, depth + 1));
+    ancestors.delete(value);
+    return valid;
+}
+/**
+ * Validate untrusted import descriptions without filesystem access or path rewriting.
+ * Requires unique relative files, printable non-empty roles and plain JSON metadata (maximum depth 64).
+ * @capability asset-import-validation validate game-owned multi-file asset descriptions before ingest
+ */
 export function validateImportSpec(spec) {
-    if (spec === null || typeof spec !== "object")
+    if (!record(spec))
         return { ok: false, reason: "spec must be an object" };
-    if (typeof spec.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(spec.id))
+    if (typeof spec.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(spec.id) || !safePath(spec.id)) {
         return { ok: false, reason: "id must be a non-empty path-safe string" };
-    if (!kinds.has(spec.kind))
+    }
+    if (typeof spec.kind !== "string" || !kinds.has(spec.kind))
         return { ok: false, reason: "kind is unsupported" };
     if (!Array.isArray(spec.files) || spec.files.length === 0)
         return { ok: false, reason: "files must contain at least one file" };
-    if (spec.files.some((file) => !file || typeof file.path !== "string" || file.path.length === 0 || file.path.includes("..")))
-        return { ok: false, reason: "files must have safe non-empty paths" };
-    return { ok: true, entry: { ...spec, files: spec.files.map((file) => ({ path: file.path, ...(file.role === undefined ? {} : { role: file.role }) })) } };
-}
-/** Classify common asset bytes, using magic bytes and JSON sprite-sheet metadata. */
-export function classifyAssetFile(bytes, filename) {
-    const lower = filename.toLowerCase();
-    if (bytes.length >= 4 && text(bytes.subarray(0, 4)) === "glTF")
-        return "model";
-    if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47)
-        return "texture";
-    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
-        return "texture";
-    if (bytes.length >= 12 && text(bytes.subarray(0, 4)) === "RIFF" && text(bytes.subarray(8, 12)) === "WAVE")
-        return "audio";
-    if (bytes.length >= 4 && text(bytes.subarray(0, 4)) === "OggS")
-        return "audio";
-    if (bytes.length >= 3 && bytes[0] === 0x49 && bytes[1] === 0x44 && bytes[2] === 0x33)
-        return "audio";
-    if (bytes.length >= 4 && ((bytes[0] === 0x00 && bytes[1] === 0x01 && bytes[2] === 0x00 && bytes[3] === 0x00) || text(bytes.subarray(0, 4)) === "OTTO" || text(bytes.subarray(0, 4)) === "wOFF"))
-        return "font";
-    if (bytes.length >= 12 && text(bytes.subarray(0, 12)) === "\xabKTX 20\xbb\r\n\x1a\n")
-        return "texture";
-    if (bytes.length >= 4 && bytes[0] === 0x76 && bytes[1] === 0x2f && bytes[2] === 0x31 && bytes[3] === 0x01)
-        return "hdri";
-    if (lower.endsWith(".woff2"))
-        return "font";
-    if (lower.endsWith(".hdr"))
-        return "hdri";
-    if (lower.endsWith(".exr"))
-        return "hdri";
-    if (lower.endsWith(".json")) {
-        try {
-            if (typeof JSON.parse(text(bytes)).frames === "object")
-                return "spriteSheet";
+    const paths = new Set();
+    const files = [];
+    for (const file of spec.files) {
+        if (!record(file) || typeof file.path !== "string" || !safePath(file.path))
+            return { ok: false, reason: "files must have safe non-empty relative paths" };
+        if (paths.has(file.path))
+            return { ok: false, reason: `duplicate file path: ${file.path}` };
+        if (file.role !== undefined && (typeof file.role !== "string" || file.role.trim() !== file.role || file.role.length === 0 || /[\u0000-\u001f\u007f]/.test(file.role))) {
+            return { ok: false, reason: `file role must be a non-empty printable string: ${file.path}` };
         }
-        catch { /* not a sprite sheet */ }
+        paths.add(file.path);
+        files.push({ path: file.path, ...(file.role === undefined ? {} : { role: file.role }) });
+    }
+    if (spec.meta !== undefined && (!record(spec.meta) || !jsonData(spec.meta)))
+        return { ok: false, reason: "meta must contain plain JSON data without cycles or non-finite numbers" };
+    return {
+        ok: true,
+        entry: {
+            id: spec.id,
+            kind: spec.kind,
+            files,
+            ...(spec.meta === undefined ? {} : { meta: JSON.parse(JSON.stringify(spec.meta)) }),
+        },
+    };
+}
+function match(bytes, signature, offset = 0) {
+    return bytes.length >= offset + signature.length && signature.every((byte, i) => bytes[offset + i] === byte);
+}
+function ascii(bytes, value, offset = 0) {
+    return bytes.length >= offset + value.length && [...value].every((char, i) => bytes[offset + i] === char.charCodeAt(0));
+}
+function json(bytes) {
+    let start = match(bytes, [0xef, 0xbb, 0xbf]) ? 3 : 0;
+    while ([0x20, 0x09, 0x0a, 0x0d].includes(bytes[start]))
+        start += 1;
+    if (bytes[start] !== 0x7b)
+        return null;
+    try {
+        return JSON.parse(decoder.decode(bytes));
+    }
+    catch {
+        return null;
+    }
+}
+function gltf(value) {
+    return record(value) && record(value.asset) && typeof value.asset.version === "string" && /^2\.\d+$/.test(value.asset.version);
+}
+function wav(bytes, view) {
+    if (bytes.length < 12 || !ascii(bytes, "WAVE", 8) || view.getUint32(4, true) !== bytes.length - 8)
+        return false;
+    let format = false;
+    let data = false;
+    let offset = 12;
+    while (offset + 8 <= bytes.length) {
+        const size = view.getUint32(offset + 4, true);
+        if (size > bytes.length - offset - 8)
+            return false;
+        if (ascii(bytes, "fmt ", offset))
+            format = size >= 16 && view.getUint16(offset + 8, true) > 0 && view.getUint16(offset + 10, true) > 0 && view.getUint32(offset + 12, true) > 0;
+        if (ascii(bytes, "data", offset))
+            data = size > 0;
+        offset += 8 + size + (size % 2);
+    }
+    return format && data && offset === bytes.length;
+}
+function exr(bytes, view) {
+    if (bytes.length < 9 || (view.getUint32(4, true) & 0xff) !== 2)
+        return false;
+    let offset = 8;
+    const attributes = new Set();
+    while (offset < bytes.length && bytes[offset] !== 0) {
+        const nameEnd = bytes.indexOf(0, offset);
+        if (nameEnd < 0)
+            return false;
+        const name = new TextDecoder().decode(bytes.subarray(offset, nameEnd));
+        const typeEnd = bytes.indexOf(0, nameEnd + 1);
+        if (typeEnd < 0 || bytes.length < typeEnd + 5)
+            return false;
+        const size = view.getUint32(typeEnd + 1, true);
+        offset = typeEnd + 5;
+        if (size > bytes.length - offset)
+            return false;
+        attributes.add(name);
+        offset += size;
+    }
+    return attributes.has("channels") && attributes.has("compression") && attributes.has("dataWindow") && bytes.length >= offset + 9;
+}
+function mp3Frame(bytes, start) {
+    if (bytes.length < start + 4)
+        return false;
+    const b1 = bytes[start + 1];
+    const b2 = bytes[start + 2];
+    if (bytes[start] !== 0xff || (b1 & 0xe0) !== 0xe0)
+        return false;
+    const version = (b1 >> 3) & 3;
+    const layer = (b1 >> 1) & 3;
+    const bitrateIndex = b2 >> 4;
+    const sampleIndex = (b2 >> 2) & 3;
+    if (version === 1 || layer !== 1 || bitrateIndex === 0 || bitrateIndex === 15 || sampleIndex === 3 || (bytes[start + 3] & 3) === 2)
+        return false;
+    const rates = version === 3 ? [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320] : [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160];
+    const frequency = [44100, 48000, 32000][sampleIndex] / (version === 3 ? 1 : version === 2 ? 2 : 4);
+    const length = Math.floor((version === 3 ? 144000 : 72000) * rates[bitrateIndex] / frequency) + ((b2 >> 1) & 1);
+    return length >= 4 && bytes.length - start >= length;
+}
+function mp3(bytes) {
+    if (!ascii(bytes, "ID3"))
+        return mp3Frame(bytes, 0);
+    if (bytes.length < 10 || bytes[3] < 2 || bytes[3] > 4 || bytes[4] === 0xff || bytes.subarray(6, 10).some((byte) => byte > 0x7f))
+        return false;
+    const version = bytes[3];
+    const flags = bytes[5];
+    if ((flags & (version === 2 ? 0x3f : version === 3 ? 0x1f : 0x0f)) !== 0)
+        return false;
+    const size = bytes[6] * 2097152 + bytes[7] * 16384 + bytes[8] * 128 + bytes[9];
+    return mp3Frame(bytes, 10 + size + (version === 4 && (flags & 0x10) !== 0 ? 10 : 0));
+}
+/**
+ * Classify supported container headers from complete file bytes; filenames never override bytes.
+ * Recognizes GLB/glTF, PNG/JPEG/KTX2, Ogg/WAV/MP3, TTF/OTF/WOFF/WOFF2, HDR/EXR and JSON sprite sheets.
+ * This is format detection, not decoder validation. Images classify as texture; authors choose sprite/material in the spec.
+ * @capability asset-byte-classification identify custom asset formats from bytes instead of filename extensions
+ */
+export function classifyAssetFile(bytes, _filename) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (ascii(bytes, "glTF")) {
+        if (bytes.length < 20 || view.getUint32(4, true) !== 2 || view.getUint32(8, true) !== bytes.length || view.getUint32(16, true) !== 0x4e4f534a)
+            return null;
+        const length = view.getUint32(12, true);
+        return length > 0 && length % 4 === 0 && length <= bytes.length - 20 && gltf(json(bytes.subarray(20, 20 + length))) ? "model" : null;
     }
-    if (lower.endsWith(".jpg") || lower.endsWith(".jpeg") || lower.endsWith(".png") || lower.endsWith(".ktx2"))
-        return "texture";
-    if (lower.endsWith(".wav") || lower.endsWith(".ogg") || lower.endsWith(".mp3"))
+    if (match(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) {
+        return bytes.length >= 33 && view.getUint32(8) === 13 && ascii(bytes, "IHDR", 12) && view.getUint32(16) > 0 && view.getUint32(20) > 0 ? "texture" : null;
+    }
+    if (match(bytes, [0xff, 0xd8, 0xff]))
+        return bytes.length >= 4 && bytes[3] !== 0 && bytes[3] !== 0xff ? "texture" : null;
+    if (match(bytes, [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a])) {
+        return bytes.length >= 80 && view.getUint32(20, true) > 0 && view.getUint32(40, true) > 0 && bytes.length >= 80 + view.getUint32(40, true) * 24 ? "texture" : null;
+    }
+    if (ascii(bytes, "RIFF"))
+        return wav(bytes, view) ? "audio" : null;
+    if (ascii(bytes, "OggS")) {
+        if (bytes.length < 27 || bytes[4] !== 0 || (bytes[5] & 0xf8) !== 0 || bytes.length < 27 + bytes[26])
+            return null;
+        const payload = bytes.subarray(27, 27 + bytes[26]).reduce((sum, size) => sum + size, 0);
+        return bytes[26] > 0 && payload > 0 && bytes.length >= 27 + bytes[26] + payload ? "audio" : null;
+    }
+    if (mp3(bytes))
         return "audio";
-    if (lower.endsWith(".ttf") || lower.endsWith(".otf") || lower.endsWith(".woff2"))
+    if (match(bytes, [0, 1, 0, 0]) || ascii(bytes, "OTTO")) {
+        if (bytes.length < 12)
+            return null;
+        const tables = view.getUint16(4);
+        if (tables === 0 || bytes.length < 12 + tables * 16)
+            return null;
+        for (let i = 0; i < tables; i += 1) {
+            const offset = view.getUint32(12 + i * 16 + 8);
+            const length = view.getUint32(12 + i * 16 + 12);
+            if (offset > bytes.length || length > bytes.length - offset)
+                return null;
+        }
         return "font";
+    }
+    if (ascii(bytes, "wOFF") || ascii(bytes, "wOF2")) {
+        const minimum = ascii(bytes, "wOF2") ? 48 : 44;
+        return bytes.length > minimum && view.getUint32(8) === bytes.length && view.getUint16(12) > 0 && view.getUint16(14) === 0 ? "font" : null;
+    }
+    if (match(bytes, [0x76, 0x2f, 0x31, 0x01]))
+        return exr(bytes, view) ? "hdri" : null;
+    if (ascii(bytes, "#?RADIANCE\n") || ascii(bytes, "#?RGBE\n") || ascii(bytes, "#?RADIANCE\r\n") || ascii(bytes, "#?RGBE\r\n")) {
+        const header = new TextDecoder().decode(bytes.subarray(0, Math.min(bytes.length, 4096)));
+        const resolution = /\r?\n\r?\n[+-]([XY]) ([1-9]\d*) [+-]([XY]) ([1-9]\d*)\r?\n/.exec(header);
+        return header.includes("FORMAT=32-bit_rle_rgbe") && resolution !== null && resolution[1] !== resolution[3] && bytes.length > resolution.index + resolution[0].length ? "hdri" : null;
+    }
+    const value = json(bytes);
+    if (gltf(value))
+        return "model";
+    if (record(value) && (record(value.frames) || Array.isArray(value.frames)) && Object.keys(value.frames).length > 0)
+        return "spriteSheet";
     return null;
 }

package/dist/index.d.ts

@@ -18,3 +18,4 @@ export { registryCatalog, componentInstallUrl, type RegistryCatalog, type Regist
 export { modelWiringSnippet, materialWiringSnippet, componentWiringSnippet, iconWiringSnippet, spriteWiringSnippet, type ModelSnippetOptions, } from "./snippet.js";
 export { verifyManifest, type VerifyResult } from "./verify.js";
 export { resolveProvenance, validateAssetReferences, type AssetProvenance, type AssetProvenanceKind, type AssetReference, type ReferenceValidation, type ResolveProvenanceOptions, type ValidateAssetReferencesOptions, type ValidateAssetReferencesResult, } from "./provisioning.js";
+export { readGlbMetrics, type GlbMetrics, type GlbTextureMetrics } from "./glbMetrics.js";

package/dist/index.js

@@ -18,3 +18,4 @@ export { registryCatalog, componentInstallUrl } from "./registry.js";
 export { modelWiringSnippet, materialWiringSnippet, componentWiringSnippet, iconWiringSnippet, spriteWiringSnippet, } from "./snippet.js";
 export { verifyManifest } from "./verify.js";
 export { resolveProvenance, validateAssetReferences, } from "./provisioning.js";
+export { readGlbMetrics } from "./glbMetrics.js";

package/dist/indexGen.d.ts

@@ -1,6 +1,8 @@
+import type { GlbMetrics } from "./glbMetrics.js";
 import type { AssetSource, CollisionMeshData, IndexEntry, ModelDims } from "./manifest.js";
 export declare function keyFromFile(file: string): string;
-export declare function entryForFile(source: AssetSource, file: string, dims?: ModelDims, collisionMesh?: CollisionMeshData, clips?: readonly string[]): IndexEntry;
+/** Build a source-owned model entry, preserving optional measured bounds, collision, clips, and inventory. */
+export declare function entryForFile(source: AssetSource, file: string, dims?: ModelDims, collisionMesh?: CollisionMeshData, clips?: readonly string[], metrics?: GlbMetrics): IndexEntry;
 export declare function indexSourceDir(source: AssetSource, dir: string): IndexEntry[];
 export interface ReindexResult {
     perSource: {