OCCT dual-version harden: Handle aliases, failure messages, warning cleanup

agents.md

@@ -21,6 +21,8 @@ Pointer for AI coding assistants. Details live in [agents/README.md](agents/READ
 - Script consoles: [src/doc/script.md](src/doc/script.md) (read; update when bindings or console UI change)
 - Utilities: [src/doc/utility.md](src/doc/utility.md) (read; update when utl_* contracts or I/O change)
 - Build/test: [agents/workflows/local-dev.md](agents/workflows/local-dev.md) or root README
+- OCCT APIs / WASM (desktop 8 vs wasm 7.9.3): [agents/conventions/occt-wasm-dual-version.md](agents/conventions/occt-wasm-dual-version.md) — until wasm works on OCCT 8
+- OCCT handles (`Handle` vs `*_ptr`): [agents/conventions/occt-handles.md](agents/conventions/occt-handles.md)
 - Release (maintainers only): [agents/workflows/release.md](agents/workflows/release.md)
 - Open work context: one file under [agents/drafts/](agents/drafts/) if relevant
 

agents/README.md

@@ -6,21 +6,23 @@ Root markers: [AGENTS.md](../AGENTS.md) / [agents.md](../agents.md).
 
 ## Quick index
 
-| Need                      | File                                                                                                                 |
-| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| ASCII / `src/` edits      | [conventions/ascii-source.md](conventions/ascii-source.md)                                                           |
-| C++ style (full)          | [docs/ezycad_code_style.md](../docs/ezycad_code_style.md)                                                            |
-| User docs when UI changes | [conventions/user-docs-sync.md](conventions/user-docs-sync.md)                                                       |
-| Sketch module (dev doc)   | [src/doc/sketch.md](../src/doc/sketch.md) — read when editing sketch code; update if API/architecture changes        |
-| Shape module (dev doc)    | [src/doc/shape.md](../src/doc/shape.md) — read when editing `shp_*` code; update if API/operations change            |
-| GUI module (dev doc)      | [src/doc/gui.md](../src/doc/gui.md) — read when editing `gui_*` / viewer shell; update if routing or settings change |
-| Script module (dev doc)   | [src/doc/script.md](../src/doc/script.md) — read when editing `scr_*`; update if bindings change                     |
-| Utility module (dev doc)  | [src/doc/utility.md](../src/doc/utility.md) — read when editing `utl_*`; update if shared helpers or I/O change      |
-| Build / test / wasm       | [workflows/local-dev.md](workflows/local-dev.md)                                                                     |
-| Release                   | [workflows/release.md](workflows/release.md)                                                                         |
-| Issue/PR drafts           | [drafts/](drafts/) — [github-drafts.md](conventions/github-drafts.md)                                                |
-| Token-saving rules        | [conventions/token-lean.md](conventions/token-lean.md)                                                               |
-| Markdown tables           | [conventions/markdown-tables.md](conventions/markdown-tables.md) — align GFM pipes for source + preview              |
-| Outreach (optional)       | [outreach/discoverability.md](outreach/discoverability.md)                                                           |
+| Need                         | File                                                                                                                 |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| ASCII / `src/` edits         | [conventions/ascii-source.md](conventions/ascii-source.md)                                                           |
+| C++ style (full)             | [docs/ezycad_code_style.md](../docs/ezycad_code_style.md)                                                            |
+| User docs when UI changes    | [conventions/user-docs-sync.md](conventions/user-docs-sync.md)                                                       |
+| Sketch module (dev doc)      | [src/doc/sketch.md](../src/doc/sketch.md) — read when editing sketch code; update if API/architecture changes        |
+| Shape module (dev doc)       | [src/doc/shape.md](../src/doc/shape.md) — read when editing `shp_*` code; update if API/operations change            |
+| GUI module (dev doc)         | [src/doc/gui.md](../src/doc/gui.md) — read when editing `gui_*` / viewer shell; update if routing or settings change |
+| Script module (dev doc)      | [src/doc/script.md](../src/doc/script.md) — read when editing `scr_*`; update if bindings change                     |
+| Utility module (dev doc)     | [src/doc/utility.md](../src/doc/utility.md) — read when editing `utl_*`; update if shared helpers or I/O change      |
+| Build / test / wasm          | [workflows/local-dev.md](workflows/local-dev.md)                                                                     |
+| OCCT desktop 8 vs wasm 7.9.3 | [conventions/occt-wasm-dual-version.md](conventions/occt-wasm-dual-version.md) — until wasm works on OCCT 8          |
+| OCCT handles (`*_ptr`)       | [conventions/occt-handles.md](conventions/occt-handles.md) — prefer aliases over `Handle()` for clang-format         |
+| Release                      | [workflows/release.md](workflows/release.md)                                                                         |
+| Issue/PR drafts              | [drafts/](drafts/) — [github-drafts.md](conventions/github-drafts.md)                                                |
+| Token-saving rules           | [conventions/token-lean.md](conventions/token-lean.md)                                                               |
+| Markdown tables              | [conventions/markdown-tables.md](conventions/markdown-tables.md) — align GFM pipes for source + preview              |
+| Outreach (optional)          | [outreach/discoverability.md](outreach/discoverability.md)                                                           |
 
 Full user-doc style: [docs/ezycad_doc_style.md](../docs/ezycad_doc_style.md). OCCT build: [docs/building-occt.md](../docs/building-occt.md).

agents/conventions/occt-handles.md

@@ -0,0 +1,29 @@
+# OCCT handles vs `Handle()` macro
+
+Prefer the pattern in [`src/utl_types.h`](../../src/utl_types.h):
+
+```cpp
+using AIS_Shape_ptr = opencascade::handle<AIS_Shape>;
+```
+
+Use those `*_ptr` aliases (or `opencascade::handle<T>` inline) in new and touched code.
+
+## Why not `Handle(T)`?
+
+OCCT's `Handle(T)` macro is valid and expands to `opencascade::handle<T>`, but **clang-format does not treat it as a type**. With `PointerAlignment: Left`, format runs produce awkward spacing such as:
+
+```cpp
+const Handle(Geom_TrimmedCurve) & curve;  // bad (formatter)
+const Geom_TrimmedCurve_ptr& curve;       // good
+```
+
+Do **not** paper over this with `// clang-format off` for routine handle declarations.
+
+## Agent rules
+
+1. For a type used as a handle in EzyCad, add or reuse a `using TypeName_ptr = opencascade::handle<TypeName>;` in `utl_types.h` (forward-declare the class there if needed, matching existing entries).
+2. Prefer `TypeName_ptr` in signatures, locals, and members.
+3. `DownCast`: `TypeName_ptr::DownCast(obj)` (or `opencascade::handle<TypeName>::DownCast(obj)`), not `Handle(TypeName)::DownCast(obj)`.
+4. When editing a function that already uses `Handle(...)`, convert that local scope to `*_ptr` / `opencascade::handle` if the change is small; do not mass-rewrite unrelated files.
+
+Style summary: [docs/ezycad_code_style.md](../../docs/ezycad_code_style.md) (OCCT handles).

agents/conventions/occt-wasm-dual-version.md

@@ -0,0 +1,41 @@
+# OCCT desktop vs WASM (until v8 wasm works)
+
+**Temporary:** keep this file until EzyCad WASM builds and runs correctly against OCCT **8.x** (GLES shading and any remaining regressions fixed; see [docs/bugs.md](../../docs/bugs.md)). Then delete this convention and drop the pointers from `AGENTS.md` / `agents/README.md` / `token-lean.md`.
+
+## Pins
+
+| Target            | OCCT version                        | Notes                                      |
+| ----------------- | ----------------------------------- | ------------------------------------------ |
+| Desktop (Windows) | **8.0.0**                           | Prebuilts + `TKOpenGl`                     |
+| WASM (Emscripten) | **7.9.3** (`V7_9_3`) recommended    | `scripts/build-occt-793-wasm.ps1`          |
+| WASM (compare)    | 8.0.0.p1 (`V8_0_0_p1`) experimental | Shading regressions; not for demos/release |
+
+Details: [docs/building-occt.md](../../docs/building-occt.md), [workflows/local-dev.md](../workflows/local-dev.md).
+
+## Shared `src/` must compile on both
+
+Most app code is one tree linked against **desktop 8** and **wasm 7.9.3**. Prefer the **API intersection**. Do not assume an OCCT 8-only symbol or overload is available on the wasm kit.
+
+### `Standard_Failure` messages
+
+Use `standard_failure_message(e)` from [`utl_occt.h`](../../src/utl_occt.h) — not raw `what()` or `GetMessageString()`:
+
+```cpp
+catch (const Standard_Failure& e)
+{
+  const char* msg = standard_failure_message(e);
+  // ...
+}
+```
+
+OCCT **8** (desktop) deprecates `GetMessageString()` in favor of `what()`; OCCT **7.9.3** (wasm) has no `what()` on `Standard_Failure`. The helper picks the right API via `OCC_VERSION_HEX` so shared code builds on both without warnings or missing-member errors.
+
+### Other dual-version habits
+
+- Prefer existing call patterns already used for both targets over newer OCCT 8 helpers.
+- If you must use an 8-only API, gate it or verify a wasm 7.9.3 configure/build still succeeds.
+- Default wasm work to **7.9.3**; use the v8 wasm script only when comparing upstream regressions.
+
+## When retiring this note
+
+After wasm on OCCT 8 is the supported path: switch demo/release scripts to `build-occt-v8-wasm.ps1`, update [docs/building-occt.md](../../docs/building-occt.md) / [docs/bugs.md](../../docs/bugs.md), then remove this file and its index links.

agents/conventions/token-lean.md

@@ -15,6 +15,8 @@ Goal: give assistants **only what they need** for the task at hand. Full style g
 | Task                                                                                                 | Read                                                                                                                                |
 | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
 | Build / test                                                                                         | [workflows/local-dev.md](../workflows/local-dev.md) — or root [README.md](../../README.md#building-instructions)                    |
+| OCCT / WASM (shared `src/` APIs)                                                                     | [occt-wasm-dual-version.md](occt-wasm-dual-version.md) — desktop 8 vs wasm 7.9.3 until wasm works on OCCT 8                         |
+| OCCT handles                                                                                         | [occt-handles.md](occt-handles.md) — `*_ptr` / `opencascade::handle` over `Handle()` (clang-format)                                 |
 | User-visible UI/settings                                                                             | [user-docs-sync.md](user-docs-sync.md) + target `docs/usage-*.md` only                                                              |
 | Sketch subsystem (`src/sketch*`, `tests/sketch_*_tests.cpp`, sketch behavior in `occt_view` / `gui`) | [src/doc/sketch.md](../../src/doc/sketch.md) — read before editing; update when API, invariants, module layout, or workflows change |
 | Shape module (`src/shp*`, shape ops in `occt_view` / `gui`)                                          | [src/doc/shape.md](../../src/doc/shape.md) — read before editing; update when API, operation patterns, or registration/undo change  |

agents/drafts/issues/active/gh-196-occt-dual-version-handle-warnings.md

@@ -0,0 +1,37 @@
+---
+github_issue: 196
+github_pr: 197
+status: active
+paired_draft: ../prs/active/gh-197-occt-dual-version-handle-warnings.md
+---
+
+# OCCT dual-version (desktop 8 / WASM 7.9.3) harden
+
+**Suggested labels:** `bug`, `documentation`, `refactor`
+
+---
+
+## Title (GitHub)
+
+OCCT dual-version (desktop 8 / WASM 7.9.3): Handle aliases, failure messages, build warning cleanup
+
+## Body (GitHub)
+
+Filed: https://github.com/trailcode/EzyCad/issues/196
+
+### Summary
+
+Shared `src/` must build against desktop OCCT **8.0.0** and recommended WASM OCCT **7.9.3** until OCCT 8 GLES shading works for wasm. Harden that split: stop using `Handle(T)`, add dual-version `Standard_Failure` messaging, document agent conventions, clear native/WASM warnings.
+
+### Acceptance criteria
+
+- [x] `standard_failure_message()` used at `Standard_Failure` catch sites
+- [x] `Handle(...)` -> `*_ptr` aliases in `utl_types.h`
+- [x] Agent conventions wired (`occt-wasm-dual-version.md`, `occt-handles.md`)
+- [x] Native/WASM listed warnings cleared
+- [ ] CI green
+
+### Related
+
+- PR: https://github.com/trailcode/EzyCad/pull/197
+- Draft: `agents/drafts/prs/active/gh-197-occt-dual-version-handle-warnings.md`

agents/drafts/prs/active/gh-197-occt-dual-version-handle-warnings.md

@@ -0,0 +1,36 @@
+---
+github_issue: 196
+github_pr: 197
+status: active
+paired_draft: ../issues/active/gh-196-occt-dual-version-handle-warnings.md
+---
+
+# PR - OCCT dual-version harden
+
+## Title
+
+OCCT dual-version harden: Handle aliases, failure messages, warning cleanup
+
+## Summary
+
+- Desktop OCCT 8 vs WASM 7.9.3: `standard_failure_message()`, `*_ptr` over `Handle(T)`, agent conventions.
+- Compiler warning cleanup (native + emscripten dock flags).
+
+## Related
+
+- Issue: https://github.com/trailcode/EzyCad/issues/196
+- PR: https://github.com/trailcode/EzyCad/pull/197
+- Branch: `Trailcode/gen-fixes-refactor`
+
+## Test Plan
+
+- [x] Native Debug rebuild clean of listed warnings
+- [x] WASM build-em-793 dock enum warning fixed
+- [ ] CI Windows MSVC
+- [ ] Spot-check OCCT error paths and Esc cancel
+
+## Post-merge
+
+- [ ] Archive this draft and paired issue draft
+- [ ] Close #196 if fully addressed
+- [ ] Consider `CHANGELOG.md` `[Unreleased]` note

agents/workflows/local-dev.md

@@ -47,6 +47,8 @@ See root [README.md](../../README.md#building-instructions) and [docs/building-o
 
 ## WebAssembly (Emscripten)
 
+**Agent note:** desktop uses OCCT **8**, recommended wasm uses **7.9.3** until OCCT 8 wasm works. Shared `src/` must compile on both — see [conventions/occt-wasm-dual-version.md](../conventions/occt-wasm-dual-version.md).
+
 Full OCCT + EzyCad wasm instructions live in [docs/building-occt.md](../../docs/building-occt.md#webassembly-emscripten) and the root README.
 
 High-level flow (after `emsdk_env`):

docs/ezycad_code_style.md

@@ -69,7 +69,8 @@ User-facing Markdown (now in `docs/`: `usage.md`, `usage-*.md`, `scripting.md`,
 - **Helper functions** (`.cpp`): Prefer **file-local static helpers** in an anonymous namespace at the **bottom** of the implementing `.cpp` file. Forward-declare them near the top (or above their first use) when needed. Avoid large helper blocks at the top of the file; the goal is high-level code first, helpers last for readability.
 - **PIMPL** (`class Foo; class Foo::Impl`): Use when hiding implementation details or when you want to swap implementations (e.g. `Sketch_nodes`, `Sketch_op_recorder`). Keep the public surface in the header; put data members, private record types, and apply/clone logic in `Impl` inside the `.cpp`.
 - **Templates**: Prefer putting template implementations in `.inl` files included from the header (e.g. `utl_types.inl`, `utl.inl`).
-- **OCCT handles**: Use `opencascade::handle<T>` and project aliases (e.g. `AIS_Shape_ptr`, `Shp_ptr`).
+- **OCCT handles**: Prefer `opencascade::handle<T>` and project `*_ptr` aliases from `utl_types.h` (e.g. `AIS_Shape_ptr`, `Shp_ptr`). Avoid the OCCT `Handle(T)` macro in new/touched code -- clang-format mishandles it with `PointerAlignment: Left` (e.g. `Handle(Foo) &`). See [agents/conventions/occt-handles.md](../agents/conventions/occt-handles.md).
+- **OCCT desktop vs WASM**: Until WASM runs correctly on OCCT 8, desktop is OCCT **8** and recommended WASM is **7.9.3**. Prefer APIs available on both; for `Standard_Failure` use `standard_failure_message(e)` from `utl_occt.h` (not raw `what()` / `GetMessageString()`). See [agents/conventions/occt-wasm-dual-version.md](../agents/conventions/occt-wasm-dual-version.md).
 - **Result/error handling**: See **Fail fast** below. Use `Result<T>` and `Status` from `utl.h`, `CHK_RET(...)` for early return on failure.
 - **Assertions**: See **Fail fast** below. Use `EZY_ASSERT` and `EZY_ASSERT_MSG` from `utl_dbg.h`; use `DBG_MSG` for debug logging.
 

src/doc/utility.md

@@ -24,7 +24,7 @@ Typical uses:
 | [`utl_types.h`](../utl_types.h)                                                | OCCT/AIS handle typedefs, `ScreenCoords`, `Export_format`, `DECL_PTR`, `SafeType`          |
 | [`utl_geom.h`](../utl_geom.h) / [`.cpp`](../utl_geom.cpp)                      | 2D/3D geometry, wires, dimensions, Boost polygon tests, plane projection                   |
 | [`utl_geom_boost.inl`](../utl_geom_boost.inl)                                  | `ezy_geom` Boost.Geometry aliases                                                          |
-| [`utl_occt.h`](../utl_occt.h) / [`.cpp`](../utl_occt.cpp)                      | `TopAbs` name table, `try_make_solid`                                                      |
+| [`utl_occt.h`](../utl_occt.h) / [`.cpp`](../utl_occt.cpp)                      | `TopAbs` name table, `try_make_solid`, `standard_failure_message`                          |
 | [`utl_json.h`](../utl_json.h) / [`.cpp`](../utl_json.cpp)                      | JSON serializers for `gp_Pnt`, `gp_Pln`, etc.                                              |
 | [`utl_io.h`](../utl_io.h) / [`.cpp`](../utl_io.cpp)                            | `.ezy` zip v3 pack/unpack, format sniff, base64                                            |
 | [`utl_asset_store.h`](../utl_asset_store.h) / [`.cpp`](../utl_asset_store.cpp) | Content-addressed RGBA blobs for sketch underlay assets                                    |
@@ -102,10 +102,11 @@ Includes [`utl_geom_boost.inl`](../utl_geom_boost.inl) for `ezy_geom` polygon /
 
 ## OCCT helpers (`utl_occt`)
 
-| API                        | Role                                                     |
-| -------------------------- | -------------------------------------------------------- |
-| `c_names_TopAbs_ShapeEnum` | String names parallel to OCCT enum (selection filter UI) |
-| `try_make_solid(shape)`    | Wrap closed shell as solid when possible                 |
+| API                           | Role                                                                  |
+| ----------------------------- | --------------------------------------------------------------------- |
+| `c_names_TopAbs_ShapeEnum`    | String names parallel to OCCT enum (selection filter UI)              |
+| `try_make_solid(shape)`       | Wrap closed shell as solid when possible                              |
+| `standard_failure_message(e)` | OCCT 7/8-safe message from `Standard_Failure` (see dual-version note) |
 
 ## JSON geom (`utl_json`)
 

src/gui.cpp

@@ -227,7 +227,10 @@ void GUI::load_examples_list_()
 void GUI::seed_default_dock_layout_(ImGuiID dockspace_id)
 {
   ImGui::DockBuilderRemoveNode(dockspace_id);
-  ImGui::DockBuilderAddNode(dockspace_id, ImGuiDockNodeFlags_DockSpace | ImGuiDockNodeFlags_PassthruCentralNode);
+  // Cast private DockSpace flag: mixing ImGuiDockNodeFlagsPrivate_ with ImGuiDockNodeFlags_
+  // triggers -Wdeprecated-enum-enum-conversion (e.g. emscripten/clang).
+  ImGui::DockBuilderAddNode(dockspace_id, static_cast<ImGuiDockNodeFlags>(ImGuiDockNodeFlags_DockSpace) |
+                                              ImGuiDockNodeFlags_PassthruCentralNode);
   ImGui::DockBuilderSetNodeSize(dockspace_id, ImGui::GetMainViewport()->WorkSize);
 
   ImGuiID dock_main        = dockspace_id;