partforge 0.133.0 → 0.133.2

package/docs/AUTHORING-PARTS.md

@@ -319,7 +319,7 @@ and asks for the existing positional view argument
 ## Materials and appearance
 
 A sub-part's `display` block says how it LOOKS. Appearance never changes
-geometry, exports (other than 3MF colour, below), `measure` or `verify`, and a
+geometry, exports (other than export colours, below), `measure` or `verify`, and a
 mistake in it never fails a build — lint warns and the viewer falls back.
 
 ```js
@@ -336,7 +336,7 @@ meta: { title: "…", units: "mm", environment: "studio" },
   else the viewer's blue-grey — and **realistic mode shows it as a PLA print**
   (`pla-print`'s finish and layer lines) in that same colour. So an untouched
   part looks printed in realistic mode; name a material when it is made some
-  other way. The PLA look is realistic-only: the CAD view, 3MF colours and
+  other way. The PLA look is realistic-only: the CAD view, export colours and
   `declaresMaterials` are unaffected, and a part that names no material is not
   treated as declaring one.
 - `color` — the base colour (`0xRRGGBB`). With a preset it is the TINT. Presets
@@ -378,9 +378,11 @@ on oak shrinks the grain to a 0.2 mm tile, i.e. invisible noise):
 
 Presets without a pattern ignore it.
 
-**3MF export** carries each sub-part's colour (its `color`, else its preset's
-colour), so a multi-colour print opens in a slicer already split and coloured.
-A part with no `color` or `material` exports exactly as before.
+**3MF and STEP export** carry each sub-part's colour (its `color`, else its
+preset's colour), so a multi-colour print opens in a slicer already split and
+coloured, and each STEP body opens in a CAD tool in its own colour. A part with
+no `color` or `material` exports a 3MF exactly as before; its STEP bodies take
+the viewer's blue-grey.
 
 | Preset | Name | Tintable | Use |
 | --- | --- | --- | --- |

package/docs/KERNEL-CONTRACT.md

@@ -296,7 +296,7 @@ above. All ops return a `Solid`.
 | `vector2d(name, {shape?, width\|height\|fit, align?, valign?})` | A declared vector document → `Shape2D`. `name` = a declared name in the part's `vectors` field (`partforge-vector` JSON — authored by hand or ingested from an `.svg`; never raw `.svg`). With no `shape`, the document's own composition: every `"add"` shape unioned minus every `"subtract"` shape; `shape` selects one named shape's geometry whatever its role. Sizing follows the document's required `units`: `"artwork"` requires exactly one of `width`/`height`/`fit` in millimetres, `"mm"` places as authored (scale 1, no translate) and accepts a size option optionally; more than one is refused. Uniform scale in every case (`fit` = larger extent); `align`/`valign` position it, same as `text2d`, defaulting to centre/middle for `"artwork"` and to no translate for `"mm"`. **The composed call derives ONE transform from every region in the document**, `"add"` and `"subtract"` alike, so a size or align option cannot scale the subtracts relative to the adds; a `shape` call is measured against that shape alone. **Primitive contours (`circle`/`rect`/`polygon`) expand to ordinary path contours at the format boundary, in `vector-format.js`, so this op's kernel-facing contract is unchanged by them** — nothing below the loader learns primitives exist. Conformance: **both backends** (it lowers to `shape2d` + `union`, exactly like `text2d`). Parity: **identical across backends by construction** — the regions are curve-native (arcs/cubics), so there is no sampling step for the two backends to diverge over. |
 | `hull(inputs[])` | Convex hull of all inputs (each a `Shape2D`, a curve contour, or an `[[x,y],…]` point list) → a convex `Shape2D`. Backend-agnostic: a pure-JS monotone-chain hull over the inputs' sampled points (curved inputs tessellated at a fixed LOD), lifted via `shape2d` (see the parity note below). Throws on an empty input array or a degenerate (collinear/point-count < 3) hull. |
 | `hullChain(inputs[])` | Swept hull over an ordered sequence of ≥2 inputs (same input forms as `hull`): the union of `hull([inᵢ, inᵢ₊₁])` for each consecutive pair — e.g. a tapered link connecting a row of circles. Throws with fewer than 2 inputs. |
-| `toSTEP(named[])` | `[{name, solid}]` → `Promise<ArrayBuffer>` of a STEP assembly. B-rep class only. |
+| `toSTEP(named[])` | `[{name, solid, color?}]` → `Promise<ArrayBuffer>` of a STEP assembly. B-rep class only. `color` (`0xRRGGBB`, optional) is the body's surface colour, written as that exact sRGB value; a body without one (or with an unusable one) is written in the viewer's no-material blue-grey (`0x9fb4cc`), never a kernel default. The framework passes each sub-part's display colour — the one its 3MF object gets. Every file is AP242, its header's `FILE_SCHEMA` and its body alike — the first export in a process included. Additive: `CONTRACT_VERSION` stays 4, the `import` precedent. |
 | `import(name)` | Previously-registered imported geometry (STEP/STL/3MF, declared in the part's `imports` field) as an ordinary `Solid`. Required on both in-repo backends (Manifold accepts mesh formats, OCCT accepts STEP); a format the routed backend can't use throws lazily, at this call, not at registration. Fed by an underscore-prefixed side-channel, not part authors — see [Conformance classes](#conformance-classes). Additive: not in `OCCT_ONLY_OPS`; needed no `CONTRACT_VERSION` bump of its own (v3 came from the mesh fillet/chamfer change, not this op). |
 
 `hull`/`hullChain` parity: point-list and curve-contour inputs hull bit-identically

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.133.0",
+  "version": "0.133.2",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/geometry/kernel.js

@@ -160,7 +160,7 @@ export const ROUTED_CAD_OPS = ["shell"];
  * @property {(profile: number[][]|{outer:number[][],holes?:number[][][]}|{start:number[],segments:object[]}|Shape2D) => Shape2D} shape2d   2-D boolean value; one shared contour-storage implementation on both backends
  * @property {(inputs: (Shape2D|number[][]|{start:number[],segments:object[]})[]) => Shape2D} hull   convex hull of all inputs → a convex Shape2D (faceted; pure-JS monotone chain)
  * @property {(inputs: (Shape2D|number[][]|{start:number[],segments:object[]})[]) => Shape2D} hullChain   swept hull over an ordered sequence (≥2): union of hull([inᵢ,inᵢ₊₁])
- * @property {(named:{name:string,solid:Solid}[]) => Promise<ArrayBuffer>} toSTEP   OCCT only (Manifold throws KernelCapabilityError)
+ * @property {(named:{name:string,solid:Solid,color?:number|null}[]) => Promise<ArrayBuffer>} toSTEP   OCCT only (Manifold throws KernelCapabilityError); `color` is 0xRRGGBB per body, absent = the viewer's no-material colour
  * @property {(name: string) => Solid} import   imported geometry declared in the part's imports field (registered pre-build by the framework via the underscore-prefixed `_registerImport`/`_importDigest`/`_acceptsStep`/`_acceptsMesh` side-channel, not a part author's calling surface)
  * @property {(name:string) => void} [beginSubPart]   open a per-sub-part solid-cache round (both backends)
  * @property {() => void} [endSubPart]                close the cache round (always pair with beginSubPart)

package/src/framework/geometry/occt-backend.js

@@ -37,6 +37,7 @@ import { composePose, transformPositions, rotateNormals } from "./pose.js";
 import { filterBrepEdges } from "./brep-edges.js";
 import { meshToStl } from "./mesh-stl.js";
 import { heightfieldMesh, hashGridData } from "./heightfield.js";
+import { writeStep } from "./occt-step.js";
 const MESH = { preview: { tolerance: 0.1, angularTolerance: 0.25 }, print: { tolerance: 0.01, angularTolerance: 0.1 } };
 
 // Heightfield sew-time warning threshold, in triangles. Measured by the plan's
@@ -112,7 +113,7 @@ function stlBufferToShape(replicad, arrayBuffer) {
 
 export function createOcctKernel(replicad) {
   const { makeCylinder, makeBox, makeCircle, makeHelix, assembleWire, genericSweep,
-          loft, draw, exportSTEP, importSTEP, measureVolume, makeSphere, makeLine, Plane } = replicad;
+          loft, draw, importSTEP, measureVolume, makeSphere, makeLine, Plane } = replicad;
 
   // Feature-skip warnings: everything occt-repair (and roundAll) skips or rescues
   // is recorded here as well as console.warned, and jobs.js drains it per
@@ -755,7 +756,10 @@ export function createOcctKernel(replicad) {
     // region-in/region-out form directly. `_`-prefixed — not part of the public kernel
     // surface.
     _offsetRegions: offsetRegions,
-    toSTEP: (named) => exportSTEP(named.map(({ name, solid }) => ({ name, shape: solid._mat()._s }))).arrayBuffer(),
+    // Our own writer, not replicad's exportSTEP, so colours come out right (see
+    // occt-step.js). `color` per body is optional; jobs.js passes the sub-part's
+    // printColor, the same colour its .3mf object gets.
+    toSTEP: async (named) => writeStep(replicad, named.map(({ name, solid, color }) => ({ name, shape: solid._mat()._s, color }))),
     // Imported geometry, registered pre-build by the framework via `_registerImport`
     // (ensureImports, Task 8). Every call clones the master shape — replicad ops
     // consume their operands, and the master must never be handed out directly, or

package/src/framework/geometry/occt-step.js

@@ -0,0 +1,80 @@
+// STEP writer for the OCCT backend: replicad 0.23.1's `exportSTEP` (and the
+// `createAssembly` it calls), changed in how each body's colour is made and in
+// when the writer's model is made (so every file's header names AP242; below).
+//
+// replicad gets colour wrong twice. A body with no colour is painted its default
+// red, so every exported part opened red in a CAD tool. And a colour it is given
+// is built with `Quantity_ColorRGBA(r/255, g/255, b/255, a)` — a LINEAR-RGB
+// constructor — from an sRGB hex, while OCCT's STEP writer converts linear to
+// sRGB on the way out, so each colour landed lighter than asked (#3366cc was
+// written as #7caae7). Here every body gets a colour (the viewer's no-material
+// drafting colour when it has none of its own), converted sRGB → linear with
+// OCCT's own Convert_sRGB_To_LinearRGB — the exact inverse of the writer's
+// conversion — before it reaches that constructor, so a body's COLOUR_RGB is
+// the 0xRRGGBB the caller passed. (Building the colour as Quantity_TOC_sRGB
+// directly would be tidier, but this WASM build does not bind that enum.)
+//
+// Everything else — the XCAF document, naming, the writer's modes and statics,
+// the FS round trip, and which native objects are handed to GC — is replicad's
+// own, so this writes the same file replicad did apart from the colours and the
+// first file in a process, whose header replicad left saying AP214. The
+// document handle passed to Transfer is deliberately never freed: the document
+// itself is owned by its WrappingObj (as replicad's AssemblyExporter owns it),
+// and freeing the handle too would destroy it twice.
+import { NO_MATERIAL_COLOR } from "../materials/resolve.js";
+
+const isColor = (c) => Number.isInteger(c) && c >= 0 && c <= 0xffffff;
+
+// 0xRRGGBB → sRGB channels in 0..1. A missing or unusable colour falls back to
+// the no-material colour: appearance never fails an export.
+function srgbChannels(color) {
+  const c = isColor(color) ? color : NO_MATERIAL_COLOR;
+  return [(c >> 16) & 255, (c >> 8) & 255, c & 255].map((v) => v / 255);
+}
+
+// bodies: [{ name, shape (a replicad Shape), color? (0xRRGGBB) }] → ArrayBuffer.
+export function writeStep(replicad, bodies) {
+  const oc = replicad.getOC();
+  const r = replicad.GCWithScope();
+  const text = (s) => r(new oc.TCollection_ExtendedString_2(s, true));
+
+  const doc = new replicad.WrappingObj(new oc.TDocStd_Document(text("XmlOcaf")));
+  oc.XCAFDoc_ShapeTool.SetAutoNaming(false);
+  const mainLabel = r(doc.wrapped.Main());
+  const shapeTool = oc.XCAFDoc_DocumentTool.ShapeTool(mainLabel).get();
+  const colorTool = oc.XCAFDoc_DocumentTool.ColorTool(mainLabel).get();
+  for (const { name, shape, color } of bodies) {
+    const node = r(shapeTool.NewShape());
+    shapeTool.SetShape(node, shape.wrapped);
+    oc.TDataStd_Name.Set_1(node, text(name));
+    const [red, green, blue] = srgbChannels(color).map((v) => oc.Quantity_Color.Convert_sRGB_To_LinearRGB_1(v));
+    colorTool.SetColor_3(node, r(new oc.Quantity_ColorRGBA_5(red, green, blue, 1)), oc.XCAFDoc_ColorType.XCAFDoc_ColorSurf);
+  }
+  shapeTool.UpdateAssemblies();
+
+  const session = r(new oc.XSControl_WorkSession());
+  const sessionHandle = r(new oc.Handle_XSControl_WorkSession_2(session));
+  const writer = r(new oc.STEPCAFControl_Writer_2(sessionHandle, false));
+  oc.Interface_Static.SetIVal("write.surfacecurve.mode", true);
+  oc.Interface_Static.SetIVal("write.precision.mode", 0);
+  oc.Interface_Static.SetIVal("write.step.assembly", 2);
+  oc.Interface_Static.SetIVal("write.step.schema", 5);
+  // The header's FILE_SCHEMA is fixed when the writer's model is made, which
+  // constructing the writer does — before the statics above are set. They cannot
+  // go first: the process's first STEP writer is what defines them, so until then
+  // SetIVal is a silent no-op. So the first file in a process said AP214 (OCCT's
+  // default) over an AP242 body. Re-initialising with a fresh model now stamps
+  // the header with the schema the body is written in, on every export.
+  writer.Init(sessionHandle, true);
+  writer.SetColorMode(true);
+  writer.SetLayerMode(true);
+  writer.SetNameMode(true);
+  const progress = r(new oc.Message_ProgressRange_1());
+  writer.Transfer_1(new oc.Handle_TDocStd_Document_2(doc.wrapped), oc.STEPControl_StepModelType.STEPControl_AsIs, null, progress);
+
+  const filename = "partforge-export.step";
+  if (writer.Write(filename) !== oc.IFSelect_ReturnStatus.IFSelect_RetDone) throw new Error("STEP write failed");
+  const file = oc.FS.readFile(`/${filename}`);
+  oc.FS.unlink(`/${filename}`);
+  return file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength);
+}

package/src/framework/jobs.js

@@ -439,7 +439,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       if (names.length === 0) throw new Error("no exportable parts selected");
       const solids = names.map((name) => {
         onProgress(`building ${label(name)}`);
-        return { name: exportName(name), solid: posed(name, "export", onProgress) };
+        return { name: exportName(name), solid: posed(name, "export", onProgress), color: printColor(part.parts[name]?.display) };
       });
       onProgress("writing STEP file");
       const data = await kernel.toSTEP(solids);