@jgengine/assets 0.10.0 → 0.11.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, extractTextures } 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,15 +149,53 @@ 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))` : ""}`);
+    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 glbs = extractGlbs(archive);
     if (glbs.length === 0)
         fail(`no .glb files found in ${source.id} archive`);
@@ -157,17 +255,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 +296,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 +363,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 +406,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 +425,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 +475,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/download.d.ts

@@ -1,5 +1,16 @@
+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;
@@ -9,14 +20,18 @@ export interface ExtractedTexture {
     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 +44,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 +69,34 @@ 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>;
+/**
+ * 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 stay as-is (loaders
+ * resolve relative to the catalog URL only for GLB-embedded images).
+ * @internal
+ */
+export declare function packGltfToGlb(gltfBytes: Uint8Array, binBytes?: Uint8Array): Uint8Array;
+/**
+ * Pull every GLB out of an archive. Also converts co-located `.gltf` + `.bin`
+ * pairs (Quaternius Standard packs on OpenGameArt) into `.glb` so the catalog
+ * stays one-file-per-model. GLB wins when both formats share a basename.
+  * @internal
+  */
 export declare function extractGlbs(archive: Uint8Array): ExtractedGlb[];
+/** 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 extractTextures(archive: Uint8Array): ExtractedTexture[];
+/** @internal */
 export declare function sha256Hex(bytes: Uint8Array): Promise<string>;

package/dist/download.js

@@ -1,5 +1,34 @@
 import { unzipSync } from "fflate";
 import { isScrapeDownload } from "./manifest.js";
+/** 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 const MAX_ARCHIVE_DOWNLOAD_BYTES = 256 * 1024 * 1024;
+/** Max total uncompressed size this module will inflate out of one archive, in bytes. */
+export const MAX_ARCHIVE_UNCOMPRESSED_BYTES = 512 * 1024 * 1024;
+/** Max number of entries this module will extract out of one archive. */
+export const MAX_ARCHIVE_ENTRY_COUNT = 20_000;
+/** Max allowed originalSize/size ratio for a single archive entry — past this it's treated as a zip bomb. */
+export const MAX_ARCHIVE_COMPRESSION_RATIO = 100;
+/** @internal */
+export function boundedExtractFilter(matches) {
+    let totalUncompressedBytes = 0;
+    let entryCount = 0;
+    return (file) => {
+        if (!matches(file))
+            return false;
+        if (file.size > 0 && file.originalSize / file.size > MAX_ARCHIVE_COMPRESSION_RATIO) {
+            throw new Error(`archive entry "${file.name}" has a ${(file.originalSize / file.size).toFixed(0)}x compression ratio, exceeds the ${MAX_ARCHIVE_COMPRESSION_RATIO}x zip-bomb guard`);
+        }
+        totalUncompressedBytes += file.originalSize;
+        if (totalUncompressedBytes > MAX_ARCHIVE_UNCOMPRESSED_BYTES) {
+            throw new Error(`archive would extract more than the ${MAX_ARCHIVE_UNCOMPRESSED_BYTES} byte uncompressed-size cap`);
+        }
+        entryCount += 1;
+        if (entryCount > MAX_ARCHIVE_ENTRY_COUNT) {
+            throw new Error(`archive has more than the ${MAX_ARCHIVE_ENTRY_COUNT} entry cap`);
+        }
+        return true;
+    };
+}
 function resolveRelative(path, pageUrl) {
     try {
         return new URL(path, pageUrl).toString();
@@ -8,6 +37,7 @@ function resolveRelative(path, pageUrl) {
         return path;
     }
 }
+/** @internal */
 export function findArchiveUrl(html, pageUrl) {
     const matches = html.match(/[^\s"'()<>]+\.zip/gi);
     if (matches === null)
@@ -26,6 +56,7 @@ function score(candidate) {
         value += 1;
     return value;
 }
+/** @internal */
 export async function resolveArchiveUrl(source, fetchImpl = fetch) {
     const download = source.download;
     if (!isScrapeDownload(download))
@@ -40,17 +71,30 @@ export async function resolveArchiveUrl(source, fetchImpl = fetch) {
     }
     return url;
 }
+/** @internal */
 export async function downloadArchive(url, fetchImpl = fetch) {
     const response = await fetchImpl(url, { redirect: "follow" });
     if (!response.ok)
         throw new Error(`download ${url} -> HTTP ${response.status}`);
-    return new Uint8Array(await response.arrayBuffer());
+    const declaredLength = response.headers.get("content-length");
+    if (declaredLength !== null) {
+        const declared = Number(declaredLength);
+        if (Number.isFinite(declared) && declared > MAX_ARCHIVE_DOWNLOAD_BYTES) {
+            throw new Error(`download ${url} declares ${declared} bytes, exceeds the ${MAX_ARCHIVE_DOWNLOAD_BYTES} byte cap`);
+        }
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.byteLength > MAX_ARCHIVE_DOWNLOAD_BYTES) {
+        throw new Error(`download ${url} is ${bytes.byteLength} bytes, exceeds the ${MAX_ARCHIVE_DOWNLOAD_BYTES} byte cap`);
+    }
+    return bytes;
 }
 /**
  * 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 function mirrorOverrideUrl(baseUrl, source) {
     const base = baseUrl.replace(/\/+$/, "");
     return `${base}/${source.provider}/${source.id}.zip`;
@@ -66,7 +110,9 @@ export function mirrorOverrideUrl(baseUrl, source) {
  * `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`.
  */
 export 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 function defaultReleaseUrl(source) {
     return `${DEFAULT_RELEASE_BASE}/${source.provider}-${source.id}.zip`;
 }
@@ -89,7 +135,8 @@ async function verifyPinnedSha(source, archive) {
  * 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 async function downloadPackArchive(source, options = {}) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const attempted = [];
@@ -135,10 +182,8 @@ export async function downloadPackArchive(source, options = {}) {
     throw new Error(`failed to download ${source.id} from all ${attempted.length} source(s):\n` +
         errors.map((line) => `  - ${line}`).join("\n"));
 }
-export function extractGlbs(archive) {
-    const entries = unzipSync(archive, {
-        filter: (file) => /\.glb$/i.test(file.name),
-    });
+function dedupeByBasename(archive, pattern) {
+    const entries = unzipSync(archive, { filter: boundedExtractFilter((file) => pattern.test(file.name)) });
     const byName = new Map();
     for (const [path, bytes] of Object.entries(entries)) {
         const base = path.split("/").pop();
@@ -149,10 +194,113 @@ export function extractGlbs(archive) {
     }
     return Array.from(byName, ([file, bytes]) => ({ file, bytes })).sort((a, b) => a.file.localeCompare(b.file));
 }
+/**
+ * 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 stay as-is (loaders
+ * resolve relative to the catalog URL only for GLB-embedded images).
+ * @internal
+ */
+export function packGltfToGlb(gltfBytes, binBytes) {
+    const json = JSON.parse(new TextDecoder().decode(gltfBytes));
+    if (Array.isArray(json.buffers)) {
+        for (const buffer of json.buffers) {
+            delete buffer.uri;
+            if (binBytes !== undefined)
+                buffer.byteLength = binBytes.byteLength;
+        }
+    }
+    const jsonText = JSON.stringify(json);
+    const jsonPad = (4 - (jsonText.length % 4)) % 4;
+    const jsonChunk = new Uint8Array(jsonText.length + jsonPad);
+    new TextEncoder().encodeInto(jsonText, jsonChunk);
+    for (let i = jsonText.length; i < jsonChunk.length; i++)
+        jsonChunk[i] = 0x20;
+    const binPad = binBytes === undefined ? 0 : (4 - (binBytes.byteLength % 4)) % 4;
+    const binChunkLen = binBytes === undefined ? 0 : binBytes.byteLength + binPad;
+    const total = 12 +
+        8 +
+        jsonChunk.byteLength +
+        (binBytes === undefined ? 0 : 8 + binChunkLen);
+    const out = new Uint8Array(total);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, 0x46546c67, true); // glTF
+    view.setUint32(4, 2, true);
+    view.setUint32(8, total, true);
+    let o = 12;
+    view.setUint32(o, jsonChunk.byteLength, true);
+    view.setUint32(o + 4, 0x4e4f534a, true); // JSON
+    out.set(jsonChunk, o + 8);
+    o += 8 + jsonChunk.byteLength;
+    if (binBytes !== undefined) {
+        view.setUint32(o, binChunkLen, true);
+        view.setUint32(o + 4, 0x004e4942, true); // BIN
+        out.set(binBytes, o + 8);
+    }
+    return out;
+}
+/**
+ * Pull every GLB out of an archive. Also converts co-located `.gltf` + `.bin`
+ * pairs (Quaternius Standard packs on OpenGameArt) into `.glb` so the catalog
+ * stays one-file-per-model. GLB wins when both formats share a basename.
+  * @internal
+  */
+export function extractGlbs(archive) {
+    const entries = unzipSync(archive, {
+        filter: boundedExtractFilter((file) => /\.(glb|gltf|bin)$/i.test(file.name)),
+    });
+    const byDirBase = new Map();
+    for (const [path, bytes] of Object.entries(entries)) {
+        const parts = path.replace(/\\/g, "/").split("/");
+        const file = parts.pop();
+        if (file === undefined || file.length === 0)
+            continue;
+        const dir = parts.join("/");
+        // KayKit ships some files as `name.gltf.glb` — strip both suffixes for a clean id.
+        const base = file.replace(/\.gltf\.glb$/i, "").replace(/\.(glb|gltf|bin)$/i, "");
+        if (base.length === 0 || base === file)
+            continue;
+        const extMatch = file.match(/\.(glb|gltf|bin)$/i);
+        if (extMatch === null)
+            continue;
+        const ext = extMatch[1].toLowerCase();
+        const key = `${dir}\0${base}`;
+        const slot = byDirBase.get(key) ?? {};
+        if (ext === "glb")
+            slot.glb = bytes;
+        else if (ext === "gltf")
+            slot.gltf = bytes;
+        else if (ext === "bin")
+            slot.bin = bytes;
+        byDirBase.set(key, slot);
+    }
+    const byName = new Map();
+    for (const [key, slot] of byDirBase) {
+        const base = key.split("\0")[1];
+        const file = `${base}.glb`;
+        if (slot.glb !== undefined) {
+            if (!byName.has(file))
+                byName.set(file, slot.glb);
+            continue;
+        }
+        if (slot.gltf !== undefined) {
+            if (!byName.has(file))
+                byName.set(file, packGltfToGlb(slot.gltf, slot.bin));
+        }
+    }
+    return Array.from(byName, ([file, bytes]) => ({ file, bytes })).sort((a, b) => a.file.localeCompare(b.file));
+}
+/** Pulls every SVG/PNG out of a sprite/icon-pack archive, deduped by basename regardless of nesting depth.
+ * @internal
+ */
+export function extractSpriteFiles(archive) {
+    return dedupeByBasename(archive, /\.(svg|png)$/i);
+}
 const TEXTURE_ENTRY = /(?:^|\/)(Textures\/[^/]+)$/i;
+/** @internal */
 export function extractTextures(archive) {
     const entries = unzipSync(archive, {
-        filter: (file) => TEXTURE_ENTRY.test(file.name),
+        filter: boundedExtractFilter((file) => TEXTURE_ENTRY.test(file.name)),
     });
     const byRel = new Map();
     for (const [path, bytes] of Object.entries(entries)) {
@@ -165,6 +313,7 @@ export function extractTextures(archive) {
     }
     return Array.from(byRel, ([file, bytes]) => ({ file, bytes })).sort((a, b) => a.file.localeCompare(b.file));
 }
+/** @internal */
 export async function sha256Hex(bytes) {
     const buffer = new ArrayBuffer(bytes.byteLength);
     new Uint8Array(buffer).set(bytes);