@jwc/jscad-utils 5.2.0 → 5.5.0

package/dist/index.js

@@ -89,6 +89,54 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
   function _arrayWithHoles(r) {
     if (Array.isArray(r)) return r;
   }
+  function _createForOfIteratorHelper(r, e) {
+    var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"];
+    if (!t) {
+      if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) {
+        t && (r = t);
+        var n = 0,
+          F = function () {};
+        return {
+          s: F,
+          n: function () {
+            return n >= r.length ? {
+              done: !0
+            } : {
+              done: !1,
+              value: r[n++]
+            };
+          },
+          e: function (r) {
+            throw r;
+          },
+          f: F
+        };
+      }
+      throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+    }
+    var o,
+      a = !0,
+      u = !1;
+    return {
+      s: function () {
+        t = t.call(r);
+      },
+      n: function () {
+        var r = t.next();
+        return a = r.done, r;
+      },
+      e: function (r) {
+        u = !0, o = r;
+      },
+      f: function () {
+        try {
+          a || null == t.return || t.return();
+        } finally {
+          if (u) throw o;
+        }
+      }
+    };
+  }
   function _defineProperty(e, r, t) {
     return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
       value: t,
@@ -761,6 +809,344 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     return o.setColor(c);
   }
 
+  /* globals jscadUtilsAssertValidCSG jscadUtilsAssertValidCSGWarnings */
+  /**
+   * @typedef {Object} CSG
+   * @property {Array<{vertices: Array<{pos: any}>}>} polygons
+   * @property {function(): CSG} [canonicalized]
+   * @property {function(): CSG} [reTesselated]
+   * @property {function(): CSG} [fixTJunctions]
+   * @property {function(): Array} [getBounds]
+   * @property {Object} [properties]
+   */
+  /**
+   * Validate that a CSG object represents a solid, watertight mesh
+   * without degenerate faces. Returns an object with an `ok` boolean
+   * and an `errors` array describing any problems found.
+   *
+   * Checks performed:
+   * - **No empty mesh** – the object must contain at least one polygon.
+   * - **No degenerate polygons** – every polygon must have ≥ 3 vertices
+   *   and a computable area greater than `EPS²`.
+   * - **Watertight / manifold edges** – every directed edge A→B in the
+   *   mesh must be matched by exactly one reverse edge B→A in another
+   *   polygon.  Unmatched edges indicate holes; edges shared more than
+   *   twice indicate non-manifold geometry.
+   *
+   * By default, the mesh is canonicalized and T-junctions are repaired
+   * before validation so that results from boolean operations (union,
+   * subtract, intersect) can be validated successfully.  Pass
+   * `{ fixTJunctions: false }` to skip this step and validate the raw
+   * mesh.
+   *
+   * @param  {CSG} csg  The CSG object to validate.
+   * @param  {object} [options]  Validation options.
+   * @param  {boolean} [options.fixTJunctions=true]  Whether to canonicalize and fix T-junctions before validation.
+   * @return {{ ok: boolean, errors: string[], warnings: string[] }}  Validation result.
+   * @function validateCSG
+   */
+  function validateCSG(csg, options) {
+    /** @type {string[]} */
+    var errors = [];
+    /** @type {string[]} */
+    var warnings = [];
+    if (!csg || !csg.polygons || csg.polygons.length === 0) {
+      errors.push('Empty mesh: no polygons');
+      return {
+        ok: false,
+        errors: errors,
+        warnings: warnings
+      };
+    }
+    var opts = _objectSpread2({
+      fixTJunctions: true
+    }, options);
+
+    // Optionally canonicalize and fix T-junctions so that boolean-op
+    // output can pass the watertight check.
+    if (opts.fixTJunctions && typeof csg.canonicalized === 'function') {
+      csg = csg.canonicalized();
+      if (typeof csg.reTesselated === 'function') {
+        csg = csg.reTesselated();
+      }
+      if (typeof csg.fixTJunctions === 'function') {
+        csg = csg.fixTJunctions();
+      }
+    }
+    var AREA_EPS = 1e-10;
+    var KEY_EPS = 1e-5;
+    var degenerateCount = 0;
+    var invalidVertexCount = 0;
+
+    // Check for NaN/Infinity vertex coordinates which cause WebGL errors
+    // (GL_INVALID_VALUE: glVertexAttribPointer: Vertex attribute size must be 1, 2, 3, or 4)
+    var _iterator = _createForOfIteratorHelper(csg.polygons),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var npoly = _step.value;
+        var _iterator4 = _createForOfIteratorHelper(npoly.vertices),
+          _step4;
+        try {
+          for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+            var nvert = _step4.value;
+            var np = nvert.pos;
+            if (!Number.isFinite(np.x) || !Number.isFinite(np.y) || !Number.isFinite(np.z) || Number.isNaN(np.x) || Number.isNaN(np.y) || Number.isNaN(np.z)) {
+              invalidVertexCount++;
+              break;
+            }
+          }
+        } catch (err) {
+          _iterator4.e(err);
+        } finally {
+          _iterator4.f();
+        }
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    if (invalidVertexCount > 0) {
+      errors.push(invalidVertexCount + ' polygon(s) with invalid vertex coordinates (NaN or Infinity)');
+    }
+
+    // Position-based vertex key (shared vertices across polygons have different
+    // object tags but the same position, so we round coordinates to match them).
+    /** @param {{ pos: { x: number, y: number, z: number } }} v */
+    function vtxKey(v) {
+      var p = v.pos;
+      return Math.round(p.x / KEY_EPS) + ',' + Math.round(p.y / KEY_EPS) + ',' + Math.round(p.z / KEY_EPS);
+    }
+
+    // First pass: identify degenerate polygons
+    var validPolygons = [];
+    var _iterator2 = _createForOfIteratorHelper(csg.polygons),
+      _step2;
+    try {
+      for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+        var poly = _step2.value;
+        var verts = poly.vertices;
+        var nv = verts.length;
+        if (nv < 3) {
+          degenerateCount++;
+          continue;
+        }
+
+        // Skip polygons with invalid vertex coordinates
+        var hasInvalid = false;
+        var _iterator5 = _createForOfIteratorHelper(verts),
+          _step5;
+        try {
+          for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
+            var vert = _step5.value;
+            var ip = vert.pos;
+            if (!Number.isFinite(ip.x) || !Number.isFinite(ip.y) || !Number.isFinite(ip.z)) {
+              hasInvalid = true;
+              break;
+            }
+          }
+        } catch (err) {
+          _iterator5.e(err);
+        } finally {
+          _iterator5.f();
+        }
+        if (hasInvalid) continue;
+
+        // Check degenerate area using cross-product summation
+        var area = 0;
+        for (var ai = 0; ai < nv - 2; ai++) {
+          area += verts[ai + 1].pos.minus(verts[0].pos).cross(verts[ai + 2].pos.minus(verts[ai + 1].pos)).length();
+        }
+        area *= 0.5;
+        if (area < AREA_EPS) {
+          degenerateCount++;
+          continue;
+        }
+        validPolygons.push(poly);
+      }
+    } catch (err) {
+      _iterator2.e(err);
+    } finally {
+      _iterator2.f();
+    }
+    if (degenerateCount > 0) {
+      warnings.push(degenerateCount + ' degenerate polygon(s) (fewer than 3 vertices or near-zero area)');
+
+      // Rebuild the CSG from valid polygons only and re-run the repair
+      // pipeline so that fixTJunctions can close gaps left by the removed
+      // degenerate faces.
+      /* eslint-disable no-undef */
+      // @ts-ignore — CSG is a runtime global injected by the JSCAD compat layer
+      if (opts.fixTJunctions && typeof CSG !== 'undefined') {
+        // @ts-ignore
+        var cleaned = CSG.fromPolygons(validPolygons);
+        /* eslint-enable no-undef */
+        cleaned = cleaned.canonicalized();
+        if (typeof cleaned.reTesselated === 'function') {
+          cleaned = cleaned.reTesselated();
+        }
+        if (typeof cleaned.fixTJunctions === 'function') {
+          cleaned = cleaned.fixTJunctions();
+        }
+        // Re-scan for valid polygons after second repair pass
+        validPolygons = [];
+        var _iterator3 = _createForOfIteratorHelper(cleaned.polygons),
+          _step3;
+        try {
+          for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+            var cpoly = _step3.value;
+            var cverts = cpoly.vertices;
+            var cnv = cverts.length;
+            if (cnv < 3) continue;
+            var carea = 0;
+            for (var cai = 0; cai < cnv - 2; cai++) {
+              carea += cverts[cai + 1].pos.minus(cverts[0].pos).cross(cverts[cai + 2].pos.minus(cverts[cai + 1].pos)).length();
+            }
+            carea *= 0.5;
+            if (carea < AREA_EPS) continue;
+            validPolygons.push(cpoly);
+          }
+        } catch (err) {
+          _iterator3.e(err);
+        } finally {
+          _iterator3.f();
+        }
+      }
+    }
+
+    // Edge map: key = "vtxKeyA/vtxKeyB", value = count
+    /** @type {Record<string, number>} */
+    var edgeCounts = {};
+
+    // Accumulate directed edges from valid polygons only
+    for (var _i = 0, _validPolygons = validPolygons; _i < _validPolygons.length; _i++) {
+      var vpoly = _validPolygons[_i];
+      var vverts = vpoly.vertices;
+      var vnv = vverts.length;
+      for (var ei = 0; ei < vnv; ei++) {
+        var v0 = vverts[ei];
+        var v1 = vverts[(ei + 1) % vnv];
+        var edgeKey = vtxKey(v0) + '/' + vtxKey(v1);
+        edgeCounts[edgeKey] = (edgeCounts[edgeKey] || 0) + 1;
+      }
+    }
+
+    // Check edge manifoldness: every edge A→B should be cancelled by B→A
+    var unmatchedEdges = 0;
+    var nonManifoldEdges = 0;
+    /** @type {Record<string, boolean>} */
+    var checked = {};
+    for (var _i2 = 0, _Object$keys = Object.keys(edgeCounts); _i2 < _Object$keys.length; _i2++) {
+      var _edgeKey = _Object$keys[_i2];
+      if (checked[_edgeKey]) continue;
+      var parts = _edgeKey.split('/');
+      var reverseKey = parts[1] + '/' + parts[0];
+      var forwardCount = edgeCounts[_edgeKey] || 0;
+      var reverseCount = edgeCounts[reverseKey] || 0;
+      checked[_edgeKey] = true;
+      checked[reverseKey] = true;
+      if (forwardCount !== reverseCount) {
+        unmatchedEdges += Math.abs(forwardCount - reverseCount);
+      }
+      if (forwardCount > 1 || reverseCount > 1) {
+        nonManifoldEdges++;
+      }
+    }
+    if (unmatchedEdges > 0) {
+      errors.push(unmatchedEdges + ' unmatched edge(s): mesh is not watertight');
+    }
+    if (nonManifoldEdges > 0) {
+      errors.push(nonManifoldEdges + ' non-manifold edge(s): edge shared by more than 2 polygons');
+    }
+    return {
+      ok: errors.length === 0,
+      errors: errors,
+      warnings: warnings
+    };
+  }
+
+  /** @param {any} csg @returns {any} */
+  function _noOp(csg) {
+    return csg;
+  }
+
+  /**
+   * @param {boolean} warnEnabled
+   * @returns {function(*, string=, string=): *}
+   */
+  function _makeAssertFn(warnEnabled) {
+    return function _assert(csg) {
+      var functionName = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'unknown';
+      var moduleName = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 'unknown';
+      // Only validate CSG-like objects (they have a polygons array).
+      // CAG objects (2D cross-sections) have `sides` instead and are passed through.
+      if (!csg || csg.polygons === undefined) return csg;
+      var result = validateCSG(csg);
+      if (!result.ok) {
+        throw new Error(moduleName + ':' + functionName + ': ' + 'invalid CSG: ' + result.errors.join(', '));
+      }
+      if (warnEnabled && result.warnings.length > 0) {
+        throw new Error(moduleName + ':' + functionName + ': ' + 'CSG warnings: ' + result.warnings.join(', '));
+      }
+      return csg;
+    };
+  }
+
+  // Live pointer that all returned closures call through — swap this and all
+  // existing closures immediately pick up the change.
+  /** @type {function(*, string=, string=): *} */
+  var _assertFn = _noOp;
+
+  // Read compat globals set by initJscadutils — mirrors the Debug() pattern
+  // in debug.js.  Returns _noOp when globals are absent (ESM / test context).
+  function _resolveFromGlobals() {
+    /* eslint-disable no-undef */
+    // @ts-ignore — globals set by the JSCAD compat layer before bundle injection
+    var enabled = typeof jscadUtilsAssertValidCSG !== 'undefined' && !!jscadUtilsAssertValidCSG;
+    // @ts-ignore
+    var warnEnabled = typeof jscadUtilsAssertValidCSGWarnings !== 'undefined' && !!jscadUtilsAssertValidCSGWarnings;
+    /* eslint-enable no-undef */
+    return enabled ? _makeAssertFn(warnEnabled) : _noOp;
+  }
+
+  /**
+   * Returns an asserter function bound to `moduleName`. Call the returned
+   * function with a CSG object and the calling function's name to validate it
+   * (when enabled) or pass it through unchanged (when disabled).
+   *
+   * Best practice is to call `AssertValidCSG` once per module at load time and
+   * capture the result as a module-level constant so that `moduleName` appears
+   * consistently in every error message thrown from that module.
+   *
+   * On creation, reads compat globals (jscadUtilsAssertValidCSG /
+   * jscadUtilsAssertValidCSGWarnings) if setValidationEnabled() has not been
+   * called explicitly — identical to how Debug('name') reads jscadUtilsDebug.
+   *
+   * Error message format: `moduleName:functionName: invalid CSG: <errors>`
+   *
+   * @example
+   *   // Once at the top of your module:
+   *   const assertValidCSG = AssertValidCSG('myModule');
+   *
+   *   export function enlarge(object, ...) {
+   *     // ...
+   *     return assertValidCSG(new_object.translate(delta), 'enlarge');
+   *   }
+   *
+   * @param {string} [moduleName='unknown']  Module name, included in error messages.
+   * @return {function(CSG, string=): CSG}
+   */
+  function AssertValidCSG() {
+    var moduleName = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'unknown';
+    {
+      _assertFn = _resolveFromGlobals();
+    }
+    return function (csg, name) {
+      return _assertFn(csg, name, moduleName);
+    };
+  }
+
   /** @typedef {object} ExtendedCSG
    * @property {object} prototype 
    * @property {function} prototype.color
@@ -833,7 +1219,6 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
    * @property {function} stackTrace
    * @property {function} getConnector
    */
-
   /**
    * Initialize `jscad-utils` and add utilities to the `proto` object.
    * @param  {CSG} proto The global `proto` object
@@ -943,6 +1328,9 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     proto.prototype.subtractIf = function subtractIf(object, condition) {
       return condition ? this.subtract(result(this, object)) : this;
     };
+    proto.prototype.validate = function validate(options) {
+      return validateCSG(this, options);
+    };
     proto.prototype._translate = proto.prototype.translate;
 
     /**
@@ -994,16 +1382,17 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     'default': init
   });
 
-  var CSG = jsCadCSG__default["default"].CSG,
+  var CSG$1 = jsCadCSG__default["default"].CSG,
     CAG = jsCadCSG__default["default"].CAG;
   var rectangular_extrude = scadApi__default["default"].extrusions.rectangular_extrude;
   var _scadApi$text = scadApi__default["default"].text,
     vector_text = _scadApi$text.vector_text,
     vector_char = _scadApi$text.vector_char;
   var union = scadApi__default["default"].booleanOps.union;
-  init(CSG);
+  init(CSG$1);
 
   var debug$3 = Debug('jscadUtils:group');
+  var assertValidCSG$2 = AssertValidCSG('group');
 
   /**
    * @function JsCadUtilsGroup
@@ -1082,7 +1471,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
         debug$3('combine mapPick', value, key, object);
         return map ? map(value, key, index, object) : identity(value);
       }, self.name));
-      return g.subtractIf(self.holes && Array.isArray(self.holes) ? union(self.holes) : self.holes, self.holes && !options.noholes);
+      return assertValidCSG$2(g.subtractIf(self.holes && Array.isArray(self.holes) ? union(self.holes) : self.holes, self.holes && !options.noholes), 'combine');
     } catch (err) {
       debug$3('combine error', this, pieces, options, err);
       throw error("group::combine error \"".concat(err.message || err.toString(), "\"\nthis: ").concat(this, "\npieces: \"").concat(pieces, "\"\noptions: ").concat(JSON.stringify(options, null, 2), "\nstack: ").concat(err.stack, "\n"), 'JSCAD_UTILS_GROUP_ERROR');
@@ -1144,7 +1533,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     });
     if (self.holes) {
       group.holes = toArray(self.holes).map(function (part) {
-        return map(CSG.fromPolygons(part.toPolygons()), 'holes');
+        return assertValidCSG$2(map(CSG$1.fromPolygons(part.toPolygons()), 'holes'), 'clone');
       });
     }
     return group;
@@ -1172,7 +1561,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     var rotationCenter = solid.centroid();
     var rotationAxis = axes[axis];
     self.map(function (part) {
-      return part.rotate(rotationCenter, rotationAxis, angle);
+      return assertValidCSG$2(part.rotate(rotationCenter, rotationAxis, angle), 'rotate');
     });
     return self;
   };
@@ -1206,7 +1595,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
       // debug(', self);
       var t = calcSnap(self.combine(part), to, axis, orientation, delta);
       self.map(function (part) {
-        return part.translate(t);
+        return assertValidCSG$2(part.translate(t), 'snap');
       });
       return self;
     } catch (err) {
@@ -1232,7 +1621,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
         noholes: true
       }), axis, to, delta);
       self.map(function (part /*, name */) {
-        return part.translate(t);
+        return assertValidCSG$2(part.translate(t), 'align');
       });
 
       // if (self.holes)
@@ -1270,14 +1659,14 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     var myConnector = connectorName.split('.').reduce(function (a, v) {
       return a[v];
     }, self.parts[partName].properties);
-    debug$3('toConnector', to instanceof CSG.Connector);
+    debug$3('toConnector', to instanceof CSG$1.Connector);
     var toConnector = toConnectorName.split('.').reduce(function (a, v) {
       return a[v];
     }, to.properties);
     var matrix = myConnector.getTransformationTo(toConnector, mirror, normalrotation);
     debug$3('connectTo', matrix);
     self.map(function (part) {
-      return part.transform(matrix);
+      return assertValidCSG$2(part.transform(matrix), 'connectTo');
     });
     return self;
   };
@@ -1298,7 +1687,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     // debug(' part, t);
     // var t = util.calcCenterWith(self.combine(part), axis, to, delta);
     self.map(function (part) {
-      return part.translate(t);
+      return assertValidCSG$2(part.translate(t), 'midlineTo');
     });
 
     // if (self.holes)
@@ -1322,7 +1711,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     var t = Array.isArray(x) ? x : [x, y, z];
     debug$3('translate', t);
     self.map(function (part) {
-      return part.translate(t);
+      return assertValidCSG$2(part.translate(t), 'translate');
     });
 
     // if (self.holes)
@@ -1346,7 +1735,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     if (!map) map = identity;
     var g = Group();
     p.forEach(function (name) {
-      g.add(map(CSG.fromPolygons(self.parts[name].toPolygons()), name), name);
+      g.add(assertValidCSG$2(map(CSG$1.fromPolygons(self.parts[name].toPolygons()), name), 'pick'), name);
     });
     return g;
   };
@@ -1370,7 +1759,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
         debug$3('array error', _this, parts);
         throw error("group::array error \"".concat(name, "\" not found.\nthis: ").concat(_this, "\nparts: \"").concat(parts, "\"\n"), 'JSCAD_UTILS_GROUP_ERROR');
       }
-      a.push(map(CSG.fromPolygons(self.parts[name].toPolygons()), name));
+      a.push(assertValidCSG$2(map(CSG$1.fromPolygons(self.parts[name].toPolygons()), name), 'array'));
     });
     return a;
     //   } catch (err) {
@@ -1439,7 +1828,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
         self.names = names && names.length > 0 && names.split(',') || [];
         if (Array.isArray(objects)) {
           self.parts = zipObject(self.names, objects);
-        } else if (objects instanceof CSG) {
+        } else if (objects instanceof CSG$1) {
           self.parts = zipObject(self.names, [objects]);
         } else {
           self.parts = objects || {};
@@ -1464,6 +1853,8 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
   }
 
   var debug$2 = Debug('jscadUtils:util');
+  var assertValidCSG$1 = AssertValidCSG('util');
+
   // import utilInit from '../src/add-prototype';
   // utilInit(CSG);
   // console.trace('CSG', CSG.prototype);
@@ -1627,12 +2018,12 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     // console.trace('label', Object.getPrototypeOf(union(o)));
     // var foo = union(o);
     // console.trace('typeof', typeof foo);
-    return center(union(o));
+    return assertValidCSG$1(center(union(o)), 'label');
   }
   function text(text) {
     var l = vector_char(0, 0, text); // l contains a list of polylines to draw
     var _char = l.segments.reduce(function (result, segment) {
-      var path = new CSG.Path2D(segment);
+      var path = new CSG$1.Path2D(segment);
       var cag = path.expandToCAG(2);
       // debug('reduce', result, segment, path, cag);
       return result ? result.union(cag) : cag;
@@ -1641,17 +2032,17 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
   }
   function unitCube(length, radius) {
     radius = radius || 0.5;
-    return CSG.cube({
+    return assertValidCSG$1(CSG$1.cube({
       center: [0, 0, 0],
       radius: [radius, radius, length || 0.5]
-    });
+    }), 'unitCube');
   }
   function unitAxis(length, radius, centroid) {
     debug$2('unitAxis', length, radius, centroid);
     centroid = centroid || [0, 0, 0];
     var unitaxis = unitCube(length, radius).setColor(1, 0, 0).union([unitCube(length, radius).rotateY(90).setColor(0, 1, 0), unitCube(length, radius).rotateX(90).setColor(0, 0, 1)]);
-    unitaxis.properties.origin = new CSG.Connector([0, 0, 0], [1, 0, 0], [0, 1, 0]);
-    return unitaxis.translate(centroid);
+    unitaxis.properties.origin = new CSG$1.Connector([0, 0, 0], [1, 0, 0], [0, 1, 0]);
+    return assertValidCSG$1(unitaxis.translate(centroid), 'unitAxis');
   }
   function toArray(a) {
     return Array.isArray(a) ? a : [a];
@@ -1775,15 +2166,15 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
   }
   function center(object, objectSize) {
     objectSize = objectSize || size(object.getBounds());
-    return centerY(centerX(object, objectSize), objectSize);
+    return assertValidCSG$1(centerY(centerX(object, objectSize), objectSize), 'center');
   }
   function centerY(object, objectSize) {
     objectSize = objectSize || size(object.getBounds());
-    return object.translate([0, -objectSize.y / 2, 0]);
+    return assertValidCSG$1(object.translate([0, -objectSize.y / 2, 0]), 'centerY');
   }
   function centerX(object, objectSize) {
     objectSize = objectSize || size(object.getBounds());
-    return object.translate([-objectSize.x / 2, 0, 0]);
+    return assertValidCSG$1(object.translate([-objectSize.x / 2, 0, 0]), 'centerX');
   }
 
   /**
@@ -1815,7 +2206,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
 
     /// Calculate the difference between the original centroid and the new
     var delta = new_centroid.minus(objectCentroid).times(-1);
-    return new_object.translate(delta);
+    return assertValidCSG$1(new_object.translate(delta), 'enlarge');
   }
 
   /**
@@ -1847,10 +2238,10 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     }
     var s = [scale(objectSize.x, x), scale(objectSize.y, y), scale(objectSize.z, z)];
     var min$1 = min(s);
-    return centerWith(object.scale(s.map(function (d, i) {
+    return assertValidCSG$1(centerWith(object.scale(s.map(function (d, i) {
       if (a[i] === 0) return 1; // don't scale when value is zero
       return keep_aspect_ratio ? min$1 : d;
-    })), 'xyz', object);
+    })), 'xyz', object), 'fit');
   }
   function shift(object, x, y, z) {
     var hsize = this.div(this.size(object.getBounds()), 2);
@@ -1858,10 +2249,10 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
   }
   function zero(object) {
     var bounds = object.getBounds();
-    return object.translate([0, 0, -bounds[0].z]);
+    return assertValidCSG$1(object.translate([0, 0, -bounds[0].z]), 'zero');
   }
   function mirrored4(x) {
-    return x.union([x.mirroredY(90), x.mirroredX(90), x.mirroredY(90).mirroredX(90)]);
+    return assertValidCSG$1(x.union([x.mirroredY(90), x.mirroredX(90), x.mirroredY(90).mirroredX(90)]), 'mirrored4');
   }
   var flushSide = {
     'above-outside': [1, 0],
@@ -1927,7 +2318,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
   function snap(moveobj, withobj, axis, orientation, delta) {
     debug$2('snap', moveobj, withobj, axis, orientation, delta);
     var t = calcSnap(moveobj, withobj, axis, orientation, delta);
-    return moveobj.translate(t);
+    return assertValidCSG$1(moveobj.translate(t), 'snap');
   }
 
   /**
@@ -1940,23 +2331,35 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
    * @return {CSG}         [description]
    */
   function flush(moveobj, withobj, axis, mside, wside) {
-    return moveobj.translate(calcFlush(moveobj, withobj, axis, mside, wside));
+    return assertValidCSG$1(moveobj.translate(calcFlush(moveobj, withobj, axis, mside, wside)), 'flush');
   }
+
+  /**
+   *
+   * @param {AxisStrings} axes
+   * @param {function(number, string): number} valfun
+   * @param {Array<number>} [a] In initial array to apply the values to, if not provided a new array will be created.
+   * @returns {Array<number>} The resulting array after applying the function to the specified axes.
+   */
   function axisApply(axes, valfun, a) {
     debug$2('axisApply', axes, valfun, a);
+
+    /** @type {Array<number>} */
     var retval = a || [0, 0, 0];
+
+    /** @type {Record<AxisString, number>} */
     var lookup = {
       x: 0,
       y: 1,
       z: 2
     };
     axes.split('').forEach(function (axis) {
-      retval[lookup[axis]] = valfun(lookup[axis], axis);
+      retval[lookup[(/** @type {AxisString} */axis)]] = valfun(lookup[(/** @type {AxisString} */axis)], axis);
     });
     return retval;
   }
   function axis2array(axes, valfun) {
-    depreciated('axis2array');
+    depreciated('axis2array', false, 'Use axisApply instead.');
     var a = [0, 0, 0];
     var lookup = {
       x: 0,
@@ -1997,7 +2400,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     });
   }
   function midlineTo(o, axis, to) {
-    return o.translate(calcmidlineTo(o, axis, to));
+    return assertValidCSG$1(o.translate(calcmidlineTo(o, axis, to)), 'midlineTo');
   }
   function translator(o, axis, withObj) {
     var objectCentroid = centroid(o);
@@ -2018,7 +2421,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     return delta ? add(t, delta) : t;
   }
   function centerWith(o, axis, withObj) {
-    return o.translate(calcCenterWith(o, axis, withObj));
+    return assertValidCSG$1(o.translate(calcCenterWith(o, axis, withObj)), 'centerWith');
   }
 
   /**
@@ -2048,6 +2451,109 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
       return bounds[0][a] + (isEmpty(dist) ? size[axis] / 2 : dist);
     });
   }
+  var EPS = 1e-5;
+
+  /**
+   * Split a CSG object into two halves along a plane by directly
+   * splitting polygons. This avoids BSP-tree-based boolean operations
+   * which can fail on geometry produced by stretchAtPlane.
+   * @param {CSG} csg  The object to split
+   * @param {CSG.Plane} plane  The splitting plane
+   * @return {{ front: CSG, back: CSG }} front (positive normal side) and back (negative normal side)
+   */
+  function splitCSGByPlane(csg, plane) {
+    var frontPolys = [];
+    var backPolys = [];
+    csg.polygons.forEach(function (poly) {
+      var vertices = poly.vertices;
+      var numVerts = vertices.length;
+      var hasfront = false;
+      var hasback = false;
+      var vertexIsBack = [];
+      for (var i = 0; i < numVerts; i++) {
+        var t = plane.normal.dot(vertices[i].pos) - plane.w;
+        vertexIsBack.push(t < 0);
+        if (t > EPS) hasfront = true;
+        if (t < -EPS) hasback = true;
+      }
+      if (!hasfront && !hasback) {
+        // coplanar — assign based on normal alignment
+        var d = plane.normal.dot(poly.plane.normal);
+        if (d >= 0) {
+          frontPolys.push(poly);
+        } else {
+          backPolys.push(poly);
+        }
+      } else if (!hasback) {
+        frontPolys.push(poly);
+      } else if (!hasfront) {
+        backPolys.push(poly);
+      } else {
+        // spanning — split the polygon
+        var fv = [];
+        var bv = [];
+        for (var vi = 0; vi < numVerts; vi++) {
+          var vertex = vertices[vi];
+          var nextVi = (vi + 1) % numVerts;
+          var isback = vertexIsBack[vi];
+          var nextisback = vertexIsBack[nextVi];
+          if (isback === nextisback) {
+            if (isback) {
+              bv.push(vertex);
+            } else {
+              fv.push(vertex);
+            }
+          } else {
+            var point = vertex.pos;
+            var nextpoint = vertices[nextVi].pos;
+            var ip = plane.splitLineBetweenPoints(point, nextpoint);
+            var iv = new CSG$1.Vertex(ip);
+            if (isback) {
+              bv.push(vertex);
+              bv.push(iv);
+              fv.push(iv);
+            } else {
+              fv.push(vertex);
+              fv.push(iv);
+              bv.push(iv);
+            }
+          }
+        }
+        // Remove degenerate (near-duplicate) adjacent vertices that arise
+        // when the cut plane passes very close to existing vertices.
+        // This matches the cleanup done by the BSP-tree splitter.
+        var EPSEPS = EPS * EPS;
+        if (fv.length >= 3) {
+          var prev = fv[fv.length - 1];
+          for (var fi = 0; fi < fv.length; fi++) {
+            var curr = fv[fi];
+            if (curr.pos.distanceToSquared(prev.pos) < EPSEPS) {
+              fv.splice(fi, 1);
+              fi--;
+            }
+            prev = curr;
+          }
+        }
+        if (bv.length >= 3) {
+          var prev = bv[bv.length - 1];
+          for (var bi = 0; bi < bv.length; bi++) {
+            var curr = bv[bi];
+            if (curr.pos.distanceToSquared(prev.pos) < EPSEPS) {
+              bv.splice(bi, 1);
+              bi--;
+            }
+            prev = curr;
+          }
+        }
+        if (fv.length >= 3) frontPolys.push(new CSG$1.Polygon(fv, poly.shared, poly.plane));
+        if (bv.length >= 3) backPolys.push(new CSG$1.Polygon(bv, poly.shared, poly.plane));
+      }
+    });
+    return {
+      front: CSG$1.fromPolygons(frontPolys),
+      back: CSG$1.fromPolygons(backPolys)
+    };
+  }
 
   /**
    * Cut an object into two pieces, along a given axis. The offset
@@ -2058,7 +2564,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
    *
    * You can angle the cut plane and position the rotation point.
    *
-   * ![bisect example](./images/bisect.png)
+   * ![bisect example](../test/images/bisect%20object%20positive.snap.png)
    * @param  {CSG} object object to bisect
    * @param  {string} axis   axis to cut along
    * @param  {number} [offset] offset to cut at
@@ -2136,13 +2642,13 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     }[[axis, rotateaxis].sort().join('')];
     var centroid = object.centroid();
     var rotateDelta = getDelta(objectSize, bounds, rotateOffsetAxis, rotateoffset);
-    var rotationCenter = options.rotationCenter || new CSG.Vector3D(axisApply('xyz', function (i, a) {
+    var rotationCenter = options.rotationCenter || new CSG$1.Vector3D(axisApply('xyz', function (i, a) {
       if (a == axis) return cutDelta[i];
       if (a == rotateOffsetAxis) return rotateDelta[i];
       return centroid[a];
     }));
     var theRotationAxis = rotationAxes[rotateaxis];
-    var cutplane = CSG.OrthoNormalBasis.GetCartesian(info.orthoNormalCartesian[0], info.orthoNormalCartesian[1]).translate(cutDelta).rotate(rotationCenter, theRotationAxis, angle);
+    var cutplane = CSG$1.OrthoNormalBasis.GetCartesian(info.orthoNormalCartesian[0], info.orthoNormalCartesian[1]).translate(cutDelta).rotate(rotationCenter, theRotationAxis, angle);
     debug$2('bisect', debug$2.enabled && {
       axis: axis,
       offset: offset,
@@ -2155,7 +2661,33 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
       cutplane: cutplane,
       options: options
     });
-    var g = Group('negative,positive', [object.cutByPlane(cutplane.plane).color(options.color && 'red'), object.cutByPlane(cutplane.plane.flipped()).color(options.color && 'blue')]);
+    var negative = object.cutByPlane(cutplane.plane);
+    var positive = object.cutByPlane(cutplane.plane.flipped());
+
+    // Detect cutByPlane failure: if a half's bounding box in the cut axis
+    // is not smaller than the original, the BSP-tree-based cut failed.
+    // Fall back to direct polygon splitting which is more robust, then
+    // apply cutByPlane to the simpler half to add cap faces.
+    var negSize = size(negative);
+    var posSize = size(positive);
+    if (negSize[axis] >= objectSize[axis] - EPS || posSize[axis] >= objectSize[axis] - EPS) {
+      var halves = splitCSGByPlane(object, cutplane.plane);
+      if (negSize[axis] >= objectSize[axis] - EPS) {
+        negative = halves.back;
+        // Cap the open cut face
+        try {
+          negative = negative.cutByPlane(cutplane.plane);
+        } catch (e) {/* keep uncapped */}
+      }
+      if (posSize[axis] >= objectSize[axis] - EPS) {
+        positive = halves.front;
+        // Cap the open cut face
+        try {
+          positive = positive.cutByPlane(cutplane.plane.flipped());
+        } catch (e) {/* keep uncapped */}
+      }
+    }
+    var g = Group('negative,positive', [negative.color(options.color && 'red'), positive.color(options.color && 'blue')]);
     if (options.addRotationCenter) g.add(unitAxis(objectSize.length() + 10, 0.1, rotationCenter), 'rotationCenter');
     return g;
   }
@@ -2180,9 +2712,9 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
       addRotationCenter: true
     };
     var info = normalVector(axis);
-    var rotationCenter = options.rotationCenter || new CSG.Vector3D(0, 0, 0);
+    var rotationCenter = options.rotationCenter || new CSG$1.Vector3D(0, 0, 0);
     var theRotationAxis = rotationAxes[rotateaxis];
-    var cutplane = CSG.OrthoNormalBasis.GetCartesian(info.orthoNormalCartesian[0], info.orthoNormalCartesian[1])
+    var cutplane = CSG$1.OrthoNormalBasis.GetCartesian(info.orthoNormalCartesian[0], info.orthoNormalCartesian[1])
     // .translate(cutDelta)
     .rotate(rotationCenter, theRotationAxis, angle);
     var g = Group('negative,positive', [object.cutByPlane(cutplane.plane).color(options.color && 'red'), object.cutByPlane(cutplane.plane.flipped()).color(options.color && 'blue')]);
@@ -2197,7 +2729,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
    * Creates a `JsCadUtilsGroup` object that has  `body` and `wedge` objects. The `wedge` object
    * is created by radially cutting the object from the `start` to the `end` angle.
    *
-   * ![wedge example](./images/wedge.png)
+   * ![wedge example](../test/images/wedge.snap.png)
    *
    *
    * @example
@@ -2253,7 +2785,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     var objectSize = size(object);
     var cutDelta = getDelta(objectSize, bounds, axis, offset, true);
     // debug('stretch.cutDelta', cutDelta, normal[axis]);
-    return object.stretchAtPlane(normal[axis], cutDelta, distance);
+    return assertValidCSG$1(object.stretchAtPlane(normal[axis], cutDelta, distance), 'stretch');
   }
 
   /**
@@ -2268,11 +2800,11 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
   function poly2solid(top, bottom, height) {
     if (top.sides.length == 0) {
       // empty!
-      return new CSG();
+      return new CSG$1();
     }
     // var offsetVector = CSG.parseOptionAs3DVector(options, "offset", [0, 0, 10]);
-    var offsetVector = CSG.Vector3D.Create(0, 0, height);
-    var normalVector = CSG.Vector3D.Create(0, 1, 0);
+    var offsetVector = CSG$1.Vector3D.Create(0, 0, height);
+    var normalVector = CSG$1.Vector3D.Create(0, 1, 0);
     var polygons = [];
     // bottom and top
     polygons = polygons.concat(bottom._toPlanePolygons({
@@ -2286,8 +2818,8 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
       flipped: offsetVector.z < 0
     }));
     // walls
-    var c1 = new CSG.Connector(offsetVector.times(0), [0, 0, offsetVector.z], normalVector);
-    var c2 = new CSG.Connector(offsetVector, [0, 0, offsetVector.z], normalVector);
+    var c1 = new CSG$1.Connector(offsetVector.times(0), [0, 0, offsetVector.z], normalVector);
+    var c2 = new CSG$1.Connector(offsetVector, [0, 0, offsetVector.z], normalVector);
     polygons = polygons.concat(bottom._toWallPolygons({
       cag: top,
       toConnector1: c1,
@@ -2295,7 +2827,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     }));
     // }
 
-    return CSG.fromPolygons(polygons);
+    return assertValidCSG$1(CSG$1.fromPolygons(polygons), 'poly2solid');
   }
   function slices2poly(slices, options, axis) {
     debug$2('slices2poly', slices, options, axis);
@@ -2304,7 +2836,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
       twiststeps: 0
     }, options);
     var twistangle = options && parseFloat(options.twistangle) || 0;
-    options && parseInt(options.twiststeps) || CSG.defaultResolution3D;
+    options && parseInt(options.twiststeps) || CSG$1.defaultResolution3D;
     var normalVector = options.si.normalVector;
     var polygons = [];
 
@@ -2343,8 +2875,8 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
         var nextidx = idx + 1;
         var top = !up ? slices[nextidx] : slice;
         var bottom = up ? slices[nextidx] : slice;
-        var c1 = new CSG.Connector(bottom.offset, connectorAxis, rotate(normalVector, twistangle, idx / slices.length));
-        var c2 = new CSG.Connector(top.offset, connectorAxis, rotate(normalVector, twistangle, nextidx / slices.length));
+        var c1 = new CSG$1.Connector(bottom.offset, connectorAxis, rotate(normalVector, twistangle, idx / slices.length));
+        var c2 = new CSG$1.Connector(top.offset, connectorAxis, rotate(normalVector, twistangle, nextidx / slices.length));
 
         // debug('slices2poly.slices', c1.point, c2.point);
         polygons = polygons.concat(bottom.poly._toWallPolygons({
@@ -2354,21 +2886,21 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
         }));
       }
     });
-    return CSG.fromPolygons(polygons);
+    return assertValidCSG$1(CSG$1.fromPolygons(polygons), 'slices2poly');
   }
   function normalVector(axis) {
     var axisInfo = {
       z: {
         orthoNormalCartesian: ['X', 'Y'],
-        normalVector: CSG.Vector3D.Create(0, 1, 0)
+        normalVector: CSG$1.Vector3D.Create(0, 1, 0)
       },
       x: {
         orthoNormalCartesian: ['Y', 'Z'],
-        normalVector: CSG.Vector3D.Create(0, 0, 1)
+        normalVector: CSG$1.Vector3D.Create(0, 0, 1)
       },
       y: {
-        orthoNormalCartesian: ['X', 'Z'],
-        normalVector: CSG.Vector3D.Create(0, 0, 1)
+        orthoNormalCartesian: ['Z', 'X'],
+        normalVector: CSG$1.Vector3D.Create(0, 0, 1)
       }
     };
     if (!axisInfo[axis]) error('normalVector: invalid axis ' + axis);
@@ -2420,7 +2952,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     var si = sliceParams(orientation, radius, b);
     debug$2('reShape', absoluteRadius, si);
     if (si.axis !== 'z') throw new Error('reShape error: CAG._toPlanePolygons only uses the "z" axis.  You must use the "z" axis for now.');
-    var cutplane = CSG.OrthoNormalBasis.GetCartesian(si.orthoNormalCartesian[0], si.orthoNormalCartesian[1]).translate(si.cutDelta);
+    var cutplane = CSG$1.OrthoNormalBasis.GetCartesian(si.orthoNormalCartesian[0], si.orthoNormalCartesian[1]).translate(si.cutDelta);
     var slice = object.sectionCut(cutplane);
     var first = axisApply(si.axis, function () {
       return si.positive ? 0 : absoluteRadius;
@@ -2435,25 +2967,25 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
       si: si
     }), si.axis).color(options.color);
     var remainder = object.cutByPlane(plane);
-    return union([options.unionOriginal ? object : remainder, delta.translate(si.moveDelta)]);
+    return assertValidCSG$1(union([options.unionOriginal ? object : remainder, delta.translate(si.moveDelta)]), 'reShape');
   }
   function chamfer(object, radius, orientation, options) {
-    return reShape(object, radius, orientation, options, function (first, last, slice) {
+    return assertValidCSG$1(reShape(object, radius, orientation, options, function (first, last, slice) {
       return [{
         poly: slice,
-        offset: new CSG.Vector3D(first)
+        offset: new CSG$1.Vector3D(first)
       }, {
         poly: enlarge(slice, [-radius * 2, -radius * 2]),
-        offset: new CSG.Vector3D(last)
+        offset: new CSG$1.Vector3D(last)
       }];
-    });
+    }), 'chamfer');
   }
   function fillet(object, radius, orientation, options) {
     options = options || {};
-    return reShape(object, radius, orientation, options, function (first, last, slice) {
-      var v1 = new CSG.Vector3D(first);
-      var v2 = new CSG.Vector3D(last);
-      var res = options.resolution || CSG.defaultResolution3D;
+    return assertValidCSG$1(reShape(object, radius, orientation, options, function (first, last, slice) {
+      var v1 = new CSG$1.Vector3D(first);
+      var v2 = new CSG$1.Vector3D(last);
+      var res = options.resolution || CSG$1.defaultResolution3D;
       var slices = range(0, res).map(function (i) {
         var p = i > 0 ? i / (res - 1) : 0;
         var v = v1.lerp(v2, p);
@@ -2464,7 +2996,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
         };
       });
       return slices;
-    });
+    }), 'fillet');
   }
   function calcRotate(part, solid, axis /* , angle */) {
     var axes = {
@@ -2483,7 +3015,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     var _calcRotate = calcRotate(part, solid, axis),
       rotationCenter = _calcRotate.rotationCenter,
       rotationAxis = _calcRotate.rotationAxis;
-    return part.rotate(rotationCenter, rotationAxis, angle);
+    return assertValidCSG$1('rotateAround')(part.rotate(rotationCenter, rotationAxis, angle));
   }
   function cloneProperties(from, to) {
     return Object.entries(from).reduce(function (props, _ref) {
@@ -2495,10 +3027,10 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     }, to);
   }
   function clone(o) {
-    var c = CSG.fromPolygons(o.toPolygons());
+    var c = CSG$1.fromPolygons(o.toPolygons());
     cloneProperties(o, c);
-    debug$2('clone', o, c, CSG);
-    return c;
+    debug$2('clone', o, c, CSG$1);
+    return assertValidCSG$1(c, 'clone');
   }
 
   /**
@@ -2514,11 +3046,12 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     var point = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : [0, 0, 0];
     var axis = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : [1, 0, 0];
     var normal = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : [0, 0, 1];
-    object.properties[name] = new CSG.Connector(point, axis, normal);
-    return object;
+    object.properties[name] = new CSG$1.Connector(point, axis, normal);
+    return assertValidCSG$1('addConnector')(object);
   }
 
   var debug$1 = Debug('jscadUtils:parts');
+  var assertValidCSG = AssertValidCSG('parts');
   var parts = {
     BBox: BBox$1,
     Cube: Cube,
@@ -2536,7 +3069,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
    */
   function BBox$1() {
     function box(object) {
-      return CSG.cube({
+      return CSG$1.cube({
         center: object.centroid(),
         radius: object.size().dividedBy(2)
       });
@@ -2544,17 +3077,17 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     for (var _len = arguments.length, objects = new Array(_len), _key = 0; _key < _len; _key++) {
       objects[_key] = arguments[_key];
     }
-    return objects.reduce(function (bbox, part) {
+    return assertValidCSG(objects.reduce(function (bbox, part) {
       var object = bbox ? union([bbox, box(part)]) : part;
       return box(object);
-    }, undefined);
+    }, undefined), 'BBox');
   }
   function Cube(width) {
     var r = div$1(fromxyz(width), 2);
-    return CSG.cube({
+    return assertValidCSG(CSG$1.cube({
       center: r,
       radius: r
-    });
+    }), 'Cube');
   }
 
   // export function Sphere(diameter) {
@@ -2588,11 +3121,11 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
       center: [r[0], r[1], 0],
       radius: r,
       roundradius: corner_radius,
-      resolution: CSG.defaultResolution2D
+      resolution: CSG$1.defaultResolution2D
     }).extrude({
       offset: [0, 0, thickness || 1.62]
     });
-    return roundedcube;
+    return assertValidCSG(roundedcube, 'RoundedCube');
   }
 
   /**
@@ -2610,9 +3143,9 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
       start: [0, 0, 0],
       end: [0, 0, height],
       radius: diameter / 2,
-      resolution: CSG.defaultResolution2D
+      resolution: CSG$1.defaultResolution2D
     }, options);
-    return CSG.cylinder(options);
+    return assertValidCSG(CSG$1.cylinder(options), 'Cylinder');
   }
 
   /**
@@ -2627,13 +3160,13 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
   function Cone(diameter1, diameter2, height) {
     var options = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
     debug$1('parts.Cone', diameter1, diameter2, height, options);
-    return CSG.cylinder(Object.assign({
+    return assertValidCSG(CSG$1.cylinder(Object.assign({
       start: [0, 0, 0],
       end: [0, 0, height],
       radiusStart: diameter1 / 2,
       radiusEnd: diameter2 / 2,
-      resolution: CSG.defaultResolution2D
-    }, options));
+      resolution: CSG$1.defaultResolution2D
+    }, options)), 'Cone');
   }
 
   /**
@@ -2646,9 +3179,9 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     var radius = diameter / 2;
     var sqrt3 = Math.sqrt(3) / 2;
     var hex = CAG.fromPoints([[radius, 0], [radius / 2, radius * sqrt3], [-radius / 2, radius * sqrt3], [-radius, 0], [-radius / 2, -radius * sqrt3], [radius / 2, -radius * sqrt3]]);
-    return hex.extrude({
+    return assertValidCSG(hex.extrude({
       offset: [0, 0, height]
-    });
+    }), 'Hexagon');
   }
 
   /**
@@ -2661,9 +3194,9 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
   function Triangle(base, height) {
     var radius = base / 2;
     var tri = CAG.fromPoints([[-radius, 0], [radius, 0], [0, Math.sin(30) * radius]]);
-    return tri.extrude({
+    return assertValidCSG(tri.extrude({
       offset: [0, 0, height]
-    });
+    }), 'Triangle');
   }
 
   /**
@@ -2678,7 +3211,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
    * @returns {CSG}  A CSG Tube
    */
   function Tube(outsideDiameter, insideDiameter, height, outsideOptions, insideOptions) {
-    return Cylinder(outsideDiameter, height, outsideOptions).subtract(Cylinder(insideDiameter, height, insideOptions || outsideOptions));
+    return assertValidCSG(Cylinder(outsideDiameter, height, outsideOptions).subtract(Cylinder(insideDiameter, height, insideOptions || outsideOptions)), 'Tube');
   }
 
   /**
@@ -2702,11 +3235,11 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
       center: [r[0], r[1], 0],
       radius: r,
       roundradius: corner_radius,
-      resolution: CSG.defaultResolution2D
+      resolution: CSG$1.defaultResolution2D
     }).extrude({
       offset: [0, 0, thickness || 1.62]
     });
-    return board;
+    return assertValidCSG(board, 'Board');
   }
   var Hardware = {
     Orientation: {
@@ -2856,7 +3389,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
    * This will bisect an object using a rabett join.  Returns a
    * `group` object with `positive` and `negative` parts.
    *
-   * * ![parts example](./images/rabett.png)
+   * ![rabett example](../test/images/boxes-Rabett.snap.png)
    * @example
    *include('dist/jscad-utils.jscad');
    *
@@ -2886,6 +3419,11 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     gap = gap || 0.25;
     var inside = thickness - gap;
     var outside = -thickness + gap;
+    var boxHeight = box.size().z;
+    if (Math.abs(height) >= boxHeight) {
+      throw new Error("Rabett: height (".concat(height, ") must be less than the object height (").concat(boxHeight, ")"));
+    }
+
     // options.color = true;
     debug('inside', inside, 'outside', outside);
     var group = Group();
@@ -2915,7 +3453,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
    * Used on a hollow object, this will rabett out the top and/or
    * bottom of the object.
    *
-   * ![A hollow hexagon with removable top and bottom](../images/rabett-tb.png)
+   * ![A hollow hexagon with removable top and bottom](../test/images/boxes-RabettTopBottom.snap.png)
    *
    * @example
    *include('dist/jscad-utils.jscad');
@@ -3002,10 +3540,10 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     thickness = thickness || 2;
     var s = div$1(xyz2array(size), 2);
     var r = add(s, thickness);
-    var box = CSG.cube({
+    var box = CSG$1.cube({
       center: r,
       radius: r
-    }).subtract(CSG.cube({
+    }).subtract(CSG$1.cube({
       center: r,
       radius: s
     }));
@@ -3020,7 +3558,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
    * wall thickness.  This is done by reducing the object by half the
    * thickness and subtracting the reduced version from the original object.
    *
-   * ![A hollowed out cylinder](../images/rabett.png)
+   * ![A hollowed out cylinder](../test/images/boxes-Rabett.snap.png)
    *
    * @param {CSG}   object    A CSG object
    * @param {Number}   [thickness=2] The thickness of the walls.
@@ -3048,7 +3586,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
   var BBox = function BBox(o) {
     depreciated('BBox', true, "Use 'parts.BBox' instead");
     var s = div$1(xyz2array(o.size()), 2);
-    return CSG.cube({
+    return CSG$1.cube({
       center: s,
       radius: s
     }).align(o, 'xyz');
@@ -3060,7 +3598,7 @@ var jscadUtils = (function (exports, jsCadCSG, scadApi) {
     var gap = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 0.25;
     var r = add(getRadius(box), -thickness / 2);
     r[2] = thickness / 2;
-    var cutter = CSG.cube({
+    var cutter = CSG$1.cube({
       center: r,
       radius: r
     }).align(box, 'xy').color('green');