lecodes-assets 0.2.1 → 2.5.0

package/src/unwrap/lightmapUv.ts

@@ -0,0 +1,761 @@
+// The lightmap unwrap — `lecodes assets unwrap` (./index.ts), and `lecodes lightmap bake` before it bakes: a second
+// texture-coordinate set (TEXCOORD_1) that lays every triangle of the file out in ONE non-overlapping unit square, made
+// by xatlas (vendor/xatlas, run as wasm — src/wasm/lightmapUv.js). This is what the lightmap bake samples and writes
+// (engines/bake): each placed instance of the prop gets a rectangle of the scene atlas, so the props stay clones and one
+// unwrap per file is enough.
+//
+// WHAT COUNTS IS THE CUTTING. The bake re-packs a file's uv1-connected charts itself (engines/bake README, "THE CHARTS
+// ARE PACKED PER FILE": MaxRects at the instances' density, its own gutter, the `<stem>-uv1.bin` sidecar), so xatlas's
+// packing here only matters where the bake keeps the unwrap's square as it is (a file whose TEXCOORD_1 a texture reads,
+// a mesh under two groups, CBK_PACK_CHARTS=0): the padding is a fixed UNWRAP_PADDING texels of the bake's texel
+// (`--texel`). The decisions the bake cannot take back are the charts, the groups and the zone's texel scales.
+//
+// xatlas RE-INDEXES the mesh: a vertex that sits on a chart seam is split into one copy per chart,
+// and every output vertex carries `xref`, the input vertex it came from. So this pass rebuilds every
+// attribute (positions, normals, UV0, colours, joints/weights, tangents, morph targets) by that map,
+// preserving each accessor's component type and normalization, and widens the index buffer past
+// 65535 when the split pushes it there. Skinned meshes are left alone: a lightmap is baked in ONE
+// pose, and a rigged character never stays in it.
+//
+// GROUPS (`--groups <n>`): ONE unit square = ONE atlas rect in the bake, and a rect cannot span
+// pages — a whole level exported as one GLB (the arena: 133 m, 800k triangles) got one 8192 page at 7 cm
+// and no way to ask for more. With groups the mesh nodes are split into n parts of equal surface by
+// bisecting their world centroids (neighbours stay together), each part is unwrapped into a unit square
+// of ITS OWN, and every node carries `extras.lightmapGroup = k`. The bake describes one instance per
+// group (`<key>#k`, creator-gl lightmap_bake.cpp), the runtime binds each group's page and rect to the
+// group's renderables (glb.cpp lightmapBind) — one file, no texture paid twice.
+//
+// THE PLAYER'S ZONE (`--zone "x0,y0,z0,x1,y1,z1[;…]"`, with groups): a level is not seen from everywhere —
+// an arena's player walks the sand, and 5 cm texels on tiers 40 m away are texels nobody can tell apart. The zone is
+// the boxes the player can be in (world metres; the entrances of a passage count, the dark passage behind need not).
+// A triangle's TEXEL SCALE follows its distance d to the zone: 1 within `--zone-near` (12 m), 2 to twice
+// that, 4 beyond — a texel stays about the same size ON SCREEN. Scales never share a group: a large mesh that spans
+// them (the seating bowl) is cut along them, a small one takes its finest. A group of scale s is unwrapped with its
+// padding measured in ITS texels, carries `extras.lightmapTexelScale = s`, and the bake lays it out s times coarser
+// (CbakeInstanceDesc.texelScale): a 16th of the texels at 4.
+//
+// LOD siblings (`<name>_LOD<n>`, n ≥ 1 — the kit's own or `doctor --lod`'s) are NOT unwrapped: the
+// engine's lightmap pass traces level 0 only and binds ONE atlas rect per instance, which every
+// level reads. So level 0 gets the xatlas layout and the LODs get level 0's UV1 by PROJECTION: each
+// LOD triangle's centroid picks the closest level-0 triangle and with it a chart, and each corner
+// takes the UV of its closest point on that chart (a corner that straddles charts is split, like a
+// seam vertex). A decimated surface then samples the very texels its full-detail twin was traced
+// into — no atlas paid twice, no LOD reading texels nothing lit (the two-features-corrupt-each-other
+// bug of fps-demo FEEDBACK 92).
+import type { Accessor, Document, Mesh, Node as GltfNode, Primitive } from '@gltf-transform/core'
+// @ts-ignore — generated by build-wasm.sh (Emscripten single-file module)
+import createLightmapUv from '../wasm/lightmapUv.js'
+
+const TRIANGLES = 4
+
+type Module = {
+  _malloc(n: number): number
+  _free(p: number): void
+  _lmuv_begin(hint: number): number
+  _lmuv_add_mesh(h: number, pos: number, normals: number, uv: number, vertexCount: number, indices: number, indexCount: number): number
+  _lmuv_generate(h: number, padding: number, iterations: number, texelsPerUnit: number): number
+  _lmuv_width(h: number): number
+  _lmuv_height(h: number): number
+  _lmuv_chart_count(h: number): number
+  _lmuv_mesh_count(h: number): number
+  _lmuv_mesh_vertex_count(h: number, i: number): number
+  _lmuv_mesh_index_count(h: number, i: number): number
+  _lmuv_mesh_xref(h: number, i: number): number
+  _lmuv_mesh_uv(h: number, i: number): number
+  _lmuv_mesh_indices(h: number, i: number): number
+  _lmuv_error(): number
+  _lmuv_end(h: number): void
+  HEAPU8: Uint8Array
+  HEAPU32: Uint32Array
+  HEAPF32: Float32Array
+  UTF8ToString(ptr: number): string
+}
+
+let modulePromise: Promise<Module> | undefined
+const getModule = (): Promise<Module> => (modulePromise ??= (createLightmapUv as () => Promise<Module>)())
+
+export interface UnwrapOptions {
+  /** the bake's texel in metres the (fixed) chart padding is measured in (0.05, `lecodes lightmap bake --texel`); 0 = xatlas's auto density */
+  texel?: number
+  /** xatlas chart-growing iterations — more = better charts, slower (default 1) */
+  iterations?: number
+  /** split the file's meshes into this many groups, each with a unit square (an atlas rect) of its own (default 1) */
+  groups?: number
+  /** the boxes the player can be in, world metres: "x0,y0,z0,x1,y1,z1[;…]" — what is far from them gets a coarser texel (needs groups) */
+  zone?: string
+  /** the distance to the zone within which the texel is the full one; the scale doubles every such distance past it (default 12) */
+  zoneNear?: number
+  /** the coarsest texel scale, a power of two: the doubling stops there (default 4 = twenty centimetres at a 5 cm texel) */
+  zoneMax?: number
+  /** the weight of the VERTICAL distance to the zone (default 1): 2 = a metre of height counts as two metres of reach, so
+   *  an arena's upper tiers go coarse before the far end of the pitch does */
+  zoneUp?: number
+}
+
+export interface UnwrapPrim { mesh: Mesh; prim: Primitive; name: string; triangles: number; vertices: number; hasUv1: boolean }
+/** A LOD sibling's primitive: takes its UV1 from `baseNode`'s (level-0) mesh by projection. */
+export interface UnwrapLod { mesh: Mesh; prim: Primitive; node: GltfNode; baseNode: GltfNode; level: number; name: string; triangles: number; hasUv1: boolean }
+export interface UnwrapPlan {
+  prims: UnwrapPrim[]
+  lods: UnwrapLod[]
+  skipped: { name: string; reason: string }[]
+  padding: number
+  iterations: number
+  /** the bake's density the padding is measured in: 1 / its texel (metres); 0 = xatlas's own auto density */
+  texelsPerUnit: number
+  /** how many unit squares the file's meshes are split into (1 = the classic single layout) */
+  groups: number
+  /** the player's zone: boxes [x0,y0,z0,x1,y1,z1] in world metres (empty = one texel everywhere) and its near distance */
+  zones: number[][]
+  zoneNear: number
+  zoneMax: number
+  zoneUp: number
+}
+
+/** texels between charts in xatlas's own packing — what the bake reads only where it keeps the unwrap's square (see the top) */
+export const UNWRAP_PADDING = 4
+/** `lecodes lightmap bake`'s default texel (metres): the unwrap keeps UNWRAP_PADDING texels of THIS size between charts */
+export const DEFAULT_UNWRAP_TEXEL = 0.05
+
+const LOD_SUFFIX = /_LOD(\d+)$/
+/** "<base>_LOD<n>" → n (≥ 1), else 0 — the suffix creator-gl's lod.cpp groups renderables by. */
+export const lodLevelOf = (name: string): number => { const m = LOD_SUFFIX.exec(name); return m ? Number(m[1]) : 0 }
+
+const primName = (mesh: Mesh, i: number): string => `${mesh.getName() || 'mesh'}${mesh.listPrimitives().length > 1 ? `[${i}]` : ''}`
+
+const parseZones = (text: string | undefined): number[][] => {
+  if (!text) return []
+  return text.split(';').map((t) => t.trim()).filter(Boolean).map((t) => {
+    const v = t.split(',').map(Number)
+    if (v.length !== 6 || v.some((x) => !Number.isFinite(x))) throw new Error(`--zone: "${t}" is not x0,y0,z0,x1,y1,z1`)
+    return [ Math.min(v[0], v[3]), Math.min(v[1], v[4]), Math.min(v[2], v[5]), Math.max(v[0], v[3]), Math.max(v[1], v[4]), Math.max(v[2], v[5]) ]
+  })
+}
+
+/** The texel scale of a world point: 1 within `near` of the zone, then doubling every `near` metres (2 to twice near, 4 to three
+ *  times, 8 …) up to `zoneMax` (1 when there is no zone). The distance is to the zone's boxes, the vertical part weighed by
+ *  `zoneUp` (the arena, 2026-09-18: with 1 the upper tiers, 15-20 m up and 25 m out, stayed at x4; with 2 they are x8 / x16). */
+const texelScaleAt = (plan: UnwrapPlan, x: number, y: number, z: number): number => {
+  if (plan.zones.length === 0) return 1
+  let d = Infinity
+  for (const b of plan.zones) {
+    const dx = Math.max(b[0] - x, 0, x - b[3]), dy = Math.max(b[1] - y, 0, y - b[4]), dz = Math.max(b[2] - z, 0, z - b[5])
+    d = Math.min(d, Math.hypot(dx, dy * plan.zoneUp, dz))
+  }
+  return Math.min(plan.zoneMax, 2 ** Math.floor(d / plan.zoneNear))
+}
+
+/** What the unwrap would do to `doc` (pure): the primitives it lays out, the LOD siblings it projects, what it leaves. */
+export function planUnwrap(doc: Document, opts: UnwrapOptions = {}): UnwrapPlan {
+  const root = doc.getRoot()
+  const skinnedMeshes = new Set<Mesh>()
+  const byName = new Map<string, GltfNode>()
+  for (const node of root.listNodes()) {
+    const mesh = node.getMesh()
+    if (mesh && node.getSkin()) skinnedMeshes.add(mesh)
+    if (mesh && node.getName() && !byName.has(node.getName())) byName.set(node.getName(), node)
+  }
+  // LOD siblings: a mesh drawn by a `<base>_LOD<n≥1>` node whose level-0 node (`<base>` or
+  // `<base>_LOD0`) has a mesh of its own; a mesh SHARED with level 0 needs nothing.
+  const lodMeshes = new Map<Mesh, { node: GltfNode; baseNode: GltfNode; level: number }>()
+  const level0Meshes = new Set<Mesh>()
+  for (const node of root.listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh) continue
+    if (lodLevelOf(node.getName()) === 0) level0Meshes.add(mesh)
+  }
+  for (const node of root.listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh || level0Meshes.has(mesh) || lodMeshes.has(mesh)) continue
+    const level = lodLevelOf(node.getName())
+    if (level === 0) continue
+    const base = node.getName().replace(LOD_SUFFIX, '')
+    const baseNode = byName.get(base) ?? byName.get(`${base}_LOD0`)
+    if (!baseNode || !baseNode.getMesh() || baseNode.getMesh() === mesh || skinnedMeshes.has(baseNode.getMesh()!)) continue
+    lodMeshes.set(mesh, { node, baseNode, level })
+  }
+  const prims: UnwrapPrim[] = []
+  const lods: UnwrapLod[] = []
+  const skipped: { name: string; reason: string }[] = []
+  for (const mesh of root.listMeshes()) {
+    const lod = lodMeshes.get(mesh)
+    mesh.listPrimitives().forEach((prim, i) => {
+      const name = primName(mesh, i)
+      const pos = prim.getAttribute('POSITION')
+      if (!pos || pos.getCount() === 0) { skipped.push({ name, reason: 'no positions' }); return }
+      if (prim.getMode() !== TRIANGLES) { skipped.push({ name, reason: 'not a triangle list' }); return }
+      if (skinnedMeshes.has(mesh)) { skipped.push({ name, reason: 'skinned' }); return }
+      const idx = prim.getIndices()
+      const triangles = Math.floor((idx ? idx.getCount() : pos.getCount()) / 3)
+      if (triangles === 0) { skipped.push({ name, reason: 'no triangles' }); return }
+      const hasUv1 = !!prim.getAttribute('TEXCOORD_1')
+      if (lod) { lods.push({ mesh, prim, node: lod.node, baseNode: lod.baseNode, level: lod.level, name, triangles, hasUv1 }); return }
+      prims.push({ mesh, prim, name, triangles, vertices: pos.getCount(), hasUv1 })
+    })
+  }
+  const texel = opts.texel ?? DEFAULT_UNWRAP_TEXEL
+  return {
+    prims, lods, skipped,
+    padding: UNWRAP_PADDING,
+    iterations: Math.max(1, Math.floor(opts.iterations ?? 1)),
+    texelsPerUnit: texel > 0 ? 1 / texel : 0,
+    groups: Math.max(1, Math.min(256, Math.floor(opts.groups ?? 1))),
+    zones: parseZones(opts.zone),
+    zoneNear: opts.zoneNear && opts.zoneNear > 0 ? opts.zoneNear : 12,
+    zoneMax: opts.zoneMax && opts.zoneMax > 1 ? 2 ** Math.round(Math.log2(opts.zoneMax)) : opts.zoneMax === 1 ? 1 : 4,
+    zoneUp: opts.zoneUp && opts.zoneUp > 0 ? opts.zoneUp : 1,
+  }
+}
+
+/** True when the unwrap has something to do: a primitive it lays out (or a LOD sibling it projects onto one) without a
+ *  TEXCOORD_1. A file whose every such primitive carries one is left alone unless forced. */
+export const planNeedsUnwrap = (plan: UnwrapPlan): boolean =>
+  plan.prims.length > 0 && (plan.prims.some((p) => !p.hasUv1) || plan.lods.some((l) => !l.hasUv1))
+
+export interface UnwrapGroup { primitives: number; charts: number; width: number; height: number; area: number; texelScale: number }
+export interface UnwrapResult {
+  primitives: number; charts: number; width: number; height: number; verticesBefore: number; verticesAfter: number
+  /** one entry per unit square when the file was split (`--groups`), else empty */
+  groups: UnwrapGroup[]
+  /** nodes added by cutting meshes larger than a group's share (splitLargeMeshes) */
+  splitNodes: number
+  /** LOD primitives that took level 0's layout by projection, and the vertices they hold afterwards */
+  lodPrimitives: number; lodVertices: number
+}
+
+/** Every element of `acc` as floats (dequantized), `size` per element. */
+const floats = (acc: Accessor, size: number): Float32Array => {
+  const n = acc.getCount()
+  const out = new Float32Array(n * size)
+  const el: number[] = new Array(acc.getElementSize()).fill(0)
+  for (let i = 0; i < n; i++) { acc.getElement(i, el); for (let k = 0; k < size; k++) out[i * size + k] = el[k] ?? 0 }
+  return out
+}
+
+/** A copy of `acc` with its elements reordered by `xref` — same type, component type, normalization. */
+const remapAccessor = (doc: Document, acc: Accessor, xref: Uint32Array, buffer: ReturnType<Document['createBuffer']>): Accessor => {
+  const src = acc.getArray()!
+  const es = acc.getElementSize()
+  const Ctor = src.constructor as { new (n: number): typeof src }
+  const out = new Ctor(xref.length * es)
+  for (let v = 0; v < xref.length; v++) {
+    const s = xref[v] * es
+    for (let k = 0; k < es; k++) out[v * es + k] = src[s + k]
+  }
+  return doc.createAccessor(acc.getName()).setType(acc.getType()).setNormalized(acc.getNormalized()).setArray(out).setBuffer(buffer)
+}
+
+/** Rebuild a primitive's attributes, morph targets and indices by `xref` (re-indexed geometry) and give it `uv1`. */
+const reindexPrimitive = (doc: Document, prim: Primitive, xref: Uint32Array, indices32: Uint32Array<ArrayBuffer>, uv1: Float32Array<ArrayBuffer>,
+                          buffer: ReturnType<Document['createBuffer']>, retired: Set<Accessor>): void => {
+  for (const semantic of prim.listSemantics()) {
+    const acc = prim.getAttribute(semantic)!
+    if (semantic === 'TEXCOORD_1') { retired.add(acc); continue }   // replaced below
+    retired.add(acc)
+    prim.setAttribute(semantic, remapAccessor(doc, acc, xref, buffer))
+  }
+  for (const target of prim.listTargets()) {
+    for (const semantic of target.listSemantics()) {
+      const acc = target.getAttribute(semantic)!
+      retired.add(acc)
+      target.setAttribute(semantic, remapAccessor(doc, acc, xref, buffer))
+    }
+  }
+  const oldIdx = prim.getIndices()
+  if (oldIdx) retired.add(oldIdx)
+  const indices = xref.length <= 65535 ? Uint16Array.from(indices32) : indices32
+  prim.setIndices(doc.createAccessor().setType('SCALAR').setArray(indices).setBuffer(buffer))
+  prim.setAttribute('TEXCOORD_1', doc.createAccessor('lightmap_uv').setType('VEC2').setArray(uv1).setBuffer(buffer))
+}
+
+// ---- LOD projection ------------------------------------------------------------------------------
+
+const xformPoint = (m: number[], x: number, y: number, z: number, out: Float32Array, o: number): void => {
+  out[o] = m[0] * x + m[4] * y + m[8] * z + m[12]
+  out[o + 1] = m[1] * x + m[5] * y + m[9] * z + m[13]
+  out[o + 2] = m[2] * x + m[6] * y + m[10] * z + m[14]
+}
+
+/** Level 0's triangles in world space with their UV1 and chart, on a uniform grid for nearest-point queries. */
+class BaseSurface {
+  readonly tris: Float32Array       // 9 floats per triangle (world positions)
+  readonly uvs: Float32Array        // 6 floats per triangle
+  readonly chart: Int32Array        // chart id per triangle (an xatlas chart = connected output vertices)
+  readonly count: number
+  private readonly min = [ 0, 0, 0 ]
+  private readonly cell: number
+  private readonly dims = [ 1, 1, 1 ]
+  private readonly cells = new Map<number, number[]>()
+
+  constructor(node: GltfNode) {
+    const world = node.getWorldMatrix()
+    const triPos: number[] = [], triUv: number[] = [], triChart: number[] = []
+    let chartBase = 0
+    for (const prim of node.getMesh()!.listPrimitives()) {
+      const pos = prim.getAttribute('POSITION'), uv1 = prim.getAttribute('TEXCOORD_1')
+      if (!pos || !uv1 || prim.getMode() !== TRIANGLES) continue
+      const idxAcc = prim.getIndices()
+      const idx = idxAcc ? idxAcc.getArray()! : Uint32Array.from({ length: pos.getCount() }, (_, i) => i)
+      const p = floats(pos, 3), u = floats(uv1, 2)
+      // charts = connected components over the (seam-split) index buffer
+      const parent = Int32Array.from({ length: pos.getCount() }, (_, i) => i)
+      const find = (a: number): number => { while (parent[a] !== a) { parent[a] = parent[parent[a]]; a = parent[a] } return a }
+      for (let i = 0; i + 2 < idx.length; i += 3) {
+        const a = find(idx[i]), b = find(idx[i + 1]), c = find(idx[i + 2])
+        parent[b] = a; parent[find(c)] = find(a)
+      }
+      const chartOf = new Map<number, number>()
+      for (let i = 0; i + 2 < idx.length; i += 3) {
+        const r = find(idx[i])
+        let ch = chartOf.get(r)
+        if (ch === undefined) { ch = chartBase + chartOf.size; chartOf.set(r, ch) }
+        const w = new Float32Array(9)
+        for (let k = 0; k < 3; k++) { const v = idx[i + k]; xformPoint(world, p[v * 3], p[v * 3 + 1], p[v * 3 + 2], w, k * 3); triUv.push(u[v * 2], u[v * 2 + 1]) }
+        for (let k = 0; k < 9; k++) triPos.push(w[k])
+        triChart.push(ch)
+      }
+      chartBase += chartOf.size
+    }
+    this.tris = Float32Array.from(triPos); this.uvs = Float32Array.from(triUv); this.chart = Int32Array.from(triChart)
+    this.count = triChart.length
+    if (this.count === 0) { this.cell = 1; return }
+    const min = [ Infinity, Infinity, Infinity ], max = [ -Infinity, -Infinity, -Infinity ]
+    for (let i = 0; i < this.tris.length; i += 3) for (let k = 0; k < 3; k++) { min[k] = Math.min(min[k], this.tris[i + k]); max[k] = Math.max(max[k], this.tris[i + k]) }
+    const ext = [ max[0] - min[0], max[1] - min[1], max[2] - min[2] ]
+    const longest = Math.max(ext[0], ext[1], ext[2], 1e-6)
+    // ~4 triangles per cell along the longest axis, 48 cells at most: a crate's 10k triangles land in a few hundred cells
+    this.cell = Math.max(longest / Math.min(48, Math.max(4, Math.cbrt(this.count) * 2)), 1e-5)
+    this.min = [ min[0] - this.cell * 0.5, min[1] - this.cell * 0.5, min[2] - this.cell * 0.5 ]
+    this.dims = ext.map((e) => Math.max(1, Math.ceil(e / this.cell) + 1))
+    for (let t = 0; t < this.count; t++) {
+      const lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+      for (let k = 0; k < 3; k++) for (let a = 0; a < 3; a++) { const v = this.tris[t * 9 + k * 3 + a]; lo[a] = Math.min(lo[a], v); hi[a] = Math.max(hi[a], v) }
+      const c0 = this.cellOf(lo), c1 = this.cellOf(hi)
+      for (let z = c0[2]; z <= c1[2]; z++) for (let y = c0[1]; y <= c1[1]; y++) for (let x = c0[0]; x <= c1[0]; x++) {
+        const key = this.key(x, y, z)
+        let list = this.cells.get(key)
+        if (!list) { list = []; this.cells.set(key, list) }
+        list.push(t)
+      }
+    }
+  }
+
+  private cellOf(p: ArrayLike<number>): number[] {
+    return [ 0, 1, 2 ].map((a) => Math.min(this.dims[a] - 1, Math.max(0, Math.floor((p[a] - this.min[a]) / this.cell))))
+  }
+  private key(x: number, y: number, z: number): number { return (z * this.dims[1] + y) * this.dims[0] + x }
+
+  /** Closest point on triangle `t` to `p` (Ericson, Real-Time Collision Detection 5.1.5): squared distance + barycentrics. */
+  private closest(t: number, p: number[], out: { d2: number; b: number[] }): void {
+    const T = this.tris, o = t * 9
+    const ax = T[o], ay = T[o + 1], az = T[o + 2], bx = T[o + 3], by = T[o + 4], bz = T[o + 5], cx = T[o + 6], cy = T[o + 7], cz = T[o + 8]
+    const abx = bx - ax, aby = by - ay, abz = bz - az, acx = cx - ax, acy = cy - ay, acz = cz - az
+    const apx = p[0] - ax, apy = p[1] - ay, apz = p[2] - az
+    const d1 = abx * apx + aby * apy + abz * apz, d2 = acx * apx + acy * apy + acz * apz
+    let u: number, v: number, w: number
+    if (d1 <= 0 && d2 <= 0) { u = 1; v = 0; w = 0 } else {
+      const bpx = p[0] - bx, bpy = p[1] - by, bpz = p[2] - bz
+      const d3 = abx * bpx + aby * bpy + abz * bpz, d4 = acx * bpx + acy * bpy + acz * bpz
+      if (d3 >= 0 && d4 <= d3) { u = 0; v = 1; w = 0 } else {
+        const vc = d1 * d4 - d3 * d2
+        if (vc <= 0 && d1 >= 0 && d3 <= 0) { v = d1 / (d1 - d3); u = 1 - v; w = 0 } else {
+          const cpx = p[0] - cx, cpy = p[1] - cy, cpz = p[2] - cz
+          const d5 = abx * cpx + aby * cpy + abz * cpz, d6 = acx * cpx + acy * cpy + acz * cpz
+          if (d6 >= 0 && d5 <= d6) { u = 0; v = 0; w = 1 } else {
+            const vb = d5 * d2 - d1 * d6
+            if (vb <= 0 && d2 >= 0 && d6 <= 0) { w = d2 / (d2 - d6); u = 1 - w; v = 0 } else {
+              const va = d3 * d6 - d5 * d4
+              if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0) { w = (d4 - d3) / ((d4 - d3) + (d5 - d6)); v = 1 - w; u = 0 } else {
+                const denom = 1 / (va + vb + vc)
+                v = vb * denom; w = vc * denom; u = 1 - v - w
+              }
+            }
+          }
+        }
+      }
+    }
+    const qx = ax * u + bx * v + cx * w, qy = ay * u + by * v + cy * w, qz = az * u + bz * v + cz * w
+    out.d2 = (qx - p[0]) ** 2 + (qy - p[1]) ** 2 + (qz - p[2]) ** 2
+    out.b[0] = u; out.b[1] = v; out.b[2] = w
+  }
+
+  /** The closest triangle to `p` (within chart `chart` when ≥ 0) and the barycentrics of the closest point; -1 = none. */
+  nearest(p: number[], chart: number, bary: number[]): number {
+    if (this.count === 0) return -1
+    const c = this.cellOf(p)
+    let best = -1, bestD2 = Infinity
+    const tmp = { d2: 0, b: [ 0, 0, 0 ] }
+    const maxR = Math.max(this.dims[0], this.dims[1], this.dims[2])
+    for (let r = 0; r <= maxR; r++) {
+      // everything not yet visited lies at least (r − 1) cells away: stop once the best is closer than that
+      if (best >= 0 && Math.sqrt(bestD2) <= (r - 1) * this.cell) break
+      for (let z = c[2] - r; z <= c[2] + r; z++) {
+        if (z < 0 || z >= this.dims[2]) continue
+        for (let y = c[1] - r; y <= c[1] + r; y++) {
+          if (y < 0 || y >= this.dims[1]) continue
+          const edgeYZ = Math.abs(z - c[2]) === r || Math.abs(y - c[1]) === r
+          for (let x = c[0] - r; x <= c[0] + r; x++) {
+            if (x < 0 || x >= this.dims[0]) continue
+            if (!edgeYZ && Math.abs(x - c[0]) !== r) continue   // only the ring's shell
+            const list = this.cells.get(this.key(x, y, z))
+            if (!list) continue
+            for (const t of list) {
+              if (chart >= 0 && this.chart[t] !== chart) continue
+              this.closest(t, p, tmp)
+              if (tmp.d2 < bestD2) { bestD2 = tmp.d2; best = t; bary[0] = tmp.b[0]; bary[1] = tmp.b[1]; bary[2] = tmp.b[2] }
+            }
+          }
+        }
+      }
+    }
+    return best
+  }
+
+  uvAt(t: number, bary: number[], out: Float32Array, o: number): void {
+    const U = this.uvs, k = t * 6
+    out[o] = U[k] * bary[0] + U[k + 2] * bary[1] + U[k + 4] * bary[2]
+    out[o + 1] = U[k + 1] * bary[0] + U[k + 3] * bary[1] + U[k + 5] * bary[2]
+  }
+}
+
+/** Give a LOD primitive level 0's UV1: per triangle the centroid picks a chart, per corner the closest point on it. */
+const projectLodPrimitive = (doc: Document, lod: UnwrapLod, base: BaseSurface, buffer: ReturnType<Document['createBuffer']>,
+                             retired: Set<Accessor>): number => {
+  const prim = lod.prim
+  const pos = prim.getAttribute('POSITION')!
+  const idxAcc = prim.getIndices()
+  const idx = idxAcc ? Uint32Array.from(idxAcc.getArray()!) : Uint32Array.from({ length: pos.getCount() }, (_, i) => i)
+  const local = floats(pos, 3)
+  const world = lod.node.getWorldMatrix()
+  const wp = new Float32Array(local.length)
+  for (let v = 0; v < pos.getCount(); v++) xformPoint(world, local[v * 3], local[v * 3 + 1], local[v * 3 + 2], wp, v * 3)
+  const xref: number[] = [], uv: number[] = [], out: number[] = []
+  const slot = new Map<number, number>()   // (vertex, chart) → output vertex
+  const bary = [ 0, 0, 0 ]
+  const centroid = [ 0, 0, 0 ], corner = [ 0, 0, 0 ]
+  const uv2 = new Float32Array(2)
+  for (let i = 0; i + 2 < idx.length; i += 3) {
+    for (let a = 0; a < 3; a++) centroid[a] = (wp[idx[i] * 3 + a] + wp[idx[i + 1] * 3 + a] + wp[idx[i + 2] * 3 + a]) / 3
+    const ct = base.nearest(centroid, -1, bary)
+    const chart = ct >= 0 ? base.chart[ct] : -1
+    for (let k = 0; k < 3; k++) {
+      const v = idx[i + k]
+      const key = v * 65536 + (chart + 1)
+      let o = slot.get(key)
+      if (o === undefined) {
+        corner[0] = wp[v * 3]; corner[1] = wp[v * 3 + 1]; corner[2] = wp[v * 3 + 2]
+        let t = base.nearest(corner, chart, bary)
+        if (t < 0) t = base.nearest(corner, -1, bary)
+        if (t >= 0) base.uvAt(t, bary, uv2, 0); else { uv2[0] = 0; uv2[1] = 0 }
+        o = xref.length
+        slot.set(key, o)
+        xref.push(v); uv.push(uv2[0], uv2[1])
+      }
+      out.push(o)
+    }
+  }
+  reindexPrimitive(doc, prim, Uint32Array.from(xref), Uint32Array.from(out), Float32Array.from(uv), buffer, retired)
+  return xref.length
+}
+
+/** A MESH LARGER THAN A GROUP'S SHARE IS CUT INTO SEVERAL NODES first (the arena's seating bowl: one mesh, 43 % of the
+ *  level's surface - 6454 texels of layout at 5 cm, which no 4096 page holds and no grouping of whole meshes can help).
+ *  Its triangles are bisected by their world centroids into k = ceil(area / share) parts; part 0 stays in the mesh, the
+ *  others become sibling nodes `<name>_lm<i>` with the same transform and material. Left whole: a mesh drawn by several
+ *  nodes, one with morph targets, one that has LOD siblings. Returns how many nodes were added. */
+const splitLargeMeshes = (doc: Document, plan: UnwrapPlan, buffer: ReturnType<Document['createBuffer']>, retired: Set<Accessor>): number => {
+  const root = doc.getRoot()
+  const users = new Map<Mesh, GltfNode[]>()
+  for (const node of root.listNodes()) { const mesh = node.getMesh(); if (mesh) users.set(mesh, [ ...(users.get(mesh) ?? []), node ]) }
+  const lodBases = new Set(plan.lods.map((l) => l.baseNode.getMesh()!))
+  type Tri = { prim: Primitive; i: number; c: number[]; area: number; cls: number }
+  const perMesh = new Map<Mesh, Tri[]>()
+  let total = 0
+  const w = new Float32Array(9)
+  for (const p of plan.prims) {
+    const node = users.get(p.mesh)?.[0]
+    const m = node ? node.getWorldMatrix() : [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ]
+    const pos = floats(p.prim.getAttribute('POSITION')!, 3)
+    const idxAcc = p.prim.getIndices()
+    const idx = idxAcc ? idxAcc.getArray()! : Uint32Array.from({ length: pos.length / 3 }, (_, i) => i)
+    const list = perMesh.get(p.mesh) ?? []
+    for (let i = 0; i + 2 < idx.length; i += 3) {
+      for (let k = 0; k < 3; k++) { const v = idx[i + k]; xformPoint(m, pos[v * 3], pos[v * 3 + 1], pos[v * 3 + 2], w, k * 3) }
+      const ux = w[3] - w[0], uy = w[4] - w[1], uz = w[5] - w[2], vx = w[6] - w[0], vy = w[7] - w[1], vz = w[8] - w[2]
+      const area = 0.5 * Math.hypot(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx)
+      const c = [ (w[0] + w[3] + w[6]) / 3, (w[1] + w[4] + w[7]) / 3, (w[2] + w[5] + w[8]) / 3 ]
+      list.push({ prim: p.prim, i, c, area, cls: texelScaleAt(plan, c[0], c[1], c[2]) })
+    }
+    perMesh.set(p.mesh, list)
+  }
+  // A mesh spans texel scales (the zone): it is cut along them when what it has in the coarser ones is worth a cut;
+  // else it is one piece at its finest. Shares are in EFFECTIVE area (area / scale²) - what the atlas pays.
+  const kMinCoarseArea = 50
+  const buckets = new Map<Mesh, Map<number, Tri[]>>()
+  for (const [ mesh, tris ] of perMesh) {
+    const finest = tris.reduce((a, t) => Math.min(a, t.cls), plan.zoneMax)
+    const coarseArea = tris.reduce((a, t) => a + (t.cls > finest ? t.area : 0), 0)
+    const byCls = new Map<number, Tri[]>()
+    for (const t of tris) {
+      const cls = coarseArea >= kMinCoarseArea ? t.cls : finest
+      byCls.set(cls, [ ...(byCls.get(cls) ?? []), t ])
+    }
+    buckets.set(mesh, byCls)
+    for (const [ cls, list ] of byCls) total += list.reduce((a, t) => a + t.area, 0) / (cls * cls)
+  }
+  const share = total / plan.groups
+  let added = 0
+  for (const [ mesh, byCls ] of buckets) {
+    const nodes = users.get(mesh) ?? []
+    const want = [ ...byCls ].map(([ cls, list ]) => ({ list, parts: Math.min(64, Math.max(1, Math.ceil(list.reduce((a, t) => a + t.area, 0) / (cls * cls) / share))) }))
+    if (want.reduce((a, b) => a + b.parts, 0) < 2 || nodes.length !== 1 || lodBases.has(mesh) || mesh.listPrimitives().some((q) => q.listTargets().length > 0)) continue
+    const node = nodes[0]
+    const out: Tri[][] = []
+    const bisect = (list: Tri[], n: number): void => {
+      if (n <= 1 || list.length <= 1) { out.push(list); return }
+      const lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+      for (const t of list) for (let k = 0; k < 3; k++) { lo[k] = Math.min(lo[k], t.c[k]); hi[k] = Math.max(hi[k], t.c[k]) }
+      let axis = 0
+      for (let k = 1; k < 3; k++) if (hi[k] - lo[k] > hi[axis] - lo[axis]) axis = k
+      list.sort((p, q) => p.c[axis] - q.c[axis])
+      const nl = Math.floor(n / 2)
+      const want = list.reduce((a, t) => a + t.area, 0) * nl / n
+      let acc = 0, cut = 0
+      while (cut < list.length - 1 && acc < want) acc += list[cut++].area
+      bisect(list.slice(0, Math.max(1, cut)), nl)
+      bisect(list.slice(Math.max(1, cut)), n - nl)
+    }
+    for (const b of want) bisect(b.list, b.parts)
+    // a part's triangles of one primitive -> a compact primitive (attributes remapped like a seam split)
+    const build = (prim: Primitive, list: Tri[], into: Primitive): void => {
+      const idxAcc = prim.getIndices()
+      const idx = idxAcc ? idxAcc.getArray()! : null
+      const slot = new Map<number, number>(), xref: number[] = [], indices: number[] = []
+      for (const t of list) for (let k = 0; k < 3; k++) {
+        const v = idx ? idx[t.i + k] : t.i + k
+        let o = slot.get(v)
+        if (o === undefined) { o = xref.length; slot.set(v, o); xref.push(v) }
+        indices.push(o)
+      }
+      const x = Uint32Array.from(xref)
+      for (const semantic of prim.listSemantics()) into.setAttribute(semantic, remapAccessor(doc, prim.getAttribute(semantic)!, x, buffer))
+      into.setIndices(doc.createAccessor().setType('SCALAR').setArray(xref.length <= 65535 ? Uint16Array.from(indices) : Uint32Array.from(indices)).setBuffer(buffer))
+      into.setMaterial(prim.getMaterial()).setMode(prim.getMode())
+    }
+    const prims = mesh.listPrimitives()
+    const made: { mesh: Mesh; prim: Primitive }[] = []
+    const replacements = new Map<Primitive, Primitive>()
+    out.forEach((list, k) => {
+      const target = k === 0 ? null : doc.createMesh(`${mesh.getName()}_lm${k}`)
+      for (const prim of prims) {
+        const mine = list.filter((t) => t.prim === prim)
+        if (mine.length === 0) continue
+        const q = doc.createPrimitive()
+        build(prim, mine, q)
+        if (target) { target.addPrimitive(q); made.push({ mesh: target, prim: q }) } else replacements.set(prim, q)
+      }
+      if (target) {
+        const twin = doc.createNode(`${node.getName()}_lm${k}`).setMesh(target).setTranslation(node.getTranslation()).setRotation(node.getRotation()).setScale(node.getScale()).setExtras({ ...node.getExtras() })
+        const parent = node.getParentNode()
+        if (parent) parent.addChild(twin); else for (const scene of root.listScenes()) if (scene.listChildren().includes(node)) scene.addChild(twin)
+        added++
+      }
+    })
+    // part 0 replaces the mesh's own primitives
+    for (const prim of prims) {
+      for (const semantic of prim.listSemantics()) retired.add(prim.getAttribute(semantic)!)
+      const oldIdx = prim.getIndices(); if (oldIdx) retired.add(oldIdx)
+      mesh.removePrimitive(prim)
+      const q = replacements.get(prim)
+      if (q) { mesh.addPrimitive(q); made.push({ mesh, prim: q }) }
+      prim.dispose()
+    }
+    plan.prims = plan.prims.filter((p) => p.mesh !== mesh)
+    for (const m of made) {
+      const pos = m.prim.getAttribute('POSITION')!
+      plan.prims.push({ mesh: m.mesh, prim: m.prim, name: m.mesh.getName(), triangles: m.prim.getIndices()!.getCount() / 3, vertices: pos.getCount(), hasUv1: false })
+    }
+  }
+  return added
+}
+
+/** Split the plan's meshes into `n` groups of about equal world surface by bisecting their centroids along the longest
+ *  axis (neighbours share a group — a page holds a part of the level, not a scatter of it). A mesh drawn by several
+ *  nodes is placed by its first one: UV1 belongs to the mesh, so all of its nodes are in the same group. */
+const partitionMeshes = (doc: Document, plan: UnwrapPlan): { groupOf: Map<Mesh, number>; areas: number[]; scales: number[] } => {
+  const firstNode = new Map<Mesh, GltfNode>()
+  for (const node of doc.getRoot().listNodes()) {
+    const mesh = node.getMesh()
+    if (mesh && lodLevelOf(node.getName()) === 0 && !firstNode.has(mesh)) firstNode.set(mesh, node)
+  }
+  type Item = { mesh: Mesh; c: number[]; area: number; cls: number }
+  const items: Item[] = []
+  const seen = new Set<Mesh>()
+  const w = new Float32Array(9)
+  for (const p of plan.prims) {
+    if (seen.has(p.mesh)) continue
+    seen.add(p.mesh)
+    const node = firstNode.get(p.mesh)
+    const m = node ? node.getWorldMatrix() : [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ]
+    let area = 0, cls = plan.zoneMax
+    const c = [ 0, 0, 0 ]
+    for (const q of plan.prims) {
+      if (q.mesh !== p.mesh) continue
+      const pos = floats(q.prim.getAttribute('POSITION')!, 3)
+      const idxAcc = q.prim.getIndices()
+      const idx = idxAcc ? idxAcc.getArray()! : Uint32Array.from({ length: pos.length / 3 }, (_, i) => i)
+      for (let i = 0; i + 2 < idx.length; i += 3) {
+        for (let k = 0; k < 3; k++) { const v = idx[i + k]; xformPoint(m, pos[v * 3], pos[v * 3 + 1], pos[v * 3 + 2], w, k * 3) }
+        const ux = w[3] - w[0], uy = w[4] - w[1], uz = w[5] - w[2], vx = w[6] - w[0], vy = w[7] - w[1], vz = w[8] - w[2]
+        const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx
+        const a = 0.5 * Math.sqrt(nx * nx + ny * ny + nz * nz)
+        area += a
+        for (let k = 0; k < 3; k++) c[k] += a * (w[k] + w[3 + k] + w[6 + k]) / 3
+        // a mesh's scale is its FINEST triangle's (splitLargeMeshes has already cut what was worth cutting)
+        cls = Math.min(cls, texelScaleAt(plan, (w[0] + w[3] + w[6]) / 3, (w[1] + w[4] + w[7]) / 3, (w[2] + w[5] + w[8]) / 3))
+      }
+    }
+    if (area > 0) for (let k = 0; k < 3; k++) c[k] /= area
+    items.push({ mesh: p.mesh, c, area, cls: area > 0 ? cls : 1 })
+  }
+  const groupOf = new Map<Mesh, number>()
+  const areas: number[] = []
+  const scales: number[] = []
+  const split = (list: Item[], n: number): void => {
+    if (n <= 1 || list.length <= 1) {
+      const g = areas.length
+      areas.push(list.reduce((a, it) => a + it.area, 0))
+      scales.push(list[0]?.cls ?? 1)
+      for (const it of list) groupOf.set(it.mesh, g)
+      return
+    }
+    const lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+    for (const it of list) for (let k = 0; k < 3; k++) { lo[k] = Math.min(lo[k], it.c[k]); hi[k] = Math.max(hi[k], it.c[k]) }
+    let axis = 0
+    for (let k = 1; k < 3; k++) if (hi[k] - lo[k] > hi[axis] - lo[axis]) axis = k
+    const sorted = [ ...list ].sort((p, q) => p.c[axis] - q.c[axis])
+    const nl = Math.floor(n / 2)
+    const want = sorted.reduce((a, it) => a + it.area, 0) * nl / n
+    let acc = 0, cut = 0
+    while (cut < sorted.length - 1 && (cut === 0 || acc + sorted[cut].area * 0.5 <= want)) acc += sorted[cut++].area
+    split(sorted.slice(0, cut), nl)
+    split(sorted.slice(cut), n - nl)
+  }
+  // every scale gets its share of the groups by what it costs in the atlas (area / scale²), one at least
+  const classes = [ ...new Set(items.map((it) => it.cls)) ].sort((a, b) => a - b)
+  const eff = classes.map((cls) => items.filter((it) => it.cls === cls).reduce((a, it) => a + it.area, 0) / (cls * cls))
+  const effTotal = eff.reduce((a, b) => a + b, 0) || 1
+  classes.forEach((cls, i) => split(items.filter((it) => it.cls === cls), Math.max(1, Math.round(plan.groups * eff[i] / effTotal))))
+  return { groupOf, areas, scales }
+}
+
+export async function applyUnwrap(doc: Document, plan: UnwrapPlan): Promise<UnwrapResult> {
+  const res: UnwrapResult = { primitives: 0, charts: 0, width: 0, height: 0, verticesBefore: 0, verticesAfter: 0, groups: [], splitNodes: 0, lodPrimitives: 0, lodVertices: 0 }
+  if (plan.prims.length === 0) return res
+  const m = await getModule()
+  const buffer = doc.getRoot().listBuffers()[0] ?? doc.createBuffer()
+  const retired = new Set<Accessor>()
+
+  // one xatlas layout = one unit square = one atlas rect of the bake
+  const unwrap = (prims: UnwrapPrim[], texelScale = 1): UnwrapGroup => {
+    const h = m._lmuv_begin(prims.length)
+    if (h === 0) throw new Error(`lightmap UV: ${m.UTF8ToString(m._lmuv_error())}`)
+    const allocs: number[] = []
+    const upload = (arr: Float32Array | Uint32Array): number => {
+      const ptr = m._malloc(arr.byteLength)
+      allocs.push(ptr)
+      if (arr instanceof Float32Array) m.HEAPF32.set(arr, ptr >> 2)
+      else m.HEAPU32.set(arr, ptr >> 2)
+      return ptr
+    }
+    try {
+      for (const p of prims) {
+        const pos = p.prim.getAttribute('POSITION')!
+        const nrm = p.prim.getAttribute('NORMAL')
+        const uv0 = p.prim.getAttribute('TEXCOORD_0')
+        const idxAcc = p.prim.getIndices()
+        const indices = idxAcc ? Uint32Array.from(idxAcc.getArray()!) : Uint32Array.from({ length: pos.getCount() }, (_, i) => i)
+        const indexCount = indices.length - (indices.length % 3)
+        const posPtr = upload(floats(pos, 3))
+        const nrmPtr = nrm && nrm.getCount() === pos.getCount() ? upload(floats(nrm, 3)) : 0
+        const uvPtr = uv0 && uv0.getCount() === pos.getCount() ? upload(floats(uv0, 2)) : 0
+        const idxPtr = upload(indices)
+        const err = m._lmuv_add_mesh(h, posPtr, nrmPtr, uvPtr, pos.getCount(), idxPtr, indexCount)
+        if (err !== 0) throw new Error(`lightmap UV: ${p.name}: ${m.UTF8ToString(m._lmuv_error())}`)
+        res.verticesBefore += pos.getCount()
+      }
+      // xatlas copies the mesh data in AddMesh — the inputs can go before the (long) generate.
+      for (const ptr of allocs) m._free(ptr)
+      allocs.length = 0
+      const err = m._lmuv_generate(h, plan.padding, plan.iterations, plan.texelsPerUnit / texelScale)
+      if (err !== 0) throw new Error(`lightmap UV: ${m.UTF8ToString(m._lmuv_error())}`)
+      const group: UnwrapGroup = { texelScale, primitives: prims.length, charts: m._lmuv_chart_count(h), width: m._lmuv_width(h), height: m._lmuv_height(h), area: 0 }
+      if (m._lmuv_mesh_count(h) !== prims.length) throw new Error('lightmap UV: xatlas returned a different mesh count')
+      prims.forEach((p, i) => {
+        const vcount = m._lmuv_mesh_vertex_count(h, i)
+        const icount = m._lmuv_mesh_index_count(h, i)
+        const xrefPtr = m._lmuv_mesh_xref(h, i) >> 2
+        const xref = m.HEAPU32.slice(xrefPtr, xrefPtr + vcount)
+        const uvPtr = m._lmuv_mesh_uv(h, i) >> 2
+        const uv1 = m.HEAPF32.slice(uvPtr, uvPtr + vcount * 2)
+        const idxPtr = m._lmuv_mesh_indices(h, i) >> 2
+        const idx32 = m.HEAPU32.slice(idxPtr, idxPtr + icount)
+        reindexPrimitive(doc, p.prim, xref, idx32, uv1, buffer, retired)
+        res.verticesAfter += vcount
+        res.primitives++
+      })
+      return group
+    } finally {
+      for (const ptr of allocs) m._free(ptr)
+      m._lmuv_end(h)
+    }
+  }
+
+  // a node's group rides in its extras; a file unwrapped whole carries none (and loses what an earlier split left)
+  const setGroup = (node: GltfNode, g: number | undefined, texelScale = 1): void => {
+    const extras = { ...(node.getExtras() as Record<string, unknown>) }
+    if (g === undefined) delete extras.lightmapGroup; else extras.lightmapGroup = g
+    if (g === undefined || texelScale <= 1) delete extras.lightmapTexelScale; else extras.lightmapTexelScale = texelScale
+    node.setExtras(extras)
+  }
+  if (plan.groups <= 1) {
+    const g = unwrap(plan.prims)
+    res.charts = g.charts; res.width = g.width; res.height = g.height
+    for (const node of doc.getRoot().listNodes()) if (node.getMesh() && (node.getExtras() as Record<string, unknown>).lightmapGroup !== undefined) setGroup(node, undefined)
+  } else {
+    res.splitNodes = splitLargeMeshes(doc, plan, buffer, retired)
+    const { groupOf, areas, scales } = partitionMeshes(doc, plan)
+    for (let k = 0; k < areas.length; k++) {
+      const g = unwrap(plan.prims.filter((p) => groupOf.get(p.mesh) === k), scales[k])
+      g.area = areas[k]
+      res.groups.push(g)
+      res.charts += g.charts; res.width = Math.max(res.width, g.width); res.height = Math.max(res.height, g.height)
+    }
+    // every node of a grouped mesh, and the LOD siblings with their level 0 (they read its texels)
+    const lodBase = new Map<Mesh, Mesh>()
+    for (const lod of plan.lods) lodBase.set(lod.mesh, lod.baseNode.getMesh()!)
+    for (const node of doc.getRoot().listNodes()) {
+      const mesh = node.getMesh()
+      if (!mesh) continue
+      const g = groupOf.get(lodBase.get(mesh) ?? mesh)
+      setGroup(node, g, g !== undefined ? scales[g] : 1)
+    }
+  }
+
+  // the LOD siblings, from the level-0 meshes that now carry the layout
+  const surfaces = new Map<GltfNode, BaseSurface>()
+  for (const lod of plan.lods) {
+    let base = surfaces.get(lod.baseNode)
+    if (!base) { base = new BaseSurface(lod.baseNode); surfaces.set(lod.baseNode, base) }
+    if (base.count === 0) continue   // level 0 got no layout (skipped above): the LOD keeps what it had
+    res.lodVertices += projectLodPrimitive(doc, lod, base, buffer, retired)
+    res.lodPrimitives++
+  }
+
+  // A retired accessor may still back another primitive (shared POSITION with different indices)
+  // or a morph target we did not touch — only drop the ones nothing references any more.
+  for (const acc of retired) {
+    if (acc.listParents().every((parent) => parent.propertyType === 'Root')) acc.dispose()
+  }
+  return res
+}