openscad-cpp-evaluator 1.15.0__tar.gz → 1.18.0__tar.gz

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/CLAUDE.md

@@ -449,6 +449,39 @@ closed in one pass after a fresh "anything still unimplemented?" audit. Each bel
    all (`resolve_use_scopes`/`UseStatement` had zero hits in `openscad_evaluator`'s own `tests/`), so
    these were verified against real reference *behavior*, not ported from an existing test.
 
+   **File-level globals are evaluated ONCE per run (v1.16.0).** The main file's and every
+   `include`'s are, by the top-level statement pass, into the root `let_` level; a `use`d file's
+   are not -- `use` injects only declarations -- so `Evaluator::fileGlobal` evaluates ALL of that
+   file's top-level assignments, in source order, into a context of its own the first time anything
+   in the file reads one, and keeps it for the run. `ResolvedUseScopes::usedFileGlobals` carries
+   the per-file assignment lists and every entry point hands them over with
+   `Evaluator::setUsedFileGlobals` (CLI, both binding paths, the tests); a caller that skips that
+   keeps the old per-read fallback. Before this, `evalIdentifier`'s scope fallback re-evaluated the
+   assignment's expression on EVERY read from inside a function -- `callCtx()` isolates `let_` so the
+   root level was invisible -- which made `r = rands(0,1,1); function g() = r;` give `g() != g()`
+   (OpenSCAD: equal) and a 20K-element global list read 2000 times from a function cost 9.7s
+   (now 0.02s). Two deliberate divergences from OpenSCAD 2026.02.01, both verified against it:
+   a used file's globals are evaluated once, not once per call into the file (upstream's per-call
+   re-evaluation is a long-standing bug there, so its forward-read warning prints once here, not
+   per call); and a global read from a function BEFORE its assignment has run is `undef` with an
+   "Ignoring unknown variable" warning, exactly as upstream, where the old fallback had quietly
+   computed the not-yet-assigned value.
+**Scope-trail level table shrinks (v1.18.0).** `ScopeTrailStorage::parent_` and its indexed twin
+map level -> parent level in a vector indexed by level. Levels came from `++nextLevel_` and were
+never reused, so the vector grew 4 bytes per level for the whole run -- 3 x 64MB on a 13M-call
+script, plus the copy at every doubling -- and was 192MB of fractal_tree.scad's peak. A popped
+level is now marked -1 (0 still means "live, no parent": an isolated root), and when the NEWEST
+level dies `markDead` pops the vector back past every dead level above the newest live one, whose
+numbers `openLevel` then hands out again. Every invariant `lookup()`'s sorted-merge walk relies on
+holds: a reused number is greater than every level still holding an entry (all higher levels were
+dead and `popLevel` had already removed their entries), so a name's push-stack stays ascending,
+and a live level's number never changes -- an escaping closure that keeps a level alive simply
+stops the shrink at it (`tests/test_scope_trail.cpp` covers both). The ancestry walk now stops at
+`ancestor > 0` rather than `!= 0`. Same PR: `callCtxFor`'s per-call scan over active declarations
+does the integer span test before the origin STRING compare (`_platform_memcmp` was 1.4% of
+fractal_tree), and driveVm's completion branch no longer copies the finished frame's name. Anklet
+74 -> 63MB, a 4M-call synthetic 380 -> 258MB, fractal_tree -3.4% wall.
+
 **Known gap closed in Phase 3, worth remembering for Phase 5+**: every builtin resolve function must
 call `resolveCallArgs` (call_args.hpp), never bare `resolveArgs`, or a `$`-prefixed named call
 argument (`circle(r=2, $fn=64)`) silently fails to reach `ctx.dyn`. Caught by a geometric-correctness
@@ -910,6 +943,28 @@ grep for `ponytail:`.
   operation`. `linear_extrude`/`rotate_extrude`/`offset` are always-2D and `projection` always-3D, so
   they skip the "mixing" line and emit only the second; `roof()` emits neither, matching the
   reference. Background (`%`) children are exempt.
+  **The emptiness test is cached on the body (`ColoredBody::knownEmpty`, v1.17.0).** It used to
+  call `Manifold::NumTri()` on every child at every level, and every Manifold accessor goes through
+  `GetImpl()`, which materialises a lazy transform (a full mesh + collider copy) and runs a lazy
+  boolean -- so each leaf was copied once per ancestor transform, and because every node kept its
+  `bodies` until the tree died, all those copies stayed alive: fractal_tree.scad held 72,929
+  transformed copies of 1024 leaves (3.1GB). Now a body is asked once, the flag rides along on the
+  struct copies transform/colour/flatten make (emptiness is transform-invariant, and every generate
+  function that builds a new body starts from a fresh `ColoredBody`), and `generateTreeImpl` clears
+  each child's `bodies` once the parent has consumed them (move-assigning a fresh vector: `clear()`
+  and `= {}` both keep the capacity, and 35K nodes x 592-byte slots was 230MB) -- only top-level
+  bodies leave, a cache hit re-fills from the cache, and the bindings' `csg_tree` facade no longer
+  converts per-node bodies (it used to `GetMeshGL()` every node into numpy on every evaluate(), for
+  a dump that never read them). Three more forcing points had to go for the chain to stay lazy: the
+  booleans' `Status()` operand filter (now `bodyStatus()`, same cache), the boolean RESULT's own
+  emptiness (derived from the operands' flags -- a union is non-empty if any operand is -- rather
+  than asked), and `attachTriColors`, which `GetMeshGL()`'d every boolean result and now runs only
+  when the operands could actually disagree on colour. `Evaluator::generatedNodeCount` replaced
+  "does the child have bodies" as the cache-hit proxy in tests. Transforms compose lazily inside
+  Manifold and each leaf is transformed once, at the boolean that needs it. fractal_tree 3.1GB ->
+  0.67GB, Dalek 370 -> 277MB, snappy-reprap full_assembly 1.6GB -> 0.87GB; wall time neutral to
+  -3% interleaved. The output is geometrically identical (triangle count, area, volume) but not
+  byte-identical: Manifold evaluates one flat batch union instead of our old level-by-level order.
 
   Doing this centrally is also what keeps `generateCsg` safe: it builds ONE result and switches on
   whether it holds a `body` or a `section`, so a group that changed dimension part-way dereferenced

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/PKG-INFO

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

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/bindings/module.cpp

@@ -223,8 +223,9 @@ nb::dict idSpansToDict(const std::vector<IdSpan>& idSpans) {
     return d;
 }
 
-// CSGNode -> a facade `_CSGNode` (kind/params/bodies/is_builtin/children),
-// recursively, eagerly converting every field to plain Python data. No
+// CSGNode -> a facade `_CSGNode` (kind/params/is_builtin/children; `bodies`
+// is always empty, see below), recursively, eagerly converting every field
+// to plain Python data. No
 // lifetime extension needed -- CSGParams (Value-only, see csg_node.hpp) and
 // ColoredBody never hold AST pointers, so the result is fully self-contained
 // once built, unlike CSGNode::node itself (deliberately not exposed: the AST
@@ -234,15 +235,14 @@ nb::dict idSpansToDict(const std::vector<IdSpan>& idSpans) {
 nb::object csgNodeToPy(const oscadeval::CSGNode& node) {
     nb::dict params;
     for (const auto& [k, v] : node.params) params[nb::str(k.c_str())] = valueToPy(v);
+    // Deliberately no bodies. This used to GetMeshGL() every body of every
+    // node in the tree into numpy on every evaluate() -- and the only
+    // consumer, format_csg_tree(), never read them. Since v1.17.0 an inner
+    // node's bodies are released once its parent has consumed them (see
+    // generateTreeImpl), so there is nothing here to convert anyway; and a
+    // body the tree still holds may be a LAZY Manifold whose GetMeshGL()
+    // would materialise the very transform that release exists to avoid.
     nb::list bodies;
-    for (const oscadeval::ColoredBody& cb : node.bodies) {
-        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
-        // signature only because manifold3d's own API isn't const-qualified.
-        bodies.append(bodyToDict(const_cast<oscadeval::ColoredBody&>(cb)));
-    }
     nb::list children;
     for (const std::unique_ptr<oscadeval::CSGNode>& child : node.children) children.append(csgNodeToPy(*child));
     return facadeAttr("_CSGNode")(node.kind, params, bodies, node.isBuiltin, children);
@@ -457,6 +457,7 @@ nb::object evaluate(const std::string& path, nb::dict viewportParams,
             oscad::ParsedProgram program = oscad::getProgramFromFile(path);
             oscadeval::ResolvedUseScopes used = oscadeval::resolveUseScopes(program.nodes, path, logFn);
             oscadeval::Evaluator ev(logFn, nullptr, manifoldCache, oscadeval::DebugHooks{}, profile);
+            ev.setUsedFileGlobals(used.usedFileGlobals);
             oscadeval::EvalContext ctx = oscadeval::EvalContext::makeRoot(used.rootScope.get());
             bodies = oscadeval::toRenderableBodies(ev.evaluate(used.processedNodes, ctx, vp, generate));
             collectIdSpans(ev, idSpans);
@@ -764,6 +765,7 @@ nb::object debugEvaluate(const std::string& path, nb::dict viewportParams, nb::c
             oscadeval::Evaluator ev(echoCpp, nullptr, manifoldCache, hooks, false);
             evPtr = &ev;
             if (fastContinueSignal) ev.setFastContinueInterruptFlag(fastContinueSignal->flag());
+            ev.setUsedFileGlobals(used.usedFileGlobals);
             oscadeval::EvalContext ctx = oscadeval::EvalContext::makeRoot(used.rootScope.get());
             bodies = oscadeval::toRenderableBodies(ev.evaluate(used.processedNodes, ctx, vp));
             collectIdSpans(ev, idSpans);

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/include/openscad_cpp_evaluator/colored_body.hpp

@@ -53,6 +53,22 @@ struct ColoredBody {
     BodyRole role = BodyRole::Normal;
     std::optional<std::vector<std::array<float, 4>>> triColors; // per-triangle RGBA, multi-color CSG merges only
 
+    // Whether `body` is empty, once anything has asked (isEmptyBody,
+    // csg_generate.cpp). Asking Manifold is not free: every accessor goes
+    // through GetImpl(), which MATERIALIZES a lazy transform (a full copy of
+    // the mesh and its collider) and, for a boolean, runs it. Emptiness is
+    // invariant under transforms and colour, and every generate function
+    // that produces a genuinely new body starts from a fresh ColoredBody,
+    // so a copy carrying this flag is always still right. Before this, the
+    // dimension check at every tree level materialised every child at
+    // every level: fractal_tree.scad held 72,929 transformed copies of its
+    // 1024 leaf meshes at once (3.1GB).
+    std::optional<bool> knownEmpty;
+    // Same idea for Manifold::Status(), which the booleans consult to keep an
+    // invalid operand from poisoning a union: validity is transform-invariant
+    // too, and a boolean of valid operands is valid.
+    std::optional<manifold::Manifold::Error> knownStatus;
+
     // 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
@@ -75,6 +91,33 @@ struct ColoredBody {
     bool isDisplayOnly() const { return rawMesh.has_value(); }
 };
 
+// The cached questions -- see ColoredBody::knownEmpty. Ask Manifold once per
+// body, never once per tree level.
+inline bool bodyIsEmpty(ColoredBody& b) {
+    if (!b.knownEmpty) b.knownEmpty = !b.body || b.body->IsEmpty();
+    return *b.knownEmpty;
+}
+inline manifold::Manifold::Error bodyStatus(ColoredBody& b) {
+    if (!b.knownStatus) b.knownStatus = b.body ? b.body->Status() : manifold::Manifold::Error::NoError;
+    return *b.knownStatus;
+}
+
+// Emptiness of a union, from its operands' own flags and nothing else:
+// non-empty if any operand is known non-empty, empty if every one is known
+// empty, otherwise unknown (asked of Manifold later, if anyone ever asks).
+// `get` maps a range element to its ColoredBody.
+template <typename Range, typename Get>
+std::optional<bool> unionEmptyOf(const Range& ops, Get get) {
+    bool allKnownEmpty = true;
+    for (const auto& o : ops) {
+        const ColoredBody& b = get(o);
+        if (b.knownEmpty && !*b.knownEmpty) return false;
+        if (!b.knownEmpty) allKnownEmpty = false;
+    }
+    if (allKnownEmpty) return true;
+    return std::nullopt;
+}
+
 // `EvalContext::color`/CSGParams round-trip: a resolve function reads
 // ctx.color (double-precision, matching Value's own numeric type) but a
 // generate function only sees CSGParams (Value-typed, no ctx access) -- so

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/include/openscad_cpp_evaluator/eval_use.hpp

@@ -15,9 +15,21 @@ namespace oscadeval {
 // must keep this struct alive for as long as evaluation runs against
 // .rootScope/.processedNodes, since declarations injected from a used file
 // are raw (non-owning) pointers into it.
+// One used file's own top-level assignments, in source order, keyed by
+// that file's root Scope (the one its injected declarations were
+// re-anchored onto). Evaluator::setUsedFileGlobals takes the list so a
+// used file's globals can be evaluated ONCE per run, eagerly, the first
+// time anything in that file reads one -- see Evaluator::fileGlobal.
+// Raw pointers into usedFileAsts, same lifetime contract as processedNodes.
+struct UsedFileGlobals {
+    const oscad::Scope* root = nullptr;
+    std::vector<const oscad::ASTNode*> assignments;
+};
+
 struct ResolvedUseScopes {
     std::vector<std::vector<std::unique_ptr<oscad::ASTNode>>> usedFileAsts;
     std::vector<std::unique_ptr<oscad::Scope>> usedFileScopes;
+    std::vector<UsedFileGlobals> usedFileGlobals;
     // What currentFile should actually be evaluated as: declarations
     // injected via `use` (raw pointers into usedFileAsts, above), followed
     // by currentFile's own nodes (raw pointers into the caller-owned

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/include/openscad_cpp_evaluator/evaluator.hpp

@@ -7,6 +7,7 @@
 #include "openscad_cpp_evaluator/csg_node.hpp"
 #include "openscad_cpp_evaluator/debug_hooks.hpp"
 #include "openscad_cpp_evaluator/eval_context.hpp"
+#include "openscad_cpp_evaluator/eval_use.hpp"
 #include "openscad_cpp_evaluator/eval_error.hpp"
 #include "openscad_cpp_evaluator/font_provider.hpp"
 #include "openscad_cpp_evaluator/manifold_cache.hpp"
@@ -285,6 +286,11 @@ public:
                           const oscad::ASTNode* producer);
 
     std::unordered_map<uint32_t, const oscad::ASTNode*> idToNode;
+    // Nodes whose bodies were actually generated this run (not served from
+    // the ManifoldCache). Reset per run; a diagnostic, and the only honest
+    // way for a test to tell a cache hit from a miss now that an inner
+    // node's bodies are released the moment its parent has consumed them.
+    std::size_t generatedNodeCount = 0;
     std::unordered_map<uint32_t, std::optional<std::array<float, 4>>> idToColor;
 
     // Called by primitive-construction generate functions (cube, sphere,
@@ -1396,6 +1402,11 @@ public:
     // the same decision evalUserFunction*/evalFunctionLiteral* already
     // make before calling lookupOrCompileChunk/lookupCompiledLiteralChunk
     // themselves.
+    // Every used file's own top-level assignments (ResolvedUseScopes::
+    // usedFileGlobals), so fileGlobal() can evaluate a file's globals once.
+    // A caller that skips this keeps the old per-read fallback for used files.
+    void setUsedFileGlobals(std::vector<UsedFileGlobals> globals) { usedFileGlobals_ = std::move(globals); }
+
     bool useBytecodeVm() const {
         return bytecodeVmEnabled() && (!debugHooks_.debugHook || fastContinueBreakpoints_.has_value());
     }
@@ -1941,6 +1952,25 @@ private:
     // lifetime contract as every other raw AST/EvalContext pointer this
     // class holds).
     const EvalContext* rootCtx_ = nullptr;
+
+    // File-level globals are evaluated ONCE per run. The main file's (and
+    // every include's) already are, by the top-level statement pass, into
+    // rootCtx_'s own let_ level. A used file's are not -- `use` injects only
+    // its declarations -- so the first read of any global from that file
+    // evaluates ALL of its assignments, in source order, into a context of
+    // its own, kept here for the rest of the run. Before this, a function
+    // reading a global re-evaluated the assignment's expression on every
+    // read (evalIdentifier's scope fallback): `r = rands(0,1,1); function
+    // g() = r;` gave `g() != g()`, and a 20K-element global list read 2000
+    // times from a function cost 9.7s. OpenSCAD itself re-evaluates a used
+    // file's globals per CALL, which is a long-standing upstream bug, not
+    // behaviour to match. Returns nullopt for a file this evaluator was
+    // never told about (setUsedFileGlobals), so such a caller keeps the
+    // old fallback; nullptr for a known file whose global is not (yet)
+    // assigned -- a forward read, undef in OpenSCAD too.
+    std::optional<const Value*> fileGlobal(const oscad::Scope& fileRoot, const std::string& name);
+    std::vector<UsedFileGlobals> usedFileGlobals_;
+    std::unordered_map<const oscad::Scope*, EvalContext> usedFileCtx_;
     // The most recent ctx seen by evalStatement() -- error()'s only way to
     // reach a locals snapshot for its own errorBreak hook call, since
     // error() itself (called from dozens of builtin resolve functions)

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/include/openscad_cpp_evaluator/scope_trail.hpp

@@ -186,7 +186,7 @@ public:
             }
             dirty_.erase(it);
         }
-        parent_[static_cast<size_t>(level)] = 0; // dead: an ancestry walk stops here
+        markDead(level);
     }
 
     // nullptr if `name` has no binding on `myLevel`'s own ancestry chain.
@@ -211,7 +211,7 @@ public:
         const std::vector<Entry>& vec = it->second;
         auto idx = static_cast<long>(vec.size()) - 1;
         int ancestor = myLevel;
-        while (ancestor != 0 && idx >= 0) {
+        while (ancestor > 0 && idx >= 0) {
             const int entryLevel = vec[static_cast<size_t>(idx)].level;
             if (entryLevel > ancestor) {
                 --idx;
@@ -236,6 +236,11 @@ public:
         auto it = stacks_.find(name);
         return it == stacks_.end() ? 0 : it->second.size();
     }
+    // Test-only: how many level slots `parent_` currently holds (index 0
+    // included) -- lets ScopeTrailStorageTest assert that popping levels in
+    // call/return order really does shrink it back, and that an escaping
+    // closure's still-live level stops the shrink at itself.
+    size_t debugLevelSlotsForTesting() const { return parent_.size(); }
 
     // Ancestry-filtered snapshot -- O(total distinct names ever bound so
     // far in the whole evaluation), not O(names visible now). Only used
@@ -272,6 +277,27 @@ private:
     std::vector<int> parent_{0};
     int nextLevel_ = 0;
 
+    // A popped level is marked -1 (0 is a live level with no parent -- an
+    // isolated root -- so the two must stay distinguishable). Then, whenever
+    // the level being popped is the newest one, `parent_` shrinks back past
+    // every dead level above the newest still-live one, and its number is
+    // handed out again by the next openLevel(). This keeps every invariant
+    // lookup() relies on: a reused number is greater than every level still
+    // holding an entry (all higher levels were dead, and popLevel already
+    // removed their entries), so a name's push-stack stays ascending, and a
+    // live level's number never changes -- an escaping closure that keeps a
+    // level alive simply stops the shrink at it. Without this, `parent_`
+    // grew by one int per level for the whole run and never shrank: 3 x
+    // 64MB for a 13M-call script, plus the copy of each doubling.
+    void markDead(int level) {
+        parent_[static_cast<size_t>(level)] = -1;
+        if (level == nextLevel_) {
+            while (nextLevel_ > 0 && parent_[static_cast<size_t>(nextLevel_)] < 0) {
+                parent_.pop_back();
+                --nextLevel_;
+            }
+        }
+    }
 };
 
 // Per-EvalContext handle onto a shared ScopeTrailStorage<T>: this view's
@@ -473,7 +499,7 @@ public:
             }
             dirty_.erase(it);
         }
-        parent_[static_cast<size_t>(level)] = 0; // dead: an ancestry walk stops here
+        markDead(level);
     }
 
     // Same sorted-merge ancestry walk as ScopeTrailStorage::lookup -- see
@@ -485,7 +511,7 @@ public:
         const std::vector<Entry>& vec = stacks_[static_cast<size_t>(id)];
         auto idx = static_cast<long>(vec.size()) - 1;
         int ancestor = myLevel;
-        while (ancestor != 0 && idx >= 0) {
+        while (ancestor > 0 && idx >= 0) {
             const int entryLevel = vec[static_cast<size_t>(idx)].level;
             if (entryLevel > ancestor) {
                 --idx;
@@ -505,6 +531,7 @@ public:
         int id = intern_->idFor(name);
         return id >= 0 && static_cast<size_t>(id) < stacks_.size() ? stacks_[static_cast<size_t>(id)].size() : 0;
     }
+    size_t debugLevelSlotsForTesting() const { return parent_.size(); } // see ScopeTrailStorage's
 
     std::vector<std::pair<std::string, T>> items(int myLevel) const {
         std::vector<std::pair<std::string, T>> result;
@@ -530,6 +557,15 @@ private:
     std::vector<int> parent_{0}; // see ScopeTrailStorage::parent_
     int nextLevel_ = 0;
 
+    void markDead(int level) { // see ScopeTrailStorage::markDead
+        parent_[static_cast<size_t>(level)] = -1;
+        if (level == nextLevel_) {
+            while (nextLevel_ > 0 && parent_[static_cast<size_t>(nextLevel_)] < 0) {
+                parent_.pop_back();
+                --nextLevel_;
+            }
+        }
+    }
 };
 
 // Per-EvalContext handle onto a shared IndexedScopeTrailStorage<T> -- the

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/pyproject.toml

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

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/python/openscad_cpp_evaluator/__init__.py

@@ -123,8 +123,11 @@ class RootScope:
 
 class _CSGNode:
     """One resolved (and, after evaluate(), generated) node in the CSG tree --
-    mirrors the reference's CSGNode dataclass. `bodies` is a list of already-
-    converted ColoredBody dicts (see bodyToDict on the C++ side); `params` is
+    mirrors the reference's CSGNode dataclass. `bodies` is always empty since
+    v1.17.0: an inner node's bodies are released as soon as its parent has
+    consumed them, and converting every node's mesh to numpy on every
+    evaluate() was work nothing read (format_csg_tree() prints structure,
+    not geometry; the rendered bodies come back separately). `params` is
     plain Python data (numbers/strings/bools/lists/dicts/OscObject), never an
     AST pointer -- eagerly converted, no lifetime tie to the Evaluator that
     produced it. Used by format_csg_tree(); not otherwise part of the public

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/src/builtins/booleans.cpp

@@ -286,6 +286,14 @@ std::vector<ColoredBody> generateCsg(Evaluator& ev, const CSGParams& params, con
     std::vector<Part2d> res2d;
     bool have2d = false;
     size_t idx = 0;
+    // Whether the 3D operands could possibly disagree on colour. Only then
+    // is attachTriColors worth its GetMeshGL(), which evaluates the boolean
+    // and copies the whole mesh out -- at EVERY level of a nested union
+    // chain, when nothing but the top ever needed it. Operands that all
+    // carry the same colour and no per-triangle colours of their own can
+    // only produce a uniformly coloured result.
+    std::optional<std::optional<std::array<float, 4>>> firstColor;
+    bool mixedColors = false;
 
     size_t stmtIndex = 0;
     for (const Value& sizeVal : groupSizes) {
@@ -314,7 +322,7 @@ std::vector<ColoredBody> generateCsg(Evaluator& ev, const CSGParams& params, con
         allDo.insert(allDo.end(), split.displayOnly.begin(), split.displayOnly.end());
 
         std::vector<ColoredBody> bodies3d, sections2d;
-        for (const ColoredBody& c : split.foreground) {
+        for (ColoredBody& c : split.foreground) {
             // A body whose own Manifold::Status() isn't NoError (e.g.
             // NonFiniteVertex, from a degenerate accumulated transform deep
             // in an unrelated ancestor's positioning math -- found via a
@@ -331,7 +339,12 @@ std::vector<ColoredBody> generateCsg(Evaluator& ev, const CSGParams& params, con
             // operand and unioning everything else is the closest match to
             // its own behavior available without new numerical-robustness
             // work on Manifold's own boolean ops.
-            if (c.body && c.body->Status() == manifold::Manifold::Error::NoError) bodies3d.push_back(c);
+            if (c.body && bodyStatus(c) == manifold::Manifold::Error::NoError) bodies3d.push_back(c);
+        }
+        for (const ColoredBody& c : bodies3d) {
+            if (c.triColors) mixedColors = true;
+            if (!firstColor) firstColor = c.color;
+            else if (*firstColor != c.color) mixedColors = true;
         }
         for (const ColoredBody& c : split.foreground) {
             if (c.section) sections2d.push_back(c);
@@ -358,17 +371,33 @@ std::vector<ColoredBody> generateCsg(Evaluator& ev, const CSGParams& params, con
         if (!bodies3d.empty()) {
             manifold::Manifold grp = *bodies3d.front().body;
             for (size_t i = 1; i < bodies3d.size(); ++i) grp = grp + *bodies3d[i].body;
+            // The result stays LAZY inside Manifold: its emptiness is derived
+            // from the operands' flags here rather than asked, so a chain of
+            // unions under transforms is evaluated once, at the top, instead
+            // of once per level (see ColoredBody::knownEmpty).
+            const std::optional<bool> grpEmpty =
+                unionEmptyOf(bodies3d, [](const ColoredBody& b) -> const ColoredBody& { return b; });
+            const auto known = [](const std::optional<bool>& e, bool v) { return e && *e == v; };
             if (!res3d) {
                 ColoredBody cb;
                 cb.body = std::move(grp);
                 cb.color = bodies3d.front().color;
+                cb.knownStatus = manifold::Manifold::Error::NoError; // every operand was
+                cb.knownEmpty = grpEmpty;
                 res3d = std::move(cb);
             } else if (op == "union") {
                 res3d->body = *res3d->body + grp;
+                if (known(res3d->knownEmpty, false) || known(grpEmpty, false)) res3d->knownEmpty = false;
+                else if (known(res3d->knownEmpty, true) && known(grpEmpty, true)) res3d->knownEmpty = true;
+                else res3d->knownEmpty.reset();
             } else if (op == "difference") {
                 res3d->body = *res3d->body - grp;
+                if (known(res3d->knownEmpty, true)) res3d->knownEmpty = true;
+                else if (!known(grpEmpty, true)) res3d->knownEmpty.reset(); // subtracting nothing changes nothing
             } else if (op == "intersection") {
                 res3d->body = *res3d->body ^ grp;
+                if (known(res3d->knownEmpty, true) || known(grpEmpty, true)) res3d->knownEmpty = true;
+                else res3d->knownEmpty.reset();
             }
         }
         if (!sections2d.empty()) {
@@ -394,7 +423,7 @@ std::vector<ColoredBody> generateCsg(Evaluator& ev, const CSGParams& params, con
         }
     }
 
-    if (res3d && res3d->body) attachTriColors(ev, *res3d);
+    if (res3d && res3d->body && mixedColors) attachTriColors(ev, *res3d);
 
     std::vector<ColoredBody> result;
     if (res3d) result.push_back(std::move(*res3d));

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/src/builtins/color.cpp

@@ -65,8 +65,8 @@ namespace {
 // `union() { color("red") stroke(...); text(); }` had no red recorded for
 // the stroke's runs at all, so every run looked identical, the merge kept
 // the first child's colour, and the whole thing came out red.
-void recordRunColors(Evaluator& ev, const ColoredBody& b, const std::optional<std::array<float, 4>>& rgba) {
-    if (!b.body || b.body->IsEmpty()) return;
+void recordRunColors(Evaluator& ev, ColoredBody& b, const std::optional<std::array<float, 4>>& rgba) {
+    if (!b.body || bodyIsEmpty(b)) return;
     // A body that is still one original knows its own ID without building
     // a mesh -- the common case, and the cheap one.
     const int original = b.body->OriginalID();

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/src/builtins/control.cpp

@@ -68,6 +68,7 @@ ColoredBody combineBodies(const std::vector<ColoredBody>& bodies) {
         ColoredBody cb;
         cb.body = std::move(merged);
         cb.color = bodies3d.front()->color;
+        cb.knownEmpty = unionEmptyOf(bodies3d, [](const ColoredBody* b) -> const ColoredBody& { return *b; });
         return cb;
     }
     std::vector<const ColoredBody*> sections;

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/src/bytecode_vm.cpp

@@ -585,7 +585,7 @@ Value driveVm(Evaluator& ev, size_t floor) {
                 ev.vmCallStack_.pop_back();
                 std::optional<Evaluator::UserCallHandle> bracket = std::move(ev.vmCallBrackets_.back());
                 ev.vmCallBrackets_.pop_back();
-                const std::string finishedName = finished->logicalName;
+                const std::string& finishedName = finished->logicalName; // `finished` outlives every use below
                 const bool ownsModuleSplice = finished->ownsModuleSplice;
                 const std::uint64_t moduleRandsBefore = finished->moduleRandsBefore;
                 const oscad::ASTNode* moduleSpliceCallNode = finished->moduleSpliceCallNode;

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/src/csg_generate.cpp

@@ -81,6 +81,7 @@ std::vector<ColoredBody> Evaluator::generateTreeImpl(const std::vector<CSGNode*>
             insideHull = savedInsideHull;
 
             applyDimensionRules(node);
+            ++generatedNodeCount;
 
             auto it = dispatch.find(node.kind);
             if (node.isBuiltin && it != dispatch.end()) {
@@ -109,6 +110,25 @@ std::vector<ColoredBody> Evaluator::generateTreeImpl(const std::vector<CSGNode*>
                 manifoldCache_->put(*key, node.bodies);
                 if (!measuring_) cacheProducer_[*key] = node.node;
             }
+                // The children's bodies have been consumed (by the dispatch above,
+                // or flattened into this node's own) and nothing reads them again:
+                // only a TOP-LEVEL node's bodies leave this function, a cache hit
+                // re-fills a node from the cache, and the CSG-tree facade in the
+                // bindings never used them. Keeping them held every intermediate
+                // result of the whole tree alive until the tree died -- one
+                // transformed copy per level per leaf. A cache, when there is one,
+                // already holds its own reference to whatever it wants to keep.
+            // The children's bodies have been consumed (by the dispatch above,
+            // or flattened into this node's own) and nothing reads them again:
+            // only a TOP-LEVEL node's bodies leave this function, a cache hit
+            // re-fills a node from the cache, and the CSG-tree facade in the
+            // bindings never used them. Keeping them held every intermediate
+            // result of the whole tree alive until the tree died -- one
+            // transformed copy per level per leaf. A cache, when there is one,
+            // already holds its own reference to whatever it wants to keep.
+            // Move-assign a fresh vector, not clear() or `= {}`: both keep the
+            // capacity, and 35K nodes' worth of 592-byte slots was 230MB.
+            for (const std::unique_ptr<CSGNode>& c : node.children) c->bodies = std::vector<ColoredBody>();
         }
         for (const ColoredBody& b : node.bodies) topLevelBodies.push_back(b);
     }
@@ -151,8 +171,8 @@ DimRule dimRuleFor(const std::string& kind) {
     return DimRule::Group;
 }
 
-bool isEmptyBody(const ColoredBody& b) {
-    if (b.body) return b.body->NumTri() == 0;
+bool isEmptyBody(ColoredBody& b) {
+    if (b.body) return bodyIsEmpty(b); // see ColoredBody::knownEmpty
     if (b.section) return b.section->IsEmpty();
     return true;
 }

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/src/csg_resolve.cpp

@@ -216,6 +216,8 @@ std::vector<std::unique_ptr<CSGNode>> Evaluator::resolveTreeImpl(const NodeList&
     treeStack_.emplace_back();
     rootCtx_ = &ctx;
     lastCtx_ = &ctx;
+    usedFileCtx_.clear();
+    generatedNodeCount = 0;
     // Cleared here, not just guarded by inResolvePass_ below, so a host
     // that reuses one Evaluator across separate top-level resolveTree()/
     // evaluate() calls (each against a freshly re-parsed AST -- the normal

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/src/eval_use.cpp

@@ -87,6 +87,12 @@ ResolvedUseScopes resolveUseScopesInto(const std::vector<const oscad::ASTNode*>&
         for (auto& sc : nested.usedFileScopes) result.usedFileScopes.push_back(std::move(sc));
         result.usedFileScopes.push_back(std::move(nested.rootScope));
         if (!libInjected.empty()) reanchor.emplace_back(std::move(libInjected), result.usedFileScopes.back().get());
+        for (auto& g : nested.usedFileGlobals) result.usedFileGlobals.push_back(std::move(g));
+        UsedFileGlobals globals{result.usedFileScopes.back().get(), {}};
+        for (const oscad::ASTNode* n : nested.ownNodesFiltered) {
+            if (n->kind() == oscad::NodeKind::Assignment) globals.assignments.push_back(n);
+        }
+        result.usedFileGlobals.push_back(std::move(globals));
     }
 
     for (const oscad::ASTNode* nodePtr : ownNodes) {

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/src/expr_eval.cpp

@@ -162,9 +162,44 @@ Value Evaluator::evalIdentifier(const std::string& name, const oscad::Position*
         return Value{};
     }
     if (decl->kind() == oscad::NodeKind::ParameterDeclaration) return Value{};
+    // A file-level global (its declaring scope has no parent) is read back
+    // from its file's once-evaluated values, never re-evaluated -- see
+    // fileGlobal. Anything else (a module body's own variable reached from
+    // a function declared inside it) keeps the on-demand evaluation.
+    const oscad::Scope* declScope = ctx.scopeOf(*decl);
+    if (declScope && declScope->parent() == nullptr && rootCtx_) {
+        if (std::optional<const Value*> v = fileGlobal(*declScope, name)) {
+            if (*v) return **v;
+            if (warnIfUndef) warn("Ignoring unknown variable '" + name + "'", position);
+            return Value{};
+        }
+    }
     return evalExpr(*static_cast<const oscad::Assignment*>(decl)->expr, ctx);
 }
 
+std::optional<const Value*> Evaluator::fileGlobal(const oscad::Scope& fileRoot, const std::string& name) {
+    if (&fileRoot == rootCtx_->scope) return rootCtx_->let_->find(name);
+    auto it = usedFileCtx_.find(&fileRoot);
+    if (it == usedFileCtx_.end()) {
+        const UsedFileGlobals* globals = nullptr;
+        for (const UsedFileGlobals& g : usedFileGlobals_) {
+            if (g.root == &fileRoot) { globals = &g; break; }
+        }
+        if (!globals) return std::nullopt;
+        // Reference, not iterator: a global's initializer can call a function
+        // from ANOTHER used file, whose first read inserts here too, and a
+        // rehash invalidates iterators but never element references.
+        EvalContext& fctx = usedFileCtx_.emplace(&fileRoot, rootCtx_->callCtx(&fileRoot)).first->second;
+        // Source order, once; a read of a later global from an earlier one's
+        // initializer finds nothing yet and is undef, as in OpenSCAD.
+        for (const oscad::ASTNode* a : globals->assignments) {
+            evalAssignment(static_cast<const oscad::Assignment&>(*a), fctx);
+        }
+        return fctx.let_->find(name);
+    }
+    return it->second.let_->find(name);
+}
+
 // -- List comprehensions ----------------------------------------------
 
 // Debug checkpoints below mirror the reference's _eval_list_comp AND its

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.18.0}/src/user_calls.cpp

@@ -251,9 +251,13 @@ EvalContext Evaluator::callCtxFor(const oscad::ASTNode& decl, EvalContext& ctx,
     const oscad::Position& declPos = decl.position();
     for (const auto& [activeDecl, count] : activeDeclRefcount_) {
         const oscad::Position* outer = &activeDecl->position();
-        if (outer->origin != declPos.origin) continue;
+        // Integer span test first: it rejects almost every candidate, and the
+        // origin compare it used to follow is a string compare per active
+        // declaration per call.
         const bool sameSpan = (outer->start_offset == declPos.start_offset && outer->end_offset == declPos.end_offset);
-        if (!sameSpan && outer->start_offset <= declPos.start_offset && declPos.end_offset <= outer->end_offset) {
+        if (sameSpan || outer->start_offset > declPos.start_offset || declPos.end_offset > outer->end_offset) continue;
+        if (outer->origin != declPos.origin) continue;
+        {
             if (usedChildCtx) *usedChildCtx = true;
             return ctx.childCtx(scope, std::nullopt, std::move(childrenNodes), childrenCallerCtx);
         }