lecodes-assets 0.2.0 → 2.4.10

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
+}

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
+}