openscad-cpp-evaluator 0.14.0__tar.gz → 0.16.0__tar.gz

{openscad_cpp_evaluator-0.14.0 → openscad_cpp_evaluator-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_cpp_evaluator
-Version: 0.14.0
+Version: 0.16.0
 Summary: C++ OpenSCAD evaluator with Python bindings
 Author: NeuSCAD Contributors
 License-Expression: MIT

{openscad_cpp_evaluator-0.14.0 → openscad_cpp_evaluator-0.16.0}/bindings/CMakeLists.txt

@@ -15,6 +15,7 @@ find_package(nanobind CONFIG REQUIRED)
 # from-source Manifold/Boost rebuild per interpreter in CI.
 nanobind_add_module(_openscad_cpp_evaluator NB_STATIC STABLE_ABI
   module.cpp
+  ast_to_py.cpp
 )
 
 # The static evaluator lib PUBLIC-links parser + manifold + Boost::polygon,

openscad_cpp_evaluator-0.16.0/bindings/ast_to_py.cpp

@@ -0,0 +1,326 @@
+// Snapshots the parser's AST into plain Python dicts.
+//
+// Deliberately a COPY rather than wrappers around live ASTNode pointers.
+// The tree is owned by a `std::vector<std::unique_ptr<ASTNode>>` local to
+// whichever binding parsed it, and dies when that call returns; handing
+// Python raw pointers into it would be a use-after-free the moment anything
+// outlived the call, and this project has already shipped one dangling
+// pointer of exactly that shape (the bodyCtx bug fixed in v0.13.1). It also
+// sidesteps the threading problem entirely -- a render worker thread can
+// parse, hand the snapshot to the GUI thread, and exit, with nothing shared.
+//
+// The cost is one walk plus allocation per parse. That is affordable
+// because callers ask for this explicitly (parse_ast()), not on the render
+// path, which never needs it.
+//
+// Every node dict carries at least:
+//   kind      -- str, the NodeKind name ("NumberLiteral", "ModularCall", ...)
+//   position  -- dict(origin, line, column, start_offset, end_offset)
+// plus that kind's own fields, named in snake_case. Child nodes are nested
+// dicts; child lists are lists of dicts; an absent optional child is None.
+//
+// `position.start_offset`/`end_offset` are the point of the whole exercise:
+// they let a caller recover the ORIGINAL source text of any subexpression
+// and reuse it verbatim, rather than re-serialising a parsed value and
+// losing how the author wrote it (1.500 -> 1.5, 1e3 -> 1000).
+
+#include "openscad_cpp_parser/api.hpp"
+#include "openscad_cpp_parser/ast/ast_node.hpp"
+#include "openscad_cpp_parser/ast/comments.hpp"
+#include "openscad_cpp_parser/ast/declarations.hpp"
+#include "openscad_cpp_parser/ast/expression.hpp"
+#include "openscad_cpp_parser/ast/module_instantiation.hpp"
+#include "openscad_cpp_parser/ast/vector_element.hpp"
+
+#include <nanobind/nanobind.h>
+#include <nanobind/stl/string.h>
+
+#include <memory>
+#include <vector>
+
+namespace nb = nanobind;
+
+namespace oscadbind {
+
+namespace {
+
+nb::dict positionToPy(const oscad::Position& p) {
+    nb::dict d;
+    // origin is "" for the main file (matching how the evaluator reports
+    // it); left as-is rather than mapped to None, so a caller can compare
+    // it against a path without a null check.
+    d["origin"] = p.origin;
+    d["line"] = p.line;
+    d["column"] = p.column;
+    d["start_offset"] = p.start_offset;
+    d["end_offset"] = p.end_offset;
+    return d;
+}
+
+nb::object nodeToPy(const oscad::ASTNode* n);
+
+// A null unique_ptr child (e.g. a parameter with no default) becomes None
+// rather than being omitted, so a consumer can index the key unconditionally.
+template <typename T>
+nb::object childToPy(const std::unique_ptr<T>& p) {
+    return p ? nodeToPy(p.get()) : nb::none();
+}
+
+template <typename T>
+nb::list listToPy(const std::vector<std::unique_ptr<T>>& v) {
+    nb::list out;
+    for (const std::unique_ptr<T>& item : v) out.append(nodeToPy(item.get()));
+    return out;
+}
+
+nb::dict baseDict(const oscad::ASTNode* n) {
+    nb::dict d;
+    d["kind"] = oscad::nodeKindName(n->kind());
+    d["position"] = positionToPy(n->position());
+    return d;
+}
+
+nb::object nodeToPy(const oscad::ASTNode* n) {
+    if (n == nullptr) return nb::none();
+    nb::dict d = baseDict(n);
+
+    // kind() is authoritative about the concrete type (every leaf class sets
+    // its own), so static_cast is safe here and avoids a dynamic_cast per
+    // node on what is already an allocation-heavy walk.
+#define OSC_NODE(KindName, Type) case oscad::NodeKind::KindName: { const auto* x = static_cast<const oscad::Type*>(n); (void)x;
+#define OSC_END break; }
+
+    switch (n->kind()) {
+        // -- comments ---------------------------------------------------
+        OSC_NODE(CommentLine, CommentLine) d["text"] = x->text; OSC_END
+        OSC_NODE(BlankLine, BlankLine) OSC_END
+        OSC_NODE(CommentSpan, CommentSpan) d["text"] = x->text; OSC_END
+        OSC_NODE(CommentedExpr, CommentedExpr)
+            d["leading_comments"] = listToPy(x->leadingComments);
+            d["trailing_comments"] = listToPy(x->trailingComments);
+            d["expr"] = childToPy(x->expr);
+        OSC_END
+
+        // -- primaries / literals ---------------------------------------
+        OSC_NODE(Identifier, Identifier) d["name"] = x->name; OSC_END
+        // `val` is the DECODED string minus its quotes; escape sequences
+        // are kept raw (a source \n stays two characters). Use the span to
+        // recover exactly what was written.
+        OSC_NODE(StringLiteral, StringLiteral) d["val"] = x->val; OSC_END
+        // Parsed to double, so the source spelling (1.500, 1e3, 0x10) is
+        // NOT recoverable from here -- that is what the span is for.
+        OSC_NODE(NumberLiteral, NumberLiteral) d["val"] = x->val; OSC_END
+        OSC_NODE(BooleanLiteral, BooleanLiteral) d["val"] = x->val; OSC_END
+        OSC_NODE(UndefinedLiteral, UndefinedLiteral) OSC_END
+        OSC_NODE(RangeLiteral, RangeLiteral)
+            d["start"] = childToPy(x->start);
+            d["end"] = childToPy(x->end);
+            // Never null: the parser defaults an omitted step to 1.
+            d["step"] = childToPy(x->step);
+        OSC_END
+
+        // -- declarations / arguments -----------------------------------
+        OSC_NODE(ParameterDeclaration, ParameterDeclaration)
+            d["name"] = childToPy(x->name);
+            d["default_value"] = childToPy(x->defaultValue); // nullable
+            d["leading_comments"] = listToPy(x->leadingComments);
+            d["trailing_comments"] = listToPy(x->trailingComments);
+        OSC_END
+        OSC_NODE(PositionalArgument, PositionalArgument) d["expr"] = childToPy(x->expr); OSC_END
+        OSC_NODE(NamedArgument, NamedArgument)
+            d["name"] = childToPy(x->name);
+            d["expr"] = childToPy(x->expr);
+        OSC_END
+        OSC_NODE(Assignment, Assignment)
+            d["name"] = childToPy(x->name);
+            d["expr"] = childToPy(x->expr);
+        OSC_END
+
+        // -- prefix expression forms ------------------------------------
+        OSC_NODE(LetOp, LetOp)
+            d["assignments"] = listToPy(x->assignments);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(EchoOp, EchoOp)
+            d["arguments"] = listToPy(x->arguments);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(AssertOp, AssertOp)
+            d["arguments"] = listToPy(x->arguments);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(FunctionLiteral, FunctionLiteral)
+            d["parameters"] = listToPy(x->parameters);
+            d["body"] = childToPy(x->body);
+        OSC_END
+
+        // -- unary operators --------------------------------------------
+#define OSC_UNARY(KindName) OSC_NODE(KindName, KindName) d["expr"] = childToPy(x->expr); OSC_END
+        OSC_UNARY(UnaryMinusOp)
+        OSC_UNARY(LogicalNotOp)
+        OSC_UNARY(BitwiseNotOp)
+#undef OSC_UNARY
+
+        // -- binary operators -------------------------------------------
+#define OSC_BINARY(KindName)                                                                                          \
+    OSC_NODE(KindName, KindName) d["left"] = childToPy(x->left); d["right"] = childToPy(x->right); OSC_END
+        OSC_BINARY(AdditionOp)
+        OSC_BINARY(SubtractionOp)
+        OSC_BINARY(MultiplicationOp)
+        OSC_BINARY(DivisionOp)
+        OSC_BINARY(ModuloOp)
+        OSC_BINARY(ExponentOp)
+        OSC_BINARY(BitwiseAndOp)
+        OSC_BINARY(BitwiseOrOp)
+        OSC_BINARY(BitwiseShiftLeftOp)
+        OSC_BINARY(BitwiseShiftRightOp)
+        OSC_BINARY(LogicalAndOp)
+        OSC_BINARY(LogicalOrOp)
+        OSC_BINARY(EqualityOp)
+        OSC_BINARY(InequalityOp)
+        OSC_BINARY(GreaterThanOp)
+        OSC_BINARY(GreaterThanOrEqualOp)
+        OSC_BINARY(LessThanOp)
+        OSC_BINARY(LessThanOrEqualOp)
+#undef OSC_BINARY
+
+        OSC_NODE(TernaryOp, TernaryOp)
+            d["condition"] = childToPy(x->condition);
+            d["true_expr"] = childToPy(x->trueExpr);
+            d["false_expr"] = childToPy(x->falseExpr);
+        OSC_END
+
+        // -- postfix ----------------------------------------------------
+        OSC_NODE(PrimaryCall, PrimaryCall)
+            d["left"] = childToPy(x->left);
+            d["arguments"] = listToPy(x->arguments);
+        OSC_END
+        OSC_NODE(PrimaryIndex, PrimaryIndex)
+            d["left"] = childToPy(x->left);
+            d["index"] = childToPy(x->index);
+        OSC_END
+        OSC_NODE(PrimaryMember, PrimaryMember)
+            d["left"] = childToPy(x->left);
+            d["member"] = childToPy(x->member);
+        OSC_END
+
+        // -- list comprehension clauses ---------------------------------
+        OSC_NODE(ListCompLet, ListCompLet)
+            d["assignments"] = listToPy(x->assignments);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(ListCompEach, ListCompEach) d["body"] = childToPy(x->body); OSC_END
+        OSC_NODE(ListCompFor, ListCompFor)
+            d["assignments"] = listToPy(x->assignments);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(ListCompCFor, ListCompCFor)
+            d["inits"] = listToPy(x->inits);
+            d["condition"] = childToPy(x->condition);
+            d["incrs"] = listToPy(x->incrs);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(ListCompIf, ListCompIf)
+            d["condition"] = childToPy(x->condition);
+            d["true_expr"] = childToPy(x->trueExpr);
+        OSC_END
+        OSC_NODE(ListCompIfElse, ListCompIfElse)
+            d["condition"] = childToPy(x->condition);
+            d["true_expr"] = childToPy(x->trueExpr);
+            d["false_expr"] = childToPy(x->falseExpr);
+        OSC_END
+        // Also how a plain vector literal ([1,2,3]) is represented --
+        // elements mix comprehension clauses and bare expressions.
+        OSC_NODE(ListComprehension, ListComprehension) d["elements"] = listToPy(x->elements); OSC_END
+
+        // -- module instantiation ---------------------------------------
+        OSC_NODE(ModularCall, ModularCall)
+            d["name"] = childToPy(x->name);
+            d["arguments"] = listToPy(x->arguments);
+            d["children"] = listToPy(x->children);
+        OSC_END
+        OSC_NODE(ModularFor, ModularFor)
+            d["assignments"] = listToPy(x->assignments);
+            d["body"] = listToPy(x->body);
+        OSC_END
+        OSC_NODE(ModularIntersectionFor, ModularIntersectionFor)
+            d["assignments"] = listToPy(x->assignments);
+            d["body"] = listToPy(x->body);
+        OSC_END
+        OSC_NODE(ModularLet, ModularLet)
+            d["assignments"] = listToPy(x->assignments);
+            d["children"] = listToPy(x->children);
+        OSC_END
+        OSC_NODE(ModularEcho, ModularEcho)
+            d["arguments"] = listToPy(x->arguments);
+            d["children"] = listToPy(x->children);
+        OSC_END
+        OSC_NODE(ModularAssert, ModularAssert)
+            d["arguments"] = listToPy(x->arguments);
+            d["children"] = listToPy(x->children);
+        OSC_END
+        OSC_NODE(ModularIf, ModularIf)
+            d["condition"] = childToPy(x->condition);
+            d["true_branch"] = listToPy(x->trueBranch);
+        OSC_END
+        OSC_NODE(ModularIfElse, ModularIfElse)
+            d["condition"] = childToPy(x->condition);
+            d["true_branch"] = listToPy(x->trueBranch);
+            d["false_branch"] = listToPy(x->falseBranch);
+        OSC_END
+
+        // -- modifier wrappers (! # % *) --------------------------------
+#define OSC_MODIFIER(KindName) OSC_NODE(KindName, KindName) d["child"] = childToPy(x->child); OSC_END
+        OSC_MODIFIER(ModularModifierShowOnly)
+        OSC_MODIFIER(ModularModifierHighlight)
+        OSC_MODIFIER(ModularModifierBackground)
+        OSC_MODIFIER(ModularModifierDisable)
+#undef OSC_MODIFIER
+
+        // -- top-level declarations -------------------------------------
+        OSC_NODE(ModuleDeclaration, ModuleDeclaration)
+            d["name"] = childToPy(x->name);
+            d["parameters"] = listToPy(x->parameters);
+            d["children"] = listToPy(x->children);
+            d["pre_name_comments"] = listToPy(x->preNameComments);
+            d["post_name_comments"] = listToPy(x->postNameComments);
+            d["post_params_comments"] = listToPy(x->postParamsComments);
+        OSC_END
+        OSC_NODE(FunctionDeclaration, FunctionDeclaration)
+            d["name"] = childToPy(x->name);
+            d["parameters"] = listToPy(x->parameters);
+            d["expr"] = childToPy(x->expr);
+            d["pre_name_comments"] = listToPy(x->preNameComments);
+            d["post_name_comments"] = listToPy(x->postNameComments);
+            d["post_params_comments"] = listToPy(x->postParamsComments);
+        OSC_END
+        OSC_NODE(UseStatement, UseStatement) d["filepath"] = childToPy(x->filepath); OSC_END
+        OSC_NODE(IncludeStatement, IncludeStatement) d["filepath"] = childToPy(x->filepath); OSC_END
+    }
+
+#undef OSC_NODE
+#undef OSC_END
+
+    // No default: above -- the switch is exhaustive over NodeKind, so
+    // adding a node kind to the parser without handling it here is a
+    // compiler warning rather than a silently field-less dict.
+    return d;
+}
+
+} // namespace
+
+nb::list astToPy(const std::vector<std::unique_ptr<oscad::ASTNode>>& ast) {
+    nb::list out;
+    for (const std::unique_ptr<oscad::ASTNode>& n : ast) out.append(nodeToPy(n.get()));
+    return out;
+}
+
+nb::list parseAstFromFile(const std::string& path, bool includeComments) {
+    return astToPy(oscad::getASTFromFile(path, includeComments));
+}
+
+nb::list parseAstFromString(const std::string& code, bool includeComments) {
+    return astToPy(oscad::getASTFromString(code, includeComments));
+}
+
+} // namespace oscadbind

{openscad_cpp_evaluator-0.14.0 → openscad_cpp_evaluator-0.16.0}/bindings/module.cpp

@@ -40,6 +40,14 @@
 
 namespace nb = nanobind;
 
+// Defined in ast_to_py.cpp -- snapshots the parser's AST into plain Python
+// dicts. Declared here rather than in a header since these two entry points
+// are the whole interface and only this file calls them.
+namespace oscadbind {
+nb::list parseAstFromFile(const std::string& path, bool includeComments);
+nb::list parseAstFromString(const std::string& code, bool includeComments);
+} // namespace oscadbind
+
 namespace {
 
 // Moves a std::vector's storage into a NumPy array that owns it via a
@@ -129,7 +137,11 @@ const char* roleToString(oscadeval::BodyRole role) {
 // tri_verts (nTri, 3), run_original_id (nRun,), run_index (nRun+1,) -- the
 // same flat 3*triangle units manifold3d's own run_index uses).
 nb::dict bodyToDict(oscadeval::ColoredBody& cb) {
-    manifold::MeshGL mesh = cb.body->GetMeshGL();
+    // A display-only body's Manifold is empty by construction, so its
+    // GetMeshGL() would hand back nothing -- take the raw triangle soup
+    // that failed to build instead. Everything downstream reads plain
+    // arrays, so the two cases are indistinguishable from here on.
+    manifold::MeshGL mesh = cb.isDisplayOnly() ? *cb.rawMesh : cb.body->GetMeshGL();
     const size_t numProp = mesh.numProp;
     const size_t numVert = numProp ? mesh.vertProperties.size() / numProp : 0;
     const size_t numTri = mesh.triVerts.size() / 3;
@@ -184,7 +196,9 @@ void collectIdSpans(const oscadeval::Evaluator& ev, std::vector<IdSpan>& out) {
 nb::list bodiesToList(std::vector<oscadeval::ColoredBody>& bodies) {
     nb::list out;
     for (oscadeval::ColoredBody& cb : bodies) {
-        if (!cb.body || cb.body->IsEmpty()) continue;
+        // isDisplayOnly() bodies are ALWAYS IsEmpty() -- that's what made
+        // an open polyhedron() silently vanish here rather than render.
+        if (!cb.isDisplayOnly() && (!cb.body || cb.body->IsEmpty())) continue;
         out.append(bodyToDict(cb));
     }
     return out;
@@ -210,7 +224,7 @@ nb::object csgNodeToPy(const oscadeval::CSGNode& node) {
     for (const auto& [k, v] : node.params) params[nb::str(k.c_str())] = valueToPy(v);
     nb::list bodies;
     for (const oscadeval::ColoredBody& cb : node.bodies) {
-        if (!cb.body || cb.body->IsEmpty()) continue;
+        if (!cb.isDisplayOnly() && (!cb.body || cb.body->IsEmpty())) continue;
         // ColoredBody here is const in this walk (tree ownership stays with
         // the caller) -- GetMeshGL() itself is logically read-only, so a
         // const_cast here is safe/local, mirroring bodyToDict's mutating
@@ -643,6 +657,12 @@ NB_MODULE(_openscad_cpp_evaluator, m) {
           "Evaluate a .scad file; return (bodies, echoes, id_to_node, csg_tree, profile_result, dyn, dyn_explicit).");
     m.def("parse_decls", &parseDecls, nb::arg("path"),
           "Parse a .scad file; return top-level declaration (namespace, name, start, end, line, column, origin) tuples.");
+    m.def("parse_ast", &oscadbind::parseAstFromFile, nb::arg("path"), nb::arg("include_comments") = false,
+          "Parse a .scad file; return the AST as a list of plain nested dicts "
+          "(kind, position, plus that kind's own fields). A snapshot, not a view -- "
+          "safe to keep, share across threads, and outlive the parse.");
+    m.def("parse_ast_string", &oscadbind::parseAstFromString, nb::arg("code"), nb::arg("include_comments") = false,
+          "As parse_ast(), but parses a source string instead of a file.");
     m.def("debug_evaluate", &debugEvaluate, nb::arg("path"), nb::arg("viewport_params"), nb::arg("debug_hook"),
           nb::arg("error_break"), nb::arg("echo_fn"), nb::arg("manifold_cache") = nullptr,
           nb::arg("return_hook") = nb::none(), nb::arg("fast_continue_signal") = nullptr,

{openscad_cpp_evaluator-0.14.0 → openscad_cpp_evaluator-0.16.0}/include/openscad_cpp_evaluator/colored_body.hpp

@@ -26,6 +26,27 @@ struct ColoredBody {
     bool flatPreview = false;
     BodyRole role = BodyRole::Normal;
     std::optional<std::vector<std::array<float, 4>>> triColors; // per-triangle RGBA, multi-color CSG merges only
+
+    // Set ONLY when a mesh could not be built into a valid Manifold -- in
+    // practice a polyhedron() whose faces don't close the surface (it has
+    // boundary edges), which Manifold reports by returning an *empty* body
+    // with Status() == NotManifold rather than by failing. Note the status
+    // name is misleading: a closed mesh with reversed winding, non-manifold
+    // vertices or self-intersections builds fine; only an OPEN one lands
+    // here.
+    //
+    // Carrying the raw triangle soup alongside lets the renderer still draw
+    // what the script described, which is far more use for spotting the
+    // missing face than an empty viewport. `body` is deliberately left set
+    // (and empty), so every existing `cb.body->...` path keeps working.
+    //
+    // Such a body is display-only: it can never take part in a CSG
+    // operation, since there is no Manifold for Manifold to operate on.
+    // splitByRole() pulls it aside much as it does a `%` background body,
+    // and the CSG/hull/minkowski generators re-join it unchanged.
+    std::optional<manifold::MeshGL> rawMesh;
+
+    bool isDisplayOnly() const { return rawMesh.has_value(); }
 };
 
 // `EvalContext::color`/CSGParams round-trip: a resolve function reads

{openscad_cpp_evaluator-0.14.0 → openscad_cpp_evaluator-0.16.0}/include/openscad_cpp_evaluator/evaluator.hpp

@@ -236,6 +236,18 @@ public:
     // comment for why that reference exists at all).
     ColoredBody tagGenerated(manifold::Manifold body, const oscad::ASTNode& node, const Value& colorValue);
 
+    // tagGenerated()'s counterpart for a mesh Manifold refused to build --
+    // an open polyhedron(). Returns a display-only ColoredBody (see
+    // ColoredBody::rawMesh) carrying the triangle soup as-is, so it can
+    // still be drawn even though no CSG operation can ever touch it.
+    //
+    // A failed Manifold has no run IDs of its own, so one is reserved here
+    // and written onto the raw mesh -- otherwise the body would be
+    // invisible to selection and to the originalID -> AST node mapping
+    // that drives click-to-source, which is exactly when a user most wants
+    // to click the broken thing and be shown the line that made it.
+    ColoredBody tagDisplayOnly(manifold::MeshGL mesh, const oscad::ASTNode& node, const Value& colorValue);
+
     // Raises an OpenSCAD-level runtime error: throws EvalError with the
     // formatted "ERROR: {msg}{TRACE lines}" message (see eval_error.hpp),
     // walking the real user function/module call stack for the TRACE lines

{openscad_cpp_evaluator-0.14.0 → openscad_cpp_evaluator-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "openscad_cpp_evaluator"
-version = "0.14.0"
+version = "0.16.0"
 description = "C++ OpenSCAD evaluator with Python bindings"
 readme = "README.md"
 requires-python = ">=3.12"

{openscad_cpp_evaluator-0.14.0 → openscad_cpp_evaluator-0.16.0}/python/openscad_cpp_evaluator/__init__.py

@@ -18,7 +18,7 @@ from ._openscad_cpp_evaluator import FastContinueSignal, ManifoldCache
 __all__ = [
     "Evaluator", "ColoredBody", "EvalError", "ParseError", "OscObject", "parse", "to_renderable_bodies",
     "ManifoldCache", "CallSiteProfile", "ProfileResult", "format_csg_tree", "bodies_from_dicts",
-    "FastContinueSignal",
+    "FastContinueSignal", "parse_ast", "parse_ast_string",
 ]
 
 
@@ -256,6 +256,41 @@ def parse(path: str) -> RootScope:
     return RootScope(decls)
 
 
+def parse_ast(path: str, include_comments: bool = False) -> list:
+    """Parse a .scad file; return its AST as a list of plain nested dicts.
+
+    Each node is `{"kind": str, "position": {...}, **fields}`, where fields
+    are that kind's own (e.g. NumberLiteral has "val"; ModularCall has
+    "name"/"arguments"/"children"). Child nodes nest as dicts, child lists
+    as lists, and an absent optional child is None.
+
+    `position` carries `start_offset`/`end_offset`, which is the point of
+    this API: they let a caller slice the ORIGINAL source text of any
+    subexpression and reuse it verbatim, instead of re-serialising a parsed
+    value and losing how it was written (`1.500` -> `1.5`, `1e3` -> `1000`).
+
+    This is a SNAPSHOT, not a view of live parser memory: it is safe to
+    keep, mutate, share across threads, and outlive the parse. That costs
+    one walk per call, which is why it is a separate entry point rather
+    than something evaluate() always pays for.
+
+    Raises ParseError on a syntax error.
+    """
+    try:
+        return _ext.parse_ast(path, include_comments)
+    except Exception as e:
+        raise ParseError(str(e)) from e
+
+
+def parse_ast_string(code: str, include_comments: bool = False) -> list:
+    """As `parse_ast`, but parses a source string. `position.origin` is
+    "<string>" for every node. Raises ParseError on a syntax error."""
+    try:
+        return _ext.parse_ast_string(code, include_comments)
+    except Exception as e:
+        raise ParseError(str(e)) from e
+
+
 class _MeshShim:
     """Duck-types a manifold3d mesh: the four arrays the renderer reads."""
     __slots__ = ("vert_properties", "tri_verts", "run_original_id", "run_index", "num_prop")

{openscad_cpp_evaluator-0.14.0 → openscad_cpp_evaluator-0.16.0}/src/builtins/booleans.cpp

@@ -27,8 +27,19 @@ RoleSplit splitByRole(const std::vector<ColoredBody>& bodies) {
     for (const ColoredBody& c : bodies) {
         if (c.role == BodyRole::Background) r.background.push_back(c);
     }
+    // Checked before the foreground sweep below and excluded from it: a
+    // display-only body has an empty Manifold, so letting it reach a
+    // boolean would silently zero the whole operation (the same failure
+    // mode invalid operands caused before they were filtered out).
     for (const ColoredBody& c : bodies) {
-        if (c.role != BodyRole::Background && c.role != BodyRole::ShowOnly) r.foreground.push_back(c);
+        if (c.isDisplayOnly() && c.role != BodyRole::Background && c.role != BodyRole::ShowOnly) {
+            r.displayOnly.push_back(c);
+        }
+    }
+    for (const ColoredBody& c : bodies) {
+        if (c.role != BodyRole::Background && c.role != BodyRole::ShowOnly && !c.isDisplayOnly()) {
+            r.foreground.push_back(c);
+        }
     }
     for (const ColoredBody& c : r.foreground) {
         if (c.role == BodyRole::Highlight) r.highlight.push_back(c);
@@ -160,7 +171,7 @@ std::vector<ColoredBody> generateCsg(Evaluator& ev, const CSGParams& params, con
     const std::string& op = std::get<std::string>(params.at("op"));
     const auto& groupSizes = std::get<ListPtr>(params.at("group_sizes"))->items;
 
-    std::vector<ColoredBody> allBg, allHi, allSo;
+    std::vector<ColoredBody> allBg, allHi, allSo, allDo;
     std::optional<ColoredBody> csgResult;
     size_t idx = 0;
 
@@ -173,6 +184,7 @@ std::vector<ColoredBody> generateCsg(Evaluator& ev, const CSGParams& params, con
         allBg.insert(allBg.end(), split.background.begin(), split.background.end());
         allHi.insert(allHi.end(), split.highlight.begin(), split.highlight.end());
         allSo.insert(allSo.end(), split.showOnly.begin(), split.showOnly.end());
+        allDo.insert(allDo.end(), split.displayOnly.begin(), split.displayOnly.end());
 
         std::vector<ColoredBody> bodies3d, sections2d;
         for (const ColoredBody& c : split.foreground) {
@@ -251,6 +263,7 @@ std::vector<ColoredBody> generateCsg(Evaluator& ev, const CSGParams& params, con
     result.insert(result.end(), allBg.begin(), allBg.end());
     result.insert(result.end(), allHi.begin(), allHi.end());
     result.insert(result.end(), allSo.begin(), allSo.end());
+    result.insert(result.end(), allDo.begin(), allDo.end());
     return result;
 }
 

{openscad_cpp_evaluator-0.14.0 → openscad_cpp_evaluator-0.16.0}/src/builtins/builtins.hpp

@@ -77,11 +77,23 @@ std::vector<ColoredBody> generateCsg(Evaluator& ev, const CSGParams& params,
 // splitting/2D-merge logic.
 struct RoleSplit {
     std::vector<ColoredBody> background;
-    std::vector<ColoredBody> foreground; // role != Background && role != ShowOnly
+    std::vector<ColoredBody> foreground; // role != Background && role != ShowOnly, and not display-only
     std::vector<ColoredBody> highlight;  // the subset of `foreground` that's role == Highlight
     std::vector<ColoredBody> showOnly;
+    // Bodies with no Manifold to operate on (an open polyhedron -- see
+    // ColoredBody::rawMesh). Split out for the same reason showOnly is:
+    // they must survive a CSG/hull/minkowski step untouched rather than be
+    // merged into it, since there is nothing to merge. Kept separate from
+    // `background` because they render as ordinary geometry, not as a
+    // translucent ghost.
+    std::vector<ColoredBody> displayOnly;
 };
 RoleSplit splitByRole(const std::vector<ColoredBody>& bodies);
+
+// manifold::ToString(Manifold::Error) only exists under MANIFOLD_DEBUG --
+// not enabled in this build -- so this mirrors it. Shared by import.cpp and
+// primitives_3d.cpp, both of which report why a mesh wouldn't build.
+std::string manifoldErrorName(manifold::Manifold::Error e);
 std::optional<manifold::CrossSection> toCrossSection(const std::vector<ColoredBody>& bodies);
 
 // Merges a statement's bodies into one (3D union, else 2D union, else an