lecodes-assets 0.2.1 → 2.5.0

package/src/doctor/merge/index.ts

@@ -0,0 +1,98 @@
+// Mesh merging + texture atlasing (`lecodes assets doctor --merge`): fewer draw calls per model.
+//
+// A modular character arrives as a dozen parts — head, hands, shirt, pants, boots, vest, helmet,
+// pouches — each its own mesh node, its own skin (a subset of the joints) and its own material with
+// its own base / normal / ORM maps. The renderer draws one primitive per material, so the character
+// costs 16 draw calls and 45 texture binds; a squad of twelve is 200 draw calls of characters alone.
+// This pass folds all of it into ONE primitive over ONE material per compatibility class:
+//
+//   • every primitive is classified — SKINNED (on a skin), RIGID (a static mesh sitting under a joint:
+//     a hat, a strap, a holstered weapon — it is skinned to that joint with weight 1), STATIC (a plain
+//     node: its world transform is baked into the vertices); anything animated by a node channel, with
+//     morph targets, or excluded by name is left alone (reported);
+//   • primitives are grouped by what the material pipeline cannot mix in one draw: alpha mode (+ cutoff),
+//     double-sidedness, unlit; a material carrying an extension this pass does not understand, or a
+//     KHR_texture_transform, or UVs that tile the texture too far, forms a group of its own (its geometry
+//     still merges with its siblings, its textures are kept as they are);
+//   • one union SKIN per skinned group: joints in tree order, the inverse bind matrices from the skin that
+//     has most of them; a part bound in another bind space (each of its inverse bind matrices differs from
+//     the canonical one by the same rigid transform) is moved into the canonical space; a part whose joints
+//     disagree by different transforms is skipped;
+//   • one ATLAS per map kind (base colour, normal, packed occlusion-roughness-metallic, emissive) per group:
+//     every material gets a tile sized like its largest map (materials with the same maps and factors share
+//     a tile), the tiles are shelf-packed into the smallest power-of-two square that holds them at full
+//     resolution, or scaled down to fit `--atlas-size` (default 2048) BY SURFACE AREA: each material's area
+//     on the model (its triangles in bind / world space) and its UV coverage give the texel density its tile
+//     would have, and the tiles are sized so every part lands at the same texels-per-metre — a torso keeps
+//     its map, a strap or a buckle gets the small tile it needs, never past a map's native size
+//     (`--atlas-uniform` = the plain rule instead: every tile at the same fraction); each tile is padded by
+//     `--atlas-pad` texels of edge replication (bilinear + the first mips stay clean); the material's
+//     FACTORS are baked into its tile (base colour factor in linear light, roughness / metallic into the
+//     ORM channels, normal scale, emissive factor, occlusion strength), so the merged material is factor-
+//     free and reads the same as the parts did; UVs are remapped into the tile; a material without a map
+//     gets a flat tile of its factor;
+//   • the merged primitive carries the union of the parts' attributes (positions, normals — computed for a
+//     part without any —, UVs, colours, joints / weights; tangents only when every part has them, a
+//     lightmap UV set only when every part has one), the old meshes, skins, materials, textures and empty
+//     part nodes are gone, and the new node is named `merged` (`merged.blend`, `merged.mask`, `merged.2side`,
+//     `merged.<material>` for the further classes).
+//
+// The pass runs BEFORE the texture passes: the atlases are written as PNG and picked up by `--ktx2` /
+// the size cap like any other texture — except that an atlas is capped by `--atlas-size`, not
+// `--max-size` (the per-part cap): a kit whose 15 maps were capped at 1024 each is one 4096² map now.
+// KTX2 source textures are decoded through KTX-Software's `ktx extract` (next to toktx); without the
+// tool a group holding KTX2 maps is reported and skipped.
+import type { Document, Material, Mesh, Node } from '@gltf-transform/core'
+import { buildAtlas } from './atlasPixels'
+import { mergeGroup } from './geometry'
+import type { AtlasLayout, MergePlan, MergeResult, Tile } from './types'
+
+export { planMerge } from './plan'
+export { findKtxTool } from './textures'
+export { DEFAULT_ATLAS_PAD, DEFAULT_ATLAS_SIZE } from './types'
+export type { AtlasLayout, MergeGroupPlan, MergeOptions, MergePlan, MergeResult, MergeSkipped } from './types'
+
+/** Drop what the merge replaced: the parts' primitives, meshes, skins, nodes (when empty), unused materials / textures / accessors. */
+function cleanup(doc: Document, plan: MergePlan, mergedNodes: Set<Node>): void {
+  const root = doc.getRoot()
+  const animated = new Set<Node>()
+  for (const a of root.listAnimations()) for (const c of a.listChannels()) { const n = c.getTargetNode(); if (n) animated.add(n) }
+  const joints = new Set<Node>(root.listSkins().flatMap((s) => s.listJoints()))
+  const meshes = new Set<Mesh>()
+  const nodes = new Set<Node>()
+  for (const g of plan.groups) for (const s of g.sources) { s.prim.dispose(); meshes.add(s.mesh); nodes.add(s.node) }
+  for (const m of meshes) if (!m.listPrimitives().length) m.dispose()
+  for (const n of nodes) {
+    if (mergedNodes.has(n) || n.getMesh() || joints.has(n) || animated.has(n)) continue
+    if (n.listChildren().length) continue
+    n.setSkin(null)
+    n.dispose()
+  }
+  for (const s of root.listSkins()) if (!s.listParents().some((p) => p.propertyType === 'Node')) s.dispose()
+  for (const m of root.listMaterials()) if (!m.listParents().some((p) => p.propertyType === 'Primitive')) m.dispose()
+  for (const t of root.listTextures()) if (!t.listParents().some((p) => p.propertyType !== 'Root')) t.dispose()
+  for (const a of root.listAccessors()) if (a.listParents().every((p) => p === root)) a.dispose()
+}
+
+/** "tiles at 40%" / "tiles 12–100% by area" — nothing when every tile is native. */
+export const describeScale = (a: AtlasLayout): string =>
+  a.scaleMax >= 0.999 && a.scale >= 0.999 ? '' : a.byArea && a.scaleMax - a.scale > 0.005 ? ` (tiles ${(a.scale * 100).toFixed(0)}–${(a.scaleMax * 100).toFixed(0)}% by area)` : ` (tiles at ${(a.scale * 100).toFixed(0)}%)`
+
+/** Apply the plan (mutates). The atlas textures come back as PNG for the caller's texture passes. */
+export async function applyMerge(doc: Document, plan: MergePlan): Promise<MergeResult> {
+  const res: MergeResult = { groups: [], skipped: plan.skipped, textures: [], primitivesBefore: plan.primitivesBefore, primitivesAfter: plan.primitivesAfter }
+  const mergedNodes = new Set<Node>()
+  for (const g of plan.groups) {
+    let material: Material | null = null, tileOf: Map<Material, Tile> | null = null
+    if (g.atlas) {
+      const built = await buildAtlas(doc, g, plan.ktxTool)
+      material = built.material; tileOf = built.tileOf
+      res.textures.push(...built.textures)
+    }
+    const r = mergeGroup(doc, g, tileOf, g.atlas, material)
+    mergedNodes.add(r.node)
+    res.groups.push({ label: g.label, primitives: g.sources.length, materials: g.materials.length, vertices: r.vertices, triangles: r.triangles, joints: g.joints, atlas: g.atlas ? `${g.atlas.size}² ${g.atlas.maps.join('+')}${describeScale(g.atlas)}` : null })
+  }
+  cleanup(doc, plan, mergedNodes)
+  return res
+}

package/src/doctor/merge/matrix.ts

@@ -0,0 +1,60 @@
+// A small matrix kit (column-major, like glTF).
+
+import type { Node } from '@gltf-transform/core'
+import type { Mat4 } from './types'
+
+export const I4: Mat4 = [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ]
+export const mul = (a: Mat4, b: Mat4): Mat4 => {
+  const o = new Array<number>(16).fill(0)
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) o[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3]
+  return o
+}
+export const invert = (m: Mat4): Mat4 | null => {
+  const [ a00, a01, a02, a03, a10, a11, a12, a13, a20, a21, a22, a23, a30, a31, a32, a33 ] = m
+  const b00 = a00 * a11 - a01 * a10, b01 = a00 * a12 - a02 * a10, b02 = a00 * a13 - a03 * a10, b03 = a01 * a12 - a02 * a11
+  const b04 = a01 * a13 - a03 * a11, b05 = a02 * a13 - a03 * a12, b06 = a20 * a31 - a21 * a30, b07 = a20 * a32 - a22 * a30
+  const b08 = a20 * a33 - a23 * a30, b09 = a21 * a32 - a22 * a31, b10 = a21 * a33 - a23 * a31, b11 = a22 * a33 - a23 * a32
+  let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06
+  if (Math.abs(det) < 1e-30) return null
+  det = 1 / det
+  return [
+    (a11 * b11 - a12 * b10 + a13 * b09) * det, (a02 * b10 - a01 * b11 - a03 * b09) * det, (a31 * b05 - a32 * b04 + a33 * b03) * det, (a22 * b04 - a21 * b05 - a23 * b03) * det,
+    (a12 * b08 - a10 * b11 - a13 * b07) * det, (a00 * b11 - a02 * b08 + a03 * b07) * det, (a32 * b02 - a30 * b05 - a33 * b01) * det, (a20 * b05 - a22 * b02 + a23 * b01) * det,
+    (a10 * b10 - a11 * b08 + a13 * b06) * det, (a01 * b08 - a00 * b10 - a03 * b06) * det, (a30 * b04 - a31 * b02 + a33 * b00) * det, (a21 * b02 - a20 * b04 - a23 * b00) * det,
+    (a11 * b07 - a10 * b09 - a12 * b06) * det, (a00 * b09 - a01 * b07 + a02 * b06) * det, (a31 * b01 - a30 * b03 - a32 * b00) * det, (a20 * b03 - a21 * b01 + a22 * b00) * det,
+  ]
+}
+export const isIdentity = (m: Mat4, tol = 1e-5): boolean => m.every((v, i) => Math.abs(v - I4[i]) < tol)
+export const same = (a: Mat4, b: Mat4, tol: number): boolean => a.every((v, i) => Math.abs(v - b[i]) <= tol * Math.max(1, Math.abs(v), Math.abs(b[i])))
+export const det3 = (m: Mat4): number => m[0] * (m[5] * m[10] - m[6] * m[9]) - m[4] * (m[1] * m[10] - m[2] * m[9]) + m[8] * (m[1] * m[6] - m[2] * m[5])
+/** Inverse-transpose of the upper 3×3, as a column-major 3×3 (`dir` applies it). */
+export const normalMatrix = (m: Mat4): number[] => {
+  const a = m[0], b = m[4], c = m[8], d = m[1], e = m[5], f = m[9], g = m[2], h = m[6], i = m[10]
+  const det = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g)
+  if (Math.abs(det) < 1e-20) return [ 1, 0, 0, 0, 1, 0, 0, 0, 1 ]
+  // inverse (row-major rows), then transposed = columns of the inverse become rows
+  const inv = [
+    (e * i - f * h) / det, (c * h - b * i) / det, (b * f - c * e) / det,
+    (f * g - d * i) / det, (a * i - c * g) / det, (c * d - a * f) / det,
+    (d * h - e * g) / det, (b * g - a * h) / det, (a * e - b * d) / det,
+  ]
+  // n' = inv^T · n → n'[r] = Σ_c inv[c*3 + r] · n[c]; stored column-major: col c = inv row c
+  return [ inv[0], inv[1], inv[2], inv[3], inv[4], inv[5], inv[6], inv[7], inv[8] ]
+}
+export const point = (m: Mat4, p: number[]): number[] => [
+  m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12], m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13], m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14],
+]
+export const dir = (n3: number[], v: number[]): number[] => {
+  const x = n3[0] * v[0] + n3[3] * v[1] + n3[6] * v[2], y = n3[1] * v[0] + n3[4] * v[1] + n3[7] * v[2], z = n3[2] * v[0] + n3[5] * v[1] + n3[8] * v[2]
+  const l = Math.hypot(x, y, z) || 1
+  return [ x / l, y / l, z / l ]
+}
+export const localMatrix = (n: Node): Mat4 => Array.from(n.getMatrix() as unknown as ArrayLike<number>)
+export const worldMatrix = (n: Node, cache = new Map<Node, Mat4>()): Mat4 => {
+  const hit = cache.get(n)
+  if (hit) return hit
+  const parent = n.getParentNode()
+  const w = parent ? mul(worldMatrix(parent, cache), localMatrix(n)) : localMatrix(n)
+  cache.set(n, w)
+  return w
+}

package/src/doctor/merge/plan.ts

@@ -0,0 +1,88 @@
+// The plan: classify, group by what one draw cannot mix, check the skins can be unified, lay the atlases out.
+
+import type { Document, Material, Node, Texture } from '@gltf-transform/core'
+import { planAtlas } from './atlasLayout'
+import { bySize, canonicalBinds } from './bindSpace'
+import { classify, classSuffix, materialInfo, measureSurface, type MatInfo } from './classify'
+import { readAttr } from './accessors'
+import { findKtxTool, isKtx2 } from './textures'
+import { DEFAULT_ATLAS_PAD, DEFAULT_ATLAS_SIZE, type AtlasLayout, type Kind, type Mat4, type MergeGroupPlan, type MergeOptions, type MergePlan, type Source } from './types'
+
+export async function planMerge(doc: Document, opts: MergeOptions): Promise<MergePlan> {
+  const atlasSize = Math.max(64, Math.round(opts.atlasSize ?? DEFAULT_ATLAS_SIZE))
+  const pad = Math.max(0, Math.round(opts.atlasPad ?? DEFAULT_ATLAS_PAD))
+  const exclude = opts.mergeExclude ? new RegExp(opts.mergeExclude) : null
+  const root = doc.getRoot()
+  const primitivesBefore = root.listMeshes().reduce((n, m) => n + m.listPrimitives().length, 0)
+  const materialsBefore = root.listMaterials().length
+  const empty: MergePlan = { enabled: false, atlasSize, pad, groups: [], skipped: [], primitivesBefore, materialsBefore, primitivesAfter: primitivesBefore, joints: 0, ktxTool: null }
+  if (primitivesBefore < 2) return empty
+  const { sources, skipped } = classify(doc, exclude)
+  if (!sources.length) return { ...empty, skipped }
+
+  // material infos (UV ranges over the candidate primitives)
+  const uvOf = (m: Material): number[][] => sources.filter((s) => s.material === m).map((s) => { const a = s.prim.getAttribute('TEXCOORD_0'); return a ? Array.from(readAttr(a).data) : [] })
+  const texId = (t: Texture): string => String(root.listTextures().indexOf(t))
+  const wm = new Map<Node, Mat4>()
+  const measure = (m: Material) => measureSurface(sources.filter((x) => x.material === m), wm)
+  const infos = new Map<Material, MatInfo>()
+  for (const s of sources) if (s.material && !infos.has(s.material)) infos.set(s.material, await materialInfo(s.material, root.listMaterials().indexOf(s.material), uvOf, measure))
+
+  // KTX2 sources need the ktx tool — checked once, only when some candidate map is KTX2
+  const needsKtx = [ ...infos.values() ].some((i) => Object.values(i.maps).some((t) => isKtx2(t)))
+  const ktxTool = needsKtx ? findKtxTool() : null
+
+  // group by family × material class
+  const groupsMap = new Map<string, Source[]>()
+  for (const s of sources) {
+    const family = s.kind === 'static' ? 'static' : 'skinned'
+    const cls = s.material ? infos.get(s.material)!.classKey : 'OPAQUE||0|0'
+    const key = `${family}|${cls}`
+    const list = groupsMap.get(key) ?? []
+    list.push(s)
+    groupsMap.set(key, list)
+  }
+  // skinned family: can every skin join one bind space? (against the skin with most joints)
+  const badSkins = canonicalBinds(bySize(sources.filter((x) => x.kind !== 'static').map((x) => x.skin))).bad
+  const groups: MergeGroupPlan[] = []
+  let kept = 0
+  const usedLabels = new Set<string>()
+  for (const [ key, list ] of groupsMap) {
+    const family = key.startsWith('static') ? 'static' : 'skinned'
+    const usable = list.filter((s) => { if (s.skin && badSkins.has(s.skin)) { skipped.push({ name: s.name, reason: 'bind spaces differ per joint (skin cannot be unified)' }); return false } return true })
+    if (usable.length < 2) { kept += usable.length; continue }
+    // skinned parts first (the merged node is placed where the first one sat), then rigid, then static
+    const rank: Record<Kind, number> = { skinned: 0, rigid: 1, static: 2 }
+    usable.sort((x, y) => rank[x.kind] - rank[y.kind])
+    const mats = [ ...new Set(usable.map((s) => s.material).filter((m): m is Material => !!m)) ]
+    const first = mats[0]
+    let label = family === 'static' && groupsMap.size > 1 && [ ...groupsMap.keys() ].some((k) => k.startsWith('skinned')) ? 'merged.static' : 'merged'
+    if (first) {
+      const info = infos.get(first)!
+      const suffix = info.own ? (first.getName() || 'material').replace(/[^\w.-]+/g, '_') : classSuffix(first)
+      if (suffix) label = `${label}.${suffix}`
+    }
+    while (usedLabels.has(label)) label += '_'
+    usedLabels.add(label)
+    let atlas: AtlasLayout | null = null
+    let note: string | undefined
+    if (mats.length > 1) {
+      const minfos = mats.map((m) => infos.get(m)!)
+      const ktxNeeded = minfos.some((i) => Object.values(i.maps).some((t) => isKtx2(t)))
+      if (ktxNeeded && !ktxTool) { skipped.push({ name: label, reason: `${mats.length} materials carry KTX2 textures and the ktx tool was not found (KTX-Software, next to toktx)` }); kept += usable.length; continue }
+      const a = planAtlas(minfos, atlasSize, pad, !!opts.atlasUniform, texId)
+      if (!a.layout) { skipped.push({ name: label, reason: a.reason! }); kept += usable.length; continue }
+      atlas = a.layout
+    } else if (first && infos.get(first)!.own) note = infos.get(first)!.own!
+    const jointSet = new Set<Node>()
+    for (const s of usable) { if (s.skin) for (const j of s.skin.listJoints()) jointSet.add(j); if (s.joint) jointSet.add(s.joint) }
+    groups.push({
+      label, family, sources: usable, materials: mats, atlas,
+      alphaMode: first?.getAlphaMode() ?? 'OPAQUE', alphaCutoff: first?.getAlphaCutoff() ?? 0.5, doubleSided: first?.getDoubleSided() ?? false, unlit: !!first?.getExtension('KHR_materials_unlit'),
+      joints: jointSet.size, note,
+    })
+  }
+  const inGroups = groups.reduce((n, g) => n + g.sources.length, 0)
+  const primitivesAfter = primitivesBefore - inGroups + groups.length
+  return { enabled: !!opts.merge && groups.length > 0, atlasSize, pad, groups, skipped, primitivesBefore, materialsBefore, primitivesAfter, joints: Math.max(0, ...groups.map((g) => g.joints)), ktxTool }
+}

package/src/doctor/merge/textures.ts

@@ -0,0 +1,60 @@
+// Reading the parts' textures: sizes without decoding, pixels at a tile's size — a Basis KTX2 goes
+// back to PNG through KTX-Software's `ktx extract`.
+
+import type { Texture } from '@gltf-transform/core'
+import sharp from 'sharp'
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { checkToktx, findKtxCli } from '../transcodeKtx2'
+
+export function findKtxTool(): string | null {
+  const ktx = findKtxCli()
+  return checkToktx(ktx) ? ktx : null
+}
+
+export const isKtx2 = (t: Texture): boolean => (t.getMimeType() || '').includes('ktx2')
+
+/** Pixel size of a texture without decoding it: the KTX2 header, or sharp's metadata. */
+export async function imageSize(t: Texture): Promise<[number, number] | null> {
+  const img = t.getImage()
+  if (!img) return null
+  if (isKtx2(t)) {
+    if (img.length < 28) return null
+    const dv = new DataView(img.buffer, img.byteOffset, img.byteLength)
+    return [ dv.getUint32(20, true), dv.getUint32(24, true) ]
+  }
+  try { const m = await sharp(Buffer.from(img)).metadata(); return m.width && m.height ? [ m.width, m.height ] : null } catch { return null }
+}
+
+/** Encoded bytes sharp can read for a texture (a KTX2 goes through `ktx extract`). */
+export async function decodable(tex: Texture, ktxTool: string | null, cache: Map<Texture, Buffer | null>): Promise<Buffer | null> {
+  if (cache.has(tex)) return cache.get(tex)!
+  const img = tex.getImage()
+  let out: Buffer | null = null
+  if (img && !isKtx2(tex)) out = Buffer.from(img)
+  else if (img && ktxTool) {
+    const dir = mkdtempSync(join(tmpdir(), 'glbatlas-'))
+    try {
+      const inK = join(dir, 'in.ktx2'), outP = join(dir, 'out.png')
+      writeFileSync(inK, img)
+      const p = spawnSync(ktxTool, [ 'extract', '--transcode', 'rgba8', inK, outP ], { encoding: 'utf8' })
+      if (p.status === 0 && existsSync(outP)) out = readFileSync(outP)
+    } finally { rmSync(dir, { recursive: true, force: true }) }
+  }
+  cache.set(tex, out)
+  return out
+}
+
+/** A texture as RGBA at exactly w×h (tiled `ru`×`rv` times), or null when it cannot be read. */
+export async function texels(tex: Texture, w: number, h: number, ru: number, rv: number, ktxTool: string | null, cache: Map<Texture, Buffer | null>): Promise<Uint8Array | null> {
+  const bytes = await decodable(tex, ktxTool, cache)
+  if (!bytes) return null
+  const cw = Math.max(1, Math.round(w / ru)), ch = Math.max(1, Math.round(h / rv))
+  const cell = new Uint8Array(await sharp(bytes).resize({ width: cw, height: ch, fit: 'fill', kernel: 'lanczos3' }).ensureAlpha().raw().toBuffer())
+  if (ru === 1 && rv === 1 && cw === w && ch === h) return cell
+  const out = new Uint8Array(w * h * 4)
+  for (let y = 0; y < h; y++) { const sy = y % ch; for (let x = 0; x < w; x++) { const sx = x % cw; const si = (sy * cw + sx) * 4, di = (y * w + x) * 4; out[di] = cell[si]; out[di + 1] = cell[si + 1]; out[di + 2] = cell[si + 2]; out[di + 3] = cell[si + 3] } }
+  return out
+}

package/src/doctor/merge/types.ts

@@ -0,0 +1,77 @@
+// The merge pass's vocabulary: options, the plan (what WOULD be merged — the doctor reports it), the result.
+
+import type { Material, Mesh, Node, Primitive, Skin, Texture } from '@gltf-transform/core'
+
+export interface MergeOptions {
+  /** Merge every mergeable primitive into one per material class + atlas the textures (see the header). */
+  merge?: boolean
+  /** Largest atlas edge in texels (default 2048); tiles scale down uniformly to fit. */
+  atlasSize?: number
+  /** Edge-replication padding around every tile, in texels (default 8). */
+  atlasPad?: number
+  /** Node names (regex) to leave out of the merge — a part the game hides or swaps. */
+  mergeExclude?: string
+  /** Scale every tile by the same factor to fit (default: by surface area — equal texel density). */
+  atlasUniform?: boolean
+}
+
+export const DEFAULT_ATLAS_SIZE = 2048
+export const DEFAULT_ATLAS_PAD = 8
+
+export type Mat4 = number[]
+export type Kind = 'skinned' | 'rigid' | 'static'
+export type MapKind = 'base' | 'normal' | 'orm' | 'emissive'
+
+export interface Source { node: Node; mesh: Mesh; prim: Primitive; kind: Kind; skin: Skin | null; joint: Node | null; name: string; material: Material | null; triangles: number }
+export interface MergeSkipped { name: string; reason: string }
+
+export interface Tile {
+  key: string
+  materials: Material[]
+  /** source texel size (the material's largest map, × the UV repeat) */
+  srcW: number; srcH: number
+  /** UV repeat and origin: the tile covers [u0, u0 + ru) × [v0, v0 + rv) of the material's UV space */
+  u0: number; v0: number; ru: number; rv: number
+  /** surface on the model (m², bind / world space) and the fraction of the tile's UV square the triangles cover */
+  area: number; uvArea: number
+  /** placed size and position (inner rect, without the padding) at the chosen scale */
+  w: number; h: number; x: number; y: number
+  /** tile edge / source edge */
+  scale: number
+}
+export interface AtlasLayout { size: number; /** smallest tile scale */ scale: number; /** largest tile scale */ scaleMax: number; byArea: boolean; pad: number; maps: MapKind[]; tiles: Tile[]; hasAlpha: boolean }
+
+export interface MergeGroupPlan {
+  label: string
+  family: 'skinned' | 'static'
+  sources: Source[]
+  materials: Material[]
+  /** null = the group keeps its (single) material — geometry-only merge */
+  atlas: AtlasLayout | null
+  /** the class the merged material inherits */
+  alphaMode: 'OPAQUE' | 'MASK' | 'BLEND'; alphaCutoff: number; doubleSided: boolean; unlit: boolean
+  joints: number
+  note?: string
+}
+export interface MergePlan {
+  enabled: boolean
+  atlasSize: number
+  pad: number
+  groups: MergeGroupPlan[]
+  skipped: MergeSkipped[]
+  primitivesBefore: number
+  materialsBefore: number
+  /** primitives that stay (skipped) + one per group */
+  primitivesAfter: number
+  /** joints of the largest merged skin (the bone cap applies to it) */
+  joints: number
+  ktxTool: string | null
+}
+export interface MergeResult {
+  groups: { label: string; primitives: number; materials: number; vertices: number; triangles: number; atlas: string | null; joints: number }[]
+  skipped: MergeSkipped[]
+  /** the atlas textures created (for the caller's texture passes) */
+  textures: Texture[]
+  primitivesBefore: number
+  primitivesAfter: number
+}