lecodes-gl-lite 2.0.0

package/src/core/frame.ts

@@ -0,0 +1,230 @@
+// Screen-space frame report — the part of scene3d that makes the JSON *evaluable*, not just
+// inspectable (docs/gl-lite-core-plan.md phase 4). The rest of scene3d is world-space, so an AI
+// reading it must do the camera math mentally to know what the frame looks like. This projects every
+// visible mesh / model / particles entity's world AABB through the camera (world matrix + fov +
+// viewport) into a screen rect, so composition is readable at a glance.
+//
+// It is serializer-level math over state the core already holds: NO bridges.d.ts method, no parity
+// impact — world→screen deliberately never becomes a bridge call (creator-gl only exposes the inverse,
+// getCameraViewDirection). Honest limits, mirrored in the output docs: depth order is a *hint* (true
+// occlusion needs rasterization — that's the WebGL backend's job, screenshot + _dumpScene3d side by
+// side), and headless does not *sample* animation poses, so rects reflect the rest pose.
+
+import { invertTRS, lookAtView, multiply, perspective } from "./math3d"
+import type { Ent, SceneCore, SceneRec } from "./sceneCore"
+
+const round = (v: number, digits: number): number => {
+  const f = 10 ** digits
+  const r = Math.round(v * f) / f
+  return r === 0 ? 0 : r
+}
+
+export type FrameObject = {
+  name?: string
+  /** Absolute path of named ancestors, root→self ("ball/bead") — the entity's identity now that
+   *  scene node names are only sibling-unique. Unnamed intermediate ancestors appear as `~`
+   *  (leading unnamed containers are dropped), so two same-named nodes under different unnamed
+   *  parents never collapse into one path. Always present on named objects. */
+  path?: string
+  kind: "mesh" | "model" | "particles"
+  /** Screen rect [x, y, w, h] in px (top-left origin) from projecting the world AABB's 8 corners. */
+  rect?: [number, number, number, number]
+  /** Screen center [x, y] in px. */
+  center?: [number, number]
+  /** Camera-space forward distance of the AABB center. Negative = behind the camera. */
+  depth: number
+  /** Fraction of the viewport the on-screen rect covers (0..1). */
+  coverage: number
+  /** Entirely off the viewport. */
+  offscreen?: boolean
+  /** Straddles a viewport edge or the near plane — the rect is a partial/approximate view. */
+  clipped?: boolean
+  /** Entirely behind the camera (no rect). */
+  behindCamera?: boolean
+}
+
+export type Frame = {
+  viewport: { width: number, height: number }
+  /** Notes on how to read this section (depth is a hint; rest-pose only headless). */
+  note: string
+  objects: FrameObject[]
+}
+
+/** Local-space AABB corners (world-transformed) for an entity that carries a mesh, else [].
+ *  (exported for the top-down map serializer — mapView.ts) */
+export const meshWorldCorners = (core: SceneCore, e: Ent): number[][] => {
+  const size = e.mesh?.size
+  if (!size) return []
+  const c = e.mesh?.center ?? [0, 0, 0]
+  const hx = size[0] / 2, hy = size[1] / 2, hz = size[2] / 2
+  const w = core.worldMatrixF(e.id)
+  const out: number[][] = []
+  for (let i = 0; i < 8; i++) {
+    const x = c[0] + (i & 1 ? hx : -hx)
+    const y = c[1] + (i & 2 ? hy : -hy)
+    const z = c[2] + (i & 4 ? hz : -hz)
+    out.push([
+      w[0] * x + w[4] * y + w[8] * z + w[12],
+      w[1] * x + w[5] * y + w[9] * z + w[13],
+      w[2] * x + w[6] * y + w[10] * z + w[14],
+    ])
+  }
+  return out
+}
+
+/** World-space AABB corners over a whole subtree (for a model root: all its glTF part meshes). */
+const subtreeWorldCorners = (core: SceneCore, id: number): number[][] => {
+  const acc: number[][] = []
+  const walk = (nid: number): void => {
+    const e = core.entities.get(nid)
+    if (!e) return
+    acc.push(...meshWorldCorners(core, e))
+    for (const c of e.children) walk(c)
+  }
+  walk(id)
+  return acc
+}
+
+/** World-space AABB over every mesh/model in the scene (+ overlays), or null when nothing is
+ *  renderable yet — backs the auto-fitted inspection views (`view: "iso"`), like creator-gl's
+ *  getCurrentSceneBounds natively. */
+export function sceneWorldBounds(core: SceneCore, scene: SceneRec): { min: number[], max: number[] } | null {
+  const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity]
+  let any = false
+  const memberScenes: SceneRec[] = [scene, ...scene.overlays.map((id) => core.scenes.get(id)).filter((s): s is SceneRec => !!s)]
+  const seen = new Set<number>()
+  const visit = (id: number): void => {
+    if (seen.has(id) || !core.entities.has(id)) return
+    seen.add(id)
+    const e = core.ent(id)
+    if (e.visible) {
+      for (const c of meshWorldCorners(core, e)) {
+        for (let i = 0; i < 3; i++) { if (c[i] < min[i]) min[i] = c[i]; if (c[i] > max[i]) max[i] = c[i] }
+        any = true
+      }
+      for (const ch of e.children) visit(ch)
+    }
+  }
+  for (const s of memberScenes) for (const id of s.entities) visit(id)
+  return any ? { min, max } : null
+}
+
+export function computeFrame(core: SceneCore, scene: SceneRec): Frame | undefined {
+  const camId = scene.camera
+  const override = core.cameraOverride()
+  if (!override && (camId === undefined || !core.entities.has(camId))) return undefined
+
+  const W = core.width, H = core.height
+  // the scene's own projection (setCameraProjection), so a custom fov moves the reported rects —
+  // unless an inspection camera is set, which then owns both the view and (optionally) the fov.
+  const { fov: sceneFov, near, far } = core.projectionOf(scene.id)
+  const fov = override?.fov ?? sceneFov
+  const view = override ? lookAtView(override.eye, override.target) : invertTRS(core.worldMatrixF(camId!))
+  const vp = multiply(new Float32Array(16), perspective(fov, W / H, near, far), view)
+
+  /** Project a world point → screen px + forward depth (clip w). */
+  const project = (x: number, y: number, z: number): { sx: number, sy: number, cw: number, inFront: boolean } => {
+    const cw = vp[3] * x + vp[7] * y + vp[11] * z + vp[15]
+    const cx = vp[0] * x + vp[4] * y + vp[8] * z + vp[12]
+    const cy = vp[1] * x + vp[5] * y + vp[9] * z + vp[13]
+    const inFront = cw > 1e-4
+    if (!inFront) return { sx: 0, sy: 0, cw, inFront }
+    return { sx: ((cx / cw) * 0.5 + 0.5) * W, sy: (1 - ((cy / cw) * 0.5 + 0.5)) * H, cw, inFront }
+  }
+
+  // Collect every entity in the active scene + its overlays (members and their descendants).
+  const isVisible = (id: number): boolean => {
+    for (let cur = id; cur !== 0; cur = core.ent(cur).parent) if (!core.ent(cur).visible) return false
+    return true
+  }
+  const memberScenes: SceneRec[] = [scene, ...scene.overlays.map((id) => core.scenes.get(id)).filter((s): s is SceneRec => !!s)]
+  const seen = new Set<number>()
+  const candidates: number[] = []
+  const gather = (id: number): void => {
+    if (seen.has(id) || !core.entities.has(id)) return
+    seen.add(id)
+    candidates.push(id)
+    for (const c of core.ent(id).children) gather(c)
+  }
+  for (const s of memberScenes) for (const id of s.entities) gather(id)
+
+  const entries: { obj: FrameObject, id: number }[] = []
+  for (const id of candidates) {
+    const e = core.ent(id)
+    if (!isVisible(id)) continue
+    const kind: FrameObject["kind"] | null = e.model ? "model" : (e.mesh && !e.light) ? "mesh" : e.particles ? "particles" : null
+    if (!kind) continue
+
+    // World corners: mesh → its own AABB; model → subtree aggregate; particles → its origin point.
+    let corners: number[][]
+    if (kind === "model") corners = subtreeWorldCorners(core, id)
+    else if (kind === "mesh") corners = meshWorldCorners(core, e)
+    else { const w = core.worldMatrixF(id); corners = [[w[12], w[13], w[14]]] }
+    if (corners.length === 0) continue // a mesh/model with no bounds contributes nothing to the frame
+
+    // World AABB center (representative point for depth).
+    let cxMin = Infinity, cyMin = Infinity, czMin = Infinity, cxMax = -Infinity, cyMax = -Infinity, czMax = -Infinity
+    for (const c of corners) {
+      if (c[0] < cxMin) cxMin = c[0]; if (c[0] > cxMax) cxMax = c[0]
+      if (c[1] < cyMin) cyMin = c[1]; if (c[1] > cyMax) cyMax = c[1]
+      if (c[2] < czMin) czMin = c[2]; if (c[2] > czMax) czMax = c[2]
+    }
+    const centerProj = project((cxMin + cxMax) / 2, (cyMin + cyMax) / 2, (czMin + czMax) / 2)
+
+    // Project corners; the screen bbox comes from the in-front ones.
+    let anyBehind = false, anyFront = false
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity
+    for (const c of corners) {
+      const p = project(c[0], c[1], c[2])
+      if (!p.inFront) { anyBehind = true; continue }
+      anyFront = true
+      if (p.sx < minX) minX = p.sx; if (p.sx > maxX) maxX = p.sx
+      if (p.sy < minY) minY = p.sy; if (p.sy > maxY) maxY = p.sy
+    }
+
+    const obj: FrameObject = { kind, depth: round(centerProj.cw, 3), coverage: 0 }
+    if (e.name) obj.name = e.name
+
+    if (!anyFront) {
+      obj.behindCamera = true
+      entries.push({ obj, id })
+      continue
+    }
+
+    const rectX = minX, rectY = minY, rectW = Math.max(0, maxX - minX), rectH = Math.max(0, maxY - minY)
+    obj.rect = [round(rectX, 1), round(rectY, 1), round(rectW, 1), round(rectH, 1)]
+    if (centerProj.inFront) obj.center = [round(centerProj.sx, 1), round(centerProj.sy, 1)]
+
+    const ix0 = Math.max(0, rectX), iy0 = Math.max(0, rectY)
+    const ix1 = Math.min(W, rectX + rectW), iy1 = Math.min(H, rectY + rectH)
+    const interArea = Math.max(0, ix1 - ix0) * Math.max(0, iy1 - iy0)
+    obj.coverage = round(interArea / (W * H), 4)
+
+    const insideFully = rectX >= 0 && rectY >= 0 && rectX + rectW <= W && rectY + rectH <= H
+    if (interArea === 0) obj.offscreen = true
+    else if (anyBehind || !insideFully) obj.clipped = true
+    entries.push({ obj, id })
+  }
+
+  // Every named object carries its ancestor `path` (root→self) — names are sibling-unique, so
+  // the path is the identity. Unnamed intermediates become `~` (leading ones dropped) so distinct
+  // unnamed parents never merge two same-named children into one path.
+  const namedPath = (id: number): string => {
+    const parts: string[] = []
+    for (let cur = id; cur !== 0; cur = core.ent(cur).parent) parts.unshift(core.ent(cur).name || "~")
+    while (parts.length > 0 && parts[0] === "~") parts.shift()
+    return parts.join("/")
+  }
+  for (const { obj, id } of entries) {
+    if (obj.name) obj.path = namedPath(id)
+  }
+
+  // Prominence sort: coverage desc, then nearest first.
+  entries.sort((a, b) => b.obj.coverage - a.obj.coverage || a.obj.depth - b.obj.depth)
+
+  return {
+    viewport: { width: W, height: H },
+    note: (override ? "INSPECTION camera (not the app's) — " : "") + "screen px, top-left origin; depth is a camera-distance hint, not true occlusion; rects are rest-pose (headless doesn't sample animation)",
+    objects: entries.map((e) => e.obj),
+  }
+}

package/src/core/glbStructure.ts

@@ -0,0 +1,100 @@
+// GL-free GLB (binary glTF 2.0) structure parser for the lite 3D scene core. Reads ONLY the JSON
+// chunk — enough to mirror what gltfio gives the SDK: the node hierarchy (names + local transforms),
+// which nodes carry meshes (and their POSITION accessor bounds), and the animation clip list with
+// durations. No geometry/texture decoding: the core records structure; each backend does its own
+// heavy load (headless records nothing more; the WebGL backend additionally runs OGL's GLTFLoader
+// and attaches drawables to these same entities by glTF node index — both derive from this same JSON,
+// so indices align). Moved here from lecodes-headless/src/g3/glb.ts.
+
+import { composeTRS, identity, type Mat4 } from "./math3d"
+
+export type GlbNode = {
+  name?: string
+  children: number[]
+  /** Local transform (column-major), composed from the node's matrix or TRS. */
+  matrix: Mat4
+  /** Present when the node carries a mesh: POSITION bounds when the accessors declare min/max. */
+  mesh?: { primitives: number, min?: [number, number, number], max?: [number, number, number] }
+  /** The node is a joint of some skin — what a name-bound Animator prefers when names collide. */
+  skinJoint?: true
+}
+
+export type GlbAnimation = { name: string, duration: number }
+
+export type GlbStructure = {
+  nodes: GlbNode[]
+  /** Indices (into `nodes`) of the default scene's root nodes. */
+  roots: number[]
+  animations: GlbAnimation[]
+}
+
+const GLB_MAGIC = 0x46546c67 // 'glTF'
+const CHUNK_JSON = 0x4e4f534a // 'JSON'
+
+/** Parse a GLB buffer's JSON chunk into a node/animation structure. Returns null when the buffer
+ *  isn't a valid GLB (the caller then falls back to an opaque model placeholder). */
+export const parseGlbStructure = (buf: ArrayBuffer): GlbStructure | null => {
+  try {
+    if (buf.byteLength < 20) return null
+    const dv = new DataView(buf)
+    if (dv.getUint32(0, true) !== GLB_MAGIC) return null
+    const chunkLen = dv.getUint32(12, true)
+    if (dv.getUint32(16, true) !== CHUNK_JSON || 20 + chunkLen > buf.byteLength) return null
+    const json = JSON.parse(new TextDecoder("utf-8").decode(new Uint8Array(buf, 20, chunkLen)))
+
+    const accessors: any[] = json.accessors ?? []
+    const meshes: any[] = json.meshes ?? []
+
+    const nodes: GlbNode[] = (json.nodes ?? []).map((n: any) => {
+      let matrix: Mat4
+      if (Array.isArray(n.matrix) && n.matrix.length === 16) {
+        matrix = Float32Array.from(n.matrix) // glTF matrices are column-major, same as ours
+      } else if (n.translation || n.rotation || n.scale) {
+        matrix = composeTRS(n.translation ?? [0, 0, 0], n.rotation ?? [0, 0, 0, 1], n.scale ?? [1, 1, 1])
+      } else {
+        matrix = identity()
+      }
+      const node: GlbNode = { children: n.children ?? [], matrix }
+      if (typeof n.name === "string" && n.name.length > 0) node.name = n.name
+      if (n.mesh != null && meshes[n.mesh]) {
+        const prims: any[] = meshes[n.mesh].primitives ?? []
+        // Union the POSITION bounds over the primitives (accessor min/max are required for POSITION).
+        let min: [number, number, number] | undefined
+        let max: [number, number, number] | undefined
+        for (const p of prims) {
+          const acc = accessors[p.attributes?.POSITION]
+          if (!acc || !Array.isArray(acc.min) || !Array.isArray(acc.max)) continue
+          if (!min || !max) {
+            min = [acc.min[0], acc.min[1], acc.min[2]]
+            max = [acc.max[0], acc.max[1], acc.max[2]]
+          } else {
+            for (let i = 0; i < 3; i++) {
+              min[i] = Math.min(min[i], acc.min[i])
+              max[i] = Math.max(max[i], acc.max[i])
+            }
+          }
+        }
+        node.mesh = { primitives: prims.length, min, max }
+      }
+      return node
+    })
+    for (const skin of json.skins ?? []) for (const j of skin.joints ?? []) if (nodes[j]) nodes[j].skinJoint = true
+
+    // Animation duration = the max end time over the channels' sampler input accessors (min/max are
+    // required on animation inputs by the glTF spec; missing → 0).
+    const animations: GlbAnimation[] = (json.animations ?? []).map((a: any, i: number) => {
+      let duration = 0
+      for (const s of a.samplers ?? []) {
+        const inMax = accessors[s.input]?.max?.[0]
+        if (typeof inMax === "number" && inMax > duration) duration = inMax
+      }
+      return { name: typeof a.name === "string" ? a.name : `animation_${i}`, duration }
+    })
+
+    const sceneIndex = json.scene ?? 0
+    const roots: number[] = json.scenes?.[sceneIndex]?.nodes ?? []
+    return { nodes, roots, animations }
+  } catch {
+    return null
+  }
+}

package/src/core/headlessBridge.ts

@@ -0,0 +1,92 @@
+// The headless backend for the lite 3D scene core (lecodes-headless). Assembles the GL-free
+// SceneCore + the recording method groups + the scene3d serializer into the same handle the old
+// g3/Scene3dRecorder exposed — a drop-in for lecodes-headless/src/headless/index.ts. No GL objects
+// exist here at all: the backend supplies only fresh identity matrices, and every GL hook is absent,
+// so the recorded state IS the core state. Bun-testable with no browser; the animation and physics
+// runtimes (creator-anim / creator-physics wasm) load on demand — a scene that never touches them
+// needs neither.
+
+import { identity } from "./math3d"
+import { createSceneCore, type SceneBackend, type SceneCoreOptions } from "./sceneCore"
+import { createRecording } from "./recording"
+import { serialize } from "./serialize"
+import { sceneWorldBounds } from "./frame"
+import { computeMapView } from "./mapView"
+import { unsupported } from "../gen/unsupported.gen"
+// The global `Handle` the contract's creators return (declared with the tree bridge): without it
+// gl.d.ts reads `Handle` as any and the `satisfies` below cannot see a creator returning a number.
+import type {} from "lecodes-sdk/bridges/tree"
+
+export type HeadlessBridgeOptions = Pick<SceneCoreOptions, "getBuffer" | "getSourceName" | "width" | "height">
+
+export function createHeadlessBridge(opts: HeadlessBridgeOptions) {
+  // Headless backend: no GL. Every entity gets a fresh identity matrix; the core does the rest.
+  const backend: SceneBackend = { allocMatrix: () => identity() }
+
+  const core = createSceneCore(backend, { ...opts, fov: 60 })
+  const recording = createRecording(core)
+
+  const bridge = {
+    ...unsupported,   // the contract's completeness layer (generated) under the core + the recorder
+    backend: "headless",
+    ...core.methods,
+    ...recording.methods,
+    // The OWNED creators (docs/owned.md) hand the SDK a Handle and it puts `_h.id` on the wire. The core
+    // numbers everything and the lite engine keeps no owned records (a drop frees nothing), so the
+    // handle is a plain `{ id }` over the core's id — the wrap creator-gl's generated bridge does.
+    createEntity: (): Handle => ({ id: core.methods.createEntity() }),
+    cloneEntity: (entityId: number): Handle => ({ id: core.methods.cloneEntity(entityId) }),
+    createMaterial: (systemId: number): Handle => ({ id: core.methods.createMaterial(systemId) }),
+    // Never null: a name this engine has no program for draws unlit (buildProgramFor), as it always did.
+    builtinMaterial: (name: string): Handle | null => ({ id: core.methods.createMaterialNamed(name) }),
+    createTexture(systemId: number, onComplete: (texture: Handle, width: number, height: number) => void, onReject: () => void): void {
+      core.methods.createTexture(systemId, (id, width, height) => onComplete({ id }, width, height), onReject)
+    },
+    createTexturePixels: (width: number, height: number, channels: number): Handle => ({ id: core.methods.createTexturePixels(width, height, channels) }),
+    createGlb(systemId: number, onComplete: (root: Handle | null) => void, onReject: () => void): void {
+      core.methods.createGlb(systemId, (root) => onComplete({ id: root }), onReject)
+    },
+  }
+  bridge satisfies typeof _creator
+
+  /** Inspection camera (the headless twin of `lecodes render --desktop --camera/--view`): a fixed
+   *  eye + look-at, a named view auto-fitted to the scene's bounds (bounding sphere + margin — the
+   *  same fit creator-gl's host uses), or null to clear. Returns false for a named view when the
+   *  scene has nothing renderable yet (the override is then cleared). */
+  const setInspectionCamera = (spec: InspectionCameraSpec | null): boolean => {
+    if (spec === null) { core.setCameraOverride(null); return true }
+    if ("eye" in spec) { core.setCameraOverride({ eye: spec.eye, target: spec.target, fov: spec.fov }); return true }
+    const scene = core.scenes.get(core.activeSceneId())
+    const b = scene ? sceneWorldBounds(core, scene) : null
+    if (!b) { core.setCameraOverride(null); return false }
+    const c: [number, number, number] = [(b.min[0] + b.max[0]) / 2, (b.min[1] + b.max[1]) / 2, (b.min[2] + b.max[2]) / 2]
+    const r = Math.max(0.01, 0.5 * Math.hypot(b.max[0] - b.min[0], b.max[1] - b.min[1], b.max[2] - b.min[2]))
+    const fov = spec.fov ?? core.fov
+    const dist = r / Math.sin((fov * 0.5 * Math.PI) / 180) * 1.15
+    const dir = VIEW_DIRS[spec.view]
+    const len = Math.hypot(dir[0], dir[1], dir[2])
+    core.setCameraOverride({ eye: [c[0] + dir[0] / len * dist, c[1] + dir[1] / len * dist, c[2] + dir[2] / len * dist], target: c, fov: spec.fov })
+    return true
+  }
+
+  return {
+    bridge,
+    hasActiveScene: core.hasActiveScene,
+    simulate: core.simulate,
+    serialize: () => serialize(core, core.physicsConfig()),
+    /** Top-down map data of the active scene (mapView.ts) — null when nothing is on the map. */
+    mapView: () => computeMapView(core),
+    setInspectionCamera,
+  }
+}
+
+export type InspectionView = "iso" | "top" | "front" | "side" | "back"
+export type InspectionCameraSpec =
+  | { eye: [number, number, number], target: [number, number, number], fov?: number }
+  | { view: InspectionView, fov?: number }
+// Same directions as the desktop host's applyInspectionCamera (main.cpp) — keep in step.
+const VIEW_DIRS: Record<InspectionView, [number, number, number]> = {
+  iso: [1, 0.8, 1], top: [0, 1, 0], front: [0, 0, 1], side: [1, 0, 0], back: [0, 0, -1],
+}
+
+export type HeadlessBridge = ReturnType<typeof createHeadlessBridge>

package/src/core/mapView.ts

@@ -0,0 +1,195 @@
+// Top-down map serializer for the lite 3D scene core — the data half of `lecodes render --map`.
+// Walks the ACTIVE scene (overlays excluded: they hold viewmodels/HUD 3D, not the world) and
+// projects every visible mesh/model onto the XZ plane as a convex-hull footprint, plus named
+// empties as point markers, the sun direction and the app camera. Pure serializer-level math over
+// core state (like frame.ts) — no bridge methods, no parity impact. The PNG drawing lives in
+// lecodes-headless (headless/mapRender.ts); this side stays GL-free and Bun-testable.
+
+import { getEulerYXZDeg } from "./math3d"
+import { meshWorldCorners } from "./frame"
+import type { Ent, SceneCore, SceneRec } from "./sceneCore"
+
+export type MapObject = {
+  /** Named ancestor path root→self; `__generated` containers (make() output) are elided. */
+  path: string
+  kind: "mesh" | "model"
+  /** Convex-hull footprint on the XZ plane, world units (≥ 3 points). */
+  hull: [number, number][]
+  /** World-Y range [min, max] — height banding / "is this a floor or a wall". */
+  y: [number, number]
+  /** Footprint area in m² (hull shoelace) — the drawer's label/decimation heuristic. */
+  area: number
+  /** Mesh entities: the material's base color when it has one. */
+  color?: string
+}
+
+export type MapPoint = {
+  path: string
+  kind: "empty" | "light" | "particles"
+  x: number
+  z: number
+  y: number
+}
+
+export type MapCamera = { x: number, z: number, y: number, yaw: number }
+
+export type MapView = {
+  /** World XZ extent over everything on the map. */
+  bounds: { min: [number, number], max: [number, number] }
+  objects: MapObject[]
+  points: MapPoint[]
+  camera?: MapCamera
+  /** Sun direction projected to XZ (normalized), when a sun light with a horizontal component exists. */
+  sun?: { dx: number, dz: number }
+}
+
+const round = (v: number, digits = 3): number => {
+  const f = 10 ** digits
+  const r = Math.round(v * f) / f
+  return r === 0 ? 0 : r
+}
+
+/** Monotone-chain convex hull over XZ points (n is tiny — 8 per box, a few hundred per model). */
+const convexHull = (pts: [number, number][]): [number, number][] => {
+  const p = [...pts].sort((a, b) => a[0] - b[0] || a[1] - b[1])
+  if (p.length <= 2) return p
+  const cross = (o: [number, number], a: [number, number], b: [number, number]) =>
+    (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0])
+  const lower: [number, number][] = []
+  for (const pt of p) {
+    while (lower.length >= 2 && cross(lower[lower.length - 2]!, lower[lower.length - 1]!, pt) <= 0) lower.pop()
+    lower.push(pt)
+  }
+  const upper: [number, number][] = []
+  for (let i = p.length - 1; i >= 0; i--) {
+    const pt = p[i]!
+    while (upper.length >= 2 && cross(upper[upper.length - 2]!, upper[upper.length - 1]!, pt) <= 0) upper.pop()
+    upper.push(pt)
+  }
+  lower.pop(); upper.pop()
+  return [...lower, ...upper]
+}
+
+const hullArea = (hull: [number, number][]): number => {
+  let a = 0
+  for (let i = 0; i < hull.length; i++) {
+    const [x1, z1] = hull[i]!
+    const [x2, z2] = hull[(i + 1) % hull.length]!
+    a += x1 * z2 - x2 * z1
+  }
+  return Math.abs(a) / 2
+}
+
+export function computeMapView(core: SceneCore, scene?: SceneRec): MapView | null {
+  const s = scene ?? core.scenes.get(core.activeSceneId())
+  if (!s) return null
+
+  const hex = (packed: number): string => "#" + (packed >>> 0).toString(16).padStart(6, "0")
+  const meshColor = (e: Ent): string | undefined => {
+    const m = core.materials.get(e.materials[0]!)
+    const u = m?.uniforms["color"] ?? m?.uniforms["baseColor"]
+    return u && (u.kind === "rgb" || u.kind === "rgba") ? hex(u.kind === "rgba" ? (u.v >>> 8) : u.v) : undefined
+  }
+
+  const namedPath = (id: number): string => {
+    const parts: string[] = []
+    for (let cur = id; cur !== 0; cur = core.ent(cur).parent) {
+      const n = core.ent(cur).name
+      if (n && n !== "__generated") parts.unshift(n)
+    }
+    return parts.join("/") || "~"
+  }
+
+  const objects: MapObject[] = []
+  const points: MapPoint[] = []
+  let sun: MapView["sun"]
+  const min: [number, number] = [Infinity, Infinity]
+  const max: [number, number] = [-Infinity, -Infinity]
+  const grow = (x: number, z: number): void => {
+    if (x < min[0]) min[0] = x
+    if (z < min[1]) min[1] = z
+    if (x > max[0]) max[0] = x
+    if (z > max[1]) max[1] = z
+  }
+
+  const cornersToObject = (id: number, kind: "mesh" | "model", corners: number[][], color?: string): void => {
+    if (corners.length === 0) return
+    let yMin = Infinity, yMax = -Infinity
+    const xz: [number, number][] = []
+    for (const c of corners) {
+      xz.push([c[0]!, c[2]!])
+      if (c[1]! < yMin) yMin = c[1]!
+      if (c[1]! > yMax) yMax = c[1]!
+      grow(c[0]!, c[2]!)
+    }
+    const hull = convexHull(xz).map(([x, z]) => [round(x), round(z)] as [number, number])
+    if (hull.length < 3) return
+    objects.push({
+      path: namedPath(id), kind, hull, y: [round(yMin), round(yMax)],
+      area: round(hullArea(hull), 2), ...(color !== undefined && { color }),
+    })
+  }
+
+  /** All mesh corners of a model subtree (bones and empties inside contribute nothing). */
+  const subtreeCorners = (id: number): number[][] => {
+    const acc: number[][] = []
+    const walk = (nid: number): void => {
+      const e = core.entities.get(nid)
+      if (!e || !e.visible) return
+      acc.push(...meshWorldCorners(core, e))
+      for (const c of e.children) walk(c)
+    }
+    walk(id)
+    return acc
+  }
+
+  const seen = new Set<number>()
+  const visit = (id: number): void => {
+    if (seen.has(id) || !core.entities.has(id)) return
+    seen.add(id)
+    const e = core.ent(id)
+    if (!e.visible) return
+    if (e.model) {
+      cornersToObject(id, "model", subtreeCorners(id))
+      return // a model's internals belong to the model — no per-bone points/objects
+    }
+    if (e.light) {
+      const d = e.light.direction
+      if (d && (Math.abs(d[0]!) > 1e-4 || Math.abs(d[2]!) > 1e-4)) {
+        const len = Math.hypot(d[0]!, d[2]!)
+        sun ??= { dx: round(d[0]! / len), dz: round(d[2]! / len) }
+      } else {
+        const w = core.worldMatrixF(id)
+        points.push({ path: namedPath(id), kind: "light", x: round(w[12]!), z: round(w[14]!), y: round(w[13]!) })
+      }
+    } else if (e.mesh) {
+      cornersToObject(id, "mesh", meshWorldCorners(core, e), meshColor(e))
+    } else if (e.particles) {
+      const w = core.worldMatrixF(id)
+      points.push({ path: namedPath(id), kind: "particles", x: round(w[12]!), z: round(w[14]!), y: round(w[13]!) })
+    } else if (e.name && e.name !== "__generated" && id !== s.camera) {
+      // a NAMED empty is intent (a spawn, a waypoint, a folder) — put it on the map
+      const w = core.worldMatrixF(id)
+      const p: MapPoint = { path: namedPath(id), kind: "empty", x: round(w[12]!), z: round(w[14]!), y: round(w[13]!) }
+      points.push(p)
+      grow(p.x, p.z)
+    }
+    for (const c of e.children) visit(c)
+  }
+  for (const id of s.entities) visit(id)
+
+  let camera: MapCamera | undefined
+  if (s.camera !== undefined && core.entities.has(s.camera)) {
+    const w = core.worldMatrixF(s.camera)
+    const yaw = getEulerYXZDeg(w)[1]!
+    camera = { x: round(w[12]!), z: round(w[14]!), y: round(w[13]!), yaw: Math.round(yaw * 100) / 100 }
+  }
+
+  if (min[0] === Infinity) return null
+  return {
+    bounds: { min: [round(min[0]), round(min[1])], max: [round(max[0]), round(max[1])] },
+    objects, points,
+    ...(camera && { camera }),
+    ...(sun && { sun }),
+  }
+}