holder: fit-check — translucent max-box + manual enclosure overlay

The hex_cell.scad echoes its computed dimensions (pack_height_holder,
total_*_holder, box_total_*) to stderr. Capture those and surface them
in the viewer so the user can sanity-check whether the assembled
battery will fit in a target case.

Backend:
- holder.py: render_stl() now returns (stl_bytes, dims) where dims is
  a {name: float} dict parsed from openscad ECHO lines.
- app.py: /api/holder/render emits the dims dict as an
  X-Holder-Dimensions response header (JSON) with the matching
  Access-Control-Expose-Headers entry so fetch() can read it under
  any proxy / future CORS setup.

Viewer (holder-viewer.js):
- New setGhostBox(name, {w,d,h}, {visible,color}) and clearGhostBox(name)
  helpers. Each ghost is a Group of a translucent BoxGeometry mesh +
  matching EdgesGeometry wireframe, positioned to match how the STL
  mesh is placed (centred XY, bottom on Z=0).

UI (holder.html / holder.css):
- New "Fit check" panel under Status with two sections:
    • Show max bounding box (auto, from ECHO — defaults to box_total_*
      dims, falls back to total_*_holder + pack_height_holder).
    • Show enclosure (manual W × D × H inputs in mm).
- Verdict line under the enclosure inputs: "✓ fits" green or
  "✗ too small — battery won't fit" red.

Controller (holder-app.js):
- Reads X-Holder-Dimensions after each render, updates the max-box
  ghost in blue, prints the dimensions label.
- Watches enclosure inputs + toggles, drives the enclosure ghost
  (green if it fits, red if smaller than the max box on any axis).
- Fit comparison is orientation-independent in the XY plane (sorted
  W,D pair) but strict on Z (height).

static/js/holder-app.js

@@ -20,8 +20,15 @@ const state = {
   elapsedTimer: null,
   rendererReady: false,
   maxCells: 1000,    // server-published cap; overridden by /api/holder/params
+  dimensions: null,  // last ECHO dims dict from X-Holder-Dimensions
+  maxBox: null,      // {w, d, h} of assembled-battery bounding box
+  enclosure: null,   // {w, d, h} of user-defined case (or null)
 };
 
+const COLOR_MAX_BOX  = 0x4a9eff;  // blue
+const COLOR_ENC_OK   = 0x4ad97a;  // green
+const COLOR_ENC_BAD  = 0xd94a4a;  // red
+
 // ----- viewer init ----------------------------------------------------------
 // HolderViewer is set up by holder-viewer.js (loaded as ES module) and
 // attached to window. We wait briefly for it to be ready.
@@ -188,12 +195,18 @@ async function _doRender() {
       try { msg = (await res.json()).error || msg; } catch {}
       throw new Error(msg);
     }
+    // Pick up the ECHO dimensions header before we read the body (whichever
+    // order is fine, but keep header access close to the response).
+    const dimHdr = res.headers.get("X-Holder-Dimensions");
+    state.dimensions = dimHdr ? _safeParseJSON(dimHdr) : null;
+
     state.lastBlob = await res.blob();
     const buf = await state.lastBlob.arrayBuffer();
     window.HolderViewer.loadSTL(buf);
     const dt = ((performance.now() - t0) / 1000).toFixed(1);
     $("render-status").textContent = `✓ rendered in ${dt}s · ${(state.lastBlob.size/1024).toFixed(0)} kB`;
     _clearDirty();
+    _updateFitCheck();
   } catch (e) {
     if (e.name === "AbortError") {
       $("render-status").textContent = "✗ cancelled";
@@ -231,8 +244,97 @@ function _updateStatus() {
   $("btn-to-busbar").disabled = overLimit;
 }
 
+// ----- fit check ------------------------------------------------------------
+
+function _safeParseJSON(s) {
+  try { return JSON.parse(s); } catch { return null; }
+}
+
+function _extractMaxBox(dims) {
+  if (!dims) return null;
+  // Prefer the fully-assembled-case dims; fall back to plain-holder dims.
+  const w = dims.box_total_length ?? dims.total_length_holder;
+  const d = dims.box_total_width  ?? dims.total_width_holder;
+  const h = dims.box_total_height ?? dims.pack_height_holder;
+  if (!(w > 0) || !(d > 0) || !(h > 0)) return null;
+  return { w, d, h };
+}
+
+function _readEnclosureInputs() {
+  const w = +$("enc-w").value;
+  const d = +$("enc-d").value;
+  const h = +$("enc-h").value;
+  if (!(w > 0) || !(d > 0) || !(h > 0)) return null;
+  return { w, d, h };
+}
+
+function _checkFit(maxBox, enc) {
+  // Compare orientation-independently in the XY plane (rotating the battery
+  // 90° around Z is usually free), but keep Z (height) fixed.
+  if (!maxBox || !enc) return null;
+  const mxxy = [maxBox.w, maxBox.d].sort((a, b) => a - b);
+  const exxy = [enc.w, enc.d].sort((a, b) => a - b);
+  return exxy[0] + 1e-6 >= mxxy[0]
+      && exxy[1] + 1e-6 >= mxxy[1]
+      && enc.h + 1e-6 >= maxBox.h;
+}
+
+function _fmt(n) { return (Math.round(n * 10) / 10).toFixed(1); }
+
+function _updateFitCheck() {
+  state.maxBox = _extractMaxBox(state.dimensions);
+  state.enclosure = _readEnclosureInputs();
+
+  // Max-box ghost + label
+  if (state.maxBox) {
+    $("max-box-dims").textContent =
+      `${_fmt(state.maxBox.w)} × ${_fmt(state.maxBox.d)} × ${_fmt(state.maxBox.h)} mm`;
+    window.HolderViewer.setGhostBox("max", state.maxBox, {
+      visible: $("show-max-box").checked,
+      color: COLOR_MAX_BOX,
+    });
+  } else {
+    $("max-box-dims").textContent = "— render first";
+    window.HolderViewer.clearGhostBox("max");
+  }
+
+  // Enclosure ghost + verdict
+  const verdict = $("fit-verdict");
+  verdict.className = "hint";
+  if (state.enclosure) {
+    const fits = _checkFit(state.maxBox, state.enclosure);
+    const color = fits === false ? COLOR_ENC_BAD : COLOR_ENC_OK;
+    window.HolderViewer.setGhostBox("enc", state.enclosure, {
+      visible: $("show-enclosure").checked,
+      color,
+    });
+    if (fits === true) {
+      verdict.textContent = "✓ fits";
+      verdict.classList.add("fit-ok");
+    } else if (fits === false) {
+      verdict.textContent = "✗ too small — battery won't fit";
+      verdict.classList.add("fit-bad");
+    } else {
+      verdict.textContent = "render to compare";
+    }
+  } else {
+    window.HolderViewer.clearGhostBox("enc");
+    verdict.textContent = "";
+  }
+}
+
 // ----- buttons --------------------------------------------------------------
 
+$("show-max-box").addEventListener("change", _updateFitCheck);
+$("show-enclosure").addEventListener("change", _updateFitCheck);
+for (const id of ["enc-w", "enc-d", "enc-h"]) {
+  $(id).addEventListener("input", () => {
+    // Auto-enable the toggle when the user starts typing dims.
+    if (_readEnclosureInputs()) $("show-enclosure").checked = true;
+    _updateFitCheck();
+  });
+}
+
 $("btn-render").addEventListener("click", () => {
   if (state.rendererReady) _doRender();
 });