# 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.