feat: establish reproducible FreeCAD web compatibility baseline

native/planegcs/README.md

@@ -0,0 +1,91 @@
+# FreeCAD planegcs WASM
+
+This directory builds the planegcs core from the locked FreeCAD 1.1.1 commit
+`0108fd4b4850cc46e625b60e53cea7a7bbe69f8d`. The source graph contains
+`Geo.cpp`, `Constraints.cpp`, `SubSystem.cpp`, `qp_eq.cpp`, and `GCS.cpp`.
+The browser-only stubs provide the FreeCAD console, elapsed-time, and export
+macros needed by that graph; the upstream solver sources are not modified.
+
+The build enables a two-thread pthread pool because upstream planegcs uses
+`std::async`. Browser execution therefore requires COOP/COEP isolation and
+`SharedArrayBuffer`. The checked-in artifact hashes and Chrome-only dedicated
+Worker evidence are validated by the repository gates.
+
+The current Embind functions are intentionally bounded artifact and solver
+lifecycle surfaces. They prove that the real FreeCAD planegcs
+`System::solve()` and `applySolution()` execute in WASM, while the Facade owns
+snapshot validation, capability reporting, cancellation, stale-result
+handling, and crash recovery. They are not a general arbitrary-constraint
+graph adapter; that broader mapping remains in SK-06/SK-07.
+
+`solveAngle` fixes the first endpoint and combines native
+`addConstraintP2PDistance` and `addConstraintP2PAngle`. Its angle input is in
+radians and its length must be positive. Arbitrary endpoint combinations,
+multi-line angle constraints, and complete dimensional graphs remain outside
+this smoke subset.
+
+`solveCircleRadius` and `solveCircleDiameter` fix the circle center and use
+the matching native `addConstraintCircleRadius` and
+`addConstraintCircleDiameter` APIs for one positive dimension.
+
+`solveEqualLines` uses the native `addConstraintEqualLength` contract for two
+lines, fixing the first line and the second start point so the second length is
+deterministic while its direction remains free. `solveEqualCircles` uses the
+native `addConstraintEqualRadius` contract for two circles, fixing both centers
+and the first radius. Mixed geometry, arcs, ellipses, arbitrary constraint
+graphs, and reference dimensions remain outside this bounded subset.
+
+`solveTangentCircles` uses native `addConstraintTangent(Circle, Circle)` for
+two externally tangent circles with fixed centers and first radius. The
+adapter does not claim line-circle, arc, internal-tangent, or multi-constraint
+support from this function.
+
+`solvePointSymmetry` uses native `addConstraintP2PSymmetric(Point, Point,
+Point)` for three distinct point geometries. The first point and center are
+fixed, so the second point is deterministic and the returned residual is the
+midpoint-to-center distance. Line-axis symmetry, endpoint references and
+multi-constraint graphs remain outside this bounded subset.
+
+`solvePointOnLine` uses native `addConstraintPointOnLine(Point, Line)` for a
+single horizontal or vertical line. The point coordinate along the line is
+fixed and the orthogonal coordinate is solved; oblique lines, curve targets,
+endpoint references and multi-constraint graphs remain outside this subset.
+
+`solvePointOnCircle`, `solvePointOnArc`, and `solvePointOnEllipse` use the
+matching native PointOnObject relation for one fixed target curve. The point X
+coordinate is fixed and Y is solved. Arc results are accepted only when the
+point lies in the declared counter-clockwise sweep. Ellipse support preserves
+the center, focus-derived major radius, minor radius, and rotation.
+
+`solvePointOnCubicBspline` uses native `addConstraintPointOnBSpline` for one
+non-periodic, unit-weight, clamped cubic B-spline with four strictly
+X-monotonic poles. It solves the curve parameter and point Y while fixing
+point X. Other degrees, pole counts, weights, knot vectors, periodic curves,
+and arbitrary B-spline graphs remain outside this bounded contract.
+
+FreeCAD `Block` is implemented at the Facade pre-solve boundary, matching the
+desktop Sketch behavior: all parameters of the single referenced geometry are
+frozen and no synthetic GCS constraint is claimed.
+
+`solveCoincidentLinePoints` directly uses native
+`addConstraintP2PCoincident` and accepts all four start/end combinations for
+two distinct non-degenerate lines. The first line is fixed and the second line
+keeps its original length. `solveCoincidentLines` remains as the compatible
+first-end to second-start wrapper.
+
+`solveSnellsLawLines` maps FreeCAD's three-Line SnellsLaw graph. The selected
+ray endpoints must already coincide on the boundary, matching the Coincident
+and PointOnObject prerequisites created by the desktop Sketcher command. The
+native binding preserves the first ray, boundary, and second-ray length, uses
+FreeCAD's stored `n2/n1` ratio split and endpoint-dependent normal flips, then
+solves `addConstraintSnellsLaw`. The Facade accepts this operation only when
+the three prerequisite constraints form the exact compound graph.
+
+```bash
+./npmw run build:planegcs
+./npmw run check:planegcs-artifact
+./npmw run test:planegcs
+./npmw run test:chrome-planegcs
+```
+
+FreeCAD planegcs source files retain their upstream LGPL licensing notices.