Sketch nodes refactor, global dimension settings, OCCT 8 wasm build docs

README.md

@@ -38,7 +38,9 @@ Ensure the following dependencies are installed:
 
 ### OCCT Build
 
-#### For VS2022
+Full guide: **[docs/building-occt.md](docs/building-occt.md)** (Windows prebuilts, wasm/Emscripten, troubleshooting).
+
+#### For VS2022 (summary)
 - See: https://dev.opencascade.org/doc/overview/html/build_upgrade__building_occt.html
 - OCCT 3rd-party binaries: https://github.com/Open-Cascade-SAS/OCCT/releases/download/V7_9_1/3rdparty-vc14-64.zip
 - Currently building EzyCad has only been tested with the Release build of OCCT.
@@ -60,6 +62,7 @@ Ensure the following dependencies are installed:
 ### Notes for Emscripten Builds
 - **Known issue:** The Emscripten build with the Ninja generator (`-G Ninja`) is currently not working. Use the default generator (e.g. `emcmake cmake ..` without `-G Ninja`, then `emmake make`) or another generator that works with your Emscripten setup.
 - Install Emscripten and activate its environment.
+- **OCCT 8.0.0 for wasm:** `scripts\build-occt-v8-wasm.cmd` or `.\scripts\build-occt-v8-wasm.ps1` after `emsdk_env` — see [docs/building-occt.md](docs/building-occt.md#webassembly-emscripten). Experimental; manual 7.9.x steps below remain for reference.
 - Build FreeType (2.10.1) for Emscripten using the instructions: https://stackoverflow.com/questions/61049517/build-latest-freetype-with-emscripten
   - Add exception support:
     - `emcmake cmake .. -DCMAKE_CXX_FLAGS="-fexceptions" -DCMAKE_EXE_LINKER_FLAGS="-fexceptions" -DCMAKE_INSTALL_PREFIX=c:/src/freetype-2.10.1_em_install -DCMAKE_POLICY_VERSION_MINIMUM=3.5`

agents/README.md

@@ -8,4 +8,5 @@ To use a note in **Cursor**, copy or symlink the relevant file into your user or
 | --- | --- |
 | [ezycad-ascii-source.md](ezycad-ascii-source.md) | ASCII-only comments and strings in `src/`; points at `ezycad_code_style.md` and `scripts/check-nonascii-src.ps1`. |
 | [discoverability-outreach.md](discoverability-outreach.md) | Draft posts for forums, Reddit, awesome lists (SEO / backlinks). |
+| *(repo root)* [docs/building-occt.md](../docs/building-occt.md) | Download/build OCCT for Windows desktop and wasm. |
 | *(repo root)* [ezycad_doc_style.md](../ezycad_doc_style.md) | User guides, Read the Docs, images, in-app doc URLs. |

agents/issues/008-refactor1-dimensions-sketch-nodes-occt-wasm.md

@@ -0,0 +1,63 @@
+# Branch `Trailcode/refactor1`: sketch nodes refactor, dimension settings, OCCT wasm build
+
+**Opened on GitHub:** https://github.com/trailcode/EzyCad/issues/113
+
+**Branch:** `Trailcode/refactor1` (7 commits ahead of `main` at open time)
+
+**Labels:** `enhancement`, `documentation`
+
+---
+
+## Title (GitHub)
+
+Sketch nodes PIMPL refactor, global dimension settings, OCCT 8 wasm build tooling
+
+## Body (GitHub)
+
+### Summary
+
+Tracking branch **`Trailcode/refactor1`**: refactor sketch-node internals, add persisted **Settings → Sketch → Dimensions** controls (line width, arrows, label rendering, visibility), fix permanent node annotation scale, and add **OCCT V8.0.0 WebAssembly** build scripts plus **`docs/building-occt.md`**.
+
+### Scope (implemented on branch)
+
+**Sketch nodes (`src/sketch_nodes.cpp`, `src/sketch_nodes.h`):**
+
+- PIMPL-style refactor (`Sketch_nodes` implementation detail moved behind `m_impl`).
+- Snap / axis-guide behavior preserved; cleaner separation from `Sketch`.
+
+**Dimension style (`src/geom.h`, `src/geom.cpp`, `src/gui.*`, `src/sketch.cpp`, `src/occt_view.*`, `src/shp_extrude.*`):**
+
+- `Length_dimension_style` bundles global dimension display settings.
+- `apply_length_dimension_style()` applies `Prs3d_DimensionAspect` + AIS Z-layer for labels.
+- **Settings → Sketch → Dimensions** (nested): line width, arrow size/color, text scale, **label rendering** (0–5; default **Z-layer Topmost** to avoid grid ghosting), placement, arrow style/orientation, **show sketch dimensions**.
+- `Occt_view::refresh_all_length_dimensions()` rebuilds dims when settings change.
+- Removed non-functional flyout / extension-line settings after OCCT limitations.
+
+**Other:**
+
+- Permanent node annotation scale fix (`gui.permanent_node_anno_scale`).
+- **`scripts/build-occt-v8-wasm.ps1`** + **`scripts/build-occt-v8-wasm.cmd`** — download FreeType, build OCCT `V8_0_0` static + GLES2 for Emscripten.
+- **`docs/building-occt.md`** — Windows prebuilts, wasm build, troubleshooting, wrapper-script patterns.
+- **`usage-settings.md`** updated for new dimension controls.
+
+### Out of scope / follow-ups
+
+- [ ] Verify **EzyCad wasm** links against OCCT 8 install produced by the new script (experimental; README still references 7.9.x manual path).
+- [ ] Review commits **`Debug code`** / **`WIP`** — drop or gate debug-only changes before merge.
+- [ ] Desktop upgrade to **OCCT 8.0.0** prebuilts (separate from wasm); retest grid + dimension labels after OCCT 8 grid shader changes.
+- [ ] Consider typed enum for `edge_dim_text_render_mode` instead of magic `int` 0–5.
+
+### Test plan
+
+- [ ] **Settings → Sketch → Dimensions:** change each control; confirm live refresh on sketch length dimensions and extrude preview dims.
+- [ ] **Label rendering:** try **Z-layer Top** / **Topmost** (defaults); confirm no grid bleed-through on labels.
+- [ ] **Show sketch dimensions** global toggle; per-sketch list overrides still work.
+- [ ] Sketch snap: dimension-tool hover, cross-sketch snap, add-node on edge interior (`Sketch_test` if available).
+- [ ] **Permanent node annotation size** slider visible effect on sketch nodes.
+- [ ] Desktop Release build; open/save settings JSON (`edge_dim_*` keys).
+- [ ] (Optional) `.\scripts\build-occt-v8-wasm.ps1` completes; `emcmake` EzyCad with printed `OpenCASCADE_DIR`.
+
+### Links
+
+- Branch: `Trailcode/refactor1`
+- Doc: `docs/building-occt.md`

docs/building-occt.md

@@ -0,0 +1,236 @@
+# Building Open CASCADE (OCCT) for EzyCad
+
+EzyCad does **not** vendor OCCT; builds live **outside** the tree. Point CMake at an install via `OpenCASCADE_DIR` (and on Windows desktop, `OCCT_3RD_PARTY_DIR`).
+
+**Official references**
+
+- [OCCT releases](https://github.com/Open-Cascade-SAS/OCCT/releases)
+- [Build OCCT (overview)](https://dev.opencascade.org/doc/overview/html/build_upgrade__building_occt.html)
+- [WebGL / wasm sample (upstream)](https://dev.opencascade.org/doc/occt-7.9.0/overview/html/occt_samples_webgl.html)
+
+---
+
+## Version matrix (EzyCad)
+
+| Target | Documented / tested | Experimental | CMake variables |
+| --- | --- | --- | --- |
+| **Windows desktop** | OCCT **7.9.1** prebuilt | OCCT **8.0.0** prebuilt | `OpenCASCADE_DIR`, `OCCT_3RD_PARTY_DIR` |
+| **WebAssembly** | OCCT **7.9.x** manual / [wasm-occ-demo](https://github.com/mathysyon/wasm-occ-demo) | OCCT **8.0.0** via `scripts/build-occt-v8-wasm.ps1` | `OpenCASCADE_DIR` only (static install) |
+
+After upgrading OCCT, retest **sketch dimensions**, **grid**, **fillet/chamfer/boolean**, and **STEP/STL** export. OCCT 8.0 changes grid rendering and many modeling paths.
+
+---
+
+## Windows desktop (easiest): prebuilt binaries
+
+No OCCT compile. Use **Release** builds (EzyCad is tested with Release OCCT).
+
+### Download (7.9.1 — current README default)
+
+```text
+# Combined (OCCT + 3rd-party, simplest layout):
+https://github.com/Open-Cascade-SAS/OCCT/releases/download/V7_9_1/opencascade-7.9.1-vc14-64-combined.zip
+
+# Or separate:
+https://github.com/Open-Cascade-SAS/OCCT/releases/download/V7_9_1/3rdparty-vc14-64.zip
+# + a 7.9.1 opencascade-*-vc14-64 package from the V7_9_1 release page
+```
+
+### Download (8.0.0 — upgrade path)
+
+```text
+https://github.com/Open-Cascade-SAS/OCCT/releases/download/V8_0_0/occt-combined-release-no-pch.zip
+https://github.com/Open-Cascade-SAS/OCCT/releases/download/V8_0_0/3rdparty-vc14-64.zip
+```
+
+Unpack so `3rdparty-vc14-64` and the OCCT folder share a **parent directory** (required for DRAW; EzyCad only needs CMake paths).
+
+### Configure EzyCad
+
+```text
+cmake C:\src\EzyCad -DOpenCASCADE_DIR=C:\bin\OCCT-install\cmake -DOCCT_3RD_PARTY_DIR=C:\bin\3rdparty-vc14-64
+```
+
+- `OpenCASCADE_DIR` — directory containing `OpenCASCADEConfig.cmake` (often `...\cmake` or `...\lib\cmake\opencascade` depending on package layout; **verify on disk**).
+- `OCCT_3RD_PARTY_DIR` — root of `3rdparty-vc14-64` (FreeType, TBB, FFmpeg DLLs copied next to `EzyCad.exe` per `CMakeLists.txt`).
+
+Use **Visual Studio** generator, **x64**, **Release** for the app.
+
+---
+
+## Windows desktop: build from source
+
+Only when prebuilts are insufficient (custom flags, Debug OCCT, patches).
+
+1. Install **VS 2022** (C++), **CMake 3.16+**, **Git**.
+2. Download [3rdparty-vc14-64.zip](https://github.com/Open-Cascade-SAS/OCCT/releases) matching the OCCT tag.
+3. Clone OCCT, configure with CMake GUI or CLI, `BUILD_LIBRARY_TYPE=Shared` or `Static` as needed, enable `USE_OPENGL`, `USE_FREETYPE`, etc. per [build guide](https://dev.opencascade.org/doc/overview/html/build_upgrade__building_occt.html).
+4. Build **INSTALL** target; set `OpenCASCADE_DIR` to the install prefix’s cmake package path.
+
+Prefer **prebuilt** packages unless you need a custom source build.
+
+---
+
+## WebAssembly (Emscripten)
+
+EzyCad’s wasm target links **`TKOpenGles`** (not `TKOpenGl`), static OCCT, and **`-fexceptions`** (see `CMakeLists.txt` Emscripten block).
+
+### Automated: `scripts/build-occt-v8-wasm.ps1`
+
+Builds **FreeType 2.13.3** + **OCCT `V8_0_0`** static with GLES2 into a single install prefix.
+
+**Prerequisites:** Git, CMake 3.16+, [Emscripten emsdk](https://emscripten.org/docs/getting_started/downloads.html) 3.0+ with `emsdk_env` active (`emcc`, `emcmake`, `emmake` on `PATH`).
+
+**Layout created** (default `RootDir` = `%USERPROFILE%\occt-wasm-build`):
+
+```text
+occt-wasm-build/
+  src/OCCT/                    git clone V8_0_0
+  src/freetype-2.13.3/         from .tar.gz (not .tar.xz on Windows)
+  build/freetype/
+  build/occt/
+  install/                     CMAKE_INSTALL_PREFIX
+    lib/cmake/opencascade/     → OpenCASCADE_DIR
+    freetype/                  FreeType install (used at OCCT configure time)
+```
+
+**PowerShell (repo root, after `emsdk_env`):**
+
+```powershell
+.\scripts\build-occt-v8-wasm.ps1 -RootDir C:\src\occt-wasm-build
+```
+
+Or use `scripts\build-occt-v8-wasm.cmd` if PowerShell script execution is restricted.
+
+**Script flags:** `-SkipDownload`, `-SkipFreeType`, `-SkipOcct`, `-ReconfigureOnly`, `-Jobs 8`, `-OcctTag V8_0_0`, `-BuildType Release`.
+
+**Expect:** 1–3+ hours compile, large disk use. Success prints `OpenCASCADE_DIR=...`.
+
+**Configure EzyCad wasm** (do **not** use `-G Ninja` for EzyCad — known issue in README):
+
+```text
+mkdir build_em
+cd build_em
+emcmake cmake C:\src\EzyCad -Wno-dev -DOpenCASCADE_DIR=C:\src\occt-wasm-build\install\lib\cmake\opencascade
+emmake cmake --build . --config Release
+```
+
+Serve: `python -m http.server 8000` from the build output directory.
+
+### OCCT wasm CMake flags (reference)
+
+Used by `build-occt-v8-wasm.ps1` — keep in sync if editing the script:
+
+| Variable | Value | Why |
+| --- | --- | --- |
+| `BUILD_LIBRARY_TYPE` | `Static` | `.a` archives linked into EzyCad.wasm |
+| `BUILD_MODULE_Draw` | `OFF` | No Tcl/Tk harness |
+| `USE_OPENGL` | `OFF` | Desktop GL driver |
+| `USE_GLES2` | `ON` | `TKOpenGles` for WebGL2 |
+| `USE_VTK` | `OFF` | Default in 8.0; avoids GLES VTK issues |
+| `USE_FREETYPE` | `ON` | Dimension / text rendering |
+| `USE_TBB`, `USE_FFMPEG`, `USE_FREEIMAGE`, `USE_OPENVR`, `USE_TK` | `OFF` | Reduce deps and build time |
+| `CMAKE_*_FLAGS` | `-fexceptions` | Match EzyCad emscripten link flags |
+
+FreeType wasm configure also disables optional zlib/png/harfbuzz finds to simplify the emscripten build.
+
+### Wasm troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `running scripts is disabled` | `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` **or** use `build-occt-v8-wasm.cmd` **or** `powershell -ExecutionPolicy Bypass -File ...` |
+| `Can't initialize filter; xz` | Script uses `.tar.gz` for FreeType; delete stale `*.tar.xz` under `src/` and re-run |
+| `source directory .../build/freetype does not contain CMakeLists.txt` | Fixed: do not name a PowerShell function parameter `$Args` (shadows automatic `$Args`) |
+| `emcc` not found | Run `emsdk_env.bat` / `emsdk_env.ps1` in the same shell |
+| EzyCad configure hangs on `find_package(OpenCASCADE)` | `emcmake cmake ... --debug-output`; verify `OpenCASCADE_DIR` path |
+| OCCT 8 + ghosted dimension labels | Retest `gui.edge_dim_text_render_mode` (Z-layer Topmost); grid compositing changed in 8.0 |
+
+### Legacy wasm path (7.9.x)
+
+Manual FreeType 2.10.1 + OCCT 7.9.0 per [wasm-occ-demo](https://github.com/mathysyon/wasm-occ-demo). Prefer the V8 script for new wasm OCCT work; keep 7.9.x until EzyCad wasm is verified on 8.0.
+
+---
+
+## Wrapper scripts and automation
+
+When adding helper scripts under `scripts/`, follow existing repo conventions.
+
+### Windows `.cmd` (ExecutionPolicy bypass)
+
+`scripts/build-occt-v8-wasm.cmd` wraps the PowerShell script (same pattern as `check-nonascii-src.cmd`):
+
+```bat
+@echo off
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0build-occt-v8-wasm.ps1" %*
+if errorlevel 1 exit /b 1
+```
+
+**Batch + emsdk:**
+
+```bat
+call C:\src\emsdk\emsdk_env.bat
+cd /d C:\src\EzyCad
+scripts\build-occt-v8-wasm.cmd -RootDir C:\src\occt-wasm-build
+```
+
+### Unix `.sh`
+
+No first-party wasm shell script yet; a `scripts/build-occt-v8-wasm.sh` may mirror the PowerShell logic:
+
+- `set -euo pipefail`
+- Require `emcc`, `git`, `cmake`
+- `ROOT="${ROOT:-$HOME/occt-wasm-build}"`
+- Download `freetype-$VER.tar.gz` (gzip portable; avoid `.tar.xz` if `xz` missing)
+- `emcmake cmake -S ... -B ...` with the same `-D` flags as the `.ps1`
+- `emmake cmake --build ... --target install -j"$(nproc)"`
+- Print `OpenCASCADE_DIR=$ROOT/install/lib/cmake/opencascade`
+
+Use forward slashes in cmake paths on Unix.
+
+### PowerShell one-liner (no policy change)
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File C:\src\EzyCad\scripts\build-occt-v8-wasm.ps1 -RootDir C:\src\occt-wasm-build
+```
+
+### curl downloads (CI)
+
+**Windows desktop 8.0 combined:**
+
+```bash
+curl -L -o occt-combined.zip https://github.com/Open-Cascade-SAS/OCCT/releases/download/V8_0_0/occt-combined-release-no-pch.zip
+```
+
+**Windows desktop 7.9.1 3rdparty:**
+
+```bash
+curl -L -o 3rdparty.zip https://github.com/Open-Cascade-SAS/OCCT/releases/download/V7_9_1/3rdparty-vc14-64.zip
+```
+
+### vcpkg (alternative desktop path)
+
+OCCT 8 supports vcpkg (`USE_VTK=ON` only if needed). EzyCad’s `CMakeLists.txt` is written for `find_package(OpenCASCADE)` + manual `OCCT_3RD_PARTY_DIR` DLL copies — vcpkg integration is **not** wired in-tree.
+
+---
+
+## Maintaining OCCT version pins
+
+| File | What to update |
+| --- | --- |
+| `README.md` | Pin version, download URLs, example `OpenCASCADE_DIR` |
+| `CMakeLists.txt` | `OCCT_3RD_PARTY_DIR` paths (freetype/tbb/ffmpeg versions in `DLLS_COMMON`) |
+| `scripts/build-occt-v8-wasm.ps1` | `$OcctTag`, `$FreeTypeVersion`, cmake flags |
+| `docs/building-occt.md` | This document |
+| `src/ply_io.cpp` | Comments if triangulation API changes |
+
+---
+
+## Quick reference: EzyCad CMake variables
+
+| Variable | Platform | Purpose |
+| --- | --- | --- |
+| `OpenCASCADE_DIR` | All | Path to `OpenCASCADEConfig.cmake` directory |
+| `OCCT_3RD_PARTY_DIR` | Windows desktop | Root of 3rdparty bundle for runtime DLLs |
+| `CMAKE_BUILD_TYPE` | Native / wasm | `Release` recommended |
+
+EzyCad wasm also sets `TKOpenGles` in `OpenCASCADE_LIBS` when `CMAKE_CXX_COMPILER_ID` is `Emscripten`.

scripts/build-occt-v8-wasm.cmd

@@ -0,0 +1,5 @@
+@echo off
+REM Build OCCT V8.0.0 for WebAssembly (see docs/building-occt.md).
+REM Activate Emscripten first, e.g. call C:\src\emsdk\emsdk_env.bat
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0build-occt-v8-wasm.ps1" %*
+if errorlevel 1 exit /b 1