openscad-cpp-evaluator 0.31.2__tar.gz → 0.32.2__tar.gz

{openscad_cpp_evaluator-0.31.2 → openscad_cpp_evaluator-0.32.2}/CLAUDE.md

@@ -12,14 +12,26 @@ OpenSCAD AST and produces Manifold CSG geometry. This port builds on two depende
   tag, not vendored) — wired in as of Phase 2
 - Boost.Polygon (`boostorg/polygon` + `boostorg/config`, fetched individually — not the full Boost
   superproject) for `roof()`'s Voronoi-diagram construction — wired in as of Phase 6, see below
-- `nothings/stb` (`stb_image.h`, `stb_truetype.h`; header-only, no build step) for `surface()`'s
-  PNG loader and the built-in `FontProvider` default's TTF parsing/outline extraction — wired in as
-  of Phase 7
+- `nothings/stb` (`stb_image.h`; header-only, no build step) for `surface()`'s PNG loader — wired
+  in as of Phase 7
+- FreeType (`VER-2-14-3`) and HarfBuzz (`14.3.1`), both via `FetchContent` — the font backend:
+  HarfBuzz shapes, FreeType supplies outlines and face metrics. Deliberately NOT fontconfig, the
+  third leg of real OpenSCAD's font stack: it is meson-only (no CMake build at all), needs expat,
+  and wants a runtime `fonts.conf` plus a cache directory, none of which survives contact with six
+  cibuildwheel targets. `src/text/font_match.cpp` reimplements the part of it that `font=` actually
+  uses — spec syntax and directory scanning — so name matching behaves identically everywhere
+  rather than only where a fontconfig build exists. The two libraries are also kept independent of
+  *each other* (`HB_HAVE_FREETYPE=OFF`): HarfBuzz reads the font through its own hb-ot tables
+  reader, so no `find_package(Freetype)` has to resolve against a FetchContent target that is
+  installed nowhere. Both address glyphs by the same font-internal index and both work in font
+  units (`hb_font_set_scale` to unitsPerEm on one side, `FT_LOAD_NO_SCALE` on the other), so the
+  split costs nothing to bridge.
 
 The full design and phase-by-phase build order live in the plan this repo is being built from:
 `/Users/gminette/.claude/plans/please-plan-out-a-twinkly-anchor.md`. Read it before starting a new
 phase — it has the rationale for every non-obvious choice (value model, `EvalContext` lifetime,
-the `FontProvider` callback abstraction for Qt-hosted cross-platform font support, why Manifold's
+the `FontProvider` abstraction (whose built-in backend has since become
+FreeType/HarfBuzz rather than the stb_truetype single-font default the plan describes), why Manifold's
 own vendored `linalg.h` types and not GLM/Eigen, etc.) and the exit criterion each phase needs to
 hit before the next one starts. §6a was corrected during Phase 2 after checking Manifold's real
 source (it no longer uses GLM) — a live example of why the plan says to verify API assumptions
@@ -43,7 +55,7 @@ CSG-tree shape like union/difference/intersection, role-split via the shared `sp
 `POLYLINE`) and SVG (`path`/`polygon`/`polyline`/`rect`/`circle`/`ellipse`, nested
 `transform=`, all path commands including elliptical arcs) 2D contour import in both module
 (Region geometry) and expression (Region value) contexts, and the `FontProvider` abstraction
-(`font_provider.hpp`) + built-in `StbFontProvider` default + `text()`/`textmetrics()`/
+(`font_provider.hpp`) + built-in FreeType/HarfBuzz backend + `text()`/`textmetrics()`/
 `fontmetrics()`; and (Phase 8) `ManifoldCache` — an opt-in, thread-safe content-hash cache of
 already-generated CSGNode subtrees (`manifold_cache.hpp`/`.cpp`), plus `rands()`-taint tracking
 (`Evaluator::noteRandsCall()`/`CSGNode::uncacheable`) so a subtree whose resolved content isn't a
@@ -215,31 +227,45 @@ top-level 2D primitive/projection() script had been silently unexportable via th
 Fixed by porting `toRenderableBodies()` (`colored_body.hpp`/`.cpp`) and calling it from the CLI right
 before export, matching the reference's own call site exactly.
 
-**Font support, Phase 7**: mirrors the plan's §6 design exactly — a `FontProvider` abstract
-interface (`font_provider.hpp`: `resolveFont`/`metrics`/`glyphMetrics`/`glyphOutline`) rather than
-hard-depending on the Python reference's `fc-match` shell-out (Linux-only, unusable inside a
-cross-platform Qt host app). `Evaluator`'s constructor takes an optional
-`shared_ptr<FontProvider>`; if unset, `Evaluator::fontProvider()` lazily constructs the built-in
-`StbFontProvider` default on first use (not eagerly in the constructor, so a script that never
-calls `text()`/`textmetrics()`/`fontmetrics()` never pays for font-file parsing).
-`StbFontProvider::resolveFont()` always returns the one bundled font (`resources/fonts/
-LiberationSans-Regular.ttf`, the *exact same* font file as the Python reference's own bundled
-default, copied over so cross-checks are apples-to-apples) regardless of the requested spec — no
-system font matching, matching the plan's documented limitation for the built-in default; a real Qt
-host app supplies its own `FontProvider` (`QFontDatabase`/`QRawFont`-backed) instead of this class
-for actual system-font resolution. `text_metrics.hpp`/`.cpp` holds the shared, backend-agnostic
-layout math (`measureText`/`textAlignOffset`, mirroring `_measure_text`/`_text_align_offset`
-exactly) used by both `text()` (`builtins/text.cpp`) and `textmetrics()`/`fontmetrics()`
-(`function_builtins.cpp`) — cross-checked bit-for-bit against the Python reference's fonttools-based
-metrics on the bundled font (identical `advance`/`ascent`/`descent`/family name values) and against
-its glyph-outline mesh output (identical triangle count and bounding box for `text()`).
-
-**Known gap carried from Phase 7**: `StbFontProvider::resolveFont()` ignores its `spec` argument
-entirely (always the one bundled font) — this is the documented, intentional shape of the *built-in
-default* (see above), not a bug; a script that requests a specific system font (`font="Times New
-Roman:style=Bold"`) silently gets Liberation Sans instead under this default provider. No upgrade
-path needed in this repo: the fix is a Qt host application supplying its own `FontProvider`, which
-is exactly what the injection seam exists for.
+**Font support**: a `FontProvider` abstract interface (`font_provider.hpp`: `resolveFont`/
+`metrics`/`shapeText`/`glyphInkBounds`/`glyphOutline`) with `FreetypeFontProvider` as the built-in
+implementation everything here actually uses. `Evaluator`'s constructor takes an optional
+`shared_ptr<FontProvider>`; if unset, `Evaluator::fontProvider()` constructs the built-in one
+lazily on first use (not eagerly in the constructor, so a script that never calls `text()`/
+`textmetrics()`/`fontmetrics()` never pays for font parsing). Laziness runs one level deeper too:
+the system font directories are only scanned once a `font=` spec actually names a family, so the
+common case — the default font, or a family already resolved once — never walks the filesystem.
+
+The interface is shaped around shaping: `shapeText()` takes a whole string, because kerning,
+ligatures, mark positioning and bidi reordering are properties of the run and not of any character
+in it, and returns positioned *glyph indices* rather than codepoints (the mapping is neither 1:1
+nor stable across fonts). `direction`/`language`/`script` are honoured rather than merely accepted;
+whichever is left empty is filled in by `hb_buffer_guess_segment_properties`, the same job real
+OpenSCAD's `detect_properties()`/`detect_script()` does by hand.
+
+`resolveFont()` never fails. An unmatched family falls back to the bundled Liberation Sans
+(`resources/fonts/`, embedded into the binary by `cmake/embed_font.cmake`, byte-identical to the
+Python reference's own bundled font), which is both the default and the last-resort fallback — so
+`text()` draws something even on a machine with no fonts installed at all. That mirrors
+fontconfig's own never-fails matching, and so real OpenSCAD's: a missing font silently becomes the
+nearest available one rather than an error.
+
+`font_match.cpp` is the part of fontconfig that `font=` actually needs, reimplemented: comma-
+separated family lists, `:style=Bold Italic` (and bare `:Bold`), other properties ignored rather
+than rejected, generic `sans-serif`/`serif`/`monospace` aliases expanded to concrete families, and
+a recursive scan of the platform font directories plus `OPENSCAD_FONT_PATH` (the same environment
+variable real OpenSCAD reads). Family match is case-insensitive and required; style is a
+*preference* — exact, then substring, then Regular, then the family's first face — because
+dropping to Regular beats falling through to an unrelated family, which is what fontconfig does
+too.
+
+`text_metrics.hpp`/`.cpp` holds the shared layout math (`measureText`/`textAlignOffset`) used by
+both `text()` (`builtins/text.cpp`) and `textmetrics()`/`fontmetrics()` (`function_builtins.cpp`).
+Sharing it is the point: the numbers a script positions against cannot disagree with what it
+draws. The `size * (100/72) / unitsPerEm` scale factor reproduces real OpenSCAD's own long-standing
+`text()` size bug (its issue #4304 — `FT_Set_Char_Size` given 100 dpi where 72 is correct, making
+glyphs ~1.39x nominal) deliberately: a decade of models are drawn to it, and OpenSCAD itself chose
+to keep it and add an `em=` parameter rather than fix it.
 
 **Debugger/profiler, Phase 9 (the last phase)**: `checkDebug()` fires at **full parity with the
 reference's `_check_debug` call sites** — the statement checkpoint in `evalChildren`'s `runAll`,
@@ -633,30 +659,39 @@ grep for `ponytail:`.
   OpenSCAD up) at the point-transform step, `applyMat()` (named to avoid colliding with
   `std::apply` in an ADL lookup that broke the build once — see its own comment).
 - `include/openscad_cpp_evaluator/font_provider.hpp` — the `FontProvider` abstract interface
-  (`resolveFont`/`metrics`/`glyphMetrics`/`glyphOutline`), the injection seam that keeps
-  `text()`/`textmetrics()`/`fontmetrics()` decoupled from any specific font backend (the plan's §6
-  design — avoids hard-depending on the Python reference's Linux-only `fc-match` shell-out, since
-  this library is meant to be embedded in a cross-platform Qt GUI app). `Evaluator`'s constructor
-  takes an optional injected `shared_ptr<FontProvider>`; `Evaluator::fontProvider()` lazily
-  constructs the built-in default (below) on first use otherwise.
-- `include/openscad_cpp_evaluator/stb_font_provider.hpp`, `src/text/stb_font_provider.cpp` — the
-  built-in `FontProvider` default: `stb_truetype.h` over the one bundled font
-  (`resources/fonts/LiberationSans-Regular.ttf`, byte-identical to the Python reference's own
-  bundled font). `resolveFont()` ignores its `spec` argument entirely and always returns that one
-  font (see the "known gap" note above) — a real Qt host app supplies its own `QFontDatabase`/
-  `QRawFont`-backed `FontProvider` instead of this class for real system-font matching.
+  (`resolveFont`/`metrics`/`shapeText`/`glyphInkBounds`/`glyphOutline`), the seam that keeps
+  `text()`/`textmetrics()`/`fontmetrics()` decoupled from any specific font backend. `Evaluator`'s
+  constructor takes an optional injected `shared_ptr<FontProvider>`; `Evaluator::fontProvider()`
+  lazily constructs the built-in one (below) on first use otherwise. The seam stays because a host
+  that already owns a font stack (a Qt app with `QRawFont`) may prefer to answer these five
+  questions itself rather than run a second font engine in the same process.
+- `include/openscad_cpp_evaluator/freetype_font_provider.hpp`,
+  `src/text/freetype_font_provider.cpp` — the built-in implementation. HarfBuzz shapes
+  (`hb_blob_create_from_file_or_fail` → `hb_face_create` → `hb_font_create` +
+  `hb_ot_font_set_funcs`, scaled to unitsPerEm so positions come back in font units); FreeType
+  supplies outlines (`FT_LOAD_NO_SCALE` + `FT_Outline_Decompose`, curves flattened uniformly in
+  `t` — the same approximation real OpenSCAD's `DrawingCallback` makes) and face metrics
+  (`lineGap` derived as `height - (ascender - descender)`, since FreeType reports the summed line
+  height). Faces are cached per resolved spec; handle 0 is always the bundled font.
+- `include/openscad_cpp_evaluator/font_match.hpp`, `src/text/font_match.cpp` — the fontconfig
+  replacement: `parseFontSpec()` (family list + `:style=`), `expandGenericFamily()`
+  (sans-serif/serif/monospace → concrete families), `systemFontDirs()`/`findFontFiles()` (platform
+  font directories + `OPENSCAD_FONT_PATH`, `.ttf`/`.otf`/`.ttc`/`.otc`, permission errors skipped
+  rather than thrown — a font directory with odd permissions must not take down a render), and
+  `matchFace()` (case-insensitive family match required, style preferred). All pure functions over
+  plain data, so their tests need no system fonts.
 - `include/openscad_cpp_evaluator/text_metrics.hpp`, `src/text/text_metrics.cpp` — the
   backend-agnostic text-layout math shared by `text()` and `textmetrics()`/`fontmetrics()`:
-  `measureText()` (left-to-right glyph layout, ink-bbox/advance aggregation — mirrors
-  `_measure_text` exactly, including the "unmapped codepoint skipped entirely, mapped-but-inkless
-  codepoint still advances" distinction) and `textAlignOffset()` (halign/valign →
-  translation offset, mirrors `_text_align_offset`). `utf8DecodeAll()` here decodes a UTF-8 byte
-  string to full Unicode scalar values for per-codepoint `FontProvider` calls.
-- `src/builtins/text.cpp` — `text()` itself: resolves layout via `text_metrics.hpp` at resolve
-  time (so `resolveText`'s params carry only plain data — per-glyph codepoint+pen-x, scale, segment
-  count, alignment offset — no `FontProvider`/`EvalContext` reference crossing into generate),
-  then at generate time calls `FontProvider::glyphOutline()` per glyph, unions the resulting
-  `CrossSection`s, and applies the alignment offset.
+  `measureText()` (shapes the run, then aggregates ink-bbox/advance over the positioned glyphs —
+  an inkless glyph like a space still advances the pen while contributing nothing to the ink box)
+  and `textAlignOffset()` (halign/valign → translation offset).
+- `src/builtins/text.cpp` — `text()` itself: resolves the font and lays the run out via
+  `text_metrics.hpp` at resolve time (so `resolveText`'s params carry only plain data — per-glyph
+  index + pen x/y, scale, segment count, alignment offset — no `FontProvider`/`EvalContext`
+  reference crossing into generate), then at generate time calls `FontProvider::glyphOutline()`
+  per glyph, builds each `CrossSection` with the `NonZero` fill rule (what turns a counter wound
+  against its outer contour into a hole rather than a second filled blob), unions them, and
+  applies the alignment offset.
 - `include/openscad_cpp_evaluator/debug_hooks.hpp`, `include/openscad_cpp_evaluator/profile.hpp`,
   `src/debug_profile.cpp` — the debugging/profiling injection seam. `DebugHookFn`/`ErrorBreakFn`/
   `ReturnHookFn` (bundled into one `DebugHooks` constructor parameter) mirror the reference's

{openscad_cpp_evaluator-0.31.2 → openscad_cpp_evaluator-0.32.2}/CMakeLists.txt

@@ -129,13 +129,66 @@ FetchContent_Declare(boost_config GIT_REPOSITORY https://github.com/boostorg/con
 FetchContent_Declare(boost_polygon GIT_REPOSITORY https://github.com/boostorg/polygon.git GIT_TAG boost-1.86.0 GIT_SHALLOW TRUE)
 FetchContent_MakeAvailable(boost_config boost_polygon)
 
-# nothings/stb: single-header stb_image.h (surface()'s PNG loader) and
-# stb_truetype.h (the built-in FontProvider's TTF parser/rasterizer, Phase
-# 7) -- no build system of its own, just headers, so this only needs an
-# include path, not add_subdirectory/MakeAvailable's target machinery.
+# nothings/stb: single-header stb_image.h, surface()'s PNG loader -- no
+# build system of its own, just headers, so this only needs an include
+# path, not add_subdirectory/MakeAvailable's target machinery. (It used to
+# supply stb_truetype.h for the font backend too; FreeType/HarfBuzz below
+# replaced that.)
 FetchContent_Declare(stb GIT_REPOSITORY https://github.com/nothings/stb.git GIT_TAG master GIT_SHALLOW TRUE)
 FetchContent_MakeAvailable(stb)
 
+# FreeType (glyph outlines + face metrics) and HarfBuzz (shaping), the two
+# halves of the font backend. Both build with plain CMake, which is why
+# they can be FetchContent deps like everything else here -- fontconfig,
+# the third leg of real OpenSCAD's font stack, is meson-only and is
+# deliberately NOT used; font_match.cpp implements its spec syntax and
+# directory scanning directly so that name matching behaves identically on
+# all six wheel targets rather than only where a fontconfig build exists.
+#
+# The two are kept independent of each other on purpose: HB_HAVE_FREETYPE
+# is OFF, so HarfBuzz reads the font through its own hb-ot tables reader
+# rather than through FreeType, and no find_package(Freetype) has to
+# resolve against a FetchContent target that isn't installed anywhere.
+# Both sides address glyphs by the same font-internal glyph index, so the
+# split costs nothing: HarfBuzz shapes text into positioned glyph indices,
+# FreeType turns each index into an outline. Everything crosses that
+# boundary in font units (hb_font_set_scale to unitsPerEm on one side,
+# FT_LOAD_NO_SCALE on the other), so there is no scale mismatch to
+# reconcile either.
+#
+# FreeType's optional dependencies are all disabled: zlib/bzip2/brotli
+# decompress rare embedded-table formats, PNG is for colour bitmap emoji
+# strikes, and HarfBuzz there is only for autohinting quality -- none of
+# which matter when the only thing being asked for is a scalable outline.
+# Leaving them on would make the wheel build depend on whatever those
+# libraries happen to be on six different build images.
+set(FT_DISABLE_ZLIB ON CACHE BOOL "" FORCE)
+set(FT_DISABLE_BZIP2 ON CACHE BOOL "" FORCE)
+set(FT_DISABLE_PNG ON CACHE BOOL "" FORCE)
+set(FT_DISABLE_HARFBUZZ ON CACHE BOOL "" FORCE)
+set(FT_DISABLE_BROTLI ON CACHE BOOL "" FORCE)
+FetchContent_Declare(
+  freetype
+  GIT_REPOSITORY https://github.com/freetype/freetype.git
+  GIT_TAG VER-2-14-3
+  GIT_SHALLOW TRUE
+)
+FetchContent_MakeAvailable(freetype)
+
+set(HB_HAVE_FREETYPE OFF CACHE BOOL "" FORCE)
+set(HB_HAVE_GLIB OFF CACHE BOOL "" FORCE)
+set(HB_HAVE_ICU OFF CACHE BOOL "" FORCE)
+set(HB_BUILD_SUBSET OFF CACHE BOOL "" FORCE)
+set(HB_BUILD_UTILS OFF CACHE BOOL "" FORCE)
+set(HB_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+FetchContent_Declare(
+  harfbuzz
+  GIT_REPOSITORY https://github.com/harfbuzz/harfbuzz.git
+  GIT_TAG 14.3.1
+  GIT_SHALLOW TRUE
+)
+FetchContent_MakeAvailable(harfbuzz)
+
 # yhirose/cpp-linenoise: header-only, BSD-2-Clause C++ port of antirez/
 # linenoise with native Windows console support (no ANSI emulation layer,
 # unlike GNU readline's Windows story) -- gives the --debug REPL's real
@@ -149,7 +202,7 @@ FetchContent_MakeAvailable(cpp_linenoise)
 
 # Embeds the bundled default font's (resources/fonts/) raw bytes into a
 # generated header (kBundledFontData/kBundledFontDataSize), so
-# StbFontProvider's default constructor needs no runtime file path at all --
+# FreetypeFontProvider needs no runtime file path for its default font --
 # a real installed/packaged build (e.g. the PyPI wheel) has no guarantee the
 # source tree's resources/fonts/ is present or at any predictable path
 # alongside the installed shared library.

{openscad_cpp_evaluator-0.31.2 → openscad_cpp_evaluator-0.32.2}/PKG-INFO

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

{openscad_cpp_evaluator-0.31.2 → openscad_cpp_evaluator-0.32.2}/include/openscad_cpp_evaluator/evaluator.hpp

@@ -63,7 +63,7 @@ public:
     // `fontProvider`: injection seam for text()/textmetrics()/fontmetrics()
     // (see font_provider.hpp). Left null (the common case for this repo's
     // own tests/CLI, and for any host that hasn't wired in its own) lazily
-    // constructs the built-in StbFontProvider default on first use, not in
+    // constructs the built-in FreetypeFontProvider on first use, not in
     // the constructor -- avoids paying for font-file parsing on every
     // Evaluator even when a script never calls text()/textmetrics().
     // `manifoldCache`: opt-in content-hash cache (see manifold_cache.hpp)

openscad_cpp_evaluator-0.32.2/include/openscad_cpp_evaluator/font_match.hpp

@@ -0,0 +1,62 @@
+#pragma once
+
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace oscadeval {
+
+// A parsed fontconfig-style font spec, which is what OpenSCAD's `font=`
+// takes: a comma-separated family list, then colon-separated properties.
+//
+//   "Liberation Sans"
+//   "Liberation Sans:style=Bold Italic"
+//   "Helvetica,Arial,sans-serif:style=Bold"
+//
+// Only `style=` is meaningful here; fontconfig accepts a long tail of
+// other properties (:size=, :weight=, :lang=) that OpenSCAD models never
+// use, and quietly ignoring them beats rejecting a spec that fontconfig
+// itself would have accepted. A bare `:Bold` (no `=`) is read as a style
+// too, since fontconfig's own parser allows it.
+struct FontSpec {
+    std::vector<std::string> families;
+    std::string style;
+};
+
+FontSpec parseFontSpec(const std::string& spec);
+
+// Generic family names, expanded to the concrete families likely to be
+// installed. fontconfig resolves these through its own alias config
+// (OpenSCAD ships 10-liberation.conf pointing them at the Liberation
+// faces); with no fontconfig, the alias list lives here instead.
+// Returns an empty vector for a family that isn't generic.
+std::vector<std::string> expandGenericFamily(const std::string& family);
+
+// Every directory the platform keeps fonts in, plus anything on
+// OPENSCAD_FONT_PATH (same environment variable real OpenSCAD reads, same
+// platform path separator). Directories that don't exist are dropped, so
+// the result is safe to walk blindly.
+std::vector<std::string> systemFontDirs();
+
+// Every font file under those directories: .ttf/.otf/.ttc/.otc, recursive.
+// A directory that can't be read is skipped rather than throwing -- a font
+// directory with odd permissions must not take down a render.
+std::vector<std::string> findFontFiles();
+
+// One face inside one font file. A .ttc collection holds several, hence
+// the index; a plain .ttf is always index 0.
+struct FontFace {
+    std::string path;
+    int faceIndex = 0;
+    std::string family;
+    std::string style;
+};
+
+// Best match for `spec` among `faces`, or nullopt if no requested family
+// (after generic expansion) is present at all. Family match is
+// case-insensitive and required; style is a preference, not a filter,
+// resolved in the order: exact style, then substring, then "Regular",
+// then the first face of that family.
+std::optional<FontFace> matchFace(const FontSpec& spec, const std::vector<FontFace>& faces);
+
+} // namespace oscadeval

openscad_cpp_evaluator-0.32.2/include/openscad_cpp_evaluator/font_provider.hpp

@@ -0,0 +1,98 @@
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace oscadeval {
+
+using FontHandle = std::uint64_t;
+
+// A font-internal glyph index, NOT a Unicode codepoint. Shaping is what
+// turns one into the other, and the mapping is neither 1:1 nor stable
+// across fonts: one codepoint can shape to several glyphs, several
+// codepoints can shape to one ligature glyph, and the same character has a
+// different index in every font.
+using GlyphId = std::uint32_t;
+
+// Global (whole-font) metrics, all in font units (not yet scaled for a
+// particular `size=`) -- mirrors fontmetrics()'s "nominal"/"max" split:
+// ascent/descent/lineGap come from the font's hhea table (or equivalent),
+// yMax/yMin from its head table (or equivalent) -- these commonly differ
+// (yMax/yMin bound the tallest/deepest glyph actually in the font; ascent/
+// descent are the font designer's nominal line-layout values).
+struct FontMetrics {
+    double unitsPerEm = 1000.0;
+    double ascent = 0, descent = 0, lineGap = 0;
+    double yMax = 0, yMin = 0;
+    std::string family, style;
+};
+
+// One glyph as placed by the shaper, in font units. `xOffset`/`yOffset`
+// adjust this glyph's own position without moving the pen (mark
+// attachment, cursive joins); `xAdvance`/`yAdvance` move the pen. Both are
+// shaping output, not raw hmtx values -- kerning and ligature
+// substitutions are already applied by the time this exists.
+struct ShapedGlyph {
+    GlyphId glyph = 0;
+    double xOffset = 0, yOffset = 0;
+    double xAdvance = 0, yAdvance = 0;
+};
+
+// What OpenSCAD's text()/textmetrics() call direction/language/script.
+// Any field left empty is guessed from the text itself by the shaper,
+// which is what real OpenSCAD's detect_properties() does by hand.
+struct ShapeOptions {
+    std::string direction; // "ltr", "rtl", "ttb", "btt"
+    std::string language;  // BCP 47, e.g. "en"
+    std::string script;    // ISO 15924, e.g. "Latn", "Arab"
+};
+
+// Flattened polyline contours (curves already split into straight
+// segments), in font units.
+using GlyphContours = std::vector<std::vector<std::array<double, 2>>>;
+
+// Abstraction over font resolution/shaping/outline extraction, so
+// text()/textmetrics()/fontmetrics() don't hard-depend on a specific font
+// backend. The library ships FreetypeFontProvider (HarfBuzz for shaping,
+// FreeType for outlines and face metrics, and its own fontconfig-syntax
+// matcher for system fonts) as the built-in default, which is what every
+// build here actually uses; the interface stays because a host that
+// already owns a font stack (a Qt app with QRawFont, say) may prefer to
+// answer these five questions itself rather than have a second font
+// engine resolving names in the same process.
+class FontProvider {
+public:
+    virtual ~FontProvider() = default;
+
+    // Resolves an OpenSCAD/fontconfig-style spec (e.g. "Times New
+    // Roman:style=Bold", or "" for the default) to an opaque handle.
+    // Never fails: an unmatched spec falls back to the default font,
+    // matching fontconfig's own never-fails matching (and so real
+    // OpenSCAD's), where a missing font silently becomes the nearest
+    // available one rather than an error.
+    virtual FontHandle resolveFont(const std::string& spec) = 0;
+
+    virtual FontMetrics metrics(FontHandle handle) = 0;
+
+    // Lays out a whole string at once -- not per codepoint, because
+    // kerning, ligatures, mark positioning and bidi reordering are all
+    // properties of the run rather than of any character in it.
+    virtual std::vector<ShapedGlyph> shapeText(FontHandle handle, const std::string& utf8,
+                                               const ShapeOptions& opts) = 0;
+
+    // The glyph's ink bounding box (xMin, yMin, xMax, yMax) in font units,
+    // or nullopt for a glyph that draws nothing (a space, or a .notdef
+    // with an empty outline) -- such a glyph still advances the pen, so it
+    // affects `advance` while contributing nothing to the ink box that
+    // textmetrics() reports as position/size.
+    virtual std::optional<std::array<double, 4>> glyphInkBounds(FontHandle handle, GlyphId glyph) = 0;
+
+    // Only called by text() itself (rendering) -- textmetrics()/
+    // fontmetrics() need only the two calls above.
+    virtual GlyphContours glyphOutline(FontHandle handle, GlyphId glyph, int segsPerCurve) = 0;
+};
+
+} // namespace oscadeval

openscad_cpp_evaluator-0.32.2/include/openscad_cpp_evaluator/freetype_font_provider.hpp

@@ -0,0 +1,38 @@
+#pragma once
+
+#include "openscad_cpp_evaluator/font_provider.hpp"
+
+#include <memory>
+
+namespace oscadeval {
+
+// The built-in FontProvider: HarfBuzz shapes, FreeType supplies outlines
+// and face metrics, and font_match.cpp resolves `font=` specs against the
+// platform's font directories. No fontconfig -- see the CMakeLists note on
+// why, and font_match.hpp for what of its behaviour is reimplemented.
+//
+// The bundled Liberation Sans (resources/fonts/, embedded into the binary
+// by cmake/embed_font.cmake) is the default font and the last-resort
+// fallback, so `text()` always draws something even on a machine with no
+// fonts installed at all -- the same font real OpenSCAD falls back to.
+//
+// Font files are opened lazily and cached per resolved spec: a script that
+// never calls text()/textmetrics()/fontmetrics() opens nothing, and one
+// that only uses the default font never scans a system directory.
+class FreetypeFontProvider : public FontProvider {
+public:
+    FreetypeFontProvider();
+    ~FreetypeFontProvider() override;
+
+    FontHandle resolveFont(const std::string& spec) override;
+    FontMetrics metrics(FontHandle handle) override;
+    std::vector<ShapedGlyph> shapeText(FontHandle handle, const std::string& utf8, const ShapeOptions& opts) override;
+    std::optional<std::array<double, 4>> glyphInkBounds(FontHandle handle, GlyphId glyph) override;
+    GlyphContours glyphOutline(FontHandle handle, GlyphId glyph, int segsPerCurve) override;
+
+private:
+    struct Impl;
+    std::unique_ptr<Impl> impl_;
+};
+
+} // namespace oscadeval

openscad_cpp_evaluator-0.32.2/include/openscad_cpp_evaluator/text_metrics.hpp

@@ -0,0 +1,40 @@
+#pragma once
+
+#include "openscad_cpp_evaluator/font_provider.hpp"
+
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace oscadeval {
+
+// Layout of `text`'s ink-bbox/advance metrics, in OpenSCAD units scaled
+// for `size`. `glyphs` is what text() places: each shaped glyph with its
+// pen position, already scaled. An inkless glyph (a space) still advances
+// the pen and still gets a glyphs entry -- it just contributes nothing to
+// ascent/descent/inkMinX/inkMaxX.
+//
+// The run comes from the shaper, so kerning and ligatures are already
+// applied and `spacing` scales the shaped advances rather than raw
+// per-character widths.
+struct TextMeasurement {
+    struct Placed {
+        GlyphId glyph = 0;
+        double x = 0, y = 0;
+    };
+
+    double ascent = 0, descent = 0, inkMinX = 0, inkMaxX = 0;
+    double advanceX = 0, advanceY = 0;
+    std::vector<Placed> glyphs;
+};
+
+TextMeasurement measureText(FontProvider& fp, FontHandle handle, const std::string& text, double size,
+                            double spacing, const ShapeOptions& opts = {});
+
+// (offsetX, offsetY) translation for halign/valign, given a
+// TextMeasurement. Shared by textmetrics() (reports it) and text()
+// (applies it).
+std::pair<double, double> textAlignOffset(const std::string& halign, const std::string& valign,
+                                          const TextMeasurement& m);
+
+} // namespace oscadeval

{openscad_cpp_evaluator-0.31.2 → openscad_cpp_evaluator-0.32.2}/pyproject.toml

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

{openscad_cpp_evaluator-0.31.2 → openscad_cpp_evaluator-0.32.2}/src/CMakeLists.txt

@@ -21,7 +21,8 @@ add_library(openscad_cpp_evaluator STATIC
   import/surface_load.cpp
   import/dxf_import.cpp
   import/svg_import.cpp
-  text/stb_font_provider.cpp
+  text/freetype_font_provider.cpp
+  text/font_match.cpp
   text/text_metrics.cpp
   debug/debug_repl.cpp
   builtins/text.cpp
@@ -51,7 +52,7 @@ target_include_directories(openscad_cpp_evaluator PRIVATE ${stb_SOURCE_DIR} ${CM
 add_dependencies(openscad_cpp_evaluator generate_bundled_font)
 
 target_link_libraries(openscad_cpp_evaluator PUBLIC openscad_cpp_parser manifold Boost::polygon)
-target_link_libraries(openscad_cpp_evaluator PRIVATE linenoise)
+target_link_libraries(openscad_cpp_evaluator PRIVATE linenoise freetype harfbuzz)
 target_compile_options(openscad_cpp_evaluator PRIVATE
   $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall;-Wextra>
 )

{openscad_cpp_evaluator-0.31.2 → openscad_cpp_evaluator-0.32.2}/src/builtins/function_builtins.cpp

@@ -320,10 +320,13 @@ Value objectOf(std::vector<std::pair<std::string, Value>> items) {
     return Value{std::make_shared<const ValueObject>(ValueObject{std::move(items)})};
 }
 
-// textmetrics(text=, size=10, halign=, valign=, spacing=, font=) -- measures
-// `text` against the FontProvider-resolved font (same resolution text()
-// uses) and returns an OscObject with position/size/ascent/descent/offset/
-// advance, matching real OpenSCAD's key order. Mirrors _builtin_textmetrics.
+// textmetrics(text=, size=10, font=, direction=, language=, script=,
+// halign=, valign=, spacing=) -- measures `text` against the
+// FontProvider-resolved font, laid out by exactly the same shaping call
+// text() makes, and returns an OscObject with position/size/ascent/
+// descent/offset/advance in real OpenSCAD's key order. Going through the
+// same measureText() the geometry goes through is the point: the numbers
+// a script positions against cannot disagree with what it draws.
 Value builtinTextmetrics(Evaluator& ev, const CallArgs& args) {
     const std::string text = asStringOr(getArg(args, 0, "text", Value{std::string("")}), "");
     const double size = toDoubleLenient(getArg(args, 1, "size", Value{10.0}));
@@ -331,10 +334,14 @@ Value builtinTextmetrics(Evaluator& ev, const CallArgs& args) {
     const std::string valign = asStringOr(getArg(args, std::nullopt, "valign", Value{std::string("baseline")}), "baseline");
     const double spacing = toDoubleLenient(getArg(args, std::nullopt, "spacing", Value{1.0}));
     const std::string fontSpec = asStringOr(getArg(args, std::nullopt, "font", Value{std::string("")}), "");
+    ShapeOptions shape;
+    shape.direction = asStringOr(getArg(args, std::nullopt, "direction", Value{std::string("")}), "");
+    shape.language = asStringOr(getArg(args, std::nullopt, "language", Value{std::string("")}), "");
+    shape.script = asStringOr(getArg(args, std::nullopt, "script", Value{std::string("")}), "");
 
     FontProvider& fp = ev.fontProvider();
     const FontHandle handle = fp.resolveFont(fontSpec);
-    const TextMeasurement m = measureText(fp, handle, text, size, spacing);
+    const TextMeasurement m = measureText(fp, handle, text, size, spacing, shape);
     const auto [offsetX, offsetY] = textAlignOffset(halign, valign, m);
 
     return objectOf({
@@ -343,7 +350,7 @@ Value builtinTextmetrics(Evaluator& ev, const CallArgs& args) {
         {"ascent", Value{m.ascent}},
         {"descent", Value{m.descent}},
         {"offset", numList({offsetX, offsetY})},
-        {"advance", numList({m.advanceX, 0.0})},
+        {"advance", numList({m.advanceX, m.advanceY})},
     });
 }
 
@@ -684,8 +691,29 @@ Value evalBuiltinFunction(Evaluator& ev, const std::string& name, const CallArgs
             }
             return Value{false};
         }
-        case BuiltinFnId::Version: return numList({2025.0, 1.0, 1.0});
-        case BuiltinFnId::VersionNum: return Value{20250101.0};
+        // The OpenSCAD release we track. version_num() is that same
+        // year/month/day folded as y * 10000 + m * 100 + d, exactly like the
+        // reference's own builtin_version_num (builtin_functions.cc).
+        case BuiltinFnId::Version: return numList({2026.0, 1.0, 1.0});
+        case BuiltinFnId::VersionNum: {
+            // The optional vector argument the reference also accepts: with
+            // no argument this is our own version() folded; with one, it is
+            // whatever [y, m] / [y, m, d] the caller passed, so
+            // version_num([2019, 5, 0]) == 20190500 regardless of what
+            // release we report. A 2-element vector defaults the day to 0
+            // (getVec3's own defaultval), and anything else -- a non-list, a
+            // wrong length, a non-numeric element -- is undef.
+            //
+            // One deliberate divergence: the reference's size-2 path ignores
+            // getVec2's own failure and folds uninitialized doubles for e.g.
+            // version_num(["a", "b"]). That is undef here rather than
+            // whatever happened to be on the stack.
+            const Value* arg = args.findPositional(0);
+            if (!arg) return Value{20260101.0};
+            const auto v = allNumericList(*arg);
+            if (!v || (v->size() != 2 && v->size() != 3)) return Value{};
+            return Value{(*v)[0] * 10000.0 + (*v)[1] * 100.0 + (v->size() == 3 ? (*v)[2] : 0.0)};
+        }
         case BuiltinFnId::ParentModule:
             return ev.parentModuleName(static_cast<int>(toDoubleLenient(getArg(args, 0, "index", Value{0.0}))));
     }