lecodes-assets 0.2.0 → 2.4.10

package/src/doctor/validateGlb.ts

@@ -0,0 +1,264 @@
+// 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).
+//
+// Why this exists: the creator-gl wasm is shipped WITHOUT emscripten assertions, so when a
+// model violates a filament hard-limit the C++ code calls abort() with no usable message
+// (e.g. "bone count > 256", or a missing texture-decoder for webp). Validate the bytes here,
+// BEFORE handing them to module._loadGlb(), and reject with a clear, actionable error instead.
+//
+// Mirrors the exact constraints filament/gltfio enforce at load time:
+//   - filament CONFIG_MAX_BONE_COUNT        = 256  (skin.joints per renderable)
+//   - filament CONFIG_MAX_MORPH_TARGET_COUNT = 256  (morph targets per primitive)
+//   - gltfio texture providers registered in glb.cpp: image/png, image/jpeg, image/ktx2 only
+//     (webp / EXT_texture_webp has no provider -> load fails).
+
+// ---- filament limits (keep in sync with EngineEnums.h) ----------------------------------------
+export const MAX_BONE_COUNT = 256
+export const MAX_MORPH_TARGET_COUNT = 256
+
+// 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'
+
+export interface GlbIssue {
+  level: 'error' | 'warning'
+  code: 'CONTAINER' | 'BONE_COUNT' | 'MORPH_COUNT' | 'TEXTURE_FORMAT'
+  message: string
+  detail?: Record<string, unknown>
+}
+
+export interface GlbValidationResult {
+  ok: boolean
+  errors: GlbIssue[]
+  warnings: GlbIssue[]
+  summary: {
+    skins: number
+    maxJointCount: number
+    images: number
+    formats: Record<string, number>
+  }
+}
+
+const GLB_MAGIC = 0x46546c67 // "glTF"
+const CHUNK_JSON = 0x4e4f534a // "JSON"
+const CHUNK_BIN = 0x004e4942 // "BIN\0"
+
+class GlbParseError extends Error {}
+
+export interface ParsedGlb {
+  json: any
+  bin: Uint8Array | null
+}
+
+function toBytes(data: ArrayBuffer | Uint8Array): Uint8Array {
+  return data instanceof Uint8Array ? data : new Uint8Array(data)
+}
+
+/** Container parse only (JSON chunk + BIN chunk); also accepts raw .gltf JSON bytes.
+ *  Exported for reuse (backend asset-metadata extraction) — throws GlbParseError on bad input. */
+export function parseGlb(bytes: Uint8Array): ParsedGlb {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+
+  // Accept a raw .gltf (JSON) too — useful for editor/CI paths. No BIN chunk in that case,
+  // so byte-sniffing of embedded images is skipped (uri/mimeType still validated).
+  if (bytes.byteLength < 12 || dv.getUint32(0, true) !== GLB_MAGIC) {
+    try {
+      return { json: JSON.parse(new TextDecoder().decode(bytes)), bin: null }
+    } catch {
+      throw new GlbParseError('Not a GLB (bad magic) and not parseable as glTF JSON')
+    }
+  }
+
+  const version = dv.getUint32(4, true)
+  if (version !== 2) throw new GlbParseError(`Unsupported GLB container version ${version} (expected 2)`)
+
+  let offset = 12
+  let json: any = null
+  let bin: Uint8Array | null = null
+  while (offset + 8 <= bytes.byteLength) {
+    const chunkLen = dv.getUint32(offset, true)
+    const chunkType = dv.getUint32(offset + 4, true)
+    const start = offset + 8
+    const end = start + chunkLen
+    if (end > bytes.byteLength) throw new GlbParseError(`Chunk at ${offset} overruns the file`)
+    if (chunkType === CHUNK_JSON) {
+      json = JSON.parse(new TextDecoder().decode(bytes.subarray(start, end)))
+    } else if (chunkType === CHUNK_BIN) {
+      bin = bytes.subarray(start, end)
+    }
+    offset = end // chunkLength already includes the 4-byte alignment padding (glTF spec)
+  }
+
+  if (!json) throw new GlbParseError('GLB has no JSON chunk')
+  return { json, bin }
+}
+
+// ---- image format detection -------------------------------------------------------------------
+
+function mimeToFormat(mime: string): ImageFormat {
+  switch (mime) {
+    case 'image/png': return 'png'
+    case 'image/jpeg': return 'jpeg'
+    case 'image/ktx2': return 'ktx2'
+    case 'image/webp': return 'webp'
+    default: return 'unknown'
+  }
+}
+
+function extToFormat(ext: string): ImageFormat {
+  switch (ext) {
+    case 'png': return 'png'
+    case 'jpg':
+    case 'jpeg': return 'jpeg'
+    case 'ktx2': return 'ktx2'
+    case 'webp': return 'webp'
+    default: return 'unknown'
+  }
+}
+
+function sniffMagic(b: Uint8Array): ImageFormat {
+  if (b.length >= 4 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return 'png'
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'jpeg'
+  // RIFF....WEBP
+  if (b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 &&
+      b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50) return 'webp'
+  // KTX2: 0xAB 'KTX 20' 0xBB 0x0D 0x0A 0x1A 0x0A
+  if (b.length >= 8 && b[0] === 0xab && b[1] === 0x4b && b[2] === 0x54 && b[3] === 0x58 &&
+      b[4] === 0x20 && b[5] === 0x32 && b[6] === 0x30 && b[7] === 0xbb) return 'ktx2'
+  return 'unknown'
+}
+
+function detectFormat(image: any, json: any, bin: Uint8Array | null): { format: ImageFormat; via: string } {
+  if (typeof image?.uri === 'string') {
+    const uri: string = image.uri
+    if (uri.startsWith('data:')) {
+      const m = /^data:([^;,]+)[;,]/.exec(uri)
+      const mime = (m?.[1] ?? '').toLowerCase()
+      return { format: mimeToFormat(mime), via: `data-uri "${mime || '?'}"` }
+    }
+    const ext = (uri.split('?')[0].split('#')[0].split('.').pop() ?? '').toLowerCase()
+    return { format: extToFormat(ext), via: `uri ".${ext}"` }
+  }
+  if (typeof image?.mimeType === 'string') {
+    const mime = image.mimeType.toLowerCase()
+    return { format: mimeToFormat(mime), via: `mimeType "${image.mimeType}"` }
+  }
+  if (typeof image?.bufferView === 'number' && bin) {
+    const bv = json.bufferViews?.[image.bufferView]
+    // embedded images live in buffer 0 (the BIN chunk) for GLB
+    if (bv && (bv.buffer ?? 0) === 0) {
+      const start = bv.byteOffset ?? 0
+      return { format: sniffMagic(bin.subarray(start, start + 16)), via: 'magic-bytes' }
+    }
+  }
+  return { format: 'unknown', via: 'undetermined' }
+}
+
+// Image indices actually referenced by a texture (standard source + ktx2/webp extension sources).
+function collectUsedImages(json: any): Set<number> {
+  const used = new Set<number>()
+  for (const t of json.textures ?? []) {
+    if (typeof t.source === 'number') used.add(t.source)
+    const basisu = t.extensions?.KHR_texture_basisu
+    if (typeof basisu?.source === 'number') used.add(basisu.source)
+    const webp = t.extensions?.EXT_texture_webp
+    if (typeof webp?.source === 'number') used.add(webp.source)
+  }
+  return used
+}
+
+// ---- main entry -------------------------------------------------------------------------------
+
+export function validateGlb(data: ArrayBuffer | Uint8Array): GlbValidationResult {
+  const errors: GlbIssue[] = []
+  const warnings: GlbIssue[] = []
+  const formats: Record<string, number> = {}
+
+  let parsed: ParsedGlb
+  try {
+    parsed = parseGlb(toBytes(data))
+  } catch (e) {
+    return {
+      ok: false,
+      errors: [{ level: 'error', code: 'CONTAINER', message: (e as Error).message }],
+      warnings: [],
+      summary: { skins: 0, maxJointCount: 0, images: 0, formats: {} },
+    }
+  }
+  const { json, bin } = parsed
+
+  // --- skins: joints per skin == filament mSkinningBoneCount, capped at CONFIG_MAX_BONE_COUNT ---
+  const skins: any[] = json.skins ?? []
+  let maxJointCount = 0
+  for (let i = 0; i < skins.length; i++) {
+    const n = skins[i]?.joints?.length ?? 0
+    maxJointCount = Math.max(maxJointCount, n)
+    if (n > MAX_BONE_COUNT) {
+      errors.push({
+        level: 'error',
+        code: 'BONE_COUNT',
+        message: `skin[${i}]${skins[i].name ? ` "${skins[i].name}"` : ''} has ${n} joints, exceeds filament limit of ${MAX_BONE_COUNT}`,
+        detail: { skin: i, name: skins[i].name, joints: n, limit: MAX_BONE_COUNT },
+      })
+    }
+  }
+
+  // --- morph targets per primitive, capped at CONFIG_MAX_MORPH_TARGET_COUNT --------------------
+  for (let mi = 0; mi < (json.meshes?.length ?? 0); mi++) {
+    const mesh = json.meshes[mi]
+    for (let pi = 0; pi < (mesh.primitives?.length ?? 0); pi++) {
+      const n = mesh.primitives[pi]?.targets?.length ?? 0
+      if (n > MAX_MORPH_TARGET_COUNT) {
+        errors.push({
+          level: 'error',
+          code: 'MORPH_COUNT',
+          message: `mesh[${mi}]${mesh.name ? ` "${mesh.name}"` : ''} primitive ${pi} has ${n} morph targets, exceeds filament limit of ${MAX_MORPH_TARGET_COUNT}`,
+          detail: { mesh: mi, primitive: pi, targets: n, limit: MAX_MORPH_TARGET_COUNT },
+        })
+      }
+    }
+  }
+
+  // --- textures: every image must decode with a registered provider (png/jpeg/ktx2) -----------
+  const images: any[] = json.images ?? []
+  const used = collectUsedImages(json)
+  for (let i = 0; i < images.length; i++) {
+    const { format, via } = detectFormat(images[i], json, bin)
+    formats[format] = (formats[format] ?? 0) + 1
+    const supported = (SUPPORTED_IMAGE_FORMATS as readonly string[]).includes(format)
+    if (supported) continue
+
+    const referenced = used.has(i)
+    const issue: GlbIssue = {
+      level: referenced ? 'error' : 'warning',
+      code: 'TEXTURE_FORMAT',
+      message:
+        `image[${i}]${images[i].name ? ` "${images[i].name}"` : ''} is ${format.toUpperCase()} ` +
+        `(${via})${referenced ? '' : ' [unreferenced]'} — only ${SUPPORTED_IMAGE_FORMATS.join('/')} are supported`,
+      detail: { image: i, format, via, referenced },
+    }
+    ;(referenced ? errors : warnings).push(issue)
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    summary: { skins: skins.length, maxJointCount, images: images.length, formats },
+  }
+}
+
+// Human-readable report (string, so it works identically in browser console and Bun stdout).
+export function formatReport(result: GlbValidationResult, label = 'GLB'): string {
+  const lines: string[] = []
+  const s = result.summary
+  lines.push(`${result.ok ? '✅ VALID' : '❌ INVALID'}  ${label}`)
+  lines.push(
+    `  skins=${s.skins} (max joints=${s.maxJointCount}/${MAX_BONE_COUNT})  ` +
+    `images=${s.images} [${Object.entries(s.formats).map(([k, v]) => `${k}:${v}`).join(', ') || 'none'}]`,
+  )
+  for (const e of result.errors) lines.push(`  ✗ ${e.code}: ${e.message}`)
+  for (const w of result.warnings) lines.push(`  ⚠ ${w.code}: ${w.message}`)
+  return lines.join('\n')
+}

package/src/doctor/vertexAo.ts

@@ -0,0 +1,321 @@
+// 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)
+//                                               or, for a mesh without one, 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
+
+/** 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 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 (its alpha, as it came) or the height over the plant, squared
+        let wind: number
+        if (old && oldEl === 4) { 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
+}