@jgengine/assets 0.18.1 → 0.21.0

package/dist/indexGen.js

@@ -1,17 +1,20 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { readGlbFileMetrics } from "./assetBudget.js";
 import { COLLISION_MESH_ASSET_IDS } from "./collisionMeshAssets.js";
 import { readGlbClips, readGlbCollisionMesh, readGlbDims } from "./dims.js";
 import { sourceById } from "./sources/index.js";
 export function keyFromFile(file) {
     return file.replace(/\.gltf\.glb$/i, "").replace(/\.glb$/i, "");
 }
-export function entryForFile(source, file, dims, collisionMesh, clips) {
+/** Build a source-owned model entry, preserving optional measured bounds, collision, clips, and inventory. */
+export function entryForFile(source, file, dims, collisionMesh, clips, metrics) {
     return {
         id: `${source.id}/${keyFromFile(file)}`,
         source: source.id,
         categories: source.categories,
         file,
+        ...(metrics === undefined ? {} : { metrics }),
         ...(dims === undefined ? {} : { dims }),
         ...(collisionMesh === undefined ? {} : { collisionMesh }),
         ...(clips === undefined ? {} : { clips }),
@@ -54,7 +57,7 @@ function measureClips(bytes) {
         return undefined;
     }
 }
-function entryFromGlb(source, file, full) {
+function entryFromGlb(source, file, full, resourceRoot) {
     let bytes;
     try {
         bytes = readFileSync(full);
@@ -64,7 +67,14 @@ function entryFromGlb(source, file, full) {
     }
     const id = `${source.id}/${keyFromFile(file)}`;
     const collisionMesh = COLLISION_MESH_ASSET_IDS.has(id) ? measureCollisionMesh(bytes) : undefined;
-    return entryForFile(source, file, measureDims(bytes), collisionMesh, measureClips(bytes));
+    let metrics;
+    try {
+        metrics = readGlbFileMetrics(full, resourceRoot);
+    }
+    catch {
+        metrics = undefined;
+    }
+    return entryForFile(source, file, measureDims(bytes), collisionMesh, measureClips(bytes), metrics);
 }
 export function indexSourceDir(source, dir) {
     const seen = new Set();
@@ -73,7 +83,7 @@ export function indexSourceDir(source, dir) {
         if (seen.has(file))
             continue;
         seen.add(file);
-        entries.push(entryFromGlb(source, file, full));
+        entries.push(entryFromGlb(source, file, full, dir));
     }
     return entries;
 }

package/dist/manifest.d.ts

@@ -1,6 +1,8 @@
 import type { ModelDims } from "@jgengine/core/scene/assetCatalog";
 import type { AssetSpace } from "@jgengine/core/scene/assetSpace";
 import type { CollisionMeshData } from "@jgengine/core/scene/collisionMesh";
+import type { GlbMetrics } from "./glbMetrics.js";
+import type { MaterialMapRole } from "./materials.js";
 export type { ModelDims };
 export type { AssetSpace };
 export type { CollisionMeshData };
@@ -30,6 +32,8 @@ export interface AssetSource {
     categories: readonly string[];
     download: AssetDownload;
     homepage?: string;
+    /** Map roles present in the pinned material archive, used by the catalog and checked during pull. */
+    materialMaps?: readonly MaterialMapRole[];
     /** Direct archive URL tried as a last resort when the primary provider path fails; see `downloadPackArchive`. */
     mirror?: string;
     /**
@@ -41,11 +45,14 @@ export interface AssetSource {
      */
     unpulled?: string;
 }
+/** A source-owned model or sprite id, with optional offline model measurements. */
 export interface IndexEntry {
     id: string;
     source: string;
     categories: readonly string[];
     file: string;
+    /** Offline byte, stored-triangle, and image inventory measured at reindex; absent if inspection fails. */
+    metrics?: GlbMetrics;
     /** Footprint/center/minY measured from the GLB at reindex; absent when the model could not be read. */
     dims?: ModelDims;
     /** Opt-in compact triangle mesh extracted at reindex (see {@link "@jgengine/core/scene/collisionMesh".CollisionMeshData}); present only for ids in `COLLISION_MESH_ASSET_IDS` whose geometry extracted. */

package/dist/materials.d.ts

@@ -23,12 +23,12 @@ export interface ExtractedMaterialMap {
  * URLs never depend on the provider's naming or the pulled resolution.
  */
 export declare function extractMaterialMaps(archive: Uint8Array): ExtractedMaterialMap[];
-/** URLs of one material's PBR maps; `ao`/`displacement` files may be absent from a rare pack. */
+/** URLs of one material's PBR maps; `ao`/`roughness`/`ktx2` appear only when declared by its source. */
 export interface MaterialMaps {
     color: string;
     normal: string;
-    roughness: string;
-    ao: string;
+    roughness?: string;
+    ao?: string;
     displacement: string;
     ktx2?: string;
 }

package/dist/materials.js

@@ -65,10 +65,10 @@ function refFor(source, basePath) {
         maps: {
             color: `${base}/${MATERIAL_MAP_FILES.color}`,
             normal: `${base}/${MATERIAL_MAP_FILES.normal}`,
-            roughness: `${base}/${MATERIAL_MAP_FILES.roughness}`,
-            ao: `${base}/${MATERIAL_MAP_FILES.ao}`,
+            ...(source.materialMaps?.includes("roughness") ? { roughness: `${base}/${MATERIAL_MAP_FILES.roughness}` } : {}),
+            ...(source.materialMaps?.includes("ao") ? { ao: `${base}/${MATERIAL_MAP_FILES.ao}` } : {}),
             displacement: `${base}/${MATERIAL_MAP_FILES.displacement}`,
-            ktx2: `${base}/${MATERIAL_MAP_FILES.ktx2}`,
+            ...(source.materialMaps?.includes("ktx2") ? { ktx2: `${base}/${MATERIAL_MAP_FILES.ktx2}` } : {}),
         },
     };
 }

package/dist/snippet.js

@@ -30,7 +30,7 @@ export function materialWiringSnippet(id, basePath = "/materials") {
         `export const materials = buildMaterialCatalog({ basePath: ${JSON.stringify(basePath)} });`,
         ``,
         `const material = materials.resolve(${JSON.stringify(id)})!;`,
-        `// material.maps => { color, normal, roughness, ao, displacement } URLs under ${basePath}/${id}/`,
+        `// material.maps => { color, normal, displacement, roughness?, ao?, ktx2? } URLs under ${basePath}/${id}/`,
         ``,
         `// onto the ground (terrain() in defineGame({ world: environment({ terrain: ... }) })):`,
         `terrain({ detail: { material: { maps: material.maps, repeat: 4 } } })`,

package/dist/sources/ambientcg.js

@@ -6,38 +6,39 @@
  * catalog is generated per family instead of hand-typing hundreds of ids.
  */
 const RESOLUTION = "1K-JPG";
+// Optional-map availability for the pinned 1K-JPG variants: https://ambientcg.com/api/v2/full_json?type=Material&include=downloadData
 const FAMILIES = [
-    { family: "Grass", count: 5, categories: ["ground", "grass", "nature"] },
-    { family: "Ground", count: 25, categories: ["ground", "dirt", "mud"] },
-    { family: "Rock", count: 25, categories: ["rock", "cliff", "stone"] },
-    { family: "Rocks", count: 8, categories: ["rock", "scatter"] },
-    { family: "Gravel", count: 15, categories: ["ground", "gravel"] },
-    { family: "Snow", count: 6, categories: ["ground", "snow", "winter"] },
-    { family: "Ice", count: 3, categories: ["ice", "winter"] },
-    { family: "Lava", count: 4, categories: ["lava", "volcanic"] },
-    { family: "Moss", count: 2, categories: ["moss", "nature"] },
-    { family: "Bark", count: 8, categories: ["bark", "wood", "nature"] },
-    { family: "Wood", count: 30, categories: ["wood"] },
-    { family: "WoodFloor", count: 25, categories: ["wood", "floor", "interior"] },
-    { family: "Planks", count: 12, categories: ["wood", "planks"] },
-    { family: "Bricks", count: 30, categories: ["brick", "wall"] },
-    { family: "PavingStones", count: 25, categories: ["paving", "stone", "path"] },
-    { family: "Tiles", count: 30, categories: ["tile", "floor", "interior"] },
-    { family: "Concrete", count: 25, categories: ["concrete", "urban"] },
-    { family: "Asphalt", count: 12, categories: ["asphalt", "road", "urban"] },
-    { family: "Metal", count: 25, categories: ["metal"] },
-    { family: "MetalPlates", count: 10, categories: ["metal", "plates", "scifi"] },
-    { family: "Fabric", count: 25, categories: ["fabric", "cloth"] },
-    { family: "Leather", count: 12, categories: ["leather"] },
-    { family: "Marble", count: 12, categories: ["marble", "stone", "interior"] },
-    { family: "Plaster", count: 7, categories: ["plaster", "wall", "interior"] },
-    { family: "Facade", count: 6, categories: ["facade", "building"] },
-    { family: "Terrazzo", count: 8, categories: ["floor", "interior"] },
-    { family: "Wicker", count: 4, categories: ["wicker"] },
-    { family: "Rope", count: 2, categories: ["rope"] },
-    { family: "Cardboard", count: 3, categories: ["cardboard", "prop"] },
-    { family: "Paper", count: 3, categories: ["paper", "prop"] },
-    { family: "RoofingTiles", count: 8, categories: ["roof", "tile", "building"] },
+    { family: "Grass", count: 5, categories: ["ground", "grass", "nature"], ao: [1, 2, 3, 4, 5] },
+    { family: "Ground", count: 25, categories: ["ground", "dirt", "mud"], ao: [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19, 20, 21, 22, 23, 24, 25] },
+    { family: "Rock", count: 25, categories: ["rock", "cliff", "stone"], ao: [2, 3, 4, 5, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25] },
+    { family: "Rocks", count: 8, categories: ["rock", "scatter"], ao: [1, 2, 3, 4, 5, 6, 7, 8] },
+    { family: "Gravel", count: 15, withoutRoughness: [1], categories: ["ground", "gravel"], ao: [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] },
+    { family: "Snow", count: 6, categories: ["ground", "snow", "winter"], ao: [6] },
+    { family: "Ice", count: 3, categories: ["ice", "winter"], ao: [] },
+    { family: "Lava", count: 4, categories: ["lava", "volcanic"], ao: [] },
+    { family: "Moss", count: 2, categories: ["moss", "nature"], ao: [1, 2] },
+    { family: "Bark", count: 8, categories: ["bark", "wood", "nature"], ao: [2, 3, 4, 5, 6, 7, 8] },
+    { family: "Wood", count: 30, categories: ["wood"], ao: [11] },
+    { family: "WoodFloor", count: 25, categories: ["wood", "floor", "interior"], ao: [3, 7, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25] },
+    { family: "Planks", count: 12, categories: ["wood", "planks"], ao: [3, 4, 5, 6, 7, 8, 9, 10, 11, 12] },
+    { family: "Bricks", count: 30, categories: ["brick", "wall"], ao: [4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 19, 20, 22, 23, 24, 25, 26, 28, 30] },
+    { family: "PavingStones", count: 25, categories: ["paving", "stone", "path"], ao: [2, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25] },
+    { family: "Tiles", count: 30, categories: ["tile", "floor", "interior"], ao: [7, 8, 9, 10, 11, 17, 18, 19, 26, 27, 28] },
+    { family: "Concrete", count: 25, withoutRoughness: [1], categories: ["concrete", "urban"], ao: [3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 25] },
+    { family: "Asphalt", count: 12, categories: ["asphalt", "road", "urban"], ao: [3, 4, 5, 6, 7, 8] },
+    { family: "Metal", count: 25, categories: ["metal"], ao: [] },
+    { family: "MetalPlates", count: 10, categories: ["metal", "plates", "scifi"], ao: [10] },
+    { family: "Fabric", count: 25, categories: ["fabric", "cloth"], ao: [7, 8, 9] },
+    { family: "Leather", count: 12, categories: ["leather"], ao: [8] },
+    { family: "Marble", count: 12, categories: ["marble", "stone", "interior"], ao: [] },
+    { family: "Plaster", count: 7, categories: ["plaster", "wall", "interior"], ao: [7] },
+    { family: "Facade", count: 6, categories: ["facade", "building"], ao: [] },
+    { family: "Terrazzo", count: 8, categories: ["floor", "interior"], ao: [] },
+    { family: "Wicker", count: 4, categories: ["wicker"], ao: [1, 2, 3, 4] },
+    { family: "Rope", count: 2, categories: ["rope"], ao: [] },
+    { family: "Cardboard", count: 3, categories: ["cardboard", "prop"], ao: [] },
+    { family: "Paper", count: 3, categories: ["paper", "prop"], ao: [] },
+    { family: "RoofingTiles", count: 8, categories: ["roof", "tile", "building"], ao: [6, 7, 8] },
 ];
 /** Upstream asset id (`Grass001`) for a material source id (`ambientcg-grass001`). */
 export function ambientcgAssetId(source) {
@@ -56,6 +57,11 @@ function materialSource(family, index) {
         license: "CC0-1.0",
         author: "ambientCG",
         categories: family.categories,
+        materialMaps: [
+            "color", "normal", "displacement",
+            ...(family.withoutRoughness?.includes(index) ? [] : ["roughness"]),
+            ...(family.ao.includes(index) ? ["ao"] : []),
+        ],
         download: { url: `https://ambientcg.com/get?file=${assetId}_${RESOLUTION}.zip` },
         homepage: `https://ambientcg.com/view?id=${assetId}`,
     };

package/dist/staticPrefabBake.d.ts

@@ -0,0 +1,58 @@
+import type { EditorPrefab } from "@jgengine/core/editor/types";
+import { type StaticPrefabBox } from "@jgengine/core/editor/staticPrefab";
+import type { ModelAssetRef, ModelDims } from "@jgengine/core/scene/assetCatalog";
+import { type CollisionMeshData } from "@jgengine/core/scene/collisionMesh";
+/** A verified external source image and its complete runtime URL. URI matches the source GLB exactly. */
+export interface StaticPrefabTextureSource {
+    uri: string;
+    path: string;
+    sha256: string;
+    bytes: number;
+    url: string;
+}
+/** Original static model bytes; paths are absolute and every external image must have a pin. */
+export interface StaticPrefabSource {
+    catalogId: string;
+    path: string;
+    sha256: string;
+    bytes: number;
+    textures?: readonly StaticPrefabTextureSource[];
+}
+/** Deterministic inventory and provenance for an editor-authored static artifact. */
+export interface StaticPrefabBakeReport {
+    assetId: string;
+    prefabId: string;
+    sha256: string;
+    bytes: number;
+    /** GLB and unique external images; shared textures still contribute real encoded bytes. */
+    byteLength: number;
+    triangles: number;
+    submissions: number;
+    /** Optimization merges source mesh primitives; original mesh/primitive selectors are not portable. */
+    materialLayout: "merged-by-source-material";
+    bounds: StaticPrefabBox;
+    sourcePrefabSha256: string;
+    staticBakeSha256: string;
+    sources: readonly {
+        catalogId: string;
+        sha256: string;
+        bytes: number;
+        copyright?: string;
+        textures?: readonly Omit<StaticPrefabTextureSource, "path">[];
+    }[];
+    textures: readonly Omit<StaticPrefabTextureSource, "path">[];
+}
+/** GLB bytes and catalog-ready metadata; origin anchoring preserves the editable fragment's local frame. */
+export interface StaticPrefabBakeResult {
+    bytes: Uint8Array;
+    dims: ModelDims;
+    space: NonNullable<ModelAssetRef["space"]>;
+    anchor: "origin";
+    collisionMesh: CollisionMeshData;
+    report: StaticPrefabBakeReport;
+}
+/**
+ * Bake pinned static source art in an editor prefab's local frame. Node-only; never mutates authored data.
+ * @capability static-prefab-export export editable prefab compositions with source materials and collision metadata
+ */
+export declare function bakeStaticPrefab(prefab: EditorPrefab, sources: readonly StaticPrefabSource[]): Promise<StaticPrefabBakeResult>;

package/dist/staticPrefabBake.js

@@ -0,0 +1,315 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { Document, GLB_BUFFER, NodeIO, PropertyType, Root } from "@gltf-transform/core";
+import { ALL_EXTENSIONS } from "@gltf-transform/extensions";
+import { dedup, flatten, getBounds, join, mergeDocuments, unpartition, weld } from "@gltf-transform/functions";
+import { parseStaticPrefabBake } from "@jgengine/core/editor/staticPrefab";
+import { encodeCollisionMesh } from "@jgengine/core/scene/collisionMesh";
+import { markerCatalogId } from "@jgengine/core/world/authoredObjects";
+import { readGlbMetrics } from "./glbMetrics.js";
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+async function readPin(pin) {
+    if (!isAbsolute(pin.path))
+        throw new Error(`Static prefab source path must be absolute: ${pin.path}`);
+    if (!Number.isSafeInteger(pin.bytes) || pin.bytes <= 0 || !/^[a-f0-9]{64}$/.test(pin.sha256))
+        throw new Error(`Invalid byte/hash pin for ${pin.path}`);
+    let bytes;
+    try {
+        bytes = await readFile(pin.path);
+    }
+    catch (cause) {
+        throw new Error(`Provision or restore pinned static prefab source ${pin.path}`, { cause });
+    }
+    if (bytes.length !== pin.bytes || sha256(bytes) !== pin.sha256)
+        throw new Error(`Provision or verify ${pin.path}: static prefab source does not match its byte/hash pin`);
+    return bytes;
+}
+function markerTransform(marker) {
+    if (marker.kind !== "prop")
+        throw new Error(`Static prefab marker ${marker.id} requires kind prop; interactive or custom kind ${marker.kind} is unsupported`);
+    const catalogId = markerCatalogId(marker);
+    if (catalogId === null)
+        throw new Error(`Static prefab marker ${marker.id} requires a pinned catalogId`);
+    const unsupported = ["scale", "scaleX", "scaleY", "scaleZ", "rotation", "rotationX", "rotationZ", "quaternion", "matrix", "offsetY", "yOffset", "targetHeight", "anchor", "animation", "interactive", "interaction", "behavior", "on", "action", "triggers", "triggerRadius", "generatorId", "params", "material", "materialId", "materials", "materialAssignments", "surface", "maps", "tint"];
+    for (const key of unsupported) {
+        if (marker.meta?.[key] !== undefined || marker[key] !== undefined)
+            throw new Error(`Static prefab marker ${marker.id}: unsupported ${key}; keep this part outside the static bake`);
+    }
+    const lift = marker.meta?.verticalOffset ?? 0;
+    const yaw = marker.rotationY ?? 0;
+    const translation = [marker.position.x, marker.position.y, marker.position.z];
+    if (!translation.every(Number.isFinite) || typeof lift !== "number" || !Number.isFinite(lift) || !Number.isFinite(yaw))
+        throw new Error(`Static prefab marker ${marker.id} requires finite position, verticalOffset, and rotationY`);
+    translation[1] += lift;
+    if (!Number.isFinite(translation[1]))
+        throw new Error(`Static prefab marker ${marker.id} has an overflowing verticalOffset`);
+    return { catalogId, translation, yaw };
+}
+function decodeGlb(bytes) {
+    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("Static prefab sources must be valid GLB v2 files");
+    const jsonLength = view.getUint32(12, true);
+    if (view.getUint32(16, true) !== 0x4e4f534a || jsonLength % 4 !== 0 || 20 + jsonLength > bytes.length)
+        throw new Error("Invalid static prefab GLB JSON chunk");
+    const json = JSON.parse(new TextDecoder().decode(bytes.subarray(20, 20 + jsonLength)));
+    const offset = 20 + jsonLength;
+    const resources = {};
+    if (offset < bytes.length) {
+        if (offset + 8 > bytes.length || view.getUint32(offset + 4, true) !== 0x004e4942 || view.getUint32(offset, true) % 4 !== 0 || offset + 8 + view.getUint32(offset, true) !== bytes.length)
+            throw new Error("Invalid static prefab GLB BIN chunk");
+        resources[GLB_BUFFER] = bytes.subarray(offset + 8);
+    }
+    return { json, resources };
+}
+function validateStaticSource(json, path) {
+    if ((json.animations?.length ?? 0) > 0 || (json.skins?.length ?? 0) > 0 || json.nodes?.some((node) => node.skin !== undefined))
+        throw new Error(`${path}: animations and skins cannot be baked into a static prefab`);
+    if (json.nodes?.some((node) => node.weights !== undefined) || json.meshes?.some((mesh) => mesh.weights !== undefined || mesh.primitives.some((primitive) => (primitive.targets?.length ?? 0) > 0)))
+        throw new Error(`${path}: morph targets cannot be baked into a static prefab`);
+    if (json.scenes?.length !== 1 || (json.cameras?.length ?? 0) > 0)
+        throw new Error(`${path}: static prefab sources require exactly one scene and no cameras`);
+    const supported = new Set(ALL_EXTENSIONS.map((extension) => extension.EXTENSION_NAME));
+    for (const extension of new Set([...(json.extensionsUsed ?? []), ...(json.extensionsRequired ?? [])])) {
+        if (!supported.has(extension) || !/^(KHR_materials_|KHR_texture_transform$|KHR_texture_basisu$|EXT_texture_webp$|EXT_texture_avif$)/.test(extension))
+            throw new Error(`${path}: unsupported static prefab extension ${extension}`);
+    }
+    for (const node of json.nodes ?? []) {
+        for (const vector of [node.matrix, node.translation, node.rotation, node.scale]) {
+            if (vector !== undefined && !vector.every(Number.isFinite))
+                throw new Error(`${path}: non-finite source transform`);
+        }
+        if (node.scale?.some((value) => value === 0))
+            throw new Error(`${path}: zero-scale source transform`);
+        if (node.matrix !== undefined) {
+            const m = node.matrix;
+            const columns = [[m[0], m[1], m[2]], [m[4], m[5], m[6]], [m[8], m[9], m[10]]];
+            if (m[3] !== 0 || m[7] !== 0 || m[11] !== 0 || m[15] !== 1 || columns.some((column) => Math.hypot(...column) === 0) || columns.some((a, i) => columns.some((b, j) => i < j && Math.abs(a.reduce((sum, value, k) => sum + value * b[k], 0)) > 1e-6 * Math.hypot(...a) * Math.hypot(...b))))
+                throw new Error(`${path}: sheared or non-affine source transform`);
+        }
+    }
+    for (const mesh of json.meshes ?? []) {
+        for (const primitive of mesh.primitives) {
+            if ((primitive.mode ?? 4) !== 4 || primitive.attributes.POSITION === undefined || Object.keys(primitive.attributes).some((name) => /^(JOINTS|WEIGHTS)_/.test(name)))
+                throw new Error(`${path}: static prefabs require unskinned triangle primitives with POSITION`);
+        }
+    }
+}
+function encodeGlb(output, document) {
+    const json = output.json;
+    const buffer = json.buffers?.[0];
+    if (json.buffers?.length !== 1 || buffer?.uri === undefined)
+        throw new Error("Static prefab output requires one binary buffer");
+    let binary = output.resources[buffer.uri];
+    if (binary === undefined)
+        throw new Error("Static prefab output buffer is missing");
+    const textures = document.getRoot().listTextures();
+    for (let i = 0; i < (json.images?.length ?? 0); i += 1) {
+        const image = json.images[i];
+        const runtimeUrl = textures[i].getURI();
+        if (runtimeUrl !== "") {
+            // GLTFTransform's GLTF writer strips image directories; the pinned runtime URI is authoritative.
+            image.uri = runtimeUrl;
+        }
+        else {
+            const encoded = image.uri === undefined ? undefined : output.resources[image.uri];
+            if (encoded === undefined)
+                throw new Error("Static prefab embedded image is missing");
+            const offset = Math.ceil(binary.length / 4) * 4;
+            const combined = new Uint8Array(offset + encoded.length);
+            combined.set(binary);
+            combined.set(encoded, offset);
+            binary = combined;
+            image.bufferView = (json.bufferViews ??= []).length;
+            json.bufferViews.push({ buffer: 0, byteOffset: offset, byteLength: encoded.length });
+            delete image.uri;
+        }
+    }
+    buffer.byteLength = binary.length;
+    delete buffer.uri;
+    const text = new TextEncoder().encode(JSON.stringify(json));
+    const jsonSize = Math.ceil(text.length / 4) * 4;
+    const binSize = Math.ceil(binary.length / 4) * 4;
+    const bytes = new Uint8Array(28 + jsonSize + binSize);
+    const view = new DataView(bytes.buffer);
+    for (const [offset, value] of [[0, 0x46546c67], [4, 2], [8, bytes.length], [12, jsonSize], [16, 0x4e4f534a], [20 + jsonSize, binSize], [24 + jsonSize, 0x004e4942]])
+        view.setUint32(offset, value, true);
+    bytes.fill(32, 20, 20 + jsonSize);
+    bytes.set(text, 20);
+    bytes.set(binary, 28 + jsonSize);
+    return bytes;
+}
+function dedupPinnedTextures(document) {
+    const owners = new Map();
+    for (const texture of document.getRoot().listTextures()) {
+        const image = texture.getImage();
+        if (image === null)
+            throw new Error("Static prefab texture has no verified image bytes");
+        // Generic dedup ignores URIs, which merges separately owned but byte-identical source images.
+        const key = JSON.stringify([texture.getURI(), texture.getMimeType(), sha256(image), texture.getName(), texture.getExtras()]);
+        const existing = owners.get(key);
+        if (existing === undefined) {
+            owners.set(key, texture);
+        }
+        else {
+            for (const parent of texture.listParents())
+                if (!(parent instanceof Root))
+                    parent.swap(texture, existing);
+            texture.dispose();
+        }
+    }
+}
+function textureProvenance(pin) {
+    return { uri: pin.uri, url: pin.url, sha256: pin.sha256, bytes: pin.bytes };
+}
+/**
+ * Bake pinned static source art in an editor prefab's local frame. Node-only; never mutates authored data.
+ * @capability static-prefab-export export editable prefab compositions with source materials and collision metadata
+ */
+export async function bakeStaticPrefab(prefab, sources) {
+    return bakeStaticPrefabSnapshot(structuredClone(prefab), structuredClone(sources));
+}
+async function bakeStaticPrefabSnapshot(prefab, sources) {
+    if (prefab.staticBake === undefined)
+        throw new Error(`Prefab ${prefab.id} has no authored staticBake settings`);
+    const config = parseStaticPrefabBake(prefab.staticBake);
+    const fragment = prefab.fragment;
+    if (fragment.markers.length === 0 || fragment.volumes.length > 0 || fragment.paths.length > 0 || fragment.annotations.length > 0)
+        throw new Error(`Static prefab ${prefab.id} requires model markers only; retain gameplay regions, paths, and notes outside the bake`);
+    const ids = new Set();
+    const parts = fragment.markers.map((marker) => {
+        if (ids.has(marker.id))
+            throw new Error(`Static prefab ${prefab.id} has duplicate marker id ${marker.id}`);
+        ids.add(marker.id);
+        return markerTransform(marker);
+    });
+    const byId = new Map();
+    for (const source of sources) {
+        if (byId.has(source.catalogId))
+            throw new Error(`Duplicate static prefab source ${source.catalogId}`);
+        byId.set(source.catalogId, source);
+    }
+    const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
+    const document = new Document();
+    const scene = document.createScene(prefab.name);
+    document.getRoot().setDefaultScene(scene);
+    const loaded = new Map();
+    const usedSources = [];
+    const usedTextures = new Map();
+    for (let i = 0; i < parts.length; i += 1) {
+        const part = parts[i];
+        let sourceDocument = loaded.get(part.catalogId);
+        if (sourceDocument === undefined) {
+            const source = byId.get(part.catalogId);
+            if (source === undefined)
+                throw new Error(`Static prefab marker ${fragment.markers[i].id}: no pinned source for ${part.catalogId}`);
+            const bytes = await readPin(source);
+            const input = decodeGlb(bytes);
+            validateStaticSource(input.json, source.path);
+            const textures = new Map();
+            const verifiedTextures = new Map();
+            for (const texture of source.textures ?? []) {
+                if (textures.has(texture.uri))
+                    throw new Error(`${source.path}: duplicate texture pin URI ${texture.uri}`);
+                if (!texture.url.startsWith("/") && !/^https?:\/\//.test(texture.url))
+                    throw new Error(`${source.path}: texture requires a full runtime URL: ${texture.url}`);
+                textures.set(texture.uri, texture);
+            }
+            for (const image of input.json.images ?? []) {
+                if (image.uri === undefined || image.uri.startsWith("data:"))
+                    continue;
+                const pin = textures.get(image.uri);
+                if (pin === undefined)
+                    throw new Error(`${source.path}: unpinned external texture ${image.uri}`);
+                const previous = usedTextures.get(pin.url);
+                if (previous !== undefined && (previous.pin.sha256 !== pin.sha256 || previous.pin.bytes !== pin.bytes))
+                    throw new Error(`Conflicting static prefab texture pins for ${pin.url}`);
+                const data = await readPin(pin);
+                input.resources[image.uri] = data;
+                verifiedTextures.set(image.uri, pin);
+                usedTextures.set(pin.url, { pin: { ...pin }, data });
+            }
+            readGlbMetrics(bytes, (uri) => {
+                const resource = input.resources[uri];
+                if (resource === undefined)
+                    throw new Error(`${source.path}: unpinned external resource ${uri}`);
+                return resource;
+            });
+            sourceDocument = await io.readJSON(input);
+            for (const texture of sourceDocument.getRoot().listTextures()) {
+                const pin = textures.get(texture.getURI());
+                if (pin !== undefined)
+                    texture.setURI(pin.url);
+            }
+            loaded.set(part.catalogId, sourceDocument);
+            usedSources.push({ catalogId: source.catalogId, sha256: source.sha256, bytes: source.bytes, ...(input.json.asset.copyright === undefined ? {} : { copyright: input.json.asset.copyright }), ...(verifiedTextures.size === 0 ? {} : { textures: [...verifiedTextures.values()].map(textureProvenance) }) });
+        }
+        const mapping = mergeDocuments(document, sourceDocument);
+        const pivot = document.createNode(fragment.markers[i].id).setTranslation(part.translation).setRotation([0, Math.sin(part.yaw / 2), 0, Math.cos(part.yaw / 2)]);
+        for (const sourceScene of sourceDocument.getRoot().listScenes()) {
+            for (const node of sourceScene.listChildren())
+                pivot.addChild(mapping.get(node));
+            mapping.get(sourceScene).dispose();
+        }
+        scene.addChild(pivot);
+    }
+    dedupPinnedTextures(document);
+    await document.transform(dedup({ propertyTypes: [PropertyType.ACCESSOR, PropertyType.MESH, PropertyType.MATERIAL], keepUniqueNames: true }), flatten(), join({ keepNamed: false }), weld(), unpartition());
+    const positions = [];
+    const indices = [];
+    let submissions = 0;
+    scene.traverse((node) => {
+        const matrix = node.getWorldMatrix();
+        for (const primitive of node.getMesh()?.listPrimitives() ?? []) {
+            const position = primitive.getAttribute("POSITION");
+            const base = positions.length / 3;
+            const vertex = [0, 0, 0];
+            for (let i = 0; i < position.getCount(); i += 1) {
+                position.getElement(i, vertex);
+                for (let axis = 0; axis < 3; axis += 1)
+                    positions.push(matrix[axis] * vertex[0] + matrix[axis + 4] * vertex[1] + matrix[axis + 8] * vertex[2] + matrix[axis + 12]);
+            }
+            const sourceIndices = primitive.getIndices();
+            for (let i = 0; i < (sourceIndices?.getCount() ?? position.getCount()); i += 1)
+                indices.push(base + (sourceIndices?.getScalar(i) ?? i));
+            submissions += 1;
+        }
+    });
+    const collisionMesh = encodeCollisionMesh({ positions, indices });
+    if (collisionMesh === null)
+        throw new Error(`Static prefab ${prefab.id} has no nondegenerate collision triangles`);
+    const bounds = getBounds(scene);
+    if (![...bounds.min, ...bounds.max].every(Number.isFinite))
+        throw new Error(`Static prefab ${prefab.id} has invalid bounds`);
+    if (config.collisionBoxes === undefined && bounds.min.some((value, axis) => value >= bounds.max[axis]))
+        throw new Error(`Static prefab ${prefab.id} has degenerate bounds; author explicit collisionBoxes`);
+    collisionMesh.boxes = config.collisionBoxes ?? [{ min: [...bounds.min], max: [...bounds.max] }];
+    const dims = {
+        footprint: { w: bounds.max[0] - bounds.min[0], d: bounds.max[2] - bounds.min[2] },
+        center: { x: (bounds.max[0] + bounds.min[0]) / 2, z: (bounds.max[2] + bounds.min[2]) / 2 },
+        minY: bounds.min[1], maxY: bounds.max[1],
+    };
+    const output = await io.writeJSON(document);
+    const copyrights = [...new Set(usedSources.flatMap((source) => source.copyright === undefined ? [] : [source.copyright]))];
+    if (copyrights.length > 0)
+        output.json.asset.copyright = copyrights.join("\n");
+    const bytes = encodeGlb(output, document);
+    const metrics = readGlbMetrics(bytes, (url) => {
+        const texture = usedTextures.get(url);
+        if (texture === undefined)
+            throw new Error(`Static prefab output has an unverified texture ${url}`);
+        return texture.data;
+    });
+    return {
+        bytes, dims, space: { anchor: { x: 0, z: 0 }, unitScale: 1 }, anchor: "origin", collisionMesh,
+        report: {
+            assetId: config.assetId, prefabId: prefab.id, sha256: sha256(bytes), bytes: bytes.length, byteLength: metrics.byteLength,
+            triangles: metrics.triangles, submissions, materialLayout: "merged-by-source-material", bounds: { min: [...bounds.min], max: [...bounds.max] },
+            sourcePrefabSha256: sha256(JSON.stringify(fragment)), staticBakeSha256: sha256(JSON.stringify(config)),
+            sources: usedSources, textures: [...usedTextures.values()].map(({ pin }) => textureProvenance(pin)),
+        },
+    };
+}

package/dist/verify.js

@@ -3,7 +3,7 @@ import { generatedIndex } from "./generated/index.js";
 import { materialAliases } from "./materials.js";
 import { singles } from "./singles.js";
 import { sources } from "./sources/index.js";
-/** Providers allowed repo-wide; Kenney.nl is permanently barred — see CLAUDE.md "Never Kenney". */
+/** Providers allowed repo-wide; Kenney.nl is permanently barred — see AGENTS.md "Never use Kenney assets". */
 const ALLOWED_PROVIDERS = ["quaternius", "kaykit", "ambientcg", "gameicons"];
 function containsKenney(value) {
     return value.toLowerCase().includes("kenney");
@@ -16,7 +16,7 @@ export function verifyData(input) {
         if (source.author.trim().length === 0)
             errors.push(`source ${source.id}: missing author`);
         if (!ALLOWED_PROVIDERS.includes(source.provider)) {
-            errors.push(`source ${source.id}: provider "${source.provider}" is not allowlisted (Never Kenney — see CLAUDE.md)`);
+            errors.push(`source ${source.id}: provider "${source.provider}" is not allowlisted (Never Kenney — see AGENTS.md)`);
         }
         if (containsKenney(source.id))
             errors.push(`source ${source.id}: id contains banned "kenney" substring`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/assets",
-  "version": "0.18.1",
+  "version": "0.21.0",
   "description": "Self-generating, license-verified index of thousands of CC0 3D models for JGengine. Sources fetch from providers' own CDNs at pull time; the npm tarball ships only the typed index and CLI (no GLB bytes).",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,7 +35,10 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.18.1",
+    "@gltf-transform/core": "4.2.1",
+    "@gltf-transform/extensions": "4.2.1",
+    "@gltf-transform/functions": "4.2.1",
+    "@jgengine/core": "^0.21.0",
     "fflate": "^0.8.2"
   },
   "devDependencies": {