lecodes-assets 0.2.0 → 2.4.10

package/src/commands/retarget/donor.ts

@@ -0,0 +1,63 @@
+// Loading the rigs of a retarget: any of the formats, a skeleton-only clip file bound onto the rig it
+// was animated on, and clip ASSETS (Unity .anim / Unreal AnimSequence) attached to the donor.
+
+import { existsSync, readFileSync } from "node:fs"
+import { basename } from "node:path"
+import { CliError, notFound } from "../../cli-kit"
+import type { Clip, Rig } from "../../retarget/rig"
+import { log, resolveInputs } from "../shared"
+
+export type UnrealLocation = { skeleton?: string, contentRoot?: string }
+
+const unboundNote = (names: string[]): string => `${names.slice(0, 3).join(", ")}${names.length > 3 ? ` +${names.length - 3}` : ""}`
+
+export const loadAnyRig = async (path: string, unreal: UnrealLocation): Promise<Rig> => {
+  const { loadRig, rigFromDocument } = await import("../../retarget/rig")
+  const lower = path.toLowerCase()
+  if (lower.endsWith(".uasset")) return (await import("../../unreal/rig")).rigFromUnreal(path, unreal)
+  if (lower.endsWith(".bvh")) {
+    const { bvhToDocument, describeBvh } = await import("../../bvh/toDocument")
+    const r = bvhToDocument(readFileSync(path, "utf8"), { name: basename(path).replace(/\.bvh$/i, "") })
+    log(`   ${basename(path)}: ${describeBvh(r.report)}`)
+    return rigFromDocument(r.doc, basename(path))
+  }
+  if (lower.endsWith(".fbx")) return loadRig(path)
+  const { makeIO } = await import("../../fbx/convert")
+  return rigFromDocument(await makeIO().read(path), basename(path))
+}
+
+/** A skeleton-only clip file (a mocap pack's FBX: nodes + curves, no mesh) has no skin to classify
+ *  and no bind to measure from: its clips are bound by bone name onto the rig it was animated on. */
+export const bindToDonorRig = async (donor: Rig, donorPath: string, rigPath: string, unreal: UnrealLocation): Promise<Rig> => {
+  if (!existsSync(rigPath)) throw notFound(rigPath)
+  const { rebindClips } = await import("../../retarget/rig")
+  const r = rebindClips(await loadAnyRig(rigPath, unreal), donor)
+  log(`   📎 ${basename(donorPath)}: ${r.bound}/${r.total} bones bound to ${basename(rigPath)} by name${Math.abs(r.scale - 1) > 0.01 ? ` · the clip's skeleton is ×${(1 / r.scale).toFixed(2)} the rig's size (rotations taken, lengths the rig's)` : ""}${r.unbound.length ? ` (no bone: ${unboundNote(r.unbound)})` : ""}`)
+  return r.rig
+}
+
+/** Clip assets that stand in for clips the donor rig file does not carry: Unity `.anim`
+ *  AnimationClips, or Unreal `.uasset` AnimSequences (each on its own skeleton, bound by name). */
+export const attachClipAssets = async (donor: Rig, files: string[], unreal: UnrealLocation): Promise<Rig> => {
+  const animFiles = resolveInputs(files, /\.(anim|uasset)$/i, false)
+  if (!animFiles.length) return donor
+  for (const f of animFiles) if (!existsSync(f)) throw notFound(f)
+  const attached: Clip[] = []
+  const report: { name: string, bound: number, total: number, unbound: string[] }[] = []
+  const unity = animFiles.filter((f) => /\.anim$/i.test(f))
+  if (unity.length) {
+    const { parseUnityAnim, attachUnityClips } = await import("../../retarget/unityAnim")
+    const r = attachUnityClips(donor, unity.map((f) => parseUnityAnim(readFileSync(f, "utf8"), basename(f).replace(/\.anim$/i, ""))))
+    attached.push(...r.clips); report.push(...r.report)
+  }
+  for (const f of animFiles.filter((x) => /\.uasset$/i.test(x))) {
+    const { loadUnreal } = await import("../../unreal/index")
+    const { attachUnrealClips } = await import("../../unreal/rig")
+    const u = loadUnreal(f, unreal)
+    if (!u.anim) throw new CliError(`${basename(f)}: not an AnimSequence (${u.kind}) — --anim wants animation assets`)
+    const r = attachUnrealClips(donor, u.skeleton, [ u.anim ])
+    attached.push(...r.clips); report.push(...r.report)
+  }
+  for (const r of report) log(`   📎 ${r.name.padEnd(20)} ${r.bound}/${r.total} curves bound${r.unbound.length ? `  (no bone: ${unboundNote(r.unbound)})` : ""}`)
+  return { ...donor, clips: [ ...donor.clips, ...attached ] }
+}

package/src/commands/retarget/index.ts

@@ -0,0 +1,169 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { basename, dirname } from "node:path"
+import { bool, defineCommand, int, list, missing, notFound, num, str, usageError } from "../../cli-kit"
+import type { RootMotion } from "../../retarget/retarget"
+import type { Rig } from "../../retarget/rig"
+import { log, megabytes, seconds, unrealFlags } from "../shared"
+import { attachClipAssets, bindToDonorRig, loadAnyRig } from "./donor"
+import { deriveMap, readMap, type MapSpec, type ResolvedMap } from "./map"
+import { printReport, printScaleNotes, printSkeletons, printTransfer } from "./report"
+
+/** A retarget is only meaningful if both rigs agree which way is forward: measure it from the
+ *  skeleton shape, falling back to the mapped head/tail bones, and return the signed yaw about +Y
+ *  that turns the donor's forward onto the target's (0 when they already agree within 2°). */
+const measureDonorYaw = async (target: Rig, donor: Rig, spec: MapSpec): Promise<number> => {
+  const { analyzeFacing, facingMismatch } = await import("../../retarget/retarget")
+  let fa: { forward: number[] } | null = null, da: { forward: number[] } | null = null
+  try {
+    // A biped faces where its toes point (its long horizontal axis is the ARM SPAN in a T-pose);
+    // a quadruped faces along its body.
+    const { classify } = await import("../../retarget/automap")
+    const { classifyBiped } = await import("../../retarget/humanoid")
+    const facingOf = (rig: Rig): { forward: number[] } => { try { return classifyBiped(rig) } catch { return classify(rig) } }
+    fa = facingOf(target); da = facingOf(donor)
+  } catch {
+    const pairs = Object.entries(spec.bones)
+    const head = pairs.find(([ t ]) => /head/i.test(t)), tail = pairs.find(([ t ]) => /tail|root|hip|pelvis/i.test(t))
+    if (head && tail) { fa = analyzeFacing(target, [ head[0], tail[0] ]); da = analyzeFacing(donor, [ head[1], tail[1] ]) }
+  }
+  if (!fa || !da) return 0
+  const off = facingMismatch(fa.forward as [number, number, number], da.forward as [number, number, number])
+  const signed = Math.atan2(da.forward[2] * fa.forward[0] - da.forward[0] * fa.forward[2], da.forward[0] * fa.forward[0] + da.forward[2] * fa.forward[2]) * 180 / Math.PI
+  log(`   facing: target [${fa.forward.map((x) => x.toFixed(2))}] vs donor [${da.forward.map((x) => x.toFixed(2))}] — ${off.toFixed(1)}° apart${off > 2 ? ` → turning the donor by ${signed.toFixed(1)}°` : ""}`)
+  return off > 2 ? signed : 0
+}
+
+export default defineCommand({
+  name: "retarget",
+  summary: "Drive one rig with ANOTHER rig's clips (different bone names, chain lengths and axis conventions are all fine)",
+  usage: "<target.glb> --from <donor.fbx|.glb|.uasset|.bvh>",
+  flags: {
+    from: str("the donor: the rig whose clips are taken", { value: "<donor>" }),
+    o: str("output (default: <target>.retargeted.glb)", { value: "out.glb" }),
+    map: str(`{ "root": "Hips", "bones": { targetBone: donorBone }, "align": { bone: "keep" | "direction" | "heading" | [ refBones ] }, "legs": [ footBones ] } (align / legs optional) — or "auto" to derive it and use it directly`, { value: "map.json|auto", group: "The bone map" }),
+    "auto-map": str("derive the map from the two skeletons' SHAPE and WRITE it. Quadrupeds: spine / neck / head / tail / legs / ears / jaw chains. Humanoids: both rigs' AVATARS (see `avatar`) joined on the canon", { value: "out.json", bare: "" }),
+    skeletons: bool("print both bone lists and exit (to write that map)"),
+    avatar: str("the target's avatar instead of deriving it (a Unity .meta works)", { value: "<a.avatar.json|model.meta>" }),
+    "donor-avatar": str("the donor's", { value: "<…>" }),
+    "donor-rig": str("the rig a skeleton-only clip file (mocap packs: nodes + curves, no mesh) was animated on — its clips bind to it by bone name", { value: "<model.fbx|.glb|.uasset>", group: "The donor's clips" }),
+    anim: list("clip assets to use as the donor's clips: Unity AnimationClips (packs shipping an empty FBX rig + .anim files) or Unreal AnimSequences (each on its own skeleton, bound by bone name)", { value: "a.anim b.uasset …" }),
+    clips: list("only these donor clips", { value: "a b …" }),
+    "keep-clips": bool("keep the target's own clips"),
+    "clip-names": list("rename the produced clips, positionally", { value: "n1 n2 …" }),
+    prefix: str("clip name prefix", { value: "s" }),
+    ...unrealFlags,
+    align: str("posture alignment (default bone-direction)", { value: "none|bone-direction", group: "Transfer" }),
+    ik: str("foot placement against the ground (default legs); hands = the hands as effectors too (clips where they meet or hold)", { value: "none|legs|hands" }),
+    "donor-ref": str("pose the donor's motion is measured from (auto = mean of its idle/walk)", { value: "bind|auto|<clip>" }),
+    "root-motion": str("where the travel lands: a root above the hips takes the horizontal travel, the hips the bob (auto/root); all on the hips; none = in place", { value: "auto|hips|root|none" }),
+    "root-rotation": str("what the root takes of the hips' turning (default none)", { value: "none|yaw" }),
+    "root-scale": num("root-motion scale", { positive: true }),
+    "heading-end": num("the baked heading curve must END here (a stop that turns: its idle faces the turn)", { value: "DEG" }),
+    loop: bool("the clips are LOOPS (last frame = first, a cycle on): the heading smoothed periodically — an arc loop's curve is then the clean ramp it runs"),
+    "no-plant": bool("no foot planting (each foot is otherwise LOCKED through its still windows)"),
+    stand: num("a target bound with the knees bent (more crouched than the donor's bind) stands up by K of the difference (0 = as bound, default; 1 = the donor's extension)", { value: "K" }),
+    "stand-clips": str("…in the clips matching this (default: all)", { value: "REGEX" }),
+    "min-knee": num("a SOFT limit on how straight a knee may get, degrees of bend (default none): a donor that locks its push-off leg otherwise lands the knee at exactly 0 for a few frames — a click; 12–14 also keeps it clear of the runtime's own reach clamp", { value: "DEG" }),
+    "foot-stance": str("the horizontal stance a planted foot keeps: the target's own foot-under-hip offset + the donor's departure from its bind (default), or the donor's offset whole, and each foot turned to the donor's HEADING (its own bind pitch kept) — a rig bound legs-apart / toes-out stands as the donor does", { value: "target|donor" }),
+    stairs: str(`donor clips to fit a STAIRCASE to (default: names containing "stair")`, { value: "<regex>|all|none" }),
+    platforms: str(`donor clips with a PLATFORM: two levels, the floor and the top (default "platform"); a foot slow at any other height (the wall) is no plant`, { value: "<regex>|all|none" }),
+    twist: str("twist helpers' share of their limb's axial turn (default 0.5)", { value: "N|off" }),
+    "body-clearance": num("a joint the donor has on the floor (a roll's back) keeps this much over the target's ground beyond the donor's height (default 0.05)", { value: "M", positive: true }),
+    fps: int("sampling rate", { group: "Sampling" }),
+    epsilon: num("key-reduction tolerance, metres (default 1e-4)", { value: "M", positive: true }),
+    "epsilon-deg": num("…and degrees (default 0.2°; hips + legs 0.01°)", { value: "D", positive: true }),
+  },
+  examples: [
+    "lecodes assets retarget fox.glb --from Wolf_Animation.fbx --skeletons",
+    "lecodes assets retarget fox.glb --from Wolf_Animation.fbx --auto-map fox-from-wolf.map.json",
+    "lecodes assets retarget hero.glb --from Walking.fbx --map auto --clip-names walk -o hero-walk.glb",
+  ],
+  run: async ({ args, flags, given }) => {
+    const input = args[0], donorPath = flags.from
+    if (!input) throw missing("the target GLB")
+    if (!donorPath) throw missing("--from <donor>")
+    for (const f of [ input, donorPath ]) if (!existsSync(f)) throw notFound(f)
+    const { rigFromDocument, checkUniformScale, hasSkin } = await import("../../retarget/rig")
+    const { retarget, bindAccessors } = await import("../../retarget/retarget")
+    const { makeIO, writeGlb } = await import("../../fbx/convert")
+
+    const doc = await makeIO().read(input)
+    const target = rigFromDocument(doc, basename(input))
+    const unreal = { skeleton: flags.skeleton, contentRoot: flags["content-root"] }
+    let donor = await loadAnyRig(donorPath, unreal)
+    if (flags["donor-rig"]) donor = await bindToDonorRig(donor, donorPath, flags["donor-rig"], unreal)
+    else if (!hasSkin(donor) && !flags.skeletons) throw usageError(`${basename(donorPath)} carries no skin (a clip-only file) — name the rig it was animated on: --donor-rig <model.fbx|.glb>`)
+    donor = await attachClipAssets(donor, flags.anim, unreal)
+
+    if (flags.skeletons) { await printSkeletons(target, input, donor, donorPath); return 0 }
+
+    const derive = given.has("auto-map") || flags.map === "auto" || !!flags.avatar || !!flags["donor-avatar"]
+    const { spec, humanoid }: ResolvedMap = derive
+      ? await deriveMap({ rig: target, file: input, avatar: flags.avatar }, { rig: donor, file: donorPath, avatar: flags["donor-avatar"] })
+      : await readMap(flags.map, target, donor)
+    if (given.has("auto-map")) {
+      const out = flags["auto-map"] || input.replace(/\.glb$/i, "") + "-from-" + basename(donorPath).replace(/\.[^.]+$/, "") + ".map.json"
+      writeFileSync(out, JSON.stringify(spec, null, 2) + "\n")
+      log(`💾 wrote ${out}  (${Object.keys(spec.bones).length} bones) — edit it, then: retarget … --map ${basename(out)}`)
+      return 0
+    }
+
+    checkUniformScale(target); checkUniformScale(donor)
+    const t0 = performance.now()
+    log(`🔁 ${basename(input)} ← ${basename(donorPath)}`)
+    const donorYawDeg = await measureDonorYaw(target, donor, spec)
+    printScaleNotes(target, donor)
+
+    if (!flags["keep-clips"]) for (const a of doc.getRoot().listAnimations()) a.dispose()
+    // The avatar's transfer block (the studio's decisions) supplies the defaults; flags override.
+    const tr = humanoid?.target.transfer
+    printTransfer(tr)
+    const prefix = flags.prefix ?? ""
+    const names = flags["clip-names"]
+    let produced = 0
+    const ikOff = flags.ik === "none" || spec.ik === false
+    const { stairsMatcher } = await import("../../retarget/marks")
+    const rep = retarget(target, donor, spec.bones, spec.root ?? null, {
+      align: (flags.align as "none" | "bone-direction" | undefined) ?? "bone-direction",
+      alignTo: spec.alignTo,
+      alignBones: spec.align,
+      donorYawDeg,
+      donorRef: flags["donor-ref"] === undefined ? spec.donorRef : flags["donor-ref"] === "bind" || flags["donor-ref"] === "auto" ? flags["donor-ref"] : { clip: flags["donor-ref"] },
+      ik: ikOff ? "none" : flags.ik === "hands" || (flags.ik === undefined && tr?.hands) ? "legs+hands" : "legs",
+      rootMotion: (flags["root-motion"] as RootMotion | undefined) ?? tr?.rootMotion ?? "auto",
+      headingEnd: flags["heading-end"],
+      loop: flags.loop,
+      rootRotation: (flags["root-rotation"] as "none" | "yaw" | undefined) ?? "none",
+      plant: flags["no-plant"] ? false : tr?.plant ?? true,
+      footStance: flags["foot-stance"] as "target" | "donor" | undefined,
+      minKnee: flags["min-knee"],
+      stand: flags.stand !== undefined ? ((k, re) => (name: string) => (re.test(name) ? k : 0))(flags.stand, new RegExp(flags["stand-clips"] ?? ".", "i")) : undefined,
+      stairs: stairsMatcher(flags.stairs, flags.platforms),
+      twist: flags.twist === undefined ? (tr?.twist !== undefined ? (tr.twist > 0 ? tr.twist : false) : 0.5) : flags.twist === "off" ? false : Number(flags.twist),
+      legs: spec.legs,
+      fps: flags.fps,
+      epsilon: flags.epsilon,
+      bodyClearance: flags["body-clearance"],
+      epsilonDeg: flags["epsilon-deg"],
+      rootScale: flags["root-scale"],
+      clips: flags.clips.length ? flags.clips : undefined,
+      rename: names.length || prefix ? (n: string) => prefix + (names[produced++] ?? n) : undefined,
+      humanoid,
+      warn: (w) => log(`   ⚠ ${w}`),
+    })
+    printReport(rep, { humanoid: !!humanoid, ikWanted: !ikOff })
+
+    bindAccessors(doc)
+    const out = flags.o ?? input.replace(/\.glb$/i, ".retargeted.glb")
+    const dir = dirname(out)
+    if (dir && !existsSync(dir)) mkdirSync(dir, { recursive: true })
+    const glb = await writeGlb(doc)
+    writeFileSync(out, glb)
+    const { validateGlb, formatReport } = await import("../../doctor/validateGlb")
+    const { probeDocument } = await import("../../probe")
+    log(formatReport(validateGlb(glb), out))
+    log(probeDocument(doc, out).split("\n").slice(1).join("\n"))
+    log(`💾 wrote ${out}  (${megabytes(glb.byteLength)}, ${seconds(t0)})`)
+    return 0
+  },
+})

package/src/commands/retarget/map.ts

@@ -0,0 +1,81 @@
+// WHICH target bone follows WHICH donor bone: a map file, or one derived from the two rigs —
+// humanoids through their avatars (both joined on the Unity/VRM canon), everything else from
+// skeleton SHAPE (retarget/automap.ts: a starting point the user reads and corrects).
+
+import { existsSync, readFileSync } from "node:fs"
+import { basename } from "node:path"
+import { CliError, notFound, usageError } from "../../cli-kit"
+import type { Avatar, AvatarFile } from "../../retarget/humanoid"
+import type { Rig } from "../../retarget/rig"
+import { log } from "../shared"
+
+export type MapSpec = {
+  _comment?: string
+  root?: string
+  bones: Record<string, string>
+  alignTo?: Record<string, string[]>
+  align?: Record<string, "keep" | "direction" | "heading" | string[]>
+  legs?: string[]
+  ik?: boolean
+  donorRef?: "bind" | "auto" | { clip: string, time?: number }
+  twist?: Record<string, string>
+  /** Both avatars of a humanoid map — reloaded so `--map file.json` keeps the humanoid treatment. */
+  avatars?: { target: AvatarFile, donor: AvatarFile }
+}
+export type Humanoid = { target: Avatar, donor: Avatar }
+export type ResolvedMap = { spec: MapSpec, humanoid?: Humanoid }
+
+type Side = { rig: Rig, file: string, avatar?: string }
+
+/** A humanoid rig's bones in the canon — given (`.avatar.json` / Unity `.meta`) or read off its shape. */
+const loadAvatar = async (rig: Rig, file: string | undefined): Promise<Avatar | null> => {
+  const { avatarFromRig, avatarFromUnity, avatarFromFile, parseUnityAvatar, isBiped } = await import("../../retarget/humanoid")
+  if (!file) return isBiped(rig) ? avatarFromRig(rig) : null
+  if (!existsSync(file)) throw notFound(file)
+  const text = readFileSync(file, "utf8")
+  return /\.meta$/i.test(file) ? avatarFromUnity(rig, parseUnityAvatar(text)) : avatarFromFile(rig, JSON.parse(text))
+}
+
+/** Derive the map from the rigs themselves. */
+export const deriveMap = async (target: Side, donor: Side): Promise<ResolvedMap> => {
+  const tAv = await loadAvatar(target.rig, target.avatar), dAv = await loadAvatar(donor.rig, donor.avatar)
+  const title = `${basename(target.file)} ← ${basename(donor.file)}`
+  if (tAv && dAv) {
+    const { mapAvatars, describeHumanoidMap, describeBiped, classifyBiped, avatarToFile } = await import("../../retarget/humanoid")
+    const hm = mapAvatars(tAv, dAv)
+    log(`🧭 humanoid map ${title}`)
+    for (const [ label, side ] of [ [ "target", target ], [ "donor", donor ] ] as const) {
+      try { log(`   ${label}: ${side.avatar ? `avatar from ${basename(side.avatar)} · ` : ""}${describeBiped(side.rig, classifyBiped(side.rig))}`) }
+      catch { log(`   ${label}: avatar from ${basename(side.avatar ?? "?")} (shape did not classify)`) }
+    }
+    for (const l of describeHumanoidMap(tAv, dAv, hm)) log(l)
+    return {
+      humanoid: { target: tAv, donor: dAv },
+      spec: { _comment: `humanoid map ${title} — target and donor avatars joined on the Unity/VRM canon; review before trusting`, root: hm.root, bones: hm.map, legs: hm.legs, twist: tAv.twist, avatars: { target: avatarToFile(tAv), donor: avatarToFile(dAv) } },
+    }
+  }
+  if (tAv || dAv) throw new CliError(`${tAv ? "the donor" : "the target"} does not read as a humanoid while ${tAv ? "the target" : "the donor"} does — a biped↔quadruped retarget needs a hand-written map`)
+  const { autoMap, describeSkeleton } = await import("../../retarget/automap")
+  const am = autoMap(target.rig, donor.rig)
+  log(`🧭 auto-map ${title}`)
+  log(`   target: ${describeSkeleton(target.rig, am.target)}`)
+  log(`   donor:  ${describeSkeleton(donor.rig, am.donor)}`)
+  for (const l of am.lines) log(l)
+  return { spec: { _comment: `auto-mapped ${title} by skeleton shape — review before trusting`, root: am.root, bones: am.map, legs: am.legs } }
+}
+
+/** Read a hand-written (or previously derived) map; its avatars, when it carries them, keep the humanoid treatment. */
+export const readMap = async (mapPath: string | undefined, target: Rig, donor: Rig): Promise<ResolvedMap> => {
+  if (!mapPath) throw usageError("--map <map.json> is required (--map auto / --auto-map [out.json] to derive one from the skeletons, --skeletons to list them)")
+  if (!existsSync(mapPath)) throw notFound(mapPath)
+  const spec = JSON.parse(readFileSync(mapPath, "utf8")) as MapSpec
+  if (!spec.bones) throw usageError(`${mapPath} has no "bones" object`)
+  if (!spec.avatars) return { spec }
+  try {
+    const { avatarFromFile } = await import("../../retarget/humanoid")
+    return { spec, humanoid: { target: avatarFromFile(target, spec.avatars.target), donor: avatarFromFile(donor, spec.avatars.donor) } }
+  } catch (e) {
+    log(`   ⚠ ${basename(mapPath)} carries avatars that do not fit these rigs (${(e as Error).message}) — plain map`)
+    return { spec }
+  }
+}

package/src/commands/retarget/report.ts

@@ -0,0 +1,77 @@
+// What a retarget prints: the two skeletons side by side (--skeletons), the avatar's transfer
+// defaults, and the run's report.
+
+import { basename } from "node:path"
+import type { Avatar } from "../../retarget/humanoid"
+import type { retarget } from "../../retarget/retarget"
+import type { Rig } from "../../retarget/rig"
+import { log } from "../shared"
+
+type Report = ReturnType<typeof retarget>
+
+/** Depth-first, parents before children — the shape you actually read a skeleton in. */
+const skeletonColumn = (rig: Rig): string[] => {
+  const kids: number[][] = rig.names.map(() => [])
+  const roots: number[] = []
+  rig.parents.forEach((par, i) => (par >= 0 ? kids[par].push(i) : roots.push(i)))
+  const out: string[] = []
+  const walk = (i: number, d: number): void => {
+    out.push(`${"  ".repeat(d)}${rig.names[i] || "?"}${rig.bind.fromSkin[i] ? " *" : ""}`)
+    for (const c of kids[i]) walk(c, d + 1)
+  }
+  roots.forEach((r) => walk(r, 0))
+  return out
+}
+
+export const printSkeletons = async (target: Rig, targetFile: string, donor: Rig, donorFile: string): Promise<void> => {
+  const a = skeletonColumn(target), b = skeletonColumn(donor)
+  log(`\n${`TARGET ${basename(targetFile)} (${target.names.length})`.padEnd(46)}DONOR ${basename(donorFile)} (${donor.names.length})`)
+  log(`${"(* = bound by a skin)".padEnd(46)}(* = bound by a skin)`)
+  for (let i = 0; i < Math.max(a.length, b.length); i++) log(`${(a[i] ?? "").slice(0, 44).padEnd(46)}${b[i] ?? ""}`)
+  log(`\ndonor clips: ${donor.clips.map((c) => `"${c.name}" ${c.duration.toFixed(2)}s`).join(", ") || "none"}`)
+  const { classifyBiped, describeBiped } = await import("../../retarget/humanoid")
+  for (const [ label, rig ] of [ [ "target", target ], [ "donor", donor ] ] as const) {
+    try { log(`${label} reads as a humanoid: ${describeBiped(rig, classifyBiped(rig))}`) } catch { /* not a biped — fine */ }
+  }
+}
+
+/** The avatar's transfer block (the studio's decisions) supplies the defaults; flags override. */
+export const printTransfer = (tr: Avatar["transfer"]): void => {
+  if (!tr || !Object.keys(tr).length) return
+  const parts: string[] = []
+  if (tr.rootMotion) parts.push(`root motion ${tr.rootMotion}`)
+  if (tr.plant !== undefined) parts.push(tr.plant ? "plant" : "no plant")
+  if (tr.hands) parts.push("hands IK")
+  if (tr.twist !== undefined) parts.push(`twist ${tr.twist}`)
+  for (const s of [ "Left", "Right" ] as const) if (tr.roll?.[s]) parts.push(`${s[0]} roll ${tr.roll[s]! > 0 ? "+" : ""}${tr.roll[s]}°`)
+  const byVerdict = (v: string): string[] => Object.entries(tr.align ?? {}).filter(([ , x ]) => x === v).map(([ k ]) => k)
+  const keep = byVerdict("keep"), al = byVerdict("align")
+  if (keep.length) parts.push(`keep ${keep.join(", ")}`)
+  if (al.length) parts.push(`align ${al.join(", ")}`)
+  log(`   avatar transfer: ${parts.join(" · ")}`)
+}
+
+export const printScaleNotes = (target: Rig, donor: Rig): void => {
+  for (const [ label, rig ] of [ [ "target", target ], [ "donor", donor ] ] as const) {
+    if (rig.bind.scale !== 1) log(`   ℹ ${label} skin's bind space is ×${+(1 / rig.bind.scale).toPrecision(4)} of node space — bind pose rescaled ×${+rig.bind.scale.toPrecision(4)} to match`)
+  }
+}
+
+export const printReport = (rep: Report, opts: { humanoid: boolean, ikWanted: boolean }): void => {
+  if (opts.humanoid) log(`   humanoid: torso/legs keep, arms + fingers aligned (≥ 8°)${rep.roll.length ? ` · palm roll ${rep.roll.map((r) => `${r.side[0]} ${r.degrees.toFixed(0)}° (${r.via})`).join(", ")}` : ""}${rep.rootTranslateOnly ? " · root takes the hips' travel only" : ""}`)
+  if (rep.bindGap.donor.worst > 1e-3) log(`   ℹ donor's node pose sits ${rep.bindGap.donor.worst.toFixed(3)}m from its bind pose (worst: ${rep.bindGap.donor.bone}) — anchoring on the bind pose`)
+  log(`   ${rep.mapped.length} bones mapped · ${rep.align.length} direction-aligned (worst ${rep.align[0]?.degrees.toFixed(0) ?? 0}° on ${rep.align[0]?.bone ?? "-"})${rep.underThreshold.length ? ` · ${rep.underThreshold.length} under 8° kept (worst ${rep.underThreshold[0].degrees.toFixed(0)}° on ${rep.underThreshold[0].bone})` : ""} · ${rep.kept.length} keep bind (${rep.kept.join(", ") || "-"})`)
+  log(`   donor reference: ${rep.donorRef} (leg directions ${rep.legDisagreement.toFixed(0)}° apart between the binds) · target binds ${rep.stance ? "in a stance — legs keep it" : "posed — legs aligned to the donor"}`)
+  log(`   root ${rep.root ? `${rep.root.target}←${rep.root.donor} ×${+rep.rootScale.toPrecision(3)} (from ${rep.rootScaleFrom})` : "none"}${rep.ground ? ` · ground target ${rep.ground.target.toFixed(3)}m / donor ${rep.ground.donor.toFixed(3)}m` : ""}`)
+  if (rep.legs.length) for (const l of rep.legs) log(`   ${l.isFoot ? "🦶" : "✋"} ${l.effector.padEnd(14)} ← ${l.donorEffector.padEnd(12)} chain ${l.chain.join("→")}${l.contact !== l.effector ? `  contact ${l.contact}` : ""}  ×${l.ratio.toFixed(3)}${l.planted ? `  planted ${l.planted} frames` : ""}${l.shortfall > 1e-4 ? `  ⚠ out of reach by up to ${(l.shortfall * 1000).toFixed(0)}mm` : ""}`)
+  else if (opts.ikWanted) log(`   ℹ no leg chains detected — feet follow FK only (name them in the map: "legs": [ … ])`)
+  if (rep.root) log(`   root motion: ${rep.rootMotion}${rep.hipsBob ? ` · hips carry the ${rep.hipsBob === "donor" ? "donor's own bob" : "vertical bob"}` : ""}`)
+  if (rep.twist.length) log(`   twist helpers: ${rep.twist.map((t) => `${t.bone} (${(t.at * 100).toFixed(0)}% of ${t.of})`).join(", ")}`)
+  if (rep.bridges.length) log(`   bridged (interpolated between mapped bones): ${rep.bridges.join(", ")}`)
+  if (rep.unmappedTarget.length) log(`   unmapped (left at rest): ${rep.unmappedTarget.join(", ")}`)
+  for (const c of rep.clips) {
+    const worst = (kind: string): { n: number, mm: string } => { const e = c.events.filter((x) => x.kind === kind); return { n: e.length, mm: (Math.max(0, ...e.map((x) => x.value ?? 0)) * 1000).toFixed(0) } }
+    const reach = worst("reach"), below = worst("below")
+    log(`   🎞  ${c.name.padEnd(22)} ${c.duration.toFixed(2)}s  ${c.frames} frames → ${c.keys} keys${reach.n ? `  ⚠ ${reach.n}× out of reach (${reach.mm} mm)` : ""}${below.n ? `  ⚠ ${below.n}× toe under the ground (${below.mm} mm)` : ""}`)
+  }
+}

package/src/commands/scene.ts

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+import { bool, defineCommand, int, missing, notFound, num, str, usageError } from "../cli-kit"
+import { log, regexFlag, seconds } from "./shared"
+
+/** `x0,z0,x1,z1` (any corner order) → [minX, minZ, maxX, maxZ]. */
+const parseDropAt = (s: string | undefined): [number, number, number][] | undefined => {
+  if (!s) return undefined
+  return s.split(";").filter((p) => p.trim()).map((p) => {
+    const v = p.split(",").map(Number)
+    if (v.length !== 3 || v.some((n) => !Number.isFinite(n))) throw usageError(`--drop-at wants x,y,z;x,y,z — got "${p}"`)
+    return [ v[0], v[1], v[2] ] as [number, number, number]
+  })
+}
+
+const parseRegion = (raw: string | undefined): [number, number, number, number] | undefined => {
+  if (raw === undefined) return undefined
+  const v = raw.split(",").map(Number)
+  if (v.length !== 4 || v.some((x) => !Number.isFinite(x))) throw usageError(`--region wants x0,z0,x1,z1 (Unity metres), got "${raw}"`)
+  return [ Math.min(v[0], v[2]), Math.min(v[1], v[3]), Math.max(v[0], v[2]), Math.max(v[1], v[3]) ]
+}
+
+export default defineCommand({
+  name: "scene",
+  summary: "Unity scene → level JSON, or (--project) GLBs + scene files inside a LeCodes project",
+  usage: "<map.unity>",
+  description: `
+    Nested prefabs are expanded with their overrides into KINDS (meshes + materials + LOD levels +
+    colliders), one placement per instance in LeCodes' frame; the terrain (binary TerrainData read)
+    with its painted trees + detail meshes as placements; the lights.
+
+    With --project it is built INTO a LeCodes project: one GLB per kind (assets/<map>/), a prefab
+    scene file per kind with its colliders (src/<map>/), the terrain (.terrain + packed layers) and
+    src/<map>.scene.ts placing everything. The command line is written into that file's header:
+    re-import with the same line, the flags carry decisions the file cannot show.`,
+  flags: {
+    o: str("the level JSON (default: <map>.level.json beside the scene)", { value: "level.json" }),
+    project: str("build into this LeCodes project instead", { value: "<dir>", group: "Into a project" }),
+    name: str("map name: folder + scene file stem (default: the Unity scene's name, lower-cased)", { value: "map" }),
+    "max-size": int("texture size cap (1024)"),
+    png: bool("PNG textures, no KTX2"),
+    force: bool("reconvert every GLB (default: only the kinds that changed)"),
+    "no-sun": bool("leave the pack's sun out of the scene file: the level owns the directional light"),
+    foliage: str("which kinds wear the vegetation tier ('foliage: true': wind, touch bending, per-copy tint): exactly the kind names matching this. Default: kinds with a material in a Vegetation/Plants/Grass/Trees folder or named so (Grass_01, M_Bush_Set) — never by alpha mode; the verdict is printed", { value: "<re>" }),
+    "no-foliage": bool("…or none"),
+    "no-lightmap": str("kinds whose name matches take 'lightmap: false' — no rect in the bake, lit in real time. Written for LAMP FIXTURES (the bulb sits inside its housing, so the fixture's own faces come out the brightest texels in the level) and for anything the game moves", { value: "<re>" }),
+    "collider-fit": num(`metres a pack's BOX collider face may stand off the geometry under it before the kind takes a mesh collider instead (default 0.015). A box is an approximation: the shooting range's wall module is flat at ±0.100 m while its box was fitted to the ±0.138 m of its edge trim, so bullets stopped 3.8 cm in front of the wall and their holes and sparks landed in mid-air. 0 = every box with any gap goes to a mesh, a big number = keep the pack's boxes whatever they cover`, { value: "<m>" }),
+    "no-shadows": str("kinds whose name matches take 'castShadows: false': a pack's BACKGROUND MOUNTAINS are 2 km meshes a kilometre out that Unity's shadow distance never reaches, and here their shadow lies across the whole map", { value: "<re>" }),
+    "no-colliders": bool("write NO colliders: the kinds are pure visuals, nothing gets a Physics body. For a viewer, or a level whose 78 000 placements would otherwise be 20 000 Jolt bodies before the game adds one of its own"),
+    "max-tris": int("triangles a kind may have before the import simplifies it (default 50000, 0 = no cap): a photogrammetry scan otherwise arrives as a million-triangle prop AND mesh collider"),
+    "no-trim-cards": bool("skip the alpha-card trim the import otherwise runs (it can empty a kind whose decal atlas is mostly clear)"),
+    filter: str("keep only instances whose kind name / scene group / node name matches", { value: "<re>", group: "Subset" }),
+    "drop-at": str(`leave OUT the placements standing at these points ("x,y,z;x,y,z", the lecodes frame the scene file prints, within 10 cm): the one instance of a kind the game moves while its twins stay put — the range's five lane targets, which Unity names like the sixth on a shelf`, { value: "<x,y,z;…>" }),
+    drop: str("leave every instance whose kind / group / node name matches OUT of the scene (and its kind out of the import): props a pack authors sunk into the geometry they decorate", { value: "<re>" }),
+    group: str("only instances under a scene group whose path contains this", { value: "name" }),
+    region: str("only instances inside this Unity X/Z rectangle", { value: "x0,z0,x1,z1" }),
+    "no-trees": bool("skip the terrain's painted trees"),
+    "no-details": bool("skip the terrain's detail meshes"),
+    "include-inactive": bool("import inactive GameObjects too"),
+    handedness: str("how Unity's left-handed frame is undone (default x: −x, (x, −y, −z, w))", { value: "x|none", group: "Source" }),
+    index: str("GUID → path table (default: found above the scene, else .meta sidecars)", { value: "<unity-index.txt>" }),
+  },
+  examples: [
+    `lecodes assets scene Outdoor.unity --project . --name school --force`,
+    `lecodes assets scene LV_Showcase.unity --project . --drop Sign --no-lightmap lamp`,
+    `lecodes assets scene Demo.unity --region 0,0,120,120 -o demo.level.json`,
+  ],
+  run: async ({ args, flags, argv }) => {
+    const input = args[0]
+    if (!input) throw missing("the .unity scene")
+    if (!existsSync(input)) throw notFound(input)
+    const region = parseRegion(flags.region)
+    const hand = flags.handedness ?? "x"
+    if (hand !== "x" && hand !== "none") throw usageError("--handedness wants x | none")
+    const { importUnityScene, describeSceneImport } = await import("../unity/scene")
+    const t0 = performance.now()
+    const r = await importUnityScene(input, {
+      indexFile: flags.index, handedness: hand, filter: regexFlag(flags.filter), drop: regexFlag(flags.drop), dropAt: parseDropAt(flags["drop-at"]), group: flags.group, region,
+      includeInactive: flags["include-inactive"], noTrees: flags["no-trees"], noDetails: flags["no-details"],
+    })
+    log(`🗺  ${input}`)
+    for (const l of describeSceneImport(r)) log(`   ${l}`)
+    if (flags.project) {
+      const { writeLeCodesLevel } = await import("../unity/lecodesLevel")
+      const res = await writeLeCodesLevel(r, {
+        project: flags.project, name: flags.name, force: flags.force, maxSize: flags["max-size"] ?? 1024, ktx2: !flags.png, log,
+        foliage: regexFlag(flags.foliage), noFoliage: flags["no-foliage"], noSun: flags["no-sun"],
+        noLightmap: regexFlag(flags["no-lightmap"]), noTrimCards: flags["no-trim-cards"], colliderFit: flags["collider-fit"], noColliders: flags["no-colliders"], noShadows: regexFlag(flags["no-shadows"]), maxTris: flags["max-tris"],
+        // the invocation, for the scene file's header (quote what a shell would need quoted)
+        command: "lecodes assets scene " + argv.map((a) => (/[\s"'|<>^&();]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(" "),
+      })
+      log(`💾 ${res.scene} — ${res.kinds} kinds (${res.converted} converted, ${res.reused} up to date), ${r.instances.length} placements, ${seconds(t0)}`)
+      return 0
+    }
+    const out = flags.o ?? input.replace(/\.unity$/i, "") + ".level.json"
+    const dir = dirname(out)
+    if (dir && !existsSync(dir)) mkdirSync(dir, { recursive: true })
+    const { terrainData: _, ...json } = r
+    writeFileSync(out, JSON.stringify(json, null, 1) + "\n")
+    log(`💾 wrote ${out}  (${r.instances.length} instances, ${seconds(t0)}) — frame: ${r.frame}`)
+    return 0
+  },
+})

package/src/commands/shared.ts

@@ -0,0 +1,121 @@
+// What several commands share: flag groups (spread into `flags:`), the doctor's options read off
+// them, the doctor's result printed, and input expansion.
+
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+import { bool, int, num, str, type FlagValues } from "../cli-kit"
+import type { ApplyResult, DoctorOptions } from "../doctor/doctor"
+
+export const log = (s: string): void => console.log(s)
+export const warnLine = (w: { level: string, message: string }): void => log(`   ${w.level === "warn" ? "⚠" : "ℹ"} ${w.message}`)
+export const seconds = (t0: number): string => `${((performance.now() - t0) / 1000).toFixed(1)}s`
+export const megabytes = (bytes: number): string => `${(bytes / 1024 / 1024).toFixed(2)} MB`
+
+// ---- flag groups ------------------------------------------------------------------------------------
+
+/** Where an Unreal asset's skeleton / pack is found. */
+export const unrealFlags = {
+  skeleton: str("(Unreal) the skeleton a clip was authored on — by default it is found in the pack by the object path the clip carries", { value: "<SK.uasset>", group: "Unreal" }),
+  "content-root": str("(Unreal) the pack's Content folder, if the search cannot find it", { value: "<dir>" }),
+}
+
+/** The doctor passes `convert` and `doctor` both run. */
+export const doctorFlags = {
+  fix: bool("run the doctor passes (bone cap, texture normalize) before writing", { group: "Doctor passes" }),
+  ktx2: bool("textures → KTX2 (needs KTX-Software: toktx, or ktx ≥ 4.4): colour on ETC1S, every DATA map (normal, metal/rough, occlusion) on UASTC"),
+  "ktx2-hq": bool("the same as --ktx2"),
+  "ktx2-uastc": bool("EVERYTHING on UASTC — for HERO assets (first-person weapon, gloves) where ETC1S blocking is visible at 30 cm. ~8x larger"),
+  "max-size": int("texture size cap (2048)"),
+  target: int("bone cap (256)"),
+  "fix-metallic": bool("zero metallic on materials that carry it without an MR texture (they may render BLACK without IBL)"),
+  "fix-scale": bool("bake an auto unit fix (cm/mm/inch/0.01-armature → metres) — scale is always REPORTED, applied only with a flag"),
+  scale: num("bake an explicit factor", { positive: true }),
+  "scale-to": num("make the largest dimension M metres", { value: "M", positive: true }),
+  "fix-emissive": bool("drop a self-lit emissive (emissive = base colour → ~2x too bright)"),
+  unlit: bool("flat base colour, no lighting (KHR_materials_unlit) — for stylised assets"),
+  "trim-cards": bool("cut every alpha-MASK quad (a foliage card) to the box of its opaque texels and drop empty ones — less discarded fill per card; PNG/JPEG base colour only, so run it with --ktx2 rather than after it"),
+  "trim-margin": int("texels kept around a trimmed card (2)"),
+  merge: bool("fewer draw calls: every part's primitive into ONE per material class (alpha mode + cutoff, double-sided, unlit) with ONE material whose base / normal / ORM / emissive maps are ATLASES of the parts' maps (factors baked in, UVs remapped); the parts' skins become one skin, a static part under a bone is skinned to it, a plain node's transform is baked. Node-animated parts and morph targets stay as they are. KTX2 parts decode through KTX-Software's ktx tool (next to toktx). The atlas is written PNG and goes through the texture passes like any map (--ktx2 encodes it)"),
+  "atlas-size": int("atlas edge cap (2048): the smallest power of two that holds every part's map at full size, else the tiles shrink to fit BY SURFACE AREA — every part at the same texels per metre (a torso keeps its map, a buckle gets a small tile), none past its native size; --max-size does not apply to the atlas"),
+  "atlas-uniform": bool("…or shrink every tile by the same factor instead"),
+  "atlas-pad": int("edge-replication gutter per tile (8 texels)"),
+  "merge-exclude": str("parts (node names) to leave out — the ones the game hides or swaps", { value: "<regex>" }),
+}
+
+type DoctorFlagValues = FlagValues<typeof doctorFlags>
+
+export const wantsKtx2 = (f: DoctorFlagValues): boolean => f.ktx2 || f["ktx2-hq"] || f["ktx2-uastc"]
+export const wantsScale = (f: DoctorFlagValues): boolean => f["fix-scale"] || f.scale !== undefined || f["scale-to"] !== undefined
+
+/** Any flag that CHANGES the file (so `doctor` writes one, and `convert` runs the doctor at all). */
+export const wantsDoctorFix = (f: DoctorFlagValues): boolean =>
+  f.fix || wantsKtx2(f) || wantsScale(f) || f.unlit || f["fix-emissive"] || f["trim-cards"] || f.merge
+
+export const doctorOptions = (f: DoctorFlagValues): DoctorOptions => ({
+  ktx2: wantsKtx2(f), ktx2Hq: f["ktx2-hq"], ktx2Uastc: f["ktx2-uastc"], maxSize: f["max-size"], target: f.target,
+  scale: f.scale, scaleTo: f["scale-to"], fixScale: f["fix-scale"],
+  unlit: f.unlit, fixEmissive: f["fix-emissive"],
+  trimCards: f["trim-cards"], trimMargin: f["trim-margin"],
+  merge: f.merge, atlasSize: f["atlas-size"], atlasPad: f["atlas-pad"], mergeExclude: f["merge-exclude"], atlasUniform: f["atlas-uniform"],
+})
+
+export const ktx2Progress = (done: number, total: number): void => { process.stdout.write(`\r   encoding ktx2… ${done}/${total}${done === total ? "\n" : ""}`) }
+
+/** What `applyPlan` did, one line per pass that did anything. */
+export const logDoctorResult = (res: ApplyResult): void => {
+  if (res.metallicZeroed) log(`   zeroed metallic on ${res.metallicZeroed} material(s)`)
+  if (res.bareFixed) log(`   gave ${res.bareFixed} material-less primitive(s) a white dielectric material`)
+  if (res.emissiveCleared) log(`   cleared self-lit emissive on ${res.emissiveCleared} material(s)`)
+  if (res.unlit) log(`   ${res.unlit} material(s) → unlit (flat base colour, no lighting)`)
+  if (res.scaled !== 1) log(`   baked scale ×${+res.scaled.toPrecision(6)}`)
+  if (res.merge) {
+    log(`   merge: ${res.merge.primitivesBefore} primitive(s) → ${res.merge.primitivesAfter} draw call(s)`)
+    for (const g of res.merge.groups) log(`     ${g.label}: ${g.primitives} primitives / ${g.materials} material(s) → ${g.vertices} vertices, ${g.triangles} triangles${g.atlas ? `, atlas ${g.atlas}` : ""}${g.joints ? `, ${g.joints} joints` : ""}`)
+    if (res.merge.skipped.length) log(`     skipped: ${res.merge.skipped.slice(0, 6).map((s) => `${s.name} (${s.reason})`).join(", ")}${res.merge.skipped.length > 6 ? "…" : ""}`)
+  }
+  const cards = res.cards
+  if (cards) log(`   cards: ${cards.trimmed} quad(s) trimmed, ${cards.dropped} empty quad(s) dropped of ${cards.quads} over ${cards.primitives} primitive(s) — card area ${cards.areaBefore > 0 ? Math.round(100 * cards.areaAfter / cards.areaBefore) : 100}% of before${cards.skipped.length ? `; skipped ${cards.skipped.map((s) => `${s.name} (${s.reason})`).slice(0, 3).join(", ")}` : ""}`)
+  if (res.lod) {
+    for (const t of res.lod.tris) log(`   lod: ${t.name} ${t.levels.join(" / ")} tris`)
+    for (const b of res.lod.bones) log(`   lod bones: ${b.name} last level ${b.before} → ${b.after} joints`)
+    for (const k of res.lod.skipped) log(`   lod: ${k.name} level ${k.level} dropped — the simplifier reached only ${k.tris} tris (seams / hard surfaces; try a smaller ratio)`)
+    if (!res.lod.nodes) log(`   lod: no mesh with >= 2000 triangles (or the _LOD nodes are already there)`)
+  }
+}
+
+// ---- inputs -------------------------------------------------------------------------------------------
+
+/** Positionals → concrete files: plain files, directories, and globs (`*.glb`, `dir/**\/*.glb`).
+ *  Generated outputs (.ktx2.glb / .fixed.glb) are skipped when EXPANDING a glob or a directory, but
+ *  kept when named explicitly (e.g. to --dump one). A minimal glob of our own: this also runs under
+ *  Node, where the lecodes CLI is a plain binary. */
+export const resolveInputs = (args: string[], ext = /\.glb$/i, skipGenerated = true): string[] => {
+  const out: string[] = []
+  const keep = (f: string): void => { if (ext.test(f) && !(skipGenerated && /\.(ktx2|fixed)\.glb$/i.test(f))) out.push(f) }
+  const walk = (dir: string, recursive: boolean, pattern: RegExp): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, entry.name).replace(/\\/g, "/")
+      if (entry.isDirectory()) { if (recursive) walk(p, true, pattern) }
+      else if (pattern.test(entry.name)) keep(p)
+    }
+  }
+  const toRegex = (glob: string): RegExp =>
+    new RegExp("^" + glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$", "i")
+  for (const raw of args) {
+    const a = raw.replace(/\\/g, "/")
+    if (/[*?]/.test(a)) {
+      const segs = a.split("/")
+      const last = segs.pop()!
+      const recursive = segs[segs.length - 1] === "**"
+      if (recursive) segs.pop()
+      const dir = segs.join("/") || "."
+      if (existsSync(dir)) walk(dir, recursive, toRegex(last))
+    } else if (existsSync(a) && statSync(a).isDirectory()) {
+      walk(a.replace(/\/+$/, ""), false, ext)
+    } else out.push(a)
+  }
+  return [ ...new Set(out) ]
+}
+
+/** `--x <regex>` as a case-insensitive RegExp, or undefined. */
+export const regexFlag = (v: string | undefined): RegExp | undefined => (v ? new RegExp(v, "i") : undefined)