lecodes-assets 0.2.1 → 2.5.0

package/src/doctor/transcodeKtx2.ts

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

package/src/doctor/transcodeTextures.ts

@@ -15,6 +15,11 @@ import type { Root, Texture } from '@gltf-transform/core'
 export const DEFAULT_MAX_SIZE = 2048
 const HEAVY_PNG_MIN_DIM = 1024
 
+/** An IMPOSTOR ATLAS (doctor/impostor.ts tags both with extras `lecodes.impostor`): never resized by the size cap — its
+ *  frames sit at fixed pixel rects, and a 12 × 256 = 3072 px strip squashed under a 2048 cap is a different layout. */
+export const isImpostorAtlas = (tex: Texture): boolean =>
+  !!(tex.getExtras() as { lecodes?: { impostor?: unknown } } | undefined)?.lecodes?.impostor
+
 export interface TexturePlan {
   tex: Texture
   name: string
@@ -63,7 +68,7 @@ export async function planTexture(tex: Texture, root: Root, maxSize = DEFAULT_MA
     return null // undecodable by sharp — leave it
   }
 
-  const resize = Math.max(width, height) > maxSize
+  const resize = !isImpostorAtlas(tex) && Math.max(width, height) > maxSize
   let desired: 'jpeg' | 'png' = forceFmt ?? (hasAlpha ? 'png' : 'jpeg') // PNG only when alpha is needed
   if (desired === 'jpeg' && hasAlpha) desired = 'png' // never drop a real alpha channel
 

package/src/doctor/validateGlb.ts

@@ -1,4 +1,4 @@
-// MIRROR of packages/viewer/src/viewer/validateGlb.ts (kept in sync by hand — the viewer copy is the source of truth;
+// MIRROR of runtime/web/src/viewer/validateGlb.ts (kept in sync by hand — the viewer copy is the source of truth;
 // duplicated so lecodes-assets stays publishable without a cross-package import).
 // Pre-flight GLB validator — runs in the browser and in Bun (no Node/DOM APIs, no deps).
 //
@@ -17,7 +17,7 @@
 export const MAX_BONE_COUNT = 256
 export const MAX_MORPH_TARGET_COUNT = 256
 
-// Texture formats with a provider registered in creator-gl (see packages/creator-gl/src/glb.cpp).
+// Texture formats with a provider registered in creator-gl (see engines/gl/src/glb.cpp).
 export const SUPPORTED_IMAGE_FORMATS = ['png', 'jpeg', 'ktx2'] as const
 export type ImageFormat = (typeof SUPPORTED_IMAGE_FORMATS)[number] | 'webp' | 'unknown'
 

package/src/doctor/vertexAo.ts

@@ -0,0 +1,333 @@
+// VERTEX AMBIENT OCCLUSION FOR VEGETATION — the sky's visibility from every vertex of a plant, baked into
+// COLOR_0.r at import (what SpeedTree bakes for its trees, and the one thing that makes a crown read as
+// a volume instead of a heap of green cards: the leaves deep inside take less sky than the ones on the
+// outside, and the trunk under the crown stands in its shade).
+//
+// The convention the vegetation tier reads (creator-gl materials/src/foliage.mat):
+//   COLOR_0 = (ao, cavity, 1, wind)   ao      = sky visibility 0..1 (cosine-weighted upper hemisphere, WORLD up)
+//                                     cavity  = the bark's short-range occlusion 0..1 (the hemisphere of its own normal,
+//                                               hits within `cavity` metres: limb joints, the trunk under a limb); cards 1
+//                                     wind    = the per-vertex wind weight — the pack's own (COLOR_0.a as it came) when
+//                                               its material carries a wind profile (`lecodes.wind`), else the height
+//                                               over the plant squared
+// An exact white (1, 1, 1, 1) is what gltfio hands a mesh WITHOUT a colour set, and the shader takes that
+// as "no data" (ao 1, height weight) — a vertex whose ao AND wind both round to 1 lands there too, and it
+// is exactly the vertex nothing changes for.
+//
+// Occluders = every triangle of the asset's level-0 meshes (`_LOD<n>` n ≥ 1 are copies of the same
+// plant), cards counted opaque — a coarse hit for an alpha-cutout leaf, which over-darkens a little and
+// is what the shader's strength knob is for. A BVH over the triangles, `rays` cosine-weighted rays per
+// vertex from a fixed sequence rotated per vertex, rays start `bias` metres off the surface.
+
+import type { Document, Primitive } from "@gltf-transform/core"
+
+type Tri = { ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number }
+type BvhNode = { min: [number, number, number], max: [number, number, number], left: number, right: number, first: number, count: number }
+
+const buildBvh = (tris: Tri[]): { nodes: BvhNode[], order: number[] } => {
+  const order = tris.map((_, i) => i)
+  const nodes: BvhNode[] = []
+  const cx = (t: Tri): number => (t.ax + t.bx + t.cx) / 3, cy = (t: Tri): number => (t.ay + t.by + t.cy) / 3, cz = (t: Tri): number => (t.az + t.bz + t.cz) / 3
+  const build = (first: number, count: number): number => {
+    const min: [number, number, number] = [ Infinity, Infinity, Infinity ], max: [number, number, number] = [ -Infinity, -Infinity, -Infinity ]
+    for (let i = first; i < first + count; i++) {
+      const t = tris[order[i]]
+      min[0] = Math.min(min[0], t.ax, t.bx, t.cx); min[1] = Math.min(min[1], t.ay, t.by, t.cy); min[2] = Math.min(min[2], t.az, t.bz, t.cz)
+      max[0] = Math.max(max[0], t.ax, t.bx, t.cx); max[1] = Math.max(max[1], t.ay, t.by, t.cy); max[2] = Math.max(max[2], t.az, t.bz, t.cz)
+    }
+    const id = nodes.length
+    nodes.push({ min, max, left: -1, right: -1, first, count })
+    if (count <= 8) return id
+    const ext = [ max[0] - min[0], max[1] - min[1], max[2] - min[2] ]
+    const axis = ext[0] >= ext[1] && ext[0] >= ext[2] ? 0 : ext[1] >= ext[2] ? 1 : 2
+    const key = axis === 0 ? cx : axis === 1 ? cy : cz
+    const slice = order.slice(first, first + count).sort((a, b) => key(tris[a]) - key(tris[b]))
+    for (let i = 0; i < count; i++) order[first + i] = slice[i]
+    const half = count >> 1
+    const n = nodes[id]
+    n.count = 0
+    n.left = build(first, half)
+    n.right = build(first + half, count - half)
+    return id
+  }
+  if (tris.length) build(0, tris.length)
+  return { nodes, order }
+}
+
+/** Möller–Trumbore, both sides: the hit distance in (tmin, tmax), or -1. */
+const triDist = (t: Tri, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tmin: number, tmax: number): number => {
+  const e1x = t.bx - t.ax, e1y = t.by - t.ay, e1z = t.bz - t.az
+  const e2x = t.cx - t.ax, e2y = t.cy - t.ay, e2z = t.cz - t.az
+  const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x
+  const det = e1x * px + e1y * py + e1z * pz
+  if (Math.abs(det) < 1e-9) return -1
+  const inv = 1 / det
+  const tx = ox - t.ax, ty = oy - t.ay, tz = oz - t.az
+  const u = (tx * px + ty * py + tz * pz) * inv
+  if (u < 0 || u > 1) return -1
+  const qx = ty * e1z - tz * e1y, qy = tz * e1x - tx * e1z, qz = tx * e1y - ty * e1x
+  const v = (dx * qx + dy * qy + dz * qz) * inv
+  if (v < 0 || u + v > 1) return -1
+  const d = (e2x * qx + e2y * qy + e2z * qz) * inv
+  return d > tmin && d < tmax ? d : -1
+}
+const hitTri = (t: Tri, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tmin: number, tmax: number): boolean =>
+  triDist(t, ox, oy, oz, dx, dy, dz, tmin, tmax) >= 0
+
+const hitBox = (n: BvhNode, ox: number, oy: number, oz: number, ix: number, iy: number, iz: number, tmax: number): boolean => {
+  let t0 = 0, t1 = tmax
+  const a = (n.min[0] - ox) * ix, b = (n.max[0] - ox) * ix; t0 = Math.max(t0, Math.min(a, b)); t1 = Math.min(t1, Math.max(a, b))
+  const c = (n.min[1] - oy) * iy, d = (n.max[1] - oy) * iy; t0 = Math.max(t0, Math.min(c, d)); t1 = Math.min(t1, Math.max(c, d))
+  const e = (n.min[2] - oz) * iz, f = (n.max[2] - oz) * iz; t0 = Math.max(t0, Math.min(e, f)); t1 = Math.min(t1, Math.max(e, f))
+  return t1 >= t0
+}
+
+const occluded = (bvh: { nodes: BvhNode[], order: number[] }, tris: Tri[], ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tmin: number, tmax: number): boolean => {
+  if (!bvh.nodes.length) return false
+  const ix = 1 / (dx || 1e-12), iy = 1 / (dy || 1e-12), iz = 1 / (dz || 1e-12)
+  const stack = [ 0 ]
+  while (stack.length) {
+    const n = bvh.nodes[stack.pop()!]
+    if (!hitBox(n, ox, oy, oz, ix, iy, iz, tmax)) continue
+    if (n.left < 0) {
+      for (let i = n.first; i < n.first + n.count; i++) if (hitTri(tris[bvh.order[i]], ox, oy, oz, dx, dy, dz, tmin, tmax)) return true
+    } else { stack.push(n.left, n.right) }
+  }
+  return false
+}
+
+/** The nearest hit along the ray in (tmin, tmax), or Infinity. */
+const nearestHit = (bvh: { nodes: BvhNode[], order: number[] }, tris: Tri[], ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tmin: number, tmax: number): number => {
+  let best = Infinity
+  if (!bvh.nodes.length) return best
+  const ix = 1 / (dx || 1e-12), iy = 1 / (dy || 1e-12), iz = 1 / (dz || 1e-12)
+  const stack = [ 0 ]
+  while (stack.length) {
+    const n = bvh.nodes[stack.pop()!]
+    if (!hitBox(n, ox, oy, oz, ix, iy, iz, Math.min(tmax, best))) continue
+    if (n.left < 0) {
+      for (let i = n.first; i < n.first + n.count; i++) {
+        const d = triDist(tris[bvh.order[i]], ox, oy, oz, dx, dy, dz, tmin, Math.min(tmax, best))
+        if (d >= 0 && d < best) best = d
+      }
+    } else { stack.push(n.left, n.right) }
+  }
+  return best
+}
+
+export type VertexAoOptions = {
+  /** Rays per vertex (default 48). */
+  rays?: number
+  /** Metres a ray starts off its vertex (default 0.02). */
+  bias?: number
+  /** Metres a ray travels (default: the asset's extent). */
+  maxDistance?: number
+  /** CAVITY (junction) occlusion for the OPAQUE primitives — the bark: `cavityRays` cosine-weighted rays in the
+   *  hemisphere of the vertex' own normal, a hit within `cavity` metres counts by (1 - distance / cavity) → COLOR_0.g,
+   *  1 = open. The base of a limb and the trunk around it darken, the joint reads as grown, not laid on. Leaf cards
+   *  keep 1 (their own neighbours would darken every crown). Default 0.8 m, 0 = off. */
+  cavity?: number
+  /** Rays per vertex for the cavity term (default 24). */
+  cavityRays?: number
+  /** CANOPY NORMALS: how far the normals of the alpha-MASK primitives (the leaf cards) are bent toward the
+   *  direction from the crown's centre — 0 keeps the cards' own (each card lit as a flat plane: a heap of
+   *  cut-outs), 1 makes the crown shade like one sphere. Default 0.6 — what a tree tool bakes. */
+  canopy?: number
+}
+
+const LOD_RE = /_LOD([1-9]\d*)$/i
+
+/** True when the primitive's material carries the pack's wind profile (glTF extras `lecodes.wind`, kindGlb.ts
+ *  windProfile): the one case a vertex alpha is an authored wind weight. */
+const windProfiled = (p: Primitive): boolean => {
+  const extras = p.getMaterial()?.getExtras() as { lecodes?: { wind?: unknown } } | null | undefined
+  return Array.isArray(extras?.lecodes?.wind)
+}
+
+/** World-space triangles of every level-0 mesh node. */
+const collectOccluders = (doc: Document): { tris: Tri[], min: [number, number, number], max: [number, number, number] } => {
+  const tris: Tri[] = []
+  const min: [number, number, number] = [ Infinity, Infinity, Infinity ], max: [number, number, number] = [ -Infinity, -Infinity, -Infinity ]
+  for (const node of doc.getRoot().listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh || LOD_RE.test(node.getName())) continue
+    const m = node.getWorldMatrix()
+    for (const p of mesh.listPrimitives()) {
+      const pos = p.getAttribute("POSITION"), idx = p.getIndices()
+      if (!pos || p.getMode() !== 4) continue
+      const n = idx ? idx.getCount() : pos.getCount()
+      const v: number[] = []
+      const at = (k: number): [number, number, number] => {
+        pos.getElement(idx ? idx.getScalar(k) : k, v)
+        const x = m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12], y = m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13], z = m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14]
+        min[0] = Math.min(min[0], x); min[1] = Math.min(min[1], y); min[2] = Math.min(min[2], z)
+        max[0] = Math.max(max[0], x); max[1] = Math.max(max[1], y); max[2] = Math.max(max[2], z)
+        return [ x, y, z ]
+      }
+      for (let k = 0; k + 2 < n; k += 3) {
+        const a = at(k), b = at(k + 1), c = at(k + 2)
+        tris.push({ ax: a[0], ay: a[1], az: a[2], bx: b[0], by: b[1], bz: b[2], cx: c[0], cy: c[1], cz: c[2] })
+      }
+    }
+  }
+  return { tris, min, max }
+}
+
+/** Cosine-weighted directions on the upper hemisphere (world +Y), a fixed Fibonacci set. */
+const skyRays = (count: number): [number, number, number][] => {
+  const out: [number, number, number][] = []
+  const golden = Math.PI * (3 - Math.sqrt(5))
+  for (let i = 0; i < count; i++) {
+    const u = (i + 0.5) / count                 // cosine-weighted: y = sqrt(1 - u) puts more rays near the zenith
+    const y = Math.sqrt(1 - u), r = Math.sqrt(u), phi = i * golden
+    out.push([ r * Math.cos(phi), y, r * Math.sin(phi) ])
+  }
+  return out
+}
+
+/**
+ * Bake the sky visibility of every vertex of the document's meshes into COLOR_0 as (ao, 1, 1, wind) — see the
+ * header. Returns the number of vertices written and the mean ao (a plant reads ~0.5–0.7).
+ */
+export const bakeVertexAo = (doc: Document, opts: VertexAoOptions = {}): { vertices: number, meanAo: number } => {
+  const { tris, min, max } = collectOccluders(doc)
+  if (!tris.length) return { vertices: 0, meanAo: 1 }
+  const bvh = buildBvh(tris)
+  const rays = skyRays(opts.rays ?? 48)
+  const bias = opts.bias ?? 0.02
+  const reach = opts.maxDistance ?? Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2])
+  const cavReach = Math.max(opts.cavity ?? 0.8, 0)
+  const cavRays = skyRays(opts.cavityRays ?? 24)
+  const height = Math.max(max[1] - min[1], 0.05)
+  let vertices = 0, sum = 0
+  const done = new Set<Primitive>()
+  // the crown: the centre of every leaf card's vertices (world), what the canopy normals point away from
+  const canopy = Math.min(Math.max(opts.canopy ?? 0.6, 0), 1)
+  const crown = [ 0, 0, 0 ]
+  let crownN = 0
+  if (canopy > 0) {
+    for (const node of doc.getRoot().listNodes()) {
+      const mesh = node.getMesh()
+      if (!mesh || LOD_RE.test(node.getName())) continue
+      const m = node.getWorldMatrix()
+      for (const p of mesh.listPrimitives()) {
+        if (p.getMaterial()?.getAlphaMode() !== "MASK") continue
+        const pos = p.getAttribute("POSITION"); if (!pos) continue
+        const v: number[] = []
+        for (let i = 0; i < pos.getCount(); i++) { pos.getElement(i, v); crown[0] += m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12]; crown[1] += m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13]; crown[2] += m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14]; crownN++ }
+      }
+    }
+    if (crownN) { crown[0] /= crownN; crown[1] /= crownN; crown[2] /= crownN }
+  }
+  for (const node of doc.getRoot().listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh) continue
+    const m = node.getWorldMatrix()
+    for (const p of mesh.listPrimitives()) {
+      if (done.has(p)) continue
+      done.add(p)
+      const pos = p.getAttribute("POSITION")
+      if (!pos) continue
+      const n = pos.getCount()
+      // canopy normals on the leaf cards: the card's normal blended toward "away from the crown's centre" (in the
+      // node's frame: the crown centre pulled back through the inverse world matrix, rotation-only for the normal)
+      const nrm = p.getAttribute("NORMAL")
+      if (canopy > 0 && crownN && nrm && p.getMaterial()?.getAlphaMode() === "MASK") {
+        const inv = invert4(m)
+        const cl = inv ? [ inv[0] * crown[0] + inv[4] * crown[1] + inv[8] * crown[2] + inv[12], inv[1] * crown[0] + inv[5] * crown[1] + inv[9] * crown[2] + inv[13], inv[2] * crown[0] + inv[6] * crown[1] + inv[10] * crown[2] + inv[14] ] : null
+        if (cl) {
+          const out = new Float32Array(new ArrayBuffer(n * 12)), v: number[] = [], q: number[] = []
+          for (let i = 0; i < n; i++) {
+            pos.getElement(i, v); nrm.getElement(i, q)
+            let dx = v[0] - cl[0], dy = v[1] - cl[1], dz = v[2] - cl[2]
+            const l = Math.hypot(dx, dy, dz) || 1
+            dx /= l; dy /= l; dz /= l
+            // a card facing the wrong way is flipped into the hemisphere of its radial first (double-sided cards
+            // have no side of their own), then blended
+            const flip = q[0] * dx + q[1] * dy + q[2] * dz < 0 ? -1 : 1
+            let nx = q[0] * flip * (1 - canopy) + dx * canopy, ny = q[1] * flip * (1 - canopy) + dy * canopy, nz = q[2] * flip * (1 - canopy) + dz * canopy
+            const nl = Math.hypot(nx, ny, nz) || 1
+            out[i * 3] = nx / nl; out[i * 3 + 1] = ny / nl; out[i * 3 + 2] = nz / nl
+          }
+          p.setAttribute("NORMAL", doc.createAccessor().setType("VEC3").setArray(out).setBuffer(doc.getRoot().listBuffers()[0] ?? doc.createBuffer()))
+          if (nrm.listParents().length <= 1) nrm.dispose()
+        }
+      }
+      const old = p.getAttribute("COLOR_0")
+      const oldEl = old ? old.getElementSize() : 0
+      const authoredWind = windProfiled(p)
+      const out = new Float32Array(new ArrayBuffer(n * 16))
+      const v: number[] = [], c: number[] = [], q: number[] = []
+      // the cavity term: the bark (opaque) with a normal, rays in the hemisphere of the vertex' world normal
+      const cavNrm = cavReach > 0 && p.getMaterial()?.getAlphaMode() !== "MASK" ? p.getAttribute("NORMAL") : null
+      for (let i = 0; i < n; i++) {
+        pos.getElement(i, v)
+        const x = m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12], y = m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13], z = m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14]
+        // a per-vertex rotation of the fixed set about +Y, so neighbours never share a banding pattern
+        const rot = ((x * 12.9898 + z * 78.233 + y * 37.719) % 1 + 1) % 1 * Math.PI * 2, cr = Math.cos(rot), sr = Math.sin(rot)
+        let open = 0
+        for (const d of rays) {
+          const dx = d[0] * cr - d[2] * sr, dz = d[0] * sr + d[2] * cr
+          if (!occluded(bvh, tris, x + dx * bias, y + d[1] * bias, z + dz * bias, dx, d[1], dz, 0, reach)) open++
+        }
+        const ao = open / rays.length
+        let cav = 1
+        if (cavNrm) {
+          nrmOf(cavNrm, i, m, q)
+          // a tangent frame about the normal: the +Y ray set turned into it, and the per-vertex rotation kept
+          const ax = Math.abs(q[1]) < 0.9 ? 0 : 1, ay = ax ? 0 : 1
+          let tx = ay * q[2] - 0, ty = 0 - ax * q[2], tz = ax * q[1] - ay * q[0]      // cross(n, a) for a = (ax, ay, 0)
+          const tl = Math.hypot(tx, ty, tz) || 1; tx /= tl; ty /= tl; tz /= tl
+          const bx = q[1] * tz - q[2] * ty, by = q[2] * tx - q[0] * tz, bz = q[0] * ty - q[1] * tx   // cross(n, t)
+          let occ = 0
+          for (const d of cavRays) {
+            const rx = d[0] * cr - d[2] * sr, rz = d[0] * sr + d[2] * cr
+            const dx = tx * rx + q[0] * d[1] + bx * rz, dy = ty * rx + q[1] * d[1] + by * rz, dz = tz * rx + q[2] * d[1] + bz * rz
+            // the origin is lifted off the vertex' OWN surface along its normal only, and a hit at distance 0 counts: a limb's
+            // base vertex lies ON the trunk, and the rays into the trunk meet its surface right there - that IS the joint
+            const h = nearestHit(bvh, tris, x + q[0] * bias, y + q[1] * bias, z + q[2] * bias, dx, dy, dz, -1e-6, cavReach)
+            if (h < cavReach) occ += 1 - h / cavReach
+          }
+          cav = 1 - occ / cavRays.length
+        }
+        // the wind weight: the pack's own alpha when its shader AUTHORED one there (the material carries a wind profile,
+        // `lecodes.wind` - NatureManufacture paints the weight into the vertex alpha), else the height over the plant,
+        // squared. A pack whose wind mask lives in a texture (Chernobyl's Leaves.shader) ships the alpha at 1 everywhere,
+        // and taken as the weight that shivered every leaf by the field's full amplitude (2026-11-03).
+        let wind: number
+        if (old && oldEl === 4 && authoredWind) { old.getElement(i, c); wind = c[3] } else { const h = Math.min(Math.max((y - min[1]) / height, 0), 1); wind = h * h }
+        out[i * 4] = ao; out[i * 4 + 1] = cav; out[i * 4 + 2] = 1; out[i * 4 + 3] = wind
+        sum += ao; vertices++
+      }
+      const acc = doc.createAccessor().setType("VEC4").setArray(out).setBuffer(doc.getRoot().listBuffers()[0] ?? doc.createBuffer())
+      p.setAttribute("COLOR_0", acc)
+      if (old && old.listParents().length <= 1) old.dispose()
+    }
+  }
+  return { vertices, meanAo: vertices ? sum / vertices : 1 }
+}
+
+/** The vertex' normal in world space (the node's rotation part, then normalised), into `q`. */
+const nrmOf = (nrm: { getElement(i: number, out: number[]): number[] }, i: number, m: ArrayLike<number>, q: number[]): void => {
+  nrm.getElement(i, q)
+  const x = m[0] * q[0] + m[4] * q[1] + m[8] * q[2], y = m[1] * q[0] + m[5] * q[1] + m[9] * q[2], z = m[2] * q[0] + m[6] * q[1] + m[10] * q[2]
+  const l = Math.hypot(x, y, z) || 1
+  q[0] = x / l; q[1] = y / l; q[2] = z / l
+}
+
+/** 4×4 column-major inverse (null when singular). */
+const invert4 = (m: ArrayLike<number>): number[] | null => {
+  const a = Array.from(m), r = new Array<number>(16)
+  const [ a00, a01, a02, a03, a10, a11, a12, a13, a20, a21, a22, a23, a30, a31, a32, a33 ] = a
+  const b00 = a00 * a11 - a01 * a10, b01 = a00 * a12 - a02 * a10, b02 = a00 * a13 - a03 * a10, b03 = a01 * a12 - a02 * a11
+  const b04 = a01 * a13 - a03 * a11, b05 = a02 * a13 - a03 * a12, b06 = a20 * a31 - a21 * a30, b07 = a20 * a32 - a22 * a30
+  const b08 = a20 * a33 - a23 * a30, b09 = a21 * a32 - a22 * a31, b10 = a21 * a33 - a23 * a31, b11 = a22 * a33 - a23 * a32
+  let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06
+  if (Math.abs(det) < 1e-12) return null
+  det = 1 / det
+  r[0] = (a11 * b11 - a12 * b10 + a13 * b09) * det; r[1] = (a02 * b10 - a01 * b11 - a03 * b09) * det; r[2] = (a31 * b05 - a32 * b04 + a33 * b03) * det; r[3] = (a22 * b04 - a21 * b05 - a23 * b03) * det
+  r[4] = (a12 * b08 - a10 * b11 - a13 * b07) * det; r[5] = (a00 * b11 - a02 * b08 + a03 * b07) * det; r[6] = (a32 * b02 - a30 * b05 - a33 * b01) * det; r[7] = (a20 * b05 - a22 * b02 + a23 * b01) * det
+  r[8] = (a10 * b10 - a11 * b08 + a13 * b06) * det; r[9] = (a01 * b08 - a00 * b10 - a03 * b06) * det; r[10] = (a30 * b04 - a31 * b02 + a33 * b00) * det; r[11] = (a21 * b02 - a20 * b04 - a23 * b00) * det
+  r[12] = (a11 * b07 - a10 * b09 - a12 * b06) * det; r[13] = (a00 * b09 - a01 * b07 + a02 * b06) * det; r[14] = (a31 * b01 - a30 * b03 - a32 * b00) * det; r[15] = (a20 * b03 - a21 * b01 + a22 * b00) * det
+  return r
+}