lecodes-assets 0.2.0 → 2.4.10

package/src/doctor/doctor.ts

@@ -0,0 +1,305 @@
+// glTF doctor — analyze a Document against creator-gl/filament constraints and (optionally) fix it.
+// The former tools/glb-reduce/glbDoctor.ts, as functions so `convert` can run the same passes on a
+// freshly converted model (`convert … --ktx2`) and the CLI can run them on any GLB (`doctor`).
+//
+//   Analyze : reports issues grouped by impact — LOSSLESS fixes (no degradation, e.g. dropping
+//             unbound joints / re-encoding webp→png) vs LOSSY fixes (bound-joint removal,
+//             webp→jpg, downscaling, heavy-png→jpg).
+//   Fix     : applies everything; the caller writes <name>.fixed.glb and re-validates.
+//   KTX2    : textures → KTX2 (ETC1S; --ktx2-hq keeps normals UASTC) via KTX-Software (toktx, or `ktx create` where toktx is gone).
+import { gatherSkinPrims, planSkin, applySkinPlan, DEFAULT_TARGET, type SkinPlan } from './reduceGlbBones'
+import { planTexture, applyTexturePlan, getTextureRoles, DEFAULT_MAX_SIZE, type TexturePlan } from './transcodeTextures'
+import { planKtx2, applyKtx2, findKtxEncoder, KTX_ENCODER_MISSING, type Ktx2Plan, type KtxEncoder } from './transcodeKtx2'
+import { measureScale, planScale, applyScale, type ScaleInfo, type ScalePlan, type ScaleOptions } from './normalizeScale'
+import { analyzeShading, applyShading, type ShadingPlan, type ShadingOptions } from './shading'
+import { planCardTrim, applyCardTrim, type CardTrimPlan, type CardTrimOptions, type CardTrimResult } from './cardTrim'
+import { planLod, applyLod, type LodPlan, type LodOptions, type LodResult } from './lod'
+import { planMerge, applyMerge, describeScale, type MergePlan, type MergeOptions, type MergeResult } from './merge'
+import { duplicateNodeNames } from '../mergeSkins'
+import { KHRTextureBasisu } from '@gltf-transform/extensions'
+import type { Document, Material } from '@gltf-transform/core'
+import { mkdirSync, existsSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export { DEFAULT_TARGET, DEFAULT_MAX_SIZE, findKtxEncoder, KTX_ENCODER_MISSING }
+export { sceneBounds, measureScale, applyScale } from './normalizeScale'
+
+interface MetallicWarn { mat: Material; name: string; metal: number }
+export interface DoctorPlan { skinPlans: SkinPlan[]; texPlans: TexturePlan[]; ktx2Plans: Ktx2Plan[]; metallicWarn: MetallicWarn[]; bareCount: number; shadingPlan: ShadingPlan; scaleInfo: ScaleInfo | null; scalePlan: ScalePlan | null; lodPlan: LodPlan | null; cardTrimPlan: CardTrimPlan; mergePlan: MergePlan; conflicts: number; target: number; dupNames: { name: string; count: number; shadowsJoint: boolean }[] }
+export interface DoctorOptions extends ScaleOptions, ShadingOptions, LodOptions, CardTrimOptions, MergeOptions { target?: number; maxSize?: number; ktx2?: boolean; ktx2Hq?: boolean; ktx2Uastc?: boolean }
+
+export async function analyzeDoc(doc: Document, opts: DoctorOptions = {}): Promise<DoctorPlan> {
+  const target = opts.target ?? DEFAULT_TARGET
+  const maxSize = opts.maxSize ?? DEFAULT_MAX_SIZE
+  const root = doc.getRoot()
+  const { bySkin, conflicts } = gatherSkinPrims(doc)
+  const skinPlans = root.listSkins().map((s, i) => planSkin(s, i, bySkin.get(s) ?? [], target))
+  const texPlans: TexturePlan[] = []
+  const ktx2Plans: Ktx2Plan[] = []
+  // KTX2 mode: everything → ETC1S (max compression). --ktx2-hq upgrades NORMAL maps to UASTC
+  // (much higher quality, same VRAM, larger file); colour/metalRough stay ETC1S either way.
+  const codecPolicy = opts.ktx2Uastc ? 'uastc' : opts.ktx2Hq ? 'hq' : 'default'
+  for (const tex of root.listTextures()) {
+    if (opts.ktx2) {
+      const p = await planKtx2(tex, root, maxSize, codecPolicy); if (p) ktx2Plans.push(p)
+    } else {
+      const p = await planTexture(tex, root, maxSize); if (p) texPlans.push(p)
+    }
+  }
+  // Materials with a flat metallic factor but NO metallicRoughness texture render BLACK without an
+  // IBL/environment (metal reflects nothing, has no diffuse). Common export quirk on non-metal assets.
+  const metallicWarn: MetallicWarn[] = root.listMaterials()
+    .filter((m) => m.getMetallicFactor() > 0.01 && !m.getMetallicRoughnessTexture())
+    .map((m) => ({ mat: m, name: m.getName() || '?', metal: m.getMetallicFactor() }))
+  // Primitives with NO material at all: glTF's default material is metallic 1 / roughness 1 — a white ROUGH METAL,
+  // which under an environment (or a lightmap's reflection probe) is a dark featureless blob (the school's
+  // cabinets and sinks, 2026-09-17). --fix-metallic gives them a plain white dielectric.
+  let bareCount = 0
+  for (const mesh of root.listMeshes()) for (const prim of mesh.listPrimitives()) if (!prim.getMaterial()) bareCount++
+  const shadingPlan = analyzeShading(doc, opts)
+  // Scale is always MEASURED (probe/report it even with no flag); it is only APPLIED when asked.
+  const scaleInfo = measureScale(doc)
+  const scalePlan = planScale(scaleInfo, opts)
+  // Duplicate node names: the Animator binds clips BY NAME and takes the first match. A leftover
+  // donor skeleton (two skinned files merged by hand) shadows the real joints → the mesh freezes.
+  const dupNames = duplicateNodeNames(doc)
+  // LOD levels are only ever ADDED on request (--lod); see doctor/lod.ts.
+  const lodPlan = planLod(doc, opts)
+  // Card trimming only on request (--trim-cards); the analysis lists the alpha-MASK primitives it would cut.
+  const cardTrimPlan = planCardTrim(doc, opts)
+  // Mesh merge + atlas only on request (--merge); the analysis says how many draw calls it would fold.
+  const mergePlan = await planMerge(doc, opts)
+  return { skinPlans, texPlans, ktx2Plans, metallicWarn, bareCount, shadingPlan, scaleInfo, scalePlan, lodPlan, cardTrimPlan, mergePlan, conflicts, target, dupNames }
+}
+
+export const kb = (n?: number) => (n === undefined ? '?' : `${Math.round(n / 1024)}KB`)
+
+/** A length in metres, in whatever unit reads best — 0.0055 is "5.5mm", not "0.01m". */
+export const metres = (m: number): string =>
+  m >= 1 ? `${m.toFixed(m >= 10 ? 0 : 2)}m` : m >= 0.01 ? `${(m * 100).toFixed(1)}cm` : `${(m * 1000).toFixed(m >= 0.001 ? 1 : 3)}mm`
+const dims3 = (d: readonly number[]): string => d.map((x) => metres(x)).join(' × ')
+const fmtFactor = (f: number): string => (f >= 0.001 && f < 1e6 ? +f.toPrecision(6) : f.toExponential(2)).toString()
+
+const EXT_BY_MIME: Record<string, string> = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/ktx2': 'ktx2' }
+const safeName = (n: string) => (n || 'tex').replace(/[\\/:*?"<>|\s]+/g, '_').slice(0, 60)
+
+/** Write every texture's raw bytes to `dir` (+ a _manifest.txt) for manual inspection. */
+export async function dumpTextures(doc: Document, dir: string, log: (s: string) => void = console.log) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  const root = doc.getRoot()
+  const rows: string[] = []
+  let sharp: any = null
+  try { sharp = (await import('sharp')).default } catch { /* dims/alpha columns stay '-' */ }
+  let i = 0
+  for (const tex of root.listTextures()) {
+    const img = tex.getImage()
+    const mime = tex.getMimeType() || ''
+    const ext = EXT_BY_MIME[mime] ?? 'bin'
+    const file = `${String(i).padStart(2, '0')}_${safeName(tex.getName())}.${ext}`
+    if (img) writeFileSync(`${dir}/${file}`, img)
+    const { roles } = getTextureRoles(tex, root)
+    let dims = '-', alpha = '-'
+    if (img && ext !== 'ktx2' && sharp) {
+      try {
+        const m = await sharp(Buffer.from(img)).metadata()
+        dims = `${m.width}x${m.height}`
+        alpha = (await sharp(Buffer.from(img)).stats()).isOpaque ? 'opaque' : 'ALPHA'
+      } catch { /* undecodable by sharp */ }
+    }
+    rows.push(`${file.padEnd(48)} ${ext.padEnd(5)} ${dims.padEnd(11)} ${alpha.padEnd(7)} ${roles.padEnd(12)} ${kb(img?.length)}`)
+    i++
+  }
+  const header = `# ${i} textures from this GLB\n# file  format  dimensions  alpha  role  size\n`
+  writeFileSync(`${dir}/_manifest.txt`, header + rows.join('\n') + '\n')
+  log(`\n🖼  dumped ${i} textures → ${dir}`)
+  log(rows.join('\n'))
+}
+
+export function reportPlan(plan: DoctorPlan): { text: string; lossless: number; lossy: number; blocking: number } {
+  const lossless: string[] = [], lossy: string[] = [], blocking: string[] = []
+
+  for (const s of plan.skinPlans) {
+    if (s.before <= plan.target) continue
+    if (s.removedDeep === 0) {
+      lossless.push(`bones  ${s.name}: drop ${s.removedUnbound} unbound joints  (${s.before} → ${s.after})`)
+    } else {
+      if (s.removedUnbound > 0) lossless.push(`bones  ${s.name}: drop ${s.removedUnbound} unbound joints`)
+      lossy.push(`bones  ${s.name}: drop ${s.removedDeep} deepest BOUND joints, merge weights → parent  (${s.before} → ${s.after})`)
+    }
+    if (s.after > plan.target) blocking.push(`bones  ${s.name}: still ${s.after} > ${plan.target} after reduction (too many root joints)`)
+  }
+
+  for (const t of plan.texPlans) {
+    if (!t.toFmt) continue
+    const line = `tex    "${t.name}" [${t.roles}] ${t.fromFmt}→${t.toFmt}  (${t.reason}, ${kb(t.beforeBytes)})`
+    ;(t.category === 'lossless' ? lossless : lossy).push(line)
+  }
+  for (const t of plan.ktx2Plans) {
+    lossy.push(`tex    "${t.name}" [${t.roles}] ${t.reason}  (${kb(t.beforeBytes)})`)
+  }
+  if (plan.conflicts > 0) blocking.push(`${plan.conflicts} primitive(s) shared across skins — skipped`)
+  const shadowing = plan.dupNames.filter((d) => d.shadowsJoint)
+  if (shadowing.length) blocking.push(`names  ${shadowing.length} skinned joint(s) shadowed by a plain node of the same name (${shadowing.slice(0, 5).map((d) => d.name).join(', ')}${shadowing.length > 5 ? '…' : ''}) — a name-bound Animator drives the copy and the mesh freezes; rebuild with convert --merge-skins, or delete the stray skeleton`)
+
+  const lines: string[] = []
+  if (lossless.length) { lines.push('  ── LOSSLESS (no quality loss) ──'); lossless.forEach((l) => lines.push('   • ' + l)) }
+  if (lossy.length) { lines.push('  ── LOSSY (some degradation) ──'); lossy.forEach((l) => lines.push('   • ' + l)) }
+  if (blocking.length) { lines.push('  ── BLOCKING / manual ──'); blocking.forEach((l) => lines.push('   ✗ ' + l)) }
+  if (plan.metallicWarn.length || plan.bareCount) lines.push(`  ── MATERIALS ──`)
+  if (plan.metallicWarn.length) {
+    lines.push(`   ℹ ${plan.metallicWarn.length} material(s) have metallic without an MR texture → may render BLACK without IBL (--fix-metallic zeroes them):`)
+    lines.push(`     ${plan.metallicWarn.map((w) => `${w.name}(${w.metal.toFixed(2)})`).join(', ')}`)
+  }
+  if (plan.bareCount) lines.push(`   ℹ ${plan.bareCount} primitive(s) have NO material → glTF's default is a white ROUGH METAL (a dark blob under any environment; --fix-metallic gives them a white dielectric)`)
+  const selfLit = plan.shadingPlan.issues.filter((i) => i.selfLit)
+  const boosted = plan.shadingPlan.issues.filter((i) => i.specularBoost > 0)
+  if (selfLit.length || boosted.length) {
+    if (!plan.metallicWarn.length && !plan.bareCount) lines.push(`  ── MATERIALS ──`)
+    if (selfLit.length) {
+      lines.push(`   ⚠ ${selfLit.length} material(s) emit their own base colour (emissive = albedo) → render ~2× too bright, washed out (--fix-emissive drops it, --unlit goes flat):`)
+      lines.push(`     ${selfLit.map((i) => i.name).join(', ')}`)
+    }
+    if (boosted.length) {
+      lines.push(`   ℹ ${boosted.length} material(s) boost specular above 1 (${boosted.map((i) => `${i.name}(×${i.specularBoost.toFixed(1)})`).join(', ')}) — gltfio also refuses specular + unlit, so --unlit drops it`)
+    }
+  }
+  const sc = plan.scaleInfo
+  if (sc?.suspicious || plan.scalePlan) {
+    lines.push(`  ── SCALE ──`)
+    if (sc) lines.push(`   ${sc.suspicious ? '⚠' : 'ℹ'} model measures ${dims3(sc.dims)}${sc.suspicious ? ` — implausible for a real-world asset (${sc.label})` : ''}`)
+    else lines.push(`   ℹ no geometry to measure (clip-only file)`)
+    if (plan.scalePlan) lines.push(`     → ×${fmtFactor(plan.scalePlan.factor)}${plan.scalePlan.source === 'explicit' ? '' : ` (${plan.scalePlan.label})`}${sc ? ` → ${dims3(plan.scalePlan.after)}` : ''}`)
+    else if (sc && sc.suggested !== 1) lines.push(`     --fix-scale applies ×${fmtFactor(sc.suggested)} → ${dims3(sc.dims.map((d) => d * sc.suggested))}; --scale-to <m> / --scale <n> to decide yourself`)
+    else lines.push(`     --scale-to <m> sets the largest dimension explicitly`)
+  }
+  const ct = plan.cardTrimPlan
+  if (ct.prims.length) {
+    lines.push(`  ── CARDS ──`)
+    const tris = ct.prims.reduce((n, p) => n + p.triangles, 0)
+    const ready = ct.prims.filter((p) => p.texture === 'ok').length
+    if (ct.enabled) lines.push(`   • trim ${ready} alpha-MASK primitive(s) (${tris} triangles) to their opaque texels, margin ${ct.margin} texel(s)${ready < ct.prims.length ? `; ${ct.prims.length - ready} skipped (${ct.prims.filter((p) => p.texture !== 'ok').map((p) => `${p.name}: ${p.texture}`).slice(0, 4).join(', ')})` : ''}`)
+    else lines.push(`   ℹ ${ct.prims.length} alpha-MASK primitive(s), ${tris} triangles — foliage cards? --trim-cards cuts each quad to its opaque texels (less discarded fill)${ready < ct.prims.length ? `; ${ct.prims.length - ready} carry KTX2 / transformed / no textures and would be skipped` : ''}`)
+  }
+  const mg = plan.mergePlan
+  if (mg.groups.length || mg.skipped.length) {
+    lines.push(`  ── MERGE ──`)
+    const fold = `${mg.primitivesBefore} primitive(s) over ${mg.materialsBefore} material(s) → ${mg.primitivesAfter} draw call(s)`
+    if (mg.enabled) {
+      lines.push(`   • merge ${fold}`)
+      for (const g of mg.groups) lines.push(`     ${g.label}: ${g.sources.length} primitives, ${g.materials.length} material(s)${g.atlas ? ` → 1 (atlas ${g.atlas.size}² ${g.atlas.maps.join('+')}, ${g.atlas.tiles.length} tiles${describeScale(g.atlas)}, pad ${g.atlas.pad})` : g.materials.length === 1 ? ` (kept: ${g.materials[0].getName() || 'material'}${g.note ? ` — ${g.note}` : ''})` : ''}${g.family === 'skinned' ? `, ${g.joints} joints in one skin` : ', transforms baked'}`)
+      if (mg.joints > plan.target) blocking.push(`bones  merged skin has ${mg.joints} joints > ${plan.target} — exclude parts (--merge-exclude) or raise --target`)
+    } else if (mg.groups.length) lines.push(`   ℹ ${fold} with --merge (one atlas material per alpha mode / sidedness)`)
+    if (mg.skipped.length) lines.push(`     ${mg.enabled ? 'skipped' : 'would skip'}: ${mg.skipped.slice(0, 6).map((s) => `${s.name} (${s.reason})`).join(', ')}${mg.skipped.length > 6 ? '…' : ''}`)
+  }
+  const plainDups = plan.dupNames.filter((d) => !d.shadowsJoint)
+  if (plainDups.length) {
+    lines.push(`  ── NAMES ──`)
+    lines.push(`   ℹ ${plainDups.length} node name(s) used more than once (${plainDups.slice(0, 6).map((d) => `${d.name} ×${d.count}`).join(', ')}${plainDups.length > 6 ? '…' : ''}) — clips and node paths address the FIRST one`)
+  }
+  if (!lines.length) lines.push('  ✅ no issues — model is within all limits')
+  return { text: lines.join('\n'), lossless: lossless.length, lossy: lossy.length, blocking: blocking.length }
+}
+
+export interface ApplyOptions extends DoctorOptions { fixMetallic?: boolean; ktxEncoder?: KtxEncoder; progress?: (done: number, total: number) => void }
+export interface ApplyResult { metallicZeroed: number; bareFixed: number; ktx2Encoded: number; scaled: number; unlit: number; emissiveCleared: number; lod: LodResult | null; cards: CardTrimResult | null; merge: MergeResult | null; emptied: number }
+
+/** Apply a plan to the document (mutates). Resolves the KTX encoder itself when `ktx2` and none is given. */
+export async function applyPlan(doc: Document, plan: DoctorPlan, opts: ApplyOptions = {}): Promise<ApplyResult> {
+  const maxSize = opts.maxSize ?? DEFAULT_MAX_SIZE
+  for (const s of plan.skinPlans) applySkinPlan(doc, s)
+  // After the skin plan: bone reduction rewrites joints/IBMs, and scaling the reduced set is both
+  // cheaper and keeps the IBM offsets it just wrote consistent with the geometry.
+  if (plan.scalePlan) applyScale(doc, plan.scalePlan.factor)
+  let metallicZeroed = 0
+  if (opts.fixMetallic && plan.metallicWarn.length) {
+    for (const w of plan.metallicWarn) w.mat.setMetallicFactor(0)
+    metallicZeroed = plan.metallicWarn.length
+  }
+  let bareFixed = 0
+  if (opts.fixMetallic && plan.bareCount) {
+    const plain = doc.createMaterial('Default').setBaseColorFactor([1, 1, 1, 1]).setMetallicFactor(0).setRoughnessFactor(1)
+    for (const mesh of doc.getRoot().listMeshes()) for (const prim of mesh.listPrimitives()) if (!prim.getMaterial()) { prim.setMaterial(plain); bareFixed++ }
+  }
+  const shading = applyShading(doc, plan.shadingPlan)
+  // Merge + atlas before every other geometry pass (they see the merged primitive) and before the texture
+  // passes: the atlases are new PNG textures, planned below like any other — capped by --atlas-size, not
+  // --max-size — while the plans of the textures the atlases replaced are dropped with them.
+  const merge = plan.mergePlan.enabled ? await applyMerge(doc, plan.mergePlan) : null
+  if (merge) {
+    const root = doc.getRoot()
+    const alive = new Set(root.listTextures())
+    plan.ktx2Plans = plan.ktx2Plans.filter((t) => alive.has(t.tex))
+    plan.texPlans = plan.texPlans.filter((t) => alive.has(t.tex))
+    const codecPolicy = opts.ktx2Uastc ? 'uastc' : opts.ktx2Hq ? 'hq' : 'default'
+    for (const tex of merge.textures) {
+      if (opts.ktx2) { const p = await planKtx2(tex, root, plan.mergePlan.atlasSize, codecPolicy); if (p) plan.ktx2Plans.push(p) }
+      else { const p = await planTexture(tex, root, plan.mergePlan.atlasSize); if (p) plan.texPlans.push(p) }
+    }
+    // …and the geometry passes are planned AGAIN: their plans were made in `analyzeDoc`, against primitives
+    // the merge has just disposed (a plan that kept one died on it: `pos.getCount` of null).
+    plan.lodPlan = planLod(doc, opts)
+    plan.cardTrimPlan = planCardTrim(doc, opts)
+  }
+  // LOD levels after every geometry pass (they copy the final base mesh) and before textures.
+  const lod = plan.lodPlan ? await applyLod(doc, plan.lodPlan) : null
+  // Card trimming before the texture passes: it decodes the base colour (PNG / JPEG), which a KTX2
+  // encode below would take away.
+  const cards = plan.cardTrimPlan.enabled ? await applyCardTrim(doc, plan.cardTrimPlan) : null
+  let ktx2Encoded = 0
+  if (opts.ktx2) {
+    const enc = opts.ktxEncoder ?? findKtxEncoder()
+    if (!enc) throw new Error(KTX_ENCODER_MISSING)
+    // Launched together, not one after another: `applyKtx2` bounds the real concurrency with its own
+    // pool of encoder processes (LECODES_KTX_JOBS, default one per core less one). Encoding used to be
+    // strictly sequential — a `spawnSync` per texture blocked the event loop — so a project's whole
+    // texture set went through one core however many were idle.
+    await Promise.all(plan.ktx2Plans.map(async (t) => {
+      await applyKtx2(t, enc, maxSize)
+      opts.progress?.(++ktx2Encoded, plan.ktx2Plans.length)
+    }))
+    // KTX2 textures must be written via KHR_texture_basisu (core texture.source allows only PNG/JPEG);
+    // gltf-transform only emits that form when the extension is attached to the document.
+    if (plan.ktx2Plans.length && !doc.getRoot().listExtensionsUsed().some((e) => e.extensionName === 'KHR_texture_basisu')) {
+      doc.createExtension(KHRTextureBasisu).setRequired(true)
+    }
+  } else {
+    for (const t of plan.texPlans) if (t.toFmt) await applyTexturePlan(t, maxSize)
+  }
+  // Once no texture is webp anymore, drop EXT_texture_webp — else it lingers in extensionsRequired
+  // and a strict loader (gltfio) can reject the file for a now-unused requirement.
+  if (!doc.getRoot().listTextures().some((t) => (t.getMimeType() || '').includes('webp'))) {
+    for (const ext of doc.getRoot().listExtensionsUsed()) {
+      if (ext.extensionName === 'EXT_texture_webp') ext.dispose()
+    }
+  }
+  // LAST, after every pass that can eat geometry: a primitive with no vertices left is not a
+  // primitive. Card trimming produces them — it cuts an alpha-MASK quad down to its opaque texels,
+  // and the Modular Shooting Range's floor stripes have LOD levels whose texels are all clear, so
+  // the level came out carrying five empty meshes. That is not a cosmetic problem: filament's
+  // gltfio walks the primitive in `ResourceLoader::loadResources` and takes the host down with an
+  // access violation before the first frame.
+  let emptied = 0
+  for (const mesh of doc.getRoot().listMeshes()) {
+    for (const prim of mesh.listPrimitives()) {
+      if ((prim.getAttribute("POSITION")?.getCount() ?? 0) > 0) continue
+      mesh.removePrimitive(prim)
+      prim.dispose()
+      emptied++
+    }
+    if (!mesh.listPrimitives().length) mesh.dispose()
+  }
+  return { metallicZeroed, bareFixed, ktx2Encoded, scaled: plan.scalePlan?.factor ?? 1, unlit: shading.unlit, emissiveCleared: shading.emissiveCleared, lod, cards, merge, emptied }
+}
+
+/** Output path for a doctored file: single file + -o → exact path; -o as dir (or batch) → derived name inside it. */
+export function outputFor(input: string, oVal: string | null, batch: boolean, ktx2: boolean): string {
+  const derived = input.replace(/\.glb$/i, ktx2 ? '.ktx2.glb' : '.fixed.glb')
+  if (!oVal) return derived
+  const oNorm = oVal.replace(/\\/g, '/')
+  const asDir = batch || /\/$/.test(oNorm) || (existsSync(oNorm) && statSync(oNorm).isDirectory())
+  if (asDir) {
+    if (!existsSync(oNorm)) mkdirSync(oNorm, { recursive: true })
+    return join(oNorm, derived.split(/[\\/]/).pop()!)
+  }
+  return oVal
+}

package/src/doctor/lod.ts

@@ -0,0 +1,177 @@
+// Mesh + skeleton LOD levels for creator-gl's LOD pass (docs/lod-plan.md §5).
+//
+//   --lod 0.5,0.2     every mesh node with ≥ MIN_TRIS triangles gets sibling nodes `<name>_LOD1`,
+//                     `<name>_LOD2` … (same parent / transform / skin / materials) whose primitives are
+//                     meshoptimizer-simplified copies at the given ratios of the ORIGINAL triangle count.
+//                     Skinned primitives keep JOINTS/WEIGHTS (the simplifier only collapses vertices), so
+//                     every level rides the same skin. Morph targets are not carried to the levels.
+//   --lod-bones       the LAST level of a skinned node also gets a reduced SKIN: vertices weighted to
+//                     finger / toe / twist / leaf joints are re-weighted onto their nearest kept ancestor
+//                     and the level references a new Skin over the kept joints only — the engine
+//                     uploads a third of the bones for a far character.
+//
+// The engine groups levels by the `_LOD<n>` name (creator-gl src/lod.cpp) and shows one at a time; a
+// viewer without LOD support draws them all — harmless. Extras carry the bookkeeping for probes.
+
+import type { Accessor, Document, Mesh, Node as GltfNode, Primitive, Skin } from '@gltf-transform/core'
+import { simplifyPrimitive, weldPrimitive } from '@gltf-transform/functions'
+import { MeshoptSimplifier } from 'meshoptimizer'
+
+export interface LodOptions { lod?: number[]; lodBones?: boolean }
+export interface LodNodePlan { node: GltfNode; name: string; tris: number; skinned: boolean }
+export interface LodPlan { ratios: number[]; bones: boolean; nodes: LodNodePlan[]; existing: number }
+export interface LodResult { levels: number; nodes: number; tris: { name: string; levels: number[] }[]; bones: { name: string; before: number; after: number }[]; skipped: { name: string; level: number; tris: number }[] }
+
+/** Meshes under this go without levels — a crate does not need one. */
+export const LOD_MIN_TRIS = 2000
+/** Joints a far character stops animating / weighting — the same vocabulary as creator-gl's joint mask
+ *  (animation/animator.cpp lodMaskedName) and the retargeter's helper classes. Keep them in step. */
+export const LOD_JOINT_MASK = /finger|thumb|index|middle|ring|pinky|toe|twist|roll|leaf|_end$/i
+const LOD_NAME = /_LOD\d+$/
+
+const shortName = (s: string): string => { const p = Math.max(s.lastIndexOf(':'), s.lastIndexOf('|')); return p < 0 ? s : s.slice(p + 1) }
+
+const primTris = (p: Primitive): number => {
+  if (p.getMode() !== 4) return 0   // TRIANGLES only
+  const idx = p.getIndices()
+  const n = idx ? idx.getCount() : (p.getAttribute('POSITION')?.getCount() ?? 0)
+  return Math.floor(n / 3)
+}
+const meshTris = (m: Mesh): number => m.listPrimitives().reduce((s, p) => s + primTris(p), 0)
+
+export function planLod(doc: Document, opts: LodOptions): LodPlan | null {
+  const ratios = (opts.lod ?? []).filter((r) => r > 0 && r < 1).sort((a, b) => b - a)
+  if (!ratios.length) return null
+  const nodes: LodNodePlan[] = []
+  let existing = 0
+  for (const node of doc.getRoot().listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh) continue
+    if (LOD_NAME.test(node.getName())) { existing++; continue }
+    const tris = meshTris(mesh)
+    if (tris < LOD_MIN_TRIS) continue
+    nodes.push({ node, name: node.getName() || mesh.getName() || `mesh${nodes.length}`, tris, skinned: !!node.getSkin() })
+  }
+  return { ratios, bones: !!opts.lodBones, nodes, existing }
+}
+
+/** A deep copy of a primitive's geometry (own accessors — simplify rewrites them in place), sharing the material. */
+const clonePrimitive = (doc: Document, prim: Primitive): Primitive => {
+  const buffer = doc.getRoot().listBuffers()[0] ?? doc.createBuffer()
+  const cloneAcc = (a: Accessor): Accessor => doc.createAccessor(a.getName(), buffer).setType(a.getType()).setNormalized(a.getNormalized()).setArray(a.getArray()!.slice())
+  const out = doc.createPrimitive().setMode(prim.getMode()).setMaterial(prim.getMaterial())
+  for (const sem of prim.listSemantics()) out.setAttribute(sem, cloneAcc(prim.getAttribute(sem)!))
+  const idx = prim.getIndices()
+  if (idx) out.setIndices(cloneAcc(idx))
+  return out
+}
+
+/** The last level of a skinned node: masked joints fold onto their nearest kept ancestor, on a new Skin over the kept joints. */
+const reduceSkinForLod = (doc: Document, lodNode: GltfNode): { before: number; after: number } | null => {
+  const skin = lodNode.getSkin()
+  const mesh = lodNode.getMesh()
+  if (!skin || !mesh) return null
+  const joints = skin.listJoints()
+  const removed = new Set<number>()
+  joints.forEach((j, i) => { if (LOD_JOINT_MASK.test(shortName(j.getName()))) removed.add(i) })
+  if (!removed.size) return null
+  const idxOf = new Map<GltfNode, number>(joints.map((j, i) => [j, i]))
+  const remap = joints.map((j, i) => {
+    if (!removed.has(i)) return i
+    for (let p = j.getParentNode(); p; p = p.getParentNode()) { const k = idxOf.get(p); if (k !== undefined && !removed.has(k)) return k }
+    return i   // no kept ancestor: keep the joint
+  })
+  const kept = [...new Set(remap)].sort((a, b) => a - b)
+  const newIndex = new Map<number, number>(kept.map((old, k) => [old, k]))
+  const buffer = doc.getRoot().listBuffers()[0] ?? doc.createBuffer()
+  const newSkin: Skin = doc.createSkin(`${skin.getName() || 'skin'}_LOD`)
+  if (skin.getSkeleton()) newSkin.setSkeleton(skin.getSkeleton())
+  for (const i of kept) newSkin.addJoint(joints[i]!)
+  const ibm = skin.getInverseBindMatrices()
+  if (ibm) {
+    const src = ibm.getArray()!
+    const out = new Float32Array(kept.length * 16)
+    kept.forEach((i, k) => out.set(src.subarray(i * 16, i * 16 + 16), k * 16))
+    newSkin.setInverseBindMatrices(doc.createAccessor(`${ibm.getName() || 'ibm'}_LOD`, buffer).setType('MAT4').setArray(out))
+  }
+  const jv: number[] = [], wv: number[] = []
+  for (const prim of mesh.listPrimitives()) {
+    // every set is gathered per vertex, folded by target joint, then written back set by set (largest first)
+    const sets: { j: Accessor; w: Accessor }[] = []
+    for (let s = 0; ; s++) { const j = prim.getAttribute(`JOINTS_${s}`), w = prim.getAttribute(`WEIGHTS_${s}`); if (!j || !w) break; sets.push({ j, w }) }
+    if (!sets.length) continue
+    const count = sets[0]!.j.getCount()
+    const folded = new Map<number, number>()
+    for (let v = 0; v < count; v++) {
+      folded.clear()
+      for (const { j, w } of sets) {
+        j.getElement(v, jv); w.getElement(v, wv)
+        for (let k = 0; k < 4; k++) {
+          const weight = wv[k] ?? 0
+          if (weight <= 0) continue
+          const target = newIndex.get(remap[jv[k]!] ?? jv[k]!) ?? 0
+          folded.set(target, (folded.get(target) ?? 0) + weight)
+        }
+      }
+      const pairs = [...folded].sort((a, b) => b[1] - a[1])
+      let n = 0
+      for (const { j, w } of sets) {
+        for (let k = 0; k < 4; k++) { const p = pairs[n++]; jv[k] = p ? p[0] : 0; wv[k] = p ? p[1] : 0 }
+        j.setElement(v, jv); w.setElement(v, wv)
+      }
+    }
+  }
+  lodNode.setSkin(newSkin)
+  return { before: joints.length, after: kept.length }
+}
+
+export async function applyLod(doc: Document, plan: LodPlan): Promise<LodResult> {
+  await MeshoptSimplifier.ready
+  const result: LodResult = { levels: plan.ratios.length, nodes: 0, tris: [], bones: [], skipped: [] }
+  for (const entry of plan.nodes) {
+    const { node } = entry
+    const baseMesh = node.getMesh()!
+    const parent = node.getParentNode()
+    const scenes = parent ? [] : doc.getRoot().listScenes().filter((s) => s.listChildren().includes(node))
+    const baseExtras = (node.getExtras() ?? {}) as Record<string, unknown>
+    const baseLecodes = (baseExtras.lecodes ?? {}) as Record<string, unknown>
+    node.setExtras({ ...baseExtras, lecodes: { ...baseLecodes, lod: { level: 0, levels: plan.ratios.length + 1, tris: entry.tris } } })
+    const levels: number[] = [entry.tris]
+    for (let i = 0; i < plan.ratios.length; i++) {
+      const level = i + 1
+      const ratio = plan.ratios[i]!
+      const mesh = doc.createMesh(`${baseMesh.getName() || entry.name}_LOD${level}`)
+      let tris = 0
+      for (const prim of baseMesh.listPrimitives()) {
+        if (prim.getMode() !== 4) continue
+        let copy = clonePrimitive(doc, prim)
+        weldPrimitive(copy)
+        copy = simplifyPrimitive(copy, { simplifier: MeshoptSimplifier, ratio, error: 0.02, lockBorder: false })
+        tris += primTris(copy)
+        mesh.addPrimitive(copy)
+      }
+      // A level the simplifier could not shrink (hard-surface meshes with many seams stop early) is not
+      // worth its bytes or its draw: drop it rather than ship a near-duplicate.
+      if (tris > levels[levels.length - 1]! * 0.85) {
+        for (const p of mesh.listPrimitives()) { for (const sem of p.listSemantics()) p.getAttribute(sem)?.dispose(); p.getIndices()?.dispose(); p.dispose() }
+        mesh.dispose()
+        result.skipped.push({ name: entry.name, level, tris })
+        break
+      }
+      const lodNode = doc.createNode(`${node.getName() || entry.name}_LOD${level}`).setMesh(mesh)
+        .setTranslation(node.getTranslation()).setRotation(node.getRotation()).setScale(node.getScale())
+      if (node.getSkin()) lodNode.setSkin(node.getSkin())
+      lodNode.setExtras({ lecodes: { lod: { level, ratio, tris } } })
+      if (parent) parent.addChild(lodNode)
+      else for (const s of scenes) s.addChild(lodNode)
+      levels.push(tris)
+      if (plan.bones && i === plan.ratios.length - 1 && node.getSkin()) {
+        const r = reduceSkinForLod(doc, lodNode)
+        if (r) result.bones.push({ name: entry.name, ...r })
+      }
+    }
+    result.nodes++
+    result.tris.push({ name: entry.name, levels })
+  }
+  return result
+}

package/src/doctor/merge/accessors.ts

@@ -0,0 +1,30 @@
+// Accessor reads as flat typed arrays.
+
+import type { Accessor, Primitive } from '@gltf-transform/core'
+
+export const readAttr = (acc: Accessor): { size: number; data: Float32Array } => {
+  const size = acc.getElementSize(), n = acc.getCount()
+  const data = new Float32Array(n * size)
+  const el = new Array<number>(size)
+  for (let i = 0; i < n; i++) { acc.getElement(i, el); for (let k = 0; k < size; k++) data[i * size + k] = el[k] }
+  return { size, data }
+}
+export const readIndices = (p: Primitive): Uint32Array => {
+  const idx = p.getIndices()
+  if (idx) return Uint32Array.from(idx.getArray() as ArrayLike<number>)
+  const n = p.getAttribute('POSITION')!.getCount()
+  return Uint32Array.from({ length: n }, (_, i) => i)
+}
+/** Area-weighted vertex normals for a primitive that has none. */
+export function flatNormals(pos: Float32Array, idx: Uint32Array): Float32Array {
+  const n = new Float32Array(pos.length)
+  for (let t = 0; t + 2 < idx.length; t += 3) {
+    const a = idx[t] * 3, b = idx[t + 1] * 3, c = idx[t + 2] * 3
+    const ux = pos[b] - pos[a], uy = pos[b + 1] - pos[a + 1], uz = pos[b + 2] - pos[a + 2]
+    const vx = pos[c] - pos[a], vy = pos[c + 1] - pos[a + 1], vz = pos[c + 2] - pos[a + 2]
+    const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx
+    for (const i of [ a, b, c ]) { n[i] += nx; n[i + 1] += ny; n[i + 2] += nz }
+  }
+  for (let i = 0; i < n.length; i += 3) { const l = Math.hypot(n[i], n[i + 1], n[i + 2]) || 1; n[i] /= l; n[i + 1] /= l; n[i + 2] /= l }
+  return n
+}

package/src/doctor/merge/atlasLayout.ts

@@ -0,0 +1,94 @@
+// Atlas layout: one tile per distinct material look, shelf-packed into a power-of-two square, scaled
+// down BY SURFACE AREA (equal texel density) when the cap is hit.
+
+import type { Material, Texture } from '@gltf-transform/core'
+import type { MatInfo } from './classify'
+import type { AtlasLayout, MapKind, Tile } from './types'
+
+function shelfPack(items: { w: number; h: number }[], S: number): { x: number; y: number }[] | null {
+  const order = items.map((_, i) => i).sort((a, b) => items[b].h - items[a].h || items[b].w - items[a].w)
+  const pos: { x: number; y: number }[] = new Array(items.length)
+  let x = 0, y = 0, rowH = 0
+  for (const i of order) {
+    const { w, h } = items[i]
+    if (w > S || h > S) return null
+    if (x + w > S) { y += rowH; x = 0; rowH = 0 }
+    if (y + h > S) return null
+    pos[i] = { x, y }; x += w; rowH = Math.max(rowH, h)
+  }
+  return pos
+}
+
+/** Tile scales for a texel-density budget `D` (texels² per m² of surface): the tile's used texels
+ *  (edge² × UV coverage) per square metre of the material's surface reach D, capped at the native map. */
+const scalesForDensity = (tiles: Tile[], D: number): number[] => tiles.map((t) => {
+  const uv = Math.max(0.02, t.uvArea), area = Math.max(1e-6, t.area)
+  return Math.min(1, Math.sqrt(D * area / uv / (t.srcW * t.srcH)))
+})
+
+function layoutTiles(tiles: Tile[], atlasSize: number, pad: number, uniform: boolean): { size: number; scale: number; scaleMax: number } | null {
+  const place = (S: number, scales: number[]): boolean => {
+    const items = tiles.map((t, i) => ({ w: Math.max(4, Math.round(t.srcW * scales[i])) + 2 * pad, h: Math.max(4, Math.round(t.srcH * scales[i])) + 2 * pad }))
+    const pos = shelfPack(items, S)
+    if (!pos) return false
+    tiles.forEach((t, i) => { t.w = items[i].w - 2 * pad; t.h = items[i].h - 2 * pad; t.x = pos[i].x + pad; t.y = pos[i].y + pad; t.scale = t.w / t.srcW })
+    return true
+  }
+  const ones = tiles.map(() => 1)
+  const done = (S: number) => ({ size: S, scale: Math.min(...tiles.map((t) => t.scale)), scaleMax: Math.max(...tiles.map((t) => t.scale)) })
+  // the smallest power-of-two square that holds everything at full resolution …
+  for (let S = 64; S <= atlasSize; S *= 2) if (place(S, ones)) return done(S)
+  if (place(atlasSize, ones)) return done(atlasSize)
+  // … else the cap, with the tiles scaled down as little as possible: one factor for all, or a texel-density
+  // budget that gives every part the same texels per metre (the density at which the densest part is native
+  // is the upper bound — above it nothing changes)
+  const scalesAt = uniform ? (x: number) => tiles.map(() => x) : (x: number) => scalesForDensity(tiles, x)
+  let lo = 0, hi = uniform ? 1 : Math.max(...tiles.map((t) => t.srcW * t.srcH * Math.max(0.02, t.uvArea) / Math.max(1e-6, t.area)))
+  for (let i = 0; i < 40; i++) { const mid = (lo + hi) / 2; if (place(atlasSize, scalesAt(mid))) lo = mid; else hi = mid }
+  if (lo === 0 || !place(atlasSize, scalesAt(lo))) return null
+  return done(atlasSize)
+}
+
+function tileKey(info: MatInfo, texId: (t: Texture) => string): string {
+  const m = info.material
+  const id = (t?: Texture) => (t ? texId(t) : '-')
+  return [
+    id(info.maps.base), m.getBaseColorFactor().map((v) => v.toFixed(4)).join(','),
+    id(info.maps.normal), m.getNormalScale().toFixed(3),
+    id(info.maps.mr), id(info.maps.occ), m.getRoughnessFactor().toFixed(3), m.getMetallicFactor().toFixed(3), m.getOcclusionStrength().toFixed(3),
+    id(info.maps.emissive), m.getEmissiveFactor().map((v) => v.toFixed(4)).join(','),
+    info.uv ? `${info.uv.u0},${info.uv.v0},${info.uv.ru},${info.uv.rv}` : '-',
+  ].join('|')
+}
+
+export function planAtlas(infos: MatInfo[], atlasSize: number, pad: number, uniform: boolean, texId: (t: Texture) => string): { layout: AtlasLayout | null; reason?: string } {
+  const anyTex = (k: keyof MatInfo['maps']) => infos.some((i) => i.maps[k])
+  const differ = (f: (m: Material) => number[]) => { const first = f(infos[0].material); return infos.some((i) => f(i.material).some((v, k) => Math.abs(v - first[k]) > 1e-4)) }
+  const maps: MapKind[] = []
+  if (anyTex('base') || differ((m) => m.getBaseColorFactor())) maps.push('base')
+  if (anyTex('normal')) maps.push('normal')
+  if (anyTex('mr') || anyTex('occ') || differ((m) => [ m.getRoughnessFactor(), m.getMetallicFactor() ])) maps.push('orm')
+  if (anyTex('emissive') || infos.some((i) => i.material.getEmissiveFactor().some((v) => v > 0))) maps.push('emissive')
+  const byKey = new Map<string, Tile>()
+  for (const info of infos) {
+    const key = tileKey(info, texId)
+    let t = byKey.get(key)
+    if (!t) {
+      const dims = Object.values(info.sizes)
+      const uv = info.uv ?? { u0: 0, v0: 0, ru: 1, rv: 1 }
+      const maxW = dims.length ? Math.max(...dims.map((d) => d[0])) : 8
+      const maxH = dims.length ? Math.max(...dims.map((d) => d[1])) : 8
+      const cap = atlasSize - 2 * pad
+      t = { key, materials: [], srcW: Math.min(cap, maxW * uv.ru), srcH: Math.min(cap, maxH * uv.rv), ...uv, area: 0, uvArea: 0, w: 0, h: 0, x: 0, y: 0, scale: 1 }
+      byKey.set(key, t)
+    }
+    t.materials.push(info.material)
+    t.area += info.area
+    t.uvArea = Math.min(1, t.uvArea + info.uvArea)
+  }
+  const tiles = [ ...byKey.values() ]
+  const fit = layoutTiles(tiles, atlasSize, pad, uniform)
+  if (!fit) return { layout: null, reason: `${tiles.length} tiles do not fit a ${atlasSize}² atlas (raise --atlas-size or lower --atlas-pad)` }
+  const hasAlpha = infos[0].material.getAlphaMode() !== 'OPAQUE'
+  return { layout: { size: fit.size, scale: fit.scale, scaleMax: fit.scaleMax, byArea: !uniform, pad, maps, tiles, hasAlpha } }
+}