lecodes-assets 0.2.0 → 2.4.10

package/src/commands/sky.ts

@@ -0,0 +1,35 @@
+import { bool, CliError, defineCommand, int, missing, str } from "../cli-kit"
+import { log } from "./shared"
+
+export default defineCommand({
+  name: "sky",
+  summary: "Equirectangular HDR → the TWO cubemaps a scene needs (drawn sky + lighting probe)",
+  usage: "<env.exr|.hdr>",
+  description: `
+    Writes sky.ktx (sharp — use it for \`skybox: { texture }\`) and ibl.ktx (prefiltered + SH — lights
+    the scene). They are NOT interchangeable: the IBL is blurred by design, so drawing it as the sky
+    looks soft. Also reports WHERE THE SUN IS in the environment, so the scene's directional light can
+    be aimed to match instead of by eye.
+
+    Needs filament's cmgen (LECODES_CMGEN / ~/.lecodes/cmgen).`,
+  flags: {
+    o: str("where they land (default: beside the input)", { value: "dir" }),
+    size: int("edge of the DRAWN sky cubemap (default 512)"),
+    "ibl-size": int("edge of the lighting probe (default 256 — it is only ever sampled as low-frequency light, so it stays small)"),
+    name: str("the sky's file name without extension (default sky)", { value: "n" }),
+    "ibl-name": str("the probe's (default ibl)", { value: "n" }),
+    "ibl-only": bool("lighting probe only, no drawn sky"),
+    "no-sun": bool("take the sun out of the LIGHTING PROBE (the drawn sky keeps it): for a level with a directional sun — the sun in the probe is the same light twice, shadowless"),
+  },
+  run: async ({ args, flags }) => {
+    const input = args[0]
+    if (!input) throw missing("the environment map")
+    const { buildSky, formatSkyReport } = await import("../sky")
+    log(`\n🌤  ${input}`)
+    try {
+      const res = await buildSky(input, { outDir: flags.o, size: flags.size, iblSize: flags["ibl-size"], skyName: flags.name, iblName: flags["ibl-name"], iblOnly: flags["ibl-only"], noSun: flags["no-sun"], log })
+      log(formatSkyReport(res))
+      return 0
+    } catch (e) { throw new CliError((e as Error).message) }
+  },
+})

package/src/commands/terrainPack.ts

@@ -0,0 +1,40 @@
+import { resolve } from "node:path"
+import { bool, CliError, defineCommand, int, list, missing, str } from "../cli-kit"
+import { log } from "./shared"
+
+export default defineCommand({
+  name: "terrain-pack",
+  summary: "A terrain's splat layers (≤ 4) → <name>.ktx2 per layer + the PACKED normal maps",
+  usage: "<layer|dir> …",
+  description: `
+    Normals ship two per texture — normals01.ktx2 / normals23.ktx2, layer XY pairs in RG/BA — because
+    terrain.mat has nine samplers. A layer = an albedo file (its normal guessed from the name, or
+    --normals) or a FOLDER holding *Albedo* + *Normal* (Unity terrain packs). A layer's ROUGHNESS map
+    (--roughness, *Roughness*, or a Unity *AlbedoSmoothness* alpha) goes into its albedo's alpha.
+    Prints the Terrain.create fragment.`,
+  flags: {
+    o: str("where they land (default: ./terrain)", { value: "dir" }),
+    normals: list(`normal map per layer, positionally ("-" = none)`, { value: "n0 n1 …" }),
+    roughness: list(`roughness map per layer, positionally ("-" = none): packed into the layer's albedo ALPHA, which the terrain material multiplies the layer's roughness by (read from the image's green channel: a grey map or a glTF metallicRoughness / ORM one)`, { value: "r0 r1 …" }),
+    names: list("layer names → file names (default: from the inputs)", { value: "a b …" }),
+    size: int("output edge (1024)"),
+    quality: int("UASTC quality 0–4 (1)"),
+    png: bool("PNGs instead of KTX2 (no KTX-Software needed)"),
+    "flip-y": bool("DirectX-style normal maps (green inverted)"),
+  },
+  run: async ({ args, flags }) => {
+    if (args.length === 0) throw missing("the layers")
+    const { resolveTerrainLayer, packTerrainTextures } = await import("../terrainPack")
+    const outDir = resolve(flags.o ?? "terrain")
+    try {
+      const layers = args.map((input, i) => {
+        const n = flags.normals[i], r = flags.roughness[i]
+        return resolveTerrainLayer(input, n && n !== "-" ? n : undefined, flags.names[i], r && r !== "-" ? r : undefined)
+      })
+      log(`\n🏔  ${layers.length} layer(s) → ${outDir}`)
+      const res = await packTerrainTextures(layers, { outDir, size: flags.size, png: flags.png, flipY: flags["flip-y"], quality: flags.quality, log })
+      log(`\n   Terrain.create({ …,\n${res.snippet.split("\n").map((l) => "     " + l).join("\n")}\n   })   (asset() paths relative to the calling file)`)
+      return 0
+    } catch (e) { throw new CliError((e as Error).message) }
+  },
+})

package/src/commands/unpack.ts

@@ -0,0 +1,43 @@
+import { existsSync } from "node:fs"
+import { basename, dirname, extname, join } from "node:path"
+import { bool, defineCommand, list, missing, notFound, str } from "../cli-kit"
+import { log } from "./shared"
+
+export default defineCommand({
+  name: "unpack",
+  summary: "Stream a .unitypackage: write unity-index.txt (GUID → path) and the matching assets (+ .meta)",
+  usage: "<pkg.unitypackage>",
+  flags: {
+    o: str("where it lands (default: a folder named after the package, beside it)", { value: "dir" }),
+    only: list("extract only the asset paths matching these (default: all)", { value: "regex …" }),
+    list: bool("print the matching asset paths and exit"),
+  },
+  run: async ({ args, flags }) => {
+    const pkg = args[0]
+    if (!pkg) throw missing("the .unitypackage")
+    if (!existsSync(pkg)) throw notFound(pkg)
+    const { indexUnityPackage, writeUnityIndex, readUnityIndex, extractUnityPackage, INDEX_NAME } = await import("../unity/unpack")
+    const outDir = flags.o ?? join(dirname(pkg), basename(pkg, extname(pkg)))
+    const t0 = performance.now()
+    const indexFile = join(outDir, INDEX_NAME)
+    let index
+    if (existsSync(indexFile)) { index = readUnityIndex(indexFile); log(`📇 ${index.size} assets (cached ${indexFile})`) }
+    else {
+      log(`📇 indexing ${pkg} …`)
+      index = await indexUnityPackage(pkg, (n, a) => process.stdout.write(`\r   ${n} entries, ${a} assets`))
+      process.stdout.write("\r")
+      writeUnityIndex(outDir, index)
+      log(`   ${index.size} assets → ${indexFile}`)
+    }
+    const only = flags.only.map((r) => new RegExp(r, "i"))
+    if (flags.list) {
+      for (const [ , path ] of index) if (!only.length || only.some((r) => r.test(path))) log(path)
+      return 0
+    }
+    log(`📦 extracting${only.length ? ` (${only.length} pattern(s))` : ""} → ${outDir}`)
+    const r = await extractUnityPackage(pkg, index, outDir, { only, progress: (f, b) => process.stdout.write(`\r   ${f} files, ${(b / 1e6).toFixed(0)} MB`) })
+    process.stdout.write("\r")
+    log(`   ${r.files} files written (${(r.bytes / 1e6).toFixed(1)} MB) of ${r.matched} matching, ${((performance.now() - t0) / 1000).toFixed(0)}s`)
+    return 0
+  },
+})

package/src/commands/unreal.ts

@@ -0,0 +1,109 @@
+import { existsSync, writeFileSync } from "node:fs"
+import { bool, defineCommand, int, missing, notFound, str } from "../cli-kit"
+import { log } from "./shared"
+
+const needTarget = (target: string | undefined, what: string): string => {
+  if (!target) throw missing(what)
+  if (!existsSync(target)) throw notFound(target)
+  return target
+}
+
+const ls = defineCommand({
+  name: "ls",
+  summary: "What an UNREAL pack holds: every .uasset by class, grouped by the skeleton it belongs to",
+  usage: "<dir>",
+  description: `
+    With the reason for anything unreadable (a UE4 package, a mesh with no import data, a clip whose
+    rig is elsewhere). Reads only the headers — a 800-asset pack lists in a second. convert / probe /
+    retarget take .uasset files directly (uncooked UE 5.0-5.7 editor assets: SkeletalMesh, Skeleton,
+    AnimSequence).`,
+  flags: { all: bool("list every asset, not only the ones this pipeline reads") },
+  run: async ({ args, flags }) => {
+    const target = needTarget(args[0], "the pack folder")
+    const { scanUnreal, formatUnrealListing } = await import("../unreal/list")
+    log(formatUnrealListing(target, scanUnreal(target), { all: flags.all }))
+    return 0
+  },
+})
+
+const tex = defineCommand({
+  name: "tex",
+  summary: "The SOURCE image out of a texture asset (Oodle-compressed — see the README; UE 4.25+ too, zlib bulk data)",
+  usage: "<T_x.uasset>",
+  flags: {
+    o: str("output (default: beside the asset, .png or .jpg as stored)", { value: "out.png" }),
+    raw: bool("write it exactly as stored"),
+    "max-size": int("downscale to this edge"),
+    "flip-green": bool("for a normal map. A PNG source stays lossless"),
+  },
+  run: async ({ args, flags }) => {
+    const target = needTarget(args[0], "the texture asset")
+    const { readPackageFile } = await import("../unreal/index")
+    const { extractTexture } = await import("../unreal/texture")
+    const img = await extractTexture(readPackageFile(target, { ue4: true }))
+    const t = img.texture
+    log(`🖼  ${t.name}: ${t.source.width}×${t.source.height} ${t.source.format} ${t.source.compression} · ${t.compressionSettings}${t.srgb ? " · sRGB" : ""}`)
+    let data = img.data, mime = img.mimeType
+    if (!flags.raw && img.swapRb) {
+      const { fixChannels } = await import("../unreal/materials")
+      const fixed = await fixChannels(data, mime, { swapRb: true, flipGreen: flags["flip-green"], maxSize: flags["max-size"] ?? 0, png: /\.png$/i.test(flags.o ?? "") || mime === "image/png" })
+      data = fixed.data; mime = fixed.mimeType
+      log(`   red/blue swapped back (the source is ${t.source.format})${flags["flip-green"] ? " · normal green flipped" : ""}`)
+    }
+    const out = flags.o ?? target.replace(/\.uasset$/i, mime === "image/png" ? ".png" : ".jpg")
+    writeFileSync(out, data)
+    log(`💾 wrote ${out}  (${(data.byteLength / 1024).toFixed(0)} KB, ${mime})`)
+    return 0
+  },
+})
+
+const mat = defineCommand({
+  name: "mat",
+  summary: "A Material's EXPRESSION GRAPH as JSON — for a tool that evaluates what the material computes",
+  usage: "<M_x.uasset>",
+  description: `
+    Its outputs (BaseColor, Opacity, Normal…) and every expression with its edges and settings
+    (constants, parameter defaults, texture paths).`,
+  flags: { o: str("output (default: printed)", { value: "graph.json" }) },
+  run: async ({ args, flags }) => {
+    const target = needTarget(args[0], "the material asset")
+    const { readPackageFile } = await import("../unreal/index")
+    const { readMaterialGraph } = await import("../unreal/materialGraph")
+    const graph = readMaterialGraph(readPackageFile(target, { ue4: true }))
+    const json = JSON.stringify(graph, null, 2)
+    if (!flags.o) { console.log(json); return 0 }
+    writeFileSync(flags.o, json)
+    log(`💾 ${graph.name}: ${Object.keys(graph.expressions).length} expressions, outputs ${Object.keys(graph.outputs).join(" ")} → ${flags.o}`)
+    return 0
+  },
+})
+
+const wav = defineCommand({
+  name: "wav",
+  summary: "The imported WAV out of every SoundWave asset (same Oodle buffer as textures)",
+  usage: "<Sound dir|.uasset> … -o <dir>",
+  flags: {
+    o: str("output folder (required)", { value: "<dir>" }),
+    ogg: bool("re-encode to mono Vorbis through ffmpeg"),
+    stereo: bool("…keeping the channels"),
+    quality: int("libvorbis -q (default 5)"),
+  },
+  run: async ({ args, flags }) => {
+    needTarget(args[0], "the sound assets")
+    if (!flags.o) throw missing("-o <dir>")
+    const { listUassets } = await import("../unreal/list")
+    const { exportSounds } = await import("../unreal/sound")
+    const { readPackageFile } = await import("../unreal/index")
+    const ogg = flags.ogg ? { mono: !flags.stereo, quality: flags.quality } : false as const
+    const rows = await exportSounds(args.flatMap((t) => listUassets(t)), flags.o, { ogg, readPackage: readPackageFile, log })
+    const total = rows.reduce((s, r) => s + r.bytes, 0)
+    log(`💾 ${rows.length} sound${rows.length === 1 ? "" : "s"} → ${flags.o}  (${(total / 1024).toFixed(0)} KB${ogg ? ", ogg" : ", wav"})`)
+    return rows.length > 0 ? 0 : 1
+  },
+})
+
+export default defineCommand({
+  name: "unreal",
+  summary: "Look inside an Unreal pack: list it, pull a texture, a material graph, the sounds",
+  commands: [ ls, tex, mat, wav ],
+})

package/src/commands/unwrap.ts

@@ -0,0 +1,56 @@
+import { defineCommand, int, missing, num, str, bool, usageError } from "../cli-kit"
+import { log, resolveInputs, seconds } from "./shared"
+
+export default defineCommand({
+  name: "unwrap",
+  summary: "Lightmap UVs (TEXCOORD_1, xatlas) for `lecodes lightmap bake` — written into the file itself",
+  usage: `<in.glb | dir | "*.glb"> …`,
+  description: `
+    Cuts every static mesh of the file into charts and lays them out in ONE unit square as TEXCOORD_1 — the set the
+    lightmap bake traces and the runtime samples. The file is rewritten IN PLACE (a temp file beside it, renamed over
+    it) unless -o says where; a file whose primitives all carry TEXCOORD_1 already is skipped (--force unwraps it again).
+    Skinned meshes are left as they are (a rig never stays in the baked pose); LOD siblings (<name>_LOD1…) take level
+    0's layout by projection, so every level reads the texels level 0 was baked into.
+
+    \`lecodes lightmap bake\` runs this itself on the GLBs the app references that have no TEXCOORD_1, so a raw import
+    bakes as it is. Run it by hand for what the bake cannot decide: a whole level in one GLB (--groups, --zone).
+    The bake re-packs every file's charts at its own density, so only the cutting here matters — the layout padding
+    is fixed.`,
+  flags: {
+    o: str("output file (one input) or folder (several) — default: the input itself", { value: "out" }),
+    force: bool("unwrap again files that already carry TEXCOORD_1 (the old set is replaced)"),
+    groups: int("split the meshes into this many parts of equal surface (neighbours together), each with a unit square of its own = an atlas rect of its own in the bake: a whole level in ONE GLB is otherwise one rect, which cannot span atlas pages (1)", { group: "Levels in one file" }),
+    zone: str("WHERE THE PLAYER WALKS, as boxes in world metres — \"x0,y0,z0,x1,y1,z1[;…]\" (with --groups): what is far from them is unwrapped and baked at a coarser texel, x2 past --zone-near, x4 past twice that, doubling every such distance up to --zone-max (an arena's upper tiers: a 16th of the texels and less); large meshes that span the distances are cut along them", { value: "boxes" }),
+    "zone-near": num("the distance to the zone (m) within which the texel is the full one (12)", { positive: true }),
+    "zone-max": num("the coarsest texel scale far from the zone, a power of two (4): 16 = 80 cm texels at a 5 cm bake", { positive: true }),
+    "zone-up": num("the weight of the vertical distance to the zone (1): 2 = a metre of height counts as two of reach, so what is high above the player goes coarse first", { positive: true }),
+    iterations: int("xatlas chart-growing iterations (1; more = better charts, slower)", { group: "Charts" }),
+    texel: num("the bake's texel (m) the fixed chart padding is measured in (0.05, the bake's default) — read only where the bake keeps the file's own square (a texture samples TEXCOORD_1, a mesh under two groups)", { value: "M" }),
+  },
+  examples: [
+    "lecodes assets unwrap assets/props",
+    `lecodes assets unwrap "assets/school/*.glb" --force`,
+    `lecodes assets unwrap assets/arena/Arena.glb --groups 12 --zone "-30,0,-20,30,3,20" --zone-max 16 --zone-up 2`,
+  ],
+  run: async ({ args, flags }) => {
+    const files = resolveInputs(args)
+    if (files.length === 0) throw missing("the GLB file(s)")
+    if (flags.zone && !(flags.groups && flags.groups > 1)) throw usageError("--zone needs --groups (> 1): a group holds one texel scale")
+    const { unwrapGlbFiles, detailUnwrap } = await import("../unwrap")
+    const t0 = performance.now()
+    if (files.length > 1) log(`Unwrapping ${files.length} files…`)
+    const reports = await unwrapGlbFiles(files, {
+      out: flags.o, force: flags.force,
+      groups: flags.groups, zone: flags.zone, zoneNear: flags["zone-near"], zoneMax: flags["zone-max"], zoneUp: flags["zone-up"],
+      iterations: flags.iterations, texel: flags.texel,
+      onFile: (r) => {
+        const mark = r.status === "unwrapped" ? "✓" : r.status === "failed" ? "✗" : "·"
+        log(`${mark} ${r.input} — ${r.summary}${r.status === "skipped" && r.reason?.startsWith("has TEXCOORD_1") ? " (--force unwraps it again)" : ""}`)
+        if (r.status !== "skipped") for (const l of detailUnwrap(r)) log(`   ${l}`)
+      },
+    })
+    const count = (s: string): number => reports.filter((r) => r.status === s).length
+    if (files.length > 1) log(`\n${count("unwrapped")} unwrapped · ${count("skipped")} skipped · ${count("failed")} failed in ${seconds(t0)}`)
+    return count("failed") > 0 ? 1 : 0
+  },
+})

package/src/doctor/cardTrim.ts

@@ -0,0 +1,286 @@
+// Card trimming (`lecodes assets doctor --trim-cards`): shrink alpha-MASK quads to their opaque texels.
+//
+// A foliage card is a quad over a leaf/grass texture that is mostly transparent — half or more of
+// every card the GPU rasterises is texels the masked shader then discards, and on a level of
+// thousands of cards that discarded fill is the frame (Twig & Twine's vegetation: 17–20 ms of 33).
+// The fix is geometric and lossless for what is drawn: each quad whose texture coordinates form an
+// axis-aligned rectangle is cut down to the bounding box of the opaque texels inside that rectangle
+// (plus a margin for the mips), its four vertices moved by bilinear interpolation inside the old
+// quad, its UVs set to the new rectangle. Quads with no opaque texel at all are dropped. Anything
+// that is not such a quad (a triangle fan, a bent strip, a vertex shared with another quad) is
+// left alone — a subdivided card keeps its shape.
+//
+// Runs on PNG / JPEG / WebP / TGA / BMP base-colour textures only (KTX2 has no decoder here): in the
+// doctor's order it comes BEFORE the texture passes, so `--ktx2` files trim first and encode after; a
+// GLB that already carries KTX2 is reported and skipped (re-run the import / conversion from the
+// source textures with the flag).
+import type { Accessor, Document, Primitive } from '@gltf-transform/core'
+import { weldPrimitive } from '@gltf-transform/functions'
+import { decodeImage } from '../unity/image'
+
+export interface CardTrimOptions {
+  /** Trim alpha-MASK quads to their opaque texels (see the header). */
+  trimCards?: boolean
+  /** Texels kept around the opaque box at the base mip (default 2 — a mip-2 texel each side). */
+  trimMargin?: number
+}
+export interface CardTrimPrimPlan { prim: Primitive; name: string; material: string; triangles: number; texture: 'ok' | 'ktx2' | 'none' | 'transform' }
+export interface CardTrimPlan { enabled: boolean; margin: number; prims: CardTrimPrimPlan[] }
+export interface CardTrimResult {
+  primitives: number
+  quads: number
+  trimmed: number
+  dropped: number
+  /** UV-space area of every quad before / after (1 = the whole texture). */
+  areaBefore: number
+  areaAfter: number
+  skipped: { name: string; reason: string }[]
+}
+
+const primTris = (p: Primitive): number => {
+  if (p.getMode() !== 4) return 0
+  const idx = p.getIndices()
+  return Math.floor((idx ? idx.getCount() : (p.getAttribute('POSITION')?.getCount() ?? 0)) / 3)
+}
+
+/** Which primitives the pass would touch (no decoding yet — that happens in apply). */
+export function planCardTrim(doc: Document, opts: CardTrimOptions): CardTrimPlan {
+  const prims: CardTrimPrimPlan[] = []
+  for (const mesh of doc.getRoot().listMeshes()) {
+    for (const prim of mesh.listPrimitives()) {
+      const mat = prim.getMaterial()
+      if (!mat || mat.getAlphaMode() !== 'MASK' || prim.getMode() !== 4) continue
+      if (!prim.getAttribute('POSITION') || !prim.getAttribute('TEXCOORD_0')) continue
+      const tex = mat.getBaseColorTexture()
+      const info = mat.getBaseColorTextureInfo()
+      const texture: CardTrimPrimPlan['texture'] = !tex ? 'none'
+        : (tex.getMimeType() || '').includes('ktx2') ? 'ktx2'
+        : info?.getExtension('KHR_texture_transform') ? 'transform' : 'ok'
+      prims.push({ prim, name: mesh.getName() || 'mesh', material: mat.getName() || 'material', triangles: primTris(prim), texture })
+    }
+  }
+  return { enabled: !!opts.trimCards && prims.length > 0, margin: Math.max(0, Math.round(opts.trimMargin ?? 2)), prims }
+}
+
+/** Summed-area table over the opaque mask, so any rectangle's opaque count is four reads. */
+class OpaqueTable {
+  readonly w: number
+  readonly h: number
+  private readonly sat: Uint32Array
+  constructor(rgba: Uint8Array, w: number, h: number, cutoff: number) {
+    this.w = w; this.h = h
+    const sat = new Uint32Array((w + 1) * (h + 1))
+    const stride = w + 1
+    for (let y = 0; y < h; y++) {
+      let row = 0
+      for (let x = 0; x < w; x++) {
+        if (rgba[(y * w + x) * 4 + 3] >= cutoff) row++
+        sat[(y + 1) * stride + x + 1] = sat[y * stride + x + 1] + row
+      }
+    }
+    this.sat = sat
+  }
+  /** Opaque texels in [x0, x1) × [y0, y1) (clamped). */
+  count(x0: number, y0: number, x1: number, y1: number): number {
+    x0 = Math.max(0, Math.min(this.w, x0)); x1 = Math.max(0, Math.min(this.w, x1))
+    y0 = Math.max(0, Math.min(this.h, y0)); y1 = Math.max(0, Math.min(this.h, y1))
+    if (x1 <= x0 || y1 <= y0) return 0
+    const s = this.w + 1
+    return this.sat[y1 * s + x1] - this.sat[y0 * s + x1] - this.sat[y1 * s + x0] + this.sat[y0 * s + x0]
+  }
+  /** Tight box of the opaque texels inside [x0, x1) × [y0, y1), or null when there are none. */
+  bounds(x0: number, y0: number, x1: number, y1: number): [number, number, number, number] | null {
+    if (this.count(x0, y0, x1, y1) === 0) return null
+    let bx0 = x0, bx1 = x1, by0 = y0, by1 = y1
+    while (bx0 < bx1 && this.count(bx0, y0, bx0 + 1, y1) === 0) bx0++
+    while (bx1 > bx0 && this.count(bx1 - 1, y0, bx1, y1) === 0) bx1--
+    while (by0 < by1 && this.count(x0, by0, x1, by0 + 1) === 0) by0++
+    while (by1 > by0 && this.count(x0, by1 - 1, x1, by1) === 0) by1--
+    return [ bx0, by0, bx1, by1 ]
+  }
+}
+
+type Quad = { tris: [number, number]; corners: [number, number, number, number]; u0: number; u1: number; v0: number; v1: number }
+
+const EPS = 1e-5
+
+/** Pair the triangles into axis-aligned UV quads whose four vertices belong to nobody else. */
+function findQuads(indices: Uint32Array, uv: Float32Array): Quad[] {
+  const triCount = indices.length / 3
+  const usage = new Map<number, number>()
+  for (const i of indices) usage.set(i, (usage.get(i) ?? 0) + 1)
+  const byEdge = new Map<string, number[]>()
+  for (let t = 0; t < triCount; t++) {
+    for (let e = 0; e < 3; e++) {
+      const a = indices[t * 3 + e], b = indices[t * 3 + (e + 1) % 3]
+      const key = a < b ? `${a}:${b}` : `${b}:${a}`
+      const list = byEdge.get(key)
+      if (list) list.push(t); else byEdge.set(key, [ t ])
+    }
+  }
+  const taken = new Uint8Array(triCount)
+  const quads: Quad[] = []
+  for (const [ , tris ] of byEdge) {
+    if (tris.length !== 2) continue
+    const [ ta, tb ] = tris
+    if (taken[ta] || taken[tb]) continue
+    const verts = new Set<number>()
+    for (const t of [ ta, tb ]) for (let e = 0; e < 3; e++) verts.add(indices[t * 3 + e])
+    if (verts.size !== 4) continue
+    // every vertex used by these two triangles only (a shared vertex would drag a neighbour along)
+    let own = true
+    for (const v of verts) {
+      let n = 0
+      for (const t of [ ta, tb ]) for (let e = 0; e < 3; e++) if (indices[t * 3 + e] === v) n++
+      if (usage.get(v) !== n) { own = false; break }
+    }
+    if (!own) continue
+    const vs = [ ...verts ]
+    const us = vs.map((v) => uv[v * 2]), vvs = vs.map((v) => uv[v * 2 + 1])
+    const u0 = Math.min(...us), u1 = Math.max(...us), v0 = Math.min(...vvs), v1 = Math.max(...vvs)
+    if (u1 - u0 < EPS || v1 - v0 < EPS) continue
+    // OUTSIDE THE IMAGE = TILED, and the opaque test below cannot read a tiled quad: it clamps the
+    // rect to the texture, so a quad at u 12.5..13.2 of a REPEAT-wrapped decal sheet measures the
+    // last column of texels, finds nothing opaque and the quad is dropped as an empty card. That is
+    // how five `SM_Floor_stripe_*` kinds — 101 lane markings on the range's floor — arrived as GLBs
+    // with textures, nodes and not one triangle (2026-09-17). A tiled quad is not a foliage card;
+    // leave it alone.
+    if (u0 < -EPS || v0 < -EPS || u1 > 1 + EPS || v1 > 1 + EPS) continue
+    // each vertex sits on a corner, and every corner is taken once
+    const corners: (number | undefined)[] = [ undefined, undefined, undefined, undefined ]   // (u0,v0) (u1,v0) (u0,v1) (u1,v1)
+    let ok = true
+    for (let k = 0; k < 4 && ok; k++) {
+      const su = Math.abs(us[k] - u0) < EPS ? 0 : Math.abs(us[k] - u1) < EPS ? 1 : -1
+      const sv = Math.abs(vvs[k] - v0) < EPS ? 0 : Math.abs(vvs[k] - v1) < EPS ? 1 : -1
+      if (su < 0 || sv < 0) { ok = false; break }
+      const c = sv * 2 + su
+      if (corners[c] !== undefined) { ok = false; break }
+      corners[c] = vs[k]
+    }
+    if (!ok || corners.some((c) => c === undefined)) continue
+    taken[ta] = 1; taken[tb] = 1
+    quads.push({ tris: [ ta, tb ], corners: corners as [number, number, number, number], u0, u1, v0, v1 })
+  }
+  return quads
+}
+
+/** Apply the pass to every planned primitive. */
+export async function applyCardTrim(doc: Document, plan: CardTrimPlan): Promise<CardTrimResult> {
+  const res: CardTrimResult = { primitives: 0, quads: 0, trimmed: 0, dropped: 0, areaBefore: 0, areaAfter: 0, skipped: [] }
+  const tables = new Map<string, Promise<OpaqueTable | null>>()
+  for (const p of plan.prims) {
+    const mat = p.prim.getMaterial()!
+    if (p.texture !== 'ok') {
+      res.skipped.push({ name: `${p.name}/${p.material}`, reason: p.texture === 'ktx2' ? 'base colour is KTX2 (no decoder) — trim from the source textures' : p.texture === 'none' ? 'no base colour texture' : 'KHR_texture_transform on the base colour' })
+      continue
+    }
+    const tex = mat.getBaseColorTexture()!
+    const cutoff = Math.max(0, Math.min(1, mat.getAlphaCutoff())) * 255 / Math.max(1e-3, mat.getBaseColorFactor()[3])
+    const key = `${tex.getName()}#${tex.getImage()?.byteLength ?? 0}#${cutoff.toFixed(2)}`
+    let table = tables.get(key)
+    if (!table) {
+      table = (async () => {
+        const bytes = tex.getImage()
+        if (!bytes) return null
+        const img = await decodeImage(bytes, tex.getURI() || tex.getMimeType() || 'texture.png')
+        return img ? new OpaqueTable(img.data, img.width, img.height, cutoff) : null
+      })()
+      tables.set(key, table)
+    }
+    const opaque = await table
+    if (!opaque) { res.skipped.push({ name: `${p.name}/${p.material}`, reason: 'base colour texture could not be decoded' }); continue }
+    const r = trimPrimitive(p.prim, opaque, plan.margin)
+    if (!r) continue
+    res.primitives++
+    res.quads += r.quads; res.trimmed += r.trimmed; res.dropped += r.dropped
+    res.areaBefore += r.areaBefore; res.areaAfter += r.areaAfter
+  }
+  return res
+}
+
+function trimPrimitive(prim: Primitive, opaque: OpaqueTable, margin: number): { quads: number; trimmed: number; dropped: number; areaBefore: number; areaAfter: number } | null {
+  if (!prim.getIndices()) weldPrimitive(prim)   // non-indexed cards: six vertices per quad → four (exact weld in this gltf-transform)
+  const idxAcc = prim.getIndices()
+  if (!idxAcc) return null
+  const indices = Uint32Array.from(idxAcc.getArray() as ArrayLike<number>)
+  const uvAcc = prim.getAttribute('TEXCOORD_0')!
+  const uv = Float32Array.from(uvAcc.getArray() as ArrayLike<number>)
+  const quads = findQuads(indices, uv)
+  if (!quads.length) return null
+
+  // every vertex attribute is rewritten by the same bilinear rule, so gather them once
+  const semantics = prim.listSemantics()
+  const attrs = semantics.map((s) => { const a = prim.getAttribute(s)!; return { s, acc: a, size: a.getElementSize(), data: Float32Array.from(a.getArray() as ArrayLike<number>) } })
+  const dropTri = new Uint8Array(indices.length / 3)
+  let trimmed = 0, dropped = 0, areaBefore = 0, areaAfter = 0
+  const { w, h } = opaque
+  for (const q of quads) {
+    areaBefore += (q.u1 - q.u0) * (q.v1 - q.v0)
+    const x0 = Math.floor(q.u0 * w), x1 = Math.ceil(q.u1 * w), y0 = Math.floor(q.v0 * h), y1 = Math.ceil(q.v1 * h)
+    const box = opaque.bounds(x0, y0, x1, y1)
+    if (!box) { dropTri[q.tris[0]] = 1; dropTri[q.tris[1]] = 1; dropped++; continue }
+    // the box in UV, widened by the margin, never past the quad's own rectangle
+    const nu0 = Math.max(q.u0, (box[0] - margin) / w), nu1 = Math.min(q.u1, (box[2] + margin) / w)
+    const nv0 = Math.max(q.v0, (box[1] - margin) / h), nv1 = Math.min(q.v1, (box[3] + margin) / h)
+    const newArea = (nu1 - nu0) * (nv1 - nv0)
+    areaAfter += newArea
+    if (newArea > (q.u1 - q.u0) * (q.v1 - q.v0) * 0.98) continue   // nothing worth moving
+    // corner k = (sv * 2 + su): new (s, t) inside the old quad, bilinear over the old corners
+    const old = attrs.map((a) => q.corners.map((c) => a.data.slice(c * a.size, (c + 1) * a.size)))
+    for (let k = 0; k < 4; k++) {
+      const su = k & 1, sv = k >> 1
+      const s = ((su ? nu1 : nu0) - q.u0) / (q.u1 - q.u0)
+      const t = ((sv ? nv1 : nv0) - q.v0) / (q.v1 - q.v0)
+      const vtx = q.corners[k]
+      attrs.forEach((a, ai) => {
+        if (a.s.startsWith('JOINTS')) return   // joint indices are not interpolable; the vertex keeps its own
+        const [ c00, c10, c01, c11 ] = old[ai]
+        for (let i = 0; i < a.size; i++) {
+          const top = c00[i] * (1 - s) + c10[i] * s
+          const bottom = c01[i] * (1 - s) + c11[i] * s
+          a.data[vtx * a.size + i] = top * (1 - t) + bottom * t
+        }
+      })
+      // the UVs are the new rectangle exactly (the bilinear rule lands there too, up to rounding)
+      const uvA = attrs.find((a) => a.s === 'TEXCOORD_0')!
+      uvA.data[vtx * 2] = su ? nu1 : nu0
+      uvA.data[vtx * 2 + 1] = sv ? nv1 : nv0
+    }
+    trimmed++
+  }
+  if (!trimmed && !dropped) return { quads: quads.length, trimmed, dropped, areaBefore, areaAfter }
+
+  // write back: dropped triangles leave the index list, orphaned vertices leave the arrays
+  const kept: number[] = []
+  for (let t = 0; t < dropTri.length; t++) if (!dropTri[t]) kept.push(indices[t * 3], indices[t * 3 + 1], indices[t * 3 + 2])
+  const remap = new Map<number, number>()
+  const order: number[] = []
+  for (const i of kept) if (!remap.has(i)) { remap.set(i, order.length); order.push(i) }
+  const newIndices = kept.map((i) => remap.get(i)!)
+  for (const a of attrs) {
+    const out = new Float32Array(order.length * a.size)
+    order.forEach((src, dst) => { for (let i = 0; i < a.size; i++) out[dst * a.size + i] = a.data[src * a.size + i] })
+    const acc = a.acc.clone() as Accessor
+    // normalised integer attributes (colours, weights) keep their storage; positions / uvs are float
+    acc.setArray(typedLike(a.acc, out) as never)
+    prim.setAttribute(a.s, acc)
+  }
+  const newIdx = idxAcc.clone() as Accessor
+  newIdx.setArray(order.length > 65535 ? Uint32Array.from(newIndices) : Uint16Array.from(newIndices))
+  prim.setIndices(newIdx)
+  return { quads: quads.length, trimmed, dropped, areaBefore, areaAfter }
+}
+
+/** The values back in the accessor's own storage type: getArray() hands out the RAW integers of an 8/16-bit
+ *  (normalised) attribute, the interpolation was linear on them, so they go back rounded, unscaled. */
+function typedLike(acc: Accessor, values: Float32Array): Float32Array | Uint8Array | Uint16Array | Int8Array | Int16Array {
+  const t = acc.getComponentType()
+  const conv = (C: { from(a: ArrayLike<number>, f: (v: number) => number): any }) => C.from(values, (v) => Math.round(v))
+  switch (t) {
+    case 5121: return conv(Uint8Array)
+    case 5123: return conv(Uint16Array)
+    case 5120: return conv(Int8Array)
+    case 5122: return conv(Int16Array)
+    default: return values
+  }
+}