lecodes-cli 0.20.2 → 2.0.0

package/src/commands/lightmap.ts

@@ -1,290 +1,581 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs"
-import { spawn, spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
-import { join, relative, resolve } from "node:path"
-import { findProjectRoot } from "../manifest"
+import { basename, dirname, join, relative, resolve } from "node:path"
+import { deflateSync } from "node:zlib"
 import { buildBundle } from "./compile"
-import { readAppConfigAt, resolveDesktopRenderer } from "./appShared"
-import { runDesktopRender } from "../desktopRenderer"
-import { CliError, c, flagStr, flagBool, logErr, note, warnErr, type Args } from "../util"
+import { readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
+import { runDesktopRender } from "../hosts/desktopRenderer"
+import { CliError, bool, c, defineCommand, log, logErr, note, num, str, warnErr } from "../cli"
+import { bundleFlags, bundleOptions, localProject } from "./shared"
 
 /*
- * `lecodes lightmap bake` — bake static shadows, ambient occlusion and the level's point lights for
- * the local project (docs/lightmap-plan.md). The app is compiled with a synthetic entry that puts it
- * in BAKE mode (`globalThis.__lecodesLightmap = { outDir, … }`, then `import "./main"`) and run in the
- * native desktop host; when the app calls `Lightmap.load(...)` — the point where its scene is
- * complete — the SDK sees the flag and calls `_creator.lightmapBake` instead of loading: creator-gl
- * traces every `Lightmap.add`-registered static against the scene's sun and point lights and writes
- * its rasters (PNGs, INTERMEDIATES) + lightmap.bake into --out. The host's stdout carries
- * "[lightmap] …" progress lines; "[lightmap] done" is the success marker. The atlases then ship as
- * **KTX2**: the CLI runs KTX-Software's toktx (UASTC + zstd + mips, sRGB transfer function — the bake
- * encodes sRGB on purpose, precision in the darks) and deletes the PNGs. toktx is REQUIRED — the
- * command refuses to start without it, so a bake never leaves a half-finished output behind.
+ * `lecodes lightmap` — the baked lighting of a level (engines/bake).
  *
- * Output, under --out with the --name stem (default `lightmap`, so a project with several baked
- * levels gives each its own stem — `app build desktop` rejects two resources of one basename):
- *   <name>.bake                 rects, pages, the baked lights (what the scene's `data` names)
- *   <name>.ktx2, <name>_1.ktx2… the atlas pages — R = sun visibility, G = ambient occlusion
- *   <name>-light[_n].ktx2       the point lights' baked irradiance, only when the level holds any
- *   <name>.volume               the light volume for movers (unless --no-volume)
+ *   bake      compile the app with a synthetic entry that puts it in BAKE mode (`globalThis.__lecodesLightmap`),
+ *             run it in the native desktop host; when the app calls `Lightmap.load(...)` — the point where its
+ *             scene is complete — the SDK calls `_creator.lightmapBake` instead of loading: the host describes
+ *             every registered static to creator-bake, which traces the sun, the sky and the lamps on the
+ *             NVIDIA card and writes <out>/<name>.bake + <name>-light[_n].ktx2 + <name>-aux[_n].ktx2 itself
+ *             (no toktx, no PNG intermediates). "[lightmap] done" is the success marker.
+ *   stats     the per-instance numbers a .bake carries (mean lux, sun / sky visibility, texels, rect)
+ *   diff      the noise of a bake per instance: two bakes with different --seed compared texel by texel
+ *   inspect   PNGs from the float layers a `bake --debug-dir` kept: whole pages or one instance's rect
  *
- * Only the desktop host has the bake module (a dev tool — never in the wasm / mobile engines), so
- * this needs a host with it: a local build via LECODES_DESKTOP_EXE until the release ships it.
+ * Only a desktop host built with the CUDA toolkit has the bake — a local build via LECODES_DESKTOP_EXE.
  * The props need lightmap UVs first: `lecodes assets doctor assets/props/*.glb --lightmap-uv`.
  */
 
-const num = (args: Args, key: string, fallback: number, min: number, max: number): number => {
-  const raw = flagStr(args, key)
-  if (raw === undefined) return fallback
-  const n = Number(raw)
-  if (!Number.isFinite(n) || n < min || n > max) throw new CliError(`--${key} wants a number in ${min}..${max}, got "${raw}".`)
-  return n
+const range = (name: string, value: number, min: number, max: number): number => {
+  if (value < min || value > max) throw new CliError(`--${name} wants a number in ${min}..${max}, got "${value}".`)
+  return value
 }
 
-// ---- toktx (KTX-Software) — same lookup as lecodes-assets' doctor --------------------------------
+type BakeInstance = { key: string, receiver: boolean, page?: number, rect?: number[], st?: number[], texels?: number, area?: number, charts?: number, mean?: number[], sunVis?: number, skyVis?: number, share?: number }
+type BakeData = { version: number, size: number, pages: number, texel: number, lightScale: number, light: string[], aux: string[], direct?: string[], indirect?: string[], probes?: { file: string, size: number, levels: number, count: number, spacing: number } | null, volume?: { file: string, n: number[], cell: number[], valid: number } | null, texels?: number, instances: BakeInstance[], sun?: unknown, sky?: unknown, lights?: unknown[] }
 
-const findToktx = (): string => {
-  const env = process.env.KTX_TOKTX
-  if (env && existsSync(env)) return env
-  for (const base of [ process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, "Programs"), process.env.ProgramFiles ]) {
-    if (!base) continue
-    const guess = join(base, "KTX-Software", "bin", "toktx.exe")
-    if (existsSync(guess)) return guess
-  }
-  return "toktx"   // on PATH
+const readBake = (file: string): BakeData => {
+  if (!existsSync(file)) throw new CliError(`No bake at ${file} — run \`lecodes lightmap bake\` first.`)
+  const data = JSON.parse(readFileSync(file, "utf8")) as BakeData
+  if (data.version !== 4) throw new CliError(`${file} is not a creator-bake file (version ${String(data.version)}) — rebake.`)
+  return data
 }
 
-const checkToktx = (toktx: string): string | null => {
-  try {
-    const p = spawnSync(toktx, [ "--version" ], { encoding: "utf8" })
-    if (p.status === 0) return (p.stdout ?? "").toString().trim() || "toktx"
-  } catch { /* not found */ }
-  return null
+const probeLayoutOf = (s: string): "rooms" | "grid" => {
+  if (s !== "rooms" && s !== "grid") throw new CliError(`--probe-layout is rooms or grid, got "${s}".`)
+  return s
 }
 
-const requireToktx = (): string => {
-  const toktx = findToktx()
-  if (!checkToktx(toktx)) {
-    throw new CliError("lecodes lightmap bake needs KTX-Software's toktx — the atlas ships as KTX2 (GPU-compressed, mipmapped).\n  Install it from https://github.com/KhronosGroup/KTX-Software/releases (make sure toktx is on PATH) or set KTX_TOKTX=<path to toktx>.")
-  }
-  return toktx
+/** `--probe-box x0,y0,z0,x1,y1,z1` → six numbers, min then max per axis */
+const probeBoxOf = (s: string): [number, number, number, number, number, number] => {
+  const v = s.split(",").map((t) => Number(t.trim()))
+  if (v.length !== 6 || v.some((x) => !Number.isFinite(x))) throw new CliError(`--probe-box wants six numbers x0,y0,z0,x1,y1,z1, got "${s}".`)
+  return [ Math.min(v[0], v[3]), Math.min(v[1], v[4]), Math.min(v[2], v[5]), Math.max(v[0], v[3]), Math.max(v[1], v[4]), Math.max(v[2], v[5]) ]
 }
 
-/** PNG raster → .ktx2: UASTC (the high-quality Basis codec — ETC1S blocks the shadow edges),
- *  zstd supercompression, a full mip chain, sRGB transfer function (what the bake encodes and what
- *  the ordinary texture path expects; the KTX2 reader refuses a mismatch instead of guessing). */
-// Async so the pages encode CONCURRENTLY: toktx's zstd + mip stages are serial per file, and the four
-// pages of a two-page bake with a light atlas took 23 s one after another against 10 s side by side.
-const encodeKtx2 = (toktx: string, png: string, ktx2: string): Promise<void> => new Promise((resolve, reject) => {
-  const args = [ "--t2", "--encode", "uastc", "--uastc_quality", "2", "--zcmp", "18", "--genmipmap", "--assign_oetf", "srgb", ktx2, png ]
-  const p = spawn(toktx, args, { stdio: [ "ignore", "pipe", "pipe" ] })
-  let out = ""
-  p.stdout.on("data", (d) => { out += String(d) })
-  p.stderr.on("data", (d) => { out += String(d) })
-  p.on("error", (e) => reject(new CliError(`toktx failed (${e.message}) while encoding ${ktx2}`)))
-  p.on("close", (status) => {
-    if (status === 0) resolve()
-    else reject(new CliError(`toktx failed (${status ?? "?"}) while encoding ${ktx2}:\n${out.trim()}`))
-  })
-})
+/** A .bake with no pages and no scale: enough for the compiler to stage the files and for Lightmap.load to
+ *  no-op with a "rebake" warning. The two KTX2 placeholders are 4x4 pages of the right formats. */
+const placeholderBake = (stem: string): string => JSON.stringify({ version: 4, placeholder: true, size: 4, pages: 0, texel: 0, lightScale: 0, light: [ `${stem}-light.ktx2` ], aux: [ `${stem}-aux.ktx2` ], instances: [] }) + "\n"
+const ktx2Placeholder = (vkFormat: number): Buffer => {
+  // one 4x4 level, no supercompression; BC6H (143) = one 16-byte block of zeros, RGBA8 (37) = 64 bytes
+  const raw = Buffer.alloc(vkFormat === 143 ? 16 : 64)
+  const dfdSize = 44
+  const dfdOffset = 80 + 24
+  const b = Buffer.alloc(dfdOffset + dfdSize + raw.length)
+  Buffer.from([ 0xAB, 0x4B, 0x54, 0x58, 0x20, 0x32, 0x30, 0xBB, 0x0D, 0x0A, 0x1A, 0x0A ]).copy(b, 0)
+  let o = 12
+  for (const v of [ vkFormat, 1, 4, 4, 0, 0, 1, 1, 0 ]) { b.writeUInt32LE(v, o); o += 4 }
+  b.writeUInt32LE(dfdOffset, o); b.writeUInt32LE(dfdSize, o + 4); o += 8
+  b.writeUInt32LE(0, o); b.writeUInt32LE(0, o + 4); o += 8
+  b.writeBigUInt64LE(0n, o); b.writeBigUInt64LE(0n, o + 8); o += 16
+  b.writeBigUInt64LE(BigInt(dfdOffset + dfdSize), o); b.writeBigUInt64LE(BigInt(raw.length), o + 8); b.writeBigUInt64LE(BigInt(raw.length), o + 16); o += 24
+  b.writeUInt32LE(dfdSize, o)
+  raw.copy(b, dfdOffset + dfdSize)
+  return b
+}
+const ensurePlaceholders = (outDir: string, stem: string): void => {
+  const missing = (f: string): boolean => !existsSync(f) || statSync(f).size === 0
+  const bake = join(outDir, `${stem}.bake`)
+  if (missing(bake)) writeFileSync(bake, placeholderBake(stem))
+  const light = join(outDir, `${stem}-light.ktx2`), aux = join(outDir, `${stem}-aux.ktx2`), probes = join(outDir, `${stem}-probes.ktx2`)
+  if (missing(light)) writeFileSync(light, ktx2Placeholder(143))
+  if (missing(aux)) writeFileSync(aux, ktx2Placeholder(37))
+  if (missing(probes)) writeFileSync(probes, ktx2Placeholder(143))   // a scene may list the probes before the first bake wrote them
+  const grid = join(outDir, `${stem}.lgrid`)
+  if (missing(grid)) writeFileSync(grid, "NONE")   // ... and the light grid: the engine refuses it with a "rebake" line
+}
 
-/** The bake's file names for `stem`: page 0 is `<stem>.ktx2`, page n `<stem>_n.ktx2`; the light atlas adds `-light`. */
-const pageFile = (stem: string, page: number, light: boolean, ext = ".ktx2"): string =>
-  `${stem}${light ? "-light" : ""}${page > 0 ? `_${page}` : ""}${ext}`
+const bake = defineCommand({
+  name: "bake",
+  summary: "Bake the sun, the sky and the lamps into a lux atlas for the level's statics",
+  description: "Runs the app in the desktop host in bake mode: the statics are what the app registers with Lightmap.add (a scene file does it for every node no Physics aspect moves), the bake fires at its Lightmap.load call. Writes <out>/<name>.bake + <name>-light[_n].ktx2 (irradiance, BC6H) + <name>-aux[_n].ktx2 (sky visibility, the directional share and direction of the light) + <name>-probes.ktx2 (the reflection probes: a cubemap of the level's radiance per probe, prefiltered per roughness; --probe-spacing 0 = none). Needs a desktop host built with the CUDA toolkit and an NVIDIA card (LECODES_DESKTOP_EXE for a local build).\n\nProps need lightmap UVs first: lecodes assets doctor assets/props/*.glb --lightmap-uv",
+  flags: {
+    out: str("where the atlas lands", { value: "<dir>", default: "assets/lightmap" }),
+    name: str("file stem — one per baked level", { value: "<stem>", default: "lightmap" }),
+    ...bundleFlags,
+    entry: str("the file that builds the scene and calls Lightmap.load", { value: "<file>", default: "main.ts" }),
+    size: num("atlas page edge (texels)", { default: 4096 }),
+    texel: num("texel size (m); the bake coarsens only when the pages are full", { default: 0.05 }),
+    pages: num("atlas pages to fill before the bake coarsens the texel", { default: 4 }),
+    "sun-rays": num("shadow rays into the sun's disc per texel", { default: 64 }),
+    "sky-rays": num("hemisphere rays per texel (the sky's irradiance and visibility). 2048 (2026-09-16): shadow rays are cheap (the school's direct pass 2 s a page) and a texel deep in a corridor sees the sky through a far window with 1 ray in 256 — every hit was 410 lux", { default: 2048 }),
+    "light-rays": num("shadow rays per lamp per texel (64: at 32 the school's lamp layer read 43 % noise between two seeds, the ceilings and doors next to a lamp 48 %)", { default: 64 }),
+    "bounce-rays": num("bounce paths per texel; 0 = direct light only. 128 (2026-09-16): a dark room's floor in the school reads 240 % noise at 64, 160 % at 128, 130 % at 256 — the last doubling costs 2x the bake time for little", { default: 128 }),
+    bounces: num("path vertices at most (Russian roulette from the third); 0 = direct light only", { default: 3 }),
+    "patch-samples": num("next-event samples per texel over the BRIGHT PATCHES of a first direct pass (sunlit floors, the ceiling around a lamp) — what keeps the bounce in dark rooms from arriving as impulses (every path vertex takes one more); 0 = the cosine paths alone", { default: 64 }),
+    split: bool("also write <name>-direct[_n].ktx2 / <name>-indirect[_n].ktx2 — the pages the \"direct\" / \"indirect\" views bind (list them as env.lightmap.direct / .indirect)"),
+    denoise: str("OptiX's AI denoiser over: indirect = the bounce alone (the range 2026-09-16: bounce noise 57 % -> 23 % of the mean, per-instance means unchanged), no-sun = + the sky and the lamps (the sky through a small opening: 0..3 hits of 256 rays, a texel is one of four values), all = + the sun (its shadow edges too: a sunlit pillar's mean moved 6 %), none. School, two seeds: no-sun took the sky 1.8 % -> 0.5 %, the lamps 43 % -> 21 %", { value: "<none|indirect|no-sun|all>", default: "no-sun" }),
+    "light-radius": num("lamps: the emitter's radius (m) — soft shadows, no 1/d² singularity", { default: 0.05 }),
+    "sun-angle": num("sun angular diameter (deg)", { default: 0.53 }),
+    bias: num("ray start offset from the surface (m)", { default: 0.01 }),
+    filter: num("the texel's reconstruction filter radius, in texels: every ray starts at a tent-distributed point of the texel's footprint, so a shadow's edge is a ramp of this width instead of a step at the texel grid (1 = ±1 texel, the classic; 0.5 = within the texel; 0 = the centre alone)", { default: 1 }),
+    seed: num("the RNG seed: two bakes that differ only here differ by their noise (`lightmap diff`)", { default: 1 }),
+    "probe-spacing": num("reflection probes: the grid spacing in metres over the receivers (one probe per cell a static touches, minus the points inside geometry; every static reflects the nearest it can see); 0 = no probes", { default: 4 }),
+    "probe-size": num("a probe cubemap face's edge in texels (a power of two, 16..128)", { default: 32 }),
+    "probe-rays": num("paths per probe texel; the first hit of each takes four times the direct-light samples (the picture), so noise on a mirror is the one thing this buys", { default: 128 }),
+    "probe-indoor": bool("keep only the probes under a roof — those whose open share of the sphere (rays from the point that meet nothing) is at most 15 %, holes in the geometry or not: outdoor statics reflect the sky through their baked sky visibility instead — an environment map without the ground, but no outdoor probe can reach indoors and the atlas shrinks"),
+    "probe-layout": str("rooms = every indoor point of the grid slides to the middle of its room and the points of one room merge: one probe per room, far from the walls, its box the room (stations every ~8 m along a room over 12 m), outdoor points stay on the grid; grid = everything stays on the grid. Either way the pages carry which probes each block of texels sees (rays at bake time)", { value: "<rooms|grid>", default: "rooms" }),
+    "min-texels": num("instances smaller than this many ATLAS TEXELS along every axis (x --texel: 12 at 5 cm = 0.6 m) get no place in the atlas: they still cast their baked shadow and bounce, their own light is baked where they stand (six sides, no atlas texels) — cartridges, boxes, pipe elbows, a fire extinguisher: a baked shadow does not read on them and their tight charts are where the seams are. 0 = everything bakes; --dry-run lists what falls under it", { default: 12 }),
+    "emissive-nits": num("EMISSIVE SURFACES LIGHT THE LEVEL: cd/m² of emission 1.0 (emissive factor x strength x map) — every lit region of an emissive surface (a panel drawn in a ceiling's texture, a screen, a sign) bakes as a rectangle lamp. Default: what the level's camera makes of 1.0, 1.2 x 2^EV100, so a panel lights as brightly as it looks. 0 = emissive surfaces light nothing"),
+    "detail-texels": num("A SMALL SURFACE GETS A FINER TEXEL: an instance whose surface is under this many atlas texels (area / texel²) is laid out denser by sqrt(this / its texels), 3x at most — a pipe of 1 m is ~300 texels at 5 cm, its charts a few texels wide and every chart edge a step; at 2000 it bakes at ~2 cm. 0 = off", { default: 2000 }),
+    volume: num("THE LIGHT GRID for movers: the cell size in metres (0.75 of it tall) — per cell in free space the baked ambient light (sky, lamps, every bounce; not the direct sun, which stays real-time on movers), links between cells a ray connects so nothing blends through a wall; written as <name>.lgrid, list it as env.lightmap.volume. 0 = none", { default: 1 }),
+    "probe-box": str("only grid cells whose centre lies inside this world box get a probe: x0,y0,z0,x1,y1,z1 in metres — keeps probes off a roof top the player never sees (the range: 79 probes above a ceiling with holes where the fixtures were bled the sky onto the walls). Default: the receivers' bounds", { value: "<x0,y0,z0,x1,y1,z1>" }),
+    "debug-dir": str("keep the float layers per page (PFM) here for `lightmap inspect` — gigabytes per level; a `.lightmap/` dir inside the project is skipped by the compile scan, anywhere else must be outside the project", { value: "<dir>" }),
+    "dry-run": bool("only the atlas LAYOUT: pages, texel size, the largest rects — no tracing, nothing written (seconds, not minutes; the host still loads the level)"),
+    frames: num("host frames to run before giving up — load headroom", { default: 900 }),
+    timeout: num("host time cap (ms; default: none)"),
+    width: num("host window width (default: app.json desktop.window, else 1280)"),
+    height: num("host window height (default: app.json desktop.window, else 720)"),
+    renderer: str("desktop host + shader variant (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
+    logs: bool("forward the host's output"),
+  },
+  examples: [ "lecodes lightmap bake", "lecodes lightmap bake --entry school.ts --name school --texel 0.04 --pages 4 --debug-dir .lightmap/school --logs" ],
+  run: async ({ flags }) => {
+    const { root } = localProject()
+    const outDir = resolve(root, flags.out)
+    const stem = flags.name
+    if (!/^[A-Za-z0-9_-]+$/.test(stem)) throw new CliError(`--name wants a plain file stem (letters, digits, - and _), got "${stem}".`)
+    const entryFile = flags.entry
+    if (!existsSync(resolve(root, entryFile))) {
+      throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the scene and calls Lightmap.load).`)
+    }
+    const debugDir = flags["debug-dir"] ? resolve(root, flags["debug-dir"]) : ""
+    const cfg = {
+      outDir: outDir.replace(/\\/g, "/"),
+      stem,
+      size: range("size", flags.size, 256, 16384),
+      texel: range("texel", flags.texel, 0.001, 2),
+      pages: range("pages", flags.pages, 1, 16),
+      sunRays: range("sun-rays", flags["sun-rays"], 1, 4096),
+      skyRays: range("sky-rays", flags["sky-rays"], 1, 16384),
+      lightRays: range("light-rays", flags["light-rays"], 1, 1024),
+      lightRadius: range("light-radius", flags["light-radius"], 0.001, 5),
+      sunAngle: range("sun-angle", flags["sun-angle"], 0.01, 30),
+      bias: range("bias", flags.bias, 0.0001, 1),
+      seed: Math.max(0, Math.floor(flags.seed)),
+      bounceRays: range("bounce-rays", flags["bounce-rays"], 0, 16384),
+      bounces: range("bounces", flags.bounces, 0, 64),
+      patchSamples: range("patch-samples", flags["patch-samples"], 0, 1024),
+      split: !!flags.split,
+      denoise: flags.denoise,
+      filter: range("filter", flags.filter, 0, 4),
+      probeSpacing: range("probe-spacing", flags["probe-spacing"], 0, 100),
+      probeSize: range("probe-size", flags["probe-size"], 16, 128),
+      probeRays: range("probe-rays", flags["probe-rays"], 1, 4096),
+      probeIndoor: !!flags["probe-indoor"],
+      probeLayout: probeLayoutOf(flags["probe-layout"]),
+      minTexels: range("min-texels", flags["min-texels"], 0, 10000),
+      volumeSpacing: range("volume", flags.volume, 0, 100),
+      detailTexels: range("detail-texels", flags["detail-texels"], 0, 1e7),
+      ...(flags["emissive-nits"] !== undefined ? { emissiveNits: range("emissive-nits", flags["emissive-nits"], 0, 1e7) } : {}),
+      probeBox: flags["probe-box"] ? probeBoxOf(flags["probe-box"]) : undefined,
+      debugDir: debugDir.replace(/\\/g, "/"),
+    }
+    const frames = range("frames", flags.frames, 30, 100000)
+    const win = readAppConfigAt(root)?.desktop?.window
+    const width = flags.width || win?.width || 1280
+    const height = flags.height || win?.height || 720
 
-const bake = async (args: Args): Promise<void> => {
-  let root: string
-  try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() }
-  const toktx = requireToktx()
-  const outDir = resolve(root, flagStr(args, "out") ?? "assets/lightmap")
-  const stem = flagStr(args, "name") ?? "lightmap"
-  if (!/^[A-Za-z0-9_-]+$/.test(stem)) throw new CliError(`--name wants a plain file stem (letters, digits, - and _), got "${stem}".`)
-  const entryFlag = flagStr(args, "entry")
-  const entryFile = entryFlag ?? "main.ts"
-  if (!existsSync(resolve(root, entryFile))) {
-    throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the scene and calls Lightmap.load).`)
-  }
-  const cfg = {
-    outDir: outDir.replace(/\\/g, "/"),
-    size: num(args, "size", 4096, 256, 16384),
-    texel: num(args, "texel", 0.02, 0.001, 2),
-    // atlas PAGES: the bake fills up to this many atlases of --size at the requested texel before it
-    // coarsens; every page is one more texture the scene lists under env.lightmap.texture
-    pages: num(args, "pages", 4, 1, 16),
-    sunRays: num(args, "sun-rays", 32, 1, 1024),
-    aoRays: num(args, "ao-rays", 64, 1, 4096),
-    aoDistance: num(args, "ao-distance", 2, 0.01, 1000),
-    bias: num(args, "bias", 0.02, 0.0001, 1),
-    sunAngle: num(args, "sun-angle", 0.5, 0.01, 30),
-    // point lights: shadow rays per light per texel, toward a disc of this radius at the light
-    lightRays: num(args, "light-rays", 16, 1, 256),
-    lightRadius: num(args, "light-radius", 0.1, 0.001, 5),
-    // One bounce of indirect from the lamps, gathered on the AO rays (the albedo it assumes for
-    // every surface it hits). Off by default: it is the difference between "a room lit by its
-    // lamps" and "lit fixtures in a black room", but it costs a full Intersect per AO ray.
-    bounce: num(args, "bounce", 0, 0, 1),
-    bounceDistance: num(args, "bounce-distance", 8, 0.5, 100),
-    bounceRays: num(args, "bounce-rays", 1, 1, 32),
-    coplanarSkip: num(args, "coplanar-skip", 0.05, 0, 1),
-    // geometry-aware denoise of the traced texels (radius in px; 0 = off)
-    denoise: num(args, "denoise", 2, 0, 4),
-    // the light volume for dynamic objects (docs/lightmap-plan.md §9); 0 = skip it
-    volumeCell: flagBool(args, "no-volume") ? 0 : num(args, "cell", 0.5, 0.05, 20),
-  }
-  const frames = num(args, "frames", 900, 30, 100000)
-  const win = readAppConfigAt(root)?.desktop?.window
-  const width = Number(flagStr(args, "width")) || win?.width || 1280
-  const height = Number(flagStr(args, "height")) || win?.height || 720
-  const logs = flagBool(args, "logs")
+    // The synthetic entry: bake mode flag first, then the real entry. It lives at the project root so
+    // the real entry's own relative imports resolve unchanged.
+    const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "")
+    const entryPath = "/.lightmap-entry.ts"
+    const entryText = `globalThis.__lecodesLightmap = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
 
-  // The synthetic entry: bake mode flag first, then the real entry. It lives at the project root so
-  // the real entry's own relative imports resolve unchanged.
-  const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "")
-  const entryPath = "/.lightmap-entry.ts"
-  const entryText = `globalThis.__lecodesLightmap = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
+    // The bake files must exist BEFORE the compile: the scene references them through asset(), and a
+    // missing asset is a broken bundle. The first bake starts from placeholders the real files overwrite.
+    mkdirSync(outDir, { recursive: true })
+    ensurePlaceholders(outDir, stem)
+    if (debugDir) mkdirSync(debugDir, { recursive: true })
 
-  // The bake files must exist BEFORE the compile: the scene references them through asset(), and
-  // a missing asset is a broken bundle (chisel emits the constant after its use — a TDZ crash at
-  // boot, seen 2026-08-26). The first bake starts from placeholders the real files overwrite;
-  // Lightmap.load on a placeholder applies nothing and says "rebake".
-  mkdirSync(outDir, { recursive: true })
-  ensurePlaceholders(outDir, stem)
+    const desktopRenderer = resolveDesktopRenderer(root, flags.renderer)
+    const { js, resources } = await buildBundle(bundleOptions(flags), {
+      localAssets: true, desktopRenderer,
+      extraEntries: [{ path: entryPath, type: "text", text: entryText }],
+      entryOverride: entryPath,
+    })
 
-  const desktopRenderer = resolveDesktopRenderer(root, args)
-  const { js, resources } = await buildBundle(args, undefined, {
-    localAssets: true, desktopRenderer,
-    extraEntries: [{ path: entryPath, type: "text", text: entryText }],
-    entryOverride: entryPath,
-  })
+    // The host writes the bake itself; the PNG the render driver insists on goes to a scratch dir.
+    const scratch = mkdtempSync(join(tmpdir(), "lecodes-lightmap-"))
+    const outPng = join(scratch, "frame.png")
+    const bounce = cfg.bounceRays > 0 && cfg.bounces > 0 ? `, ${cfg.bounceRays} bounce paths of ${cfg.bounces}${cfg.patchSamples > 0 ? ` + ${cfg.patchSamples} patch samples` : ""}${cfg.denoise !== "none" ? `, denoised (${cfg.denoise})` : ", raw"}` : ", no bounce"
+    note(`Baking up to ${cfg.pages} × ${cfg.size}² at ${(cfg.texel * 100).toFixed(1)} cm texels (${cfg.sunRays} sun + ${cfg.skyRays} sky + ${cfg.lightRays} lamp rays${bounce}) → ${relative(root, outDir) || "."}/${stem}.*…`)
+    let output = ""
+    if (flags["dry-run"]) process.env.CBK_LAYOUT_ONLY = "1"   // the host inherits it: creator-bake stops after the layout
+    try {
+      const timeoutMs = flags.timeout || 24 * 3600 * 1000
+      const res = await runDesktopRender(js, resources, {
+        renderer: desktopRenderer, width, height, frames, outPng, logs: flags.logs, timeoutMs,
+        stopOnLine: (chunk) => chunk.includes("[lightmap] done") || chunk.includes("[lightmap] error"),
+      })
+      output = res.output
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      if (!/\[lightmap\] done/.test(msg)) throw e
+      output = msg
+    } finally {
+      try { rmSync(scratch, { recursive: true, force: true }) } catch { /* a killed host may hold the dir a moment longer */ }
+    }
 
-  // The host writes the bake itself; the PNG the render driver insists on goes to a scratch dir.
-  const scratch = mkdtempSync(join(tmpdir(), "lecodes-lightmap-"))
-  const outPng = join(scratch, "frame.png")
-  note(`Baking up to ${cfg.pages} × ${cfg.size}² at ${(cfg.texel * 100).toFixed(1)} cm texels (${cfg.sunRays} sun + ${cfg.aoRays} AO + ${cfg.lightRays} light rays)${cfg.volumeCell ? ` + a ${cfg.volumeCell} m light volume` : ""} → ${relative(root, outDir) || "."}/${stem}.*…`)
-  let output = ""
-  try {
-    // A bake is not interactive and a large level traces for a long time: no timeout unless asked
-    // (the host prints its progress once a second — a silent host is the thing to watch, not the clock).
-    const timeoutMs = Number(flagStr(args, "timeout")) || 24 * 3600 * 1000
-    const res = await runDesktopRender(js, resources, {
-      renderer: desktopRenderer, width, height, frames, outPng, logs, timeoutMs,
-      // the bake is synchronous inside Lightmap.load — once the marker is out there is nothing to wait for
-      stopOnLine: (chunk) => chunk.includes("[lightmap] done") || chunk.includes("[lightmap] error"),
-      // no script: the frame cap ends the run once Lightmap.load has fired (the bake is synchronous)
-    })
-    output = res.output
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e)
-    // A run that baked and then hit the cap without a PNG is still a success — check the markers.
-    if (!/\[lightmap\] done/.test(msg)) throw e
-    output = msg
-  } finally {
-    try { rmSync(scratch, { recursive: true, force: true }) } catch { /* a killed host may hold the dir a moment longer */ }
-  }
+    const lines = output.split(/\r?\n/).filter((l) => l.startsWith("[lightmap]"))
+    for (const l of lines) {
+      const text = l.slice("[lightmap]".length).trim()
+      if (text === "done") continue
+      logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : text.startsWith("warning") ? c.yellow(`  ${text}`) : c.dim(`  ${text}`))
+    }
+    if (flags["dry-run"] && /\[lightmap\] done/.test(output)) {
+      for (const l of lines) if (/atlas \d+ x|larger rect|largest rect|do not fit|charts touch/.test(l)) logErr(l.replace(/^\[lightmap\] /, "  "))
+      logErr(c.green("✓ layout only — nothing written"))
+      return
+    }
+    if (/\[lightmap\] done/.test(output)) {
+      const data = readBake(join(outDir, `${stem}.bake`))
+      const rel = (f: string): string => relative(root, join(outDir, f)).replace(/\\/g, "/")
+      const assets = (files: string[]): string => files.length === 1 ? `asset('<rel>/${rel(files[0])}')` : `[${files.map((f) => `asset('<rel>/${rel(f)}')`).join(", ")}]`
+      const splitFiles = data.direct && data.indirect ? ` + ${data.direct.join(", ")} + ${data.indirect.join(", ")}` : ""
+      const splitDef = data.direct && data.indirect ? `, direct: ${assets(data.direct)}, indirect: ${assets(data.indirect)}` : ""
+      const probeFiles = data.probes ? ` + ${data.probes.file} (${data.probes.count} probe(s) of ${data.probes.size}² at ${data.probes.spacing} m)` : ""
+      const gridFile = data.volume ? ` + ${data.volume.file} (light grid ${data.volume.n.join(" x ")}, ${data.volume.valid} cell(s) in free space)` : ""
+      const probeDef = (data.probes ? `, probes: asset('<rel>/${rel(data.probes.file)}')` : "") + (data.volume ? `, volume: asset('<rel>/${rel(data.volume.file)}')` : "")
+      logErr(c.green(`✓ baked → ${relative(root, outDir) || "."}/${stem}.bake + ${data.light.join(", ")} + ${data.aux.join(", ")}${splitFiles}${probeFiles}${gridFile}`))
+      logErr(c.dim(`  scene file: env.lightmap: { data: asset('<rel>/${rel(`${stem}.bake`)}'), light: ${assets(data.light)}, aux: ${assets(data.aux)}${splitDef}${probeDef} }  — asset() paths are relative to the scene file`))
+      if (debugDir) logErr(c.dim(`  debug layers: ${relative(root, debugDir)} (lecodes lightmap inspect --bake ${relative(root, join(outDir, `${stem}.bake`)).replace(/\\/g, "/")} --debug-dir ${relative(root, debugDir).replace(/\\/g, "/")})`))
+      return
+    }
+    if (lines.some((l) => /no bake module/.test(l))) {
+      throw new CliError("This desktop host has no bake module. Build hosts/desktop with the CUDA toolkit installed and point LECODES_DESKTOP_EXE at build/lecodes-desktop.exe.")
+    }
+    if (lines.some((l) => /error/.test(l))) throw new CliError("The bake failed — see the lines above.")
+    warnErr("The host ran to its frame cap without baking. Make sure the app calls Lightmap.load(...) after the static scene is built, and skips menus when Lightmap.baking is true. More load headroom: --frames <n>. Host output: --logs.")
+    throw new CliError("Nothing was baked.")
+  },
+})
 
-  const lines = output.split(/\r?\n/).filter((l) => l.startsWith("[lightmap]"))
-  for (const l of lines) {
-    const text = l.slice("[lightmap]".length).trim()
-    if (text === "done") continue
-    logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : text.startsWith("warning") ? c.yellow(`  ${text}`) : c.dim(`  ${text}`))
-  }
-  if (/\[lightmap\] done/.test(output)) {
-    // the host writes `lightmap.*`; the stem is the CLI's, applied while the PNGs turn into KTX2
-    const bakePath = join(outDir, "lightmap.bake")
-    if (!existsSync(bakePath)) throw new CliError(`The host reported a bake but ${bakePath} is missing.`)
-    const data = JSON.parse(readFileSync(bakePath, "utf8")) as { pages?: number, textures?: string[], lightTextures?: string[], volume?: { file: string }, texture?: string }
-    const pages = Math.max(1, data.pages ?? 1)
-    const hasLight = !!data.lightTextures?.length
-    const t0 = Date.now()
-    let pngKb = 0, ktxKb = 0
-    const encodePage = async (page: number, light: boolean): Promise<void> => {
-      const png = join(outDir, pageFile("lightmap", page, light, ".png"))
-      const ktx2 = join(outDir, pageFile(stem, page, light))
-      if (!existsSync(png)) throw new CliError(`The host reported a bake but ${png} is missing.`)
-      await encodeKtx2(toktx, png, ktx2)
-      pngKb += statSync(png).size / 1024; ktxKb += statSync(ktx2).size / 1024
-      unlinkSync(png)
+// ---- stats ----------------------------------------------------------------------------------------
+
+const lum = (rgb: number[] | undefined): number => rgb ? 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2] : 0
+
+const stats = defineCommand({
+  name: "stats",
+  summary: "The per-instance numbers a .bake carries: mean lux, sun / sky visibility, texels, rect",
+  description: "Reads the .bake alone (no debug layers needed). One row per receiver, sorted by mean lux unless --sort says otherwise; --key filters by a regular expression over the keys.",
+  flags: {
+    bake: str("the .bake file", { value: "<file>", default: "assets/lightmap/lightmap.bake" }),
+    key: str("only instances whose key matches this regular expression", { value: "<regex>" }),
+    sort: str("row order", { value: "<lux|key|texels|sun|sky>", default: "lux" }),
+    limit: num("rows to print (0 = all)", { default: 60 }),
+  },
+  examples: [ "lecodes lightmap stats --bake assets/school/lightmap/school.bake --key Wall", "lecodes lightmap stats --sort sky --limit 0" ],
+  run: ({ flags }) => {
+    const { root } = localProject()
+    const data = readBake(resolve(root, flags.bake))
+    const re = flags.key ? new RegExp(flags.key) : null
+    let rows = data.instances.filter((i) => i.receiver && (!re || re.test(i.key)))
+    const sorters: Record<string, (a: BakeInstance, b: BakeInstance) => number> = {
+      lux: (a, b) => lum(b.mean) - lum(a.mean),
+      key: (a, b) => a.key.localeCompare(b.key),
+      texels: (a, b) => (b.texels ?? 0) - (a.texels ?? 0),
+      sun: (a, b) => (b.sunVis ?? 0) - (a.sunVis ?? 0),
+      sky: (a, b) => (b.skyVis ?? 0) - (a.skyVis ?? 0),
     }
-    const encodes: Promise<void>[] = []
-    for (let p = 0; p < pages; p++) {
-      encodes.push(encodePage(p, false))
-      if (hasLight) encodes.push(encodePage(p, true))
+    const sorter = sorters[flags.sort]
+    if (!sorter) throw new CliError(`--sort: expected lux, key, texels, sun or sky, got ${JSON.stringify(flags.sort)}`)
+    rows = rows.sort(sorter)
+    const total = rows.length
+    if (flags.limit > 0) rows = rows.slice(0, flags.limit)
+    log(`${basename(flags.bake)}: ${data.pages} page(s) of ${data.size}, ${(data.texel * 100).toFixed(2)} cm texels, ${data.texels ?? "?"} texels, lightScale ${data.lightScale}`)
+    log(`${"key".padEnd(48)} ${"page".padStart(4)} ${"rect".padStart(20)} ${"texels".padStart(8)} ${"lux".padStart(9)} ${"sun".padStart(6)} ${"sky".padStart(6)} ${"dir".padStart(6)}`)
+    for (const r of rows) {
+      const rect = r.rect ? `${r.rect[0]},${r.rect[1]} ${r.rect[2]}x${r.rect[3]}` : ""
+      log(`${r.key.slice(0, 48).padEnd(48)} ${String(r.page ?? "").padStart(4)} ${rect.padStart(20)} ${String(r.texels ?? "").padStart(8)} ${lum(r.mean).toFixed(1).padStart(9)} ${(r.sunVis ?? 0).toFixed(3).padStart(6)} ${(r.skyVis ?? 0).toFixed(3).padStart(6)} ${(r.share ?? 0).toFixed(3).padStart(6)}`)
     }
-    await Promise.all(encodes)
-    // a page the previous bake had and this one does not: keep the file a scene may still list, as a placeholder
-    for (let p = pages; p < 16; p++) {
-      for (const light of [ false, true ]) {
-        const stale = join(outDir, pageFile(stem, p, light))
-        if (existsSync(stale) && statSync(stale).size !== PLACEHOLDER_KTX2.length) writeFileSync(stale, PLACEHOLDER_KTX2)
+    if (total > rows.length) log(`… ${total - rows.length} more (--limit 0 for all)`)
+  },
+})
+
+// ---- diff -----------------------------------------------------------------------------------------
+// Two bakes that differ only by --seed are two independent samples of the same estimate: per texel the
+// difference of the two, over root two, is the noise of ONE bake. Summed per instance and put over the mean
+// it is the number "is this speckle or a feature" — instead of an eye on a screenshot.
+
+const diff = defineCommand({
+  name: "diff",
+  summary: "The noise of a bake, per instance: two bakes that differ only by --seed, compared texel by texel",
+  description: "Bake the level twice with different --seed (and --out / --debug-dir, so the second does not overwrite the first — a `.lightmap/` dir inside the project is skipped by the compile scan). Both must share the layout (same instances, rects and pages — a seed changes nothing else). Per instance: the mean of the layer, the noise as the RMS of (a − b) / √2 over the mean, in %, and the share of texels that differ by more than half their mean. Sorted by noise unless --sort says otherwise.",
+  flags: {
+    bake: str("the first .bake", { value: "<file>", default: "assets/lightmap/lightmap.bake" }),
+    "debug-dir": str("where the first bake kept its PFM layers", { value: "<dir>", default: ".lightmap" }),
+    bake2: str("the second .bake (another --seed)", { value: "<file>" }),
+    "debug-dir2": str("where the second bake kept its PFM layers", { value: "<dir>" }),
+    layer: str("which layer to compare", { value: "<irradiance|bounce|sun|sky|lamps>", default: "irradiance" }),
+    key: str("only instances whose key matches this regular expression", { value: "<regex>" }),
+    sort: str("row order", { value: "<noise|lux|key|texels>", default: "noise" }),
+    "min-lux": num("instances whose mean is under this are 'dark': no noise figure, sorted last (a relative noise over nothing is not a number)", { default: 1 }),
+    limit: num("rows to print (0 = all)", { default: 40 }),
+  },
+  examples: [
+    "lecodes lightmap bake --entry range.ts --name range --seed 2 --out .lightmap/range-seed2/bake --debug-dir .lightmap/range-seed2 --logs",
+    "lecodes lightmap diff --bake assets/range/lightmap/range.bake --debug-dir .lightmap/range --bake2 .lightmap/range-seed2/bake/range.bake --debug-dir2 .lightmap/range-seed2 --layer bounce",
+  ],
+  run: ({ flags }) => {
+    const { root } = localProject()
+    if (!flags.bake2 || !flags["debug-dir2"]) throw new CliError("--bake2 and --debug-dir2 name the second bake (another --seed).")
+    const a = readBake(resolve(root, flags.bake)), b = readBake(resolve(root, flags.bake2))
+    if (a.size !== b.size || a.pages !== b.pages) throw new CliError(`The bakes differ in layout (${a.pages} × ${a.size} vs ${b.pages} × ${b.size}) — a diff needs the same scene baked twice with another --seed.`)
+    const ra = a.instances.filter((i) => i.receiver), rb = b.instances.filter((i) => i.receiver)
+    if (ra.length !== rb.length || ra.some((i, k) => i.key !== rb[k].key || i.page !== rb[k].page || String(i.rect) !== String(rb[k].rect))) {
+      throw new CliError("The bakes list different instances or rects — a diff needs the same scene baked twice with another --seed.")
+    }
+    const stemA = basename(flags.bake, ".bake"), stemB = basename(flags.bake2, ".bake")
+    const dirA = resolve(root, flags["debug-dir"]), dirB = resolve(root, flags["debug-dir2"])
+    const layer = flags.layer
+    if (![ "irradiance", "bounce", "sun", "sky", "lamps" ].includes(layer)) throw new CliError(`--layer: expected irradiance, bounce, sun, sky or lamps, got ${JSON.stringify(layer)}`)
+    // per instance index: texels, sum of the mean, sum of the squared half-difference, texels off by > 50 %
+    const n = a.instances.length
+    const texels = new Float64Array(n), sumMean = new Float64Array(n), sumVar = new Float64Array(n), off = new Float64Array(n)
+    const pageFile = (dir: string, stem: string, kind: string, page: number): string => join(dir, `${stem}-${kind}${page > 0 ? `_${page}` : ""}.pfm`)
+    for (let pg = 0; pg < a.pages; pg++) {
+      const fa = pageFile(dirA, stemA, layer, pg), fb = pageFile(dirB, stemB, layer, pg), fi = pageFile(dirA, stemA, "ids", pg), fn = pageFile(dirA, stemA, "normal", pg)
+      for (const f of [ fa, fb, fi, fn ]) if (!existsSync(f)) throw new CliError(`No ${relative(root, f)} — bake with --debug-dir to keep the layers.`)
+      const A = readPfm(fa), B = readPfm(fb), I = readPfm(fi), N = readPfm(fn)
+      if (A.w !== B.w || A.h !== B.h) throw new CliError(`Page ${pg}: the layers differ in size.`)
+      const count = A.w * A.h
+      for (let t = 0; t < count; t++) {
+        const nx = N.data[t * 3], ny = N.data[t * 3 + 1], nz = N.data[t * 3 + 2]
+        if (nx * nx + ny * ny + nz * nz < 0.25) continue   // not a texel of any rect
+        const inst = Math.round(I.data[t * 3])
+        if (inst < 0 || inst >= n) continue
+        const la = 0.2126 * A.data[t * 3] + 0.7152 * A.data[t * 3 + 1] + 0.0722 * A.data[t * 3 + 2]
+        const lb = 0.2126 * B.data[t * 3] + 0.7152 * B.data[t * 3 + 1] + 0.0722 * B.data[t * 3 + 2]
+        const m = 0.5 * (la + lb), d = la - lb
+        texels[inst]++
+        sumMean[inst] += m
+        sumVar[inst] += 0.5 * d * d
+        if (Math.abs(d) > 0.5 * m && m > 0) off[inst]++
       }
     }
-    if (!hasLight) {
-      // no point lights in the level: a light atlas the scene may still reference goes back to a placeholder
-      const light = join(outDir, pageFile(stem, 0, true))
-      if (existsSync(light) && statSync(light).size !== PLACEHOLDER_KTX2.length) writeFileSync(light, PLACEHOLDER_KTX2)
+    type Row = { key: string, texels: number, mean: number, noise: number, off: number }
+    const re = flags.key ? new RegExp(flags.key) : null
+    let rows: Row[] = []
+    let allTexels = 0, allMean = 0, allVar = 0
+    for (let i = 0; i < n; i++) {
+      if (texels[i] === 0) continue
+      allTexels += texels[i]; allMean += sumMean[i]; allVar += sumVar[i]
+      if (re && !re.test(a.instances[i].key)) continue
+      const mean = sumMean[i] / texels[i]
+      const dark = mean < flags["min-lux"]
+      rows.push({ key: a.instances[i].key, texels: texels[i], mean, noise: dark ? -1 : Math.sqrt(sumVar[i] / texels[i]) / mean, off: off[i] / texels[i] })
+    }
+    const sorters: Record<string, (x: Row, y: Row) => number> = {
+      noise: (x, y) => y.noise - x.noise,
+      lux: (x, y) => y.mean - x.mean,
+      key: (x, y) => x.key.localeCompare(y.key),
+      texels: (x, y) => y.texels - x.texels,
+    }
+    const sorter = sorters[flags.sort]
+    if (!sorter) throw new CliError(`--sort: expected noise, lux, key or texels, got ${JSON.stringify(flags.sort)}`)
+    rows = rows.sort(sorter)
+    const total = rows.length
+    if (flags.limit > 0) rows = rows.slice(0, flags.limit)
+    const overallMean = allTexels > 0 ? allMean / allTexels : 0
+    log(`${layer}: ${a.pages} page(s) of ${a.size}, ${allTexels} texels compared; mean ${overallMean.toFixed(1)} lux, noise ${overallMean > 0 ? (100 * Math.sqrt(allVar / allTexels) / overallMean).toFixed(1) : "0"} % of the mean over the whole atlas`)
+    log(`${"key".padEnd(48)} ${"texels".padStart(8)} ${"mean lux".padStart(9)} ${"noise".padStart(7)} ${"off>50%".padStart(8)}`)
+    for (const r of rows) {
+      log(`${r.key.slice(0, 48).padEnd(48)} ${String(r.texels).padStart(8)} ${r.mean.toFixed(1).padStart(9)} ${r.noise < 0 ? "dark".padStart(7) : (100 * r.noise).toFixed(0).padStart(6) + "%"} ${(100 * r.off).toFixed(0).padStart(7)}%`)
     }
-    // the .bake names the encoded files under the stem
-    data.texture = pageFile(stem, 0, false)
-    data.textures = Array.from({ length: pages }, (_, p) => pageFile(stem, p, false))
-    if (hasLight) data.lightTextures = Array.from({ length: pages }, (_, p) => pageFile(stem, p, true))
-    if (data.volume) data.volume.file = `${stem}.volume`
-    writeFileSync(join(outDir, `${stem}.bake`), JSON.stringify(data, null, 1) + "\n")
-    if (stem !== "lightmap") unlinkSync(bakePath)
-    const volumeSrc = join(outDir, "lightmap.volume")
-    const hasVolume = cfg.volumeCell > 0 && existsSync(volumeSrc)
-    if (hasVolume && stem !== "lightmap") { rmSync(join(outDir, `${stem}.volume`), { force: true }); renameSync(volumeSrc, join(outDir, `${stem}.volume`)) }
-    logErr(c.dim(`  encoded ${pages} page(s)${hasLight ? " + the light atlas" : ""} (UASTC + mips, ${Math.round(ktxKb)} KB from ${Math.round(pngKb)} KB of rasters) in ${((Date.now() - t0) / 1000).toFixed(1)} s`))
-    logErr(c.green(`✓ baked → ${relative(root, outDir) || "."}/${stem}.bake + ${data.textures.join(", ")}${hasLight ? ` + ${data.lightTextures!.join(", ")}` : ""}${hasVolume ? ` + ${stem}.volume` : ""}`))
-    const rel = (f: string): string => relative(root, join(outDir, f)).replace(/\\/g, "/")
-    const assets = (files: string[]): string => files.length === 1 ? `asset('<rel>/${rel(files[0])}')` : `[${files.map((f) => `asset('<rel>/${rel(f)}')`).join(", ")}]`
-    logErr(c.dim(`  scene file: env.lightmap: { data: asset('<rel>/${rel(`${stem}.bake`)}'), texture: ${assets(data.textures)}${hasLight ? `, light: ${assets(data.lightTextures!)}` : ""}${hasVolume ? `, volume: asset('<rel>/${rel(`${stem}.volume`)}')` : ""} }  — asset() paths are relative to the scene file`))
-    return
+    if (total > rows.length) log(`… ${total - rows.length} more (--limit 0 for all)`)
+  },
+})
+
+// ---- inspect --------------------------------------------------------------------------------------
+
+/** A Portable Float Map (what creator-bake writes): rows come bottom-up in the file, returned top-down here. */
+const readPfm = (file: string): { w: number, h: number, ch: number, data: Float32Array } => {
+  const buf = readFileSync(file)
+  let o = 0
+  const token = (): string => {
+    while (o < buf.length && /\s/.test(String.fromCharCode(buf[o]))) o++
+    const s = o
+    while (o < buf.length && !/\s/.test(String.fromCharCode(buf[o]))) o++
+    return buf.toString("latin1", s, o)
   }
-  if (lines.some((l) => /no bake module/.test(l))) {
-    throw new CliError("This desktop host has no bake module. Build packages/desktop (CREATOR_GL_LIGHTMAP is on there) and point LECODES_DESKTOP_EXE at build/lecodes-desktop.exe, or update: lecodes desktop update.")
+  const magic = token()
+  const ch = magic === "PF" ? 3 : magic === "Pf" ? 1 : 0
+  if (!ch) throw new CliError(`${file} is not a PFM file`)
+  const w = Number(token()), h = Number(token()), scale = Number(token())
+  o++   // the single whitespace after the scale
+  const little = scale < 0
+  const data = new Float32Array(w * h * ch)
+  for (let y = 0; y < h; y++) {
+    const rowAt = o + (h - 1 - y) * w * ch * 4
+    for (let i = 0; i < w * ch; i++) data[y * w * ch + i] = little ? buf.readFloatLE(rowAt + i * 4) : buf.readFloatBE(rowAt + i * 4)
   }
-  if (lines.some((l) => /error/.test(l))) throw new CliError("The bake failed — see the lines above.")
-  warnErr("The host ran to its frame cap without baking. Make sure the app calls Lightmap.load(...) after the static scene is built, and skips menus when Lightmap.baking is true (a title screen never reaches the scene). More load headroom: --frames <n>. Host output: --logs.")
-  throw new CliError("Nothing was baked.")
+  return { w, h, ch, data }
 }
 
-/** A 1x1 white UASTC KTX2 (the atlas' "no shadow, no occlusion" value; toktx v4.4.2, sRGB) + an empty
- *  bake — enough for the compiler to stage the files and for Lightmap.load to no-op with a "rebake"
- *  warning. */
-const PLACEHOLDER_KTX2 = Buffer.from(
-  "q0tUWCAyMLsNChoKAAAAAAEAAAABAAAAAAAAAAAAAAAAAAAAAQAAAAEAAAAAAAAAaAAAACwAAACUAAAAfAAAAAAAAAAAAAAAAAAAAAAAAAAQAQAAAAAAABAAAAAAAAAAEAAAAAAAAAAsAAAAAAAAAAIAKACmAQIAAwMAABAAAAAAAAAAAAB/AAAAAAAAAAAA/////xEAAABLVFhvcmllbnRhdGlvbgByAAAAACcAAABLVFh3cml0ZXIAdG9rdHggdjQuNC4yIC8gbGlia3R4IHY0LjQuMgAAMwAAAEtUWHdyaXRlclNjUGFyYW1zAC0tZW5jb2RlIHVhc3RjIC0tdWFzdGNfcXVhbGl0eSAwAAD3////H3zvAQAAAAAAAAAA",
-  "base64")
-
-/** A 1x1x1 white light volume ("LVOL" v1, one lit cell): Lightmap.load treats a single-cell volume as "nothing baked". */
-const placeholderVolume = (): Buffer => {
-  const b = Buffer.alloc(4 + 4 + 12 + 12 + 4 + 2)
-  b.write("LVOL", 0, "latin1")
-  b.writeUInt32LE(1, 4)
-  b.writeUInt32LE(1, 8); b.writeUInt32LE(1, 12); b.writeUInt32LE(1, 16)
-  b.writeFloatLE(0, 20); b.writeFloatLE(0, 24); b.writeFloatLE(0, 28)
-  b.writeFloatLE(1, 32)
-  b[36] = 255; b[37] = 255
-  return b
+/** A minimal PNG encoder (RGB8, one IDAT) — enough for the inspection images without a native canvas. */
+const writePng = (file: string, w: number, h: number, rgb: Uint8Array): void => {
+  const crcTable = new Uint32Array(256)
+  for (let n = 0; n < 256; n++) { let cc = n; for (let k = 0; k < 8; k++) cc = cc & 1 ? 0xEDB88320 ^ (cc >>> 1) : cc >>> 1; crcTable[n] = cc >>> 0 }
+  const crc = (b: Buffer): number => { let cc = 0xFFFFFFFF; for (const x of b) cc = crcTable[(cc ^ x) & 0xFF] ^ (cc >>> 8); return (cc ^ 0xFFFFFFFF) >>> 0 }
+  const chunk = (type: string, body: Buffer): Buffer => {
+    const len = Buffer.alloc(4); len.writeUInt32BE(body.length)
+    const tb = Buffer.concat([ Buffer.from(type, "latin1"), body ])
+    const cb = Buffer.alloc(4); cb.writeUInt32BE(crc(tb))
+    return Buffer.concat([ len, tb, cb ])
+  }
+  const raw = Buffer.alloc((w * 3 + 1) * h)
+  for (let y = 0; y < h; y++) { raw[y * (w * 3 + 1)] = 0; Buffer.from(rgb.buffer, rgb.byteOffset + y * w * 3, w * 3).copy(raw, y * (w * 3 + 1) + 1) }
+  const ihdr = Buffer.alloc(13)
+  ihdr.writeUInt32BE(w, 0); ihdr.writeUInt32BE(h, 4); ihdr[8] = 8; ihdr[9] = 2; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0
+  writeFileSync(file, Buffer.concat([ Buffer.from([ 0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A ]), chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw)), chunk("IEND", Buffer.alloc(0)) ]))
 }
 
-/** The files a scene may reference before the first bake exists: the .bake, page 0 of both atlases
- *  and the volume (later pages come from a bake that needed them). An EMPTY file counts as missing —
- *  a zero-byte KTX2 is what hand-made placeholders looked like, and the host cannot build a texture
- *  from it. */
-const ensurePlaceholders = (outDir: string, stem: string): void => {
-  const missing = (f: string): boolean => !existsSync(f) || statSync(f).size === 0
-  const bake = join(outDir, `${stem}.bake`)
-  const ktx2 = join(outDir, pageFile(stem, 0, false))
-  const light = join(outDir, pageFile(stem, 0, true))
-  const volume = join(outDir, `${stem}.volume`)
-  if (missing(bake)) writeFileSync(bake, JSON.stringify({ version: 2, placeholder: true, size: 1, texel: 0, pages: 1, instances: [] }) + "\n")
-  if (missing(ktx2)) writeFileSync(ktx2, PLACEHOLDER_KTX2)
-  if (missing(light)) writeFileSync(light, PLACEHOLDER_KTX2)
-  if (missing(volume)) writeFileSync(volume, placeholderVolume())
-}
+type Tone = "log" | "linear" | "raw" | "normal"
+const LAYERS = [ "irradiance", "sun", "sky", "lamps", "bounce", "bounce-raw", "visibility", "direction", "share", "normal", "position", "ids", "probes" ]
 
-export const lightmap = async (args: Args): Promise<void> => {
-  const sub = args._[0]
-  if (sub === "bake") return bake({ ...args, _: args._.slice(1) })
-  throw new CliError("Usage: lecodes lightmap bake [--out assets/lightmap] [--name lightmap] [--size 4096] [--pages 4] [--texel 0.02] [--sun-rays 32] [--ao-rays 64] [--ao-distance 2] [--bias 0.02] [--sun-angle 0.5] [--light-rays 16] [--light-radius 0.1] [--bounce 0..1] [--denoise 2] [--cell 0.5 | --no-volume] [--frames 900] [--timeout <ms>] [--entry main.ts] [--logs]   (needs KTX-Software's toktx)")
+/** float layer -> RGB8 display: `log` maps log10 lux over [lo, hi], `linear` divides by `white`,
+ *  `normal` shows a unit vector as x0.5+0.5, `raw` clamps 0..1 */
+const toneMap = (v: number, tone: Tone, lo: number, hi: number, white: number): number => {
+  let t: number
+  if (tone === "log") t = (Math.log10(Math.max(v, 1e-6)) - lo) / Math.max(hi - lo, 1e-6)
+  else if (tone === "linear") t = v / white
+  else if (tone === "normal") t = v * 0.5 + 0.5
+  else t = v
+  return Math.round(Math.min(1, Math.max(0, t)) * 255)
 }
+
+const inspect = defineCommand({
+  name: "inspect",
+  summary: "PNGs from a bake's debug layers: whole pages, or one instance's rect enlarged",
+  description: "Reads the PFM float layers `bake --debug-dir` kept next to the .bake's rects. Without --key: one PNG per page and layer with every rect outlined. With --key: the matching instances' rects (plus a margin) enlarged by --scale, one PNG per instance and layer. Lux layers are shown as log10 over --lux-range (or linear over --white); vectors as x0.5+0.5.",
+  flags: {
+    bake: str("the .bake file", { value: "<file>", default: "assets/lightmap/lightmap.bake" }),
+    "debug-dir": str("where the bake kept its PFM layers", { value: "<dir>", default: ".lightmap" }),
+    out: str("where the PNGs go", { value: "<dir>", default: ".lightmap/png" }),
+    key: str("instances whose key matches this regular expression (default: whole pages)", { value: "<regex>" }),
+    layer: str(`which layers: a comma list of ${LAYERS.join(", ")} or all`, { value: "<list>", default: "irradiance,visibility,direction" }),
+    scale: num("enlargement of a rect crop (integer)", { default: 8 }),
+    margin: num("texels of gutter around a rect crop", { default: 4 }),
+    "lux-range": str("log10 lux mapped to black..white", { value: "<lo,hi>", default: "0,5" }),
+    white: num("linear mode: the lux shown as white (0 = log mode)", { default: 0 }),
+    limit: num("instances to render with --key (0 = all)", { default: 24 }),
+  },
+  examples: [ "lecodes lightmap inspect --bake assets/school/lightmap/school.bake --debug-dir .lightmap/school", "lecodes lightmap inspect --key 'Wall_05' --layer irradiance,sun,sky,lamps --scale 6" ],
+  run: ({ flags }) => {
+    const { root } = localProject()
+    const bakeFile = resolve(root, flags.bake)
+    const data = readBake(bakeFile)
+    const stem = basename(bakeFile).replace(/\.bake$/, "")
+    const dbg = resolve(root, flags["debug-dir"])
+    const outDir = resolve(root, flags.out)
+    mkdirSync(outDir, { recursive: true })
+    const layers = flags.layer === "all" ? LAYERS : flags.layer.split(",").map((s) => s.trim()).filter(Boolean)
+    for (const l of layers) if (!LAYERS.includes(l)) throw new CliError(`--layer: unknown layer "${l}" (${LAYERS.join(", ")})`)
+    const [ lo, hi ] = flags["lux-range"].split(",").map(Number)
+    const white = flags.white
+    const toneOf = (layer: string): Tone => layer === "irradiance" || layer === "sun" || layer === "sky" || layer === "lamps" || layer === "bounce" || layer === "bounce-raw" || layer === "probes" ? (white > 0 ? "linear" : "log") : layer === "direction" || layer === "normal" ? "normal" : layer === "position" ? "raw" : layer === "ids" ? "raw" : "raw"
+    const pageFile = (layer: string, page: number): string => join(dbg, `${stem}-${layer}${page > 0 ? `_${page}` : ""}.pfm`)
+    const receivers = data.instances.filter((i) => i.receiver && i.rect)
+    const re = flags.key ? new RegExp(flags.key) : null
+    const size = data.size
+    let written = 0
+    const layerCache = new Map<string, ReturnType<typeof readPfm>>()
+    const load = (layer: string, page: number) => {
+      const k = `${layer}:${page}`
+      let v = layerCache.get(k)
+      if (!v) {
+        const f = pageFile(layer, page)
+        if (!existsSync(f)) throw new CliError(`No ${relative(root, f)} — bake with --debug-dir ${relative(root, dbg) || "."} first.`)
+        v = readPfm(f)
+        layerCache.set(k, v)
+      }
+      return v
+    }
+    const pixel = (L: ReturnType<typeof readPfm>, x: number, y: number, tone: Tone, layer: string): [number, number, number] => {
+      const i = (y * L.w + x) * L.ch
+      if (layer === "ids") {
+        // an instance colour from its index, chart darkens it
+        const inst = L.data[i], chart = L.data[i + 1]
+        if (inst === 0 && chart === 0 && L.data[i + 2] === 0) return [ 0, 0, 0 ]
+        const h = ((inst + 1) * 0.618033) % 1, s = 0.75, v = 0.55 + 0.4 * (((chart + 1) * 0.381966) % 1)
+        const f = (n: number): number => { const k = (n + h * 6) % 6; return Math.round(255 * v * (1 - s * Math.max(0, Math.min(k, 4 - k, 1)))) }
+        return [ f(5), f(3), f(1) ]
+      }
+      if (L.ch === 1) { const g = toneMap(L.data[i], tone, lo, hi, white); return [ g, g, g ] }
+      return [ toneMap(L.data[i], tone, lo, hi, white), toneMap(L.data[i + 1], tone, lo, hi, white), toneMap(L.data[i + 2], tone, lo, hi, white) ]
+    }
+    // the reflection probes' strip (one file, not per page): level 0 of every probe, its six faces +X -X +Y -Y +Z -Z side
+    // by side, one row of faces per probe — radiance in the lux scale of the light layers
+    if (!re && layers.includes("probes")) {
+      const f = join(dbg, `${stem}-probes.pfm`)
+      if (!existsSync(f)) throw new CliError(`No ${relative(root, f)} — bake with --probe-spacing > 0 and --debug-dir ${relative(root, dbg) || "."} first.`)
+      const L = readPfm(f)
+      const rgb = new Uint8Array(L.w * L.h * 3)
+      for (let y = 0; y < L.h; y++) for (let x = 0; x < L.w; x++) { const p = pixel(L, x, y, toneOf("probes"), "probes"); const o = (y * L.w + x) * 3; rgb[o] = p[0]; rgb[o + 1] = p[1]; rgb[o + 2] = p[2] }
+      const file = join(outDir, `${stem}-probes.png`)
+      writePng(file, L.w, L.h, rgb)
+      written++
+      logErr(c.dim(`  ${relative(root, file)} (${data.probes?.count ?? L.h / (L.w / 6)} probe(s), faces +X -X +Y -Y +Z -Z per row)`))
+    }
+    if (!re) {
+      for (let page = 0; page < data.pages; page++) {
+        for (const layer of layers.filter((l) => l !== "probes")) {
+          const L = load(layer, page)
+          const tone = toneOf(layer)
+          const rgb = new Uint8Array(size * size * 3)
+          for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) { const p = pixel(L, x, y, tone, layer); const o = (y * size + x) * 3; rgb[o] = p[0]; rgb[o + 1] = p[1]; rgb[o + 2] = p[2] }
+          // rect outlines in magenta
+          for (const r of receivers) {
+            if (r.page !== page) continue
+            const [ rx, ry, rw, rh ] = r.rect!
+            for (let x = rx - 1; x <= rx + rw; x++) for (const y of [ ry - 1, ry + rh ]) if (x >= 0 && x < size && y >= 0 && y < size) { const o = (y * size + x) * 3; rgb[o] = 255; rgb[o + 1] = 0; rgb[o + 2] = 255 }
+            for (let y = ry - 1; y <= ry + rh; y++) for (const x of [ rx - 1, rx + rw ]) if (x >= 0 && x < size && y >= 0 && y < size) { const o = (y * size + x) * 3; rgb[o] = 255; rgb[o + 1] = 0; rgb[o + 2] = 255 }
+          }
+          const file = join(outDir, `${stem}-${layer}${page > 0 ? `_${page}` : ""}.png`)
+          writePng(file, size, size, rgb)
+          written++
+          logErr(c.dim(`  ${relative(root, file)}`))
+        }
+      }
+    } else {
+      let rows = receivers.filter((r) => re.test(r.key))
+      if (rows.length === 0) throw new CliError(`No receiver key matches /${flags.key}/ in ${relative(root, bakeFile)}`)
+      const total = rows.length
+      if (flags.limit > 0) rows = rows.slice(0, flags.limit)
+      const scale = Math.max(1, Math.floor(flags.scale)), margin = Math.max(0, Math.floor(flags.margin))
+      for (const r of rows) {
+        const [ rx, ry, rw, rh ] = r.rect!
+        const x0 = Math.max(0, rx - margin), y0 = Math.max(0, ry - margin), x1 = Math.min(size, rx + rw + margin), y1 = Math.min(size, ry + rh + margin)
+        const cw = (x1 - x0) * scale, chh = (y1 - y0) * scale
+        for (const layer of layers.filter((l) => l !== "probes")) {
+          const L = load(layer, r.page ?? 0)
+          const tone = toneOf(layer)
+          const rgb = new Uint8Array(cw * chh * 3)
+          for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) {
+            const p = pixel(L, x, y, tone, layer)
+            const inRect = x >= rx && x < rx + rw && y >= ry && y < ry + rh
+            // the gutter dimmed, so the rect's own texels stand out
+            const px = inRect ? p : [ p[0] >> 1, p[1] >> 1, p[2] >> 1 ]
+            for (let sy = 0; sy < scale; sy++) for (let sx = 0; sx < scale; sx++) {
+              const o = (((y - y0) * scale + sy) * cw + (x - x0) * scale + sx) * 3
+              rgb[o] = px[0]; rgb[o + 1] = px[1]; rgb[o + 2] = px[2]
+            }
+          }
+          const safe = r.key.replace(/[^A-Za-z0-9_.-]+/g, "_")
+          const file = join(outDir, `${safe}-${layer}.png`)
+          writePng(file, cw, chh, rgb)
+          written++
+        }
+        logErr(c.dim(`  ${r.key}: page ${r.page} rect ${rx},${ry} ${rw}x${rh}, mean ${lum(r.mean).toFixed(1)} lux, sun ${(r.sunVis ?? 0).toFixed(3)} sky ${(r.skyVis ?? 0).toFixed(3)} → ${relative(root, outDir)}/${r.key.replace(/[^A-Za-z0-9_.-]+/g, "_")}-<layer>.png`))
+      }
+      if (total > rows.length) logErr(c.dim(`  … ${total - rows.length} more match (--limit 0 for all)`))
+    }
+    logErr(c.green(`✓ ${written} PNG(s) in ${relative(root, outDir) || "."}`))
+  },
+})
+
+export default defineCommand({
+  name: "lightmap",
+  summary: "Baked lighting: bake the level's statics, read a bake's numbers, inspect its layers",
+  commands: [ bake, stats, diff, inspect ],
+})