lecodes-assets 0.2.0 → 2.4.10

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,275 @@
+// 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; ETC1S steps on a smooth channel)
+// …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 { createHash } from 'node:crypto'
+import sharp from 'sharp'
+import { spawn, spawnSync } from 'node:child_process'   // spawnSync only for the one-shot --version probe
+import { existsSync, mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { cpus, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { Root, Texture } from '@gltf-transform/core'
+import { getTextureRoles, DEFAULT_MAX_SIZE } from './transcodeTextures'
+
+/**
+ * The KTX2 encoder: KTX-Software's legacy `toktx`, or — when there is none — its unified `ktx`
+ * tool's `create` subcommand. KTX-Software 5 dropped `toktx` (the macOS installer ships only `ktx`),
+ * 4.4 still has both; the two write the same Basis files from the same inputs, only the flags differ
+ * (`ktxEncodeArgs`).
+ */
+export interface KtxEncoder { kind: 'toktx' | 'ktx'; path: string; version: string }
+
+export const KTX_ENCODER_MISSING =
+  'KTX-Software not found — neither `toktx` nor `ktx` (looked at $KTX_TOKTX, $KTX_TOOL, the installer\'s folders, PATH).\n' +
+  '  Install it from https://github.com/KhronosGroup/KTX-Software/releases, or set KTX_TOKTX / KTX_TOOL=<path to the binary>.'
+
+/** Where KTX-Software's installers put their binaries, per platform. */
+function installDirs(): string[] {
+  if (process.platform === 'win32') {
+    return [ process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, 'Programs', 'KTX-Software', 'bin'),
+      process.env.ProgramFiles && join(process.env.ProgramFiles, 'KTX-Software', 'bin') ].filter((d): d is string => !!d)
+  }
+  return [ '/usr/local/bin', '/opt/homebrew/bin' ]
+}
+
+/** `name` resolved: the env override, then the installer's folders, then PATH (the bare name). */
+function locate(name: 'toktx' | 'ktx', env: string | undefined): string {
+  if (env && existsSync(env)) return env
+  const exe = process.platform === 'win32' ? `${name}.exe` : name
+  return installDirs().map((d) => join(d, exe)).find((p) => existsSync(p)) ?? exe
+}
+
+/** Locate the toktx binary: $KTX_TOKTX → the installer's folders → PATH. */
+export const findToktx = (): string => locate('toktx', process.env.KTX_TOKTX)
+
+/** Locate KTX-Software's unified `ktx` tool: $KTX_TOOL → next to $KTX_TOKTX → the installer's folders → PATH. */
+export const findKtxCli = (): string =>
+  locate('ktx', process.env.KTX_TOOL ?? process.env.KTX_TOKTX?.replace(/toktx(\.exe)?$/i, process.platform === 'win32' ? 'ktx.exe' : 'ktx'))
+
+/** The binary's `--version` line, or null when it does not run. */
+export function checkToktx(tool: string): string | null {
+  try {
+    const p = spawnSync(tool, ['--version'], { encoding: 'utf8' })
+    if (p.status === 0) return (p.stdout ?? '').toString().trim() || tool
+  } catch { /* not found */ }
+  return null
+}
+
+/** toktx when it runs, else `ktx` (create), else null. */
+export function findKtxEncoder(): KtxEncoder | null {
+  const toktx = findToktx()
+  const tv = checkToktx(toktx)
+  if (tv) return { kind: 'toktx', path: toktx, version: tv }
+  const ktx = findKtxCli()
+  const kv = checkToktx(ktx)
+  return kv ? { kind: 'ktx', path: ktx, version: kv } : null
+}
+
+export interface KtxEncodeJob {
+  input: string
+  output: string
+  codec: 'etc1s' | 'uastc'
+  oetf: 'srgb' | 'linear'
+  /** Channels of the input PNG — `ktx create` wants the format spelled out. */
+  channels: 3 | 4
+  /** UASTC quality 0–4. */
+  uastcQuality: number
+  /** Zstandard level for UASTC (ETC1S is Basis-LZ, never supercompressed on top). */
+  zstd: number
+}
+
+/** The encoder's command line for one PNG → KTX2 (always 2D, mipmapped, the transfer function assigned). */
+export function ktxEncodeArgs(enc: KtxEncoder, j: KtxEncodeJob): string[] {
+  if (enc.kind === 'toktx') {
+    return [ '--t2', ...(j.codec === 'etc1s'
+      ? [ '--encode', 'etc1s', '--clevel', '2', '--qlevel', '128' ]
+      : [ '--encode', 'uastc', '--uastc_quality', String(j.uastcQuality), '--zcmp', String(j.zstd) ]),
+    '--genmipmap', '--assign_oetf', j.oetf, j.output, j.input ]
+  }
+  const format = `${j.channels === 4 ? 'R8G8B8A8' : 'R8G8B8'}_${j.oetf === 'srgb' ? 'SRGB' : 'UNORM'}`
+  return [ 'create', '--format', format, ...(j.codec === 'etc1s'
+    ? [ '--encode', 'basis-lz', '--clevel', '2', '--qlevel', '128' ]
+    : [ '--encode', 'uastc', '--uastc-quality', String(j.uastcQuality), '--zstd', String(j.zstd) ]),
+  // --assign-tf: sharp's PNGs carry no colour chunk, which `ktx` reads as sRGB and then refuses to
+  // put into a *_UNORM format without a conversion — the data maps ARE linear, so say so.
+  '--generate-mipmap', '--assign-tf', j.oetf, j.input, j.output ]
+}
+
+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
+  }
+
+  // DATA maps (normal, metal / rough, occlusion) always take UASTC: ETC1S is a palette codec whose blocks show
+  // as steps on a smooth metallic or roughness channel (the range's metal props read pixelated under the
+  // reflection probes, 2026-09-17) and it wrecks normals; colour stays on ETC1S (small, its artefacts hide in the
+  // detail) unless 'uastc' asks for UASTC everywhere (hero assets). 'hq' is the same as the default now.
+  // oetf: linear for any non-colour data.
+  const codec: 'etc1s' | 'uastc' =
+    policy === 'uastc' ? 'uastc'
+    : isNormal || isData ? 'uastc'
+    : '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)` : ''}`,
+  }
+}
+
+/**
+ * ENCODED KTX2 BY CONTENT, for the life of the process.
+ *
+ * Encoding is pure: the same pixels at the same cap, codec and transfer function give the same file.
+ * And a LEVEL import asks for the same pixels over and over — every kind is its own self-contained
+ * GLB, so a wall texture shared by a hundred buildings is embedded, and therefore encoded, a hundred
+ * times. Measured on the Chernobyl import: **3554 embedded textures of which 314 are distinct**, i.e.
+ * 11.3 encodes of each on average and 144 of the most-shared ones. Each of those is a temp dir, a
+ * sharp decode + PNG re-encode, and a SYNCHRONOUS `toktx` process — which is also why the importer
+ * sat at 1.4 of this machine's 24 cores while it ran.
+ *
+ * Keyed on everything that changes the output and nothing else.
+ */
+const encoded = new Map<string, Uint8Array>()
+let hits = 0
+/** Encodes RUNNING right now, by cache key: a second caller for the same image waits on the first
+ *  instead of starting its own toktx. Without it the concurrency below would turn the cache's whole
+ *  point inside out — a texture on a hundred props would encode a hundred times, in parallel. */
+const inFlight = new Map<string, Promise<Uint8Array>>()
+
+/**
+ * How many toktx processes may run at once. The encode is an external process per texture, so the
+ * work is ENTIRELY outside this thread and the only reason to cap it is not to swamp the machine;
+ * one per core, minus one for us, is the usual shape. `LECODES_KTX_JOBS` overrides it (1 = the old
+ * strictly-sequential behaviour, for a bisect).
+ */
+const JOBS = Math.max(1, Number(process.env.LECODES_KTX_JOBS) || Math.max(1, cpus().length - 1))
+let running = 0
+const waiting: (() => void)[] = []
+const acquire = async (): Promise<void> => {
+  if (running < JOBS) { running++; return }
+  await new Promise<void>((res) => waiting.push(res))
+  running++
+}
+const release = (): void => { running--; waiting.shift()?.() }
+
+export const ktx2Jobs = (): number => JOBS
+
+/** The encoder as a promise. `spawnSync` blocked the event loop for the whole encode, which made every
+ *  texture in a project strictly sequential no matter how many cores were idle. */
+const runEncoder = (enc: KtxEncoder, args: string[], name: string): Promise<void> =>
+  new Promise((resolve, reject) => {
+    const proc = spawn(enc.path, args, { windowsHide: true })
+    let err = ''
+    proc.stderr?.on('data', (d) => { err += String(d) })
+    proc.on('error', reject)
+    proc.on('close', (code) => code === 0
+      ? resolve()
+      : reject(new Error(`${enc.kind === 'ktx' ? 'ktx create' : 'toktx'} failed (exit ${code}) for "${name}": ${err.slice(0, 300)}`)))
+  })
+/** How many encodes this process served from the cache (for a caller that wants to report it). */
+export const ktx2CacheHits = (): number => hits
+
+export async function applyKtx2(plan: Ktx2Plan, enc: KtxEncoder, maxSize = DEFAULT_MAX_SIZE): Promise<void> {
+  const src = plan.tex.getImage()
+  const key = src
+    ? `${createHash('sha1').update(src).digest('hex')}:${maxSize}:${plan.codec}:${plan.oetf}:${plan.hasAlpha ? 1 : 0}`
+    : null
+  if (key) {
+    const hit = encoded.get(key)
+    if (hit) { hits++; plan.tex.setImage(hit).setMimeType('image/ktx2'); plan.afterBytes = hit.length; return }
+    // the same image, already being encoded by another caller: wait on that one
+    const busy = inFlight.get(key)
+    if (busy) {
+      hits++
+      const bytes = await busy
+      plan.tex.setImage(bytes).setMimeType('image/ktx2')
+      plan.afterBytes = bytes.length
+      return
+    }
+  }
+  const work = encodeOne(plan, enc, maxSize)
+  if (key) {
+    inFlight.set(key, work)
+    try { encoded.set(key, await work) } finally { inFlight.delete(key) }
+  }
+  const bytes = await work
+  plan.tex.setImage(bytes).setMimeType('image/ktx2')
+  plan.afterBytes = bytes.length
+}
+
+/** One texture through sharp + the encoder, returning the encoded bytes. Holds a pool slot only around
+ *  the external process, so the sharp resize of the next texture overlaps with this one's encode. */
+async function encodeOne(plan: Ktx2Plan, enc: KtxEncoder, maxSize: number): Promise<Uint8Array> {
+  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' })
+    // Always RGB / RGBA (a grey or palette source too): `ktx create` declares the channel count up front.
+    pipe = pipe.toColourspace('srgb')
+    pipe = plan.hasAlpha ? pipe.ensureAlpha() : pipe.removeAlpha() // RGB → no wasted alpha slice
+    writeFileSync(inPng, await pipe.png().toBuffer())
+
+    const args = ktxEncodeArgs(enc, {
+      input: inPng, output: outKtx, codec: plan.codec, oetf: plan.oetf,
+      channels: plan.hasAlpha ? 4 : 3, uastcQuality: 2, zstd: 18,
+    })
+
+    await acquire()
+    try { await runEncoder(enc, args, plan.name) } finally { release() }
+
+    return new Uint8Array(readFileSync(outKtx))
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}

package/src/doctor/transcodeTextures.ts

@@ -0,0 +1,101 @@
+// Texture normalization for creator-gl (filament providers = png/jpeg/ktx2 only) + size budget.
+// Split into PLAN (analysis, no mutation) and APPLY (sharp re-encode).
+//
+// Policy (format chosen purely by alpha — PNG only when alpha is needed, else JPG, to keep size
+// small; webp→png for a 2048 image is ~5–10× larger than webp, so we avoid PNG unless required):
+//   - alpha present               -> PNG (jpeg has no alpha channel)
+//   - no alpha                    -> JPG  (normals/metalRough use quality 92 + 4:4:4 chroma)
+//   - webp                        -> re-encode per the rule above (filament has no webp provider)
+//   - max dim > 2048              -> downscale to fit 2048 + re-encode
+//   - opaque PNG (>=1024px)       -> JPG (heavy opaque PNGs are wasteful)
+//   - ktx2                        -> left untouched (supported; sharp can't handle it)
+import sharp from 'sharp'
+import type { Root, Texture } from '@gltf-transform/core'
+
+export const DEFAULT_MAX_SIZE = 2048
+const HEAVY_PNG_MIN_DIM = 1024
+
+export interface TexturePlan {
+  tex: Texture
+  name: string
+  roles: string
+  fromFmt: string
+  toFmt: 'jpeg' | 'png' | null // null = leave unchanged
+  resize: boolean
+  width: number
+  height: number
+  hasAlpha: boolean
+  isNormal: boolean
+  isData: boolean
+  category: 'lossless' | 'lossy' | null
+  reason: string
+  beforeBytes: number
+  afterBytes?: number
+}
+
+export function getTextureRoles(tex: Texture, root: Root) {
+  const set = new Set<string>()
+  for (const m of root.listMaterials()) {
+    if (m.getBaseColorTexture() === tex) set.add('base')
+    if (m.getEmissiveTexture() === tex) set.add('emissive')
+    if (m.getNormalTexture() === tex) set.add('normal')
+    if (m.getMetallicRoughnessTexture() === tex) set.add('metalRough')
+    if (m.getOcclusionTexture() === tex) set.add('occlusion')
+  }
+  return { roles: [...set].join('+') || 'unused', isNormal: set.has('normal'), isData: set.has('metalRough') || set.has('occlusion') }
+}
+
+export async function planTexture(tex: Texture, root: Root, maxSize = DEFAULT_MAX_SIZE, forceFmt?: 'jpeg' | 'png'): Promise<TexturePlan | null> {
+  const img = tex.getImage()
+  const mime = tex.getMimeType() || ''
+  const fromFmt = mime.replace('image/', '') || '?'
+  if (!img) return null
+  if (fromFmt.includes('ktx')) return null
+
+  const { roles, isNormal, isData } = getTextureRoles(tex, root)
+  let width = 0, height = 0, hasAlpha = false
+  try {
+    const buf = Buffer.from(img)
+    const meta = await sharp(buf).metadata()
+    width = meta.width || 0; height = meta.height || 0
+    hasAlpha = !(await sharp(buf).stats()).isOpaque
+  } catch {
+    return null // undecodable by sharp — leave it
+  }
+
+  const resize = Math.max(width, height) > maxSize
+  let desired: 'jpeg' | 'png' = forceFmt ?? (hasAlpha ? 'png' : 'jpeg') // PNG only when alpha is needed
+  if (desired === 'jpeg' && hasAlpha) desired = 'png' // never drop a real alpha channel
+
+  let act = false, reason = 'ok'
+  if (forceFmt) {
+    if ((fromFmt as string) !== desired || resize || (fromFmt as string) === 'webp') { act = true; reason = `${fromFmt} → ${desired}${resize ? ` (≤${maxSize}px)` : ''}` }
+  }
+  else if (fromFmt === 'webp') { act = true; reason = `webp → ${desired}` }
+  else if (resize) { act = true; reason = `${width}×${height} → ≤${maxSize}px, ${desired}` }
+  else if (fromFmt === 'png' && desired === 'jpeg' && Math.max(width, height) >= HEAVY_PNG_MIN_DIM) { act = true; reason = `heavy opaque png → jpeg` }
+
+  const base = { tex, name: tex.getName() || '?', roles, fromFmt, resize, width, height, hasAlpha, isNormal, isData, beforeBytes: img.length }
+  if (!act) return { ...base, toFmt: null, category: null, reason }
+
+  // lossless only when staying/becoming PNG without a resize (no further pixel loss)
+  const category: 'lossless' | 'lossy' = desired === 'png' && !resize ? 'lossless' : 'lossy'
+  return { ...base, toFmt: desired, category, reason }
+}
+
+export async function applyTexturePlan(plan: TexturePlan, maxSize = DEFAULT_MAX_SIZE): Promise<void> {
+  if (!plan.toFmt) return
+  let pipe = sharp(Buffer.from(plan.tex.getImage()!))
+  if (plan.resize) pipe = pipe.resize({ width: maxSize, height: maxSize, fit: 'inside', withoutEnlargement: true })
+  if (plan.toFmt === 'jpeg') {
+    // normals / metal-rough / occlusion carry data, not colour: higher quality, no chroma subsampling
+    const dataLike = plan.isNormal || plan.isData
+    const out = await pipe.jpeg({ quality: dataLike ? 92 : 85, mozjpeg: true, chromaSubsampling: dataLike ? '4:4:4' : '4:2:0' }).toBuffer()
+    plan.tex.setImage(new Uint8Array(out)).setMimeType('image/jpeg')
+    plan.afterBytes = out.length
+  } else {
+    const out = await pipe.png({ compressionLevel: 9 }).toBuffer()
+    plan.tex.setImage(new Uint8Array(out)).setMimeType('image/png')
+    plan.afterBytes = out.length
+  }
+}