@driftengine/assets 3.61.0

package/dist/gltfAccessor.d.ts

@@ -0,0 +1,2 @@
+import type { GltfDocument } from './gltf.ts';
+export declare function accessorFloats(doc: GltfDocument, buffers: readonly Uint8Array[], index: number, what: string): Float32Array;

package/dist/gltfAccessor.js

@@ -0,0 +1,106 @@
+import { DrftError } from '@driftengine/drft';
+/**
+ * Reading one glTF accessor into floats, and the two tables that describe one.
+ *
+ * **Its own module so `gltfSkin.ts` and `gltf.ts` can both use it without importing each other.**
+ * The skin reader needs the graph the mesh reader deliberately discards, and the mesh reader needs
+ * the skin reader's remap — which would be a runtime import cycle if the accessor reader stayed in
+ * either of them. The `GltfDocument` type still comes from `gltf.ts` and costs nothing: a type
+ * import is erased, so no cycle survives to run.
+ *
+ * Every component type widens to `Float32Array`, which is what `MeshData` carries throughout —
+ * including `JOINTS_0`, whose unsigned bytes are exact in float32 well past the 512-joint cap.
+ */
+const COMPONENT_BYTES = {
+    5120: 1, // BYTE
+    5121: 1, // UNSIGNED_BYTE
+    5122: 2, // SHORT
+    5123: 2, // UNSIGNED_SHORT
+    5125: 4, // UNSIGNED_INT
+    5126: 4, // FLOAT
+};
+const TYPE_COMPONENTS = {
+    SCALAR: 1,
+    VEC2: 2,
+    VEC3: 3,
+    VEC4: 4,
+    MAT4: 16,
+};
+export function accessorFloats(doc, buffers, index, what) {
+    const accessor = doc.accessors?.[index];
+    if (accessor === undefined)
+        throw new DrftError(`gltf: ${what} names accessor ${index}, which is absent`);
+    if (accessor.sparse !== undefined) {
+        throw new DrftError(`gltf: ${what} uses a sparse accessor, which this reader does not implement. ` +
+            `Re-export without sparse accessors, or convert with a tool that expands them.`);
+    }
+    const components = TYPE_COMPONENTS[accessor.type];
+    const componentBytes = COMPONENT_BYTES[accessor.componentType];
+    if (components === undefined || componentBytes === undefined) {
+        throw new DrftError(`gltf: ${what} has an unsupported type ${accessor.type}/${accessor.componentType}`);
+    }
+    const out = new Float32Array(accessor.count * components);
+    if (accessor.bufferView === undefined)
+        return out; // Defined as zeroes.
+    const bufferView = doc.bufferViews?.[accessor.bufferView];
+    if (bufferView === undefined)
+        throw new DrftError(`gltf: ${what} names a bufferView that is absent`);
+    const source = buffers[bufferView.buffer];
+    if (source === undefined)
+        throw new DrftError(`gltf: ${what} names buffer ${bufferView.buffer}, absent`);
+    const stride = bufferView.byteStride ?? components * componentBytes;
+    const base = (bufferView.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
+    const view = new DataView(source.buffer, source.byteOffset, source.byteLength);
+    /* Normalised integers carry their range in the type, which is why this is not a cast. */
+    const scale = accessor.normalized === true ? normalisedScale(accessor.componentType) : 1;
+    for (let i = 0; i < accessor.count; i++) {
+        const at = base + i * stride;
+        for (let c = 0; c < components; c++) {
+            const offset = at + c * componentBytes;
+            if (offset + componentBytes > source.byteLength) {
+                throw new DrftError(`gltf: ${what} reads past the end of its buffer at ${offset}`);
+            }
+            out[i * components + c] = readComponent(view, offset, accessor.componentType) * scale;
+        }
+    }
+    return out;
+}
+function readComponent(view, at, componentType) {
+    switch (componentType) {
+        case 5120:
+            return view.getInt8(at);
+        case 5121:
+            return view.getUint8(at);
+        case 5122:
+            return view.getInt16(at, true);
+        case 5123:
+            return view.getUint16(at, true);
+        case 5125:
+            return view.getUint32(at, true);
+        default:
+            return view.getFloat32(at, true);
+    }
+}
+function normalisedScale(componentType) {
+    switch (componentType) {
+        case 5120:
+            return 1 / 127;
+        case 5121:
+            return 1 / 255;
+        case 5122:
+            return 1 / 32767;
+        case 5123:
+            return 1 / 65535;
+        default:
+            return 1;
+    }
+}
+/**
+ * The matrix a skinned primitive is built with: none.
+ *
+ * A palette entry already carries its joint's inverse bind, so it takes a vertex from model space
+ * to where the joint moved it — and `uModel` then places the character. Baking the node's world
+ * matrix in as well applies that placement twice and throws the rig across the scene. See
+ * `gltfSkin.ts`.
+ */
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];

package/dist/gltfSkin.d.ts

@@ -0,0 +1,32 @@
+import type { AnimationClip, Joint } from '@driftengine/drft';
+import type { GltfDocument } from './gltf.ts';
+/**
+ * Skins and animations out of a glTF document, sorted into the order a palette can be resolved in.
+ *
+ * **Its own module rather than more of `gltf.ts`**, because the two answer different questions: that
+ * file turns primitives into geometry in world space and says in its header that the node graph
+ * does not survive it. A skin is the one thing that needs the graph, and keeping the reader for it
+ * separate is what lets the flattening stay exactly as it was for every document without one.
+ *
+ * **Nothing here depends on `@driftengine/animation`.** The shapes it produces live in the format
+ * package, beside the chunks that carry them, so the package that writes a rig and the package
+ * that plays one meet over data rather than over each other.
+ */
+export interface GltfSkin {
+    readonly joints: readonly Joint[];
+    /** Sixteen floats a joint, column-major, in the same order as `joints`. */
+    readonly inverseBind: Float32Array;
+    /**
+     * glTF joint index to sorted joint index.
+     *
+     * The importer sorts parents-first because a palette is resolved in index order, and it is also
+     * the only layer that can: every index naming a joint has to move with it — a mesh's `JOINTS_0`
+     * and every animation channel's target. A caller re-indexing a mesh needs this.
+     */
+    readonly remap: Uint16Array;
+}
+export interface GltfAnimated {
+    readonly skins: readonly GltfSkin[];
+    readonly clips: readonly AnimationClip[];
+}
+export declare function readGltfSkins(doc: GltfDocument, buffers: readonly Uint8Array[]): GltfAnimated;

package/dist/gltfSkin.js

@@ -0,0 +1,144 @@
+import { DrftError } from '@driftengine/drft';
+import { accessorFloats } from './gltfAccessor.js';
+export function readGltfSkins(doc, buffers) {
+    const definitions = doc.skins ?? [];
+    if (definitions.length === 0)
+        return { skins: [], clips: [] };
+    /* Which node is whose child, which glTF states only in the other direction. */
+    const parentOf = new Map();
+    (doc.nodes ?? []).forEach((node, at) => {
+        for (const child of node.children ?? [])
+            parentOf.set(child, at);
+    });
+    const skins = [];
+    /** Node index to sorted joint index, for every skin, so a channel can find its track. */
+    const jointOfNode = new Map();
+    for (const definition of definitions) {
+        const order = sortParentsFirst(definition.joints, parentOf, doc);
+        const joints = order.map((node) => {
+            const parent = parentOf.get(node);
+            /*
+             * A parent outside this skin makes the joint a root *of this skin*. glTF allows it — a rig
+             * hung under a scene node — and reading it as missing would refuse valid files.
+             */
+            const within = parent === undefined ? -1 : order.indexOf(parent);
+            return { parent: within, name: doc.nodes?.[node]?.name ?? `joint ${node}` };
+        });
+        const remap = new Uint16Array(definition.joints.length);
+        definition.joints.forEach((node, old) => {
+            remap[old] = order.indexOf(node);
+        });
+        skins.push({ joints, inverseBind: readInverseBind(doc, buffers, definition, order), remap });
+        order.forEach((node, at) => jointOfNode.set(node, at));
+    }
+    return { skins, clips: readClips(doc, buffers, jointOfNode) };
+}
+/**
+ * The skin's joints, parents before children.
+ *
+ * A depth-first walk from each root rather than a sort with a comparator, because "before its
+ * parent" is not a total order over nodes and a comparator would have to invent one. Visiting a
+ * node only after its parent is what the walk gives for free.
+ */
+function sortParentsFirst(joints, parentOf, doc) {
+    const within = new Set(joints);
+    for (const node of joints) {
+        if (doc.nodes?.[node] === undefined) {
+            throw new DrftError(`gltf: a skin names node ${node}, which is absent`);
+        }
+    }
+    const out = [];
+    const placed = new Set();
+    const place = (node, depth) => {
+        if (placed.has(node))
+            return;
+        /*
+         * A cycle would recurse forever. glTF forbids one, and `gltf.ts` refuses a graph with one on
+         * the mesh path — but this reader walks the graph the other way round, from children up, so it
+         * checks for itself rather than relying on a check that may not have run.
+         */
+        if (depth > joints.length) {
+            throw new DrftError(`gltf: the joint hierarchy around node ${node} has a cycle`);
+        }
+        const parent = parentOf.get(node);
+        if (parent !== undefined && within.has(parent))
+            place(parent, depth + 1);
+        if (placed.has(node))
+            return;
+        placed.add(node);
+        out.push(node);
+    };
+    for (const node of joints)
+        place(node, 0);
+    return out;
+}
+/**
+ * The inverse bind matrices, reordered to match the sorted joints.
+ *
+ * Absent means identity, which glTF defines: a rig whose bind pose is the node graph's own rest
+ * transforms needs no matrices, and reading absence as zeroes would collapse every vertex.
+ */
+function readInverseBind(doc, buffers, definition, order) {
+    const out = new Float32Array(order.length * 16);
+    if (definition.inverseBindMatrices === undefined) {
+        for (let j = 0; j < order.length; j++) {
+            out[j * 16] = 1;
+            out[j * 16 + 5] = 1;
+            out[j * 16 + 10] = 1;
+            out[j * 16 + 15] = 1;
+        }
+        return out;
+    }
+    const source = accessorFloats(doc, buffers, definition.inverseBindMatrices, 'skin inverseBindMatrices');
+    if (source.length < definition.joints.length * 16) {
+        throw new DrftError(`gltf: a skin has ${definition.joints.length} joints but ${source.length / 16} inverse ` +
+            `bind matrices. Every joint needs one, or the ones past the end read as zero and ` +
+            `collapse the vertices they weight.`);
+    }
+    order.forEach((node, at) => {
+        const old = definition.joints.indexOf(node);
+        out.set(source.subarray(old * 16, old * 16 + 16), at * 16);
+    });
+    return out;
+}
+/** glTF's path names are this engine's, but only three of them drive a joint. */
+function trackPath(path) {
+    if (path === 'translation' || path === 'rotation' || path === 'scale')
+        return path;
+    /*
+     * `weights` drives morph targets rather than a joint, and is dropped here rather than refused:
+     * a file carrying both should still animate its skeleton. Track A's morph phase is what reads it.
+     */
+    return null;
+}
+function readClips(doc, buffers, jointOfNode) {
+    const clips = [];
+    (doc.animations ?? []).forEach((animation, index) => {
+        const tracks = [];
+        let duration = 0;
+        for (const channel of animation.channels) {
+            const path = trackPath(channel.target.path);
+            const node = channel.target.node;
+            /*
+             * A channel targeting a node no skin contains is skipped rather than refused. A scene's
+             * camera or a prop is animated in the same block as its characters, and a file that
+             * animates one is not a broken file.
+             */
+            if (path === null || node === undefined)
+                continue;
+            const joint = jointOfNode.get(node);
+            if (joint === undefined)
+                continue;
+            const sampler = animation.samplers[channel.sampler];
+            if (sampler === undefined) {
+                throw new DrftError(`gltf: animation ${index} has a channel naming sampler ${channel.sampler}, which is absent`);
+            }
+            const times = accessorFloats(doc, buffers, sampler.input, `animation ${index} input`);
+            const values = accessorFloats(doc, buffers, sampler.output, `animation ${index} output`);
+            duration = Math.max(duration, times[times.length - 1] ?? 0);
+            tracks.push({ joint, path, times, values });
+        }
+        clips.push({ name: animation.name ?? `animation ${index}`, durationSec: duration, tracks });
+    });
+    return clips;
+}

package/dist/iesPhotometry.d.ts

@@ -0,0 +1,44 @@
+/** The IESNA LM-63 photometric file: what a real fixture actually throws, and in which direction. */
+/**
+ * A fixture's measured intensity, as a grid over vertical and horizontal angles.
+ *
+ * **Candela rather than a normalised curve**, because the two answer different questions and only
+ * one of them is in the file: the shape of the distribution is what a renderer samples, and the
+ * absolute output is what tells a consumer whether this fixture is a reading lamp or a floodlight.
+ * Normalising here would throw the second away, and a consumer that wants the shape can divide by
+ * `maxCandela` — which is why it is carried rather than left to be recomputed.
+ */
+export interface IesProfile {
+    /**
+     * Vertical angles in degrees, increasing. 0 is straight down for the common type-C fixture.
+     *
+     * Not resampled to a regular grid here. A real file is dense where the distribution changes and
+     * sparse where it does not, and flattening that is a decision about a texture rather than about
+     * a file — `iesProfile.ts` in the renderer makes it.
+     */
+    readonly verticalAngles: Float32Array;
+    /** Horizontal angles in degrees, increasing. A single 0 means the fixture is axially symmetric. */
+    readonly horizontalAngles: Float32Array;
+    /** Candela, horizontal-major: all vertical angles of the first plane, then the second. */
+    readonly candela: Float32Array;
+    /** The brightest value in the grid, so a consumer can normalise without walking it again. */
+    readonly maxCandela: number;
+}
+/**
+ * Read an LM-63 photometric file.
+ *
+ * **Whitespace-delimited across line breaks, because that is what the format is.** LM-63 attaches
+ * no meaning to a newline inside its numeric lists, and every file a manufacturer publishes wraps
+ * them — so a reader that parses line by line passes a hand-built fixture and fails on everything
+ * real. The header is the only part that is line-oriented, and it ends at `TILT=`.
+ *
+ * **Pure, and it takes text rather than a URL**, for the reason `readRadianceHdr` gives: the
+ * fetching decision belongs to the consumer who has to make it, and a pure function is one that can
+ * be tested exactly.
+ *
+ * **What it costs** is holding the whole grid, which for a dense fixture is a few thousand floats.
+ * **What would make it wrong** is a `TILT` other than `NONE`: that describes a fixture mounted at
+ * an angle with its own correction table, and applying the distribution without it would be
+ * confidently wrong rather than obviously wrong — so it is refused by name.
+ */
+export declare function readIesProfile(text: string): IesProfile;

package/dist/iesPhotometry.js

@@ -0,0 +1,94 @@
+/** The IESNA LM-63 photometric file: what a real fixture actually throws, and in which direction. */
+/**
+ * Read an LM-63 photometric file.
+ *
+ * **Whitespace-delimited across line breaks, because that is what the format is.** LM-63 attaches
+ * no meaning to a newline inside its numeric lists, and every file a manufacturer publishes wraps
+ * them — so a reader that parses line by line passes a hand-built fixture and fails on everything
+ * real. The header is the only part that is line-oriented, and it ends at `TILT=`.
+ *
+ * **Pure, and it takes text rather than a URL**, for the reason `readRadianceHdr` gives: the
+ * fetching decision belongs to the consumer who has to make it, and a pure function is one that can
+ * be tested exactly.
+ *
+ * **What it costs** is holding the whole grid, which for a dense fixture is a few thousand floats.
+ * **What would make it wrong** is a `TILT` other than `NONE`: that describes a fixture mounted at
+ * an angle with its own correction table, and applying the distribution without it would be
+ * confidently wrong rather than obviously wrong — so it is refused by name.
+ */
+export function readIesProfile(text) {
+    if (!/IESNA/i.test(text.slice(0, 200))) {
+        throw new Error(`readIesProfile: not an IESNA photometric file — no IESNA signature in the first line, ` +
+            `found "${text.slice(0, 40).replace(/\n[\s\S]*/, '')}"`);
+    }
+    const tilt = /^TILT=(.*)$/m.exec(text);
+    if (tilt === null)
+        throw new Error('readIesProfile: no TILT= line, so the header never ended');
+    const tiltValue = (tilt[1] ?? '').trim().toUpperCase();
+    if (tiltValue !== 'NONE') {
+        throw new Error(`readIesProfile: TILT=${tiltValue} is not handled. That fixture is mounted at an angle and ` +
+            'carries its own correction table; applying its distribution without one would be ' +
+            'confidently wrong rather than obviously wrong.');
+    }
+    /* Everything after the TILT line is numbers, and the line breaks in it mean nothing. */
+    const body = text.slice(tilt.index + tilt[0].length);
+    const numbers = body
+        .split(/[\s,]+/)
+        .filter((token) => token.length > 0)
+        .map(Number);
+    let at = 0;
+    const next = (what) => {
+        const value = numbers[at];
+        at += 1;
+        if (value === undefined || !Number.isFinite(value)) {
+            throw new Error(`readIesProfile: expected ${what} at value ${at} and the file ended or held "${value}"`);
+        }
+        return value;
+    };
+    /* The ten-number line: lamps, lumens, multiplier, counts, type, units, and three dimensions. */
+    next('the lamp count');
+    next('lumens per lamp');
+    const multiplier = next('the candela multiplier');
+    const verticalCount = Math.round(next('the vertical angle count'));
+    const horizontalCount = Math.round(next('the horizontal angle count'));
+    next('the photometric type');
+    next('the units type');
+    next('the fixture width');
+    next('the fixture length');
+    next('the fixture height');
+    /* The seven-number line, of which only the ballast factor reaches the output. */
+    const ballast = next('the ballast factor');
+    next('the future-use field');
+    next('the input watts');
+    if (verticalCount <= 0 || horizontalCount <= 0) {
+        throw new Error(`readIesProfile: a ${verticalCount} by ${horizontalCount} grid has no distribution in it`);
+    }
+    const verticalAngles = new Float32Array(verticalCount);
+    for (let i = 0; i < verticalCount; i++)
+        verticalAngles[i] = next(`vertical angle ${i}`);
+    const horizontalAngles = new Float32Array(horizontalCount);
+    for (let i = 0; i < horizontalCount; i++)
+        horizontalAngles[i] = next(`horizontal angle ${i}`);
+    const wanted = verticalCount * horizontalCount;
+    const remaining = numbers.length - at;
+    if (remaining !== wanted) {
+        throw new Error(`readIesProfile: ${verticalCount} vertical by ${horizontalCount} horizontal needs ${wanted} ` +
+            `candela values and the file holds ${remaining}`);
+    }
+    /*
+     * **Both factors, and the file means their product.** The multiplier is on the ten-number line
+     * and the ballast factor on the seven-number line, and a fixture's real output is candela times
+     * both. Dropping either gives a profile uniformly too dim, which reads as the light having been
+     * authored wrong rather than as the file being misread.
+     */
+    const scale = multiplier * ballast;
+    const candela = new Float32Array(wanted);
+    let maxCandela = 0;
+    for (let i = 0; i < wanted; i++) {
+        const value = next(`candela ${i}`) * scale;
+        candela[i] = value;
+        if (value > maxCandela)
+            maxCandela = value;
+    }
+    return { verticalAngles, horizontalAngles, candela, maxCandela };
+}

package/dist/imageInfo.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What an image is, from its own first bytes. One responsibility: identify, never decode.
+ *
+ * The baker embeds compressed images untouched, so it never decodes one — but the format
+ * stores a codec and a size beside each payload, and both have to come from somewhere. They
+ * come from here, by reading the few bytes every container puts at its front for exactly
+ * this purpose.
+ *
+ * **Why the size is stored at all, when the decoder will report it anyway.** A loader that
+ * has to decode before it can size anything cannot budget: it learns that a level carries
+ * 400 MB of texture only after it has allocated it. Reading it here costs a dozen bytes per
+ * texture and lets a consumer refuse, downscale or stream before committing.
+ *
+ * **The extension is not consulted.** A `.jpg` that is really a PNG is common enough to be
+ * unremarkable, and every one of these formats identifies itself unambiguously in its first
+ * bytes. Trusting the name over the content is how a file that would have loaded fine gets
+ * refused, and how one that cannot be decoded gets embedded anyway.
+ */
+export interface ImageInfo {
+    readonly codec: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Identify an image and read its dimensions, or refuse by name.
+ *
+ * Refusing is the designed outcome for anything else. A tier 2 import that quietly dropped
+ * an unrecognised texture would produce a model that is merely the wrong colour, which is
+ * discovered late and blamed on the shading.
+ */
+export declare function describeImage(bytes: Uint8Array): ImageInfo;

package/dist/imageInfo.js

@@ -0,0 +1,119 @@
+/**
+ * What an image is, from its own first bytes. One responsibility: identify, never decode.
+ *
+ * The baker embeds compressed images untouched, so it never decodes one — but the format
+ * stores a codec and a size beside each payload, and both have to come from somewhere. They
+ * come from here, by reading the few bytes every container puts at its front for exactly
+ * this purpose.
+ *
+ * **Why the size is stored at all, when the decoder will report it anyway.** A loader that
+ * has to decode before it can size anything cannot budget: it learns that a level carries
+ * 400 MB of texture only after it has allocated it. Reading it here costs a dozen bytes per
+ * texture and lets a consumer refuse, downscale or stream before committing.
+ *
+ * **The extension is not consulted.** A `.jpg` that is really a PNG is common enough to be
+ * unremarkable, and every one of these formats identifies itself unambiguously in its first
+ * bytes. Trusting the name over the content is how a file that would have loaded fine gets
+ * refused, and how one that cannot be decoded gets embedded anyway.
+ */
+import { CODEC_JPEG, CODEC_PNG, CODEC_WEBP, DrftError } from '@driftengine/drft';
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+function startsWith(bytes, signature, at = 0) {
+    if (bytes.length < at + signature.length)
+        return false;
+    for (let i = 0; i < signature.length; i++) {
+        if (bytes[at + i] !== signature[i])
+            return false;
+    }
+    return true;
+}
+function ascii(bytes, at, length) {
+    let out = '';
+    for (let i = 0; i < length; i++)
+        out += String.fromCharCode(bytes[at + i] ?? 0);
+    return out;
+}
+/**
+ * JPEG's size lives in a start-of-frame marker, and finding it means walking the segments.
+ *
+ * There is no fixed offset: a file carries any number of leading segments (EXIF, colour
+ * profiles, comments), each length-prefixed, and the frame header sits after them. The
+ * fifteen SOF markers differ in *compression*, not in the four bytes wanted here, so all of
+ * them are accepted apart from the four that are not frames at all.
+ */
+function jpegSize(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let at = 2;
+    while (at + 4 <= bytes.length) {
+        if (bytes[at] !== 0xff) {
+            at++;
+            continue;
+        }
+        const marker = bytes[at + 1];
+        /* Padding and the standalone markers carry no length to skip. */
+        if (marker === 0xff || marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9)) {
+            at += 2;
+            continue;
+        }
+        const length = view.getUint16(at + 2, false);
+        const isFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (isFrame) {
+            if (at + 9 > bytes.length)
+                break;
+            return { height: view.getUint16(at + 5, false), width: view.getUint16(at + 7, false) };
+        }
+        /* A start-of-scan is followed by entropy-coded data, so the frame is behind us. */
+        if (marker === 0xda)
+            break;
+        if (length < 2)
+            break;
+        at += 2 + length;
+    }
+    throw new DrftError('a JPEG carries no start-of-frame marker, so its size cannot be read');
+}
+/** WEBP is a RIFF container with three payload shapes, each storing its size differently. */
+function webpSize(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const kind = ascii(bytes, 12, 4);
+    if (kind === 'VP8X' && bytes.length >= 30) {
+        /* Canvas size, stored minus one across three little-endian bytes each. */
+        const width = (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16)) + 1;
+        const height = (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16)) + 1;
+        return { width, height };
+    }
+    if (kind === 'VP8 ' && bytes.length >= 30) {
+        return { width: view.getUint16(26, true) & 0x3fff, height: view.getUint16(28, true) & 0x3fff };
+    }
+    if (kind === 'VP8L' && bytes.length >= 25) {
+        const bits = view.getUint32(21, true);
+        return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+    }
+    throw new DrftError(`a WEBP with a "${kind}" payload is not one this reader can size`);
+}
+/**
+ * Identify an image and read its dimensions, or refuse by name.
+ *
+ * Refusing is the designed outcome for anything else. A tier 2 import that quietly dropped
+ * an unrecognised texture would produce a model that is merely the wrong colour, which is
+ * discovered late and blamed on the shading.
+ */
+export function describeImage(bytes) {
+    if (startsWith(bytes, PNG_SIGNATURE)) {
+        if (bytes.length < 24)
+            throw new DrftError('a PNG ends before its header');
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        return {
+            codec: CODEC_PNG,
+            width: view.getUint32(16, false),
+            height: view.getUint32(20, false),
+        };
+    }
+    if (bytes.length > 3 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+        return { codec: CODEC_JPEG, ...jpegSize(bytes) };
+    }
+    if (ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 4) === 'WEBP') {
+        return { codec: CODEC_WEBP, ...webpSize(bytes) };
+    }
+    const head = [...bytes.subarray(0, 4)].map((b) => b.toString(16).padStart(2, '0')).join(' ');
+    throw new DrftError(`an image starting ${head} is not PNG, JPEG or WEBP. Convert it to one of those and bake again.`);
+}

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * Reading a model, and getting it onto the GPU.
+ *
+ * Separate from `@driftengine/drft` because these need a renderer: the loader uploads, and
+ * the readers exist to produce something the loader can upload. A procedurally generated
+ * world imports none of this and pays for none of it.
+ */
+export { DrftLoader } from './drftLoader.ts';
+export type { DrftFit, DrftLoaderOptions } from './drftLoader.ts';
+export { drawKeyOf, resolveDrawGrouping } from './drawKey.ts';
+export type { DrawGrouping, DrawSurfaceOverride } from './drawKey.ts';
+export type { DrftLoadPhase, DrftLoadProgress, DrftPart } from './loadProgress.ts';
+export { TextureSet, textureColorSpaces } from './drftTextures.ts';
+export { assetCandidates, basenameOf } from './assetPath.ts';
+export { describeImage } from './imageInfo.ts';
+export type { ImageInfo } from './imageInfo.ts';
+export type { AssetReference } from './assetPath.ts';
+export { readGlb, gltfToMeshes } from './gltf.ts';
+export type { GltfDocument } from './gltf.ts';
+export { parseObj, parseMtl } from './obj.ts';
+export { parseStl } from './stl.ts';
+export { readRadianceHdr } from './radianceHdr.ts';
+export { readIesProfile } from './iesPhotometry.ts';
+export type { IesProfile } from './iesPhotometry.ts';
+export type { RadianceImage } from './radianceHdr.ts';
+export type { StlAppearance } from './stl.ts';
+export { parseUsda, usdzToMeshes } from './usd.ts';
+export type { UsdResult } from './usd.ts';
+export { parseThreeMfModel, threeMfToMeshes } from './threemf.ts';
+export type { ThreeMfResult } from './threemf.ts';
+export { readZip, findEntry } from './zip.ts';
+export type { ZipEntry } from './zip.ts';
+export { recognise, describeRecognised } from './recognise.ts';
+export type { Recognised } from './recognise.ts';
+export { fbxToMeshes } from './fbx.ts';
+export type { Inflate } from './fbx.ts';
+export { readModel, readerFor, extensionOf, MODEL_FORMATS } from './readModel.ts';
+export type { ModelSource, ModelImport } from './readModel.ts';
+export { browserInflate, browserInflateRaw, prepareFbxInflate, prepareZipInflate, } from './fbxInflate.ts';
+export type { AsyncInflate } from './fbxInflate.ts';
+export { weldMesh, dropDefaultAttributes } from './weld.ts';
+export { deriveTangentsFor } from './tangentOrder.ts';
+export { buildCoarseLevel, isOutlineWorthWriting, DEFAULT_COARSE_CELLS } from './coarseLevel.ts';
+export type { CoarseLevelOptions } from './coarseLevel.ts';
+export { orientMeshes, parseUpAxis, describeUpAxis } from './orient.ts';
+export type { UpAxis } from './orient.ts';
+export { readGltfSkins } from './gltfSkin.ts';
+export type { GltfAnimated, GltfSkin } from './gltfSkin.ts';
+export { convertHandedness } from './orient.ts';
+export type { Handedness } from './orient.ts';
+export { orientNodes } from './orient.ts';
+export { mirrorNodes } from './orient.ts';
+export { localiseNodes } from './localise.ts';
+export type { Localised } from './localise.ts';
+export { colliderBeside, levelsBeside } from './readModel.ts';
+export { ddsToRgba, isDds } from './dds.ts';
+export type { DdsImage } from './dds.ts';