lecodes-gl-lite 2.0.0

package/src/webgl/editor.ts

@@ -0,0 +1,1297 @@
+// Engine-side EDITOR layer for the lite viewport (HOST API — not part of the bridge ABI or the
+// parity surface; apps never see it). Everything the 3D scene editor displays on top of a user
+// scene lives here: the ground grid, the selection outline, viewport picking, and the transform
+// gizmo. It is deliberately NOT built from scene entities: the gizmo/grid are engine-owned OGL
+// nodes rendered in dedicated passes and the gizmo handles are hit-test by pure ray math — no
+// overlay Scene, no colliders, no touch-system involvement. (The previous design put the gizmo in
+// an SDK overlay scene, which forced clicks to be routed into two scenes and per-handle collider
+// bookkeeping; this replaces all of that.)
+//
+// The scene editor connects through `_creator._editorConnect(handlers)` (createViewerLite) and
+// gets back { setGrid, setSelection, setGizmoMode, setGizmoSpace, setColliders, setGizmos }. Picking reports raw entity
+// ids — the harness bundle owns the entity→node-name policy (locked nodes, GLB part drill-down).
+//
+// Pointer contract: listeners sit on the CANVAS, which is a child of the host root the touch
+// system listens on — so a gizmo grab can stopPropagation() and the orbit track never starts,
+// while plain clicks fall through to the touch system untouched (a sub-5px pointerdown→up on the
+// canvas additionally resolves to a pick). Drag math follows the reference three.js gizmo
+// (letary-creator createGizmo.ts): a camera-facing plane through the drag axis, deltas projected
+// onto the axis; rotation reads a signed angle in the ring plane with Ctrl snapping to 15°.
+// Scale always manipulates LOCAL axes (a world-axis scale isn't expressible in a TRS local
+// matrix), matching the old gizmo's ruling.
+
+import {
+  Box, Camera, Cylinder, Geometry, GLTFSkin, Mesh, Program, Raycast, RenderTarget, Renderer,
+  Torus, Transform, Triangle, type OGLRenderingContext,
+} from 'ogl'
+import { identity, invertTRS, multiply, transformPoint, type Mat4Like } from '../core/math3d'
+import { convexHullTriangles } from '../vendor/creator-physics/js/index'
+import { depthFragment, depthVertex } from './shaders'
+import type { SceneCore } from '../core/sceneCore'
+import { viewScale } from 'lecodes-web-shared/src/ui/viewScale'
+import { Color } from 'lecodes-sdk/color'
+
+export type GizmoMode = 'translate' | 'rotate' | 'scale'
+export type GizmoSpace = 'global' | 'local'
+
+/** An entity's LOCAL transform, decomposed — what a gizmo drag reports back to the host. */
+export type EditorPose = {
+  position: [number, number, number]
+  quaternion: [number, number, number, number]
+  scale: [number, number, number]
+}
+
+export type EditorHandlers = {
+  /** A plain viewport click resolved to the topmost entity under it (0 = empty space). */
+  onPick?(entityId: number): void
+  /** A gizmo drag ended; `pose` is the entity's final local transform. Not emitted on Escape. */
+  onTransformEnd?(entityId: number, pose: EditorPose, mode: GizmoMode): void
+}
+
+/** One collider to draw (the scene editor derives these from the document's `Shape` aspects —
+ *  in edit mode aspects never attach, so there is no physics body to read back). Dimensions follow
+ *  the SDK's Shape contract: explicit primitives are WORLD units centred on the node (the node's
+ *  scale is ignored), `auto` is the node's own geometry AABB × world scale (a non-Mesh node gets
+ *  the SDK's 0.5 default box), `mesh` is the node subtree's triangles × world scale. */
+export type EditorCollider = {
+  entityId: number
+  /** The shape's centre relative to the node (Shape `origin`) — world units in the node's rotated,
+   *  UNSCALED frame, like the dimensions. Omitted = centred on the node, except `auto`, which
+   *  falls back to the centre of the geometry it measured. */
+  origin?: [number, number, number]
+  shape:
+    | { kind: 'auto' }
+    | { kind: 'box', half: [number, number, number] }
+    | { kind: 'sphere', radius: number }
+    | { kind: 'cylinder' | 'capsule', halfHeight: number, radius: number }
+    | { kind: 'mesh', convex: boolean }
+}
+
+/** One color batch of LINES (flat `[x,y,z, x,y,z]` per segment) — what the SDK's `Gizmos.*`
+ *  calls produce; the scene editor pushes them through `setGizmos`. With `entityId` the batch is
+ *  ANCHORED: segments are in that entity's local frame (scale stripped), the lines follow the
+ *  entity every frame (through a gizmo drag), pick like the entity's own geometry (screen-space
+ *  tolerance, on top of the picture) and draw in the selection accent while it is selected. */
+export type EditorGizmoBatch = { color: string, alpha: number, segments: number[], entityId?: number }
+
+/** The camera PREVIEW inset: render the scene once more from an entity's world pose (−Z = view)
+ *  with its own lens, into a rect of the canvas (CSS px, origin top-left). `hide` lists
+ *  editor-only entities (node markers) to leave out — the inset is the game's frame. */
+export type EditorPreview = {
+  entityId: number
+  fov: number
+  near: number
+  far: number
+  /** CSS px, relative to the canvas, origin top-left. */
+  rect: [number, number, number, number]
+  hide?: number[]
+}
+
+/** What the engine hands the layer (closure state of createViewerLite). */
+export type EditorContext = {
+  gl: OGLRenderingContext & WebGL2RenderingContext
+  renderer: Renderer
+  canvas: HTMLCanvasElement
+  camera: Camera
+  core: SceneCore
+  sceneRoots: Map<number, Transform>
+  drawablesOf(entityId: number): Mesh[]
+  collectMeshes(root: Transform): Mesh[]
+  /** The engine's LINES companion geometry for a triangle geometry (the wireframe mode's cache). */
+  wireGeometryFor(geometry: Geometry): Geometry
+  getViewRay(sceneId: number, x: number, y: number): { origin: number[], dir: number[] }
+  /** Draw a scene root with a camera through the engine's batched scene pass (batching.ts). */
+  renderScene(root: Transform, camera: Camera, force?: boolean): void
+}
+
+// Screen-constant gizmo size: world scale = camera distance × this × vertical fov in degrees
+// (the reference gizmo's formula — ~15% of the view height at fov 60).
+const GIZMO_SCALE = 0.0025
+const ARROW_LEN = 1.0        // axis handle tip, in gizmo units (× the screen-constant scale)
+const RING_RADIUS = 0.85
+const CENTER_RADIUS = 0.13   // uniform-scale cube pick sphere
+const HIT_THRESHOLD = 0.1    // handle grab distance, in gizmo units
+const CLICK_SLOP_PX = 5      // pointerdown→up under this = a pick, over = an orbit
+const GIZMO_PICK_PX = 8      // anchored gizmo lines pick within this many logical px
+const ROTATE_SNAP = (15 * Math.PI) / 180
+
+const AXIS_COLORS: [number, number, number][] = [
+  [0.93, 0.16, 0.12],  // X — #ee2a1f-ish (reference gizmo palette)
+  [0.42, 0.90, 0.16],  // Y
+  [0.16, 0.35, 1.0],   // Z
+]
+const CENTER_COLOR: [number, number, number] = [0.85, 0.85, 0.88]
+const highlight = (c: [number, number, number]): [number, number, number] =>
+  [c[0] * 0.5 + 0.5, c[1] * 0.5 + 0.5, c[2] * 0.5 + 0.5]
+
+const OUTLINE_COLOR = [0.941, 0.396, 0.243] // the editor accent (#f0653e)
+const COLLIDER_COLOR = [0.36, 0.92, 0.48]    // physics green (Unity's collider gizmo convention)
+const COLLIDER_ALPHA = 0.85
+
+// ---- small vector helpers (plain number[] in/out — matches getViewRay) --------------------------
+
+type V3 = number[]
+const sub3 = (a: V3, b: V3): V3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]]
+const add3 = (a: V3, b: V3): V3 => [a[0] + b[0], a[1] + b[1], a[2] + b[2]]
+const scale3 = (a: V3, s: number): V3 => [a[0] * s, a[1] * s, a[2] * s]
+const dot3 = (a: V3, b: V3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+const cross3 = (a: V3, b: V3): V3 => [
+  a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0],
+]
+const len3 = (a: V3): number => Math.hypot(a[0], a[1], a[2])
+const norm3 = (a: V3): V3 => { const l = len3(a) || 1; return [a[0] / l, a[1] / l, a[2] / l] }
+
+/** Ray→plane parameter (plane through `point` with `normal`); null when parallel or behind. */
+const intersectRayPlane = (origin: V3, dir: V3, point: V3, normal: V3): V3 | null => {
+  const denom = dot3(dir, normal)
+  if (Math.abs(denom) < 1e-6) return null
+  const t = dot3(sub3(point, origin), normal) / denom
+  if (t <= 0) return null
+  return add3(origin, scale3(dir, t))
+}
+
+/** Distance between a ray and an axis segment [0, segLen] from `axisOrigin` along unit `axisDir`,
+ *  plus the segment parameter of the closest approach (the same math the old gizmo unit-tested). */
+const rayToAxisSegment = (
+  rayO: V3, rayD: V3, axisOrigin: V3, axisDir: V3, segLen: number,
+): { dist: number, t: number } => {
+  const w = sub3(rayO, axisOrigin)
+  const b = dot3(axisDir, rayD)
+  const d = dot3(axisDir, w)
+  const e = dot3(rayD, w)
+  const denom = 1 - b * b
+  const raw = Math.abs(denom) < 1e-8 ? d : (d - b * e) / denom
+  const t = Math.max(0, Math.min(segLen, raw))
+  const p = add3(axisOrigin, scale3(axisDir, t))
+  const s = Math.max(0, dot3(sub3(p, rayO), rayD))
+  return { dist: len3(sub3(p, add3(rayO, scale3(rayD, s)))), t }
+}
+
+/** The camera-facing drag plane containing `axisDir` through `origin` (reference createPlane). */
+const dragPlaneNormal = (origin: V3, axisDir: V3, camPos: V3): V3 => {
+  const right = cross3(norm3(sub3(origin, camPos)), axisDir)
+  const normal = cross3(axisDir, right)
+  if (dot3(normal, normal) < 0.0001) return norm3(sub3(origin, camPos))
+  return norm3(normal)
+}
+
+/** Column-major rotation matrix around a unit world axis (Rodrigues). */
+const axisAngleMatrix = (axis: V3, angle: number): Float32Array => {
+  const [x, y, z] = axis
+  const c = Math.cos(angle), s = Math.sin(angle), t = 1 - c
+  const m = new Float32Array(16)
+  m[0] = t * x * x + c; m[1] = t * x * y + s * z; m[2] = t * x * z - s * y
+  m[4] = t * x * y - s * z; m[5] = t * y * y + c; m[6] = t * y * z + s * x
+  m[8] = t * x * z + s * y; m[9] = t * y * z - s * x; m[10] = t * z * z + c
+  m[15] = 1
+  return m
+}
+
+/** Decompose a TRS local matrix into the pose the host persists. */
+const decomposePose = (m: ArrayLike<number>): EditorPose => {
+  const sx = Math.hypot(m[0], m[1], m[2]) || 1
+  const sy = Math.hypot(m[4], m[5], m[6]) || 1
+  const sz = Math.hypot(m[8], m[9], m[10]) || 1
+  const r00 = m[0] / sx, r10 = m[1] / sx, r20 = m[2] / sx
+  const r01 = m[4] / sy, r11 = m[5] / sy, r21 = m[6] / sy
+  const r02 = m[8] / sz, r12 = m[9] / sz, r22 = m[10] / sz
+  const trace = r00 + r11 + r22
+  let x: number, y: number, z: number, w: number
+  if (trace > 0) {
+    const s = 0.5 / Math.sqrt(trace + 1)
+    w = 0.25 / s; x = (r21 - r12) * s; y = (r02 - r20) * s; z = (r10 - r01) * s
+  } else if (r00 > r11 && r00 > r22) {
+    const s = 2 * Math.sqrt(1 + r00 - r11 - r22)
+    w = (r21 - r12) / s; x = 0.25 * s; y = (r01 + r10) / s; z = (r02 + r20) / s
+  } else if (r11 > r22) {
+    const s = 2 * Math.sqrt(1 + r11 - r00 - r22)
+    w = (r02 - r20) / s; x = (r01 + r10) / s; y = 0.25 * s; z = (r12 + r21) / s
+  } else {
+    const s = 2 * Math.sqrt(1 + r22 - r00 - r11)
+    w = (r10 - r01) / s; x = (r02 + r20) / s; y = (r12 + r21) / s; z = 0.25 * s
+  }
+  return { position: [m[12], m[13], m[14]], quaternion: [x, y, z, w], scale: [sx, sy, sz] }
+}
+
+// ---- shaders ------------------------------------------------------------------------------------
+
+/** Flat-color program with a cheap view-space "headlight" term (matcap-ish depth cue). */
+const HANDLE_VERTEX = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 position;
+in vec3 normal;
+uniform mat4 modelViewMatrix;
+uniform mat4 projectionMatrix;
+uniform mat3 normalMatrix;
+out vec3 vN;
+void main() {
+  vN = normalize(normalMatrix * normal);
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`
+const HANDLE_FRAGMENT = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 vN;
+uniform vec3 uColor;
+out vec4 fragColor;
+void main() { fragColor = vec4(uColor * (0.72 + 0.28 * abs(vN.z)), 1.0); }
+`
+
+// Rotation rings are UNLIT and Blender-like: the hemisphere facing away from the camera is
+// discarded per fragment (a full circle reads as a sphere and hides what's behind it). During a
+// drag the grabbed ring goes full-circle again so the sweep stays readable.
+const RING_VERTEX = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 position;
+uniform mat4 modelMatrix;
+uniform mat4 modelViewMatrix;
+uniform mat4 projectionMatrix;
+out vec3 vWorld;
+void main() {
+  vWorld = (modelMatrix * vec4(position, 1.0)).xyz;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`
+const RING_FRAGMENT = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 vWorld;
+uniform vec3 uColor;
+uniform vec3 uOrigin;
+uniform vec3 uEye;
+uniform float uFull;
+out vec4 fragColor;
+void main() {
+  if (uFull < 0.5 && dot(vWorld - uOrigin, uOrigin - uEye) > 0.0) discard;
+  fragColor = vec4(uColor, 1.0);
+}
+`
+
+const LINE_VERTEX = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 position;
+uniform mat4 modelViewMatrix;
+uniform mat4 projectionMatrix;
+void main() { gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }
+`
+// Premultiplied output — the canvas is premultipliedAlpha and the grid blends ONE / 1-SRC_ALPHA
+// (same convention as the outline composite below).
+const LINE_FRAGMENT = /* glsl */ `#version 300 es
+precision highp float;
+uniform vec3 uColor;
+uniform float uAlpha;
+out vec4 fragColor;
+void main() { fragColor = vec4(uColor * uAlpha, uAlpha); }
+`
+
+// Fullscreen composite: tint the pixels near (but outside) the selection mask — a 2px outline.
+const OUTLINE_VERTEX = /* glsl */ `#version 300 es
+in vec2 position;
+in vec2 uv;
+out vec2 vUv;
+void main() { vUv = uv; gl_Position = vec4(position, 0.0, 1.0); }
+`
+const OUTLINE_FRAGMENT = /* glsl */ `#version 300 es
+precision highp float;
+in vec2 vUv;
+uniform sampler2D tMask;
+uniform vec2 uTexel;
+uniform vec3 uColor;
+out vec4 fragColor;
+void main() {
+  float center = texture(tMask, vUv).r;
+  float edge = 0.0;
+  for (int x = -2; x <= 2; x++) {
+    for (int y = -2; y <= 2; y++) {
+      edge = max(edge, texture(tMask, vUv + vec2(float(x), float(y)) * uTexel).r);
+    }
+  }
+  float a = clamp(edge - center, 0.0, 1.0);
+  if (a < 0.02) discard;
+  fragColor = vec4(uColor * a, a);
+}
+`
+
+// -------------------------------------------------------------------------------------------------
+
+export const createEditorLayer = (ctx: EditorContext) => {
+  const { gl, renderer, canvas, camera, core } = ctx
+
+  let handlers: EditorHandlers = {}
+  let gridVisible = false
+  let selectedEntity: number | null = null
+  let mode: GizmoMode | null = null
+  let space: GizmoSpace = 'global'
+
+  // ---- grid -------------------------------------------------------------------------------------
+  // The same 20×20 unit grid + brighter center cross the harness bundle used to add to the user's
+  // scene — now engine-owned, so the Filament preview (and shipped apps) never see it. Rendered
+  // right after the main pass with depth testing on, so scene content occludes it correctly.
+  //
+  // The lines are a translucent TINT OF THE BACKDROP, not a fixed slate: 10% black over a light
+  // skybox, 10% white over a dark one (the center cross doubles that so the origin still reads).
+  // One fixed color can't work for both — it either drew a hard grey cage over a light sky or
+  // vanished into a dark one. `setGridBackground` (below) repaints it as the skybox changes.
+  //
+  // Depth WRITING stays on (the default): the overlay pass right after this one clears the depth
+  // buffer, and a glDepthMask(false) left behind would silently no-op that clear.
+
+  const GRID_ALPHA = 0.1
+  const AXIS_ALPHA = 0.22
+  const gridPrograms: Program[] = []
+  const gridRoot = new Transform()
+  {
+    const HALF = 10
+    const lines: number[] = []
+    for (let i = -HALF; i <= HALF; i++) {
+      if (i === 0) continue
+      lines.push(i, 0, -HALF, i, 0, HALF, -HALF, 0, i, HALF, 0, i)
+    }
+    const lineMesh = (positions: number[], alpha: number): Mesh => {
+      const program = new Program(gl, {
+        vertex: LINE_VERTEX,
+        fragment: LINE_FRAGMENT,
+        uniforms: { uColor: { value: [1, 1, 1] }, uAlpha: { value: alpha } } as any,
+        transparent: true,
+      })
+      program.setBlendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA)
+      gridPrograms.push(program)
+      const geometry = new Geometry(gl, { position: { size: 3, data: Float32Array.from(positions) } } as any)
+      const mesh = new Mesh(gl, { geometry, program, mode: gl.LINES })
+      mesh.frustumCulled = false
+      return mesh
+    }
+    gridRoot.addChild(lineMesh(lines, GRID_ALPHA))
+    // center X/Z axes, slightly raised to win the depth tie against the grid plane
+    gridRoot.addChild(lineMesh(
+      [-HALF, 0.001, 0, HALF, 0.001, 0, 0, 0.001, -HALF, 0, 0.001, HALF],
+      AXIS_ALPHA,
+    ))
+  }
+
+  /** Ink the grid against the backdrop it sits on: `bg` is the DISPLAY-space color the frame was
+   *  cleared with (the tonemapped skybox). Perceptual luminance picks black-on-light /
+   *  white-on-dark; the alphas above never change, so the grid stays a whisper either way. */
+  let gridInk = -1
+  const setGridBackground = (bg: readonly number[]): void => {
+    const lum = 0.2126 * (bg[0] ?? 0) + 0.7152 * (bg[1] ?? 0) + 0.0722 * (bg[2] ?? 0)
+    const ink = lum > 0.5 ? 0 : 1
+    if (ink === gridInk) return
+    gridInk = ink
+    for (const program of gridPrograms) program.uniforms.uColor.value = [ink, ink, ink]
+  }
+
+  // ---- gizmo meshes -------------------------------------------------------------------------------
+  // One root, three mode groups. Handles are tagged with `_axis` (0/1/2, 3 = uniform center) so a
+  // shared program can recolor per draw and a drag can solo its own handle.
+
+  const handleProgram = new Program(gl, {
+    vertex: HANDLE_VERTEX,
+    fragment: HANDLE_FRAGMENT,
+    uniforms: { uColor: { value: [1, 1, 1] } } as any,
+  })
+  const ringProgram = new Program(gl, {
+    vertex: RING_VERTEX,
+    fragment: RING_FRAGMENT,
+    uniforms: {
+      uColor: { value: [1, 1, 1] },
+      uOrigin: { value: [0, 0, 0] },
+      uEye: { value: [0, 0, 0] },
+      uFull: { value: 0 },
+    } as any,
+  })
+
+  let hoverAxis: number | null = null
+  let dragging: {
+    axis: number
+    startLocal: Float32Array
+    onMove: (e: PointerEvent) => void
+    cleanup: () => void
+  } | null = null
+
+  const gizmoRoot = new Transform()
+  gizmoRoot.matrixAutoUpdate = false
+
+  const tagHandle = (mesh: Mesh, axis: number, program: Program = handleProgram): Mesh => {
+    ;(mesh as any)._axis = axis
+    mesh.frustumCulled = false
+    mesh.onBeforeRender(() => {
+      const active = dragging ? dragging.axis : hoverAxis
+      const base = axis === 3 ? CENTER_COLOR : AXIS_COLORS[axis]
+      ;(program.uniforms as any).uColor.value = active === axis ? highlight(base) : base
+    })
+    return mesh
+  }
+
+  /** A group whose +Y is rotated onto the given axis (0=X, 1=Y, 2=Z). */
+  const axisGroup = (parent: Transform, axis: number): Transform => {
+    const g = new Transform()
+    if (axis === 0) g.rotation.z = -Math.PI / 2
+    else if (axis === 2) g.rotation.x = Math.PI / 2
+    g.setParent(parent)
+    return g
+  }
+
+  const translateGroup = new Transform()
+  const rotateGroup = new Transform()
+  const scaleGroup = new Transform()
+  for (const g of [translateGroup, rotateGroup, scaleGroup]) g.setParent(gizmoRoot)
+  {
+    // shafts run from the ORIGIN out (the reference gizmo look — no gap at the pivot)
+    const shaftGeo = new Cylinder(gl, { radiusTop: 0.014, radiusBottom: 0.014, height: 0.78, radialSegments: 6 })
+    const coneGeo = new Cylinder(gl, { radiusTop: 0.001, radiusBottom: 0.065, height: 0.26, radialSegments: 12 })
+    const cubeGeo = new Box(gl, { width: 0.1, height: 0.1, depth: 0.1 })
+    const centerGeo = new Box(gl, { width: 0.14, height: 0.14, depth: 0.14 })
+    const ringGeo = new Torus(gl, { radius: RING_RADIUS, tube: 0.02, radialSegments: 8, tubularSegments: 64 })
+
+    for (let axis = 0; axis < 3; axis++) {
+      const tg = axisGroup(translateGroup, axis)
+      const shaft = tagHandle(new Mesh(gl, { geometry: shaftGeo, program: handleProgram }), axis)
+      shaft.position.y = 0.39
+      const cone = tagHandle(new Mesh(gl, { geometry: coneGeo, program: handleProgram }), axis)
+      cone.position.y = 0.87  // tip lands at ARROW_LEN
+      tg.addChild(shaft); tg.addChild(cone)
+
+      const sg = axisGroup(scaleGroup, axis)
+      const sShaft = tagHandle(new Mesh(gl, { geometry: shaftGeo, program: handleProgram }), axis)
+      sShaft.position.y = 0.39
+      const cube = tagHandle(new Mesh(gl, { geometry: cubeGeo, program: handleProgram }), axis)
+      cube.position.y = 0.83  // flush with the shaft end
+      sg.addChild(sShaft); sg.addChild(cube)
+
+      // torus lies in the XY plane (ring around Z) — rotate its axis onto the target one
+      const ring = tagHandle(new Mesh(gl, { geometry: ringGeo, program: ringProgram }), axis, ringProgram)
+      if (axis === 0) ring.rotation.y = Math.PI / 2
+      else if (axis === 1) ring.rotation.x = Math.PI / 2
+      rotateGroup.addChild(ring)
+    }
+    scaleGroup.addChild(tagHandle(new Mesh(gl, { geometry: centerGeo, program: handleProgram }), 3))
+  }
+
+  // ---- gizmo state --------------------------------------------------------------------------------
+
+  type GizmoState = { origin: V3, axes: V3[], scale: number, camPos: V3, sceneId: number }
+
+  /** Live world-space frame of the gizmo (null when it shouldn't show). */
+  const gizmoState = (): GizmoState | null => {
+    if (selectedEntity === null || mode === null) return null
+    if (!core.entities.has(selectedEntity)) return null
+    const sceneId = core.activeSceneId()
+    const scene = core.scenes.get(sceneId)
+    if (!scene || scene.camera === undefined) return null
+    const w = core.worldMatrixF(selectedEntity)
+    const origin: V3 = [w[12], w[13], w[14]]
+    // Scale is always manipulated on LOCAL axes (world-axis scale isn't a TRS-expressible op).
+    const useLocal = space === 'local' || mode === 'scale'
+    const axes: V3[] = useLocal
+      ? [0, 1, 2].map((i) => norm3([w[i * 4], w[i * 4 + 1], w[i * 4 + 2]]))
+      : [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
+    const cw = core.worldMatrixF(scene.camera)
+    const camPos: V3 = [cw[12], cw[13], cw[14]]
+    const dist = len3(sub3(origin, camPos)) || 1
+    return { origin, axes, scale: dist * GIZMO_SCALE * core.projectionOf(sceneId).fov, camPos, sceneId }
+  }
+
+  /** Sync the gizmo root + handle visibility to the live state; false = nothing to draw. */
+  const syncGizmo = (): boolean => {
+    const g = gizmoState()
+    if (!g) return false
+    const m = gizmoRoot.matrix as unknown as number[]
+    for (let i = 0; i < 3; i++) {
+      m[i] = g.axes[0][i] * g.scale
+      m[4 + i] = g.axes[1][i] * g.scale
+      m[8 + i] = g.axes[2][i] * g.scale
+      m[12 + i] = g.origin[i]
+    }
+    m[3] = 0; m[7] = 0; m[11] = 0; m[15] = 1
+    gizmoRoot.worldMatrixNeedsUpdate = true
+    translateGroup.visible = mode === 'translate'
+    rotateGroup.visible = mode === 'rotate'
+    scaleGroup.visible = mode === 'scale'
+    const ru = ringProgram.uniforms as any
+    ru.uOrigin.value = g.origin
+    ru.uEye.value = g.camPos
+    ru.uFull.value = dragging && mode === 'rotate' ? 1 : 0
+    // a drag solos its own handle (the reference gizmo's behavior)
+    for (const group of [translateGroup, rotateGroup, scaleGroup]) {
+      group.traverse((node: any) => {
+        if (node._axis !== undefined) node.visible = dragging === null || node._axis === dragging.axis
+      })
+    }
+    return true
+  }
+
+  /** Which handle a viewport ray grabs (0/1/2 axis, 3 = uniform center), or null. */
+  const hitTestGizmo = (x: number, y: number): number | null => {
+    const g = gizmoState()
+    if (!g) return null
+    const { origin, dir } = ctx.getViewRay(g.sceneId, x, y)
+    const threshold = HIT_THRESHOLD * g.scale
+    if (mode === 'rotate') {
+      // only the near hemisphere is drawn (Blender-style), so only it may be grabbed
+      const viewDir = norm3(sub3(g.origin, g.camPos))
+      let best: number | null = null
+      let bestT = Infinity
+      for (let axis = 0; axis < 3; axis++) {
+        const p = intersectRayPlane(origin, dir, g.origin, g.axes[axis])
+        if (!p) continue
+        if (dot3(sub3(p, g.origin), viewDir) > 0) continue
+        const err = Math.abs(len3(sub3(p, g.origin)) - RING_RADIUS * g.scale)
+        const t = len3(sub3(p, origin))
+        if (err < threshold && t < bestT) { best = axis; bestT = t }
+      }
+      return best
+    }
+    // uniform-scale center cube: a sphere around the origin
+    if (mode === 'scale') {
+      const { dist } = rayToAxisSegment(origin, dir, g.origin, norm3(dir), 0)
+      if (dist < CENTER_RADIUS * g.scale) return 3
+    }
+    let best: number | null = null
+    let bestDist = threshold
+    for (let axis = 0; axis < 3; axis++) {
+      const { dist } = rayToAxisSegment(origin, dir, g.origin, g.axes[axis], (ARROW_LEN + 0.05) * g.scale)
+      if (dist <= bestDist) { bestDist = dist; best = axis }
+    }
+    return best
+  }
+
+  // ---- gizmo drags --------------------------------------------------------------------------------
+
+  const toCanvasXY = (e: { clientX: number, clientY: number }): [number, number] => {
+    const rect = canvas.getBoundingClientRect()
+    const s = viewScale(canvas)
+    return [(e.clientX - rect.left) / s, (e.clientY - rect.top) / s]
+  }
+
+  const beginDrag = (axis: number, e: PointerEvent): boolean => {
+    const g = gizmoState()
+    if (!g || selectedEntity === null) return false
+    const id = selectedEntity
+    const entity = core.ent(id)
+    const startLocal = Float32Array.from(entity.m as ArrayLike<number>)
+    const parentWorld = entity.parent !== 0 ? core.worldMatrixF(entity.parent) : identity()
+    const invParent = invertTRS(Float32Array.from(parentWorld))
+    const startWorld = multiply(new Float32Array(16), parentWorld, startLocal)
+    const [x0] = toCanvasXY(e)
+
+    let onMove: ((e: PointerEvent) => void) | null = null
+
+    if (axis === 3) {
+      // uniform scale: pointer-x based factor
+      onMove = (ev) => {
+        const [x] = toCanvasXY(ev)
+        const f = Math.max(0.01, 1 + (x - x0) / 150)
+        const m = Float32Array.from(startLocal)
+        for (let c = 0; c < 3; c++) for (let i = 0; i < 3; i++) m[c * 4 + i] *= f
+        core.methods.setMatrix(id, m)
+      }
+    } else if (mode === 'rotate') {
+      const axisW = g.axes[axis]
+      const { origin, dir } = ctx.getViewRay(g.sceneId, ...toCanvasXY(e))
+      const p0 = intersectRayPlane(origin, dir, g.origin, axisW)
+      if (!p0) return false
+      const v0 = sub3(p0, g.origin)
+      onMove = (ev) => {
+        const ray = ctx.getViewRay(g.sceneId, ...toCanvasXY(ev))
+        const p = intersectRayPlane(ray.origin, ray.dir, g.origin, axisW)
+        if (!p) return
+        const v = sub3(p, g.origin)
+        let angle = Math.atan2(dot3(cross3(v0, v), axisW), dot3(v0, v))
+        if (ev.ctrlKey) angle = Math.round(angle / ROTATE_SNAP) * ROTATE_SNAP
+        // world' = T(o) · R · T(−o) · world  →  local' = parent⁻¹ · world'
+        const R = axisAngleMatrix(axisW, angle)
+        const ro: number[] = [0, 0, 0]
+        transformPoint(ro, R, g.origin[0], g.origin[1], g.origin[2], 1)
+        R[12] = g.origin[0] - ro[0]; R[13] = g.origin[1] - ro[1]; R[14] = g.origin[2] - ro[2]
+        const world = multiply(new Float32Array(16), R, startWorld)
+        const local = entity.parent !== 0 ? multiply(new Float32Array(16), invParent, world) : world
+        core.methods.setMatrix(id, local as Float32Array)
+      }
+    } else {
+      const axisW = g.axes[axis]
+      const planeN = dragPlaneNormal(g.origin, axisW, g.camPos)
+      const { origin, dir } = ctx.getViewRay(g.sceneId, ...toCanvasXY(e))
+      const p0 = intersectRayPlane(origin, dir, g.origin, planeN)
+      if (!p0) return false
+      if (mode === 'translate') {
+        const startWorldPos: V3 = [startWorld[12], startWorld[13], startWorld[14]]
+        onMove = (ev) => {
+          const ray = ctx.getViewRay(g.sceneId, ...toCanvasXY(ev))
+          const p = intersectRayPlane(ray.origin, ray.dir, g.origin, planeN)
+          if (!p) return
+          const delta = dot3(sub3(p, p0), axisW)
+          const world = add3(startWorldPos, scale3(axisW, delta))
+          const local: number[] = [0, 0, 0]
+          if (entity.parent !== 0) transformPoint(local, invParent, world[0], world[1], world[2], 1)
+          else { local[0] = world[0]; local[1] = world[1]; local[2] = world[2] }
+          core.methods.setPosition(id, local[0], local[1], local[2])
+        }
+      } else {
+        // per-axis scale: drag distance along the LOCAL axis, one gizmo length = factor +1
+        onMove = (ev) => {
+          const ray = ctx.getViewRay(g.sceneId, ...toCanvasXY(ev))
+          const p = intersectRayPlane(ray.origin, ray.dir, g.origin, planeN)
+          if (!p) return
+          const f = Math.max(0.01, 1 + dot3(sub3(p, p0), axisW) / (ARROW_LEN * g.scale))
+          const m = Float32Array.from(startLocal)
+          for (let i = 0; i < 3; i++) m[axis * 4 + i] *= f
+          core.methods.setMatrix(id, m)
+        }
+      }
+    }
+    if (!onMove) return false
+
+    const win = canvas.ownerDocument.defaultView ?? window
+    const pointerId = e.pointerId
+    const handleMove = (ev: PointerEvent) => { if (ev.pointerId === pointerId) dragging?.onMove(ev) }
+    const finish = (commit: boolean) => {
+      if (!dragging) return
+      const drag = dragging
+      dragging = null
+      drag.cleanup()
+      if (commit) {
+        handlers.onTransformEnd?.(id, decomposePose(core.ent(id).m as ArrayLike<number>), mode!)
+      } else {
+        core.methods.setMatrix(id, drag.startLocal) // Escape → restore
+      }
+    }
+    const handleUp = (ev: PointerEvent) => { if (ev.pointerId === pointerId) finish(true) }
+    const handleCancel = () => finish(false)
+    const handleKey = (ev: KeyboardEvent) => { if (ev.code === 'Escape') finish(false) }
+    win.addEventListener('pointermove', handleMove)
+    win.addEventListener('pointerup', handleUp)
+    win.addEventListener('pointercancel', handleCancel)
+    win.addEventListener('keydown', handleKey)
+    dragging = {
+      axis,
+      startLocal,
+      onMove,
+      cleanup: () => {
+        win.removeEventListener('pointermove', handleMove)
+        win.removeEventListener('pointerup', handleUp)
+        win.removeEventListener('pointercancel', handleCancel)
+        win.removeEventListener('keydown', handleKey)
+      },
+    }
+    return true
+  }
+
+  // ---- picking ------------------------------------------------------------------------------------
+
+  const raycaster = new Raycast()
+
+  /** Topmost entity under a viewport pixel: triangle-precise where OGL's raycast can read the
+   *  geometry (non-interleaved positions), per-mesh bounds otherwise. 0 = nothing. */
+  const pickEntity = (x: number, y: number): number => {
+    const sceneId = core.activeSceneId()
+    const root = ctx.sceneRoots.get(sceneId)
+    const scene = core.scenes.get(sceneId)
+    if (!root || !scene || scene.camera === undefined) return 0
+    const { origin, dir } = ctx.getViewRay(sceneId, x, y)
+    ;(raycaster.origin as any).set(origin[0], origin[1], origin[2])
+    ;(raycaster.direction as any).set(dir[0], dir[1], dir[2])
+    const precise: Mesh[] = []
+    const coarse: Mesh[] = []
+    for (const m of ctx.collectMeshes(root) as any[]) {
+      const pos = m.geometry?.attributes?.position
+      if (!pos?.data) continue
+      // OGL's triangle test reads positions at index*size — interleaved (strided) data would
+      // misread, so those meshes fall back to their bounds
+      const strided = pos.stride && pos.stride !== pos.size * pos.data.BYTES_PER_ELEMENT
+      if (m.mode === gl.TRIANGLES && !strided) precise.push(m)
+      else coarse.push(m)
+    }
+    root.updateMatrixWorld()
+    let best: any = null
+    try {
+      for (const hit of raycaster.intersectMeshes(precise, { cullFace: false, includeUV: false, includeNormal: false, output: [] }) as any[]) {
+        if (!best || hit.hit.distance < best.hit.distance) best = hit
+      }
+    } catch { /* a malformed geometry must not break clicking */ }
+    try {
+      for (const hit of raycaster.intersectBounds(coarse, { output: [] }) as any[]) {
+        if (!best || hit.hit.distance < best.hit.distance) best = hit
+      }
+    } catch { /* ditto */ }
+    return best?._entId ?? 0
+  }
+
+  // ---- pointer wiring -----------------------------------------------------------------------------
+  // The canvas is a child of the root the touch system listens on: stopping propagation on a gizmo
+  // grab keeps the orbit track from starting; anything else falls through untouched.
+
+  let pendingClick: { pointerId: number, x: number, y: number } | null = null
+
+  const onPointerDown = (e: PointerEvent) => {
+    if (e.button !== 0 || e.shiftKey || dragging) return
+    const [x, y] = toCanvasXY(e)
+    const axis = hitTestGizmo(x, y)
+    if (axis !== null && beginDrag(axis, e)) {
+      e.preventDefault()
+      e.stopPropagation()
+      pendingClick = null
+      return
+    }
+    pendingClick = { pointerId: e.pointerId, x: e.clientX, y: e.clientY }
+  }
+
+  const onPointerUp = (e: PointerEvent) => {
+    const pending = pendingClick
+    pendingClick = null
+    if (!pending || pending.pointerId !== e.pointerId) return
+    if (Math.abs(e.clientX - pending.x) + Math.abs(e.clientY - pending.y) > CLICK_SLOP_PX) return
+    const [x, y] = toCanvasXY(e)
+    // an anchored gizmo (an empty's cross, a camera's frustum) draws on top, so it picks on top
+    handlers.onPick?.(pickAnchoredGizmo(x, y) || pickEntity(x, y))
+  }
+
+  const onPointerMove = (e: PointerEvent) => {
+    if (dragging) return
+    const [x, y] = toCanvasXY(e)
+    const next = mode !== null && selectedEntity !== null ? hitTestGizmo(x, y) : null
+    const overGizmo = next === null && anchoredGizmos.length > 0 ? pickAnchoredGizmo(x, y) || null : null
+    if (next !== hoverAxis || overGizmo !== hoverGizmoEntity) {
+      hoverAxis = next
+      hoverGizmoEntity = overGizmo
+      canvas.style.cursor = next !== null || overGizmo !== null ? 'pointer' : ''
+    }
+  }
+
+  canvas.addEventListener('pointerdown', onPointerDown)
+  canvas.addEventListener('pointerup', onPointerUp)
+  canvas.addEventListener('pointermove', onPointerMove)
+
+  // ---- collider overlay ---------------------------------------------------------------------------
+  // Wire pictures of the document's Shape aspects: primitives as LINES geometries (unit shapes
+  // scaled through the matrix where one parameter suffices, cached per parameter set otherwise),
+  // mesh colliders as the drawables' edge wireframe (the same companion geometry the wireframe
+  // mode uses — a triangle mesh IS the render mesh), a convex hull as the REAL hull Jolt builds
+  // (hullGeometryFor below). Drawn in the overlay pass with depth testing OFF: a collider usually
+  // sits inside or exactly on the surface it protects, and a depth-tested line would z-fight or
+  // hide — "where is my collider" beats occlusion correctness here.
+
+  const colliderProgram = new Program(gl, {
+    vertex: LINE_VERTEX,
+    fragment: LINE_FRAGMENT,
+    uniforms: { uColor: { value: COLLIDER_COLOR }, uAlpha: { value: COLLIDER_ALPHA } } as any,
+    transparent: true,
+    depthTest: false,
+    depthWrite: false,
+  })
+  colliderProgram.setBlendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA)
+
+  const linesGeometry = (positions: number[]): Geometry =>
+    new Geometry(gl, { position: { size: 3, data: Float32Array.from(positions) } } as any)
+  /** Append a LINES ring of radius r in the plane normal to `axis`, offset `at` along it. */
+  const ring = (out: number[], r: number, at: number, axis: 0 | 1 | 2, segs = 32): void => {
+    for (let i = 0; i < segs; i++) {
+      for (const a of [(Math.PI * 2 * i) / segs, (Math.PI * 2 * (i + 1)) / segs]) {
+        const u = Math.cos(a) * r, v = Math.sin(a) * r
+        if (axis === 1) out.push(u, at, v)
+        else if (axis === 0) out.push(at, u, v)
+        else out.push(u, v, at)
+      }
+    }
+  }
+  // unit box [-1,1]³ and unit sphere (three great circles) — sized through the matrix
+  const unitBox = linesGeometry((() => {
+    const p: number[] = []
+    const corner = (i: number) => [i & 1 ? 1 : -1, i & 2 ? 1 : -1, i & 4 ? 1 : -1]
+    for (let i = 0; i < 8; i++) for (const bit of [1, 2, 4]) {
+      if (i & bit) continue
+      p.push(...corner(i), ...corner(i | bit))
+    }
+    return p
+  })())
+  const unitSphere = linesGeometry((() => {
+    const p: number[] = []
+    ring(p, 1, 0, 0); ring(p, 1, 0, 1); ring(p, 1, 0, 2)
+    return p
+  })())
+  // Y-aligned cylinders/capsules depend on two parameters — cached per pair (bounded)
+  const tubeCache = new Map<string, Geometry>()
+  const tubeGeometry = (kind: 'cylinder' | 'capsule', hh: number, r: number): Geometry => {
+    const key = `${kind}:${hh}:${r}`
+    let g = tubeCache.get(key)
+    if (g) return g
+    const p: number[] = []
+    ring(p, r, hh, 1); ring(p, r, -hh, 1)
+    for (const [x, z] of [[r, 0], [-r, 0], [0, r], [0, -r]]) p.push(x, -hh, z, x, hh, z)
+    if (kind === 'capsule') {
+      // hemispherical caps: half arcs in the XY and YZ planes, top and bottom
+      const n = 12
+      for (const top of [true, false]) for (const plane of [0, 2]) {
+        for (let i = 0; i < n; i++) {
+          for (const a of [(Math.PI * i) / n, (Math.PI * (i + 1)) / n]) {
+            const u = Math.cos(a) * r, v = (top ? hh : -hh) + Math.sin(a) * r * (top ? 1 : -1)
+            if (plane === 0) p.push(u, v, 0)
+            else p.push(0, v, u)
+          }
+        }
+      }
+    }
+    g = linesGeometry(p)
+    if (tubeCache.size > 64) tubeCache.clear()
+    tubeCache.set(key, g)
+    return g
+  }
+
+  // ---- editor gizmos (world-space line batches from the SDK's `Gizmos` calls) --------------------
+  // Rebuilt only when the host replaces the list (the points are world space — no per-frame
+  // matrix work); one Mesh per color batch sharing the collider line program with its own uniforms.
+  const lineGizmoRoot = new Transform()
+  const lineGizmoMeshes: Mesh[] = []
+  /** Anchored batches: matrix + tint refresh every frame, hit-tested on clicks/hover. */
+  type AnchoredGizmo = { entityId: number, mesh: Mesh, program: Program, color: [number, number, number], segments: Float32Array }
+  const anchoredGizmos: AnchoredGizmo[] = []
+  let hoverGizmoEntity: number | null = null
+  /** A batch color (any CSS color — the SDK sends '#rrggbbaa', other editors their own strings), gray when not one. */
+  const GIZMO_GRAY: [number, number, number, number] = [0.81, 0.83, 0.87, 1]
+  const setGizmos = (list: EditorGizmoBatch[]): void => {
+    for (const m of lineGizmoMeshes) { m.setParent(null as any); (m.geometry as any).remove?.() }
+    lineGizmoMeshes.length = 0
+    anchoredGizmos.length = 0
+    hoverGizmoEntity = null
+    for (const b of Array.isArray(list) ? list : []) {
+      if (!b || !Array.isArray(b.segments) || b.segments.length < 6) continue
+      const [r, g, bl, a] = Color.tryParse(b.color) ?? GIZMO_GRAY
+      const color: [number, number, number] = [r, g, bl]
+      const alpha = Math.max(0, Math.min(1, Number(b.alpha ?? 1) * a))
+      const program = new Program(gl, {
+        vertex: LINE_VERTEX,
+        fragment: LINE_FRAGMENT,
+        uniforms: { uColor: { value: color.slice() }, uAlpha: { value: alpha } } as any,
+        transparent: true,
+        depthTest: false,
+        depthWrite: false,
+      })
+      program.setBlendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA)
+      const count = Math.floor(b.segments.length / 6) * 6
+      const segments = Float32Array.from(b.segments.slice(0, count))
+      const geometry = new Geometry(gl, { position: { size: 3, data: segments } } as any)
+      const m = new Mesh(gl, { geometry, program, mode: gl.LINES })
+      m.frustumCulled = false
+      m.setParent(lineGizmoRoot)
+      lineGizmoMeshes.push(m)
+      const entityId = Number(b.entityId ?? 0)
+      if (entityId > 0) {
+        m.matrixAutoUpdate = false
+        anchoredGizmos.push({ entityId, mesh: m, program, color, segments })
+      }
+    }
+  }
+
+  /** Per frame: place every anchored batch on its entity (scale stripped — a marker keeps its
+   *  size on a scaled empty) and tint it: selection accent when selected, lifted when hovered. */
+  const syncAnchoredGizmos = (): void => {
+    for (const a of anchoredGizmos) {
+      if (!core.entities.has(a.entityId)) { a.mesh.visible = false; continue }
+      a.mesh.visible = true
+      a.mesh.matrix.copy(worldNoScale(a.entityId) as any)
+      a.mesh.worldMatrixNeedsUpdate = true
+      const tint = a.entityId === selectedEntity ? OUTLINE_COLOR
+        : a.entityId === hoverGizmoEntity ? highlight(a.color) : a.color
+      const u = (a.program.uniforms as any).uColor.value as number[]
+      u[0] = tint[0]; u[1] = tint[1]; u[2] = tint[2]
+    }
+  }
+
+  /** The anchored gizmo under a viewport point (logical px), or 0. Ray-vs-segment distance in
+   *  world units against a tolerance of GIZMO_PICK_PX at the segment's depth — the same size on
+   *  screen whatever the zoom — and ignoring occlusion, exactly like the lines draw. Among hits,
+   *  the closest to the pointer wins, then the nearest to the camera. */
+  const pickAnchoredGizmo = (x: number, y: number): number => {
+    if (anchoredGizmos.length === 0) return 0
+    const sceneId = core.activeSceneId()
+    const scene = core.scenes.get(sceneId)
+    if (!scene || scene.camera === undefined) return 0
+    const { origin, dir } = ctx.getViewRay(sceneId, x, y)
+    const rect = canvas.getBoundingClientRect()
+    const heightPx = Math.max(1, rect.height / viewScale(canvas))
+    const tolPerDepth = (2 * Math.tan((core.projectionOf(sceneId).fov * Math.PI) / 360) * GIZMO_PICK_PX) / heightPx
+    let bestId = 0, bestRatio = 1, bestDepth = Infinity
+    const a: V3 = [0, 0, 0], b: V3 = [0, 0, 0]
+    for (const g of anchoredGizmos) {
+      if (!core.entities.has(g.entityId)) continue
+      const m = worldNoScale(g.entityId)
+      const seg = g.segments
+      for (let i = 0; i + 5 < seg.length; i += 6) {
+        for (let k = 0; k < 3; k++) {
+          a[k] = m[k] * seg[i] + m[4 + k] * seg[i + 1] + m[8 + k] * seg[i + 2] + m[12 + k]
+          b[k] = m[k] * seg[i + 3] + m[4 + k] * seg[i + 4] + m[8 + k] * seg[i + 5] + m[12 + k]
+        }
+        // closest points between the ray (t ≥ 0) and the segment (u ∈ [0,1])
+        const ab = sub3(b, a), ao = sub3(a, origin)
+        const dd = dot3(dir, dir), dab = dot3(dir, ab), abab = dot3(ab, ab)
+        const dao = dot3(dir, ao), abao = dot3(ab, ao)
+        const denom = dd * abab - dab * dab
+        let u = denom > 1e-12 ? (dab * dao - dd * abao) / denom : 0
+        u = Math.max(0, Math.min(1, u))
+        const t = Math.max(0, (dao + u * dab) / (dd || 1))
+        const q = add3(a, scale3(ab, u))
+        const r = add3(origin, scale3(dir, t))
+        if (t <= 1e-6) continue   // behind the camera
+        const tol = t * tolPerDepth
+        const ratio = len3(sub3(q, r)) / tol
+        if (ratio > 1) continue
+        if (ratio < bestRatio - 1e-3 || (Math.abs(ratio - bestRatio) <= 1e-3 && t < bestDepth)) {
+          bestId = g.entityId; bestRatio = ratio; bestDepth = t
+        }
+      }
+    }
+    return bestId
+  }
+
+  let colliders: EditorCollider[] = []
+  const colliderRoot = new Transform()
+  const colliderMeshes: Mesh[] = []
+  /** The entity's world matrix with its scale stripped (explicit Shape dims are world units), plus
+   *  the scale that was taken out (the `auto` box measures in node-local units and scales itself). */
+  const worldScale: [number, number, number] = [1, 1, 1]
+  const worldNoScale = (id: number): Float32Array => {
+    const out = Float32Array.from(core.worldMatrix(id) as ArrayLike<number>)
+    for (let c = 0; c < 3; c++) {
+      const l = Math.hypot(out[c * 4], out[c * 4 + 1], out[c * 4 + 2]) || 1
+      worldScale[c] = l
+      out[c * 4] /= l; out[c * 4 + 1] /= l; out[c * 4 + 2] /= l
+    }
+    return out
+  }
+  /** m × translate(t) × scale(s) — place a unit geometry. */
+  const placed = (m: Float32Array, sx: number, sy: number, sz: number, tx = 0, ty = 0, tz = 0): Float32Array => {
+    const out = Float32Array.from(m)
+    out[12] = m[12] + m[0] * tx + m[4] * ty + m[8] * tz
+    out[13] = m[13] + m[1] * tx + m[5] * ty + m[9] * tz
+    out[14] = m[14] + m[2] * tx + m[6] * ty + m[10] * tz
+    for (let i = 0; i < 3; i++) { out[i] *= sx; out[4 + i] *= sy; out[8 + i] *= sz }
+    return out
+  }
+  /** Triangle drawables of an entity subtree (what a mesh collider is built from). */
+  const collectTriangles = (id: number, out: Mesh[]): void => {
+    const e = core.entities.get(id)
+    if (!e) return
+    for (const d of ctx.drawablesOf(id)) if ((d as any).mode === gl.TRIANGLES) out.push(d)
+    for (const c of e.children) collectTriangles(c, out)
+  }
+
+  // A `Shape { mesh: 'convex' }`'s picture is the hull the SIMULATION builds — creator-physics' own
+  // hull builder (Jolt: the 256-point cap, its tolerances) over the subtree's triangles brought into
+  // the node's unscaled frame — never a wireframe of the render mesh. Cached per collider entity on
+  // (drawable geometries, world scale): a gizmo drag moves the cached lines, a re-attach rebuilds.
+  const hullCache = new Map<number, { key: string, geometry: Geometry | null }>()
+  const hullLines = (tris: Float32Array): Geometry => {
+    const index = new Map<string, number>()
+    const verts: number[] = []
+    const vertexOf = (x: number, y: number, z: number): number => {
+      const k = `${x.toFixed(5)},${y.toFixed(5)},${z.toFixed(5)}`
+      let i = index.get(k)
+      if (i === undefined) { i = verts.length / 3; index.set(k, i); verts.push(x, y, z) }
+      return i
+    }
+    const edges = new Set<number>()
+    for (let t = 0; t + 8 < tris.length; t += 9) {
+      const a = vertexOf(tris[t], tris[t + 1], tris[t + 2])
+      const b = vertexOf(tris[t + 3], tris[t + 4], tris[t + 5])
+      const c = vertexOf(tris[t + 6], tris[t + 7], tris[t + 8])
+      for (const [p, q] of [[a, b], [b, c], [c, a]]) edges.add(p < q ? p * 65536 + q : q * 65536 + p)
+    }
+    const lines: number[] = []
+    for (const e of edges) {
+      const p = Math.floor(e / 65536) * 3, q = (e % 65536) * 3
+      lines.push(verts[p], verts[p + 1], verts[p + 2], verts[q], verts[q + 1], verts[q + 2])
+    }
+    return new Geometry(gl, { position: { size: 3, data: Float32Array.from(lines) } } as any)
+  }
+  const hullGeometryFor = (entityId: number): Geometry | null => {
+    const tris: Mesh[] = []
+    collectTriangles(entityId, tris)
+    const node = worldNoScale(entityId)   // fills worldScale
+    const key = tris.map((d: any) => d.geometry?.id ?? '?').join(',') + '|' + worldScale.map((s) => s.toFixed(4)).join(',')
+    const cached = hullCache.get(entityId)
+    if (cached && cached.key === key) return cached.geometry
+    const inv = invertTRS(node)
+    const points: number[] = []
+    for (const d of tris as any[]) {
+      const attr = d.geometry?.attributes?.position
+      const data = attr?.data
+      if (!(data instanceof Float32Array) || attr.size !== 3 || attr.stride) continue
+      const m = multiply(new Float32Array(16), inv, d.worldMatrix as any)
+      for (let i = 0; i + 2 < data.length; i += 3) {
+        const x = data[i], y = data[i + 1], z = data[i + 2]
+        points.push(m[0] * x + m[4] * y + m[8] * z + m[12], m[1] * x + m[5] * y + m[9] * z + m[13], m[2] * x + m[6] * y + m[10] * z + m[14])
+      }
+    }
+    const hull = points.length >= 12 ? convexHullTriangles(points) : null
+    const geometry = hull ? hullLines(hull) : null
+    hullCache.set(entityId, { key, geometry })
+    return geometry
+  }
+
+  /** Rebuild the overlay meshes from the collider list + current entity transforms (every frame
+   *  the overlay shows — entities move under gizmo drags, async GLB loads add drawables). */
+  const syncColliders = (): boolean => {
+    for (const m of colliderMeshes) m.setParent(null as any)
+    colliderMeshes.length = 0
+    const add = (geometry: Geometry, matrix: Float32Array): void => {
+      const m = new Mesh(gl, { geometry, program: colliderProgram, mode: gl.LINES })
+      m.frustumCulled = false
+      m.matrixAutoUpdate = false
+      m.matrix.copy(matrix as any)
+      m.setParent(colliderRoot)
+      colliderMeshes.push(m)
+    }
+    for (const c of colliders) {
+      if (!core.entities.has(c.entityId)) continue
+      const shape = c.shape
+      const o = c.origin
+      const [ox, oy, oz] = o ?? [0, 0, 0]
+      if (shape.kind === 'box') {
+        add(unitBox, placed(worldNoScale(c.entityId), shape.half[0], shape.half[1], shape.half[2], ox, oy, oz))
+      } else if (shape.kind === 'sphere') {
+        add(unitSphere, placed(worldNoScale(c.entityId), shape.radius, shape.radius, shape.radius, ox, oy, oz))
+      } else if (shape.kind === 'cylinder' || shape.kind === 'capsule') {
+        add(tubeGeometry(shape.kind, shape.halfHeight, shape.radius), placed(worldNoScale(c.entityId), 1, 1, 1, ox, oy, oz))
+      } else if (shape.kind === 'mesh' && shape.convex && hullGeometryFor(c.entityId)) {
+        add(hullGeometryFor(c.entityId)!, placed(worldNoScale(c.entityId), 1, 1, 1, ox, oy, oz))
+      } else if (shape.kind === 'mesh') {
+        const tris: Mesh[] = []
+        collectTriangles(c.entityId, tris)
+        // the origin shifts the whole collider in the NODE's unscaled frame — move each drawable by
+        // that world-space delta rather than by its own basis (a rotated child would skew otherwise)
+        const n = worldNoScale(c.entityId)
+        const dx = n[0] * ox + n[4] * oy + n[8] * oz
+        const dy = n[1] * ox + n[5] * oy + n[9] * oz
+        const dz = n[2] * ox + n[6] * oy + n[10] * oz
+        for (const d of tris as any[]) {
+          if (!d.geometry?.attributes?.position) continue
+          const m = Float32Array.from(d.worldMatrix as ArrayLike<number>)
+          m[12] += dx; m[13] += dy; m[14] += dz
+          add(ctx.wireGeometryFor(d.geometry), m)
+        }
+      } else {
+        // auto: the node's OWN geometry AABB (a Mesh node) × world scale, centred on those bounds;
+        // anything else gets the SDK's 0.5 default. An explicit origin REPLACES the measured centre
+        // (the SDK's rule), so both live in world units on the unscaled basis.
+        const own = ctx.drawablesOf(c.entityId).find((d: any) => d.mode === gl.TRIANGLES) as any
+        let hx = 0.5, hy = 0.5, hz = 0.5, cx = 0, cy = 0, cz = 0
+        const b = own?.geometry?.bounds
+        if (b && isFinite(b.min.x)) {
+          hx = (b.max.x - b.min.x) / 2; hy = (b.max.y - b.min.y) / 2; hz = (b.max.z - b.min.z) / 2
+          cx = (b.max.x + b.min.x) / 2; cy = (b.max.y + b.min.y) / 2; cz = (b.max.z + b.min.z) / 2
+        }
+        const m = worldNoScale(c.entityId)          // fills worldScale
+        const [sx, sy, sz] = worldScale
+        add(unitBox, o
+          ? placed(m, hx * sx, hy * sy, hz * sz, ox, oy, oz)
+          : placed(m, hx * sx, hy * sy, hz * sz, cx * sx, cy * sy, cz * sz))
+      }
+    }
+    return colliderMeshes.length > 0
+  }
+
+  // ---- selection outline --------------------------------------------------------------------------
+  // Two small passes after everything else: (1) the selected subtree's drawables into an offscreen
+  // mask (constant white, no depth — the silhouette shows through occluders), (2) a fullscreen
+  // composite that tints pixels near-but-outside the mask. Skinned drawables pose correctly via the
+  // bone texture; morphed drawables mask at rest pose (same degrade as the shadow pass).
+
+  const maskProgram = new Program(gl, {
+    vertex: depthVertex(false),
+    fragment: depthFragment,
+    uniforms: { modelMatrix: { value: identity() }, shadowViewProjection: { value: identity() } } as any,
+    depthTest: false,
+    depthWrite: false,
+    cullFace: false as any,
+  })
+  const maskSkinProgram = new Program(gl, {
+    vertex: depthVertex(true),
+    fragment: depthFragment,
+    uniforms: {
+      modelMatrix: { value: identity() },
+      shadowViewProjection: { value: identity() },
+      boneTexture: { value: null },
+      boneTextureSize: { value: 4 },
+    } as any,
+    depthTest: false,
+    depthWrite: false,
+    cullFace: false as any,
+  })
+  let maskTarget: RenderTarget | null = null
+  const outlineProgram = new Program(gl, {
+    vertex: OUTLINE_VERTEX,
+    fragment: OUTLINE_FRAGMENT,
+    uniforms: {
+      tMask: { value: null },
+      uTexel: { value: [0, 0] },
+      uColor: { value: OUTLINE_COLOR },
+    } as any,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+  })
+  outlineProgram.setBlendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA)
+  const outlineTriangle = new Mesh(gl, { geometry: new Triangle(gl), program: outlineProgram })
+
+  /** Visible drawables of the selected entity's subtree (wire companions are not drawables). */
+  const collectSelected = (id: number, out: Mesh[]): void => {
+    const e = core.entities.get(id)
+    if (!e || !e.visible) return
+    out.push(...ctx.drawablesOf(id))
+    for (const c of e.children) collectSelected(c, out)
+  }
+
+  const renderOutline = (): void => {
+    if (selectedEntity === null || !core.entities.has(selectedEntity)) return
+    const meshes: Mesh[] = []
+    collectSelected(selectedEntity, meshes)
+    if (meshes.length === 0) return
+
+    if (!maskTarget || maskTarget.width !== canvas.width || maskTarget.height !== canvas.height) {
+      maskTarget = new RenderTarget(gl, { width: Math.max(1, canvas.width), height: Math.max(1, canvas.height) })
+    }
+    const camVP = multiply(new Float32Array(16),
+      camera.projectionMatrix as unknown as Mat4Like, camera.viewMatrix as unknown as Mat4Like)
+    maskProgram.uniforms.shadowViewProjection.value = camVP
+    maskSkinProgram.uniforms.shadowViewProjection.value = camVP
+
+    renderer.bindFramebuffer(maskTarget)
+    renderer.setViewport(maskTarget.width, maskTarget.height)
+    gl.clearColor(0, 0, 0, 0)
+    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT)
+    const identityMat = identity()
+    for (const mesh of meshes as any[]) {
+      const isSkin = mesh instanceof GLTFSkin
+      const program = isSkin ? maskSkinProgram : maskProgram
+      program.uniforms.modelMatrix.value = isSkin ? identityMat : mesh.worldMatrix
+      const original = mesh.program
+      mesh.program = program
+      mesh.draw({})
+      mesh.program = original
+    }
+    renderer.bindFramebuffer({ buffer: null } as any)
+    renderer.setViewport(canvas.width, canvas.height)
+
+    outlineProgram.uniforms.tMask.value = maskTarget.texture
+    outlineProgram.uniforms.uTexel.value = [1 / maskTarget.width, 1 / maskTarget.height]
+    outlineTriangle.draw({})
+  }
+
+  // ---- render hooks (called by createViewerLite's renderFrame) ------------------------------------
+
+  /** After the main pass, before overlays: the grid, depth-tested against scene content.
+   *  `background` is the display-space clear color of this frame — the grid tints against it. */
+  const renderScenePass = (background: readonly number[]): void => {
+    if (!gridVisible) return
+    setGridBackground(background)
+    renderer.render({ scene: gridRoot, camera, clear: false, frustumCull: false, sort: false })
+  }
+
+  /** After the overlays: outline, then the gizmo on a fresh depth buffer (always on top). */
+  const renderOverlayPass = (): void => {
+    renderOutline()
+    if (colliders.length > 0 && syncColliders()) {
+      renderer.render({ scene: colliderRoot, camera, clear: false, frustumCull: false, sort: false })
+    }
+    if (lineGizmoMeshes.length > 0) {
+      syncAnchoredGizmos()
+      renderer.render({ scene: lineGizmoRoot, camera, clear: false, frustumCull: false, sort: false })
+    }
+    if (!syncGizmo()) return
+    // glDepthMask MASKS depth clears — the outline pass just ran with depthWrite off, so restore
+    // it through the renderer's state cache or the clear silently no-ops (gizmo ends up occluded).
+    renderer.setDepthMask(true)
+    gl.clear(gl.DEPTH_BUFFER_BIT)
+    renderer.render({ scene: gizmoRoot, camera, clear: false, frustumCull: false, sort: false })
+  }
+
+  // ---- camera preview inset -----------------------------------------------------------------------
+  let preview: EditorPreview | null = null
+  const previewCamera = new Camera(gl, { fov: 60, near: 0.01, far: 1000, aspect: 1 })
+  previewCamera.matrixAutoUpdate = false   // posed by matrix (like the main camera), never from position/quaternion
+
+  /** After everything else: the inset, drawn straight from OGL's render list with the viewport +
+   *  scissor set to the rect (renderer.render() pins the viewport to the full canvas for a null
+   *  target, and the multisampled default framebuffer refuses blits — so neither a scissored
+   *  render() nor an offscreen target + blit works). */
+  const renderPreviewPass = (root: Transform, background: readonly number[]): void => {
+    const p = preview
+    if (!p) return
+    const s = canvas.width / (canvas.getBoundingClientRect().width || canvas.width)   // CSS px → device px
+    const x = Math.round(p.rect[0] * s), y = Math.round(p.rect[1] * s)
+    const w = Math.round(p.rect[2] * s), h = Math.round(p.rect[3] * s)
+    if (w < 2 || h < 2) return
+    const wm = core.worldMatrixF(p.entityId)
+    if (!wm) return
+    for (let i = 0; i < 16; i++) (previewCamera.matrix as any)[i] = wm[i]
+    previewCamera.worldMatrixNeedsUpdate = true
+    previewCamera.perspective({ fov: p.fov, aspect: w / h, near: p.near, far: p.far })
+    previewCamera.updateMatrixWorld()
+
+    const hidden: Mesh[] = []
+    for (const id of p.hide ?? []) {
+      for (const m of ctx.drawablesOf(id)) if (m.visible) { m.visible = false; hidden.push(m) }
+    }
+    const y0 = canvas.height - y - h   // GL origin bottom-left
+    renderer.bindFramebuffer({ buffer: null } as any)
+    renderer.setViewport(w, h, x, y0)
+    gl.enable(gl.SCISSOR_TEST)
+    gl.scissor(x, y0, w, h)
+    gl.clearColor(background[0] ?? 0, background[1] ?? 0, background[2] ?? 0, 1)
+    renderer.enable(gl.DEPTH_TEST)
+    renderer.setDepthMask(true)
+    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT)
+    ctx.renderScene(root, previewCamera, hidden.length > 0)
+    gl.disable(gl.SCISSOR_TEST)
+    for (const m of hidden) m.visible = true
+    renderer.setViewport(canvas.width, canvas.height)
+  }
+
+  const dispose = (): void => {
+    dragging?.cleanup()
+    dragging = null
+    canvas.removeEventListener('pointerdown', onPointerDown)
+    canvas.removeEventListener('pointerup', onPointerUp)
+    canvas.removeEventListener('pointermove', onPointerMove)
+    canvas.style.cursor = ''
+  }
+
+  // ---- the host-facing API (what _editorConnect returns) ------------------------------------------
+
+  const api = {
+    setGrid(on: boolean): void { gridVisible = on === true },
+    setSelection(entityId: number | null): void {
+      if (dragging && entityId !== selectedEntity) {
+        dragging.cleanup()
+        dragging = null
+      }
+      selectedEntity = entityId && entityId > 0 ? entityId : null
+    },
+    setGizmoMode(next: GizmoMode | null): void {
+      mode = next === 'translate' || next === 'rotate' || next === 'scale' ? next : null
+      hoverAxis = null
+    },
+    setGizmoSpace(next: GizmoSpace): void { space = next === 'local' ? 'local' : 'global' },
+    /** Replace the drawn collider set (empty = none). Unknown entities are skipped. */
+    setColliders(list: EditorCollider[]): void { colliders = Array.isArray(list) ? list.slice() : [] },
+    /** Replace the drawn editor gizmo lines (empty = none). Anchored batches (`entityId`) follow
+     *  their entity, pick and tint with the selection. */
+    setGizmos,
+    /** The camera preview inset (null = off). */
+    setPreview(next: EditorPreview | null): void { preview = next && next.entityId > 0 ? next : null },
+    /** The topmost scene entity under a viewport pixel (0 = empty space) — the host's drop
+     *  targets (a material tile dropped on an object). Same pick the click path uses. */
+    pickAt(x: number, y: number): number { return pickEntity(x, y) },
+  }
+
+  return {
+    api,
+    setHandlers(next: EditorHandlers): void { handlers = next ?? {} },
+    renderScenePass,
+    renderOverlayPass,
+    renderPreviewPass,
+    dispose,
+  }
+}
+
+export type EditorLayer = ReturnType<typeof createEditorLayer>
+export type EditorApi = EditorLayer['api']