@jgengine/assets 0.18.1 → 0.21.0

package/README.md

@@ -36,7 +36,7 @@ assets add sword                                    # icon G�� the game-icon
 ```
 
 - A **model / pack** match is fully automated: if the pack isn't already in `<dir>/models/`, it's pulled and extracted, then `reindex` runs so the id is addressable, then the `buildCatalog` + model-seam snippet is printed.
-- A **material** match pulls the maps into `<dir>/materials/<id>/` with normalized names (`color.jpg`, `normal.jpg`, `roughness.jpg`, `ao.jpg`, `displacement.jpg`) and prints the `buildMaterialCatalog` resolve snippet G�� no reindex needed, the material catalog is fully static.
+- A **material** match pulls the maps into `<dir>/materials/<id>/` with normalized names (`color.jpg`, `normal.jpg`, `displacement.jpg`, plus `roughness.jpg`/`ao.jpg` when present) and prints the `buildMaterialCatalog` resolve snippet G�� no reindex needed, the material catalog is fully static.
 - A **sprite / spritePack** match works like model/pack: if the pack isn't already in `<dir>/sprites/`, it's pulled and extracted, then `reindex-sprites` runs so individual SVG/PNG ids are addressable, then the `buildSpriteCatalog` snippet is printed.
 - A **component / icon** match prints the one-liner to run and the import + usage G�� no bytes to pull.
 - Ambiguous query? `add` lists the top matches across kinds; narrow with `--kind model|pack|material|component|icon|sprite|spritePack` or a more specific term. `--json` emits the ranked matches for scripting.
@@ -57,10 +57,27 @@ assets register <path|url> --category <c> --license <l> [--author <a>]
                                                # register a one-off single into the shipped index
 assets reindex [public/models]                # regenerate generated/*.json (dims + animation clip names) from pulled model packs
 assets reindex-sprites [public/sprites]       # regenerate generated-sprites/*.json from pulled sprite packs
+assets budget <file|directory> [--max-bytes <n>] [--max-triangles <n>] [--max-texture-dimension <n>] [--json]
+                                               # offline per-model inventory and CI budget check for any local GLBs
 assets verify                                 # license + alias-integrity gate
 assets provenance <id> [<id>...]              # resolve each id's owner (committed/provisioned/dangling); non-zero on any dangling
 ```
 
+### Offline model budgets
+
+Check the actual GLBs in your game's served directory, including your own imported art:
+
+```bash
+assets budget public/models --max-bytes 2097152 --max-triangles 50000 --max-texture-dimension 2048 --json
+assets budget public/imported/hero.glb --json
+```
+
+Limits are per model, inclusive, and chosen by the game. Omitting limits produces an inventory. The deterministic report includes each relative filename, measurements, and actionable errors; any violation, unreadable model, missing resource, or empty scan exits non-zero. The command never fetches, writes models, or changes catalog/provisioning data.
+
+`glbBytes` is the file size; `byteLength` adds unique external buffer/image URIs, counting shared files once **per model**. Triangle counts cover every stored mesh primitive once (indexed/non-indexed triangles, strips, and fans), regardless of scene instances; they are not a rendered scene or GPU-memory budget. Texture dimensions are read from PNG, JPEG, WebP, and KTX2 headers without decoding pixels. Local references must stay within the scanned directory; symlink directories fail rather than hiding models. Remote resources and geometry requiring Draco/meshopt decoding fail inspection. An already compressed asset needs a decoder before this tool can verify its geometry.
+
+Programmatic inspection is available through `readGlbMetrics` from `@jgengine/assets/glbMetrics`, with an injected resource reader, or `createAssetBudgetReport` / `checkAssetBudget` from the Node subpath `@jgengine/assets/assetBudget`. Reindex stores successful measurements in optional `IndexEntry.metrics`, preserving existing ids, bounds, clips, and ownership. Existing entries without metrics still work; budget checks always inspect the current served bytes.
+
 ### Reference integrity
 
 Every logical asset id resolves to a declared **owner** through the provisioning contract (`resolveProvenance`): `committed` (a single's shipped URL — resolves on a clean clone with no pull), `provisioned` (a pack index entry whose GLB `assets pull <source>` fetches into the served dir), or `dangling` (nothing owns it, so it can never resolve). `validateAssetReferences(refs)` turns a set of `{ consumer, id }` references into a clean-clone gate: it fails on any dangling reference — naming the consumer, the logical id, and the null resolved path — and returns the exact `assets pull <source>` steps the checkout still needs so provisioning stays deterministic and `ensure-ready`-driven. It resolves references structurally against the catalog rather than grepping source text.
@@ -74,7 +91,7 @@ Run in-repo with `bun run --cwd packages/assets src/cli/pull.ts <verb> GǪ`. (`a
 `pull` never has just one path to the bytes. For a given `source-id` it tries, in order, until one succeeds:
 
 1. **Mirror base override** G�� `--mirror <baseUrl>` (or the `JGENGINE_ASSETS_MIRROR` env var if `--mirror` is not passed) G�� the archive is expected at `<baseUrl>/<provider>/<source-id>.zip`, e.g. `https://my-mirror.example.com/quaternius/quaternius-stylized-nature.zip`.
-2. **The default GitHub-release mirror** G�� `https://github.com/Noisemaker111/jgengine/releases/download/packs/<provider>-<source-id>.zip`, on this repo's own rolling `packs` release (no separate assets repo). github.com is reachable from every cloud sandbox with no network-policy change, so zero-setup sessions still pull. `.github/workflows/mirror-assets.yml` (weekly cron + manual dispatch) keeps the release in sync with `src/sources/*.ts` automatically G�� adding a catalog entry is the whole publishing step, no manual upload. Skip this hop with `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`. Model/sprite pack failures fail the job; individual ambientCG material 404s are soft (logged, non-fatal).
+2. **The default GitHub-release mirror** G�� `https://github.com/Noisemaker111/jgengine/releases/download/packs/<provider>-<source-id>.zip`, on this repo's own rolling `packs` release (no separate assets repo). github.com is reachable from every cloud sandbox with no network-policy change, so zero-setup sessions still pull. `.github/workflows/mirror-assets.yml` (weekly cron + manual dispatch) keeps the release in sync with `src/sources/*.ts` automatically G�� adding a catalog entry is the whole publishing step, no manual upload. Skip this hop with `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`. Model/sprite pack failures fail the job; individual ambientCG material 404s and packs that record why in `unpulled` are soft (logged, non-fatal).
 3. **The primary provider path** G�� pinned `{ url, sha256? }` when stable: **KayKit** G�� `github.com/KayKit-Game-Assets/*/archive/GǪ/main.zip`; **Quaternius** free Standard packs G�� OpenGameArt direct zips (site pages JS-gate). Else scrape. `extractGlbs` packs co-located `.gltf`+`.bin` into `.glb`, flattens external image URIs to basenames, and returns each referenced texture so `pull` writes it beside the models — a pulled pack renders textured out of the box.
 4. **The pack's own `mirror`** G�� an optional direct archive URL set on the `AssetSource` entry itself (`src/sources/*.ts`), tried as a last resort.
 
@@ -102,7 +119,7 @@ bun src/cli/pull.ts reindex ../../apps/dev/public/models
 bun src/cli/pull.ts verify                                                      # license + alias gate
 ```
 
-A **new provider** is just a new `src/sources/<provider>.ts` added to the `sources` array in `src/sources/index.ts`. Pinned providers use `download: { url, sha256? }`; providers whose pages JS-gate the download and can't be pinned use `download: { scrape: <page> }`. Any entry can also carry an optional top-level `mirror: <archiveUrl>` G�� a direct URL `pull` falls back to if both a `--mirror`/`JGENGINE_ASSETS_MIRROR` override and the primary path fail (see "Mirror fallback and offline pulls" above). Kenney.nl is not an eligible provider for this repo G�� see CLAUDE.md "Never Kenney".
+A **new provider** is just a new `src/sources/<provider>.ts` added to the `sources` array in `src/sources/index.ts`. Pinned providers use `download: { url, sha256? }`; providers whose pages JS-gate the download and can't be pinned use `download: { scrape: <page> }`. Any entry can also carry an optional top-level `mirror: <archiveUrl>` G�� a direct URL `pull` falls back to if both a `--mirror`/`JGENGINE_ASSETS_MIRROR` override and the primary path fail (see "Mirror fallback and offline pulls" above). Kenney.nl is not an eligible provider for this repo G�� see AGENTS.md "Never use Kenney assets".
 
 **A whole new sprite/icon pack** G�� same shape as a model pack, just `kind: "sprite"` and `reindex-sprites` instead of `reindex`; files are matched by `.svg`/`.png` extension, deduped by basename regardless of archive nesting, so no filenames are hand-typed here either. `src/sources/gameicons.ts` is the current example (`gameicons-icons`); a new sprite provider follows the same shape in its own `src/sources/<provider>.ts`.
 
@@ -154,6 +171,8 @@ materials.resolve("ambientcg-grass001")!.maps.color; // "/materials/ambientcg-gr
 materials.resolve("material/grass")!.maps.normal;    // alias G�� "/materials/ambientcg-grass001/normal.jpg"
 ```
 
+`maps.ao` and `maps.roughness` are optional: the catalog advertises them only when the pinned source variant provides them. `ambientcg-metalplates001` has no AO; `ambientcg-gravel001` and `ambientcg-concrete001` have neither AO nor roughness. Pass `maps` directly to model, building, or terrain material seams; omitted maps skip loading, and terrain keeps its authored scalar roughness. Callers can still supply their own map URLs. Native ambientCG 1K-JPG pulls do not include KTX2, so the catalog omits `maps.ktx2` too. Pull fails if an archive omits a map its source declares.
+
 Sprite/icon packs resolve the same way once pulled + reindexed G�� individual files, not whole packs:
 
 ```ts

package/dist/assetBudget.d.ts

@@ -0,0 +1,36 @@
+import { type GlbMetrics } from "./glbMetrics.js";
+/** Per-model limits chosen by the game; equality passes and omitted limits only report. */
+export interface AssetBudget {
+    maxBytes?: number;
+    maxTriangles?: number;
+    maxTextureDimension?: number;
+}
+/** One model's measured inventory or actionable inspection/budget errors. */
+export interface AssetBudgetEntry {
+    file: string;
+    metrics?: GlbMetrics;
+    errors: readonly string[];
+}
+/** Deterministic offline report; an empty directory or any unreadable model fails. */
+export interface AssetBudgetReport {
+    ok: boolean;
+    budget: AssetBudget;
+    entries: readonly AssetBudgetEntry[];
+    errors: readonly string[];
+}
+/**
+ * Read a GLB plus local resources under `resourceRoot`; remote URLs and symlink escapes fail without fetching.
+ * @capability asset-budgets inspect a GLB and its local external resources without network access
+ */
+export declare function readGlbFileMetrics(file: string, resourceRoot?: string): GlbMetrics;
+/**
+ * Check measured per-model bytes, stored triangles, and maximum image dimension against caller-owned limits.
+ * @capability asset-budgets enforce game-owned per-model byte, triangle, and texture-dimension limits
+ */
+export declare function checkAssetBudget(metrics: GlbMetrics, budget: AssetBudget): string[];
+/**
+ * Scan a file or directory recursively for GLBs without changing their bytes or the catalog.
+ * Paths are relative to the scanned directory, sorted lexically; unknown/custom asset folders work equally.
+ * @capability asset-budgets fail CI on local or imported GLB byte, triangle, and texture-size regressions
+ */
+export declare function createAssetBudgetReport(target: string, budget?: AssetBudget): AssetBudgetReport;

package/dist/assetBudget.js

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

package/dist/catalogs/build.d.ts

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

package/dist/catalogs/build.js

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

package/dist/cli/pull.js

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

package/dist/glbMetrics.d.ts

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

package/dist/glbMetrics.js

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