@jgengine/assets 0.19.0 → 0.21.0

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.19.0",
+  "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.19.0",
+    "@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": {

package/skills/ce-handoff/SKILL.md

@@ -25,7 +25,7 @@ Create one immutable handoff at the destination the user requested, or use the m
 ### Build the handoff
 
 1. Distill the current objective and the user's latest intent. If a focus was supplied, make it the `resume_focus`.
-2. Inspect only the workspace state needed to explain what exists now. Use JGengine project instructions already in context (`AGENTS.md` / `CLAUDE.md`, `workflow`, domain skills).
+2. Inspect only the workspace state needed to explain what exists now. Use JGengine project instructions already in context (`AGENTS.md`, `workflow`, domain skills).
 3. Point to plans, issues, commits, diffs, documentation, and relevant files instead of reproducing their contents. Prefer repository-relative paths (`docs/plans/…`, `packages/…`, `Games/…`).
 4. Redact secrets, credentials, tokens, and unrelated personal information. Preserve operational paths only when the next agent needs them.
 5. Write or publish with existing tools. If the user named another path, folder, format, or publication destination, honor it. Do not also create a managed-store copy unless asked.

package/skills/jgengine/SKILL.md

@@ -9,6 +9,22 @@ This skill decides what to load; it is not an engine manual. Package map, comman
 
 A created project installs only `jgengine`, `jgengine-editor`, `jgengine-verify`, `game-design`, and `jgengine-ui`. Run `npx jgengine skills -p --all` before loading any other domain named below. Those projects do not ship `api.md`; read exact signatures from the `.d.ts` files under `node_modules/@jgengine/<pkg>/dist/`.
 
+Created projects pin their scaffolding CLI as a local devDependency, separately from SDK versions. Run `npx jgengine doctor` after SDK upgrades to check CLI compatibility. Skill installation preserves newer or differing unversioned copies; update the project CLI first, and use `skills -p --force` only when replacement is intended. Each packaged skill install records its CLI and SDK versions in `.jgengine-version.json`.
+
+## Framework-first decisions
+
+For every requested interaction, feature, fix or visual change, follow the boundary in
+[AGENTS.md](../../../AGENTS.md): discover the installed
+capability, adopt it, or improve its shared owner before adding reusable game-local code.
+Games keep unique rules, content, assets and presentation. Custom markup is not a reason
+to copy focus handling, input tracking, storage or model lifecycle.
+
+Check installed versions before recreating an upstream fix. A published upgrade may
+replace a workaround; a beta merge does not update consumers. In the games workspace,
+the root catalog owns SDK versions. After adoption, remove superseded local machinery
+and verify the actual game. Outside these repositories, report missing SDK contracts
+upstream rather than treating a local engine implementation as the finished solution.
+
 ## 1. Establish the target
 
 For greenfield builds, write `src/art-direction.md` before any code.
@@ -26,6 +42,10 @@ Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player
 
 For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
 
+`doctor` and `upgrade` resolve Bun `catalog:` and `catalog:<name>` declarations from the nearest workspace's `workspaces.catalog` or `workspaces.catalogs`, and follow hoisted SDK installs. Missing or malformed catalog entries fail diagnostics. `upgrade` is read-only by default. For catalog-owned versions, run `upgrade --plan --to <published-version>` at the workspace root or in a game, review the whole root catalog plan and migrations, then run `upgrade --apply --to <published-version>`. Apply preserves per-game `catalog:` declarations, unrelated text, CLI/github versions, and a held editor override; it verifies published SDK targets and refuses files changed while planning. Apply changes declarations only: run `bun install` at the root, then `jgengine doctor --workspace --json` once there to check installed SDK identities across declared workspace owners. Rebuild, migrate, and verify game behavior afterward. `--json` includes exact before/after text; an apply prints its plan before writing and reports write status on stderr. A report without installed packages labels its resolved pins as a declared baseline.
+
+When a linked consumer renders differently despite matching root SDK versions, `doctor` checks direct consumers and SDK dependency/peer paths, including private copies with the same version. Review the reported importer and real paths, align the shared catalog and linked-consumer declarations, then reinstall at the root and rerun `doctor --workspace`; a root install may leave private linked-package installs intact. Restart running games after reinstall. Workspace mode checks installed identities only, reports coverage, and refuses unsupported patterns, escaped symlinks or exhausted traversal budgets. The default project audit stays scoped; neither mode covers custom bundler aliases or indirect non-SDK chains.
+
 ## 2. Select domains
 
 Load only rows the target needs. Do not preload every domain.
@@ -49,12 +69,12 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 Within each selected domain:
 
 0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) (`combat-loop`, `loot`, `world-drops`, `click-target`, `ability-bar`, `hitscan-weapon`, `rolled-gear`, `enter-vehicle` and more); `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); in the monorepo, `grep -i "<intent>" .claude/skills/*/capabilities.md` does the same. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
+1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); agents can use `--json --limit 5` for ranked imports and recipes with total, partial-match, and truncation fields. In the monorepo, `rg -i "<intent>" .claude/skills/*/capabilities.md` does the same search. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
 2. Open `api.md` (monorepo) or the package `.d.ts` only when exact signatures are needed; grep it, never read it whole.
 3. Open the linked reference only for a deeper recipe or trap.
 4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.
 
-If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.
+If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter and a reviewed consumer cleanup; coordinate a differently composed second consumer when applicable. Recipes wire SDK APIs, not copied implementations. If editor-owned content cannot be expressed, file the editor gap first; track any fallback and its removal path.
 
 ## 4. Build and finish