@driftengine/assets 3.61.0

package/dist/weld.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Collapse a triangle soup into shared vertices.
+ *
+ * Importers produce one vertex per triangle *corner*, because that is how the source
+ * formats index their attributes: FBX and OBJ address positions, normals and UVs through
+ * separate index lists, and the only way to flatten that into one array per attribute is
+ * to give every corner its own vertex. A real model comes out five to eight times larger
+ * than it is — a BMW measured 4.57M corners for perhaps 600k distinct vertices.
+ *
+ * **Corners are only merged when everything about them matches**, not just the position.
+ * Two corners at the same point with different normals are a hard edge, and welding them
+ * would round it off — the seam down a car's bonnet would soften into a dent. That is a
+ * change to the model, made silently, which is exactly what a reader must not do.
+ *
+ * Offline work, so it may allocate. Nothing here runs per frame.
+ */
+import type { MeshData } from '@driftengine/drft';
+/**
+ * Weld one mesh. Returns the same mesh when nothing can be merged.
+ *
+ * **Every attribute decides identity, and that is a cost as well as a correctness rule.** Two
+ * corners alike in position, normal and UV but weighted to different bones are two vertices, and
+ * merging them moves geometry with the wrong limb; two alike in everything including their UV but
+ * opposite in the bitangent's sign are a mirrored UV shell, and merging them lights one side of
+ * the model inside out. Neither is visible in any count a bake prints.
+ *
+ * What it costs is a file whose tangent frame was *derived* per corner instead of authored: a
+ * corner soup gets one triangle's frame per corner, so no two corners agree and the weld that
+ * would have merged them cannot. **The way out is not a looser key — it is to derive the frame
+ * from the welded mesh**, which is what the baker does as of 3.30.0: it passes
+ * `deriveTangents: false` to the reader and calls `deriveTangentsFor` here, afterwards.
+ *
+ * **How much it costs depends on the unwrap, and two figures in this repository disagreed about
+ * it.** The frame is normalised, so two triangles produce different frames only where the
+ * *direction* u increases in differs between them. On a separable unwrap — u from x, v from y —
+ * every triangle on a flat surface agrees and a derived frame costs almost nothing; a 253-mesh CAD
+ * export measured 728,168 vertices against 728,161 with no frame, seven vertices, and that file is
+ * not on this machine. On a rotational unwrap the direction turns with position and almost nothing
+ * merges: 9,600 corners to 9,482 vertices against 1,681, six different frames at one point at
+ * worst, measured in `tangentOrder.test.ts` and reproducible. The order is fixed for the second
+ * case; the first is why it went unnoticed.
+ */
+export declare function weldMesh(mesh: MeshData): MeshData;
+export declare function dropDefaultAttributes(mesh: MeshData): MeshData;

package/dist/weld.js

@@ -0,0 +1,237 @@
+/**
+ * Collapse a triangle soup into shared vertices.
+ *
+ * Importers produce one vertex per triangle *corner*, because that is how the source
+ * formats index their attributes: FBX and OBJ address positions, normals and UVs through
+ * separate index lists, and the only way to flatten that into one array per attribute is
+ * to give every corner its own vertex. A real model comes out five to eight times larger
+ * than it is — a BMW measured 4.57M corners for perhaps 600k distinct vertices.
+ *
+ * **Corners are only merged when everything about them matches**, not just the position.
+ * Two corners at the same point with different normals are a hard edge, and welding them
+ * would round it off — the seam down a car's bonnet would soften into a dent. That is a
+ * change to the model, made silently, which is exactly what a reader must not do.
+ *
+ * Offline work, so it may allocate. Nothing here runs per frame.
+ */
+/**
+ * How finely positions are compared, in units of the model.
+ *
+ * Exact bit equality is the wrong test: two corners meant to be the same point routinely
+ * differ in the last place after a transform, so exact matching welds almost nothing on
+ * exactly the files that need it most. Quantising to a millionth is far below anything a
+ * model expresses and far above float noise.
+ */
+const QUANTUM = 1e-6;
+function quantise(value) {
+    return Math.round(value / QUANTUM);
+}
+/**
+ * Every optional attribute, and how many floats each spends on a vertex.
+ *
+ * **One table, read by both halves of the weld** — the key that decides whether two corners are
+ * the same vertex, and the copy that writes the survivors. They were two lists written out by
+ * hand, and what that cost is the reason this exists: `MeshData` gained a tangent frame, relief,
+ * a rig and morph deltas over four days in August and neither list was told about any of them,
+ * so for five releases a merged mesh came back **without** its rig, its tangents and its morph
+ * targets, and with corners merged across the bones they were weighted to. Nothing raised: an
+ * unskinned mesh is a valid mesh, and it draws at its bind pose.
+ *
+ * **The `satisfies` is the load-bearing part and not decoration.** It names every optional
+ * per-vertex attribute the format has, so the day a new one is added to `MeshData` this file
+ * stops compiling until it is listed here. A table that can be forgotten is exactly the thing
+ * that was already forgotten twice.
+ */
+const ATTRIBUTES = {
+    uvs: 2,
+    specular: 1,
+    roughness: 1,
+    grain: 1,
+    relief: 1,
+    emissiveColor: 3,
+    tangents: 4,
+    joints: 4,
+    weights: 4,
+    /*
+     * The four-lane per-vertex channel. It joins the key above as well as the copy below, which is
+     * the behaviour that matters: two vertices at one position whose sway or sky exposure differ
+     * are not the same vertex, and welding them would silently keep whichever came first. A leaf
+     * tip merged into the trunk it grows from would stop moving.
+     */
+    channel: 4,
+};
+const NAMES = Object.keys(ATTRIBUTES);
+/**
+ * Weld one mesh. Returns the same mesh when nothing can be merged.
+ *
+ * **Every attribute decides identity, and that is a cost as well as a correctness rule.** Two
+ * corners alike in position, normal and UV but weighted to different bones are two vertices, and
+ * merging them moves geometry with the wrong limb; two alike in everything including their UV but
+ * opposite in the bitangent's sign are a mirrored UV shell, and merging them lights one side of
+ * the model inside out. Neither is visible in any count a bake prints.
+ *
+ * What it costs is a file whose tangent frame was *derived* per corner instead of authored: a
+ * corner soup gets one triangle's frame per corner, so no two corners agree and the weld that
+ * would have merged them cannot. **The way out is not a looser key — it is to derive the frame
+ * from the welded mesh**, which is what the baker does as of 3.30.0: it passes
+ * `deriveTangents: false` to the reader and calls `deriveTangentsFor` here, afterwards.
+ *
+ * **How much it costs depends on the unwrap, and two figures in this repository disagreed about
+ * it.** The frame is normalised, so two triangles produce different frames only where the
+ * *direction* u increases in differs between them. On a separable unwrap — u from x, v from y —
+ * every triangle on a flat surface agrees and a derived frame costs almost nothing; a 253-mesh CAD
+ * export measured 728,168 vertices against 728,161 with no frame, seven vertices, and that file is
+ * not on this machine. On a rotational unwrap the direction turns with position and almost nothing
+ * merges: 9,600 corners to 9,482 vertices against 1,681, six different frames at one point at
+ * worst, measured in `tangentOrder.test.ts` and reproducible. The order is fixed for the second
+ * case; the first is why it went unnoticed.
+ */
+export function weldMesh(mesh) {
+    const vertices = mesh.positions.length / 3;
+    if (vertices === 0)
+        return mesh;
+    const map = new Map();
+    const remap = new Uint32Array(vertices);
+    let unique = 0;
+    /* The attributes this mesh actually carries, resolved once and not per vertex. */
+    const present = NAMES.filter((name) => mesh[name] !== undefined);
+    /* Three floats per target per vertex, interleaved by vertex: `MeshData.morphTargets`' layout. */
+    const morphStride = mesh.morphTargets === undefined ? 0 : (mesh.morphTargetCount ?? 0) * 3;
+    for (let i = 0; i < vertices; i++) {
+        /*
+         * The key names every attribute, because two corners differing in any of them are
+         * genuinely different vertices — a shared position with a different normal is a hard
+         * edge, and with a different colour is a material boundary.
+         */
+        let key = `${quantise(mesh.positions[i * 3])},` +
+            `${quantise(mesh.positions[i * 3 + 1])},` +
+            `${quantise(mesh.positions[i * 3 + 2])}|` +
+            `${quantise(mesh.normals[i * 3])},` +
+            `${quantise(mesh.normals[i * 3 + 1])},` +
+            `${quantise(mesh.normals[i * 3 + 2])}|` +
+            `${quantise(mesh.colors[i * 3])},` +
+            `${quantise(mesh.colors[i * 3 + 1])},` +
+            `${quantise(mesh.colors[i * 3 + 2])}|` +
+            `${quantise(mesh.emissive[i])}`;
+        for (const name of present) {
+            const array = mesh[name];
+            const stride = ATTRIBUTES[name];
+            key += '|';
+            for (let c = 0; c < stride; c++)
+                key += `${quantise(array[i * stride + c])},`;
+        }
+        for (let c = 0; c < morphStride; c++) {
+            key += `${quantise(mesh.morphTargets?.[i * morphStride + c])},`;
+        }
+        const found = map.get(key);
+        if (found === undefined) {
+            map.set(key, unique);
+            remap[i] = unique;
+            unique++;
+        }
+        else {
+            remap[i] = found;
+        }
+    }
+    if (unique === vertices)
+        return mesh;
+    const positions = new Float32Array(unique * 3);
+    const normals = new Float32Array(unique * 3);
+    const colors = new Float32Array(unique * 3);
+    const emissive = new Float32Array(unique);
+    const copies = {};
+    for (const name of present)
+        copies[name] = new Float32Array(unique * ATTRIBUTES[name]);
+    const morphTargets = morphStride === 0 ? undefined : new Float32Array(unique * morphStride);
+    const written = new Uint8Array(unique);
+    for (let i = 0; i < vertices; i++) {
+        const to = remap[i];
+        if (written[to] === 1)
+            continue;
+        written[to] = 1;
+        for (let c = 0; c < 3; c++) {
+            positions[to * 3 + c] = mesh.positions[i * 3 + c];
+            normals[to * 3 + c] = mesh.normals[i * 3 + c];
+            colors[to * 3 + c] = mesh.colors[i * 3 + c];
+        }
+        emissive[to] = mesh.emissive[i];
+        for (const name of present) {
+            const from = mesh[name];
+            const into = copies[name];
+            const stride = ATTRIBUTES[name];
+            for (let c = 0; c < stride; c++)
+                into[to * stride + c] = from[i * stride + c];
+        }
+        if (morphTargets !== undefined) {
+            for (let c = 0; c < morphStride; c++) {
+                morphTargets[to * morphStride + c] = mesh.morphTargets?.[i * morphStride + c];
+            }
+        }
+    }
+    const indices = new Uint32Array(mesh.indices.length);
+    for (let i = 0; i < mesh.indices.length; i++) {
+        indices[i] = remap[mesh.indices[i]];
+    }
+    return {
+        positions,
+        normals,
+        colors,
+        emissive,
+        indices,
+        ...copies,
+        /* Both or neither: an array of deltas with no count moves nothing, and a count with no
+           array is a promise about a buffer that is not there. */
+        ...(morphTargets === undefined
+            ? {}
+            : { morphTargets, morphTargetCount: mesh.morphTargetCount }),
+    };
+}
+/**
+ * Drop optional attributes that never vary from the engine's own default.
+ *
+ * An importer that has no material information should not invent one, and a writer should
+ * not spend a megabyte storing the same number four million times. `Mesh` already reads an
+ * absent attribute as a constant, so leaving it out is not a loss — it is the same shading
+ * through a cheaper path, with no buffer, no upload and no per-vertex fetch.
+ *
+ * The defaults are `Mesh`'s, and they are duplicated here on purpose rather than imported:
+ * this is a *bake-time* judgement about what is worth storing, and tying it to a rendering
+ * constant would make a change to one silently rewrite files produced by the other.
+ */
+const DEFAULT_SPECULAR = 0;
+const DEFAULT_ROUGHNESS = 0.4277;
+const DEFAULT_EMISSIVE_COLOR = -1;
+/** Absent grain means none, so an asset that is nowhere mineral stores nothing about it. */
+const DEFAULT_GRAIN = 0;
+/**
+ * Absent relief means a perfectly smooth surface, which is what every reader produces.
+ *
+ * Listed late and for the same reason the weld's table exists: relief landed on `MeshData` on
+ * 2026-08-21 and this function was not told, so a producer filling an array of zeroes stored four
+ * bytes a vertex saying "no relief" — the one thing an absent attribute already says.
+ */
+const DEFAULT_RELIEF = 0;
+export function dropDefaultAttributes(mesh) {
+    const constant = (array, value) => {
+        if (array === undefined)
+            return false;
+        for (let i = 0; i < array.length; i++) {
+            if (Math.abs(array[i] - value) > 1e-6)
+                return false;
+        }
+        return true;
+    };
+    const out = { ...mesh };
+    if (constant(mesh.specular, DEFAULT_SPECULAR))
+        delete out.specular;
+    if (constant(mesh.roughness, DEFAULT_ROUGHNESS))
+        delete out.roughness;
+    if (constant(mesh.grain, DEFAULT_GRAIN))
+        delete out.grain;
+    if (constant(mesh.relief, DEFAULT_RELIEF))
+        delete out.relief;
+    if (constant(mesh.emissiveColor, DEFAULT_EMISSIVE_COLOR)) {
+        delete out.emissiveColor;
+    }
+    return out;
+}

package/dist/zip.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reading a zip container. One responsibility: name a file inside an archive, get its bytes.
+ *
+ * Shared by `.usdz` and `.3mf`, which is why it exists as its own module rather than inside
+ * either: both are zip archives of a documented layout, and a reader written twice is a
+ * reader that disagrees with itself once.
+ *
+ * **The central directory is read, not the local headers.** A zip can be scanned from the
+ * front by walking local file headers, and almost every naive reader does. It is wrong: a
+ * local header may declare a size of zero and defer the real figures to a data descriptor
+ * *after* the payload, which cannot be found without already knowing where the payload ends.
+ * The central directory at the back of the file is the authority, always carries the sizes,
+ * and is what the specification says to use.
+ *
+ * **Inflate is injected**, for the same reason as in `fbx.ts`: this module is part of an
+ * engine that runs in a browser and must not reach for Node's `zlib`. `.usdz` never needs it,
+ * because the format *requires* its entries to be stored uncompressed so they can be memory
+ * mapped, and that is why a USDZ can be read with no decompressor at all. `.3mf` is ordinary
+ * deflate and needs one.
+ */
+import type { Inflate } from './fbx.ts';
+/** One file in the archive. `bytes` is decompressed and ready to read. */
+export interface ZipEntry {
+    readonly name: string;
+    readonly bytes: Uint8Array;
+}
+/**
+ * Every file in an archive, decompressed.
+ *
+ * Directory entries are skipped: they are zero-length records whose names end in a slash, and
+ * a caller asking for files does not want them.
+ */
+export declare function readZip(buffer: ArrayBuffer, inflate?: Inflate | null): ZipEntry[];
+/** The first entry whose name matches, or null. Case-insensitive, since archives disagree. */
+export declare function findEntry(entries: readonly ZipEntry[], match: RegExp): ZipEntry | null;

package/dist/zip.js

@@ -0,0 +1,110 @@
+/**
+ * Reading a zip container. One responsibility: name a file inside an archive, get its bytes.
+ *
+ * Shared by `.usdz` and `.3mf`, which is why it exists as its own module rather than inside
+ * either: both are zip archives of a documented layout, and a reader written twice is a
+ * reader that disagrees with itself once.
+ *
+ * **The central directory is read, not the local headers.** A zip can be scanned from the
+ * front by walking local file headers, and almost every naive reader does. It is wrong: a
+ * local header may declare a size of zero and defer the real figures to a data descriptor
+ * *after* the payload, which cannot be found without already knowing where the payload ends.
+ * The central directory at the back of the file is the authority, always carries the sizes,
+ * and is what the specification says to use.
+ *
+ * **Inflate is injected**, for the same reason as in `fbx.ts`: this module is part of an
+ * engine that runs in a browser and must not reach for Node's `zlib`. `.usdz` never needs it,
+ * because the format *requires* its entries to be stored uncompressed so they can be memory
+ * mapped, and that is why a USDZ can be read with no decompressor at all. `.3mf` is ordinary
+ * deflate and needs one.
+ */
+import { DrftError } from '@driftengine/drft';
+/** Signature of a central directory record, little-endian: `PK
`. */
+const CENTRAL_SIGNATURE = 0x02014b50;
+/** Signature of the end-of-central-directory record: `PK`. */
+const END_SIGNATURE = 0x06054b50;
+/** The two compression methods that appear in practice. Anything else is refused by number. */
+const STORED = 0;
+const DEFLATED = 8;
+/**
+ * Find the end-of-central-directory record, which is the only fixed point in a zip.
+ *
+ * It sits at the very back, except that it carries a trailing comment of arbitrary length, so
+ * it has to be searched for backwards. The comment is at most 65535 bytes by definition, so
+ * the search is bounded rather than a scan of the whole file.
+ */
+function findEnd(view, length) {
+    const earliest = Math.max(0, length - 22 - 0xffff);
+    for (let at = length - 22; at >= earliest; at--) {
+        if (view.getUint32(at, true) === END_SIGNATURE)
+            return at;
+    }
+    throw new DrftError('zip: no end-of-central-directory record, so this is not a zip archive');
+}
+/**
+ * Every file in an archive, decompressed.
+ *
+ * Directory entries are skipped: they are zero-length records whose names end in a slash, and
+ * a caller asking for files does not want them.
+ */
+export function readZip(buffer, inflate = null) {
+    const bytes = new Uint8Array(buffer);
+    const view = new DataView(buffer);
+    if (buffer.byteLength < 22)
+        throw new DrftError('zip: shorter than an empty archive');
+    const end = findEnd(view, buffer.byteLength);
+    const count = view.getUint16(end + 10, true);
+    let at = view.getUint32(end + 16, true);
+    const out = [];
+    const decoder = new TextDecoder();
+    for (let i = 0; i < count; i++) {
+        if (at + 46 > buffer.byteLength || view.getUint32(at, true) !== CENTRAL_SIGNATURE) {
+            throw new DrftError(`zip: the central directory entry ${i} is malformed at byte ${at}`);
+        }
+        const method = view.getUint16(at + 10, true);
+        const compressedSize = view.getUint32(at + 20, true);
+        const uncompressedSize = view.getUint32(at + 24, true);
+        const nameLength = view.getUint16(at + 28, true);
+        const extraLength = view.getUint16(at + 30, true);
+        const commentLength = view.getUint16(at + 32, true);
+        const localAt = view.getUint32(at + 42, true);
+        const name = decoder.decode(bytes.subarray(at + 46, at + 46 + nameLength));
+        at += 46 + nameLength + extraLength + commentLength;
+        /* A directory, which carries no payload and is not a file anybody asked for. */
+        if (name.endsWith('/'))
+            continue;
+        /*
+         * The local header's *own* name and extra lengths, which differ from the central
+         * directory's. Reusing the central figures here is the classic zip bug: the extra field
+         * is routinely a different length in the two places, so the payload starts somewhere
+         * else and the entry decompresses to noise.
+         */
+        if (localAt + 30 > buffer.byteLength || view.getUint32(localAt, true) !== 0x04034b50) {
+            throw new DrftError(`zip: "${name}" points at byte ${localAt}, which is not a local header`);
+        }
+        const localNameLength = view.getUint16(localAt + 26, true);
+        const localExtraLength = view.getUint16(localAt + 28, true);
+        const from = localAt + 30 + localNameLength + localExtraLength;
+        if (from + compressedSize > buffer.byteLength) {
+            throw new DrftError(`zip: "${name}" claims ${compressedSize} bytes and runs past the archive`);
+        }
+        const payload = bytes.subarray(from, from + compressedSize);
+        if (method === STORED) {
+            out.push({ name, bytes: payload });
+            continue;
+        }
+        if (method === DEFLATED) {
+            if (inflate === null) {
+                throw new DrftError(`zip: "${name}" is deflate-compressed and this reader was given no decompressor`);
+            }
+            out.push({ name, bytes: inflate(payload, uncompressedSize) });
+            continue;
+        }
+        throw new DrftError(`zip: "${name}" uses compression method ${method}, and only stored and deflate are read`);
+    }
+    return out;
+}
+/** The first entry whose name matches, or null. Case-insensitive, since archives disagree. */
+export function findEntry(entries, match) {
+    return entries.find((entry) => match.test(entry.name)) ?? null;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@driftengine/assets",
+  "version": "3.61.0",
+  "description": "Model readers and the streaming loader for the .drft container",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@driftengine/drft": "3.61.0"
+  },
+  "peerDependencies": {
+    "@driftengine/core": "3.61.0"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/assets"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "gltf",
+    "fbx",
+    "obj",
+    "model-loader",
+    "streaming"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/assetPath.ts

@@ -0,0 +1,79 @@
+/**
+ * Turning a path a model file wrote into paths worth trying. One responsibility: candidates.
+ *
+ * **No filesystem, no network, no opinion about either.** This is string work only, and it
+ * exists because every format has the same problem and none of them solve it: a model names
+ * its textures with a path that was true on the machine that exported it, and is true almost
+ * nowhere else. Deciding *how* to look is the host's job, because only the host knows
+ * whether it is reading a folder, a zip, a URL or a bundle somebody dragged in. Deciding
+ * *what to look for* is the same everywhere, so it is written once, here.
+ *
+ * What goes wrong without it, from the asset this was built against:
+ *
+ * - `textures\carbon.jpg` uses backslashes, which are a path separator on one platform and
+ *   an ordinary filename character on the others.
+ * - the absolute path beside it is `G:\SketchfabRipper_v1.18.0-b2\tools\blender-292\...`,
+ *   a drive on somebody else's computer. Trying it cannot succeed and, on a host that maps
+ *   unknown roots, is the one candidate that could succeed *wrongly*.
+ * - the file may have been moved since export, so the basename alone, beside the model or
+ *   in the folder next to it, is worth trying after the declared path and never before it.
+ *
+ * Order matters and is the whole value: most specific first, so an asset carrying two
+ * `wheel.jpg` files in different folders resolves each to its own rather than to whichever
+ * the search happened to reach.
+ */
+
+/**
+ * A texture a model named, with its bytes when the model carried them inline.
+ *
+ * One type for both cases because the difference is the *format's* business and not the
+ * baker's: glTF may embed an image in its binary chunk or in a data URI, and may equally
+ * point at a file beside itself, while FBX and OBJ only ever name a path. A reader reports
+ * whichever it has, and the resolver looks up only what arrived without bytes.
+ */
+export interface AssetReference {
+  /** What the source called it. Used to address the texture later, and to find it now. */
+  readonly name: string;
+  /** Present when the model carried the image itself, so nothing needs resolving. */
+  readonly bytes?: Uint8Array;
+}
+
+/** Backslashes to forward slashes, and any drive letter or leading root removed. */
+function normalise(declared: string): string {
+  const forward = declared.replace(/\\/g, '/');
+  /* `C:/x`, `//host/x` and `/x` are all absolute somewhere; keep only the part below them. */
+  return forward.replace(/^[a-zA-Z]:\//, '').replace(/^\/+/, '');
+}
+
+/** Everything after the last separator. */
+export function basenameOf(declared: string): string {
+  const normalised = normalise(declared);
+  return normalised.slice(normalised.lastIndexOf('/') + 1);
+}
+
+/**
+ * Paths to try for a reference, best first, relative to the folder holding the model.
+ *
+ * Deduplicated, because a texture declared as plain `carbon.jpg` would otherwise produce the
+ * same candidate three times, and a host that logs its attempts would report three failures
+ * for one missing file.
+ *
+ * `subfolders` are the conventional places a bundle puts its images. They are tried with the
+ * basename only, and last, so they can never outrank a path the file actually stated.
+ */
+export function assetCandidates(
+  declared: string,
+  subfolders: readonly string[] = ['textures', 'Textures', 'tex', 'maps', 'images'],
+): string[] {
+  const normalised = normalise(declared);
+  if (normalised === '') return [];
+  const base = basenameOf(declared);
+
+  const out: string[] = [normalised];
+  /* A declared path with folders in it may have lost them; the basename beside the model
+     is the single most common way an asset arrives after being repacked. */
+  if (base !== normalised) out.push(base);
+  for (const folder of subfolders) out.push(`${folder}/${base}`);
+
+  return [...new Set(out)];
+}