@solidrt/3d 0.0.60 → 0.0.61

package/src/scene.ts

@@ -36,9 +36,9 @@
 // and pointer subsystems are scene-shadows.ts / scene-pointer.ts,
 // built here with the scene's seams as their deps.
 
-import { addDraw, createCubeDrawTarget, createDrawTarget, depthTexture, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, renderTarget, setDrawBuffers, setDrawOrder, setDrawParams, setDrawRange, setDrawTextures, setTargetParams, setTargetRect, setTargetSize, setTargetTextures } from "@solidrt/core/gpu"
+import { addDraw, createCubeDrawTarget, createDrawTarget, depthTexture, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, renderTarget, setDrawBuffers, setDrawParams, setDrawRange, setDrawTextures, setTargetParams, setTargetRect, setTargetSize, setTargetTextures } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
-import type { Impact as CoreImpact, NodeId, QueryFilter } from "flux:spatial"
+import type { BindDrawOptions, Impact as CoreImpact, NodeId, QueryFilter } from "flux:spatial"
 import type { BufferId, DrawId, FilterMode, ProgramId, RenderPipelineId, ShaderParams, TextureBindings, TextureId, WrapMode } from "@solidrt/core/gpu"
 import { getOwner, onCleanup } from "@solidrt/core"
 import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEvent } from "@solidrt/core"
@@ -59,8 +59,7 @@ import type { BloomOptions, ResolveInput, ResolveOptions, ResolveRecord } from "
 import { createEnvironmentPlaceholder, createPrefilter, bufferFormat } from "./environment.ts"
 import type { Prefilter } from "./environment.ts"
 import type { Material } from "./material.ts"
-import { orderEntries } from "./order.ts"
-import { activateMorph, fillTransform, freeLeaving, leaveScene, makeNode, setTransition, worldInto } from "./node.ts"
+import { activateMorph, fillTransform, freeLeaving, leaveScene, makeNode, setTransition } from "./node.ts"
 import type { SceneHooks, SceneNode, ScenePointerListener } from "./node.ts"
 import { checkInstancePairing, checkMask, instanceBinding, localBounds, publishRecords } from "./mesh.ts"
 import type { InstancedMesh, InstanceNode, Mesh } from "./mesh.ts"
@@ -117,9 +116,6 @@ function packVolume(volume: Volume, site: string): "capsule" | "box" {
 
 // pick()'s camera-ray scratch.
 let pickDir: Vec3 = [0, 0, 0]
-// worldInto's out for the light/center readbacks below; nothing here
-// outlives a single call.
-let worldScratch = mat4()
 
 /** One picking intersection, Three's intersect result: the mesh, the
  * camera-ray distance in world units, the world-space point, and for a
@@ -410,6 +406,22 @@ export type ToneMapping = "none" | "aces" | "agx" | "neutral"
 
 // The uToneMapping value per mode; the RESOLVE set branches on it.
 const TONE_MAPPING_CODE: Record<ToneMapping, number> = { none: 0, aces: 1, agx: 2, neutral: 3 }
+// The core's draw queues (flux:spatial bindDraw), drawn in this order.
+const QUEUE_BACKGROUND = 0
+const QUEUE_OPAQUE = 1
+const QUEUE_CUTOUT = 2
+const QUEUE_TRANSPARENT = 3
+let drawQueue = (m: Material): number =>
+  m.transparent === true ? QUEUE_TRANSPARENT : m.cutout === true ? QUEUE_CUTOUT : QUEUE_OPAQUE
+// A mesh entry's draw sink: what the core writes into it and where it
+// sorts, from the material the entry draws with.
+let drawBinding = (material: Material, mesh: Mesh, inst: { count: number } | null): BindDrawOptions => ({
+  normal: material.normalMatrix === true,
+  count: inst !== null ? inst.count : 1,
+  fade: material.lodFade === true,
+  queue: drawQueue(material),
+  renderOrder: mesh.renderOrder,
+})
 
 /** The RESOLVE set's params for a resolve pass of your own (an app-owned
  * atlas tiled views render into, resolved through `resolveFragment` from
@@ -575,11 +587,24 @@ export type ViewHandle = {
   /** Replace the view's layer mask (bitmask): entries for newly admitted
    * meshes attach, masked-out ones detach. */
   setLayers(mask: number): void
+  /** The level a LOD group draws in this view (scene.lodLevel through
+   * the view's camera). */
+  lodLevel(group: SceneNode): number | null
   /** The camera ray through one of the VIEW's pixels, hits nearest first:
    * scene.pick through this view's camera and size, so a mesh under a
    * minimap is picked where the minimap shows it (the scene's query
    * filters apply: visibility, the view's own layer mask is not one). */
   pick(x: number, y: number): Hit[]
+  /** scene.project through this view's camera and size: a world point
+   * to VIEW pixels. */
+  project(point: Vec3): { x: number; y: number; w: number } | null
+  /** scene.unproject through this view's camera and size. */
+  unproject(x: number, y: number, w: number, out?: Vec3): Vec3
+  /** scene.screenRay through this view's camera and size. */
+  screenRay(x: number, y: number): ScreenRay
+  /** Exactly scene.raycast: the query is the scene's, a view has no
+   * camera in it. */
+  raycast(origin: Vec3, direction: Vec3, opts?: QueryOptions): Hit[]
   /** Element pointer handlers for the element showing `texture`: the
    * scene's dispatch with THIS VIEW as the root of the walk - nodes get
    * their ordinary handlers, picked through the view's camera, the
@@ -807,6 +832,13 @@ export type Scene = {
    * measured projected size, for the scene, its views and its shadow
    * tiles. Below 1 switches to far levels sooner. */
   setLodBias(bias: number): void
+  /** The level a LOD group draws in the scene's own render (the thing to
+   * read while tuning thresholds): the index into its levels, nearest
+   * first, `levels.length` when culled past the last one, null before
+   * the scene measured it. Views read their own through view.lodLevel;
+   * an InstancedLod picks per instance, so this is its group's own
+   * pick, not any instance's. Throws for a node with no levels. */
+  lodLevel(group: SceneNode): number | null
   /**
    * Project a world point to scene pixels: origin top-left, y down - the
    * output texture's own coordinate space, ready for overlay layout (HUD
@@ -1008,6 +1040,14 @@ function checkLayout(material: Material, geometry: Geometry, what: string): void
   }
 }
 
+// The debug name a mesh's draw entries report in the resource inventory
+// (`/gpu`): its geometry's label (a model part's name, a generator's) -
+// the same name whether the part is a plain mesh or a population - else a
+// population's own label, else none.
+function drawLabel(mesh: Mesh): string | undefined {
+  return mesh.geometry.label ?? mesh._instances?.label
+}
+
 // The index range a mesh's entries draw: its own (setDrawRange) or the
 // whole index list.
 function meshRange(mesh: Mesh): { firstIndex: number; indexCount: number } {
@@ -1116,6 +1156,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     label,
     autoFree: false,
   })
+  spatial.setDrawSort(texture, true)
   let resolve = makeResolve(texture, width, height, opts?.resolve, { filter: opts?.filter, wrap: opts?.wrap }, label)
   let disposed = false
   let scheduled = false
@@ -1185,12 +1226,13 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   }
 
   // Live meshes (those holding a draw entry) in add order; the background
-  // entry never joins this list. Draw order is derived from it by
-  // orderEntries (order.ts) whenever orderDirty. Camera moves and
-  // transparent-mesh moves only dirty the order when two or more transparent
-  // meshes exist - fewer cannot change relative order.
+  // entry never joins this list. Draw order is the core's (setDrawSort on
+  // every sorted target): each mesh's bind carries its sort key (setDrawKey
+  // re-keys on a renderOrder change), and a flush that moved a node,
+  // changed a binding or moved a target's view re-keys that target's
+  // entries.
   let meshes: Mesh[] = []
-  let transparentCount = 0
+  let keyDraw = (mesh: Mesh) => spatial.setDrawKey(mesh._node!, drawQueue(mesh.material), mesh.renderOrder)
   // Attached lights in attach order (= light index); any change to the
   // set, a light's fields, or a light's world matrix rewrites the shared
   // light params at the end of the sync - one write, however many meshes.
@@ -1319,60 +1361,34 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     // matrix too: rewrite the whole array once.
     shadowSys.markMatricesDirty()
   }
-  let orderDirty = false
-  // The order last handed to the engine: a resort that lands on the same
-  // permutation (the common case under a moving camera) issues nothing.
-  let lastOrder: DrawId[] = []
   // `skybox`: the entry runs the library's cube-map fragment (its params
   // and textures are rewritable in place); false = app GLSL.
   // `sky` is the skybox source (its cube and knobs) for the bake, null
   // for a GLSL background.
   // `entries` is the background's draw entry per target that draws it:
-  // the scene's own and every sky view's (a reflection probe), each first
-  // in its list.
+  // the scene's own and every sky view's (a reflection probe). Each is
+  // bound to the scene root in the background queue, so the core's sort
+  // keeps it first and its visibility follows the root's; the root's
+  // matrix is not written (the program has no uModel).
   let background: { pipeline: RenderPipelineId; program: ProgramId; sky: SkyboxOptions | null; entries: Map<TextureId, DrawId> } | null = null
-  // Add the current background to `target` before entry `before` (its
-  // first mesh entry; undefined appends, right for a target with none yet).
-  let attachBackground = (target: TextureId, before: DrawId | undefined) => {
+  let attachBackground = (target: TextureId) => {
     if (background === null) return
     let sky = background.sky
     let params = sky === null ? null : skyboxParams(sky, "scene.setBackground")
     let textures = sky === null ? undefined : { uSky: sky.cube }
-    background.entries.set(target, addDraw(target, background.pipeline, params, { vertexCount: 3, before, textures }))
+    let entry = addDraw(target, background.pipeline, params, { vertexCount: 3, textures, instanceCount: 0 })
+    background.entries.set(target, entry)
+    spatial.bindDraw(root._node!, target, entry, { params: false, queue: QUEUE_BACKGROUND })
+  }
+  let detachBackground = (target: TextureId, entry: DrawId) => {
+    if (root._node !== null) spatial.unbindDraw(root._node, target)
+    removeDraw(target, entry)
   }
   // The environment cube bound as uEnv on every receiving target (the
   // light rewrite seeds it on new targets); null binds the placeholder,
   // the scene's own 1x1 black cube.
   let environment: TextureId | null = null
   let envPlaceholder = createEnvironmentPlaceholder(label + "-env-none")
-  let sortEntries = () => {
-    orderDirty = false
-    let order = orderEntries(meshes, camera.view, background?.entries.get(texture))
-    if (order.length === lastOrder.length && order.every((id, i) => id === lastOrder[i])) return
-    lastOrder = order
-    setDrawOrder(texture, order)
-  }
-
-  // The transparent sort keys: each transparent mesh's local-bounds
-  // center carried through its world matrix (read from the core), at
-  // sort time only - opaque meshes never need one.
-  let refreshCenters = () => {
-    if (transparentCount < 2) return
-    for (let mesh of meshes) {
-      if (!mesh._transparent || mesh._node === null) continue
-      let b = localBounds(mesh)
-      let m = worldInto(worldScratch, mesh)
-      let cx = 0, cy = 0, cz = 0
-      if (b !== null) {
-        cx = (b[0]! + b[3]!) / 2
-        cy = (b[1]! + b[4]!) / 2
-        cz = (b[2]! + b[5]!) / 2
-      }
-      mesh._center[0] = m[0] * cx + m[4] * cy + m[8] * cz + m[12]
-      mesh._center[1] = m[1] * cx + m[5] * cy + m[9] * cz + m[13]
-      mesh._center[2] = m[2] * cx + m[6] * cy + m[10] * cz + m[14]
-    }
-  }
   let camera = makeCamera()
   let clip: Vec4 = [0, 0, 0, 0]
   let pickOrigin: Vec3 = [0, 0, 0]
@@ -1417,6 +1433,26 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     pickDir[2] = -v[10]
   }
   let pixelRay = (x: number, y: number): void => pixelRayOf(camera, width, height, x, y)
+  // project() for any camera over a tw x th target (the scene's, a view's).
+  let projectWith = (cam: Camera, tw: number, th: number, point: Vec3): { x: number; y: number; w: number } | null => {
+    ensureCamera(cam, tw, th)
+    transformPoint(clip, cam.viewProj, point)
+    let w = clip[3]
+    if (w < 1e-6) return null
+    // perspective() bakes the y-down clip flip, so NDC maps straight to
+    // top-left-origin pixels with no negation here.
+    let x = ((clip[0] / w) * 0.5 + 0.5) * tw
+    let y = ((clip[1] / w) * 0.5 + 0.5) * th
+    if (cam.ortho !== null) {
+      // An orthographic clip w is 1 everywhere (every point projects, the
+      // divides above are no-ops) and carries no depth, so `w` reports
+      // the camera-forward distance off the view row instead - the same
+      // meaning as the perspective clip w, and unproject's exact input.
+      let v = cam.view
+      w = -(v[2] * point[0] + v[6] * point[1] + v[10] * point[2] + v[14])
+    }
+    return { x, y, w }
+  }
 
   // Views (scene.createView): more targets drawing the same meshes from
   // their own cameras. A view holds one entry per mesh in its target,
@@ -1457,11 +1493,6 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     ownNames: Set<string>
     camera: Camera
     entries: Map<Mesh, DrawId>
-    orderDirty: boolean
-    lastOrder: DrawId[]
-    /** A shadow tile measures LOD by the SCENE camera: set once at
-     * creation, then on every scene camera move. */
-    lodViewSet: boolean
     /** A reflection probe's target is a cube draw target of this face
      * edge, rendered face by face through probe.update(); null for a
      * 2D view. */
@@ -1515,18 +1546,17 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       ...meshRange(mesh),
       textures: entryTextures(mesh.material, mesh, morph),
       instanceCount: 0,
+      label: drawLabel(mesh),
     })
     // The core turns the entry on (with the world matrix) at the next
     // flush, and off again whenever the node or an ancestor hides.
-    spatial.bindDraw(mesh._node!, texture, mesh._entry, mesh.material.normalMatrix === true, inst !== null ? inst.count : 1, mesh.material.lodFade === true)
-    orderDirty = true
+    spatial.bindDraw(mesh._node!, texture, mesh._entry, drawBinding(mesh.material, mesh, inst))
   }
   let detachScene = (mesh: Mesh) => {
     if (mesh._entry === null) return
     if (mesh._node !== null) spatial.unbindDraw(mesh._node, texture)
     if (!disposed) removeDraw(texture, mesh._entry)
     mesh._entry = null
-    orderDirty = true
   }
   // The material a view draws a mesh with: a shadow view lets a caster's
   // material pick its own depth variant (its cull side, cutout, skinning
@@ -1568,10 +1598,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       ...meshRange(mesh),
       textures: entryTextures(material, mesh, morph),
       instanceCount: 0,
+      label: drawLabel(mesh),
     })
-    spatial.bindDraw(mesh._node!, v.texture, entry, material.normalMatrix === true, inst !== null ? inst.count : 1, material.lodFade === true)
+    spatial.bindDraw(mesh._node!, v.texture, entry, drawBinding(material, mesh, inst))
     v.entries.set(mesh, entry)
-    v.orderDirty = true
   }
   let detachView = (v: ViewRecord, mesh: Mesh) => {
     v.skipped.delete(mesh)
@@ -1580,25 +1610,15 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     v.entries.delete(mesh)
     if (mesh._node !== null) spatial.unbindDraw(mesh._node, v.texture)
     if (!v.disposed) removeDraw(v.texture, entry)
-    v.orderDirty = true
-  }
-  let sortView = (v: ViewRecord) => {
-    v.orderDirty = false
-    if (v.override !== null) return
-    let order = orderEntries(meshes, v.camera.view, background?.entries.get(v.texture), m => v.entries.get(m as Mesh) ?? null)
-    if (order.length === v.lastOrder.length && order.every((id, i) => id === v.lastOrder[i])) return
-    v.lastOrder = order
-    setDrawOrder(v.texture, order)
   }
   let disposeView = (v: ViewRecord) => {
     if (v.disposed) return
     v.disposed = true
-    background?.entries.delete(v.texture)
+    if (background?.entries.delete(v.texture) && root._node !== null) spatial.unbindDraw(root._node, v.texture)
     for (let mesh of v.entries.keys()) if (mesh._node !== null) spatial.unbindDraw(mesh._node, v.texture)
     v.entries.clear()
     for (let light of lights) if (light.type === "directional" && light._node !== null) spatial.unbindSlot(light._node, v.texture)
-    spatial.setFrustum(v.texture, null)
-    spatial.setLodView(v.texture, null)
+    spatial.setView(v.texture, null)
     // Drain the zeroed direction slots while the target still exists.
     spatial.flush()
     if (v.resolve !== null) disposeResolve(v.resolve)
@@ -1670,6 +1690,13 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
             x: vopts.x,
             y: vopts.y,
           })
+    // An override view (a shadow tile, a depth or id pass) draws in add
+    // order; every other view sorts like the scene.
+    if (override === null) spatial.setDrawSort(buffer, true)
+    // A shadow tile measures LOD by the scene camera; every other view
+    // by its own, under the scene's bias.
+    if (shadowFilter !== null) spatial.setLodReference(buffer, texture)
+    else spatial.setLodBias(buffer, lodBias)
     let v: ViewRecord = {
       texture: buffer,
       // A shadow view is depth only, a probe's faces are read as a cube,
@@ -1690,18 +1717,13 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       ownNames: new Set(),
       camera: makeCamera(),
       entries: new Map(),
-      orderDirty: true,
-      lastOrder: [],
-      lodViewSet: false,
       cube,
       probeCube: null,
       sky,
       disposed: false,
     }
     views.push(v)
-    // The background goes in first (no mesh entry exists yet), where every
-    // later sort keeps it.
-    if (sky) attachBackground(v.texture, undefined)
+    if (sky) attachBackground(v.texture)
     // The light rewrite seeds the shadow set (maps, casts, biases,
     // matrices) on the new target too.
     lightsDirty = true
@@ -1737,36 +1759,25 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     schedule: () => hooks._schedule(),
   })
 
-  // A camera write is also the target's frustum for the core's culling:
-  // the scene's own, every view's, every shadow tile's - set before the
-  // flush below, which switches the entries outside it off. Cube face
-  // renders (probes) set no frustum: six cameras share one target and the
-  // core would only ever see the last.
-  let frustumScratch = new Float32Array(16)
-  let setFrustum = (target: TextureId, cam: Camera) => {
-    frustumScratch.set(cam.viewProj)
-    spatial.setFrustum(target, frustumScratch)
+  // A camera write is also the target's view for the core: what it culls
+  // by, measures projected size with (eye, forward, focal, ortho) and
+  // sorts depth against - set before the flush below, which switches the
+  // entries outside it off. The scene and each view measure by their own
+  // camera; a shadow tile by the SCENE camera, through the LOD reference
+  // set at its creation, so a caster draws the level the camera sees and
+  // its shadow matches. Cube face renders (probes) set it per face: six
+  // cameras share one target, so each face sets its view and flushes
+  // before it renders.
+  let viewScratch = new Float32Array(16)
+  let projScratch = new Float32Array(16)
+  let setView = (target: TextureId, cam: Camera) => {
+    viewScratch.set(cam.view)
+    projScratch.set(cam.proj)
+    spatial.setView(target, viewScratch, projScratch)
   }
-  // A camera write is also the target's LOD view - eye, vertical focal
-  // factor (the magnitude of proj[5] under either projection: the
-  // projections bake in a y-down clip flip, so the element is negative),
-  // the ortho flag and the scene's bias - what the core measures
-  // projected size with. The scene and each view measure by their own
-  // camera; a shadow tile by the SCENE camera, so a caster draws the
-  // level the camera sees and its shadow matches.
   let lodBias = opts?.lodBias ?? 1
   if (!(lodBias > 0 && Number.isFinite(lodBias))) throw new Error("createScene: lodBias must be a positive number, got " + lodBias)
-  let lodBiasDirty = false
-  let lodScratch = new Float32Array(6)
-  let setLodView = (target: TextureId, cam: Camera) => {
-    lodScratch[0] = cam.eye[0]
-    lodScratch[1] = cam.eye[1]
-    lodScratch[2] = cam.eye[2]
-    lodScratch[3] = Math.abs(cam.proj[5]!)
-    lodScratch[4] = cam.ortho !== null ? 1 : 0
-    lodScratch[5] = lodBias
-    spatial.setLodView(target, lodScratch)
-  }
+  spatial.setLodBias(texture, lodBias)
   let sync = () => {
     scheduled = false
     if (disposed) return
@@ -1802,37 +1813,20 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     if (budgetError === null) budgetError = shadowError
     ensureCamera(camera, width, height)
     let cameraMoved = camera.pending
-    let biasChanged = lodBiasDirty
-    lodBiasDirty = false
     if (camera.pending) {
       camera.pending = false
       setTargetParams(texture, cameraParams(camera))
-      setFrustum(texture, camera)
-      if (transparentCount > 1) orderDirty = true
+      setView(texture, camera)
     }
-    if (cameraMoved || biasChanged) setLodView(texture, camera)
     shadowSys.placeCameras(cameraMoved)
     for (let v of views) {
       ensureCamera(v.camera, v.width, v.height)
-      let viewMoved = v.camera.pending
-      if (viewMoved) {
+      if (v.camera.pending) {
         v.camera.pending = false
         setTargetParams(v.texture, cameraParams(v.camera))
-        setFrustum(v.texture, v.camera)
-        if (transparentCount > 1) v.orderDirty = true
+        setView(v.texture, v.camera)
         if (v.shadowFilter !== null) shadowSys.markMatricesDirty()
       }
-      // Probe faces measure nothing (six cameras, one target), like their
-      // frustum.
-      if (v.cube !== null) continue
-      if (v.shadowFilter !== null) {
-        if (cameraMoved || biasChanged || !v.lodViewSet) {
-          v.lodViewSet = true
-          setLodView(v.texture, camera)
-        }
-      } else if (viewMoved || biasChanged) {
-        setLodView(v.texture, v.camera)
-      }
     }
     // Light bookkeeping first, so a fresh direction-slot bind is seeded
     // by the flush below in the same sync.
@@ -1857,21 +1851,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     // uModel/uNormal, visibility switch and direction slots.
     spatial.flush()
     if (moved.length > 0) {
-      // Which meshes moved is the core's knowledge now, so any move with
-      // two or more transparent meshes re-sorts (sortEntries issues nothing
-      // when the permutation is unchanged).
-      if (transparentCount > 1) {
-        orderDirty = true
-        for (let v of views) v.orderDirty = true
-      }
       for (let n of moved) n._moved = false
       moved.length = 0
     }
-    // The sort keys are world-space and camera-independent: refreshed once
-    // for every sort this sync.
-    if (orderDirty || views.some(v => v.orderDirty)) refreshCenters()
-    if (orderDirty) sortEntries()
-    for (let v of views) if (v.orderDirty) sortView(v)
     if (budgetError !== null) {
       if (opts?.onError !== undefined) opts.onError(budgetError)
       else throw budgetError
@@ -1957,6 +1939,15 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         )
       }
       if (inst !== null) checkInstancePairing(mesh.material, inst, "Mesh material")
+      // An anchored population's records are relative to the anchor, so
+      // it must be an ancestor (the core's contract: an anchor move then
+      // restages every record); anything else binds records that never
+      // follow it - errors here, at add().
+      if (inst !== null && inst.anchor !== null) {
+        let p: SceneNode | null = mesh.parent
+        while (p !== null && p !== inst.anchor) p = p.parent
+        if (p === null) throw new Error("An instanced mesh's anchor must be one of its ancestors when it is added to a scene")
+      }
       let bufs = acquireGeometryBuffers(mesh.geometry)
       mesh._buffers = bufs
       attachScene(mesh)
@@ -1966,20 +1957,27 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       if (inst !== null && inst.streams.some(s => s.dirty !== null)) recordsDirty.add(mesh)
       // Picking: an ordinary mesh's node carries its geometry's shape,
       // which is its box in the core index (following every
-      // updateVertices) and its triangle narrowphase. A populated mesh is
-      // box-only by its explicit population bounds (its instances are the
-      // leaves that pick, each with the shape; a record mesh's records are
-      // opaque, so without explicit bounds it is not picked at all), as is
-      // a sprite by the unit box (its triangles lie wherever the camera
-      // is, not where the geometry says).
+      // updateVertices) and its triangle narrowphase. An instanced mesh's
+      // instances are the leaves that pick, each with the shape, so its
+      // own node stays OUT of the index: explicit population bounds are
+      // its cull box only (else the cull group of its instances). A
+      // record mesh's records are opaque, so its explicit bounds are its
+      // box in the index (without them it is not picked at all), as is a
+      // sprite's unit box (its triangles lie wherever the camera is, not
+      // where the geometry says).
       if (inst === null && !mesh._sprite) spatial.setShape(mesh._node!, bufs.shape)
+      else if (inst !== null && inst.nodes !== null) spatial.setCullBounds(mesh._node!, inst.bounds)
       else spatial.setBounds(mesh._node!, localBounds(mesh))
       // A rebuilt entry (setGeometry) re-shapes the live instances to the
       // new geometry; their record bindings are untouched. On a first
-      // entry none has a core node yet - they enter after the mesh.
+      // entry none has a core node yet - they enter after the mesh -
+      // except under an anchor, where an instance in an earlier branch
+      // of the anchor's subtree is already in and waiting to be bound.
       if (inst !== null && inst.nodes !== null) {
         for (let n of inst.nodes.slots) {
-          if (n !== null && n._node !== null) spatial.setShape(n._node, bufs.shape)
+          if (n === null || n._node === null) continue
+          if (inst.anchor !== null && !byNode.has(n._node)) this._attachInstance(n)
+          else spatial.setShape(n._node, bufs.shape)
         }
       }
       // Culling: the gate and margin only when off the defaults, and a
@@ -1997,9 +1995,6 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       if (inst !== null && inst.nodes !== null && inst.bounds === null) groupDirty.add(mesh as InstancedMesh)
       byNode.set(mesh._node!, mesh)
       meshes.push(mesh)
-      mesh._transparent = mesh.material.transparent === true
-      if (mesh._transparent) transparentCount++
-      orderDirty = true
       this._schedule()
     },
     _detach(mesh) {
@@ -2010,15 +2005,14 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         detachScene(mesh)
         if (mesh._node !== null) {
           spatial.setShape(mesh._node, null)
-          spatial.setBounds(mesh._node, null)
+          if (mesh._instances !== null && mesh._instances.nodes !== null) spatial.setCullBounds(mesh._node, null)
+          else spatial.setBounds(mesh._node, null)
           byNode.delete(mesh._node)
         }
         releaseGeometryBuffers(mesh._buffers)
         mesh._buffers = null
         let i = meshes.indexOf(mesh)
         if (i >= 0) meshes.splice(i, 1)
-        if (mesh._transparent) transparentCount--
-        orderDirty = true
       }
       mesh._entry = null
     },
@@ -2029,17 +2023,23 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       // geometry buffers and core node are live - a mesh masked out of
       // the scene included, whose instances still pick.
       if (mesh === null || mesh._buffers === null || mesh._node === null || instance._node === null) return
+      // A population with an anchor may enter AFTER an instance living
+      // elsewhere in the anchor's subtree (a later sibling branch); the
+      // mesh's own attach then binds the instances it finds waiting.
+      let anchor = (mesh._instances.anchor ?? mesh)._node
+      if (anchor === null || byNode.has(instance._node)) return
       spatial.setShape(instance._node, mesh._buffers.shape)
       spatial.setLayers(instance._node, mesh.layers)
-      // The record is the instance's placement inside the mesh (the mesh
-      // node is the anchor), staged by the core at the next flush.
-      // One buffer per LOD level of an instanced LOD (the population is
-      // the group and the anchor, its levels its children at identity).
+      // The record is the instance's placement relative to the anchor -
+      // the mesh node itself, or the ancestor the mesh sits under at
+      // identity - staged by the core at the next flush. One buffer per
+      // LOD level of an instanced LOD (the population is the group and
+      // the anchor, its levels its children at identity).
       let levels = mesh._instances.levels
       instanceBuffers.length = 0
       if (levels === null) instanceBuffers.push(mesh._instances.matrix)
       else for (let l of levels) instanceBuffers.push(l._instances.matrix)
-      spatial.bindMatrixRecord(instance._node, instanceBuffers, instance._slot, mesh._node)
+      spatial.bindMatrixRecord(instance._node, instanceBuffers, instance._slot, anchor)
       // A morphing population: the instance's register takes its slot's
       // row now (a recycled slot's row is overwritten, not inherited).
       if (mesh._instances.morph !== null) activateMorph(instance)
@@ -2124,9 +2124,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       recordsDirty.add(mesh)
       this._schedule()
     },
-    _reorder() {
-      orderDirty = true
-      for (let v of views) v.orderDirty = true
+    _reorder(mesh) {
+      if (disposed || mesh._buffers === null || mesh._node === null) return
+      keyDraw(mesh)
       this._schedule()
     },
     _moved(node) {
@@ -2234,9 +2234,15 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       if (!(bias > 0 && Number.isFinite(bias))) throw new Error("scene.setLodBias: bias must be a positive number, got " + bias)
       if (disposed || bias === lodBias) return
       lodBias = bias
-      lodBiasDirty = true
+      spatial.setLodBias(texture, bias)
+      // Shadow tiles take the scene's through their LOD reference.
+      for (let v of views) if (v.shadowFilter === null && !v.disposed) spatial.setLodBias(v.texture, bias)
       hooks._schedule()
     },
+    lodLevel(group) {
+      if (disposed || group._node === null) return null
+      return spatial.lodLevel(group._node, texture)
+    },
     setLayers(mask) {
       checkMask(mask, "scene.setLayers")
       if (disposed || sceneMask === mask) return
@@ -2273,7 +2279,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       let sky = source === null || typeof source === "string" ? null : source
       if (sky !== null) skyboxParams(sky, "scene.setBackground")
       if (background !== null) {
-        for (let [target, entry] of background.entries) removeDraw(target, entry)
+        for (let [target, entry] of background.entries) detachBackground(target, entry)
         destroyRenderPipeline(background.pipeline)
         destroyProgram(background.program)
         background = null
@@ -2281,11 +2287,8 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       if (source === null) return
       let built = sky === null ? backgroundPipeline(source as string, label + "-background") : backgroundPipeline(SKYBOX_FRAGMENT, label + "-skybox")
       background = { pipeline: built.pipeline, program: built.program, sky, entries: new Map() }
-      // First in list order on every target that draws it: inserted before
-      // the first mesh ENTRY (a layers-masked mesh has none), and every
-      // later sort keeps it there.
-      attachBackground(texture, meshes.find(m => m._entry !== null)?._entry ?? undefined)
-      for (let v of views) if (v.sky && !v.disposed) attachBackground(v.texture, v.lastOrder[0] ?? v.entries.values().next().value)
+      attachBackground(texture)
+      for (let v of views) if (v.sky && !v.disposed) attachBackground(v.texture)
     },
     setEnvironment(env) {
       if (disposed) return
@@ -2318,23 +2321,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       hooks._schedule()
     },
     project(point) {
-      ensureCamera(camera, width, height)
-      transformPoint(clip, camera.viewProj, point)
-      let w = clip[3]
-      if (w < 1e-6) return null
-      // perspective() bakes the y-down clip flip, so NDC maps straight to
-      // top-left-origin pixels with no negation here.
-      let x = ((clip[0] / w) * 0.5 + 0.5) * width
-      let y = ((clip[1] / w) * 0.5 + 0.5) * height
-      if (camera.ortho !== null) {
-        // An orthographic clip w is 1 everywhere (every point projects, the
-        // divides above are no-ops) and carries no depth, so `w` reports
-        // the camera-forward distance off the view row instead - the same
-        // meaning as the perspective clip w, and unproject's exact input.
-        let v = camera.view
-        w = -(v[2] * point[0] + v[6] * point[1] + v[10] * point[2] + v[14])
-      }
-      return { x, y, w }
+      return projectWith(camera, width, height, point)
     },
     viewProj(out) {
       ensureCamera(camera, width, height)
@@ -2482,11 +2469,35 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
           }
           hooks._schedule()
         },
+        lodLevel(group) {
+          if (v.disposed || group._node === null) return null
+          return spatial.lodLevel(group._node, v.texture)
+        },
         pick(x, y) {
           if (v.disposed) return []
           pixelRayOf(v.camera, v.width, v.height, x, y)
           return raycastAs(v.texture, pickOrigin, pickDir, undefined)
         },
+        project(point) {
+          return projectWith(v.camera, v.width, v.height, point)
+        },
+        unproject(x, y, w, out = [0, 0, 0]) {
+          pixelRayOf(v.camera, v.width, v.height, x, y)
+          out[0] = pickOrigin[0] + w * pickDir[0]
+          out[1] = pickOrigin[1] + w * pickDir[1]
+          out[2] = pickOrigin[2] + w * pickDir[2]
+          return out
+        },
+        screenRay(x, y) {
+          pixelRayOf(v.camera, v.width, v.height, x, y)
+          return {
+            origin: [pickOrigin[0], pickOrigin[1], pickOrigin[2]],
+            direction: [pickDir[0], pickDir[1], pickDir[2]],
+          }
+        },
+        raycast(origin, direction, rayOpts) {
+          return raycastAs(texture, origin, direction, rayOpts)
+        },
         get handlers() {
           return viewPointer.handlers
         },
@@ -2544,8 +2555,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         spatial.destroyNode(root._node)
         root._node = null
       }
-      spatial.setFrustum(texture, null)
-      spatial.setLodView(texture, null)
+      spatial.setView(texture, null)
       // Drain the zeroed direction slots the teardown queued while the
       // targets still exist; afterwards their groups are gone.
       spatial.flush()
@@ -2601,10 +2611,12 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
           // The scene's pending state (lights, params, the fan-out to this
           // target) lands before the faces read it.
           sync()
-          renderCubeFaces(v.texture, v.camera, size, position, chain !== null, face => {
-            // Opaque order is a hint (front to back); only transparency
-            // needs the per-face sort.
-            if (face === 0 || transparentCount > 1) sortView(v)
+          renderCubeFaces(v.texture, v.camera, size, position, chain !== null, () => {
+            // Each face looks a different way: its own view, flushed so
+            // the core culls, sorts and measures the face before it
+            // renders.
+            setView(v.texture, v.camera)
+            spatial.flush()
           })
           chain?.run()
         },