@floless/app 0.34.2 → 0.35.0

package/dist/web/steel-3d-view.js

@@ -0,0 +1,422 @@
+/*
+ * steel-3d-view.js — the 3D render/interaction layer for the steel-takeoff editor's 3D mode.
+ *
+ * Three.js lives ONLY here (the rest of the editor is import-free). It renders the SAME scene the
+ * IFC/Tekla bake uses (fetched from /api/contract/:id/scene → contractToScene), so the editable 3D
+ * matches what bakes out. Phase B = read-only: orbit + shaded model + selection highlight. Phase C
+ * adds drag + snapping (it will pull the pure math from ./steel-3d-core.js).
+ *
+ * Exposes `window.Steel3DView` so the editor's classic script can drive it. The scene is Z-up
+ * (contractToScene emits meta.up='z'), so the camera/grid are set up Z-up.
+ */
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/OrbitControls.js';
+import { snapCandidates, snapPoint, planPointToWp, memberGeometry, elevationLevels } from './steel-3d-core.js';
+
+let renderer, scene, camera, controls, root, api, canvasEl, ro, rafId, grid, raycaster, downXY, lastPick = '(none)';
+let pending = null, dragging = null, marker = null, readout = null; // pending = member gesture; readout = drag dimension overlay
+const DRAG_TOL_PX = 4;   // movement past this = a drag (not a click)
+const SNAP_TOL_PX = 10;  // snap an endpoint to a target within this screen distance
+const FT_MM = 304.8;     // mm per foot (the dimension readout shows feet, matching the editor)
+let built = false, fitPending = false;
+const meshById = new Map();           // member id -> THREE.Mesh
+const groupColor = new Map();         // group key -> THREE.Color
+const baseMat = new Map();            // group key -> MeshStandardMaterial (shared per profile)
+const SELECT_EMISSIVE = 0x3b82f6;     // --brand: selected members glow blue
+
+function init(canvas, theApi) {
+  if (renderer) return;               // once
+  canvasEl = canvas; api = theApi;
+  renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+  renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
+  scene = new THREE.Scene();
+  scene.background = new THREE.Color(0x020817); // match the app --bg (the mode change reads from the geometry, not a tint)
+  camera = new THREE.PerspectiveCamera(50, 1, 1, 50_000_000);
+  camera.up.set(0, 0, 1);             // Z-up to match the scene
+  controls = new OrbitControls(camera, canvas);
+  controls.enableDamping = true;
+  scene.add(new THREE.AmbientLight(0xffffff, 0.65));
+  const key = new THREE.DirectionalLight(0xffffff, 0.85); key.position.set(0.4, -1, 1.2); scene.add(key);
+  const fill = new THREE.DirectionalLight(0xffffff, 0.25); fill.position.set(-1, 0.6, 0.4); scene.add(fill);
+  root = new THREE.Group(); scene.add(root);
+  raycaster = new THREE.Raycaster();
+  // a --brand snap marker (one sphere at the winning snap target; the readout carries the type)
+  marker = new THREE.Mesh(new THREE.SphereGeometry(1, 16, 12), new THREE.MeshBasicMaterial({ color: 0x3b82f6 }));
+  marker.visible = false; marker.renderOrder = 999; marker.material.depthTest = false; scene.add(marker);
+  // live dimension readout (toast-styled, follows the cursor during a drag — feet + snap type).
+  // Two spans + textContent (never innerHTML) so it's XSS-proof; the type span is muted.
+  readout = document.createElement('div');
+  readout.style.cssText = 'position:fixed;display:none;pointer-events:none;z-index:60;background:var(--panel,#0f172a);color:var(--text,#f8fafc);border:1px solid var(--line,#1e293b);border-radius:4px;padding:3px 7px;font:12px system-ui;white-space:nowrap;box-shadow:0 2px 8px rgba(0,0,0,.5)';
+  readout._dist = document.createElement('span');
+  readout._type = document.createElement('span'); readout._type.style.color = 'var(--mut,#94a3b8)';
+  readout.append(readout._dist, readout._type);
+  document.body.appendChild(readout);
+  // Pointer gestures: down on a member → grab it (suppress orbit); move → drag with snapping; up →
+  // commit the move, or (no move) select. Down on empty space → OrbitControls orbits/pans as usual.
+  // Capture phase on pointerdown so we can stop orbit BEFORE OrbitControls sees a member grab.
+  canvas.addEventListener('pointerdown', onDown, true);
+  window.addEventListener('pointermove', onMove); // window so a drag keeps tracking off-canvas
+  window.addEventListener('pointerup', onUp);
+  ro = new ResizeObserver(resize); ro.observe(canvas.parentElement || canvas);
+  // Resize once more on the next frame: the stage may still be laying out when init() runs (the
+  // designer flagged a first-render size mismatch as the common rough edge here).
+  requestAnimationFrame(resize);
+  resize();
+  // the render loop is started by show() (and stopped by hide()) so it never spins while in 2D
+}
+
+function resize() {
+  if (!renderer) return;
+  const el = canvasEl.parentElement || canvasEl;
+  const w = el.clientWidth || 1, h = el.clientHeight || 1;
+  renderer.setSize(w, h, false);
+  camera.aspect = w / h; camera.updateProjectionMatrix();
+}
+
+function loop() {
+  rafId = requestAnimationFrame(loop);
+  controls.update(); renderer.render(scene, camera);
+}
+
+const V = (x, y, z) => new THREE.Vector3(x, y, z);
+
+// ---- structural cross-section shapes (ported from AWARE viewer-3d for parity) ----
+// section.w = flange/overall width, section.d = section depth; shape derived from the profile name.
+function shapeOf(el) {
+  const explicit = (el.section && el.section.shape || '').toString().toUpperCase().trim();
+  if (/^(I|C|L|TUBE|BOX)$/.test(explicit)) return explicit;       // explicit section.shape override wins
+  const p = ((el.meta && el.meta.profile) || '').toString().toUpperCase().trim();
+  if (/^(W|M|S|HP|UC|UB|UKC|UKB|IPE|HE)/.test(p)) return 'I';     // wide-flange / I-section
+  if (/^(C|MC|PFC)/.test(p)) return 'C';                          // channel
+  if (/^L/.test(p)) return 'L';                                   // angle
+  if (/^(HSS|PIPE|TS|SHS|RHS|CHS|TUBE|HSQ)/.test(p)) return 'TUBE'; // hollow tube
+  return 'BOX';
+}
+function profileShape(kind, w, d) {
+  const s = new THREE.Shape(), hw = w / 2, hd = d / 2;
+  if (kind === 'I') {
+    const tf = Math.min(d * 0.5, Math.max(d * 0.10, 6)), tw = Math.min(w * 0.5, Math.max(w * 0.10, 5));
+    s.moveTo(-hw, -hd); s.lineTo(hw, -hd); s.lineTo(hw, -hd + tf); s.lineTo(tw / 2, -hd + tf);
+    s.lineTo(tw / 2, hd - tf); s.lineTo(hw, hd - tf); s.lineTo(hw, hd); s.lineTo(-hw, hd);
+    s.lineTo(-hw, hd - tf); s.lineTo(-tw / 2, hd - tf); s.lineTo(-tw / 2, -hd + tf); s.lineTo(-hw, -hd + tf); s.closePath();
+  } else if (kind === 'C') {
+    const tf = Math.max(d * 0.10, 5), tw = Math.max(w * 0.12, 5);
+    s.moveTo(-hw, -hd); s.lineTo(hw, -hd); s.lineTo(hw, -hd + tf); s.lineTo(-hw + tw, -hd + tf);
+    s.lineTo(-hw + tw, hd - tf); s.lineTo(hw, hd - tf); s.lineTo(hw, hd); s.lineTo(-hw, hd); s.closePath();
+  } else if (kind === 'L') {
+    const t = Math.max(Math.min(w, d) * 0.18, 5);
+    s.moveTo(-hw, -hd); s.lineTo(hw, -hd); s.lineTo(hw, -hd + t); s.lineTo(-hw + t, -hd + t); s.lineTo(-hw + t, hd); s.lineTo(-hw, hd); s.closePath();
+  } else if (kind === 'TUBE') {
+    const t = Math.max(Math.min(w, d) * 0.12, 4);
+    s.moveTo(-hw, -hd); s.lineTo(hw, -hd); s.lineTo(hw, hd); s.lineTo(-hw, hd); s.closePath();
+    const h = new THREE.Path(); h.moveTo(-hw + t, -hd + t); h.lineTo(hw - t, -hd + t); h.lineTo(hw - t, hd - t); h.lineTo(-hw + t, hd - t); h.closePath(); s.holes.push(h);
+  } else { s.moveTo(-hw, -hd); s.lineTo(hw, -hd); s.lineTo(hw, hd); s.lineTo(-hw, hd); s.closePath(); }
+  return s;
+}
+function memberGeom(el, w, d, len) {
+  const kind = shapeOf(el);
+  if (kind === 'BOX') return new THREE.BoxGeometry(w, len, d);                  // length on local Y
+  const g = new THREE.ExtrudeGeometry(profileShape(kind, w, d), { depth: len, bevelEnabled: false });
+  g.translate(0, 0, -len / 2); return g;                                        // extruded +Z, centred
+}
+const _ZA = new THREE.Vector3(0, 0, 1), _YA = new THREE.Vector3(0, 1, 0);
+// NOTE vs AWARE viewer-3d: AWARE converts the Z-up scene into Three's Y-up world before orienting, so
+// its roll targets world-Y. We render the scene NATIVELY Z-up (camera.up=Z), so the roll must target
+// world-Z (_ZA) — else the web rolls flat (horizontal) instead of standing vertical.
+function orientMember(mesh, dir) {
+  const m = dir.clone().normalize();
+  if (mesh.geometry.type === 'BoxGeometry') { mesh.quaternion.setFromUnitVectors(_YA, m); return; } // length on local Y
+  const q = new THREE.Quaternion().setFromUnitVectors(_ZA, m);                  // member axis = extrude (local Z)
+  const proj = _ZA.clone().sub(m.clone().multiplyScalar(_ZA.dot(m)));           // world-UP (Z) perpendicular to member
+  if (proj.lengthSq() > 1e-6) {
+    proj.normalize();
+    const ly = _YA.clone().applyQuaternion(q);                                  // where the section depth (local Y) points
+    const ang = Math.atan2(ly.clone().cross(proj).dot(m), ly.dot(proj));
+    q.premultiply(new THREE.Quaternion().setFromAxisAngle(m, ang));            // roll so the web stands vertical (depth → world-Z)
+  }
+  mesh.quaternion.copy(q);
+}
+// Build the member's geometry (real cross-section) from a→b and orient + centre it.
+function placeMember(mesh, a, b, el) {
+  const A = V(a[0], a[1], a[2]), B = V(b[0], b[1], b[2]);
+  const dir = new THREE.Vector3().subVectors(B, A); const len = dir.length() || 1; dir.normalize();
+  const w = Math.max((el.section && el.section.w) || 50, 1), d = Math.max((el.section && el.section.d) || 50, 1);
+  mesh.geometry = memberGeom(el, w, d, len);
+  orientMember(mesh, dir);
+  mesh.position.copy(A).addScaledVector(dir, len / 2);
+}
+
+function materialFor(groupKey) {
+  if (!baseMat.has(groupKey)) {
+    const col = groupColor.get(groupKey) || new THREE.Color(0x94a3b8);
+    baseMat.set(groupKey, new THREE.MeshStandardMaterial({ color: col, metalness: 0.1, roughness: 0.75 }));
+  }
+  return baseMat.get(groupKey);
+}
+
+function clearRoot() {
+  for (const m of meshById.values()) {
+    m.geometry.dispose();
+    if (m.userData._selMat) m.userData._selMat.dispose(); // per-mesh selection clone (else it leaks per rebuild)
+    root.remove(m);
+  }
+  meshById.clear();
+}
+
+function buildFromScene(sc) {
+  clearRoot();
+  for (const mat of baseMat.values()) mat.dispose(); // shared per-profile materials from the prior build
+  groupColor.clear(); baseMat.clear();
+  for (const g of sc.groups || []) groupColor.set(g.key, new THREE.Color(g.color || '#94a3b8'));
+  const box = new THREE.Box3();
+  for (const el of sc.elements || []) {
+    const mesh = new THREE.Mesh(undefined, materialFor(el.group));
+    placeMember(mesh, el.from, el.to, el); // real cross-section (I / channel / angle / tube / box) from the profile
+    mesh.userData.id = el.id; mesh.userData.group = el.group; // group needed to restore the profile material on deselect
+    root.add(mesh); meshById.set(el.id, mesh);
+    box.expandByObject(mesh);
+  }
+  buildGrid(box);
+  built = true;
+  if (fitPending || !box.isEmpty()) { fitCamera(box); fitPending = false; }
+}
+
+// A muted reference grid on the ground plane (XY, since Z-up), sized to the model. --line at low
+// opacity — no white grid (per the baseline). Rebuilt with the model so it always fits.
+function buildGrid(box) {
+  if (grid) { scene.remove(grid); grid.geometry.dispose(); grid.material.dispose(); grid = null; }
+  if (box.isEmpty()) return;
+  const size = box.getSize(new THREE.Vector3());
+  const span = Math.max(size.x, size.y) * 1.6 || 5000;
+  grid = new THREE.GridHelper(span, 24, 0x1e293b, 0x1e293b); // --line (slate-800)
+  grid.material.transparent = true; grid.material.opacity = 0.35;
+  grid.rotation.x = Math.PI / 2;                              // GridHelper is XZ by default → rotate to XY for Z-up
+  const c = box.getCenter(new THREE.Vector3());
+  grid.position.set(c.x, c.y, box.min.z);                     // ground at the lowest member
+  scene.add(grid);
+}
+
+function fitCamera(box) {
+  if (box.isEmpty()) return;
+  const c = box.getCenter(new THREE.Vector3());
+  const dir = new THREE.Vector3(0.55, -0.8, 0.5).normalize(); // 3/4 iso: front-right-above (Z-up)
+  // Build the camera's right/up axes for this view direction, then size the distance so the WIDEST
+  // box corner (projected onto right/up) fits the frustum. Projecting corners (not a bounding sphere)
+  // fits a flat plan tightly — a sphere over-zooms because it ignores that the slab is thin.
+  const fwd = dir.clone().negate();
+  const up0 = Math.abs(fwd.z) > 0.95 ? V(0, 1, 0) : V(0, 0, 1);
+  const right = new THREE.Vector3().crossVectors(up0, fwd).normalize();
+  const up = new THREE.Vector3().crossVectors(fwd, right).normalize();
+  const tanV = Math.tan(THREE.MathUtils.degToRad(camera.fov) / 2), tanH = tanV * camera.aspect;
+  let need = 1000;
+  for (let i = 0; i < 8; i++) {
+    const corner = V(i & 1 ? box.max.x : box.min.x, i & 2 ? box.max.y : box.min.y, i & 4 ? box.max.z : box.min.z).sub(c);
+    need = Math.max(need, Math.abs(corner.dot(right)) / tanH, Math.abs(corner.dot(up)) / tanV);
+  }
+  const dist = need * 1.15; // small margin
+  controls.target.copy(c);
+  camera.position.copy(c).addScaledVector(dir, dist);
+  const r = box.getBoundingSphere(new THREE.Sphere()).radius || dist;
+  camera.near = Math.max(dist / 1000, 1); camera.far = dist + r * 4; camera.updateProjectionMatrix();
+  controls.update();
+}
+
+async function rebuild() {
+  if (!api) return;
+  const sc = await api.fetchScene();   // editor POSTs the current contract to /scene
+  if (sc) buildFromScene(sc);
+}
+
+function setSelection(ids) {
+  const set = ids instanceof Set ? ids : new Set(ids || []);
+  for (const [id, mesh] of meshById) {
+    const on = set.has(id);
+    // Selected → a per-mesh clone that glows (so one selected member doesn't tint its whole profile
+    // group). Deselected → back to the SHARED profile material (its real colour).
+    mesh.material = on ? selectedMaterial(mesh) : materialFor(mesh.userData.group);
+    mesh.material.emissive = new THREE.Color(on ? SELECT_EMISSIVE : 0x000000);
+    mesh.material.emissiveIntensity = on ? 0.6 : 0;
+  }
+}
+function selectedMaterial(mesh) {
+  if (!mesh.userData._selMat) mesh.userData._selMat = materialFor(mesh.userData.group).clone();
+  return mesh.userData._selMat;
+}
+
+// Raycast the member meshes at a client (px) point → the hit member id, or null for empty space.
+function pickAt(cx, cy) {
+  camera.updateMatrixWorld(); root.updateMatrixWorld(true); // ensure current after any camera/mesh move
+  const rect = canvasEl.getBoundingClientRect();
+  const ndc = new THREE.Vector2(((cx - rect.left) / rect.width) * 2 - 1, -((cy - rect.top) / rect.height) * 2 + 1);
+  raycaster.setFromCamera(ndc, camera);
+  const hits = raycaster.intersectObjects([...meshById.values()], false);
+  lastPick = hits.length ? hits[0].object.userData.id : null;
+  return lastPick;
+}
+
+// project a 3D mm point → canvas-relative screen px (for screen-space snapping + the marker)
+function toScreen(p) {
+  const v = new THREE.Vector3(p[0], p[1], p[2]).project(camera);
+  const rect = canvasEl.getBoundingClientRect();
+  return { x: (v.x * 0.5 + 0.5) * rect.width, y: (-v.y * 0.5 + 0.5) * rect.height };
+}
+// raycast the cursor onto the horizontal work-plane z=planeZ → [x,y,z] mm, or null
+function rayToPlane(cx, cy, planeZ) {
+  camera.updateMatrixWorld();
+  const rect = canvasEl.getBoundingClientRect();
+  if (!rect.width || !rect.height) return null; // collapsed/hidden canvas → no valid ray
+  const ndc = new THREE.Vector2(((cx - rect.left) / rect.width) * 2 - 1, -((cy - rect.top) / rect.height) * 2 + 1);
+  raycaster.setFromCamera(ndc, camera);
+  const hit = new THREE.Vector3();
+  return raycaster.ray.intersectPlane(new THREE.Plane(new THREE.Vector3(0, 0, 1), -planeZ), hit) ? [hit.x, hit.y, hit.z] : null;
+}
+// raycast onto a VERTICAL plane through `thru` facing the camera (its normal is the camera's
+// horizontal direction) → [x,y,z]; the z is the new elevation for a vertical drag.
+function rayToVerticalPlane(cx, cy, thru) {
+  camera.updateMatrixWorld();
+  const rect = canvasEl.getBoundingClientRect(); if (!rect.width || !rect.height) return null;
+  const ndc = new THREE.Vector2(((cx - rect.left) / rect.width) * 2 - 1, -((cy - rect.top) / rect.height) * 2 + 1);
+  raycaster.setFromCamera(ndc, camera);
+  const n = new THREE.Vector3(); camera.getWorldDirection(n); n.z = 0;
+  if (n.lengthSq() < 1e-9) n.set(1, 0, 0); n.normalize();
+  const plane = new THREE.Plane().setFromNormalAndCoplanarPoint(n, new THREE.Vector3(thru[0], thru[1], thru[2]));
+  const hit = new THREE.Vector3();
+  return raycaster.ray.intersectPlane(plane, hit) ? [hit.x, hit.y, hit.z] : null;
+}
+const members = () => (api && api.getMembers && api.getMembers()) || [];
+const markerSize = () => Math.max(camera.position.distanceTo(controls.target) * 0.012, 10);
+
+function onDown(e) {
+  if (e.button !== 0) return;
+  downXY = [e.clientX, e.clientY];
+  let id = null; try { id = pickAt(e.clientX, e.clientY); } catch { id = null; }
+  if (!id) { pending = null; return; }          // empty space → OrbitControls orbits/pans
+  e.stopPropagation(); controls.enabled = false; // grabbed a member → suppress orbit (enabled=false is the reliable guard)
+  try {
+    const m = members().find((x) => x.id === id);
+    const ppf = api.ptPerFt(), dtos = api.defaultTosMm();
+    const geo = m ? memberGeometry(m, ppf, dtos) : null;
+    const mesh = meshById.get(id);
+    const planeZ = geo ? (geo.line[0][2] + geo.line[1][2]) / 2 : 0;
+    pending = {
+      id, ctrl: e.ctrlKey || e.metaKey, ppf, planeZ,
+      grab: geo ? rayToPlane(e.clientX, e.clientY, planeZ) : null,
+      origMm: geo ? geo.line.map((p) => [p[0], p[1], p[2]]) : null,
+      candidates: snapCandidates(members(), ppf, dtos, id),
+      levels: elevationLevels(members(), ppf, dtos, id), // Alt-drag (vertical) snaps to these T.O.S levels
+      mesh, meshPos0: mesh ? mesh.position.clone() : null, delta: null, mode: null,
+    };
+  } catch (err) { controls.enabled = true; pending = null; } // a failure must never strand orbit disabled
+}
+
+// Vertical (Alt) drag: raise/lower the member's elevation, snapping to other members' T.O.S levels.
+function onMoveVertical(e) {
+  const hit = rayToVerticalPlane(e.clientX, e.clientY, pending.grab); if (!hit) return;
+  const gx = pending.grab[0], gy = pending.grab[1];
+  const cands = pending.levels.map((z) => ({ type: 'level', p: [gx, gy, z] })); // levels as point candidates at the grab plan X/Y
+  const r = snapPoint([gx, gy, hit[2]], cands, toScreen, SNAP_TOL_PX);
+  const newZ = r.candidate ? r.snapped[2] : hit[2];
+  pending.dz = newZ - pending.planeZ;
+  if (pending.mesh && pending.meshPos0) pending.mesh.position.set(pending.meshPos0.x, pending.meshPos0.y, pending.meshPos0.z + pending.dz);
+  if (r.candidate) { marker.position.set(gx, gy, newZ); marker.scale.setScalar(markerSize()); marker.visible = true; } else marker.visible = false;
+  readout._dist.textContent = (newZ / FT_MM).toFixed(2) + ' ft'; // resulting T.O.S elevation
+  readout._type.textContent = r.candidate ? ' · level' : ' ↕';
+  readout.style.left = (e.clientX + 14) + 'px'; readout.style.top = (e.clientY + 14) + 'px'; readout.style.display = 'block';
+}
+
+function onMove(e) {
+  if (!renderer || !canvasEl || canvasEl.style.display === 'none') return; // 3D inactive — ignore window pointer events
+  if (!pending || !pending.grab || !pending.origMm) return;
+  if (!dragging && Math.hypot(e.clientX - downXY[0], e.clientY - downXY[1]) <= DRAG_TOL_PX) return;
+  if (!dragging) pending.mode = e.altKey ? 'vertical' : 'plan'; // lock the mode at drag start (Alt = vertical/elevation)
+  dragging = pending;
+  if (pending.mode === 'vertical') { onMoveVertical(e); return; }
+  const cur = rayToPlane(e.clientX, e.clientY, pending.planeZ); if (!cur) return;
+  let dx = cur[0] - pending.grab[0], dy = cur[1] - pending.grab[1];
+  // snap the translated endpoints; take the closest winning correction
+  let best = Infinity, corr = null, at = null, atType = null;
+  for (const ep of pending.origMm) {
+    const tp = [ep[0] + dx, ep[1] + dy, ep[2]];
+    const r = snapPoint(tp, pending.candidates, toScreen, SNAP_TOL_PX);
+    if (!r.candidate) continue;
+    const a = toScreen(tp), b = toScreen(r.snapped), d = Math.hypot(b.x - a.x, b.y - a.y);
+    if (d < best) { best = d; corr = [r.snapped[0] - tp[0], r.snapped[1] - tp[1]]; at = r.snapped; atType = r.candidate.type; }
+  }
+  if (corr) { dx += corr[0]; dy += corr[1]; }
+  pending.delta = [dx, dy];
+  if (pending.mesh && pending.meshPos0) pending.mesh.position.set(pending.meshPos0.x + dx, pending.meshPos0.y + dy, pending.meshPos0.z);
+  if (at) { marker.position.set(at[0], at[1], at[2]); marker.scale.setScalar(markerSize()); marker.visible = true; } else marker.visible = false;
+  // live dimension readout: plan distance moved (feet) + the snap type, near the cursor
+  readout._dist.textContent = (Math.hypot(dx, dy) / FT_MM).toFixed(2) + ' ft';
+  readout._type.textContent = atType ? ' · ' + atType : '';
+  readout.style.left = (e.clientX + 14) + 'px'; readout.style.top = (e.clientY + 14) + 'px'; readout.style.display = 'block';
+}
+
+function onUp(e) {
+  if (marker) marker.visible = false; if (readout) readout.style.display = 'none'; // always clear drag overlays, even on the early-return paths
+  if (!renderer || !canvasEl || canvasEl.style.display === 'none') { downXY = null; return; } // 3D inactive
+  const p = pending, wasDragging = dragging; pending = dragging = null;
+  controls.enabled = true;
+  const moved = downXY ? Math.hypot(e.clientX - downXY[0], e.clientY - downXY[1]) : Infinity; downXY = null;
+  if (!p) { // empty-space gesture: a click (no move) clears the selection
+    if (moved <= DRAG_TOL_PX && api && api.onSelect) api.onSelect(null, false);
+    return;
+  }
+  if (!wasDragging) { if (api && api.onSelect) api.onSelect(p.id, p.ctrl); return; } // member click → select
+  if (p.mode === 'vertical') { // elevation drag → write T.O.S (inches)
+    if (p.dz && Math.abs(p.dz) > 1e-6) {
+      if (api && api.onSelect) api.onSelect(p.id, false);
+      if (api && api.onElevateMember) api.onElevateMember(p.id, p.dz / 25.4); // mm → inches
+    }
+    return;
+  }
+  if (!p.delta || (p.delta[0] === 0 && p.delta[1] === 0)) return;                    // dragged but no net move
+  const newWp = p.origMm.map((mm) => planPointToWp([mm[0] + p.delta[0], mm[1] + p.delta[1]], p.ppf));
+  if (api && api.onSelect) api.onSelect(p.id, false);                                // keep the moved member selected
+  if (api && api.onMoveMember) api.onMoveMember(p.id, newWp);                         // editor writes wp via edit()
+}
+
+function show() { if (canvasEl) { canvasEl.style.display = 'block'; resize(); } if (!rafId) loop(); } // resume the render loop
+function hide() { if (canvasEl) canvasEl.style.display = 'none'; if (rafId) { cancelAnimationFrame(rafId); rafId = null; } } // stop rendering while in 2D
+function isReady() { return built; }
+
+function dispose() {
+  if (rafId) cancelAnimationFrame(rafId);
+  if (ro) ro.disconnect();
+  if (canvasEl) canvasEl.removeEventListener('pointerdown', onDown, true);
+  window.removeEventListener('pointermove', onMove);
+  window.removeEventListener('pointerup', onUp);
+  if (readout && readout.parentNode) readout.parentNode.removeChild(readout);
+  clearRoot();
+  if (renderer) renderer.dispose();
+  renderer = scene = camera = controls = root = api = canvasEl = ro = null; built = false;
+}
+
+function debug() {
+  const box = new THREE.Box3(); for (const m of meshById.values()) box.expandByObject(m);
+  const s = box.getSize(new THREE.Vector3()), c = box.getCenter(new THREE.Vector3());
+  return {
+    meshes: meshById.size,
+    triangles: renderer ? renderer.info.render.triangles : -1,
+    bboxEmpty: box.isEmpty(), bboxSize: [s.x, s.y, s.z], bboxCenter: [c.x, c.y, c.z],
+    firstId: meshById.keys().next().value ?? null,
+    ids: [...meshById.keys()].slice(0, 12),
+    geomTypes: [...meshById.values()].reduce((h, m) => { const t = m.geometry.type; h[t] = (h[t] || 0) + 1; return h; }, {}),
+    lastPick,
+    camPos: camera ? [camera.position.x, camera.position.y, camera.position.z] : null,
+    near: camera?.near, far: camera?.far,
+  };
+}
+// test helper: the current material colour + emissive of a member (verifies deselect restores colour)
+function probe(id) {
+  const m = meshById.get(id); if (!m) return null;
+  return { color: '#' + m.material.color.getHexString(), emissive: m.material.emissiveIntensity || 0 };
+}
+// test helper: client (px) coords of a member's endpoint (end 0|1) — lets an E2E drive a precise drag
+function screenOf(id, end) {
+  const m = members().find((x) => x.id === id); if (!m) return null;
+  const g = memberGeometry(m, api.ptPerFt(), api.defaultTosMm());
+  const s = toScreen(g.line[end]); const rect = canvasEl.getBoundingClientRect();
+  return { x: rect.left + s.x, y: rect.top + s.y };
+}
+window.Steel3DView = { init, show, hide, rebuild, setSelection, isReady, debug, probe, screenOf, dispose };