docs: rewrite the upstream brief from measurement, correcting two errors

The 2026-06-21 assessment was written before the persistence work landed and
got two load-bearing facts wrong. Both are corrected here against the branch
itself rather than from recollection:

1. It called OCCT "a dependency mainline OrcaSlicer has never carried" and
   built its whole conclusion on that. False: deps/OCCT/ exists at the
   merge-base, and upstream already links it from Format/STEP.cpp,
   Format/svg.cpp and Shape/TextShape.cpp. The real dependency diff is one
   line -- BUILD_MODULE_ModelingAlgorithms OFF -> ON -- costing a measured
   3.77 MiB of Windows DLLs (TKFillet + TKOffset; TKBool already arrives
   transitively via DataExchange).

2. It described the vendored SolveSpace solver as LGPL. False:
   src/libslic3r/slvs/LICENSE is GPL-3.0. Harmless for us, but a licence
   must not be misstated in a document aimed at upstream.

It also claimed no changes to Model, which stopped being true when 3MF
recipe persistence added a std::string there.

The rewrite replaces prose estimates with counted figures: 138 new files,
23 modified upstream files at +457/-75, nothing deleted, 99.3 % of the diff
in new files. That reframes the ask from "adopt a CAD kernel" to "widen a
build flag you already carry", which is the argument that actually has a
chance upstream.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BVzKmX6Y1aEteit1HTXG4Q

docs/design_tab_upstream_portability.md

@@ -1,58 +1,163 @@
-# Design (CAD) tab — upstream portability assessment
+# Design (CAD) tab — upstream integration brief
 
-**Question:** can the SnapOrca *Design tab* (sketch-first parametric CAD: sketch →
-constrain → extrude/revolve/fillet/hole/thread/shell, multi-body, undo) be contributed
-to **mainline OrcaSlicer** (2.4 dev) rather than living only in this Snapmaker fork?
+**Question:** can the Design tab (sketch-first parametric CAD: sketch → constrain →
+extrude/revolve/fillet/hole/thread/shell, multi-body, undo, 3MF persistence) land in
+mainline OrcaSlicer?
 
-**Short answer: yes, technically clean — the feature is self-contained and vendor-neutral.
-The single real gatekeeper is whether upstream is willing to take on OpenCASCADE (OCCT) as a
-build dependency, i.e. whether OrcaSlicer wants to become a CAD-integrated slicer.**
+**Answer: yes, and the ask is far smaller than previously believed.** OCCT is *already*
+an OrcaSlicer dependency. We are not asking upstream to adopt a new library; we are
+asking it to widen one it already builds, at a measured cost of **3.77 MiB on Windows**.
 
-## Why it is portable
+> ### Corrections to the 2026-06-21 assessment
+> That revision was written before the persistence work landed and got two load-bearing
+> facts wrong. Both are corrected here from direct measurement of the branch:
+>
+> 1. **"The real blocker: OCCT … a dependency mainline OrcaSlicer has never carried."**
+>    **False.** `deps/OCCT/` exists at the merge-base and upstream links it from
+>    `Format/STEP.cpp`, `Format/svg.cpp`, and `Shape/TextShape.cpp`. Our entire
+>    dependency diff is **one line**: `BUILD_MODULE_ModelingAlgorithms=OFF → ON`.
+> 2. **"vendored SolveSpace solver … LGPL."** **False.** `src/libslic3r/slvs/LICENSE` is
+>    **GPL-3.0**, not LGPL. This is fine (see Licensing) but must not be misstated.
+>
+> It also claimed "no changes to Model" — no longer true; 3MF recipe persistence adds one
+> `std::string` to `Model`.
 
-- **Self-contained.** The feature is ~28 kLOC of *new* files (kernel
-  `CadDocument` / `SketchEngine` / `GeometryEngine` / `Sketch*`; GUI
-  `DesignPanel` / `DesignCanvas` / `DesignSketchTool` / `GLGizmoSketch`) plus a
-  vendored, self-contained SolveSpace solver (`src/libslic3r/slvs/`, ~10 kLOC, LGPL).
-- **Tiny, guarded injection into shared code (~2–3 % surface).** The only edits to
-  pre-existing OrcaSlicer files are: a `m_design_sketch_tool` member + a handful of
-  null-checked hooks in `GLCanvas3D` (render overlay, mouse routing, Delete/Esc/Ctrl+Z),
-  a tab member + construction in `MainFrame`, and a few forward declarations. **No
-  changes** to the slicing pipeline (Print/PrintObject/Layer/GCode), Plater, Tab, Model,
-  or the printer-profile/config system.
-- **Zero Snapmaker coupling.** No "Snapmaker" references in any Design/CAD file; icons
-  are generic `resources/images/design_*.svg`; the code is pure wxWidgets/OpenGL/OCCT.
-  It would build and run in any OrcaSlicer fork unchanged.
-- **Orthogonal git history.** The feature lives on `feature/cad-primitives` as a clean,
-  linear series of `Design:` / `C*` / `M*` commits with no interleaved fork-specific
-  work, so it cherry-picks onto a clean OrcaSlicer base without slicing-logic conflicts.
+## Measured shape of the change
 
-## The real blocker: OCCT
+Against merge-base `449a4cf9fc` (34 commits ahead):
 
-`src/libslic3r/CMakeLists.txt` links ~30 OCCT toolkits (`TKBRep TKFillet TKOffset
-TKBool TKPrim TKTopAlgo TKMath TKernel …`) via `find_package(OpenCASCADE REQUIRED)`.
-OCCT is large (hundreds of MB of binaries, +15–30 min to a clean deps build) and is a
-dependency **mainline OrcaSlicer has never carried**. Accepting it is an architectural
-decision about the project's scope, not a code problem.
+| | files | lines |
+|---|---:|---:|
+| **New files** | 138 | +61,720 |
+| **Modified upstream files** | 23 | +457 / −75 |
+| **Deleted upstream files** | 0 | — |
 
-## Top work items to upstream (≈3–5 dev-days)
+The 62 kLOC headline is inflated by localization. The feature itself:
 
-1. **Make OCCT an *optional* dependency.** Add it to `deps/` like the other externals,
-   gate the whole feature behind a CMake option (`-DENABLE_DESIGN_CAD=OFF` by default),
-   and document OCCT install per-platform. Builds without OCCT simply omit the tab.
-2. **Guard the tab construction** in `MainFrame` (and the `GLCanvas3D` hooks) on that
-   same flag so a minimal build links and runs with no Design code at all.
-3. **Tests + docs + license hygiene.** Add regression coverage for the kernel
-   (sketch-solve, extrude, fillet, undo), ship the LGPL notice for the vendored
-   `slvs/`, and add user docs. (libslvs itself is self-contained, no external deps.)
+| area | LOC | files |
+|---|---:|---:|
+| kernel (`src/libslic3r/`) | 15,828 | 37 |
+| GUI (`src/slic3r/`) | 19,544 | 14 |
+| tests (Catch2) | 2,567 | 6 |
+| i18n (unrelated; strip from the CAD PR) | 23,438 | 77 |
+
+**99.3 % of the diff is new files.** The negotiable surface is 457 added lines across 23
+files, and nothing upstream is deleted. The largest single hook is `GLCanvas3D.cpp`
+(+110/−2): an `m_design_sketch_tool` member plus render/mouse/key hooks, **every one
+already null-guarded** — which is why the compile-time gate below is cheap.
+
+No changes to the slicing pipeline (Print/PrintObject/Layer/GCode), Tab, or the
+printer-profile/config system.
+
+## The dependency ask, precisely
+
+Not "adopt OCCT" — **widen the existing OCCT build**:
+
+```diff
+-        -DBUILD_MODULE_ModelingAlgorithms=OFF
++        -DBUILD_MODULE_ModelingAlgorithms=ON
+```
+
+Cost, measured from the shipped Windows artifact (42 OCCT DLLs, 45.43 MiB total):
+
+| toolkit | size | note |
+|---|---:|---|
+| `TKFillet.dll` | 2.02 MiB | only exists with the flag ON |
+| `TKOffset.dll` | 1.75 MiB | only exists with the flag ON |
+| **delta** | **3.77 MiB** | Windows only (OCCT is Shared on Win, Static elsewhere) |
+
+`TKBool` is *not* part of the delta — upstream's `DataExchange` already pulls it in
+transitively. On macOS/Linux OCCT links statically, so the cost is only the code actually
+referenced, not a 3.77 MiB floor.
+
+**Unmeasured, and we should measure before the call:** clean-deps build-time delta with
+the flag ON vs OFF, and the resulting CI runner-minute cost. Do not guess these at him.
+
+## Licensing
+
+- Vendored solver `src/libslic3r/slvs/` — **GPL-3.0**, 9,339 LOC, © Jonathan Westhues,
+  a self-contained subset of SolveSpace (`libslvs`). No external dependencies.
+- OrcaSlicer — **AGPL-3.0** (`LICENSE.txt`).
+
+GPLv3 §13 expressly permits combining a GPLv3 work with an AGPLv3 work; AGPLv3 §13 grants
+the converse. The combined work is distributable under AGPL-3.0 with the solver's GPLv3
+terms preserved. This is a favourable direction (GPLv3 → into an AGPLv3 project), but it
+is a point to **confirm explicitly with upstream**, not to assert unilaterally.
+
+Open question for SoftFever: keep the solver **vendored** (current: pinned, no submodule,
+no external build) or move it to `deps/` as a fetched external? Vendoring costs us
+upstream-sync burden; `deps/` costs build complexity.
+
+## The one irreversible decision: the 3MF format
+
+Persistence adds an **optional** archive entry and one field:
+
+```cpp
+// Model.hpp
+std::string cad_recipe;   // empty for non-CAD projects
+```
+
+```
+Metadata/SnapOrca_cad.bin   // written only when cad_recipe is non-empty
+```
+
+Readers that do not know the entry ignore it; writers skip it entirely when empty. So
+existing projects are bit-identical and old readers are unaffected. Good.
+
+**But the moment upstream ships this, it owns forward-compatibility forever.** Three
+things should be settled *before* the first release, because none can be changed after:
+
+1. **Name.** `SnapOrca_cad.bin` is fork-branded in an upstream project file. Rename to a
+   neutral path (e.g. `Metadata/cad_recipe.bin`).
+2. **Encoding.** The recipe is an opaque **cereal `PortableBinaryArchive`** blob whose
+   layout is the field order of `CadFeature::serialize`. Portable across endianness and
+   word size — *not* across a field reorder. Append-only is currently a convention held by
+   discipline, not by any check.
+3. **Embedded BRep.** `Import` features embed OCCT's ASCII BRep for the imported solid,
+   which couples saved project files to an OCCT BRep revision. Alternative: re-import from
+   the source STEP and store only a reference. Worth deciding deliberately.
+
+**Concrete gap we should close before the call.** `test_caddocument.cpp` covers the
+in-memory round-trip and correctly refuses a version-999 blob — but there is **no
+checked-in v1 fixture on disk**. A reordered field in `CadFeature::serialize` would pass
+the entire suite while silently breaking every previously-saved project. Ship a golden
+`.bin` fixture generated today plus a test that loads it; that is the only thing that will
+hold the format still once real users have files.
+
+## Proposed PR decomposition
+
+35 kLOC in one PR is not reviewable. Behind the flag, slices 1–4 are behaviour-neutral for
+existing users:
+
+1. **Build gate + OCCT flag + Windows packaging guard.** `-DSLIC3R_CAD=ON/OFF`, default
+   **OFF**. Flips `ModelingAlgorithms=ON`. Includes the guard that asserts every linked
+   OCCT toolkit has a shipped DLL (already on both forks: `546cef5f42`). ← *this is what
+   makes SoftFever's "parallel build" a one-line CI matrix entry.*
+2. **Vendored `slvs` solver** + its Catch2 tests. No GUI, no OCCT.
+3. **CAD kernel** (`CadDocument`, `SketchEngine`, `GeometryEngine`, `Sketch*`) + kernel
+   tests. Headless, no GUI.
+4. **3MF recipe persistence** + golden-fixture regression test.
+5. **GUI Design tab** (`DesignPanel`, `DesignCanvas`, `DesignSketchTool`, `GLGizmoSketch`)
+   + the 23 upstream hooks.
+
+## Agenda for the call
+
+Questions only SoftFever can answer:
+
+- Does OrcaSlicer *want* to be a CAD-integrated slicer? (Strategic; everything else is mechanical.)
+- Default of `SLIC3R_CAD` at merge time, and when it flips ON.
+- Vendored solver vs `deps/` external; and confirmation of the GPLv3/AGPLv3 combination.
+- Project-file format: neutral name, encoding, embedded-BRep policy, and who owns v1 forward-compat.
+- Undo/redo: the Design tab has its own stack; integrate with Orca's snapshot system or keep separate?
+- Does he want the i18n work (Romanian, +23 kLOC) as a wholly separate PR? (Yes, almost certainly.)
 
 ## Verdict
 
-Portability is **high (≈7/10): "needs moderate adaptation," not "deeply entangled."**
-The engineering to upstream is modest and mechanical (optional-dependency plumbing +
-tests/docs). The decision is strategic: **does OrcaSlicer want OCCT and a CAD tab?** If
-yes, this feature is a near-drop-in starting point.
+Portability **high**. The prior "does upstream want OCCT" framing was wrong — OCCT is
+already there. What remains is a 3.77 MiB dependency widening, a compile-time gate that
+the existing null-guards make cheap, and one file-format decision that must be made before
+the first release rather than after.
 
 ---
-*Generated 2026-06-21 from a read-only analysis of the `feature/cad-primitives` branch.
-Tracking issue: bd `snaporca-frp`.*
+*Revised 2026-07-10 from direct measurement of `cad-mainline` @ `546cef5f42` vs upstream
+merge-base `449a4cf9fc`. Supersedes the 2026-06-21 read-only assessment.*