@floless/app 0.62.0 → 0.64.0

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

@@ -17,7 +17,8 @@
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/OrbitControls.js';
 import { Brush, Evaluator, SUBTRACTION } from 'three-bvh-csg';
-import { snapCandidates, snapPoint, planPointToWp, memberGeometry, elevationLevels, dim3dGeom } from './steel-3d-core.js';
+import { snapCandidates, snapPoint, planPointToWp, memberGeometry, elevationLevels, dim3dGeom, planeBasis, projectToPlane, planeFrom3Points, vecToPlane } from './steel-3d-core.js';
+import { gridGeometry, gridCandidates3d, mmPerPx } from './grid-core.js';
 
 let renderer, scene, perspCam, orthoCam, 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
@@ -279,6 +280,43 @@ function placePlate(mesh, el) {
   mesh.position.set(...(el.center || [0, 0, 0]));
 }
 
+// Signed area of a closed 2D polygon (shoelace) — used to reject a zero-area/collinear footprint.
+function shoelaceArea(pts) {
+  let a = 0;
+  for (let i = 0, n = pts.length; i < n; i++) {
+    const p = pts[i], q = pts[(i + 1) % n];
+    a += p[0] * q[1] - q[0] * p[1];
+  }
+  return a / 2;
+}
+
+// A vertical extrusion of an arbitrary world-XY footprint between two Z values — the multi-view
+// reconstruction's generic body (a plate, wall or slab read from a plan + elevation; see
+// server/views-to-scene.ts). Same ExtrudeGeometry recipe as placePlate, but the outline is the
+// element's own polygon in WORLD coordinates and the sweep is always +Z, so no basis rotation.
+function placeExtrusion(mesh, el) {
+  const fp = el.footprint || [];
+  // Reject a degenerate outline (fewer than 3 vertices, or a zero-area collinear loop by the
+  // shoelace test) — ExtrudeGeometry on it produces a NaN/empty body, not an honest shape.
+  if (fp.length < 3 || Math.abs(shoelaceArea(fp)) < 1e-6) { mesh.geometry = new THREE.BufferGeometry(); return; }
+  const shape = new THREE.Shape();
+  shape.moveTo(fp[0][0], fp[0][1]);
+  for (let i = 1; i < fp.length; i++) shape.lineTo(fp[i][0], fp[i][1]);
+  shape.closePath();
+  for (const h of el.holes || []) { // optional opening loops (same world-XY polygon form)
+    if (!h || h.length < 3) continue;
+    const hole = new THREE.Path();
+    hole.moveTo(h[0][0], h[0][1]);
+    for (let i = 1; i < h.length; i++) hole.lineTo(h[i][0], h[i][1]);
+    hole.closePath();
+    shape.holes.push(hole);
+  }
+  const z0 = Math.min(el.from || 0, el.to || 0), z1 = Math.max(el.from || 0, el.to || 0);
+  mesh.geometry = new THREE.ExtrudeGeometry(shape, { depth: Math.max(z1 - z0, 0.5), bevelEnabled: false });
+  mesh.quaternion.identity();
+  mesh.position.set(0, 0, z0); // the shape carries world XY; lift the slab to its bottom face
+}
+
 // A cylinder between two points (anchor rod / bolt shank).
 function placeBar(mesh, a, b, r, radial) {
   const A = V(a[0], a[1], a[2]), B = V(b[0], b[1], b[2]);
@@ -330,6 +368,7 @@ function placeWasher(mesh, el) {
 function placeElement(mesh, el) {
   switch (el.kind || 'box') {
     case 'box': placeMember(mesh, el.from, el.to, el); return true;
+    case 'extrusion': placeExtrusion(mesh, el); return true;
     case 'plate': placePlate(mesh, el); return true;
     case 'rod': placeBar(mesh, el.from, el.to, Math.max((el.d || 20) / 2, 0.5), 16); return true;
     case 'nut': placeNut(mesh, el); return true;
@@ -455,6 +494,7 @@ function buildFromScene(sc) {
   dimParts = (sc.elements || []).filter((el) => el && (el.kind === 'plate' || el.kind === 'cut'));
   renderClipGizmo();   // re-anchor the selected clip's gizmo to the (possibly new) sceneBox after a rebuild
   buildGrid(box);
+  buildStructGrid();
   buildRefLines();
   if (isolatedIds) { isolatedIds = new Set([...isolatedIds].filter((id) => meshById.has(id))); if (!isolatedIds.size) { isolatedIds = null; if (api && api.onIsolateChange) api.onIsolateChange(false); } } // drop ids an edit removed; if none survive, exit isolation + refresh the host's Show-all button
   if (connHidden.size) connHidden = new Set([...connHidden].filter((id) => meshById.has(id)));   // drop per-part hides whose mesh an edit removed
@@ -496,6 +536,97 @@ function buildRefLines() {
 }
 function setRefLine(on) { refLineOn = !!on; buildRefLines(); }
 
+// ---- structural grid (Tekla-style): dashed lines per Z level live in the SCENE (so clips section
+// them, like Tekla); the label bubbles + level tags are sprites in the UNCLIPPED overlay pass, so the
+// wayfinding survives sectioning/work-area (the UX review's clip-regression guard). Data comes from
+// the contract via api.getGrid() (grid-core owns parsing/geometry); allCandidates() feeds the same
+// grid into snapping, plan-locked.
+let structGridGroup = null, gridLabelGroup = null;
+const gridTexCache = new Map(); // 'b:LABEL' bubble / 't:LABEL' tag -> CanvasTexture (kept until dispose)
+
+function allCandidates(excludeId) {
+  const base = snapCandidates(members(), api.ptPerFt(), api.defaultTosMm(), excludeId);
+  try { return base.concat(gridCandidates3d(api.getGrid ? api.getGrid() : null, api.ptPerFt())); }
+  catch { return base; } // a malformed hand-edited grid must never break member dragging
+}
+
+function gridBubbleTexture(label) {
+  const key = 'b:' + label;
+  if (gridTexCache.has(key)) return gridTexCache.get(key);
+  const S = 128, cv = document.createElement('canvas'); cv.width = cv.height = S;
+  const g = cv.getContext('2d');
+  g.beginPath(); g.arc(S / 2, S / 2, S / 2 - 5, 0, Math.PI * 2);
+  g.fillStyle = '#0f172a'; g.fill();
+  g.lineWidth = 5; g.strokeStyle = '#64748b'; g.stroke();
+  g.fillStyle = '#e2e8f0'; g.font = 'bold ' + (label.length > 2 ? 44 : 58) + 'px system-ui';
+  g.textAlign = 'center'; g.textBaseline = 'middle';
+  g.fillText(label, S / 2, S / 2 + 3);
+  const tex = new THREE.CanvasTexture(cv);
+  gridTexCache.set(key, tex);
+  return tex;
+}
+function gridTagTexture(label) {
+  const key = 't:' + label;
+  if (gridTexCache.has(key)) return gridTexCache.get(key);
+  const W = 256, H = 80, cv = document.createElement('canvas'); cv.width = W; cv.height = H;
+  const g = cv.getContext('2d');
+  g.beginPath(); g.roundRect(4, 4, W - 8, H - 8, 14);
+  g.fillStyle = '#0f172a'; g.fill();
+  g.lineWidth = 4; g.strokeStyle = '#64748b'; g.stroke();
+  g.fillStyle = '#94a3b8'; g.font = 'bold 40px system-ui';
+  g.textAlign = 'center'; g.textBaseline = 'middle';
+  g.fillText(label, W / 2, H / 2 + 2);
+  const tex = new THREE.CanvasTexture(cv);
+  gridTexCache.set(key, tex);
+  return tex;
+}
+function clearStructGrid() {
+  for (const [grp, parent] of [[structGridGroup, scene], [gridLabelGroup, overlayScene]]) {
+    if (!grp) continue;
+    for (const o of [...grp.children]) { grp.remove(o); if (o.geometry) o.geometry.dispose(); if (o.material) o.material.dispose(); } // sprite materials are per-sprite; textures stay cached
+    if (parent) parent.remove(grp);
+  }
+  structGridGroup = gridLabelGroup = null;
+}
+function buildStructGrid() {
+  clearStructGrid();
+  if (!api || !api.getGrid || !scene) return;
+  let g = null, geo = null;
+  try { g = api.getGrid(); if (!g || g.on === false) return; geo = gridGeometry(g, api.ptPerFt()); }
+  catch (e) { console.warn('[steel-3d] grid skipped (bad grid data)', e); return; }
+  if (!geo.v.length && !geo.h.length) return;
+  const k = mmPerPx(api.ptPerFt());
+  const mmX = (px) => px * k, mmY = (px) => -px * k;                    // display → scene (Y flips)
+  const levels = geo.zs.length ? geo.zs : [{ mm: 0, label: '0' }];
+  const pts = [];
+  for (const lv of levels) {
+    const z = lv.mm - 25;                                               // sit just under the steel at the level (no z-fight/burial)
+    for (const l of geo.v) pts.push(V(mmX(l.x), mmY(l.lo), z), V(mmX(l.x), mmY(l.hi), z));
+    for (const l of geo.h) pts.push(V(mmX(l.lo), mmY(l.y), z), V(mmX(l.hi), mmY(l.y), z));
+  }
+  structGridGroup = new THREE.Group();
+  const seg = new THREE.LineSegments(
+    new THREE.BufferGeometry().setFromPoints(pts),
+    new THREE.LineDashedMaterial({ color: 0x64748b, dashSize: 450, gapSize: 220, transparent: true, opacity: 0.85 }),
+  );
+  seg.computeLineDistances();
+  structGridGroup.add(seg);
+  scene.add(structGridGroup);
+  gridLabelGroup = new THREE.Group();
+  const span = Math.max((geo.x1 - geo.x0) * k, (geo.y1 - geo.y0) * k, 1);
+  const dia = Math.min(Math.max(span * 0.035, 400), 3000);              // bubble ⌀ scales with the grid, clamped sane
+  const z0 = levels[0].mm;
+  const sprite = (tex, x, y, z, w, h) => {
+    const s = new THREE.Sprite(new THREE.SpriteMaterial({ map: tex, depthTest: false, transparent: true }));
+    s.position.set(x, y, z); s.scale.set(w, h, 1); s.renderOrder = 994;
+    gridLabelGroup.add(s);
+  };
+  for (const l of geo.v) { sprite(gridBubbleTexture(l.label), mmX(l.x), mmY(l.lo), z0, dia, dia); sprite(gridBubbleTexture(l.label), mmX(l.x), mmY(l.hi), z0, dia, dia); }
+  for (const l of geo.h) { sprite(gridBubbleTexture(l.label), mmX(l.lo), mmY(l.y), z0, dia, dia); sprite(gridBubbleTexture(l.label), mmX(l.hi), mmY(l.y), z0, dia, dia); }
+  if (geo.zs.length > 1) for (const lv of geo.zs) sprite(gridTagTexture(lv.label), mmX(geo.x0), mmY(geo.y1), lv.mm, dia * 2.4, dia * 0.75); // level tags up the near corner
+  overlayScene.add(gridLabelGroup);
+}
+
 // The ortho frustum half-height in world units (set by a fit to the box, or by a projection toggle
 // to match the current perspective view). reframeOrtho applies it aspect-preserving on resize, so the
 // model never ends up under-framed/"cut-off" in ortho and the user's zoom (orthoCam.zoom) is kept.
@@ -662,6 +793,7 @@ function rebuildClipPlanes(c) {        // recompute a clip's .planes from its ed
 }
 function setClipMode(m) {               // arm/disarm a clip pick: 'plane' (click a face) | 'box' (draw 2 corners) | null
   if (m && dimMode3d) toggleDimTool();
+  if (m) { if (api && api.disarmTransform) api.disarmTransform(); if (api && api.disarmAdd) api.disarmAdd(); cmClear3d(); drClear3d(); }  // clip shares the left-click — disarm Move/Copy + Add so their picks don't steal it (onDown routes them first)
   clipMode = (m === 'plane' || m === 'box') ? m : null;
   clipBoxDraft = null; setClipPreview(null);
   if (canvasEl) canvasEl.style.cursor = clipMode ? 'crosshair' : 'default';
@@ -984,6 +1116,7 @@ function onKey(e) {
   if (!renderer || !canvasEl || canvasEl.style.display === 'none') return;     // only when 3D is active
   const ae = document.activeElement; if (ae && /^(INPUT|SELECT|TEXTAREA)$/.test(ae.tagName)) return;
   if (pending && pending.clipDrag && e.key === 'Escape') { e.preventDefault(); const p = pending; if (p.plane) p.clip.point = p.prePoint; else p.clip.box.copy(p.preBox); rebuildClipPlanes(p.clip); applyClips(); renderClipGizmo(); pending = dragging = null; if (controls) controls.enabled = true; if (readout) readout.style.display = 'none'; return; } // Esc mid-drag → undo the handle move
+  if (wpMode && e.key === 'Escape') { e.preventDefault(); if (wpMode === '3pt' && wpDraft && wpDraft.length) { wpDraft.pop(); updateStatusChip(); } else { wpMode = null; wpDraft = null; marker.visible = false; canvasEl.style.cursor = 'default'; reflectWpBar(); updateStatusChip(); } return; } // Esc steps a 3pt pick back, else disarms the set-plane mode
   if (clipMode && e.key === 'Escape') { e.preventDefault(); if (clipMode === 'box' && clipBoxDraft) { if (clipBoxDraft.b) clipBoxDraft.b = null; else clipBoxDraft = null; setClipPreview(null); updateStatusChip(); } else setClipMode(null); return; } // Esc steps back: height→footprint→cancel, else disarms the pick
   if (isolatedIds && e.key === 'Escape' && !dimMode3d) { e.preventDefault(); clearIsolation(); return; } // Esc exits isolate-selected (the dim tool's own Esc wins while it's armed)
   if ((e.key === ' ' && e.shiftKey) || ((e.key === 'z' || e.key === 'Z') && e.altKey)) { e.preventDefault(); frameSelection(); return; } // zoom-selected (Tekla Shift+Space / viewer Alt+Z)
@@ -997,7 +1130,7 @@ function onKey(e) {
     if (k === 'f' || k === 'x' || k === 'y' || k === 'z') { e.preventDefault(); setDimAxis(k === 'f' ? 'free' : k); reflectDimAxisBar(); return; } // sticky axis: Free / X / Y / Z
   }
   // Named-view shortcuts mirror the ViewCube faces (parity with AWARE viewer-3d): T/F/R/B/L snap to an ortho view.
-  if (VIEW_KEYS[k] && !e.ctrlKey && !e.metaKey && !e.altKey && !e.shiftKey) { e.preventDefault(); applyView(VIEW_KEYS[k]); return; }
+  if (VIEW_KEYS[k] && !cmActive() && !wpMode && !e.ctrlKey && !e.metaKey && !e.altKey && !e.shiftKey) { e.preventDefault(); applyView(VIEW_KEYS[k]); return; }  // while Move/Copy or a set-plane pick is armed, F belongs to the axis force — not the Front view (review finding)
   const a = ARROWS[e.key]; if (!a) return;
   const [hx, hy] = a;
   if (e.ctrlKey || e.metaKey) { e.preventDefault(); rotateView(-hx * Math.PI / 12, hy * Math.PI / 12); }  // 15°
@@ -1008,7 +1141,7 @@ function onKey(e) {
 function toggleDimTool() {
   dimMode3d = !dimMode3d;
   if (!dimMode3d) { dimDraft3d = null; dimCandidates3d = null; dimPreviewLine.visible = false; marker.visible = false; readout.style.display = 'none'; canvasEl.style.cursor = 'default'; }
-  else { if (clipMode) setClipMode(null); controls.enabled = true; canvasEl.style.cursor = 'crosshair'; }  // arming the dim tool disarms the clip pick (they share the left-click + Esc); shows the crosshair before the first mousemove
+  else { if (clipMode) setClipMode(null); if (wpMode) armWorkPlanePick(wpMode); if (api && api.disarmTransform) api.disarmTransform(); if (api && api.disarmAdd) api.disarmAdd(); drClear3d(); controls.enabled = true; canvasEl.style.cursor = 'crosshair'; }  // arming the dim tool disarms the clip pick, a set-plane pick, Move/Copy AND Add-member (all share the left-click + Esc)
   reflectDimBar();
   return dimMode3d;
 }
@@ -1561,6 +1694,234 @@ function rayToVerticalPlane(cx, cy, thru) {
 }
 const members = () => (api && api.getMembers && api.getMembers()) || [];
 const geoMode = () => (api && api.geoMode && api.geoMode()) || null;
+
+// ---- working plane (spec §6): session view-state grounding ALL 3D picks. null = the active plan's
+// level (horizontal at default TOS) — logically always present, only DRAWN when explicitly set. ----
+let workPlane = null;            // {origin:[x,y,z]mm, normal, xAxis} | null
+let wpMode = null;               // 'face' | '3pt' — armed set-plane pick mode
+let wpDraft = null;              // 3pt picks collected so far
+let wpVisible = true;            // "Show plane" toggle (applies to an explicit plane)
+let wpGroup = null;
+function effectiveWP() { return workPlane || { origin: [0, 0, api ? api.defaultTosMm() : 0], normal: [0, 0, 1], xAxis: [1, 0, 0] }; }
+function renderWorkPlane() {
+  if (wpGroup) { scene.remove(wpGroup); wpGroup.traverse((o) => { if (o.geometry) o.geometry.dispose(); if (o.material) o.material.dispose(); }); wpGroup = null; }
+  if (!workPlane || !wpVisible) return;                       // the implicit level plane is not drawn — the 2D plan already communicates it
+  const wp = effectiveWP(), { u, v } = planeBasis(wp.normal, wp.xAxis);
+  const CELL = 1524, N = 12, half = (CELL * N) / 2;           // 12 × 12 cells at 5 ft — a work patch, not an infinite plane
+  const g = new THREE.Group();
+  const verts = [];
+  for (let i = 0; i <= N; i++) { const o = -half + i * CELL; verts.push(o, -half, 0, o, half, 0, -half, o, 0, half, o, 0); }
+  const grid = new THREE.BufferGeometry(); grid.setAttribute('position', new THREE.Float32BufferAttribute(verts, 3));
+  g.add(new THREE.LineSegments(grid, new THREE.LineBasicMaterial({ color: 0x3b82f6, transparent: true, opacity: 0.28 })));
+  const fill = new THREE.Mesh(new THREE.PlaneGeometry(CELL * N, CELL * N), new THREE.MeshBasicMaterial({ color: 0x3b82f6, transparent: true, opacity: 0.09, side: THREE.DoubleSide, depthWrite: false }));
+  g.add(fill);
+  const ax = new THREE.Line(new THREE.BufferGeometry().setFromPoints([new THREE.Vector3(0, 0, 0), new THREE.Vector3(half, 0, 0)]), new THREE.LineBasicMaterial({ color: 0x3b82f6, transparent: true, opacity: 0.9 }));
+  ax.renderOrder = 996; g.add(ax);                            // the brighter ray = the plane's local X
+  const ay = new THREE.Line(new THREE.BufferGeometry().setFromPoints([new THREE.Vector3(0, 0, 0), new THREE.Vector3(0, half / 2, 0)]), new THREE.LineBasicMaterial({ color: 0x3b82f6, transparent: true, opacity: 0.55 }));
+  ay.renderOrder = 996; g.add(ay);                            // the shorter, dimmer ray = local Y (tells the axes apart on a skewed plane)
+  const od = new THREE.Mesh(new THREE.SphereGeometry(60, 12, 8), new THREE.MeshBasicMaterial({ color: 0x3b82f6 }));
+  g.add(od);                                                  // origin dot
+  g.applyMatrix4(new THREE.Matrix4().makeBasis(new THREE.Vector3(...u), new THREE.Vector3(...v), new THREE.Vector3(...wp.normal)));
+  g.position.set(wp.origin[0], wp.origin[1], wp.origin[2]);
+  wpGroup = g; scene.add(g);                                  // on `scene` (like epGroup) so rebuild() never wipes it; not in meshById → picking ignores it
+}
+function reflectWpBar() { const b = document.getElementById('m3dWp'); if (b) { b.classList.toggle('on', !!wpMode || !!workPlane);
+  const kind = workPlane && workPlane.kind ? { face: 'Face', p3: '3pt', xy: 'XY', xz: 'XZ', yz: 'YZ' }[workPlane.kind] || '' : '';
+  b.textContent = wpMode ? '◇ Plane ✕' : (kind ? '◇ Plane: ' + kind + ' ▾' : '◇ Plane ▾'); } }   // the label reads the active plane without opening the menu (ux review)
+function armWorkPlanePick(mode) { if (wpMode === mode) { wpMode = null; wpDraft = null; } else { wpMode = mode; wpDraft = null; if (dimMode3d) toggleDimTool(); if (api && api.disarmTransform) api.disarmTransform(); if (api && api.disarmAdd) api.disarmAdd(); cmClear3d(); drClear3d(); } marker.visible = false; canvasEl.style.cursor = wpMode ? 'crosshair' : 'default'; reflectWpBar(); }  // a set-plane pick shares the left-click — disarm Move/Copy + Add (their onDown routes run first)
+function setWorkPlanePrincipal(kind, offsetMm) {
+  const off = offsetMm || 0;
+  const def = { xy: { normal: [0, 0, 1], xAxis: [1, 0, 0] }, xz: { normal: [0, 1, 0], xAxis: [1, 0, 0] }, yz: { normal: [1, 0, 0], xAxis: [0, 1, 0] } }[kind];
+  if (!def) return;
+  workPlane = { origin: def.normal.map((c) => c * off), normal: def.normal, xAxis: def.xAxis, kind };
+  wpMode = null; wpDraft = null; renderWorkPlane(); reflectWpBar();
+}
+function clearWorkPlane() { workPlane = null; wpMode = null; wpDraft = null; renderWorkPlane(); reflectWpBar(); }
+function toggleWorkPlaneVisible(on) { wpVisible = on === undefined ? !wpVisible : !!on; renderWorkPlane(); }
+function workPlaneInfo() { return { set: !!workPlane, mode: wpMode, visible: wpVisible, plane: workPlane ? { origin: [...workPlane.origin], normal: [...workPlane.normal], xAxis: [...workPlane.xAxis] } : null }; }
+// face pick: the clip tool's raycast, minus the camera-side flip — the plane lands ON the face.
+function wpFacePick(cx, cy) {
+  camera.updateMatrixWorld(); root.updateMatrixWorld(true);
+  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 hit = raycaster.intersectObjects([...meshById.values()].filter((m) => m.visible), false)[0];
+  if (!hit || !hit.face) return null;
+  const n = hit.face.normal.clone().transformDirection(hit.object.matrixWorld).normalize();
+  const b = planeBasis([n.x, n.y, n.z]);
+  return { origin: [hit.point.x, hit.point.y, hit.point.z], normal: [n.x, n.y, n.z], xAxis: b.u, kind: 'face' };
+}
+// ray → the working plane (general orientation) → [x,y,z] mm, or null
+function rayToWP(cx, cy, wp) {
+  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 plane = new THREE.Plane().setFromNormalAndCoplanarPoint(new THREE.Vector3(...wp.normal), new THREE.Vector3(...wp.origin));
+  const hit = new THREE.Vector3();
+  return raycaster.ray.intersectPlane(plane, hit) ? [hit.x, hit.y, hit.z] : null;
+}
+
+// ---- 3D Move/Copy (spec §3+§6): the EDITOR owns the tool state (cmState via api); this side owns
+// picking/preview in scene mm against the working plane, and hands commit offsets back. ----
+let tfDraft = null;              // {base:[mm], vA:[mm]|null}
+let tfLastShift = false;         // shiftKey mirror for the rAF-synthetic hover event
+let tfLast = null;               // last constrained preview point (HUD distance direction)
+let tfLastClient = null;         // last pointer client [x,y] (HUD placement)
+let tfAxis = 'free';             // 'free' | 'u' | 'v' — X/Y force along the plane basis
+let tfCandidates = null;
+let tfGhost = null, tfRubber = null, tfRubberA = null, tfGhostMat = null;
+const cmActive = () => (api && api.cmState ? api.cmState() : null);
+const cmHasBase = () => !!tfDraft;
+const cmLastClient = () => tfLastClient;
+function setCmAxis(a) { tfAxis = a === 'x' ? 'u' : a === 'y' ? 'v' : 'free'; }
+function cmClear3d() { tfDraft = null; tfCandidates = null; tfAxis = 'free'; tfPreviewClear(); if (canvasEl) canvasEl.style.cursor = 'default'; }   // callable BEFORE init() (editor boot) — every touched handle is guarded
+function cmEscape() { if (!tfDraft) return false; if (tfDraft.vA) { tfDraft.vA = null; tfPreviewClear(); return true; } tfDraft = null; tfPreviewClear(); return true; }
+function tfDisposeGhost() { if (!tfGhost) return; if (scene) scene.remove(tfGhost); for (const c of tfGhost.children) { if (c.userData._ownGeom && c.geometry) c.geometry.dispose(); } tfGhost = null; }  // clones share the source geometry/material; only the >600 fallback BoxGeometry is per-ghost → dispose those (flagged _ownGeom) so the preview can't leak
+function tfPreviewClear() { tfDisposeGhost(); if (tfRubber) tfRubber.visible = false; if (tfRubberA) tfRubberA.visible = false; if (marker) marker.visible = false; if (readout) readout.style.display = 'none'; }
+// snapped pick projected onto the working plane (Tekla: snaps win, then land on the plane)
+function wpPointAt(e) {
+  const wp = effectiveWP();
+  const hit = rayToWP(e.clientX, e.clientY, wp); if (!hit) return null;
+  if (!e.altKey) {
+    if (!tfCandidates) tfCandidates = snapCandidates(members(), api.ptPerFt(), api.defaultTosMm());
+    const r = snapPoint(hit, tfCandidates, toScreen, SNAP_TOL_PX);
+    if (r.candidate) return { p: projectToPlane(r.snapped, wp.origin, wp.normal), snap: true, type: r.candidate.type };
+  }
+  return { p: hit, snap: false, type: null };
+}
+// Shift = dominant in-plane axis; X/Y force follows the plane basis (like the 2D local frame)
+function tfConstrain(p, e) {
+  if (!tfDraft) return p;
+  const wp = effectiveWP(), { u, v } = planeBasis(wp.normal, wp.xAxis), b = tfDraft.base;
+  const d = [p[0] - b[0], p[1] - b[1], p[2] - b[2]], c = vecToPlane(d, u, v, wp.normal);
+  let ax = tfAxis;
+  if (e && e.shiftKey) ax = Math.abs(c.du) >= Math.abs(c.dv) ? 'u' : 'v';
+  if (ax === 'u') return [b[0] + c.du * u[0], b[1] + c.du * u[1], b[2] + c.du * u[2]];
+  if (ax === 'v') return [b[0] + c.dv * v[0], b[1] + c.dv * v[1], b[2] + c.dv * v[2]];
+  return p;
+}
+// mirror of the editor's offset builders (mm side): counts INCLUDE the original, grid skips (0,0)
+function tfOffsetsFor(v, st) {
+  const lin = (vec, n) => { const o = []; for (let k = 1; k <= n; k++) o.push([vec[0] * k, vec[1] * k, vec[2] * k]); return o; };
+  if (st.array) {
+    if (!tfDraft.vA) return lin(v, Math.max(0, st.countA - 1));
+    const o = []; for (let i = 0; i < st.countA; i++) for (let j = 0; j < st.countB; j++) { if (!i && !j) continue; o.push([tfDraft.vA[0] * i + v[0] * j, tfDraft.vA[1] * i + v[1] * j, tfDraft.vA[2] * i + v[2] * j]); } return o;
+  }
+  return st.tool === 'copy' ? lin(v, st.count) : [v];
+}
+function tfGhostBuild(offs) {
+  tfDisposeGhost();                                            // dispose the previous rebuild's own geometries (the >600 boxes) before dropping it
+  tfGhost = new THREE.Group();
+  if (!tfGhostMat) { tfGhostMat = new THREE.MeshBasicMaterial({ color: 0x3b82f6, transparent: true, opacity: 0.3, depthWrite: false }); }
+  const sel = [...selIds].map((id) => meshById.get(id)).filter((m) => m && m.visible);
+  if (sel.length * offs.length <= 600) {
+    for (const off of offs) for (const m of sel) {
+      const c = new THREE.Mesh(m.geometry, tfGhostMat);       // shares the source geometry — nothing to dispose
+      c.applyMatrix4(m.matrixWorld); c.position.x += off[0]; c.position.y += off[1]; c.position.z += off[2];
+      tfGhost.add(c);
+    }
+  } else {
+    const bb = new THREE.Box3(); for (const m of sel) bb.expandByObject(m);
+    const size = bb.getSize(new THREE.Vector3()), ctr = bb.getCenter(new THREE.Vector3());
+    const boxGeom = new THREE.BoxGeometry(size.x, size.y, size.z);   // ONE shared box for all fallback ghosts this rebuild
+    for (const off of offs) { const h = new THREE.Mesh(boxGeom, tfGhostMat); h.position.set(ctr.x + off[0], ctr.y + off[1], ctr.z + off[2]); tfGhost.add(h); }
+    if (tfGhost.children[0]) tfGhost.children[0].userData._ownGeom = true;   // dispose the shared box once via the first child on the next clear
+  }
+  scene.add(tfGhost);
+}
+function tfPreview(e) {
+  const st = cmActive(); if (!st || !tfDraft) return;
+  const r = wpPointAt(e); if (!r) return;
+  const p = tfConstrain(r.p, e);
+  tfLast = p; tfLastClient = [e.clientX, e.clientY];
+  if (r.snap && tfAxis === 'free' && !e.shiftKey) { marker.position.set(p[0], p[1], p[2]); marker.scale.setScalar(markerSize()); marker.visible = true; } else marker.visible = false;
+  const v = [p[0] - tfDraft.base[0], p[1] - tfDraft.base[1], p[2] - tfDraft.base[2]];
+  tfGhostBuild(tfOffsetsFor(v, st));
+  if (!tfRubber) { tfRubber = new THREE.Line(new THREE.BufferGeometry().setFromPoints([new THREE.Vector3(), new THREE.Vector3()]), new THREE.LineBasicMaterial({ color: 0x22d3ee })); tfRubber.material.depthTest = false; tfRubber.renderOrder = 997; scene.add(tfRubber); }
+  tfRubber.geometry.setFromPoints([new THREE.Vector3(...tfDraft.base), new THREE.Vector3(...p)]);
+  tfRubber.visible = true;
+  if (st.array && tfDraft.vA) {
+    if (!tfRubberA) { tfRubberA = new THREE.Line(new THREE.BufferGeometry().setFromPoints([new THREE.Vector3(), new THREE.Vector3()]), new THREE.LineBasicMaterial({ color: 0x22d3ee, transparent: true, opacity: 0.35 })); tfRubberA.material.depthTest = false; tfRubberA.renderOrder = 997; scene.add(tfRubberA); }
+    tfRubberA.geometry.setFromPoints([new THREE.Vector3(...tfDraft.base), new THREE.Vector3(tfDraft.base[0] + tfDraft.vA[0], tfDraft.base[1] + tfDraft.vA[1], tfDraft.base[2] + tfDraft.vA[2])]);
+    tfRubberA.visible = true;
+  }
+  const L = Math.hypot(v[0], v[1], v[2]);
+  readout._dist.textContent = api.fmtLen ? api.fmtLen(L) : (L / FT_MM).toFixed(2) + ' ft';
+  readout._type.textContent = r.snap ? ' · ' + (r.type || 'snap') : (st.tool === 'copy' && !st.array && st.count > 1 ? ' ×' + st.count : '');
+  readout.style.left = (e.clientX + 14) + 'px'; readout.style.top = (e.clientY + 14) + 'px'; readout.style.display = 'block';
+}
+function tfClick(e) {
+  const st = cmActive(); if (!st) return false;
+  if (!selIds.size) {                                        // selection drained while armed (undo/delete) — end the tool and let the click SELECT instead
+    if (api && api.toast) api.toast('Selection is empty — ' + (st.tool === 'move' ? 'Move' : 'Copy') + ' ended');
+    if (api && api.disarmTransform) api.disarmTransform();
+    return false;
+  }
+  const r = wpPointAt(e); if (!r) return true;
+  const p = tfConstrain(r.p, e);
+  tfLastClient = [e.clientX, e.clientY];
+  if (!tfDraft) { tfDraft = { base: p, vA: null }; tfCandidates = null; tfLast = p; return true; }
+  const v = [p[0] - tfDraft.base[0], p[1] - tfDraft.base[1], p[2] - tfDraft.base[2]];
+  if (Math.hypot(v[0], v[1], v[2]) < 5) return true;         // ~zero pick (5 mm) — ignore, like the 2D 0.5 px guard
+  if (st.array && !tfDraft.vA) { tfDraft.vA = v; return true; }
+  const offs = tfOffsetsFor(v, st);
+  if (!offs.length) { if (api && api.toast) api.toast(st.array ? 'A 1 × 1 array places no copies — raise a count' : 'Nothing to place'); tfDraft = null; tfPreviewClear(); return true; }
+  api.onTransform3d(offs);
+  tfDraft = null; tfPreviewClear();
+  return true;
+}
+// HUD hand-off: the editor parses (inches), we turn it into a plane-space vector and run the same flow.
+function cmHudApply(pv) {
+  const st = cmActive(); if (!st || !tfDraft) return { err: 'Pick a base point first' };
+  const wp = effectiveWP(), { u, v: vv } = planeBasis(wp.normal, wp.xAxis);
+  let v;
+  if (pv.comp) { const IN = 25.4, du = pv.comp[0] * IN, dv = pv.comp[1] * IN, dn = (pv.comp[2] || 0) * IN;
+    v = [du * u[0] + dv * vv[0] + dn * wp.normal[0], du * u[1] + dv * vv[1] + dn * wp.normal[1], du * u[2] + dv * vv[2] + dn * wp.normal[2]]; }
+  else { if (!tfLast) return { err: 'Move the mouse to aim, or type dx,dy' };
+    const dir = [tfLast[0] - tfDraft.base[0], tfLast[1] - tfDraft.base[1], tfLast[2] - tfDraft.base[2]];
+    const L = Math.hypot(dir[0], dir[1], dir[2]); if (L < 1e-6) return { err: 'Move the mouse to aim, or type dx,dy' };
+    const d = pv.dist * 25.4; v = [dir[0] / L * d, dir[1] / L * d, dir[2] / L * d]; }
+  if (Math.hypot(v[0], v[1], v[2]) < 5) return { err: 'Zero distance — type a non-zero value' };
+  if (st.array && !tfDraft.vA) { tfDraft.vA = v; tfPreviewClear(); return { ok: true, staged: true }; }
+  const offs = tfOffsetsFor(v, st);
+  if (!offs.length) { tfDraft = null; tfPreviewClear(); return { err: st.array ? 'A 1 × 1 array places no copies — raise a count' : 'Nothing to place' }; }
+  api.onTransform3d(offs);
+  tfDraft = null; tfPreviewClear();
+  return { ok: true };
+}
+
+// ---- draw a new member on the working plane (spec §7): two plane picks → api.onAddMember3d (scene
+// mm); the editor maps them to wp + per-end TOS and materializes a beam or (near-vertical) column. ----
+let drDraft = null;             // first pick, scene mm
+let drRubber = null;
+const addActive = () => !!(api && api.addModeActive && api.addModeActive());
+function drClear3d() { drDraft = null; if (drRubber) drRubber.visible = false; if (marker) marker.visible = false; if (readout) readout.style.display = 'none'; }   // callable pre-init (all handles guarded)
+function drShiftLock(p, e) {                                    // Shift = ortho along the plane's local axes (same basis as Move/Copy)
+  if (!e || !e.shiftKey || !drDraft) return p;
+  const wp = effectiveWP(), { u, v } = planeBasis(wp.normal, wp.xAxis), d = [p[0] - drDraft[0], p[1] - drDraft[1], p[2] - drDraft[2]], c = vecToPlane(d, u, v, wp.normal);
+  return Math.abs(c.du) >= Math.abs(c.dv) ? [drDraft[0] + c.du * u[0], drDraft[1] + c.du * u[1], drDraft[2] + c.du * u[2]] : [drDraft[0] + c.dv * v[0], drDraft[1] + c.dv * v[1], drDraft[2] + c.dv * v[2]];
+}
+function drClick(e) {
+  const r = wpPointAt(e); if (!r) return;
+  if (!drDraft) { drDraft = r.p; return; }
+  const p = drShiftLock(r.p, e);
+  if (Math.hypot(p[0] - drDraft[0], p[1] - drDraft[1], p[2] - drDraft[2]) < 50) return;   // ~<2in — ignore a doubled click
+  if (api && api.onAddMember3d) api.onAddMember3d(drDraft, p);
+  drDraft = null; tfCandidates = null;                                          // the new member is a snap target for the NEXT one — invalidate the shared snap cache
+  if (drRubber) drRubber.visible = false; readout.style.display = 'none';       // stays armed for the next member
+}
+function drPreview(e) {
+  const r = wpPointAt(e); if (!r) return;
+  if (r.snap) { marker.position.set(r.p[0], r.p[1], r.p[2]); marker.scale.setScalar(markerSize()); marker.visible = true; } else marker.visible = false;
+  if (!drDraft) { readout.style.display = 'none'; return; }
+  const p = drShiftLock(r.p, e);
+  if (!drRubber) { drRubber = new THREE.Line(new THREE.BufferGeometry().setFromPoints([new THREE.Vector3(), new THREE.Vector3()]), new THREE.LineBasicMaterial({ color: 0x22d3ee })); drRubber.material.depthTest = false; drRubber.renderOrder = 997; scene.add(drRubber); }
+  drRubber.geometry.setFromPoints([new THREE.Vector3(...drDraft), new THREE.Vector3(...p)]); drRubber.visible = true;
+  const L = Math.hypot(p[0] - drDraft[0], p[1] - drDraft[1], p[2] - drDraft[2]);
+  readout._dist.textContent = api.fmtLen ? api.fmtLen(L) : (L / FT_MM).toFixed(2) + ' ft'; readout._type.textContent = r.snap ? ' · ' + (r.type || 'snap') : '';
+  readout.style.left = (e.clientX + 14) + 'px'; readout.style.top = (e.clientY + 14) + 'px'; readout.style.display = 'block';
+}
 // world units per screen pixel at the target plane — drives screen-CONSTANT marker/dot sizes, for
 // BOTH perspective (distance) and ortho (frustum height / zoom), so dots stay small when zoomed in.
 // world units that map to `px` screen pixels AT a world point. In perspective the scale uses that
@@ -1586,7 +1947,7 @@ function dimPointAt(e, anchor) {
   let planeZ = sceneBox.isEmpty() ? 0 : sceneBox.min.z;
   if (id) { const m = members().find((x) => x.id === id); if (m) { const g = memberGeometry(m, api.ptPerFt(), api.defaultTosMm()); planeZ = (g.line[0][2] + g.line[1][2]) / 2; } }
   const hit = rayToPlane(e.clientX, e.clientY, planeZ); if (!hit) return null;
-  if (!dimCandidates3d) dimCandidates3d = snapCandidates(members(), api.ptPerFt(), api.defaultTosMm());
+  if (!dimCandidates3d) dimCandidates3d = allCandidates(null);
   const r = snapPoint([hit[0], hit[1], hit[2]], dimCandidates3d, toScreen, SNAP_TOL_PX);
   return { p: r.candidate ? r.snapped : hit, type: r.candidate ? r.candidate.type : null };
 }
@@ -1596,6 +1957,19 @@ function dimEffectiveAxis(alt) { return alt && dimDraft3d ? 'z' : dimAxis3d; }
 
 function onDown(e) {
   if (e.button !== 0) return;                 // RIGHT/MIDDLE → OrbitControls (orbit/pan)
+  if (wpMode === 'face') { e.stopPropagation(); const r = wpFacePick(e.clientX, e.clientY); if (r) { workPlane = r; wpMode = null; canvasEl.style.cursor = 'default'; renderWorkPlane(); reflectWpBar(); if (api && api.toast) api.toast('Working plane set on the face'); } return; } // armed: one face click sets the plane
+  if (wpMode === '3pt') { e.stopPropagation();
+    const r = dimPointAt(e); if (!r) return;
+    wpDraft = wpDraft || []; wpDraft.push(r.p);
+    marker.position.set(r.p[0], r.p[1], r.p[2]); marker.scale.setScalar(markerSize()); marker.visible = true;
+    if (wpDraft.length === 3) { const wp = planeFrom3Points(wpDraft[0], wpDraft[1], wpDraft[2]);
+      wpDraft = null; wpMode = null; marker.visible = false; canvasEl.style.cursor = 'default';
+      if (wp) { wp.kind = 'p3'; workPlane = wp; renderWorkPlane(); if (api && api.toast) api.toast('Working plane set from 3 points'); }
+      else if (api && api.toast) api.toast('Points are collinear — plane not set');
+      reflectWpBar(); }
+    return; }
+  if (addActive()) { e.stopPropagation(); controls.enabled = true; drClick(e); return; }  // Add-member armed (editor state) → two plane picks draw a member
+  if (cmActive()) { if (tfClick(e)) { e.stopPropagation(); controls.enabled = true; return; } }  // Move/Copy armed (editor state) → picks land on the working plane; an empty-selection click falls through to select
   if (clipMode === 'plane') { e.stopPropagation(); addClipPlaneAtScreen(e.clientX, e.clientY); return; } // armed: left-click a face → place a clip plane (stays armed)
   if (clipMode === 'box') { e.stopPropagation(); onClipBoxClick(e); return; }                            // armed: 2-corner clip-box draw on the floor plane
   if (selectedClipIds.size) { let ch = null; try { ch = pickClipHandle(e.clientX, e.clientY); } catch { ch = null; } if (ch) { e.stopPropagation(); controls.enabled = false; downXY = [e.clientX, e.clientY]; startClipDrag(ch, e); return; } } // grab a clip handle (plane dot / box face) → drag it
@@ -1630,7 +2004,7 @@ function onDown(e) {
       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),
+      candidates: allCandidates(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,
     };
@@ -1661,7 +2035,7 @@ function startEndpointGrab(ep, e) {
     pending = {
       epDrag: true, id: ep.id, end: ep.end, ppf,
       planeZ: g.line[ep.end][2], fixed: g.line[1 - ep.end],
-      candidates: snapCandidates(members(), ppf, dtos, ep.id),
+      candidates: allCandidates(ep.id),
       newPt: [g.line[ep.end][0], g.line[ep.end][1]],
     };
     dragEp = { id: ep.id, end: ep.end };
@@ -1799,10 +2173,26 @@ function closestOnSeg3(p, a, b) {
 function onHoverMove(e) {
   lastHoverXY = [e.clientX, e.clientY];
   dimLastAlt = e.altKey;                       // remembered so the rAF body can rebuild a synthetic event
+  tfLastShift = e.shiftKey;                    // same for the Move/Copy ortho lock
   if (hoverRAF || pending || dragging || boxSel) return;
   hoverRAF = requestAnimationFrame(() => {
     hoverRAF = 0;
     if (!lastHoverXY || pending || dragging || boxSel) return;
+    if (wpMode) {                              // armed set-plane pick: crosshair (+ snap marker for the 3pt flow)
+      canvasEl.style.cursor = 'crosshair';
+      if (wpMode === '3pt') { const r = dimPointAt({ clientX: lastHoverXY[0], clientY: lastHoverXY[1], altKey: dimLastAlt });
+        if (r && !(wpDraft && wpDraft.length)) { marker.position.set(...r.p); marker.scale.setScalar(markerSize()); marker.visible = true; } }
+      updateStatusChip(); return; }
+    if (addActive()) {                         // Add-member armed: snap marker + rubber preview on the working plane
+      canvasEl.style.cursor = 'crosshair';
+      drPreview({ clientX: lastHoverXY[0], clientY: lastHoverXY[1], altKey: dimLastAlt, shiftKey: tfLastShift });
+      updateStatusChip(); return; }
+    if (cmActive()) {                          // Move/Copy armed: previews ride the working plane
+      canvasEl.style.cursor = 'crosshair';
+      if (tfDraft) tfPreview({ clientX: lastHoverXY[0], clientY: lastHoverXY[1], altKey: dimLastAlt, shiftKey: tfLastShift });
+      else { const r = wpPointAt({ clientX: lastHoverXY[0], clientY: lastHoverXY[1], altKey: dimLastAlt });
+        if (r && r.snap) { marker.position.set(...r.p); marker.scale.setScalar(markerSize()); marker.visible = true; } else marker.visible = false; }
+      updateStatusChip(); return; }
     if (clipMode) { canvasEl.style.cursor = 'crosshair'; if (clipMode === 'box') clipBoxPreviewAt(lastHoverXY[0], lastHoverXY[1]); return; } // armed clip pick: crosshair (+ live box preview while drawing)
     if (dimMode3d) {                           // dim tool: snap marker + live preview line + readout (no member hover)
       canvasEl.style.cursor = 'crosshair';
@@ -1837,12 +2227,20 @@ function updateStatusChip() {
   const rect = canvasEl.getBoundingClientRect();
   let txt = '';
   const showId = hoverId || (selIds.size === 1 ? [...selIds][0] : null);
-  if (clipMode === 'plane') txt = 'Click a face to set a clip plane · Esc to cancel';
+  if (wpMode === 'face') txt = 'Click a member face — the working plane lands on it · Esc to cancel';
+  else if (wpMode === '3pt') txt = ['Click the plane origin (snapped) · Esc to cancel', 'Click the local-X direction point · Esc to cancel', 'Click a point on the plane’s Y side · Esc to cancel'][(wpDraft || []).length] || '';
+  else if (addActive()) txt = drDraft ? 'Click the member end · Shift straight · Esc drops the start' : 'Draw a member on the working plane — click the start point · Esc exits';
+  else if (cmActive()) { const st = cmActive(), lock = tfAxis === 'u' ? ' · X locked' : tfAxis === 'v' ? ' · Y locked' : '';
+    txt = (!tfDraft ? ((st.tool === 'move' ? 'Move' : (st.array ? 'Copy array' : 'Copy')) + ' — click the base point on the working plane · type after the pick for an exact value')
+      : (st.array && !tfDraft.vA ? 'Click the direction-A point — or type its spacing' : st.array ? 'Click the direction-B point — the grid previews live' : 'Click the destination — X/Y lock to the plane axes · Esc cancels')) + lock; }
+  else if (clipMode === 'plane') txt = 'Click a face to set a clip plane · Esc to cancel';
   else if (clipMode === 'box') txt = !clipBoxDraft ? 'Click the first floor corner of the clip box · Esc to cancel' : !clipBoxDraft.b ? 'Click the opposite floor corner · Esc to cancel' : 'Move up/down to set the height, then click · Esc to step back';
   else if (showId) { const m = members().find((x) => x.id === showId); txt = m ? `${m.id} · ${m.profile || '—'}` : ''; }
   else if (selIds.size > 1) txt = `${selIds.size} members selected`;
   else if (isolatedIds) txt = `Isolated: ${isolatedIds.size} · Show all to restore`;
-  else txt = 'Drag to move · ends to stretch · Alt+drag elevation · right-drag orbit · dbl-click to zoom in';
+  // A read-only host (the vector 3D viewer) supplies its own idle hint — the default speaks
+  // editing verbs (move/stretch/elevate) that a viewer's no-op api would silently ignore.
+  else txt = (api && typeof api.statusHint === 'function' && api.statusHint()) || 'Drag to move · ends to stretch · Alt+drag elevation · right-drag orbit · dbl-click to zoom in';
   hoverChip.textContent = txt;
   hoverChip.style.left = (rect.left + rect.width / 2) + 'px'; hoverChip.style.transform = 'translateX(-50%)';
   hoverChip.style.top = (rect.bottom - 30) + 'px';
@@ -1853,6 +2251,8 @@ function show() { if (controls) controls.enabled = true; if (canvasEl) { canvasE
 function hide() {
   if (dimMode3d) toggleDimTool();              // disarm the dim tool + sync its toolbar (no stale draft/armed state on return)
   if (clipMode) setClipMode(null);             // disarm the clip-plane pick too (no stale armed state on return)
+  if (wpMode) { wpMode = null; wpDraft = null; if (marker) marker.visible = false; reflectWpBar(); }  // drop an in-progress set-plane pick — else a stale face/3pt pick steals the first click on return
+  cmClear3d(); drClear3d();                     // and any 3D Move/Copy or draw draft/ghosts
   if (dimLabelHost) dimLabelHost.style.display = 'none'; // the loop that hides labels is about to stop — hide synchronously so none are stranded
   if (canvasEl) canvasEl.style.display = 'none'; if (hoverChip) hoverChip.style.display = 'none'; if (rafId) { cancelAnimationFrame(rafId); rafId = null; }
 }
@@ -1883,6 +2283,9 @@ function dispose() {
   for (const o of [epRing, epPreview, refGroup, dimPreviewLine]) if (o) { if (o.geometry) o.geometry.dispose(); if (o.material) o.material.dispose(); }
   epGeom = epMatStart = epMatEnd = epRing = epPreview = refGroup = null;
   dims3dGroup = dimPreviewLine = overlayDimsGroup = null;
+  clearStructGrid();
+  for (const tex of gridTexCache.values()) tex.dispose();
+  gridTexCache.clear();
   clearRoot();
   if (workAreaHelper) { if (overlayScene) overlayScene.remove(workAreaHelper); workAreaHelper.geometry.dispose(); workAreaHelper.material.dispose(); workAreaHelper = null; }
   clearClipGizmo(); setClipPreview(null); overlayScene = null;
@@ -1911,6 +2314,7 @@ function debug() {
     target: controls ? [controls.target.x, controls.target.y, controls.target.z] : null,
     near: camera?.near, far: camera?.far,
     clips: getClips(), clipPlaneCount: renderer && renderer.clippingPlanes ? renderer.clippingPlanes.length : 0, clipMode, workArea: workAreaState(), selectedClips: [...selectedClipIds],
+    workPlane: workPlaneInfo(), tfHasBase: !!tfDraft, tfGhosts: tfGhost ? tfGhost.children.length : 0, drHasStart: !!drDraft,
   };
 }
 // test helper: the current material colour + emissive of a member (verifies deselect restores colour)
@@ -1936,10 +2340,15 @@ window.Steel3DView = {
   init, show, hide, rebuild, setSelection, isReady, dispose,
   setProjection, projection, setDisplayMode, mode: () => displayMode, frameAll, frameSelection, applyView,
   setRefLine, refLine: () => refLineOn,
+  refreshGrid: buildStructGrid,          // grid edited in the panel → re-render without a full rebuild
+  gridInfo: () => ({ lines: structGridGroup ? 1 : 0, labels: gridLabelGroup ? gridLabelGroup.children.length : 0 }),   // test helper
   toggleGroup, setGroupsHidden, setIdsHidden, connHiddenIds: () => [...connHidden], soloToggle, setSoloGroups, showAllGroups, groupState, getGroups,
   setClipMode, clipMode: clipModeOn, addClipBox, toggleClip, removeClip, clearClips, getClips, renameClip, selectClip, setSelectedClips, selectedClips, deleteSelectedClips, clipState, setClipState,
   isolateSelected, clearIsolation, isIsolated,
   workAreaSetAll, workAreaFromSelection, workAreaToggle, clearWorkArea, workAreaState,
+  armWorkPlanePick, setWorkPlanePrincipal, clearWorkPlane, toggleWorkPlaneVisible, workPlaneInfo,
+  cmEscape, cmHasBase, cmClear3d, setCmAxis, cmLastClient, cmHudApply,
+  drClear3d, drEscape: () => { if (drDraft) { drDraft = null; drClear3d(); return true; } return false; },
   toggleDimTool, setDimAxis, dimAxis, setDims3dVisible, dims3dVisible, refreshDims,
   refreshOverlayDims,
   overlayDimsInfo: () => computeOverlayDims().map((s) => ({ label: s.label, cat: s.cat })),   // the dims currently emitted (toggle + visibility applied) — for tests