@jgengine/assets 0.19.0 → 0.21.0

package/dist/assetBudget.js

@@ -0,0 +1,110 @@
+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { readGlbMetrics } from "./glbMetrics.js";
+/**
+ * Read a GLB plus local resources under `resourceRoot`; remote URLs and symlink escapes fail without fetching.
+ * @capability asset-budgets inspect a GLB and its local external resources without network access
+ */
+export function readGlbFileMetrics(file, resourceRoot = dirname(file)) {
+    const root = realpathSync(resourceRoot);
+    const modelPath = relative(root, realpathSync(file));
+    if (modelPath === ".." || modelPath.startsWith(`..${sep}`) || isAbsolute(modelPath)) {
+        throw new Error("model escapes resource root");
+    }
+    return readGlbMetrics(readFileSync(file), (uri) => {
+        if (/^[a-z][a-z\d+.-]*:/i.test(uri) || uri.startsWith("/") || /[\\?#]/.test(uri))
+            throw new Error(`external resource must be a local relative URI: ${uri}`);
+        const decoded = decodeURIComponent(uri);
+        if (isAbsolute(decoded) || decoded.includes("\\"))
+            throw new Error(`external resource must be a local relative URI: ${uri}`);
+        const full = realpathSync(resolve(dirname(file), decoded));
+        const path = relative(root, full);
+        if (path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path))
+            throw new Error(`external resource escapes resource root: ${uri}`);
+        return readFileSync(full);
+    });
+}
+/**
+ * Check measured per-model bytes, stored triangles, and maximum image dimension against caller-owned limits.
+ * @capability asset-budgets enforce game-owned per-model byte, triangle, and texture-dimension limits
+ */
+export function checkAssetBudget(metrics, budget) {
+    const errors = [];
+    const limits = [
+        ["byteLength", "maxBytes"],
+        ["triangles", "maxTriangles"],
+        ["maxTextureDimension", "maxTextureDimension"],
+    ];
+    for (const [metric, limit] of limits) {
+        const maximum = budget[limit];
+        if (maximum === undefined)
+            continue;
+        if (!Number.isSafeInteger(maximum) || maximum < 0)
+            throw new Error(`${limit} must be a non-negative safe integer`);
+        if (metrics[metric] > maximum)
+            errors.push(`${metric} ${metrics[metric]} exceeds ${limit} ${maximum}`);
+    }
+    return errors;
+}
+/**
+ * Scan a file or directory recursively for GLBs without changing their bytes or the catalog.
+ * Paths are relative to the scanned directory, sorted lexically; unknown/custom asset folders work equally.
+ * @capability asset-budgets fail CI on local or imported GLB byte, triangle, and texture-size regressions
+ */
+export function createAssetBudgetReport(target, budget = {}) {
+    checkAssetBudget({
+        glbBytes: 0,
+        byteLength: 0,
+        triangles: 0,
+        primitives: 0,
+        textures: [],
+        maxTextureDimension: 0,
+    }, budget);
+    const absolute = resolve(target);
+    const directory = statSync(absolute).isDirectory();
+    const root = directory ? absolute : dirname(absolute);
+    const files = [];
+    const scanErrors = [];
+    const scan = (folder) => {
+        for (const entry of readdirSync(folder, { withFileTypes: true })) {
+            const full = resolve(folder, entry.name);
+            if (entry.isDirectory())
+                scan(full);
+            else if ((entry.isFile() || entry.isSymbolicLink()) && /\.glb$/i.test(entry.name))
+                files.push(full);
+            else if (entry.isSymbolicLink() && statSync(full).isDirectory()) {
+                scanErrors.push(`${relative(root, full).split(sep).join("/")}: symlink directories cannot be scanned`);
+            }
+        }
+    };
+    if (directory)
+        scan(absolute);
+    else if (/\.glb$/i.test(absolute))
+        files.push(absolute);
+    const entries = files
+        .map((file) => ({ file, path: relative(root, file).split(sep).join("/") }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+        .map(({ file, path }) => {
+        try {
+            const metrics = readGlbFileMetrics(file, root);
+            return {
+                file: path,
+                metrics,
+                errors: checkAssetBudget(metrics, budget),
+            };
+        }
+        catch (error) {
+            return {
+                file: path,
+                errors: [error instanceof Error ? error.message : String(error)],
+            };
+        }
+    });
+    const errors = [
+        ...scanErrors.sort(),
+        ...entries.flatMap((entry) => entry.errors.map((error) => `${entry.file}: ${error}`)),
+    ];
+    if (entries.length === 0)
+        errors.push("no GLB files found; provision or import assets before checking budgets");
+    return { ok: errors.length === 0, budget: { ...budget }, entries, errors };
+}

package/dist/catalogs/build.d.ts

@@ -14,6 +14,7 @@ export interface CatalogExtra {
     url: string;
     /** Human-facing label kept only in the source literal; never registered into the catalog. */
     label?: string;
+    anchor?: "center" | "origin";
     dims?: import("@jgengine/core/scene/assetCatalog").ModelDims;
     space?: import("@jgengine/core/scene/assetSpace").AssetSpace;
     clips?: readonly string[];

package/dist/catalogs/build.js

@@ -45,6 +45,7 @@ export function buildCatalog(options = {}) {
     for (const extra of options.extras ?? []) {
         catalog.register(extra.id, {
             url: extra.url,
+            ...(extra.anchor === undefined ? {} : { anchor: extra.anchor }),
             ...(extra.dims === undefined ? {} : { dims: extra.dims }),
             ...(extra.space === undefined ? {} : { space: extra.space }),
             ...(extra.clips === undefined ? {} : { clips: extra.clips }),

package/dist/cli/pull.js

@@ -3,6 +3,7 @@ import { execFileSync } from "node:child_process";
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createAssetBudgetReport } from "../assetBudget.js";
 import { downloadPackArchive, extractGlbs, extractSpriteFiles } from "../download.js";
 import { rankAssets } from "../find.js";
 import { generatedIndex } from "../generated/index.js";
@@ -192,6 +193,9 @@ async function fetchPackInto(source, outRoot, options) {
         if (maps.every((map) => map.role !== "color")) {
             fail(`no color map found in ${source.id} archive`);
         }
+        const missing = source.materialMaps?.filter((role) => !maps.some((map) => map.role === role)) ?? [];
+        if (missing.length > 0)
+            fail(`${source.id} archive is missing declared material map(s): ${missing.join(", ")}`);
         mkdirSync(outDir, { recursive: true });
         for (const map of maps)
             writeFileSync(join(outDir, map.file), map.bytes);
@@ -403,6 +407,54 @@ async function cmdAdd(argv) {
     console.log(`→ ${describeMatch(top.match)}\n`);
     await performAdd(top.match, argv);
 }
+function cmdBudget(argv) {
+    const target = argv[0];
+    if (target === undefined || target.startsWith("--")) {
+        fail("usage: budget <file|directory> [--max-bytes <n>] [--max-triangles <n>] [--max-texture-dimension <n>] [--json]");
+    }
+    const budget = {};
+    const limits = {
+        "--max-bytes": "maxBytes",
+        "--max-triangles": "maxTriangles",
+        "--max-texture-dimension": "maxTextureDimension",
+    };
+    for (let index = 1; index < argv.length; index += 1) {
+        const option = argv[index];
+        if (option === "--json")
+            continue;
+        const key = limits[option];
+        if (key === undefined)
+            fail(`unknown budget option: ${option}`);
+        const raw = argv[++index];
+        if (raw === undefined || !/^\d+$/.test(raw) || !Number.isSafeInteger(Number(raw))) {
+            fail(`${option} requires a non-negative safe integer`);
+        }
+        if (budget[key] !== undefined)
+            fail(`duplicate budget option: ${option}`);
+        budget[key] = Number(raw);
+    }
+    try {
+        const report = createAssetBudgetReport(target, budget);
+        if (argv.includes("--json"))
+            console.log(JSON.stringify(report, null, 2));
+        else {
+            for (const entry of report.entries) {
+                const metrics = entry.metrics;
+                const detail = metrics === undefined ? "unreadable"
+                    : `${metrics.byteLength} bytes, ${metrics.triangles} triangles, ${metrics.maxTextureDimension}px max texture`;
+                console.log(`${entry.file}: ${detail}`);
+            }
+            for (const error of report.errors)
+                console.error(`error: ${error}`);
+            console.log(`budget: ${report.ok ? "ok" : "failed"} (${report.entries.length} models)`);
+        }
+        if (!report.ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+}
 function cmdReindex(argv) {
     const modelsDir = resolve(argv[0] ?? resolveDefaultReindexDir(here, "models"));
     if (!existsSync(modelsDir))
@@ -478,6 +530,9 @@ if (import.meta.main) {
         case "register":
             cmdRegisterSingle(rest);
             break;
+        case "budget":
+            cmdBudget(rest);
+            break;
         case "reindex":
             cmdReindex(rest);
             break;
@@ -491,7 +546,7 @@ if (import.meta.main) {
             cmdProvenance(rest);
             break;
         default:
-            console.log("usage: assets <add|list|search|pull|register|reindex|reindex-sprites|verify|provenance> [...args]\n" +
+            console.log("usage: assets <add|list|search|pull|register|reindex|reindex-sprites|budget|verify|provenance> [...args]\n" +
                 "  assets pull starter   # every pack the starter catalog needs, into ./public/models");
             if (command !== undefined && command !== "help")
                 process.exit(1);

package/dist/glbMetrics.d.ts

@@ -0,0 +1,24 @@
+/** Stored geometry and image inventory; triangles count mesh primitives once, regardless of scene instances. */
+export interface GlbMetrics {
+    glbBytes: number;
+    /** GLB plus unique external buffer/image bytes; shared files count once per model. */
+    byteLength: number;
+    triangles: number;
+    primitives: number;
+    textures: readonly GlbTextureMetrics[];
+    maxTextureDimension: number;
+}
+/** Dimensions and encoded bytes for one glTF image, including images referenced by texture extensions. */
+export interface GlbTextureMetrics {
+    image: number;
+    width: number;
+    height: number;
+    byteLength: number;
+}
+/**
+ * Inspect GLB v2 geometry accessors and image headers offline. Throws on unreadable resources,
+ * malformed geometry, or required geometry compression; never silently reports missing data as zero.
+ * External resources are supplied by the caller; this function never fetches or decompresses bytes.
+ * @capability asset-budgets measure bytes, triangles, and texture dimensions of imported GLB assets offline
+ */
+export declare function readGlbMetrics(bytes: Uint8Array, readResource?: (uri: string) => Uint8Array): GlbMetrics;

package/dist/glbMetrics.js

@@ -0,0 +1,291 @@
+function integer(value, label, minimum = 0) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+        throw new Error(`${label}: expected an integer >= ${minimum}`);
+    return value;
+}
+function dataUri(uri) {
+    const match = /^data:[^,]*;base64,([\s\S]*)$/i.exec(uri);
+    if (match === null)
+        throw new Error("only base64 data URIs are supported");
+    return Uint8Array.from(atob(match[1]), (character) => character.charCodeAt(0));
+}
+function imageSize(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const ascii = (offset, length) => new TextDecoder().decode(bytes.subarray(offset, offset + length));
+    if (bytes.length >= 24 &&
+        view.getUint32(0) === 0x89504e47 &&
+        view.getUint32(4) === 0x0d0a1a0a &&
+        ascii(12, 4) === "IHDR") {
+        return [view.getUint32(16), view.getUint32(20)];
+    }
+    if (bytes.length >= 48 &&
+        ascii(1, 6) === "KTX 20" &&
+        bytes[0] === 0xab &&
+        bytes[7] === 0xbb &&
+        view.getUint32(8) === 0x0d0a1a0a) {
+        return [view.getUint32(20, true), view.getUint32(24, true)];
+    }
+    if (bytes.length >= 30 && ascii(0, 4) === "RIFF" && ascii(8, 4) === "WEBP") {
+        const kind = ascii(12, 4);
+        if (kind === "VP8X") {
+            const uint24 = (offset) => bytes[offset] + bytes[offset + 1] * 256 + bytes[offset + 2] * 65536;
+            return [uint24(24) + 1, uint24(27) + 1];
+        }
+        if (kind === "VP8 " && bytes[23] === 0x9d && bytes[24] === 0x01 && bytes[25] === 0x2a) {
+            return [view.getUint16(26, true) & 0x3fff, view.getUint16(28, true) & 0x3fff];
+        }
+        if (kind === "VP8L" && bytes[20] === 0x2f) {
+            const bits = view.getUint32(21, true);
+            return [(bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1];
+        }
+    }
+    if (bytes.length >= 4 && view.getUint16(0) === 0xffd8) {
+        let offset = 2;
+        while (offset + 4 <= bytes.length) {
+            if (bytes[offset] !== 0xff)
+                break;
+            while (bytes[offset] === 0xff)
+                offset += 1;
+            const marker = bytes[offset++];
+            if (marker === 0xd9 || marker === 0xda)
+                break;
+            if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7))
+                continue;
+            if (offset + 2 > bytes.length)
+                break;
+            const length = view.getUint16(offset);
+            if (length < 2 || offset + length > bytes.length)
+                break;
+            if ([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf].includes(marker) &&
+                length >= 8) {
+                return [view.getUint16(offset + 5), view.getUint16(offset + 3)];
+            }
+            offset += length;
+        }
+    }
+    throw new Error("unreadable image dimensions (supported: PNG, JPEG, WebP, KTX2)");
+}
+/**
+ * Inspect GLB v2 geometry accessors and image headers offline. Throws on unreadable resources,
+ * malformed geometry, or required geometry compression; never silently reports missing data as zero.
+ * External resources are supplied by the caller; this function never fetches or decompresses bytes.
+ * @capability asset-budgets measure bytes, triangles, and texture dimensions of imported GLB assets offline
+ */
+export function readGlbMetrics(bytes, readResource) {
+    const header = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.length < 20 ||
+        header.getUint32(0, true) !== 0x46546c67 ||
+        header.getUint32(4, true) !== 2 ||
+        header.getUint32(8, true) !== bytes.length) {
+        throw new Error("invalid GLB v2 header or file length");
+    }
+    let json;
+    let binary;
+    for (let offset = 12; offset < bytes.length;) {
+        if (offset + 8 > bytes.length)
+            throw new Error("truncated GLB chunk header");
+        const length = header.getUint32(offset, true);
+        const kind = header.getUint32(offset + 4, true);
+        const start = offset + 8;
+        if (length % 4 !== 0 || start + length > bytes.length)
+            throw new Error("invalid GLB chunk length");
+        if (offset === 12 && kind !== 0x4e4f534a)
+            throw new Error("first GLB chunk must be JSON");
+        if (kind === 0x4e4f534a) {
+            if (json !== undefined)
+                throw new Error("duplicate GLB JSON chunk");
+            json = JSON.parse(new TextDecoder().decode(bytes.subarray(start, start + length)));
+        }
+        else if (kind === 0x004e4942) {
+            if (binary !== undefined)
+                throw new Error("duplicate GLB BIN chunk");
+            binary = bytes.subarray(start, start + length);
+        }
+        offset = start + length;
+    }
+    if (json?.asset?.version !== "2.0")
+        throw new Error("missing glTF 2.0 asset metadata");
+    if (json.extensionsRequired?.some((name) => name === "KHR_draco_mesh_compression" || name === "EXT_meshopt_compression")) {
+        throw new Error("compressed geometry requires a decoder before budget measurement");
+    }
+    let byteLength = bytes.length;
+    const resources = new Map();
+    const resource = (uri) => {
+        if (resources.has(uri))
+            return resources.get(uri);
+        const result = uri.startsWith("data:") ? dataUri(uri) : readResource?.(uri);
+        if (result === undefined)
+            throw new Error(`external resource not supplied: ${uri}`);
+        if (!uri.startsWith("data:"))
+            byteLength += result.length;
+        resources.set(uri, result);
+        return result;
+    };
+    const buffers = (json.buffers ?? []).map((buffer, index) => {
+        const result = buffer.uri !== undefined ? resource(buffer.uri) : index === 0 ? binary : undefined;
+        const length = integer(buffer.byteLength, `buffer ${index} byteLength`);
+        if (result === undefined || result.length < length)
+            throw new Error(`buffer ${index}: missing or truncated bytes`);
+        return result.subarray(0, length);
+    });
+    const bufferView = (index) => {
+        integer(index, "bufferView index");
+        const entry = json.bufferViews?.[index];
+        if (entry === undefined)
+            throw new Error(`bufferView ${index}: missing`);
+        const buffer = buffers[integer(entry.buffer, "buffer index")];
+        const offset = integer(entry.byteOffset ?? 0, "bufferView byteOffset");
+        const length = integer(entry.byteLength, "bufferView byteLength");
+        if (buffer === undefined || offset + length > buffer.length)
+            throw new Error(`bufferView ${index}: out of bounds`);
+        return {
+            bytes: buffer.subarray(offset, offset + length),
+            stride: entry.byteStride,
+        };
+    };
+    const accessor = (index, indices) => {
+        integer(index, "accessor index");
+        const entry = json.accessors?.[index];
+        if (entry === undefined)
+            throw new Error(`accessor ${index}: missing`);
+        const count = integer(entry.count, `accessor ${index} count`, 1);
+        const componentBytes = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 }[entry.componentType];
+        if (componentBytes === undefined ||
+            (indices && ![5121, 5123, 5125].includes(entry.componentType)) ||
+            entry.type !== (indices ? "SCALAR" : "VEC3")) {
+            throw new Error(`accessor ${index}: invalid ${indices ? "index" : "POSITION"} type`);
+        }
+        const components = indices ? 1 : 3;
+        const width = componentBytes * components;
+        let read;
+        let maxIndex;
+        if (entry.bufferView !== undefined) {
+            const source = bufferView(entry.bufferView);
+            const stride = integer(source.stride ?? width, "accessor stride", width);
+            const offset = integer(entry.byteOffset ?? 0, "accessor byteOffset");
+            if (stride % componentBytes !== 0 ||
+                offset % componentBytes !== 0 ||
+                offset + (count - 1) * stride + width > source.bytes.length)
+                throw new Error(`accessor ${index}: out of bounds or misaligned`);
+            if (indices) {
+                const view = new DataView(source.bytes.buffer, source.bytes.byteOffset, source.bytes.length);
+                read = (i) => componentBytes === 1
+                    ? view.getUint8(offset + i * stride)
+                    : componentBytes === 2
+                        ? view.getUint16(offset + i * stride, true)
+                        : view.getUint32(offset + i * stride, true);
+            }
+        }
+        else if (entry.sparse === undefined) {
+            throw new Error(`accessor ${index}: no bufferView or sparse values`);
+        }
+        if (entry.sparse !== undefined) {
+            const sparse = entry.sparse;
+            const sparseCount = integer(sparse.count, "sparse count", 1);
+            const source = bufferView(sparse.indices.bufferView).bytes;
+            const values = bufferView(sparse.values.bufferView).bytes;
+            const size = { 5121: 1, 5123: 2, 5125: 4 }[sparse.indices.componentType];
+            const offset = integer(sparse.indices.byteOffset ?? 0, "sparse indices offset");
+            const valueOffset = integer(sparse.values.byteOffset ?? 0, "sparse values offset");
+            if (size === undefined ||
+                sparseCount > count ||
+                offset % size !== 0 ||
+                valueOffset % componentBytes !== 0 ||
+                offset + sparseCount * size > source.length ||
+                valueOffset + sparseCount * width > values.length)
+                throw new Error(`accessor ${index}: malformed sparse values`);
+            const view = new DataView(source.buffer, source.byteOffset, source.length);
+            const valueView = new DataView(values.buffer, values.byteOffset, values.length);
+            const replacements = new Map();
+            let previous = -1;
+            for (let i = 0; i < sparseCount; i += 1) {
+                const position = size === 1
+                    ? view.getUint8(offset + i * size)
+                    : size === 2
+                        ? view.getUint16(offset + i * size, true)
+                        : view.getUint32(offset + i * size, true);
+                if (position <= previous || position >= count)
+                    throw new Error(`accessor ${index}: sparse indices must be increasing and in bounds`);
+                previous = position;
+                if (indices)
+                    replacements.set(position, componentBytes === 1
+                        ? valueView.getUint8(valueOffset + i * width)
+                        : componentBytes === 2
+                            ? valueView.getUint16(valueOffset + i * width, true)
+                            : valueView.getUint32(valueOffset + i * width, true));
+            }
+            if (indices) {
+                const baseRead = read;
+                read = (i) => replacements.get(i) ?? baseRead?.(i) ?? 0;
+                if (baseRead === undefined) {
+                    maxIndex = 0;
+                    for (const value of replacements.values())
+                        maxIndex = Math.max(maxIndex, value);
+                }
+            }
+        }
+        return { count, read, maxIndex };
+    };
+    let triangles = 0;
+    let primitives = 0;
+    for (const [meshIndex, mesh] of (json.meshes ?? []).entries()) {
+        for (const [primitiveIndex, primitive] of mesh.primitives.entries()) {
+            const label = `mesh ${meshIndex} primitive ${primitiveIndex}`;
+            if (primitive.extensions?.KHR_draco_mesh_compression !== undefined)
+                throw new Error(`${label}: Draco geometry requires a decoder`);
+            const position = primitive.attributes?.POSITION;
+            if (position === undefined)
+                throw new Error(`${label}: missing POSITION`);
+            const vertices = accessor(position, false);
+            let count = vertices.count;
+            if (primitive.indices !== undefined) {
+                const indices = accessor(primitive.indices, true);
+                count = indices.count;
+                if (indices.maxIndex !== undefined) {
+                    if (indices.maxIndex >= vertices.count)
+                        throw new Error(`${label}: sparse index exceeds POSITION count ${vertices.count}`);
+                }
+                else {
+                    for (let i = 0; i < count; i += 1) {
+                        if (indices.read(i) >= vertices.count)
+                            throw new Error(`${label}: index ${i} exceeds POSITION count ${vertices.count}`);
+                    }
+                }
+            }
+            const mode = integer(primitive.mode ?? 4, `${label} mode`);
+            if (mode > 6)
+                throw new Error(`${label}: unsupported primitive mode ${mode}`);
+            if (mode === 4 && count % 3 !== 0)
+                throw new Error(`${label}: TRIANGLES count ${count} is not divisible by 3`);
+            triangles += mode === 4 ? count / 3 : mode === 5 || mode === 6 ? Math.max(0, count - 2) : 0;
+            primitives += 1;
+        }
+    }
+    const textures = (json.images ?? []).map((image, index) => {
+        const imageBytes = image.uri !== undefined
+            ? resource(image.uri)
+            : image.bufferView !== undefined
+                ? bufferView(image.bufferView).bytes
+                : undefined;
+        if (imageBytes === undefined)
+            throw new Error(`image ${index}: missing bytes`);
+        let dimensions;
+        try {
+            dimensions = imageSize(imageBytes);
+        }
+        catch (error) {
+            throw new Error(`image ${index}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const width = integer(dimensions[0], `image ${index} width`, 1);
+        const height = integer(dimensions[1], `image ${index} height`, 1);
+        return { image: index, width, height, byteLength: imageBytes.length };
+    });
+    return {
+        glbBytes: bytes.length,
+        byteLength,
+        triangles,
+        primitives,
+        textures,
+        maxTextureDimension: textures.reduce((maximum, texture) => Math.max(maximum, texture.width, texture.height), 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;