@driftengine/assets 3.61.0

package/dist/stl.d.ts

@@ -0,0 +1,22 @@
+/**
+ * STL, binary and ASCII.
+ *
+ * The simplest format in the pipeline and the least informative: triangles and a facet
+ * normal, with no colour, no UVs, no hierarchy and no materials. Everything a `MeshData`
+ * carries beyond position and normal has to be supplied by the caller, and this reader
+ * says so rather than inventing it.
+ *
+ * **Shaded flat, deliberately.** An STL has one normal per *face*, so its vertices cannot
+ * be shared and there is nothing to average. Welding them and smoothing would make a
+ * printed part look like an organic model — a change to the artist's intent made silently
+ * by a reader, which is not a reader's decision to make. A smoothing pass belongs in the
+ * baker, behind a flag, where somebody chose it.
+ */
+import type { MeshData } from '@driftengine/drft';
+/** What a caller may supply, since the format carries none of it. */
+export interface StlAppearance {
+    readonly color?: readonly [number, number, number];
+    readonly roughness?: number;
+    readonly specular?: number;
+}
+export declare function parseStl(buffer: ArrayBuffer, appearance?: StlAppearance): MeshData;

package/dist/stl.js

@@ -0,0 +1,131 @@
+/**
+ * STL, binary and ASCII.
+ *
+ * The simplest format in the pipeline and the least informative: triangles and a facet
+ * normal, with no colour, no UVs, no hierarchy and no materials. Everything a `MeshData`
+ * carries beyond position and normal has to be supplied by the caller, and this reader
+ * says so rather than inventing it.
+ *
+ * **Shaded flat, deliberately.** An STL has one normal per *face*, so its vertices cannot
+ * be shared and there is nothing to average. Welding them and smoothing would make a
+ * printed part look like an organic model — a change to the artist's intent made silently
+ * by a reader, which is not a reader's decision to make. A smoothing pass belongs in the
+ * baker, behind a flag, where somebody chose it.
+ */
+import { DrftError } from '@driftengine/drft';
+/**
+ * Binary STL is 80 bytes of header, a count, then 50 bytes per triangle. An ASCII one
+ * begins with `solid` — but so do some binary files, so the length is checked as well.
+ * That check is the whole of the detection and it is exact rather than a guess.
+ */
+function looksBinary(bytes) {
+    if (bytes.length < 84)
+        return false;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const triangles = view.getUint32(80, true);
+    return bytes.length === 84 + triangles * 50;
+}
+export function parseStl(buffer, appearance = {}) {
+    const bytes = new Uint8Array(buffer);
+    const triangles = looksBinary(bytes)
+        ? readBinary(bytes)
+        : readAscii(new TextDecoder().decode(bytes));
+    if (triangles.length === 0)
+        throw new DrftError('stl: no triangles');
+    const count = triangles.length * 3;
+    const positions = new Float32Array(count * 3);
+    const normals = new Float32Array(count * 3);
+    const colors = new Float32Array(count * 3);
+    const indices = new Uint32Array(count);
+    const [r, g, b] = appearance.color ?? [0.8, 0.8, 0.82];
+    for (let t = 0; t < triangles.length; t++) {
+        const triangle = triangles[t];
+        for (let c = 0; c < 3; c++) {
+            const at = (t * 3 + c) * 3;
+            positions[at] = triangle.vertices[c * 3];
+            positions[at + 1] = triangle.vertices[c * 3 + 1];
+            positions[at + 2] = triangle.vertices[c * 3 + 2];
+            normals[at] = triangle.normal[0];
+            normals[at + 1] = triangle.normal[1];
+            normals[at + 2] = triangle.normal[2];
+            colors[at] = r;
+            colors[at + 1] = g;
+            colors[at + 2] = b;
+            indices[t * 3 + c] = t * 3 + c;
+        }
+    }
+    return {
+        positions,
+        normals,
+        colors,
+        emissive: new Float32Array(count),
+        /* Only what the caller named: an unasked-for attribute is the engine's own default. */
+        ...(appearance.specular === undefined
+            ? {}
+            : { specular: new Float32Array(count).fill(appearance.specular) }),
+        ...(appearance.roughness === undefined
+            ? {}
+            : { roughness: new Float32Array(count).fill(appearance.roughness) }),
+        indices,
+    };
+}
+/**
+ * A facet normal of zero is legal and common — exporters write it to mean "work it out".
+ * Computed from the winding rather than passed through, because a zero normal is not a
+ * neutral value: every lighting term multiplies by it, so the part would arrive black.
+ */
+function withNormal(normal, vertices) {
+    if (Math.hypot(normal[0], normal[1], normal[2]) > 1e-8)
+        return { normal, vertices };
+    const ux = vertices[3] - vertices[0];
+    const uy = vertices[4] - vertices[1];
+    const uz = vertices[5] - vertices[2];
+    const vx = vertices[6] - vertices[0];
+    const vy = vertices[7] - vertices[1];
+    const vz = vertices[8] - vertices[2];
+    const nx = uy * vz - uz * vy;
+    const ny = uz * vx - ux * vz;
+    const nz = ux * vy - uy * vx;
+    const length = Math.hypot(nx, ny, nz) || 1;
+    return { normal: [nx / length, ny / length, nz / length], vertices };
+}
+function readBinary(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const count = view.getUint32(80, true);
+    const triangles = [];
+    let at = 84;
+    for (let i = 0; i < count; i++) {
+        const normal = [
+            view.getFloat32(at, true),
+            view.getFloat32(at + 4, true),
+            view.getFloat32(at + 8, true),
+        ];
+        const vertices = [];
+        for (let v = 0; v < 9; v++)
+            vertices.push(view.getFloat32(at + 12 + v * 4, true));
+        triangles.push(withNormal(normal, vertices));
+        at += 50;
+    }
+    return triangles;
+}
+function readAscii(text) {
+    const triangles = [];
+    let normal = [0, 0, 0];
+    let vertices = [];
+    for (const rawLine of text.split('\n')) {
+        const parts = rawLine.trim().split(/\s+/);
+        if (parts[0] === 'facet' && parts[1] === 'normal') {
+            normal = [Number(parts[2]), Number(parts[3]), Number(parts[4])];
+            vertices = [];
+        }
+        else if (parts[0] === 'vertex') {
+            vertices.push(Number(parts[1]), Number(parts[2]), Number(parts[3]));
+        }
+        else if (parts[0] === 'endfacet') {
+            if (vertices.length === 9)
+                triangles.push(withNormal(normal, vertices));
+            vertices = [];
+        }
+    }
+    return triangles;
+}

package/dist/tangentOrder.d.ts

@@ -0,0 +1,24 @@
+import type { MeshData } from '@driftengine/drft';
+/**
+ * Derive a tangent frame for a mesh that has none, **after** it has been welded.
+ *
+ * **The order is the point of this function existing.** `generateTangents` accumulates a frame per
+ * index, so a vertex shared by several triangles gets the sum of all of them and comes out smooth
+ * — which is what it was written to do. Run on a mesh as a file stores it, and a great many files
+ * store one vertex per triangle corner, every corner is its own index and gets exactly one
+ * triangle's frame. Two corners at the same point then disagree, and the weld cannot merge them,
+ * because two corners alike in position, normal and UV but opposite in the bitangent's sign are a
+ * mirrored UV shell and merging those lights one side of a model inside out. Nothing can tell the
+ * two cases apart from the data.
+ *
+ * **Measured on a rotationally unwrapped corner soup**, which is the shape a CAD conversion
+ * arrives in: 9,600 corners weld to 1,681 vertices with no frame present and to 9,482 with a frame
+ * derived per corner, with up to six different frames at one point. Deriving afterwards gives
+ * 1,681 vertices and one frame each, and the frame is *better* — averaged over every triangle at
+ * the vertex, which is the smoothing the derivation exists for and which a soup cannot supply.
+ *
+ * A mesh that already carries a frame is returned untouched: authored data is the file's to state.
+ * A mesh with no texture coordinates is returned untouched too, since there is no texture
+ * direction to derive one along.
+ */
+export declare function deriveTangentsFor(mesh: MeshData): MeshData;

package/dist/tangentOrder.js

@@ -0,0 +1,31 @@
+import { generateTangents } from '@driftengine/core';
+/**
+ * Derive a tangent frame for a mesh that has none, **after** it has been welded.
+ *
+ * **The order is the point of this function existing.** `generateTangents` accumulates a frame per
+ * index, so a vertex shared by several triangles gets the sum of all of them and comes out smooth
+ * — which is what it was written to do. Run on a mesh as a file stores it, and a great many files
+ * store one vertex per triangle corner, every corner is its own index and gets exactly one
+ * triangle's frame. Two corners at the same point then disagree, and the weld cannot merge them,
+ * because two corners alike in position, normal and UV but opposite in the bitangent's sign are a
+ * mirrored UV shell and merging those lights one side of a model inside out. Nothing can tell the
+ * two cases apart from the data.
+ *
+ * **Measured on a rotationally unwrapped corner soup**, which is the shape a CAD conversion
+ * arrives in: 9,600 corners weld to 1,681 vertices with no frame present and to 9,482 with a frame
+ * derived per corner, with up to six different frames at one point. Deriving afterwards gives
+ * 1,681 vertices and one frame each, and the frame is *better* — averaged over every triangle at
+ * the vertex, which is the smoothing the derivation exists for and which a soup cannot supply.
+ *
+ * A mesh that already carries a frame is returned untouched: authored data is the file's to state.
+ * A mesh with no texture coordinates is returned untouched too, since there is no texture
+ * direction to derive one along.
+ */
+export function deriveTangentsFor(mesh) {
+    if (mesh.tangents !== undefined || mesh.uvs === undefined)
+        return mesh;
+    return {
+        ...mesh,
+        tangents: generateTangents(mesh.positions, mesh.normals, mesh.uvs, mesh.indices),
+    };
+}

package/dist/threemf.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 3MF, the 3D Manufacturing Format: a zip of XML from the 3MF Consortium.
+ *
+ * Tier 1. The specification is published and the core is small — a mesh is a vertex list and
+ * a triangle list, and that has not changed since the format was introduced.
+ *
+ * **The same zip reader as `.usdz`, and the reason the two were built together.** The
+ * difference is one parameter: USD requires its entries *stored* so a runtime can memory
+ * map them, and 3MF uses ordinary deflate, so this one needs the injected inflate and that
+ * one does not. Injected rather than imported for the same reason as `fbx.ts`: this module
+ * is part of an engine that runs in a browser and must not reach for Node's `zlib`.
+ *
+ * **A printing format, so what it does not carry matters as much as what it does.** There
+ * are no normals: a 3MF mesh is a closed manifold and a slicer derives what it needs, so
+ * they are computed here from the triangles. There are no texture coordinates in the core
+ * specification either — the materials extension adds them, and until an asset turns up
+ * that uses it, claiming support would be claiming something untested.
+ */
+import type { MeshData } from '@driftengine/drft';
+import type { DrftMaterial } from '@driftengine/drft';
+import type { Inflate } from './fbx.ts';
+import type { UpAxis } from './orient.ts';
+/** What a `.3mf` yields, in the shape every other reader in this directory returns. */
+export interface ThreeMfResult {
+    readonly meshes: MeshData[];
+    /** One per mesh, by ordinal. */
+    readonly materials: DrftMaterial[];
+    readonly warnings: string[];
+    /**
+     * 3MF is Z-up and says so in its specification rather than per file, so this is a fact
+     * about the format rather than something read out of the document.
+     */
+    readonly declaredUp: UpAxis;
+    /** Metres per unit, from the model's `unit` attribute. Millimetres is the default. */
+    readonly unitScale: number;
+}
+/** Read the `3dmodel.model` XML out of a 3MF archive. */
+export declare function parseThreeMfModel(xml: string): ThreeMfResult;
+/**
+ * Read a `.3mf` archive.
+ *
+ * The model part is named by the OPC relationships, and is `3D/3dmodel.model` in practice.
+ * Both are tried, the relationship first, because "in practice" is how a reader acquires a
+ * file it cannot open two years later.
+ */
+export declare function threeMfToMeshes(buffer: ArrayBuffer, inflate: Inflate): ThreeMfResult;

package/dist/threemf.js

@@ -0,0 +1,254 @@
+/**
+ * 3MF, the 3D Manufacturing Format: a zip of XML from the 3MF Consortium.
+ *
+ * Tier 1. The specification is published and the core is small — a mesh is a vertex list and
+ * a triangle list, and that has not changed since the format was introduced.
+ *
+ * **The same zip reader as `.usdz`, and the reason the two were built together.** The
+ * difference is one parameter: USD requires its entries *stored* so a runtime can memory
+ * map them, and 3MF uses ordinary deflate, so this one needs the injected inflate and that
+ * one does not. Injected rather than imported for the same reason as `fbx.ts`: this module
+ * is part of an engine that runs in a browser and must not reach for Node's `zlib`.
+ *
+ * **A printing format, so what it does not carry matters as much as what it does.** There
+ * are no normals: a 3MF mesh is a closed manifold and a slicer derives what it needs, so
+ * they are computed here from the triangles. There are no texture coordinates in the core
+ * specification either — the materials extension adds them, and until an asset turns up
+ * that uses it, claiming support would be claiming something untested.
+ */
+import { DrftError } from '@driftengine/drft';
+import { readZip } from './zip.js';
+/** `unit` values the specification defines, in metres. */
+const UNITS = {
+    micron: 1e-6,
+    millimeter: 1e-3,
+    centimeter: 1e-2,
+    inch: 0.0254,
+    foot: 0.3048,
+    meter: 1,
+};
+const DEFAULT_MATERIAL = {
+    name: '',
+    color: [0.8, 0.8, 0.8],
+    specular: 0,
+    roughness: 0.6,
+    emissive: 0,
+    emissiveColor: [-1, -1, -1],
+    opacity: 1,
+    albedo: -1,
+    reflectivity: 0,
+    normalMap: -1,
+    ormMap: -1,
+    emissiveMap: -1,
+    roughnessScale: 1,
+    metallicScale: 1,
+    occlusionStrength: 0,
+    cutout: 0,
+};
+/** Every attribute of one XML tag, as a map. Values are always quoted in 3MF. */
+function attributes(tag) {
+    const out = new Map();
+    const pattern = /([\w:]+)\s*=\s*"([^"]*)"/g;
+    let match = pattern.exec(tag);
+    while (match !== null) {
+        out.set(match[1], match[2]);
+        match = pattern.exec(tag);
+    }
+    return out;
+}
+/**
+ * `#RRGGBB` or `#RRGGBBAA` to linear colour and opacity.
+ *
+ * **sRGB to linear, rather than the byte value straight through.** 3MF states its colours
+ * as sRGB, which is what a colour picker shows and not what a renderer multiplies: taking
+ * the bytes as-is makes every surface too bright, most visibly in the midtones, and it is
+ * the kind of wrong that looks like a lighting problem.
+ */
+function parseColor(value) {
+    const hex = /^#([0-9a-fA-F]{6})([0-9a-fA-F]{2})?$/.exec(value.trim());
+    if (hex === null)
+        return null;
+    const rgb = hex[1];
+    const toLinear = (byte) => {
+        const s = byte / 255;
+        return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return {
+        color: [
+            toLinear(parseInt(rgb.slice(0, 2), 16)),
+            toLinear(parseInt(rgb.slice(2, 4), 16)),
+            toLinear(parseInt(rgb.slice(4, 6), 16)),
+        ],
+        opacity: hex[2] === undefined ? 1 : parseInt(hex[2], 16) / 255,
+    };
+}
+/**
+ * Flat normals, derived per triangle and accumulated per vertex.
+ *
+ * 3MF carries none, so they are computed rather than invented: a printing format describes a
+ * solid and leaves shading to whoever displays it. Accumulating and normalising gives smooth
+ * shading across a curved surface, and `weld.ts` keeps a hard edge hard afterwards because
+ * two corners with different normals do not merge.
+ */
+function deriveNormals(positions, indices) {
+    const normals = new Float32Array(positions.length);
+    for (let at = 0; at + 2 < indices.length; at += 3) {
+        const a = indices[at] * 3;
+        const b = indices[at + 1] * 3;
+        const c = indices[at + 2] * 3;
+        const ux = positions[b] - positions[a];
+        const uy = positions[b + 1] - positions[a + 1];
+        const uz = positions[b + 2] - positions[a + 2];
+        const vx = positions[c] - positions[a];
+        const vy = positions[c + 1] - positions[a + 1];
+        const vz = positions[c + 2] - positions[a + 2];
+        const nx = uy * vz - uz * vy;
+        const ny = uz * vx - ux * vz;
+        const nz = ux * vy - uy * vx;
+        for (const corner of [a, b, c]) {
+            normals[corner] = normals[corner] + nx;
+            normals[corner + 1] = normals[corner + 1] + ny;
+            normals[corner + 2] = normals[corner + 2] + nz;
+        }
+    }
+    for (let at = 0; at + 2 < normals.length; at += 3) {
+        const length = Math.hypot(normals[at], normals[at + 1], normals[at + 2]);
+        if (length === 0) {
+            normals[at + 1] = 1;
+            continue;
+        }
+        normals[at] = normals[at] / length;
+        normals[at + 1] = normals[at + 1] / length;
+        normals[at + 2] = normals[at + 2] / length;
+    }
+    return normals;
+}
+/** Read the `3dmodel.model` XML out of a 3MF archive. */
+export function parseThreeMfModel(xml) {
+    const warnings = [];
+    const modelTag = /<model\b[^>]*>/.exec(xml)?.[0] ?? '';
+    const unit = attributes(modelTag).get('unit') ?? 'millimeter';
+    const unitScale = UNITS[unit];
+    if (unitScale === undefined) {
+        warnings.push(`unknown unit "${unit}"; treating the model as millimetres`);
+    }
+    /*
+     * The colour groups a triangle may point at. `basematerials` is the core specification's
+     * own; `colorgroup` comes from the materials extension and is what most exporters write.
+     * Both are flat lists indexed by the `pid`/`pindex` pair on an object or a triangle.
+     */
+    const palettes = new Map();
+    const groupPattern = /<(basematerials|m:colorgroup|colorgroup)\b([^>]*)>([\s\S]*?)<\/\1>/g;
+    let group = groupPattern.exec(xml);
+    while (group !== null) {
+        const id = attributes(group[2]).get('id');
+        if (id !== undefined) {
+            const entries = [];
+            const itemPattern = /<(?:base|m:color|color)\b([^>]*)\/?>/g;
+            let item = itemPattern.exec(group[3]);
+            while (item !== null) {
+                const fields = attributes(item[1]);
+                const parsed = parseColor(fields.get('displaycolor') ?? fields.get('color') ?? '');
+                entries.push({
+                    ...DEFAULT_MATERIAL,
+                    name: fields.get('name') ?? `material ${entries.length}`,
+                    ...(parsed === null ? {} : { color: parsed.color, opacity: parsed.opacity }),
+                });
+                item = itemPattern.exec(group[3]);
+            }
+            palettes.set(id, entries);
+        }
+        group = groupPattern.exec(xml);
+    }
+    const meshes = [];
+    const materials = [];
+    const objectPattern = /<object\b([^>]*)>([\s\S]*?)<\/object>/g;
+    let object = objectPattern.exec(xml);
+    while (object !== null) {
+        const objectFields = attributes(object[1]);
+        const body = object[2];
+        const name = objectFields.get('name') ?? `object ${objectFields.get('id') ?? meshes.length}`;
+        const vertices = [];
+        const vertexPattern = /<vertex\b([^>]*)\/?>/g;
+        let vertex = vertexPattern.exec(body);
+        while (vertex !== null) {
+            const fields = attributes(vertex[1]);
+            vertices.push(Number(fields.get('x') ?? 0), Number(fields.get('y') ?? 0), Number(fields.get('z') ?? 0));
+            vertex = vertexPattern.exec(body);
+        }
+        const indices = [];
+        const trianglePattern = /<triangle\b([^>]*)\/?>/g;
+        let triangle = trianglePattern.exec(body);
+        while (triangle !== null) {
+            const fields = attributes(triangle[1]);
+            const v1 = Number(fields.get('v1'));
+            const v2 = Number(fields.get('v2'));
+            const v3 = Number(fields.get('v3'));
+            const count = vertices.length / 3;
+            if (![v1, v2, v3].every((index) => Number.isInteger(index) && index >= 0 && index < count)) {
+                throw new DrftError(`3mf: object "${name}" has a triangle indexing ${v1}, ${v2}, ${v3} of ${count} vertices`);
+            }
+            indices.push(v1, v2, v3);
+            triangle = trianglePattern.exec(body);
+        }
+        if (vertices.length >= 9 && indices.length >= 3) {
+            const positions = Float32Array.from(vertices);
+            const indexArray = Uint32Array.from(indices);
+            const count = positions.length / 3;
+            meshes.push({
+                positions,
+                normals: deriveNormals(positions, indexArray),
+                colors: new Float32Array(count * 3).fill(1),
+                emissive: new Float32Array(count),
+                indices: indexArray,
+            });
+            const pid = objectFields.get('pid');
+            const pindex = Number(objectFields.get('pindex') ?? 0);
+            const palette = pid === undefined ? undefined : palettes.get(pid);
+            const chosen = palette?.[Number.isFinite(pindex) ? pindex : 0];
+            materials.push(chosen === undefined ? { ...DEFAULT_MATERIAL, name } : { ...chosen, name });
+        }
+        else if (vertices.length > 0 || indices.length > 0) {
+            warnings.push(`object "${name}" carries no usable geometry and was skipped`);
+        }
+        object = objectPattern.exec(xml);
+    }
+    if (meshes.length === 0)
+        throw new DrftError('3mf: the model carries no readable object');
+    return {
+        meshes,
+        materials,
+        warnings,
+        /*
+         * Stated, never applied. 3MF's specification fixes Z as up, which in a Y-up engine means
+         * every print lands on its side — so it is reported here and turned once, format
+         * agnostically, in `orient.ts`, exactly as the STL note and the FBX fix established.
+         */
+        declaredUp: '+z',
+        unitScale: unitScale ?? 1e-3,
+    };
+}
+/**
+ * Read a `.3mf` archive.
+ *
+ * The model part is named by the OPC relationships, and is `3D/3dmodel.model` in practice.
+ * Both are tried, the relationship first, because "in practice" is how a reader acquires a
+ * file it cannot open two years later.
+ */
+export function threeMfToMeshes(buffer, inflate) {
+    const entries = readZip(buffer, inflate);
+    const decoder = new TextDecoder();
+    const relationships = entries.find((entry) => entry.name.toLowerCase() === '_rels/.rels');
+    let target = null;
+    if (relationships !== undefined) {
+        const declared = /Target\s*=\s*"([^"]+)"/i.exec(decoder.decode(relationships.bytes))?.[1];
+        if (declared !== undefined)
+            target = declared.replace(/^\//, '').toLowerCase();
+    }
+    const model = (target === null ? undefined : entries.find((entry) => entry.name.toLowerCase() === target)) ??
+        entries.find((entry) => entry.name.toLowerCase().endsWith('.model'));
+    if (model === undefined) {
+        throw new DrftError(`3mf: the archive holds no .model part (it holds ${entries.map((entry) => entry.name).join(', ')})`);
+    }
+    return parseThreeMfModel(decoder.decode(model.bytes));
+}

package/dist/uploadBudget.d.ts

@@ -0,0 +1,82 @@
+/**
+ * How much uploading fits in one frame, and how to tell bytes from an error page.
+ *
+ * Pure decisions with no loader state behind them: whether another upload fits the frame's
+ * budget, and whether a server answered a request for a model with HTML.
+ */
+export declare const DEFAULT_UPLOADS_PER_FRAME = 3;
+export declare const DEFAULT_REVEAL_SEC = 0.35;
+/**
+ * How long one `update` may spend *starting* new stream work.
+ *
+ * A minority of a 60 Hz frame, and under the whole of a 120 Hz one, because the scene has to
+ * draw as well as load. It is a budget for beginning work rather than for finishing it: a piece
+ * already started is always finished, so a frame overruns by whatever the last piece cost — see
+ * `mayBeginMore` for why that residue is a real limit and not a rounding error.
+ */
+export declare const DEFAULT_UPLOAD_MS_PER_FRAME = 6;
+/**
+ * Whether another piece of stream work may begin in this frame.
+ *
+ * **The clock decides, because a count cannot.** `uploadsPerFrame` bounded the number of parts a
+ * frame took, on the reasoning in its own docstring: that a part is a small buffer upload and
+ * that the allocations are the cost. Measured through the demo page on the shipped Audi, that is
+ * backwards. `createMesh` costs 0.6 to 3.1 ms; the per-part CPU work around it costs 6 to 254 ms,
+ * most of it the consumer's `transform` plus the two further walks over the same vertices this
+ * class does itself. A count bounded the cheap term and left the expensive one free, so three
+ * large parts made one 318 ms frame.
+ *
+ * The loader cannot know what a part costs before it pays for it, and it does not have to: a
+ * clock read after each one is exact, needs no per-asset tuning, and is as right on a phone as on
+ * a workstation.
+ *
+ * **The first piece always begins.** One part of a heavy model can cost more than the entire
+ * budget, and a rule that asked only "is there room left" would then start nothing on any frame
+ * and the load would never finish. A hitch is worse than smooth; a load stuck at 40% is worse
+ * than a hitch.
+ *
+ * **`StepBudget` in `@driftengine/core` is the general form of this and is the one to reach for
+ * in new code.** It adds what this cannot do: an estimate of the worst stop, so it refuses to
+ * *begin* a unit there is no room to finish rather than discovering that afterwards, and a name
+ * for the unit that blew the budget. This one stays because the loader's update is a priority
+ * ladder rather than a queue of units — an outline, then parts, then one image, then a merge,
+ * each with its own reason to go before the next — and the numbers below were measured against
+ * that order.
+ *
+ * **What this does not fix, stated because measuring it is what found it.** A single part is
+ * indivisible here, and the worst one in that car costs 254 ms on an RX 9070 XT. This stops the
+ * others joining it in the same frame — the measured worst frame falls from 318 ms to 254 — and
+ * that is the whole of the improvement. Making that one part fit a frame is a different change
+ * to a different place: either its per-part work moves off the main thread, or a part large
+ * enough is split across frames. Neither is a budget, which is why neither is here.
+ *
+ * **The second of those now exists** as `createMeshIncremental`, and it is deliberately not
+ * wired up here: measured on that same car, `createMesh` is 0.6 to 3.1 ms of a part and the 254
+ * belongs to the per-part CPU work around it. Splitting the upload would divide the small half.
+ *
+ * @param begunThisFrame How many pieces this frame has already started.
+ * @param elapsedMs How long this frame has been spending on the stream.
+ * @param budgetMs What it is allowed.
+ */
+export declare function mayBeginMore(begunThisFrame: number, elapsedMs: number, budgetMs: number): boolean;
+/**
+ * Whether a response carrying 200 is actually a *document* rather than a container.
+ *
+ * `response.ok` is not enough to tell a missing model from a broken one, and the gap is not
+ * exotic: a dev server and most static hosts answer an unknown path with the site's own page
+ * under a 200 rather than with a 404. The bytes then reach the reader, the magic does not
+ * match, and a model that was simply never deployed is reported as a corrupt file.
+ *
+ * That is what this exists to prevent, and it was found on a published demo page: the site
+ * serves no model, its dev server answered `/car.drft` with 2,947 bytes of HTML under a 200,
+ * and the scene read **"the model failed: not a drft file"** at a reader. The deployed site
+ * was correct at the same moment, because it answers a real 404 — so the two disagreed, and
+ * the honest state was the one nobody could see locally.
+ *
+ * A declared content type is the right signal rather than sniffing the first bytes: a host
+ * answering with a page says so in the header, and it says so *before* a byte of body is
+ * read, which is what lets the caller skip downloading a page it has no use for. A genuinely
+ * corrupt container still reaches the reader and still fails loudly, which is the distinction
+ * worth keeping.
+ */
+export declare function isDocumentResponse(contentType: string | null): boolean;