@driftengine/assets 4.3.0 → 4.4.1

package/dist/gltf.js

@@ -173,10 +173,32 @@ function normalMatrix(m) {
  * textures may share one image with different samplers. Following the indirection here keeps
  * the material's index meaning what the file said it meant.
  */
+/**
+ * Which image a texture shows: glTF's `source` when there is one, otherwise an image-codec
+ * extension's.
+ *
+ * **The fallback wins when both exist**, because every reader can decode it and the baker
+ * identifies whatever bytes it gets. What that gives up is nothing a bake can use today: a WebP
+ * extension's image is smaller, but nothing here knows the two are the same picture. What would
+ * make it wrong is a baker that decodes AVIF, where the extension's image may be the better source.
+ *
+ * Basis is refused by name: it is a GPU transcoding format, and this engine uploads decoded images.
+ */
+function textureSource(texture, index, warnings) {
+    if (texture?.source !== undefined)
+        return texture.source;
+    const ext = texture?.extensions;
+    if (ext?.KHR_texture_basisu !== undefined) {
+        warnings.push(`texture ${index} is KHR_texture_basisu, which this reader does not transcode; export ` +
+            'the model with PNG, JPEG or WebP images');
+        return undefined;
+    }
+    return ext?.EXT_texture_webp?.source ?? ext?.EXT_texture_avif?.source;
+}
 function readImages(doc, buffers, warnings) {
     const out = [];
     for (let i = 0; i < (doc.textures ?? []).length; i++) {
-        const source = doc.textures?.[i]?.source;
+        const source = textureSource(doc.textures?.[i], i, warnings);
         const image = source === undefined ? undefined : doc.images?.[source];
         if (image === undefined) {
             warnings.push(`texture ${i} names no image this reader can find; it will draw untextured`);
@@ -385,6 +407,17 @@ function materialOf(material) {
     const modulated = ormMap >= 0;
     const metallic = modulated ? 0 : (pbr?.metallicFactor ?? 1);
     const roughness = modulated ? DEFAULT_ROUGHNESS : (pbr?.roughnessFactor ?? 1);
+    /*
+     * **The same trap reached by the other door: a metal whose colour is an image.** `specular` is
+     * this engine's dielectric highlight and it is white, which is a metal's highlight only where the
+     * metal is white. Where the base colour is a texture that colour is per texel, the lane cannot
+     * say it, and the factor alone blew a dirt decal to white: its file names no metallic and no
+     * roughness, so the specification reads a rough metal of dark grime, and every wall it covered
+     * drew white under a low sun with the grime dark between. So the lane keeps the dielectric's
+     * zero there. What it gives up is the sun's glint on a textured metal with no map, which then
+     * shades as the grime or the paint its image says; what would change it is a metallic lane.
+     */
+    const highlight = pbr?.baseColorTexture === undefined ? metallic : 0;
     /*
      * **glTF leaves `metallicRoughnessTexture`'s R channel undefined.** The specification assigns G
      * to roughness and B to metallic and says nothing at all about R, so occlusion lives there only
@@ -402,13 +435,21 @@ function materialOf(material) {
     return {
         name: material?.name ?? '',
         color: [base[0] ?? 1, base[1] ?? 1, base[2] ?? 1],
-        specular: metallic,
+        specular: highlight,
         roughness,
         emissive,
         emissiveColor: emissive > 0
             ? [emissiveFactor[0] ?? 0, emissiveFactor[1] ?? 0, emissiveFactor[2] ?? 0]
             : [-1, -1, -1],
         opacity: blends ? Math.min(1, Math.max(0, base[3] ?? 1)) : 1,
+        /*
+         * glTF's `BLEND` says alpha is the factor *times the texture*. With a factor of 1 `opacity` alone
+         * cannot say the material blends, and a leaf whose shape is all in its texture's alpha drew as a
+         * solid card. So it is said.
+         */
+        blend: blends,
+        /* Seen from both faces: a curtain, a leaf card. The specification's default is one face. */
+        doubleSided: material?.doubleSided === true,
         /* Only in MASK mode: the specification says `alphaCutoff` has no meaning in the other two. */
         cutout: masked ? Math.min(1, Math.max(0, material?.alphaCutoff ?? 0.5)) : 0,
         /* Metalness is glTF's statement about reflection: a metal mirrors its surroundings and
@@ -424,6 +465,13 @@ function materialOf(material) {
         albedo: pbr?.baseColorTexture?.index ?? -1,
     };
 }
+/** The required extensions this reader implements, or follows far enough to fail loudly. */
+const KNOWN_REQUIRED = new Set([
+    'KHR_materials_pbrSpecularGlossiness',
+    'EXT_texture_webp',
+    'EXT_texture_avif',
+    'KHR_lights_punctual',
+]);
 /**
  * Turn a document into meshes in world space, one per primitive.
  *
@@ -441,6 +489,15 @@ export function gltfToMeshes(doc, buffers, options) {
     /* One per labelled material, by the ordinal `materials` is about to give it. */
     const substances = [];
     const warnings = [];
+    /*
+     * A required extension is the file saying it cannot be read correctly without it. One this
+     * reader does not know is said by name, rather than drawing whatever falls out.
+     */
+    for (const name of doc.extensionsRequired ?? []) {
+        if (!KNOWN_REQUIRED.has(name)) {
+            warnings.push(`the file requires ${name}, which this reader does not implement`);
+        }
+    }
     const textures = readImages(doc, buffers, warnings);
     /*
      * Said once per material rather than once per primitive that uses it.
@@ -481,6 +538,9 @@ export function gltfToMeshes(doc, buffers, options) {
      * traversal.
      */
     const nodes = [];
+    /* The lights, placed by the same world matrix the walk computes for the geometry. */
+    const lights = [];
+    const punctual = doc.extensions?.KHR_lights_punctual?.lights ?? [];
     const walk = (nodeIndex, parent, parentNode) => {
         if (seen.has(nodeIndex)) {
             // A cycle would otherwise recurse until the stack gave out, with no useful message.
@@ -491,6 +551,20 @@ export function gltfToMeshes(doc, buffers, options) {
         if (node === undefined)
             throw new DrftError(`gltf: a scene names node ${nodeIndex}, which is absent`);
         const world = multiply(parent, localMatrix(node));
+        const hung = node.extensions?.KHR_lights_punctual?.light;
+        if (hung !== undefined) {
+            const light = punctual[hung];
+            if (light === undefined) {
+                warnings.push(`node ${nodeIndex} names light ${hung}, and the file has ${punctual.length}`);
+            }
+            else {
+                const placed = placeLight(light, world, node.name ?? light.name ?? '');
+                if (placed === null)
+                    warnings.push(`light ${hung}: a type "${light.type}" is not a punctual light`);
+                else
+                    lights.push(placed);
+            }
+        }
         const entry = nodes.length;
         nodes.push({
             parent: parentNode,
@@ -571,9 +645,34 @@ export function gltfToMeshes(doc, buffers, options) {
         materials,
         textures,
         nodes,
+        lights,
         ...(substances.length === 0 ? {} : { substances }),
     };
 }
+/**
+ * One punctual light where its node puts it: the node's origin, and its local −z for the way it
+ * points, both through the world matrix. The extension's defaults stand where the file is silent.
+ */
+function placeLight(light, world, name) {
+    const kind = light.type;
+    if (kind !== 'point' && kind !== 'spot' && kind !== 'directional')
+        return null;
+    const dx = -(world[8] ?? 0);
+    const dy = -(world[9] ?? 0);
+    const dz = -(world[10] ?? 1);
+    const length = Math.hypot(dx, dy, dz) || 1;
+    return {
+        kind,
+        name,
+        position: [world[12] ?? 0, world[13] ?? 0, world[14] ?? 0],
+        direction: [dx / length, dy / length, dz / length],
+        color: [light.color?.[0] ?? 1, light.color?.[1] ?? 1, light.color?.[2] ?? 1],
+        intensity: light.intensity ?? 1,
+        range: light.range ?? 0,
+        innerConeRad: light.spot?.innerConeAngle ?? 0,
+        outerConeRad: light.spot?.outerConeAngle ?? Math.PI / 4,
+    };
+}
 function buildPrimitive(doc, buffers, primitive, world, label, warnings, 
 /** The skin this primitive is deformed by, or undefined for static geometry. */
 skin, 

package/dist/index.d.ts

@@ -7,11 +7,13 @@
  * world imports none of this and pays for none of it.
  */
 export { DrftLoader } from './drftLoader.ts';
+export { writePartMaterial } from './partMaterial.ts';
 export { dtexTileBytes, tileGridFromDtex } from './dtexTiles.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 type { DrftFieldPlacement } from './fieldPlacement.ts';
 export { TextureSet, textureColorSpaces } from './drftTextures.ts';
 export { assetCandidates, basenameOf } from './assetPath.ts';
 export { describeImage } from './imageInfo.ts';
@@ -49,10 +51,15 @@ 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 { simplifyMesh } from './bake/simplify.ts';
+export type { SimplifyOptions } from './bake/simplify.ts';
+export { componentCount, findRepeats } from './repeats.ts';
+export type { Repeats } from './repeats.ts';
 export { deriveTangentsFor } from './tangentOrder.ts';
+export { cappedSize, downscaleRgba } from './downscale.ts';
 export { buildCoarseLevel, isOutlineWorthWriting, DEFAULT_COARSE_CELLS } from './coarseLevel.ts';
 export type { CoarseLevelOptions } from './coarseLevel.ts';
-export { orientMeshes, parseUpAxis, describeUpAxis } from './orient.ts';
+export { orientMeshes, orientTransforms, orientLights, parseUpAxis, describeUpAxis, } from './orient.ts';
 export type { UpAxis } from './orient.ts';
 export { readGltfSkins } from './gltfSkin.ts';
 export type { GltfAnimated, GltfSkin } from './gltfSkin.ts';
@@ -70,6 +77,7 @@ export type { ClusterOptions, ClusterSet } from './bake/cluster.ts';
 export { buildClusterDag } from './bake/clusterLod.ts';
 export type { ClusterDag, ClusterLevel } from './bake/clusterLod.ts';
 export { bakeObjectSdf } from './bake/sdf.ts';
+export { bakeSceneField } from './bake/sceneField.ts';
 export { IMPOSTOR_GUTTER, IMPOSTOR_TILE, PROXY_BASE_CELLS, PROXY_MIN_CELLS, buildImpostor, buildProxy, frameOf, octahedralCoord, octahedralDirection, proxyResolution, rasteriseView, sampleImpostor, } from './bake/hlod.ts';
 export type { Impostor, ProxyCell, ViewFrame } from './bake/hlod.ts';
 export type { ObjectSdf } from './bake/sdf.ts';

package/dist/index.js

@@ -12,6 +12,11 @@
  * consumer writes the words, because what to call a stage is a decision about an audience.
  */
 export { DrftLoader } from './drftLoader.js';
+/*
+ * A part's whole material in the renderer's shape, so a consumer drawing parts cannot copy half of
+ * it: a copy that left out the occlusion strength drew a bought model black.
+ */
+export { writePartMaterial } from './partMaterial.js';
 /*
  * **A `DTEX` chunk's tile table as the grid residency asks about.** The other constructor of a
  * `MaterialTileGrid` — `latentTileGrid` cuts one from a latent a baker holds, and this reads one a
@@ -81,11 +86,19 @@ export { browserInflate, browserInflateRaw, prepareFbxInflate, prepareZipInflate
  * on a real asset is roughly six times more than the model has.
  */
 export { weldMesh, dropDefaultAttributes } from './weld.js';
+export { simplifyMesh } from './bake/simplify.js';
+/*
+ * Copies an export merged into one mesh, found again as a prototype and a placement each. The
+ * baker writes them as `INST`; see `repeats.ts` for how strict a copy has to be to count.
+ */
+export { componentCount, findRepeats } from './repeats.js';
 /*
  * The frame is derived after the weld and not inside a reader, for the reason `tangentOrder.ts`
  * measures: a soup carrying a frame per corner has nothing left to merge.
  */
 export { deriveTangentsFor } from './tangentOrder.js';
+/* A decoded image shrunk to a texture cap, which is what the baker's `--max-texture` runs. */
+export { cappedSize, downscaleRgba } from './downscale.js';
 /*
  * One coarse mesh standing in for a whole asset, so a load can open on an outline rather than on
  * nothing. Baked, because a coarse model has to exist as geometry before it can be drawn, and
@@ -97,7 +110,7 @@ export { buildCoarseLevel, isOutlineWorthWriting, DEFAULT_COARSE_CELLS } from '.
  * than guessed: every rule for measuring it from the geometry is wrong on something ordinary,
  * and guessing is what put a car upside down and reported it as verified.
  */
-export { orientMeshes, parseUpAxis, describeUpAxis } from './orient.js';
+export { orientMeshes, orientTransforms, orientLights, parseUpAxis, describeUpAxis, } from './orient.js';
 /* Skins and clips out of a glTF document. See the module for why it is not part of `gltf.ts`. */
 export { readGltfSkins } from './gltfSkin.js';
 /*
@@ -165,6 +178,7 @@ export { buildClusterDag } from './bake/clusterLod.js';
  * carries, and a field a consumer cannot bake is a pipeline with no input.
  */
 export { bakeObjectSdf } from './bake/sdf.js';
+export { bakeSceneField } from './bake/sceneField.js';
 /*
  * **The third time, and the one that got furthest before anybody noticed.** `bake/hlod.ts` builds
  * the proxies and impostors `docs/CAPABILITIES.md` lists as shipping, it is tested, it is sized and

package/dist/loadProgress.d.ts

@@ -1,4 +1,4 @@
-import type { MeshHandle } from '@driftengine/core';
+import type { MeshHandle, InstancedHandle, MeshInstances } from '@driftengine/core';
 /**
  * The vocabulary of a load in flight: which phase it is in, how far it has got, and what a
  * finished part is.
@@ -60,6 +60,11 @@ export interface DrftLoadProgress {
     readonly message: string;
 }
 /** One drawable piece of a loaded model. */
+/** A part's copies: the instanced batch over its mesh, and the placements already uploaded to it. */
+export interface DrftPartInstances {
+    readonly batch: InstancedHandle;
+    readonly data: MeshInstances;
+}
 export interface DrftPart {
     readonly mesh: MeshHandle;
     /** Which of the asset's images this surface wears, or -1 for none. */
@@ -108,6 +113,22 @@ export interface DrftPart {
      * nothing at all.
      */
     readonly cutout: number;
+    /**
+     * Whether the part blends: its texture's alpha is coverage, so it is drawn translucent whatever its
+     * `opacity` says. glTF's `BLEND` with a factor of 1 is the case: a leaf's shape is in its alpha.
+     */
+    readonly blend: boolean;
+    /** Whether both faces are seen: glTF's `doubleSided`. Drawn without culling, each face lit as the front. */
+    readonly doubleSided: boolean;
+    /**
+     * The copies this part is drawn as, or null for a part drawn once.
+     *
+     * A mesh the file places many times (`INST`, 1.18) is uploaded once and drawn through the
+     * engine's instanced path: `drawInstanced(batch, data)`, and `sink.instanced` for a shadow. The
+     * placements are uploaded when the part is made and carry the fit, so a caller passes them as
+     * they are. Null for every part of a file with no instances, which is every file before 1.18.
+     */
+    readonly instances: DrftPartInstances | null;
     /**
      * 0 to 1 as this part arrives, for a caller that would rather it faded in than appeared.
      *

package/dist/orient.d.ts

@@ -25,7 +25,7 @@
  * is still the winding the rasteriser wants, and the index buffers are passed through
  * untouched.
  */
-import type { DrftNode, MeshData } from '@driftengine/drft';
+import type { DrftLight, DrftNode, MeshData } from '@driftengine/drft';
 /** Which way is up in the asset, as a signed axis of the engine's own frame. */
 export type UpAxis = '+x' | '-x' | '+y' | '-y' | '+z' | '-z';
 export declare const UP_AXES: readonly UpAxis[];
@@ -41,6 +41,14 @@ export declare function describeUpAxis(up: UpAxis): string;
  * no scale here by construction, which is the other half of why.
  */
 export declare function orientMeshes(meshes: readonly MeshData[], assetUp: UpAxis): MeshData[];
+/**
+ * Column-major 4×4 placements, turned into the engine's frame: `O · M · Oᵀ` for each, with `O` the
+ * same turn `orientMeshes` gives the geometry. A copy the file moved along its own +z is then moved
+ * along the engine's +y, and a placement that was a rotation stays one of the same angle.
+ */
+export declare function orientTransforms(transforms: Float32Array, assetUp: UpAxis): Float32Array;
+/** Authored lights, turned into the engine's frame by the turn `orientMeshes` gives the geometry. */
+export declare function orientLights(lights: readonly DrftLight[], assetUp: UpAxis): DrftLight[];
 /**
  * Which way round a format's coordinate system is.
  *

package/dist/orient.js

@@ -61,7 +61,11 @@ export function parseUpAxis(text) {
 export function describeUpAxis(up) {
     return TURNS[up].says;
 }
-function turnTriples(source, m) {
+/**
+ * Turn the first three of every `stride` values, and copy the rest. Three for a position or a
+ * normal; four for a tangent, whose fourth is the bitangent's handedness and is not a direction.
+ */
+function turnTriples(source, m, stride = 3) {
     const out = new Float32Array(source.length);
     const m0 = m[0];
     const m1 = m[1];
@@ -72,13 +76,15 @@ function turnTriples(source, m) {
     const m6 = m[6];
     const m7 = m[7];
     const m8 = m[8];
-    for (let i = 0; i + 2 < source.length; i += 3) {
+    for (let i = 0; i + 2 < source.length; i += stride) {
         const x = source[i];
         const y = source[i + 1];
         const z = source[i + 2];
         out[i] = m0 * x + m1 * y + m2 * z;
         out[i + 1] = m3 * x + m4 * y + m5 * z;
         out[i + 2] = m6 * x + m7 * y + m8 * z;
+        for (let k = 3; k < stride; k++)
+            out[i + k] = source[i + k];
     }
     return out;
 }
@@ -95,6 +101,58 @@ export function orientMeshes(meshes, assetUp) {
         ...mesh,
         positions: turnTriples(mesh.positions, m),
         normals: turnTriples(mesh.normals, m),
+        /*
+         * **The tangent frame turns with the normals**, and it did not until 2026-09-25: the baker
+         * derives tangents before it orients, so a normal-mapped model baked with `--up` kept its
+         * tangents in the file's axes and lit its normal maps from the wrong side.
+         */
+        ...(mesh.tangents === undefined ? {} : { tangents: turnTriples(mesh.tangents, m, 4) }),
+    }));
+}
+/**
+ * Column-major 4×4 placements, turned into the engine's frame: `O · M · Oᵀ` for each, with `O` the
+ * same turn `orientMeshes` gives the geometry. A copy the file moved along its own +z is then moved
+ * along the engine's +y, and a placement that was a rotation stays one of the same angle.
+ */
+export function orientTransforms(transforms, assetUp) {
+    const o = TURNS[assetUp].m;
+    const out = new Float32Array(transforms.length);
+    for (let at = 0; at + 15 < transforms.length; at += 16) {
+        /* Row-major 3×3 of the placement, read out of its column-major block. */
+        for (let r = 0; r < 3; r++) {
+            for (let c = 0; c < 3; c++) {
+                let sum = 0;
+                for (let i = 0; i < 3; i++) {
+                    for (let j = 0; j < 3; j++) {
+                        /* (O M Oᵀ)[r][c] = Σ O[r][i] M[i][j] O[c][j] */
+                        sum +=
+                            o[r * 3 + i] *
+                                transforms[at + j * 4 + i] *
+                                o[c * 3 + j];
+                    }
+                }
+                out[at + c * 4 + r] = sum;
+            }
+            let t = 0;
+            for (let i = 0; i < 3; i++)
+                t += o[r * 3 + i] * transforms[at + 12 + i];
+            out[at + 12 + r] = t;
+        }
+        out[at + 15] = 1;
+    }
+    return out;
+}
+/** Authored lights, turned into the engine's frame by the turn `orientMeshes` gives the geometry. */
+export function orientLights(lights, assetUp) {
+    const { m } = TURNS[assetUp];
+    const turn = (v) => {
+        const t = turnTriples(new Float32Array(v), m);
+        return [t[0], t[1], t[2]];
+    };
+    return lights.map((light) => ({
+        ...light,
+        position: turn(light.position),
+        direction: turn(light.direction),
     }));
 }
 /**

package/dist/partMaterial.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A loaded part's material, written into the shape the renderer's `setMaterial` takes.
+ *
+ * **Every field or none**, because a partial copy fails in the one way nobody notices: silently and
+ * dark. `SurfaceMaterial` defaults `occlusionStrength` to 1, which is right for a caller who binds
+ * an ORM map and says nothing. A glTF material with no occlusion texture is carried as 0, and glTF
+ * lets its ORM map's red channel be anything — zero, in a bought scene measured here. A consumer
+ * who copied the maps and not the strength drew every surface multiplied by that zero. This is the
+ * one place the correspondence is written, so a field added to one side has one place to arrive.
+ *
+ * Writes into a caller-owned object and allocates nothing, so a scene rewrites one material per
+ * part in its frame loop. Opacity and reflectivity are not written: the first is a choice of draw
+ * call and the second a separate setter, and both stay the caller's to apply.
+ */
+import type { SurfaceMaterial, SurfaceTextureHandle } from '@driftengine/core';
+import type { TextureSet } from './drftTextures.ts';
+import type { DrftPart } from './loadProgress.ts';
+/** `part`'s maps and factors into `out`, resolving each map through `textures`. */
+export declare function writePartMaterial(part: DrftPart, textures: TextureSet<SurfaceTextureHandle> | null, out: SurfaceMaterial<SurfaceTextureHandle>): SurfaceMaterial<SurfaceTextureHandle>;

package/dist/partMaterial.js

@@ -0,0 +1,16 @@
+function at(textures, index) {
+    return index >= 0 ? (textures?.at(index) ?? null) : null;
+}
+/** `part`'s maps and factors into `out`, resolving each map through `textures`. */
+export function writePartMaterial(part, textures, out) {
+    out.albedo = at(textures, part.albedo);
+    out.orm = at(textures, part.orm);
+    out.normal = at(textures, part.normal);
+    out.emissive = at(textures, part.emissive);
+    out.roughnessScale = part.roughnessScale;
+    out.metallicScale = part.metallicScale;
+    out.occlusionStrength = part.occlusionStrength;
+    out.cutout = part.cutout;
+    out.doubleSided = part.doubleSided;
+    return out;
+}

package/dist/readModel.d.ts

@@ -21,7 +21,7 @@
  * decision, and `demo/showroom.ts` runs it in a worker.
  */
 import type { MeshData } from '@driftengine/drft';
-import type { AnimationClip, DrftMaterial, DrftNode, DrftSkin } from '@driftengine/drft';
+import type { AnimationClip, DrftLight, DrftMaterial, DrftNode, DrftSkin } from '@driftengine/drft';
 import type { AssetReference } from './assetPath.ts';
 import type { Handedness, UpAxis } from './orient.ts';
 import type { Inflate } from './fbx.ts';
@@ -124,6 +124,8 @@ export interface ModelImport {
      * reads it calls `localiseNodes` to get parts it can turn.
      */
     nodes?: readonly DrftNode[];
+    /** The lights the file was authored with, in world space. glTF carries them; nothing else here. */
+    lights?: readonly DrftLight[];
     /** Which way round the source's coordinate system was. `orient.ts` is what acts on it. */
     declaredHand?: Handedness;
 }

package/dist/repeats.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copies merged into one mesh, found again: a prototype and a rigid placement for each copy.
+ *
+ * **What an export does to repeated objects, undone.** A modelling tool that flattens a scene writes
+ * N copies of an object as one mesh: N runs of the same triangles, one after another, each run's
+ * vertices in the same order, each run moved. A bought scene measured here shipped ten thousand
+ * candles that way — nineteen million triangles for one candle's worth of shape. Finding the runs
+ * turns that back into one mesh and ten thousand matrices.
+ *
+ * **Strict, and the strictness is the design.** A count N is accepted only when:
+ * - the triangle and vertex counts both divide by N;
+ * - every run's indices are run 0's, offset by a whole run of vertices;
+ * - every run is a rigid transform of run 0 within a tolerance tied to the run's own size, with its
+ *   normals and tangents turned by the same rotation;
+ * - every other attribute is exactly equal.
+ *
+ * One vertex out refuses the count. What that gives up is copies a tool reordered or re-triangulated,
+ * which this cannot see. What would make that wrong is a scene where such copies dominate; finding
+ * them needs shape matching, not run matching.
+ *
+ * **Rigid only.** A scaled copy is refused rather than instanced with a scale, because a scale
+ * changes what the normals mean and nothing downstream is asked to renormalise them. Skinned and
+ * morphed meshes are refused outright: their copies are not placements of one shape.
+ */
+import type { MeshData } from '@driftengine/drft';
+export interface Repeats {
+    /** Run 0: one copy's geometry, with its own indices from zero. */
+    readonly prototype: MeshData;
+    readonly count: number;
+    /** One column-major 4×4 matrix a copy, taking the prototype to where that copy was. Copy 0 is identity. */
+    readonly transforms: Float32Array;
+}
+/** How many connected pieces the indices make of the mesh. Unreferenced vertices count as their own. */
+export declare function componentCount(mesh: MeshData): number;
+/**
+ * The prototype and placements for the largest candidate count that `mesh` is exactly that many
+ * rigid copies of, or null when none is.
+ */
+export declare function findRepeats(mesh: MeshData, candidates: readonly number[]): Repeats | null;