@jgengine/assets 0.10.0 → 0.12.0

package/dist/cli/pull.js

@@ -1,26 +1,34 @@
 #!/usr/bin/env node
+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 { downloadPackArchive, extractGlbs, extractTextures } from "../download.js";
+import { downloadPackArchive, extractGlbs, extractSpriteFiles } from "../download.js";
 import { rankAssets } from "../find.js";
 import { generatedIndex } from "../generated/index.js";
+import { generatedSpriteIndex } from "../generated-sprites/index.js";
 import { reindex } from "../indexGen.js";
 import { isScrapeDownload } from "../manifest.js";
+import { extractMaterialMaps } from "../materials.js";
+import { validateAssetReferences } from "../provisioning.js";
 import { registryCatalog } from "../registry.js";
-import { componentWiringSnippet, iconWiringSnippet, modelWiringSnippet } from "../snippet.js";
-import { sourceById } from "../sources/index.js";
+import { componentWiringSnippet, iconWiringSnippet, materialWiringSnippet, modelWiringSnippet, spriteWiringSnippet, } from "../snippet.js";
+import { materialSources, sourceById, spriteSources } from "../sources/index.js";
+import { reindexSprites } from "../spriteIndexGen.js";
 import { verifyManifest } from "../verify.js";
-import { resolveGeneratedDir, resolvePackageRoot, resolvePackageTreeRoot } from "./paths.js";
+import { resolveGeneratedDir, resolveGeneratedSpritesDir, resolvePackageRoot, resolvePackageTreeRoot } from "./paths.js";
 const here = dirname(fileURLToPath(import.meta.url));
 const packageTreeRoot = resolvePackageTreeRoot(here);
 const pkgRoot = resolvePackageRoot(here);
 /** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import. */
 export const generatedDir = resolveGeneratedDir(here);
+/** Sprite-pack counterpart of `generatedDir`. */
+export const generatedSpritesDir = resolveGeneratedSpritesDir(here);
 export { resolveGeneratedDir } from "./paths.js";
 const singlesJson = join(packageTreeRoot, "singles.json");
 const localDir = join(pkgRoot, "local");
 const CDN_BASE = "https://cdn.jsdelivr.net/gh/Noisemaker111/jgengine@main/packages/assets/local";
+/** @internal */
 export function flag(argv, name) {
     const index = argv.indexOf(`--${name}`);
     return index >= 0 ? argv[index + 1] : undefined;
@@ -29,6 +37,31 @@ function fail(message) {
     console.error(`error: ${message}`);
     process.exit(1);
 }
+/**
+ * The runtime's own fetch, with a curl fallback for hosts it cannot reach —
+ * some proxied sandboxes tear down bun's TLS stream to GitHub's release-asset
+ * host while curl (which honors SSL_CERT_FILE) gets through fine.
+ */
+export const cliFetch = (async (input, init) => {
+    try {
+        return await fetch(input, init);
+    }
+    catch (error) {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        if (init?.method !== undefined && init.method !== "GET")
+            throw error;
+        try {
+            const bytes = execFileSync("curl", ["-fsSL", "--max-time", "600", url], {
+                maxBuffer: 1024 * 1024 * 1024,
+            });
+            return new Response(new Uint8Array(bytes));
+        }
+        catch {
+            throw error;
+        }
+    }
+});
+/** @internal */
 export function describeNetworkFailure(error) {
     const chain = [];
     let current = error;
@@ -46,6 +79,31 @@ function cmdList(argv) {
     const category = flag(argv, "category");
     const source = flag(argv, "source");
     const limit = Number(flag(argv, "limit") ?? "50");
+    if (flag(argv, "kind") === "material") {
+        const rows = materialSources.filter((entry) => category === undefined || entry.categories.includes(category));
+        for (const entry of rows.slice(0, limit)) {
+            console.log(`${entry.id}\t[${entry.categories.join(",")}]\t${entry.license}`);
+        }
+        console.log(`— ${Math.min(rows.length, limit)} of ${rows.length} materials`);
+        return;
+    }
+    if (flag(argv, "kind") === "sprite") {
+        const rows = generatedSpriteIndex.filter((entry) => (category === undefined || entry.categories.includes(category)) &&
+            (source === undefined || entry.source === source));
+        for (const entry of rows.slice(0, limit)) {
+            console.log(`${entry.id}\t[${entry.categories.join(",")}]\t${entry.file}`);
+        }
+        console.log(`— ${Math.min(rows.length, limit)} of ${rows.length} sprite/icon files`);
+        return;
+    }
+    if (flag(argv, "kind") === "spritePack") {
+        const rows = spriteSources.filter((entry) => category === undefined || entry.categories.includes(category));
+        for (const entry of rows.slice(0, limit)) {
+            console.log(`${entry.id}\t[${entry.categories.join(",")}]\t${entry.license}`);
+        }
+        console.log(`— ${Math.min(rows.length, limit)} of ${rows.length} sprite/icon packs`);
+        return;
+    }
     const rows = generatedIndex.filter((entry) => (category === undefined || entry.categories.includes(category)) &&
         (source === undefined || entry.source === source));
     for (const entry of rows.slice(0, limit)) {
@@ -65,9 +123,11 @@ function cmdSearch(argv) {
     }
     console.log(`— ${Math.min(rows.length, limit)} of ${rows.length} matches for "${term}"`);
 }
+/** @internal */
 export function isPopulated(dir) {
     return existsSync(dir) && readdirSync(dir).length > 0;
 }
+/** @internal */
 export async function cmdPull(argv) {
     const sourceId = argv[0];
     if (sourceId === undefined) {
@@ -77,7 +137,7 @@ export async function cmdPull(argv) {
     if (source === undefined)
         fail(`unknown source: ${sourceId}`);
     const outRoot = resolve(flag(argv, "dir") ?? "public");
-    const outDir = join(outRoot, "models", sourceId);
+    const outDir = join(outRoot, packSubdir(source), sourceId);
     const offline = argv.includes("--offline");
     const mirrorBase = flag(argv, "mirror") ?? process.env.JGENGINE_ASSETS_MIRROR;
     if (offline) {
@@ -89,28 +149,62 @@ export async function cmdPull(argv) {
         return;
     }
     const result = await fetchPackInto(source, outRoot, { mirrorBase });
+    console.log(describeFetchResult(source, result));
+}
+function packSubdir(source) {
+    if (source.kind === "material")
+        return "materials";
+    if (source.kind === "sprite")
+        return "sprites";
+    return "models";
+}
+function describeFetchResult(source, result) {
+    if (source.kind === "material") {
+        return `pulled ${result.textures} material map(s) -> ${result.outDir}`;
+    }
+    if (source.kind === "sprite") {
+        return `pulled ${result.models} sprite/icon file(s) -> ${result.outDir}`;
+    }
     const textureNote = result.textures > 0 ? ` + ${result.textures} texture(s)` : "";
-    console.log(`pulled ${result.models} models${textureNote} -> ${result.outDir}`);
+    return `pulled ${result.models} models${textureNote} -> ${result.outDir}`;
 }
 async function fetchPackInto(source, outRoot, options) {
-    const outDir = join(outRoot, "models", source.id);
+    const outDir = join(outRoot, packSubdir(source), source.id);
     console.log(`resolving ${source.id}${isScrapeDownload(source.download) ? " (scrape)" : ""}` +
         `${options.mirrorBase !== undefined ? ` [mirror override: ${options.mirrorBase}]` : ""}…`);
-    const { archive, url, attempted } = await downloadPackArchive(source, { mirrorBase: options.mirrorBase });
+    const { archive, url, attempted } = await downloadPackArchive(source, {
+        mirrorBase: options.mirrorBase,
+        fetchImpl: cliFetch,
+    });
     console.log(`downloaded ${url}${attempted.length > 1 ? ` (after ${attempted.length - 1} failed attempt(s))` : ""}`);
-    const glbs = extractGlbs(archive);
-    if (glbs.length === 0)
+    if (source.kind === "material") {
+        const maps = extractMaterialMaps(archive);
+        if (maps.every((map) => map.role !== "color")) {
+            fail(`no color map found in ${source.id} archive`);
+        }
+        mkdirSync(outDir, { recursive: true });
+        for (const map of maps)
+            writeFileSync(join(outDir, map.file), map.bytes);
+        return { outDir, models: 0, textures: maps.length, url };
+    }
+    if (source.kind === "sprite") {
+        const files = extractSpriteFiles(archive);
+        if (files.length === 0)
+            fail(`no .svg/.png files found in ${source.id} archive`);
+        mkdirSync(outDir, { recursive: true });
+        for (const file of files)
+            writeFileSync(join(outDir, file.file), file.bytes);
+        return { outDir, models: files.length, textures: 0, url };
+    }
+    const { models, images } = extractGlbs(archive);
+    if (models.length === 0)
         fail(`no .glb files found in ${source.id} archive`);
     mkdirSync(outDir, { recursive: true });
-    for (const glb of glbs)
+    for (const glb of models)
         writeFileSync(join(outDir, glb.file), glb.bytes);
-    const textures = extractTextures(archive);
-    for (const texture of textures) {
-        const dest = join(outDir, texture.file);
-        mkdirSync(dirname(dest), { recursive: true });
-        writeFileSync(dest, texture.bytes);
-    }
-    return { outDir, models: glbs.length, textures: textures.length, url };
+    for (const image of images)
+        writeFileSync(join(outDir, image.file), image.bytes);
+    return { outDir, models: models.length, textures: images.length, url };
 }
 function readSingles() {
     if (!existsSync(singlesJson))
@@ -157,17 +251,31 @@ function cmdRegisterSingle(argv) {
     writeSingles(singles);
     console.log(`added single ${id} -> ${url}${isUrl ? " (0 bytes stored)" : " (copied to local/)"}`);
 }
-const KINDS = ["model", "pack", "component", "icon"];
+const KINDS = [
+    "model",
+    "pack",
+    "material",
+    "component",
+    "icon",
+    "sprite",
+    "spritePack",
+];
 function describeMatch(match) {
     switch (match.kind) {
         case "model":
             return `[model]     ${match.id}${match.via === "alias" ? "  (alias)" : match.via === "single" ? "  (single)" : ""}`;
         case "pack":
             return `[pack]      ${match.source} — ${match.title}`;
+        case "material":
+            return `[material]  ${match.id} — ${match.title}`;
         case "component":
             return `[component] ${match.name} — ${match.title}`;
         case "icon":
             return `[icon]      ${match.name}`;
+        case "sprite":
+            return `[sprite]    ${match.id}`;
+        case "spritePack":
+            return `[spritePack] ${match.source} — ${match.title}`;
     }
 }
 async function performAdd(match, argv) {
@@ -184,19 +292,58 @@ async function performAdd(match, argv) {
         console.log(iconWiringSnippet(match.name));
         return;
     }
+    const outRoot = resolve(flag(argv, "dir") ?? "public");
+    const mirrorBase = flag(argv, "mirror") ?? process.env.JGENGINE_ASSETS_MIRROR;
+    if (match.kind === "material") {
+        const source = sourceById.get(match.id);
+        if (source === undefined)
+            fail(`match resolves to unknown source: ${match.id}`);
+        const outDir = join(outRoot, "materials", match.id);
+        if (isPopulated(outDir)) {
+            console.log(`${match.id} already present in ${outDir}`);
+        }
+        else {
+            const result = await fetchPackInto(source, outRoot, { mirrorBase });
+            console.log(describeFetchResult(source, result));
+        }
+        console.log(`\nwire it in:\n`);
+        console.log(materialWiringSnippet(match.id));
+        return;
+    }
+    if (match.kind === "sprite" || match.kind === "spritePack") {
+        const source = sourceById.get(match.source);
+        if (source === undefined)
+            fail(`match resolves to unknown source: ${match.source}`);
+        const outDir = join(outRoot, "sprites", match.source);
+        if (isPopulated(outDir)) {
+            console.log(`${match.source} already present in ${outDir}`);
+        }
+        else {
+            const result = await fetchPackInto(source, outRoot, { mirrorBase });
+            console.log(describeFetchResult(source, result));
+        }
+        const result = reindexSprites(join(outRoot, "sprites"), generatedSpritesDir);
+        console.log(`reindexed ${result.total} entries -> ${generatedSpritesDir}`);
+        if (match.kind === "sprite") {
+            console.log(`\nwire it in:\n`);
+            console.log(spriteWiringSnippet(match.id));
+        }
+        else {
+            console.log(`\n${match.title}: browse ids with \`assets list --kind sprite --source ${match.source}\`, then wire like:\n`);
+            console.log(spriteWiringSnippet(`${match.source}/<icon>`));
+        }
+        return;
+    }
     const source = sourceById.get(match.source);
     if (source === undefined)
         fail(`match resolves to unknown source: ${match.source}`);
-    const outRoot = resolve(flag(argv, "dir") ?? "public");
     const outDir = join(outRoot, "models", match.source);
-    const mirrorBase = flag(argv, "mirror") ?? process.env.JGENGINE_ASSETS_MIRROR;
     if (isPopulated(outDir)) {
         console.log(`${match.source} already present in ${outDir}`);
     }
     else {
         const result = await fetchPackInto(source, outRoot, { mirrorBase });
-        const textureNote = result.textures > 0 ? ` + ${result.textures} texture(s)` : "";
-        console.log(`pulled ${result.models} models${textureNote} -> ${result.outDir}`);
+        console.log(describeFetchResult(source, result));
     }
     const result = reindex(join(outRoot, "models"), generatedDir);
     console.log(`reindexed ${result.total} entries -> ${generatedDir}`);
@@ -212,7 +359,7 @@ async function performAdd(match, argv) {
 async function cmdAdd(argv) {
     const query = argv[0];
     if (query === undefined) {
-        fail("usage: add <query> [--kind model|pack|component|icon] [--dir <dir>] [--mirror <baseUrl>] [--json]\n" +
+        fail("usage: add <query> [--kind model|pack|material|component|icon|sprite|spritePack] [--dir <dir>] [--mirror <baseUrl>] [--json]\n" +
             "       add <path|url> --license <l> [--category <c>]   (register a one-off single into the shipped index)");
     }
     // Back-compat: the old `add` registered a one-off single, always with --license.
@@ -255,6 +402,15 @@ function cmdReindex(argv) {
         console.log(`  ${row.source}: ${row.count}`);
     console.log(`reindexed ${result.total} entries -> ${generatedDir}`);
 }
+function cmdReindexSprites(argv) {
+    const spritesDir = resolve(argv[0] ?? join("public", "sprites"));
+    if (!existsSync(spritesDir))
+        fail(`sprites dir not found: ${spritesDir}`);
+    const result = reindexSprites(spritesDir, generatedSpritesDir);
+    for (const row of result.perSource)
+        console.log(`  ${row.source}: ${row.count}`);
+    console.log(`reindexed ${result.total} entries -> ${generatedSpritesDir}`);
+}
 function cmdVerify() {
     const result = verifyManifest();
     if (result.ok) {
@@ -265,6 +421,35 @@ function cmdVerify() {
         console.error(`  ✗ ${error}`);
     fail(`verify failed with ${result.errors.length} problem(s)`);
 }
+/**
+ * Resolve each id against the provisioning contract and print its owner —
+ * `committed`, `provisioned` (with the `assets pull <source>` step), or
+ * `dangling`. Exits non-zero if any id is dangling, so a clean-clone gate can
+ * feed it logical ids and fail on references no source or single owns.
+ */
+function cmdProvenance(argv) {
+    const ids = argv.filter((arg) => !arg.startsWith("--"));
+    if (ids.length === 0)
+        fail("usage: assets provenance <id> [<id>...]");
+    const references = ids.map((id) => ({ consumer: "cli", id }));
+    const result = validateAssetReferences(references);
+    for (const row of result.results) {
+        const p = row.provenance;
+        const detail = p.kind === "provisioned"
+            ? `${p.resolvedPath}  (${p.provisioningStep})`
+            : p.kind === "committed"
+                ? `${p.resolvedPath}`
+                : "no owner";
+        const mark = row.ok ? "✓" : "✗";
+        console.log(`  ${mark} ${p.id}: ${p.kind} — ${detail}`);
+    }
+    if (result.provisioning.length > 0) {
+        console.log(`provisioning steps: ${result.provisioning.join(", ")}`);
+    }
+    if (!result.ok)
+        fail(`provenance: ${result.errors.length} dangling reference(s)`);
+    console.log("provenance: ok");
+}
 if (import.meta.main) {
     const [command, ...rest] = process.argv.slice(2);
     switch (command) {
@@ -286,11 +471,17 @@ if (import.meta.main) {
         case "reindex":
             cmdReindex(rest);
             break;
+        case "reindex-sprites":
+            cmdReindexSprites(rest);
+            break;
         case "verify":
             cmdVerify();
             break;
+        case "provenance":
+            cmdProvenance(rest);
+            break;
         default:
-            console.log("usage: assets <add|list|search|pull|register|reindex|verify> [...args]");
+            console.log("usage: assets <add|list|search|pull|register|reindex|reindex-sprites|verify|provenance> [...args]");
             if (command !== undefined && command !== "help")
                 process.exit(1);
     }

package/dist/collisionMeshAssets.d.ts

@@ -0,0 +1,2 @@
+/** Catalog assets that ship a collision mesh in the generated index. Opt-in only: each entry adds ~10-30KB of quantized triangles to the index and a BVH raycast per query, so list only concave models whose fitted box lies (archways, rings, frames). */
+export declare const COLLISION_MESH_ASSET_IDS: ReadonlySet<string>;

package/dist/collisionMeshAssets.js

@@ -0,0 +1,6 @@
+/** Catalog assets that ship a collision mesh in the generated index. Opt-in only: each entry adds ~10-30KB of quantized triangles to the index and a BVH raycast per query, so list only concave models whose fitted box lies (archways, rings, frames). */
+export const COLLISION_MESH_ASSET_IDS = new Set([
+    "kaykit-dungeon/wall_arched",
+    "kaykit-dungeon/wall_archedwindow_open",
+    "kaykit-dungeon/wall_archedwindow_gated",
+]);

package/dist/dims.d.ts

@@ -1,3 +1,10 @@
 import type { ModelDims } from "@jgengine/core/scene/assetCatalog";
+import { type CollisionMeshData } from "@jgengine/core/scene/collisionMesh";
 export type { ModelDims };
 export declare function readGlbDims(bytes: Uint8Array): ModelDims | null;
+/**
+ * Extract a model-space collision triangle soup from a GLB and compress it with {@link encodeCollisionMesh}.
+ * Walks the default scene, transforming each TRIANGLES primitive's float32 VEC3 positions by the node's world
+ * matrix, and returns `null` for a JSON-only GLB or when no triangle survives quantization.
+ */
+export declare function readGlbCollisionMesh(bytes: Uint8Array): CollisionMeshData | null;

package/dist/dims.js

@@ -1,6 +1,8 @@
+import { encodeCollisionMesh } from "@jgengine/core/scene/collisionMesh";
 const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
 const GLB_MAGIC = 0x46546c67;
 const CHUNK_JSON = 0x4e4f534a;
+const CHUNK_BIN = 0x004e4942;
 function multiply(a, b) {
     const out = new Array(16);
     for (let col = 0; col < 4; col += 1) {
@@ -139,5 +141,157 @@ export function readGlbDims(bytes) {
         footprint: { w: bounds.max[0] - bounds.min[0], d: bounds.max[2] - bounds.min[2] },
         center: { x: (bounds.min[0] + bounds.max[0]) / 2, z: (bounds.min[2] + bounds.max[2]) / 2 },
         minY: bounds.min[1],
+        maxY: bounds.max[1],
     };
 }
+const COMPONENT_FLOAT = 5126;
+const COMPONENT_U8 = 5121;
+const COMPONENT_U16 = 5123;
+const COMPONENT_U32 = 5125;
+const MODE_TRIANGLES = 4;
+/** The GLB's binary chunk, or `null` for a JSON-only GLB (no geometry buffer to read). */
+function readBinChunk(bytes) {
+    if (bytes.byteLength < 20)
+        return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(0, true) !== GLB_MAGIC)
+        return null;
+    const jsonChunkLength = view.getUint32(12, true);
+    if (view.getUint32(16, true) !== CHUNK_JSON)
+        return null;
+    const header = 20 + jsonChunkLength;
+    if (header + 8 > bytes.byteLength)
+        return null;
+    const chunkLength = view.getUint32(header, true);
+    if (view.getUint32(header + 4, true) !== CHUNK_BIN)
+        return null;
+    const start = header + 8;
+    const end = Math.min(start + chunkLength, bytes.byteLength);
+    return bytes.subarray(start, end);
+}
+/** Float32 VEC3 accessor values in model space, honoring bufferView/accessor byteOffset and byteStride; `null` for a malformed or out-of-bounds accessor. */
+function readVec3Accessor(gltf, bin, accessorIndex) {
+    const accessor = gltf.accessors?.[accessorIndex];
+    if (accessor === undefined)
+        return null;
+    if (accessor.componentType !== COMPONENT_FLOAT || accessor.type !== "VEC3")
+        return null;
+    const count = accessor.count;
+    if (count === undefined || count <= 0)
+        return null;
+    if (accessor.bufferView === undefined)
+        return null;
+    const bufferView = gltf.bufferViews?.[accessor.bufferView];
+    if (bufferView === undefined)
+        return null;
+    const stride = bufferView.byteStride ?? 12;
+    const base = (bufferView.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
+    if (base < 0 || base + (count - 1) * stride + 12 > bin.byteLength)
+        return null;
+    const view = new DataView(bin.buffer, bin.byteOffset, bin.byteLength);
+    const out = new Float64Array(count * 3);
+    for (let i = 0; i < count; i += 1) {
+        const offset = base + i * stride;
+        out[i * 3] = view.getFloat32(offset, true);
+        out[i * 3 + 1] = view.getFloat32(offset + 4, true);
+        out[i * 3 + 2] = view.getFloat32(offset + 8, true);
+    }
+    return out;
+}
+/** Scalar index accessor values (u8/u16/u32), honoring byteOffset and byteStride; `null` for a malformed or out-of-bounds accessor. */
+function readIndexAccessor(gltf, bin, accessorIndex) {
+    const accessor = gltf.accessors?.[accessorIndex];
+    if (accessor === undefined || accessor.type !== "SCALAR")
+        return null;
+    const componentType = accessor.componentType;
+    const componentBytes = componentType === COMPONENT_U8 ? 1 : componentType === COMPONENT_U16 ? 2 : componentType === COMPONENT_U32 ? 4 : 0;
+    if (componentBytes === 0)
+        return null;
+    const count = accessor.count;
+    if (count === undefined || count <= 0)
+        return null;
+    if (accessor.bufferView === undefined)
+        return null;
+    const bufferView = gltf.bufferViews?.[accessor.bufferView];
+    if (bufferView === undefined)
+        return null;
+    const stride = bufferView.byteStride ?? componentBytes;
+    const base = (bufferView.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
+    if (base < 0 || base + (count - 1) * stride + componentBytes > bin.byteLength)
+        return null;
+    const view = new DataView(bin.buffer, bin.byteOffset, bin.byteLength);
+    const out = new Uint32Array(count);
+    for (let i = 0; i < count; i += 1) {
+        const offset = base + i * stride;
+        out[i] =
+            componentType === COMPONENT_U8
+                ? view.getUint8(offset)
+                : componentType === COMPONENT_U16
+                    ? view.getUint16(offset, true)
+                    : view.getUint32(offset, true);
+    }
+    return out;
+}
+/** Append one triangle primitive's world-space geometry to the soup; skips non-triangle modes and malformed accessors, appending nothing on failure. */
+function addPrimitive(gltf, bin, primitive, world, soup) {
+    if ((primitive.mode ?? MODE_TRIANGLES) !== MODE_TRIANGLES)
+        return;
+    const accessorIndex = primitive.attributes?.POSITION;
+    if (accessorIndex === undefined)
+        return;
+    const positions = readVec3Accessor(gltf, bin, accessorIndex);
+    if (positions === null)
+        return;
+    let localIndices = null;
+    if (primitive.indices !== undefined) {
+        localIndices = readIndexAccessor(gltf, bin, primitive.indices);
+        if (localIndices === null)
+            return;
+    }
+    const vertexBase = soup.positions.length / 3;
+    const vertexCount = positions.length / 3;
+    for (let v = 0; v < vertexCount; v += 1) {
+        const [wx, wy, wz] = transformPoint(world, positions[v * 3], positions[v * 3 + 1], positions[v * 3 + 2]);
+        soup.positions.push(wx, wy, wz);
+    }
+    if (localIndices === null) {
+        for (let v = 0; v < vertexCount; v += 1)
+            soup.indices.push(vertexBase + v);
+    }
+    else {
+        for (let i = 0; i < localIndices.length; i += 1)
+            soup.indices.push(vertexBase + localIndices[i]);
+    }
+}
+function walkCollision(gltf, bin, nodeIndex, parent, soup) {
+    const node = gltf.nodes?.[nodeIndex];
+    if (node === undefined)
+        return;
+    const world = multiply(parent, fromTRS(node));
+    if (node.mesh !== undefined) {
+        const mesh = gltf.meshes?.[node.mesh];
+        for (const primitive of mesh?.primitives ?? [])
+            addPrimitive(gltf, bin, primitive, world, soup);
+    }
+    for (const child of node.children ?? [])
+        walkCollision(gltf, bin, child, world, soup);
+}
+/**
+ * Extract a model-space collision triangle soup from a GLB and compress it with {@link encodeCollisionMesh}.
+ * Walks the default scene, transforming each TRIANGLES primitive's float32 VEC3 positions by the node's world
+ * matrix, and returns `null` for a JSON-only GLB or when no triangle survives quantization.
+ */
+export function readGlbCollisionMesh(bytes) {
+    const gltf = readJsonChunk(bytes);
+    if (gltf === null)
+        return null;
+    const bin = readBinChunk(bytes);
+    if (bin === null)
+        return null;
+    const sceneIndex = gltf.scene ?? 0;
+    const roots = gltf.scenes?.[sceneIndex]?.nodes ?? gltf.nodes?.map((_, index) => index) ?? [];
+    const soup = { positions: [], indices: [] };
+    for (const root of roots)
+        walkCollision(gltf, bin, root, IDENTITY, soup);
+    return encodeCollisionMesh(soup);
+}

package/dist/download.d.ts

@@ -1,22 +1,38 @@
+import { type UnzipFileFilter } from "fflate";
 import { type AssetSource } from "./manifest.js";
 export type FetchLike = typeof fetch;
+/** Max size of a downloaded (still-compressed) archive, in bytes. Provider zips run tens of MB; this leaves headroom without buffering an unbounded response. */
+export declare const MAX_ARCHIVE_DOWNLOAD_BYTES: number;
+/** Max total uncompressed size this module will inflate out of one archive, in bytes. */
+export declare const MAX_ARCHIVE_UNCOMPRESSED_BYTES: number;
+/** Max number of entries this module will extract out of one archive. */
+export declare const MAX_ARCHIVE_ENTRY_COUNT = 20000;
+/** Max allowed originalSize/size ratio for a single archive entry — past this it's treated as a zip bomb. */
+export declare const MAX_ARCHIVE_COMPRESSION_RATIO = 100;
+/** @internal */
+export declare function boundedExtractFilter(matches: UnzipFileFilter): UnzipFileFilter;
 export interface ExtractedGlb {
     file: string;
     bytes: Uint8Array;
 }
-export interface ExtractedTexture {
-    /** Path relative to the pack output dir, e.g. "Textures/colormap.png". */
+/** An image a pack's models reference, shipped flat beside the `.glb` files. */
+export interface ExtractedPackImage {
+    /** Flat basename, e.g. "citybits_texture.png" — models reference it relative to their own URL. */
     file: string;
     bytes: Uint8Array;
 }
+/** @internal */
 export declare function findArchiveUrl(html: string, pageUrl: string): string | null;
+/** @internal */
 export declare function resolveArchiveUrl(source: AssetSource, fetchImpl?: FetchLike): Promise<string>;
+/** @internal */
 export declare function downloadArchive(url: string, fetchImpl?: FetchLike): Promise<Uint8Array>;
 /**
  * Layout for the `--mirror` / `JGENGINE_ASSETS_MIRROR` base URL override: the
  * archive for a pack is expected at `<baseUrl>/<provider>/<packId>.zip`, e.g.
  * `https://my-mirror.example.com/kenney/kenney-nature.zip`.
- */
+  * @internal
+  */
 export declare function mirrorOverrideUrl(baseUrl: string, source: AssetSource): string;
 /**
  * Default asset mirror: this repo's own GitHub Releases, reachable from every
@@ -29,7 +45,9 @@ export declare function mirrorOverrideUrl(baseUrl: string, source: AssetSource):
  * `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`.
  */
 export declare const DEFAULT_RELEASE_BASE = "https://github.com/Noisemaker111/jgengine/releases/download/packs";
-/** URL of `source`'s archive on the default GitHub-release mirror. */
+/** URL of `source`'s archive on the default GitHub-release mirror.
+ * @internal
+ */
 export declare function defaultReleaseUrl(source: AssetSource): string;
 export interface DownloadPackOptions {
     /** Explicit mirror base override (CLI `--mirror` / `JGENGINE_ASSETS_MIRROR`), tried before the primary provider path. */
@@ -52,8 +70,49 @@ export interface DownloadPackResult {
  * source supplied the bytes; a mismatch is treated as a failed attempt so the
  * next source in the chain is tried. Throws with every attempted URL and its
  * failure reason when all sources fail.
- */
+  * @internal
+  */
 export declare function downloadPackArchive(source: AssetSource, options?: DownloadPackOptions): Promise<DownloadPackResult>;
-export declare function extractGlbs(archive: Uint8Array): ExtractedGlb[];
-export declare function extractTextures(archive: Uint8Array): ExtractedTexture[];
+/**
+ * External image basenames a packed `.glb` still references (its textures must
+ * sit beside it in the pack dir). Empty for self-contained models.
+ * @internal
+ */
+export declare function externalGlbImages(bytes: Uint8Array): string[];
+/**
+ * Pack a `.gltf` + optional external `.bin` into a single `.glb` so reindex /
+ * the shell only ever deal in one-file models. Strips buffer `uri` fields so
+ * the binary chunk is self-contained; external image URIs are flattened to
+ * basenames so the pack ships each referenced texture beside the models
+ * (loaders resolve the relative URI against the model's own URL).
+ * @internal
+ */
+export declare function packGltfToGlb(gltfBytes: Uint8Array, binBytes?: Uint8Array): Uint8Array;
+/** What `extractGlbs` pulls out of a pack archive: the models plus the textures they reference. */
+export interface ExtractedPack {
+    models: ExtractedGlb[];
+    /** Every archive image some extracted model references, flattened to basenames. */
+    images: ExtractedPackImage[];
+}
+/**
+ * Pull every GLB out of an archive, plus the textures those models reference.
+ * Converts co-located `.gltf` + `.bin` pairs (Quaternius Standard packs on
+ * OpenGameArt, KayKit bits packs) into `.glb` so the catalog stays
+ * one-file-per-model; GLB wins when both formats share a basename. External
+ * image URIs are flattened to basenames and the matching archive images are
+ * returned for writing beside the models — a pulled pack renders textured, not
+ * as white clay (#1005).
+  * @internal
+  */
+export declare function extractGlbs(archive: Uint8Array): ExtractedPack;
+/** One SVG/PNG file pulled out of a sprite/icon-pack archive by `extractSpriteFiles`. */
+export interface ExtractedSpriteFile {
+    file: string;
+    bytes: Uint8Array;
+}
+/** Pulls every SVG/PNG out of a sprite/icon-pack archive, deduped by basename regardless of nesting depth.
+ * @internal
+ */
+export declare function extractSpriteFiles(archive: Uint8Array): ExtractedSpriteFile[];
+/** @internal */
 export declare function sha256Hex(bytes: Uint8Array): Promise<string>;