feat: establish reproducible FreeCAD web compatibility baseline

native/occt-history/README.md

@@ -1,8 +1,8 @@
 # Native OCCT history provider
 
 This provider is compiled from the cached OCCT checkout selected by
-`OCCT_SOURCE_DIR` and exposes the native Boolean history API through Emscripten
-Embind. The provider keeps `TopoDS_Shape` handles and history queries in one
+`OCCT_SOURCE_DIR` and exposes native Boolean and PartDesign history APIs through
+Emscripten Embind. The provider keeps `TopoDS_Shape` handles and history queries in one
 WASM instance. A handle from `@bitbybit-dev/occt` must never be passed directly
 to this module because WebAssembly linear memories are independent.
 
@@ -21,11 +21,67 @@ Emscripten toolchain.
 
 The exported `booleanHistory(object, tool, operation)` function supports
 `fuse`, `cut`, and `common`. It returns the native result shape, per-input
-`modified`/`generated`/`deleted` records, and capability flags. The provider also
-exports `shapeToStep(shape)` and `booleanHistoryFromStep(objectStep, toolStep,
-operation)`. The latter is the cross-WASM transport: Bitbybit exports STEP text,
-the native provider reads it with `STEPControl_Reader`, returns the Boolean
-result again as `resultStep`, and no linear-memory pointer crosses the boundary.
+`modified`/`generated`/`deleted` records, a validity/topology/quality summary,
+and capability flags. `prismHistory(profile, dx, dy, dz)` adds the first
+PartDesign Pad contract: profile vertices can generate edges and profile edges
+can generate faces, while the profile face is preserved as a result face.
+`booleanProbe` and `booleanResult` are intentionally smaller operations for
+Worker stress/ownership gates; callers must delete every returned Embind shape
+handle. Primitive constructors cover positioned boxes, cylinders, spheres,
+cones and a test rectangle Face. The provider also exports `shapeToStep(shape)`,
+`booleanHistoryFromStep(objectStep, toolStep, operation)` and
+`prismHistoryFromStep(profileStep, dx, dy, dz)`. The STEP functions are the
+cross-WASM transport: Bitbybit exports STEP text, the native provider reads it
+with `STEPControl_Reader`, returns the result again as `resultStep`, and no
+linear-memory pointer crosses the boundary. Pad history currently requires a
+valid planar Face profile; solids are rejected by OCCT rather than silently
+treated as sketches. `loftHistoryFromStep(firstSectionStep, secondSectionStep,
+ruled)` adds a verified two-section solid loft using `BRepOffsetAPI_ThruSections`.
+It records generated edges/faces for both source profiles; more than two
+sections, closed lofts, and PartDesign base fusion/cut stay on the signature
+history path until their multi-source contract is implemented.
+`pipeHistoryFromStep(profileStep, spineStep)` adds a verified single-edge
+open-spine solid sweep using `BRepOffsetAPI_MakePipe`. It records profile
+vertex/edge generation, profile end caps, and spine edge/endpoint provenance;
+multi-edge spines, Frenet/transition modes, and hollow profiles remain explicit
+unsupported cases.
+`filletHistoryFromStep(baseStep, radius)` enables the first
+native dress-up slice: OCCT `BRepFilletAPI_MakeFillet` applies a fixed radius to
+all source edges and returns per-edge/face `Modified`, `Generated`, and `Deleted`
+relations with result-kind mapping. The native build enables `TKFillet` and its
+`TKBool` dependency.
+`chamferHistoryFromStep(baseStep, distance)` uses the same native history
+collector with `BRepFilletAPI_MakeChamfer` for a symmetric, fixed-distance,
+all-edge chamfer.
+`holeHistoryFromStep(baseStep, radius, depth, px, py, pz, dx, dy, dz)` composes
+an OCCT cylinder and `BRepAlgoAPI_Cut` for a straight cylindrical hole with
+explicit position and direction, returning the Boolean source history. Thread,
+counterbore, countersink, and face-attached hole semantics remain outside this
+minimal native contract.
+`draftHistoryFromStep(baseStep, faceIndex, angle, direction, neutralPlane,
+reversed)` uses `BRepOffsetAPI_DraftAngle` from `TKOffset` for one explicitly
+selected source face. It returns native per-subshape history and rejects an
+invalid face index, zero direction, zero angle, or invalid neutral plane before
+publishing a result. Multi-face propagation and STEP files whose imported face
+orientation OCCT cannot draft remain explicit unsupported/error cases.
+`thicknessHistoryFromStep(baseStep, faceIndex, offset, intersectionJoin)` uses
+`BRepOffsetAPI_MakeThickSolid` for one explicitly removed source face and
+returns native offset history. Zero offsets and invalid face indexes are
+rejected before execution.
+`linearPatternHistoryFromStep(baseStep, dx, dy, dz)` creates one transformed
+copy and fuses it with the source, preserving both Boolean input histories.
+The contract intentionally covers exactly two whole-shape instances.
+`polarPatternHistoryFromStep(baseStep, axis, angle)` creates one rotated copy
+and fuses it with the source. It likewise covers exactly two whole-shape
+instances around an explicit finite axis.
+`mirroredHistoryFromStep(baseStep, planeOrigin, planeNormal)` creates one plane
+reflected copy and fuses it with the source. The native contract is limited to
+one whole-shape base, one standard document plane, and a fused result.
+The `multiTransformHistoryFromStep(baseStep, steps)` binding accepts two to six
+ordered two-instance linear, polar, or mirrored whole-shape steps. Each created
+instance retains its transformed Base subshape mapping; one multi-argument Fuse
+then aggregates every instance history back to the original Base indexes. The
+single-step protocol continues to reuse the individual verified bindings.
 
 The TypeScript boundary mapper is `mapNativeOcctHistoryRecords`; the reusable
 `createNativeOcctStepHistoryBridge` exports Bitbybit ShapeHandles to STEP and