lecodes-assets 0.2.0 → 0.2.1

package/src/doctor/normalizeScale.ts

@@ -0,0 +1,220 @@
+// Scale normalization — bring a model to real-world metres before it reaches creator-gl.
+//
+// Exporters routinely ship a model at 1/100 (the Blender/FBX "armature scale 0.01" quirk), in cm, or
+// in inches. Nothing in the file records that, and the SDK carries no unit metadata — the asset just
+// turns up 5 mm across in a scene and every consumer needs its own magic multiplier.
+//
+//   measure : the RENDERED world size. Skinned primitives do not use their node's matrix (the glTF
+//             spec says a skinned mesh node's transform is ignored) — they land at world(joint)×IBM,
+//             so that is what we measure them with.
+//   plan    : an explicit factor, a target largest-dimension, or an auto unit guess.
+//   apply   : BAKES the factor into the data — positions, node translations, IBM offsets and
+//             translation tracks all × s. Local scales are left alone, so no wrapper node appears
+//             and every node path stays what it was.
+//
+// Why the bake is those four edits and nothing else: scaling every translation by s and leaving
+// every rotation/scale block alone gives world' = S·world·S⁻¹ for every node (S = uniform s). For a
+// skinned vertex, Σw·world'·IBM'·(s·v) == s·(Σw·world·IBM·v) holds exactly when IBM' = S·IBM·S⁻¹,
+// and S·IBM·S⁻¹ is just IBM with its translation column × s.
+import type { Accessor, Document } from '@gltf-transform/core'
+
+const FLOAT = 5126
+
+/** A model whose largest dimension lands outside this (metres) is almost certainly mis-scaled. */
+export const PLAUSIBLE_MIN = 0.1
+export const PLAUSIBLE_MAX = 100
+
+// Multiply-by factors we are willing to guess, with what they mean. Ordered by |ln f| so the first
+// in-band hit is the SMALLEST correction that explains the model.
+const CANDIDATES: { f: number; label: string }[] = [
+  { f: 100, label: 'cm units / the 0.01 armature-scale export quirk' },
+  { f: 0.01, label: '100× too big (metre values authored as cm)' },
+  { f: 0.3048, label: 'feet' },
+  { f: 0.0254, label: 'inches' },
+  { f: 1000, label: 'mm units' },
+  { f: 0.001, label: '1000× too big' },
+].sort((a, b) => Math.abs(Math.log(a.f)) - Math.abs(Math.log(b.f)))
+
+type Vec3 = [number, number, number]
+export interface ScaleInfo {
+  dims: Vec3            // rendered world size, metres
+  largest: number
+  suggested: number     // auto factor (1 = looks fine, or no candidate explains it)
+  label: string
+  suspicious: boolean
+}
+export interface ScalePlan { factor: number; before: Vec3; after: Vec3; source: 'auto' | 'explicit' | 'fit'; label: string }
+
+const mul = (a: number[], b: number[]): number[] => {
+  const o = new Array(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
+}
+const applyMat = (m: number[], v: number[]): Vec3 => [
+  m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12],
+  m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13],
+  m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14],
+]
+
+/** Rendered world-space bounds of every mesh in the document, or null when there is no geometry. */
+export function sceneBounds(doc: Document): { min: Vec3; max: Vec3; dims: Vec3 } | null {
+  const cache = new Map<object, number[]>()
+  const world = (n: any): number[] => {
+    const hit = cache.get(n)
+    if (hit) return hit
+    const parent = n.getParentNode()
+    const local = Array.from(n.getMatrix() as ArrayLike<number>)
+    const w = parent ? mul(world(parent), local) : local
+    cache.set(n, w)
+    return w
+  }
+  const min: Vec3 = [ Infinity, Infinity, Infinity ], max: Vec3 = [ -Infinity, -Infinity, -Infinity ]
+  let any = false
+  for (const node of doc.getRoot().listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh) continue
+    // A skinned primitive ignores its node's transform: at rest it lands at world(joint₀)·IBM₀, the
+    // skin's bind space (constant across joints for a sane rig — probe reports the deviation).
+    let m = world(node)
+    const skin = node.getSkin()
+    if (skin) {
+      const joints = skin.listJoints()
+      const ibm = skin.getInverseBindMatrices()
+      if (joints.length && ibm) m = mul(world(joints[0]), ibm.getElement(0, []))
+      else if (joints.length) m = world(joints[0])
+    }
+    for (const prim of mesh.listPrimitives()) {
+      const pos = prim.getAttribute('POSITION')
+      if (!pos) continue
+      const lo = pos.getMin([]), hi = pos.getMax([])
+      for (let corner = 0; corner < 8; corner++) {
+        const p = applyMat(m, [ corner & 1 ? hi[0] : lo[0], corner & 2 ? hi[1] : lo[1], corner & 4 ? hi[2] : lo[2] ])
+        for (let i = 0; i < 3; i++) { min[i] = Math.min(min[i], p[i]); max[i] = Math.max(max[i], p[i]) }
+      }
+      any = true
+    }
+  }
+  if (!any) return null
+  return { min, max, dims: [ max[0] - min[0], max[1] - min[1], max[2] - min[2] ] }
+}
+
+/** Measure the document and guess whether (and by how much) it is mis-scaled. */
+export function measureScale(doc: Document): ScaleInfo | null {
+  const b = sceneBounds(doc)
+  if (!b) return null
+  const largest = Math.max(...b.dims)
+  if (!(largest > 0)) return null
+  const inBand = (x: number): boolean => x >= PLAUSIBLE_MIN && x <= PLAUSIBLE_MAX
+  if (inBand(largest)) return { dims: b.dims, largest, suggested: 1, label: 'plausible', suspicious: false }
+  const hit = CANDIDATES.find((c) => inBand(largest * c.f))
+  return {
+    dims: b.dims,
+    largest,
+    suggested: hit?.f ?? 1,
+    label: hit?.label ?? 'no standard unit factor explains this size — pass --scale-to',
+    suspicious: true,
+  }
+}
+
+export interface ScaleOptions { scale?: number; scaleTo?: number; fixScale?: boolean }
+
+/** Turn options + measurement into a concrete plan, or null when there is nothing to do. */
+export function planScale(info: ScaleInfo | null, opts: ScaleOptions): ScalePlan | null {
+  let factor = 1
+  let source: ScalePlan['source'] = 'auto'
+  let label = info?.label ?? ''
+  if (opts.scale !== undefined) {
+    // An explicit factor needs no measurement — it still applies to a clip-only file with no geometry.
+    factor = opts.scale; source = 'explicit'; label = 'explicit factor'
+  } else if (opts.scaleTo !== undefined) {
+    if (!info) throw new Error('--scale-to needs geometry to measure; this file has no meshes — use --scale <factor>')
+    factor = opts.scaleTo / info.largest; source = 'fit'; label = `largest dimension → ${opts.scaleTo} m`
+  } else if (opts.fixScale) {
+    if (!info) return null
+    factor = info.suggested
+  }
+  if (!(factor > 0) || !Number.isFinite(factor)) throw new Error(`bad scale factor ${factor}`)
+  if (Math.abs(factor - 1) < 1e-9) return null
+  const before: Vec3 = info?.dims ?? [ 0, 0, 0 ]
+  return { factor, before, after: before.map((d) => d * factor) as Vec3, source, label }
+}
+
+const scaleAccessor = (acc: Accessor, s: number, what: string): void => {
+  if (acc.getComponentType() !== FLOAT) throw new Error(`cannot scale quantized/normalized ${what} (component type ${acc.getComponentType()}) — dequantize first`)
+  const src = acc.getArray()!
+  const out = new Float32Array(src.length)
+  for (let i = 0; i < src.length; i++) out[i] = src[i] * s
+  acc.setArray(out)
+}
+
+export interface ScaleResult { positions: number; nodes: number; skins: number; tracks: number; cameras: number; lights: number }
+
+/** Bake a uniform scale into the document (mutates). Adds no nodes and changes no local scales. */
+export function applyScale(doc: Document, s: number): ScaleResult {
+  const root = doc.getRoot()
+  const res: ScaleResult = { positions: 0, nodes: 0, skins: 0, tracks: 0, cameras: 0, lights: 0 }
+
+  const seen = new Set<Accessor>()
+  const once = (acc: Accessor | null, what: string): void => {
+    if (!acc || seen.has(acc)) return
+    seen.add(acc)
+    scaleAccessor(acc, s, what)
+    res.positions++
+  }
+  for (const mesh of root.listMeshes()) for (const prim of mesh.listPrimitives()) {
+    once(prim.getAttribute('POSITION'), 'POSITION')
+    for (const target of prim.listTargets()) once(target.getAttribute('POSITION'), 'morph POSITION')
+  }
+
+  for (const node of root.listNodes()) {
+    const t = node.getTranslation()
+    if (t[0] || t[1] || t[2]) { node.setTranslation([ t[0] * s, t[1] * s, t[2] * s ]); res.nodes++ }
+  }
+
+  // IBM' = S·IBM·S⁻¹ — the 3×3 block is untouched, only the offset moves.
+  for (const skin of root.listSkins()) {
+    const ibm = skin.getInverseBindMatrices()
+    if (!ibm) continue
+    const m: number[] = []
+    for (let i = 0; i < ibm.getCount(); i++) {
+      ibm.getElement(i, m)
+      m[12] *= s; m[13] *= s; m[14] *= s
+      ibm.setElement(i, m)
+    }
+    res.skins++
+  }
+
+  // Translation tracks only — rotation and scale tracks live in the untouched 3×3 block.
+  for (const anim of root.listAnimations()) {
+    const moves = new Set<Accessor>(), keeps = new Set<Accessor>()
+    for (const ch of anim.listChannels()) {
+      const out = ch.getSampler()?.getOutput()
+      if (out) (ch.getTargetPath() === 'translation' ? moves : keeps).add(out)
+    }
+    for (const acc of moves) {
+      if (keeps.has(acc)) throw new Error(`animation "${anim.getName()}" shares one output accessor between translation and other channels — cannot scale safely`)
+      if (seen.has(acc)) continue
+      seen.add(acc)
+      scaleAccessor(acc, s, 'translation track')
+      res.tracks++
+    }
+  }
+
+  for (const cam of root.listCameras()) {
+    cam.setZNear(cam.getZNear() * s)
+    const zf = cam.getZFar()
+    if (zf) cam.setZFar(zf * s)
+    if (cam.getType() === 'orthographic') { cam.setXMag(cam.getXMag() * s); cam.setYMag(cam.getYMag() * s) }
+    res.cameras++
+  }
+
+  // KHR_lights_punctual: range is a distance; intensity is candela/lux and does not scale with size.
+  for (const node of root.listNodes()) {
+    const light = node.getExtension('KHR_lights_punctual') as { getRange?: () => number | null; setRange?: (r: number) => unknown } | null
+    if (!light?.getRange || !light.setRange) continue
+    const range = light.getRange()
+    if (range) light.setRange(range * s)
+    res.lights++
+  }
+  return res
+}

package/src/doctor/reduceGlbBones.ts

@@ -0,0 +1,218 @@
+// Skin bone-count reduction for filament's CONFIG_MAX_BONE_COUNT (256), without Blender.
+// Split into PLAN (pure analysis, no mutation) and APPLY (mutation) so the same logic powers
+// both the analyzer and the fixer in glbDoctor.ts.
+//
+//   Pass 1 — drop joints not bound to any vertex (leftover IK / control bones)  -> LOSSLESS
+//   Pass 2 — drop the deepest remaining joints, merging their weights into the
+//            nearest surviving ancestor joint, until each skin has <= target    -> LOSSY
+import { NodeIO, type Document, type Skin, type Node as GltfNode, type Primitive, type Accessor } from '@gltf-transform/core'
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions'
+import { MeshoptDecoder, MeshoptEncoder } from 'meshoptimizer'
+
+export const DEFAULT_TARGET = 256
+const WEIGHT_EPS = 1e-5
+
+export interface PrimSet { j: Accessor; w: Accessor }
+export interface PrimEntry { prim: Primitive; sets: PrimSet[] }
+
+export interface SkinPlan {
+  skin: Skin
+  skinIdx: number
+  name: string
+  before: number
+  after: number
+  removedUnbound: number
+  removedDeep: number
+  prims: PrimEntry[]
+  // internals reused by applySkinPlan:
+  joints: GltfNode[]
+  removeSet: Set<number>
+  kept: number[]
+  newPos: Map<number, number>
+  mergeTarget: Int32Array
+}
+
+export function makeIO(): NodeIO {
+  return new NodeIO()
+    .registerExtensions(ALL_EXTENSIONS)
+    .registerDependencies({ 'meshopt.decoder': MeshoptDecoder, 'meshopt.encoder': MeshoptEncoder })
+}
+
+/** Meshopt codecs are WASM — must be ready before any read/write. */
+export async function ensureCodecs(): Promise<void> {
+  await MeshoptDecoder.ready
+  await MeshoptEncoder.ready
+}
+
+/** Group every skinned primitive under the single skin that uses it. */
+export function gatherSkinPrims(doc: Document): { bySkin: Map<Skin, PrimEntry[]>; conflicts: number } {
+  const owner = new Map<Primitive, Skin>()
+  const bySkin = new Map<Skin, PrimEntry[]>()
+  let conflicts = 0
+  for (const node of doc.getRoot().listNodes()) {
+    const skin = node.getSkin(), mesh = node.getMesh()
+    if (!skin || !mesh) continue
+    for (const prim of mesh.listPrimitives()) {
+      if (!prim.getAttribute('JOINTS_0')) continue
+      const prev = owner.get(prim)
+      if (prev) { if (prev !== skin) conflicts++; continue }
+      owner.set(prim, skin)
+      const sets: PrimSet[] = []
+      for (let s = 0; ; s++) {
+        const j = prim.getAttribute(`JOINTS_${s}`), w = prim.getAttribute(`WEIGHTS_${s}`)
+        if (!j || !w) break
+        sets.push({ j, w })
+      }
+      ;(bySkin.get(skin) ?? bySkin.set(skin, []).get(skin)!).push({ prim, sets })
+    }
+  }
+  return { bySkin, conflicts }
+}
+
+function depthOf(node: GltfNode): number {
+  let d = 0, p = node.getParentNode()
+  while (p) { d++; p = p.getParentNode() }
+  return d
+}
+
+/** Pure: decide which joints to drop. No mutation. */
+export function planSkin(skin: Skin, skinIdx: number, prims: PrimEntry[], target: number): SkinPlan {
+  const joints = skin.listJoints()
+  const N = joints.length
+  const name = skin.getName() || `skin[${skinIdx}]`
+  const posOf = new Map<GltfNode, number>(joints.map((n, i) => [n, i]))
+  const removeSet = new Set<number>()
+
+  const empty: SkinPlan = {
+    skin, skinIdx, name, before: N, after: N, removedUnbound: 0, removedDeep: 0,
+    prims, joints, removeSet, kept: [...Array(N).keys()], newPos: new Map(), mergeTarget: new Int32Array(N).fill(-1),
+  }
+  if (N <= target || prims.length === 0) return empty
+
+  // total weight per joint position across all primitives of this skin
+  const total = new Float64Array(N)
+  const je: number[] = [0, 0, 0, 0], we: number[] = [0, 0, 0, 0]
+  for (const { sets } of prims) {
+    for (const { j, w } of sets) {
+      const c = j.getCount()
+      for (let v = 0; v < c; v++) {
+        j.getElement(v, je); w.getElement(v, we)
+        for (let k = 0; k < 4; k++) if (we[k] > 0) total[je[k]] += we[k]
+      }
+    }
+  }
+
+  // Pass 1 — unbound
+  for (let i = 0; i < N; i++) if (total[i] <= WEIGHT_EPS) removeSet.add(i)
+  const removedUnbound = removeSet.size
+
+  // Pass 2 — deepest-first, only if still over budget
+  const depth = joints.map(depthOf)
+  const nearestKept = (i: number): number => {
+    let p = joints[i].getParentNode()
+    while (p) { const pos = posOf.get(p); if (pos !== undefined && !removeSet.has(pos)) return pos; p = p.getParentNode() }
+    return -1
+  }
+  let remaining = N - removeSet.size, removedDeep = 0
+  if (remaining > target) {
+    const order = [...Array(N).keys()].filter((i) => !removeSet.has(i))
+      .sort((a, b) => depth[b] - depth[a] || joints[b].getName().localeCompare(joints[a].getName()))
+    for (const i of order) {
+      if (remaining <= target) break
+      if (nearestKept(i) === -1) continue
+      removeSet.add(i); remaining--; removedDeep++
+    }
+  }
+
+  const kept = [...Array(N).keys()].filter((i) => !removeSet.has(i))
+  const newPos = new Map<number, number>(kept.map((old, ni) => [old, ni]))
+  const mergeTarget = new Int32Array(N).fill(-1)
+  for (const i of removeSet) {
+    let p = joints[i].getParentNode(), t = -1
+    while (p) { const pos = posOf.get(p); if (pos !== undefined && !removeSet.has(pos)) { t = pos; break } p = p.getParentNode() }
+    mergeTarget[i] = t
+  }
+
+  return { skin, skinIdx, name, before: N, after: kept.length, removedUnbound, removedDeep, prims, joints, removeSet, kept, newPos, mergeTarget }
+}
+
+/** Mutating: rewrite skinning attributes + skin joints/IBM per the plan. Returns dropped weight. */
+export function applySkinPlan(doc: Document, plan: SkinPlan): number {
+  const { skin, joints, removeSet, kept, newPos, mergeTarget, prims } = plan
+  if (removeSet.size === 0) return 0
+
+  const finalPos = (old: number): number => {
+    const np = newPos.get(old)
+    if (np !== undefined) return np
+    const t = mergeTarget[old]
+    return t < 0 ? -1 : newPos.get(t)!
+  }
+
+  let droppedWeight = 0
+  for (const { prim, sets } of prims) {
+    const c = sets[0].j.getCount()
+    const numSets = sets.length
+    const cap = 4 * numSets
+    const outJ = sets.map(() => new Array(c * 4).fill(0))
+    const outW = sets.map(() => new Array(c * 4).fill(0))
+    let maxInfluences = 0
+    const jv: number[] = [0, 0, 0, 0], wv: number[] = [0, 0, 0, 0]
+
+    for (let v = 0; v < c; v++) {
+      const acc = new Map<number, number>()
+      for (const { j, w } of sets) {
+        j.getElement(v, jv); w.getElement(v, wv)
+        for (let k = 0; k < 4; k++) {
+          const ww = wv[k]
+          if (ww <= 0) continue
+          const fp = finalPos(jv[k])
+          if (fp < 0) { droppedWeight += ww; continue }
+          acc.set(fp, (acc.get(fp) || 0) + ww)
+        }
+      }
+      let pairs = [...acc.entries()].sort((a, b) => b[1] - a[1])
+      if (pairs.length > cap) pairs = pairs.slice(0, cap)
+      maxInfluences = Math.max(maxInfluences, pairs.length)
+      let sum = 0; for (const p of pairs) sum += p[1]; if (sum <= 0) sum = 1
+      for (let s = 0; s < numSets; s++)
+        for (let k = 0; k < 4; k++) {
+          const idx = s * 4 + k
+          if (idx < pairs.length) { outJ[s][v * 4 + k] = pairs[idx][0]; outW[s][v * 4 + k] = pairs[idx][1] / sum }
+        }
+    }
+
+    for (let s = 0; s < numSets; s++) {
+      const Ja = sets[s].j, Wa = sets[s].w
+      for (let v = 0; v < c; v++) {
+        Ja.setElement(v, [outJ[s][v * 4], outJ[s][v * 4 + 1], outJ[s][v * 4 + 2], outJ[s][v * 4 + 3]])
+        Wa.setElement(v, [outW[s][v * 4], outW[s][v * 4 + 1], outW[s][v * 4 + 2], outW[s][v * 4 + 3]])
+      }
+    }
+    const neededSets = Math.max(1, Math.ceil(maxInfluences / 4))
+    for (let s = neededSets; s < numSets; s++) { prim.setAttribute(`JOINTS_${s}`, null); prim.setAttribute(`WEIGHTS_${s}`, null) }
+  }
+
+  const oldIbm = skin.getInverseBindMatrices()
+  if (oldIbm) {
+    const m: number[] = new Array(16).fill(0)
+    const arr = new Float32Array(kept.length * 16)
+    for (let ni = 0; ni < kept.length; ni++) { oldIbm.getElement(kept[ni], m); arr.set(m, ni * 16) }
+    const newIbm = doc.createAccessor(`${plan.name}_ibm`).setType('MAT4').setArray(arr).setBuffer(doc.getRoot().listBuffers()[0])
+    skin.setInverseBindMatrices(newIbm)
+    if (!doc.getRoot().listSkins().some((s) => s.getInverseBindMatrices() === oldIbm)) oldIbm.dispose()
+  }
+  for (const i of removeSet) skin.removeJoint(joints[i])
+  return droppedWeight
+}
+
+// Convenience one-shot (bones only), kept for standalone use.
+export async function reduceGlbBones(inputPath: string, outputPath: string, target = DEFAULT_TARGET): Promise<SkinPlan[]> {
+  await ensureCodecs()
+  const io = makeIO()
+  const doc = await io.read(inputPath)
+  const { bySkin } = gatherSkinPrims(doc)
+  const plans = doc.getRoot().listSkins().map((skin, i) => planSkin(skin, i, bySkin.get(skin) ?? [], target))
+  for (const p of plans) applySkinPlan(doc, p)
+  await io.write(outputPath, doc)
+  return plans
+}

package/src/doctor/shading.ts

@@ -0,0 +1,95 @@
+// Shading pass — the two material quirks that make an exported model render far brighter than the
+// art it was painted from, plus the flat-colour (unlit) conversion stylised assets usually want.
+//
+// SELF-LIT. A PBR material's emissive is meant for the parts that GLOW. Several exporters (and
+// Sketchfab's own download path) instead wire the BASE COLOUR texture into `emissiveTexture` with
+// `emissiveFactor = [1,1,1]`, so the shader adds a full copy of the albedo on top of the lit result:
+//
+//     out = lit(baseColor) + baseColor        instead of        out = lit(baseColor)
+//
+// Under any decent IBL that is ~2× too bright — the model looks washed out and loses its shading,
+// and the usual first suspects (metallic, the texture itself) are innocent.
+//
+// SPECULAR BOOST. `KHR_materials_specular` with a `specularColorFactor` above 1 is the same story
+// for the highlight. gltfio ALSO refuses to combine it with unlit ("Cannot use specular extension
+// with unlit"), so an unlit conversion must drop it or the shading model silently reverts to lit.
+import { KHRMaterialsUnlit } from '@gltf-transform/extensions'
+import type { Document, Material } from '@gltf-transform/core'
+
+const DROP_ON_UNLIT = [
+  'KHR_materials_specular', 'KHR_materials_ior', 'KHR_materials_sheen', 'KHR_materials_clearcoat',
+  'KHR_materials_transmission', 'KHR_materials_volume', 'KHR_materials_iridescence',
+  'KHR_materials_anisotropy', 'KHR_materials_dispersion',
+]
+
+export interface ShadingIssue {
+  mat: Material
+  name: string
+  /** emissive is a full copy of the base colour — the model renders ~2× too bright */
+  selfLit: boolean
+  /** highest component of a `KHR_materials_specular` colour factor above 1, else 0 */
+  specularBoost: number
+  /** already flat-shaded via KHR_materials_unlit */
+  unlit: boolean
+}
+export interface ShadingPlan { issues: ShadingIssue[]; unlit: boolean; fixEmissive: boolean }
+export interface ShadingOptions { unlit?: boolean; fixEmissive?: boolean }
+
+const specularOf = (m: Material): number => {
+  const spec = m.getExtension('KHR_materials_specular') as unknown as { getSpecularColorFactor?: () => number[] } | null
+  const f = spec?.getSpecularColorFactor?.() ?? []
+  return Math.max(0, ...f.map((v) => (v > 1 ? v : 0)))
+}
+
+export function analyzeShading(doc: Document, opts: ShadingOptions = {}): ShadingPlan {
+  const issues: ShadingIssue[] = []
+  for (const mat of doc.getRoot().listMaterials()) {
+    const emissive = mat.getEmissiveFactor()
+    const emTex = mat.getEmissiveTexture()
+    // "A full copy" means the emissive channel carries the albedo at (near) full strength: either
+    // literally the same Texture object, or — for untextured materials — a white emissive factor.
+    const strong = Math.max(...emissive) >= 0.5
+    const selfLit = strong && (emTex ? emTex === mat.getBaseColorTexture() : true)
+    const specularBoost = specularOf(mat)
+    const unlit = mat.listExtensions().some((e) => e.extensionName === 'KHR_materials_unlit')
+    if (selfLit || specularBoost > 0 || (opts.unlit && !unlit)) {
+      issues.push({ mat, name: mat.getName() || '?', selfLit, specularBoost, unlit })
+    }
+  }
+  return { issues, unlit: !!opts.unlit, fixEmissive: !!opts.fixEmissive }
+}
+
+export interface ShadingResult { unlit: number; emissiveCleared: number; extensionsDropped: number }
+
+export function applyShading(doc: Document, plan: ShadingPlan): ShadingResult {
+  const res: ShadingResult = { unlit: 0, emissiveCleared: 0, extensionsDropped: 0 }
+  if (!plan.unlit && !plan.fixEmissive) return res
+  const unlitExt = plan.unlit ? doc.createExtension(KHRMaterialsUnlit) : null
+  for (const { mat, selfLit, unlit } of plan.issues) {
+    // Unlit shades baseColorFactor × baseColorTexture and nothing else, so the emissive copy has to
+    // go either way — left in place a lit fallback would still double the albedo.
+    if (plan.unlit || (plan.fixEmissive && selfLit)) {
+      if (Math.max(...mat.getEmissiveFactor()) > 0 || mat.getEmissiveTexture()) {
+        mat.setEmissiveFactor([ 0, 0, 0 ]).setEmissiveTexture(null)
+        res.emissiveCleared++
+      }
+    }
+    if (!plan.unlit) continue
+    if (!unlit) { mat.setExtension('KHR_materials_unlit', unlitExt!.createUnlit()); res.unlit++ }
+    for (const name of DROP_ON_UNLIT) {
+      if (mat.getExtension(name)) { mat.setExtension(name, null); res.extensionsDropped++ }
+    }
+    // Inputs an unlit shader never reads: keep the file honest so a lit viewer that ignores the
+    // extension still renders the flat colour rather than a stray highlight.
+    mat.setMetallicFactor(0).setRoughnessFactor(1)
+      .setMetallicRoughnessTexture(null).setNormalTexture(null).setOcclusionTexture(null)
+  }
+  // Unlinking the property is not enough: the Extension stays registered on the document and keeps
+  // writing its name into `extensionsUsed`. Drop it once no material references it at all.
+  const materials = doc.getRoot().listMaterials()
+  for (const ext of doc.getRoot().listExtensionsUsed()) {
+    if (!DROP_ON_UNLIT.includes(ext.extensionName)) continue
+    if (!materials.some((m) => m.getExtension(ext.extensionName))) ext.dispose()
+  }
+  return res
+}

package/src/doctor/transcodeKtx2.ts

@@ -0,0 +1,124 @@
+// KTX2 / Basis-Universal encoding via KTX-Software's `toktx` (filament supports image/ktx2 through
+// createKtx2Provider — GPU-compressed, supports alpha, smaller on disk AND in VRAM).
+//
+// Codec by texture role:
+//   - colour (base/emissive)            -> ETC1S, sRGB   (small, lossy)
+//   - data  (normal/metalRough/occ.)    -> UASTC + zstd, linear  (precise)
+// …unless `codecPolicy: 'uastc'` asks for UASTC everywhere. That is for HERO assets — a
+// first-person weapon or gloves fill a third of the screen at 30 cm, where ETC1S's block artifacts
+// on the base colour are plainly visible. World props stay on the default: ETC1S is the right
+// trade there and the size difference is roughly 8x.
+// Mipmaps are generated; alpha is preserved (ETC1S/UASTC both encode it).
+import sharp from 'sharp'
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { Root, Texture } from '@gltf-transform/core'
+import { getTextureRoles, DEFAULT_MAX_SIZE } from './transcodeTextures'
+
+/** Locate the toktx binary: $KTX_TOKTX → %LOCALAPPDATA%\Programs\KTX-Software → PATH. */
+export function findToktx(): string {
+  const env = process.env.KTX_TOKTX
+  if (env && existsSync(env)) return env
+  const la = process.env.LOCALAPPDATA
+  if (la) {
+    const guess = join(la, 'Programs', 'KTX-Software', 'bin', 'toktx.exe')
+    if (existsSync(guess)) return guess
+  }
+  return 'toktx' // assume on PATH
+}
+
+export function checkToktx(toktx: string): string | null {
+  try {
+    const p = spawnSync(toktx, ['--version'], { encoding: 'utf8' })
+    if (p.status === 0) return (p.stdout ?? '').toString().trim() || 'toktx'
+  } catch { /* not found */ }
+  return null
+}
+
+export interface Ktx2Plan {
+  tex: Texture
+  name: string
+  roles: string
+  fromFmt: string
+  codec: 'etc1s' | 'uastc'
+  oetf: 'srgb' | 'linear'
+  resize: boolean
+  width: number
+  height: number
+  hasAlpha: boolean
+  beforeBytes: number
+  afterBytes?: number
+  category: 'lossy'
+  reason: string
+}
+
+export type CodecPolicy = 'default' | 'hq' | 'uastc'
+
+export async function planKtx2(tex: Texture, root: Root, maxSize = DEFAULT_MAX_SIZE, policy: CodecPolicy = 'hq'): Promise<Ktx2Plan | null> {
+  const img = tex.getImage()
+  const mime = tex.getMimeType() || ''
+  const fromFmt = mime.replace('image/', '') || '?'
+  if (!img || fromFmt.includes('ktx')) return null // missing or already ktx2
+
+  const { roles, isNormal, isData } = getTextureRoles(tex, root)
+  let width = 0, height = 0, hasAlpha = false
+  try {
+    const b = Buffer.from(img)
+    const m = await sharp(b).metadata()
+    width = m.width || 0; height = m.height || 0
+    hasAlpha = !(await sharp(b).stats()).isOpaque
+  } catch {
+    return null
+  }
+
+  // Normally only normal maps justify UASTC (high quality, ~8bpp): colour and metalRough/occlusion
+  // compress far smaller with ETC1S at acceptable quality. 'uastc' overrides that for hero assets.
+  // oetf: linear for any non-colour data.
+  const codec: 'etc1s' | 'uastc' =
+    policy === 'uastc' ? 'uastc'
+    : isNormal ? (policy === 'hq' ? 'uastc' : 'etc1s')
+    : 'etc1s'
+  const oetf: 'srgb' | 'linear' = isNormal || isData ? 'linear' : 'srgb'
+  const resize = Math.max(width, height) > maxSize
+  return {
+    tex, name: tex.getName() || '?', roles, fromFmt, codec, oetf, resize, width, height, hasAlpha,
+    beforeBytes: img.length, category: 'lossy',
+    reason: `${fromFmt} → ktx2/${codec}${hasAlpha ? '+alpha' : ''}${resize ? ` (≤${maxSize}px)` : ''}`,
+  }
+}
+
+export async function applyKtx2(plan: Ktx2Plan, toktx: string, maxSize = DEFAULT_MAX_SIZE): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), 'glbktx-'))
+  const inPng = join(dir, 'in.png')
+  const outKtx = join(dir, 'out.ktx2')
+  try {
+    // GPU block-compressed formats (BC7/BC3/ETC2, 4×4 blocks) require the texture's base dimensions
+    // to be MULTIPLES OF 4 — otherwise filament's glTexStorage2D fails ("Invalid compressed image
+    // size") and the texture renders broken. Snap dims to ×4 (and apply the maxSize cap) before toktx.
+    const snap4 = (n: number) => Math.max(4, Math.round(n / 4) * 4)
+    let tw = plan.width, th = plan.height
+    const m = Math.max(tw, th)
+    if (m > maxSize) { const s = maxSize / m; tw = tw * s; th = th * s }
+    tw = snap4(tw); th = snap4(th)
+
+    let pipe = sharp(Buffer.from(plan.tex.getImage()!))
+    if (tw !== plan.width || th !== plan.height) pipe = pipe.resize({ width: tw, height: th, fit: 'fill' })
+    if (!plan.hasAlpha) pipe = pipe.removeAlpha() // RGB → no wasted alpha slice
+    writeFileSync(inPng, await pipe.png().toBuffer())
+
+    const args = plan.codec === 'etc1s'
+      ? ['--encode', 'etc1s', '--clevel', '2', '--qlevel', '128', '--genmipmap', '--assign_oetf', plan.oetf, outKtx, inPng]
+      : ['--encode', 'uastc', '--uastc_quality', '2', '--zcmp', '18', '--genmipmap', '--assign_oetf', plan.oetf, outKtx, inPng]
+
+    const proc = spawnSync(toktx, args, { encoding: 'utf8' })
+    if (proc.status !== 0) throw new Error(`toktx failed (exit ${proc.status}) for "${plan.name}": ${(proc.stderr ?? '').toString().slice(0, 300)}`)
+
+    const ktx = readFileSync(outKtx)
+    plan.tex.setImage(new Uint8Array(ktx)).setMimeType('image/ktx2')
+    plan.afterBytes = ktx.length
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}