brep-io-kernel 1.0.0

package/src/tests/test_sweepFace.js

@@ -0,0 +1,55 @@
+export async function test_SweepFace(partHistory) {
+    const cone = await partHistory.newFeature("P.CO");
+    cone.inputParams.radiusTop = 3;
+    cone.inputParams.radiusBottom = .5;
+    cone.inputParams.height = 5.2;
+    cone.inputParams.resolution = 20;
+
+    // Build a simple sketch with a straight path edge of length 5 along +Z.
+    // We place the sketch on an XZ plane so the line from (0,0)→(0,5) maps to +Z in world.
+    const plane = await partHistory.newFeature("P");
+    plane.inputParams.orientation = "YZ";
+
+    const sketch = await partHistory.newFeature("S");
+    sketch.inputParams.sketchPlane = plane.inputParams.featureID;
+    // Define a minimal sketch: one path line (id:100) and a tiny closed loop so edges get added to the scene.
+    sketch.persistentData.sketch = {
+        points: [
+            { id: 0, x: 0, y: 0, fixed: true },   // ground
+            { id: 1, x: 8, y: 20, fixed: false },  // path end (+Z since XZ plane)
+            // tiny square to ensure a profile face is created (so edges are added to scene)
+            { id: 10, x: -0.5, y: -0.5, fixed: false },
+            { id: 11, x:  0.5, y: -0.5, fixed: false },
+            { id: 12, x:  0.5, y:  0.5, fixed: false },
+            { id: 13, x: -0.5, y:  0.5, fixed: false },
+        ],
+        geometries: [
+            // Path edge geometry (name will be G100)
+            { id: 100, type: "line", points: [0, 1], construction: false },
+            // Closed loop (small square) so the sketch emits edges and a face group
+            { id: 200, type: "line", points: [10, 11], construction: false },
+            { id: 201, type: "line", points: [11, 12], construction: false },
+            { id: 202, type: "line", points: [12, 13], construction: false },
+            { id: 203, type: "line", points: [13, 10], construction: false },
+        ],
+        constraints: [
+            { id: 0, type: "⏚", points: [0] }, // ground point 0
+        ],
+    };
+
+    // Create the path-based Sweep from the cone's top face, following the sketch edge G100.
+    const sweep = await partHistory.newFeature("SW");
+    sweep.inputParams.profile = `${cone.inputParams.featureID}_T`;
+    sweep.inputParams.path = [`${sketch.inputParams.featureID}:G100`]; // resolve to the sketch edge created above
+    sweep.inputParams.orientationMode = "translate"; // default, but make explicit
+
+    // perform a boolean operation between the 2 solids.
+    const boolean = await partHistory.newFeature("B");
+    boolean.inputParams.targetSolid = cone.inputParams.featureID;
+    boolean.inputParams.boolean = {
+        targets: [sweep.inputParams.featureID],
+        operation: "UNION",
+    };
+
+    return partHistory;
+}

package/src/tests/test_tube.js

@@ -0,0 +1,45 @@
+export async function test_tube(partHistory) {
+    const plane = await partHistory.newFeature("P");
+    plane.inputParams.orientation = "XY";
+
+    const sketch = await partHistory.newFeature("S");
+    sketch.inputParams.sketchPlane = plane.inputParams.featureID;
+    sketch.persistentData.sketch = {
+        points: [
+            { id: 0, x: 0, y: 0, fixed: true },
+            { id: 1, x: 0, y: 40, fixed: false },
+            { id: 2, x: 25, y: 40, fixed: false },
+            { id: 10, x: -2, y: -2, fixed: false },
+            { id: 11, x: 2, y: -2, fixed: false },
+            { id: 12, x: 2, y: 2, fixed: false },
+            { id: 13, x: -2, y: 2, fixed: false },
+        ],
+        geometries: [
+            { id: 200, type: "line", points: [0, 1], construction: false },
+            { id: 201, type: "line", points: [1, 2], construction: false },
+            { id: 300, type: "line", points: [10, 11], construction: false },
+            { id: 301, type: "line", points: [11, 12], construction: false },
+            { id: 302, type: "line", points: [12, 13], construction: false },
+            { id: 303, type: "line", points: [13, 10], construction: false },
+        ],
+        constraints: [
+            { id: 0, type: "⏚", points: [0] },
+        ],
+    };
+
+    const edgePrefix = `${sketch.inputParams.featureID}:`;
+
+    const solidTube = await partHistory.newFeature("TU");
+    solidTube.inputParams.path = [`${edgePrefix}G200`, `${edgePrefix}G201`];
+    solidTube.inputParams.radius = 4;
+    solidTube.inputParams.innerRadius = 0;
+    solidTube.inputParams.resolution = 32;
+
+    const hollowTube = await partHistory.newFeature("TU");
+    hollowTube.inputParams.path = [`${edgePrefix}G200`, `${edgePrefix}G201`];
+    hollowTube.inputParams.radius = 5;
+    hollowTube.inputParams.innerRadius = 2;
+    hollowTube.inputParams.resolution = 48;
+
+    return partHistory;
+}

package/src/tests/test_tube_closedLoop.js

@@ -0,0 +1,67 @@
+export async function test_tube_closedLoop(partHistory) {
+    const plane = await partHistory.newFeature("P");
+    plane.inputParams.orientation = "XY";
+
+    const sketch = await partHistory.newFeature("S");
+    sketch.inputParams.sketchPlane = plane.inputParams.featureID;
+    
+    // Create a closed loop path (hexagon)
+    const numSides = 6;
+    const radius = 20;
+    const points = [];
+    const geometries = [];
+    
+    // Generate hexagon points
+    for (let i = 0; i < numSides; i++) {
+        const angle = (i / numSides) * 2 * Math.PI;
+        points.push({
+            id: i,
+            x: Math.cos(angle) * radius,
+            y: Math.sin(angle) * radius,
+            fixed: false
+        });
+    }
+    
+    // Create line segments between consecutive points
+    for (let i = 0; i < numSides; i++) {
+        const nextI = (i + 1) % numSides;
+        geometries.push({
+            id: 200 + i,
+            type: "line",
+            points: [i, nextI],
+            construction: false
+        });
+    }
+
+    sketch.persistentData.sketch = {
+        points: points,
+        geometries: geometries,
+        constraints: [
+            { id: 0, type: "⏚", points: [0] }, // Fix the first point
+        ],
+    };
+
+    const edgePrefix = `${sketch.inputParams.featureID}:`;
+
+    // Create a solid tube with the closed loop path
+    const solidTube = await partHistory.newFeature("TU");
+    solidTube.inputParams.path = geometries.map(g => `${edgePrefix}G${g.id}`);
+    solidTube.inputParams.radius = 3;
+    solidTube.inputParams.innerRadius = 0;
+    solidTube.inputParams.resolution = 24;
+
+    // Create a hollow tube with the closed loop path
+    const hollowTube = await partHistory.newFeature("TU");
+    hollowTube.inputParams.path = geometries.map(g => `${edgePrefix}G${g.id}`);
+    hollowTube.inputParams.radius = 4;
+    hollowTube.inputParams.innerRadius = 1;
+    hollowTube.inputParams.resolution = 24;
+    // Offset the hollow tube vertically so we can see both
+    hollowTube.inputParams.transform = {
+        position: [0, 0, 10],
+        rotation: [0, 0, 0],
+        scale: [1, 1, 1]
+    };
+
+    return partHistory;
+}

package/src/tests/tests.js

@@ -0,0 +1,493 @@
+import { posix as path } from '../path.proxy.js';
+import { fs } from '../fs.proxy.js';
+import { PartHistory } from "../PartHistory.js";
+import { test_primitiveCube } from './test_primitiveCube.js';
+import { test_solidMetrics, afterRun_solidMetrics } from './test_solidMetrics.js';
+import { test_primitiveCylinder } from './test_primitiveCylinder.js';
+import { test_plane } from './test_plane.js';
+import { test_primitiveCone } from './test_primitiveCone.js';
+import { test_primitiveTorus } from './test_primitiveTorus.js';
+import { test_boolean_subtract } from './test_boolean_subtract.js';
+import { test_primitiveSphere } from './test_primitiveSphere.js';
+import { test_primitivePyramid } from './test_primitivePyramid.js';
+import { test_stlLoader } from './test_stlLoader.js';
+import { test_SweepFace } from './test_sweepFace.js';
+import { test_ExtrudeFace } from './test_extrudeFace.js';
+import { test_Fillet } from './test_fillet.js';
+import { test_Chamfer } from './test_chamfer.js';
+import { test_mirror } from './test_mirror.js';
+import { test_fillets_more_dificult } from './test_filletsMoreDifficult.js';
+import { test_tube } from './test_tube.js';
+import { test_tube_closedLoop } from './test_tube_closedLoop.js';
+import { test_offsetShellGrouping } from './test_offsetShellGrouping.js';
+import { test_sheetMetal_tab, test_sheetMetal_flange, test_sheetMetal_hem, test_sheetMetal_cutout } from './test_sheetMetal_features.js';
+import {
+    test_SheetMetalContourFlange_Basic,
+    test_SheetMetalContourFlange_StraightLine,
+    afterRun_SheetMetalContourFlange_Basic,
+    afterRun_SheetMetalContourFlange_StraightLine,
+} from './test_sheetMetalContourFlange.js';
+import { test_pushFace, afterRun_pushFace } from './test_pushFace.js';
+import { test_sketch_openLoop, afterRun_sketch_openLoop } from './test_sketch_openLoop.js';
+import { test_Fillet_NonClosed, afterRun_Fillet_NonClosed } from './test_fillet_nonClosed.js';
+import { test_history_features_basic, afterRun_history_features_basic } from './test_history_features_basic.js';
+import { generate3MF } from '../exporters/threeMF.js';
+import { buildSheetMetalFlatPatternSvgs } from '../exporters/sheetMetalFlatPattern.js';
+import {
+    test_hole_through,
+    afterRun_hole_through,
+    test_hole_thread_symbolic,
+    afterRun_hole_thread_symbolic,
+    test_hole_thread_modeled,
+    afterRun_hole_thread_modeled,
+    test_hole_countersink,
+    afterRun_hole_countersink,
+    test_hole_counterbore,
+    afterRun_hole_counterbore,
+} from './test_hole.js';
+
+const IS_NODE_RUNTIME = typeof process !== 'undefined' && process.versions && process.versions.node && typeof window === 'undefined';
+const TEST_LOG_PATH = path.join('tests', 'test-run.log');
+
+
+export const testFunctions = [
+    { test: test_plane, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_primitiveCube, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_primitivePyramid, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_primitiveCylinder, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_primitiveCone, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_primitiveTorus, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_primitiveSphere, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_boolean_subtract, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_stlLoader, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_SweepFace, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_tube, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_tube_closedLoop, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_sketch_openLoop, afterRun: afterRun_sketch_openLoop, printArtifacts: false, exportFaces: false, exportSolids: false, resetHistory: true },
+    { test: test_offsetShellGrouping, printArtifacts: false, exportFaces: false, exportSolids: false, resetHistory: true },
+    { test: test_sheetMetal_tab, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_sheetMetal_flange, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_sheetMetal_hem, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_sheetMetal_cutout, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_SheetMetalContourFlange_Basic, afterRun: afterRun_SheetMetalContourFlange_Basic, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_SheetMetalContourFlange_StraightLine, afterRun: afterRun_SheetMetalContourFlange_StraightLine, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_ExtrudeFace, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_Fillet, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_Fillet_NonClosed, afterRun: afterRun_Fillet_NonClosed, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_fillets_more_dificult, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_Chamfer, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_hole_through, afterRun: afterRun_hole_through, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_hole_countersink, afterRun: afterRun_hole_countersink, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_hole_counterbore, afterRun: afterRun_hole_counterbore, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_hole_thread_symbolic, afterRun: afterRun_hole_thread_symbolic, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_hole_thread_modeled, afterRun: afterRun_hole_thread_modeled, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_pushFace, afterRun: afterRun_pushFace, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_mirror, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_history_features_basic, afterRun: afterRun_history_features_basic, printArtifacts: false, exportFaces: true, exportSolids: true, resetHistory: true },
+    { test: test_solidMetrics, afterRun: afterRun_solidMetrics, printArtifacts: true, exportFaces: true, exportSolids: true, resetHistory: true },
+
+];
+
+// Dynamically register tests to import part files from src/tests/partFiles (Node only)
+async function registerPartFileTests() {
+    if (!(typeof process !== 'undefined' && process.versions && process.versions.node)) return;
+    try {
+        const partsDir = 'src/tests/partFiles';
+        // Use async API to avoid ESM sync-fs readiness issues
+        try {
+            const entries = await fs.promises.readdir(partsDir);
+            const files = entries.filter(f => typeof f === 'string' && f.toLowerCase().endsWith('.json'));
+            for (const file of files) {
+                const filePath = path.join(partsDir, file);
+                const baseName = String(file).replace(/\.[^.]+$/, '');
+                const safeName = baseName.replace(/[^a-zA-Z0-9._-]+/g, '_').substring(0, 100);
+                const testName = `import_part_${safeName}`;
+                const isSheetMetalHem = file.toLowerCase() === 'sheetmetalhem.brep.json';
+
+                const importTest = async function (partHistory) {
+                    // Read file and load into PartHistory
+                    const content = await fs.promises.readFile(filePath, 'utf8');
+                    let payload = content;
+                    try {
+                        const obj = JSON.parse(content);
+                        if (obj && typeof obj === 'object') {
+                            if (Array.isArray(obj.features)) {
+                                payload = JSON.stringify(obj);
+                            } else if (obj.data) {
+                                payload = (typeof obj.data === 'string') ? obj.data : JSON.stringify(obj.data);
+                            }
+                        }
+                    } catch (_) {
+                        // invalid JSON; let runSingleTest catch and report when fromJSON or runHistory runs
+                    }
+                    await partHistory.reset();
+                    await partHistory.fromJSON(payload);
+                    // runHistory will be called by runSingleTest()
+                };
+                try { Object.defineProperty(importTest, 'name', { value: testName, configurable: true }); } catch {}
+
+                const afterRun = isSheetMetalHem ? async function (partHistory) {
+                    const solids = (partHistory.scene?.children || []).filter(o => o && o.type === 'SOLID' && typeof o.getMesh === 'function');
+                    const svgEntries = buildSheetMetalFlatPatternSvgs(solids, {
+                        metadataManager: partHistory?.metadataManager || null,
+                    });
+                    if (!svgEntries.length) {
+                        console.warn(`[runTests] No flat pattern SVG produced for ${testName}`);
+                        return;
+                    }
+                    const exportPath = `./tests/results/${testName}/`;
+                    for (const entry of svgEntries) {
+                        const safeEntryName = sanitizeFileName(entry.name || 'SHEET');
+                        const outPath = path.join(exportPath, `${safeEntryName}_flat-pattern.svg`);
+                        writeFile(outPath, entry.svg);
+                    }
+                } : null;
+
+                testFunctions.push({
+                    test: importTest,
+                    afterRun,
+                    printArtifacts: false,
+                    exportFaces: true,
+                    exportSolids: true,
+                    resetHistory: true,
+                    allowErrors: true,
+                    _sourceFile: filePath,
+                });
+            }
+        } catch (e) {
+            // Directory may not exist; ignore silently in CI
+        }
+    } catch (e) {
+        console.warn('Failed to register part file import tests:', e?.message || e);
+    }
+}
+
+
+
+// call runTests automatically when executed under Node.js
+if (IS_NODE_RUNTIME) {
+    runTests()
+        .then(() => {
+            // ensure CLI exits promptly once the suite finishes
+            process.exit(0);
+        })
+        .catch((err) => {
+            console.error(err);
+            process.exit(1);
+        });
+}
+
+
+
+
+export async function runTests(partHistory = new PartHistory(), callbackToRunBetweenTests = null) {
+    if (typeof process !== "undefined" && process.versions && process.versions.node) {
+        //await console.clear();
+    }
+
+    if (IS_NODE_RUNTIME) {
+        resetTestLog();
+        logTestEvent('Test run started');
+    }
+
+    // delete the ./tests/results directory in an asynchronous way
+    await fs.promises.rm('./tests/results', { recursive: true, force: true });
+
+    // Discover and register part-file import tests (Node only)
+    await registerPartFileTests();
+
+    for (const testFunction of testFunctions) {
+        const isLastTest = testFunction === testFunctions[testFunctions.length - 1];
+        await partHistory.reset();
+
+        if (testFunction.resetHistory) partHistory.features = [];
+
+        const testName = (testFunction?.test?.name && String(testFunction.test.name)) || 'unnamed_test';
+        if (IS_NODE_RUNTIME) logTestEvent(`Starting ${testName}`);
+
+        let handledError = null;
+        try {
+            handledError = await runSingleTest(testFunction, partHistory);
+        } catch (err) {
+            if (IS_NODE_RUNTIME) logTestEvent(`Test ${testName} failed: ${stringifyError(err)}`);
+            throw err;
+        }
+
+        if (IS_NODE_RUNTIME) {
+            if (handledError) logTestEvent(`Test ${testName} completed with handled error: ${stringifyError(handledError)}`);
+            else logTestEvent(`Test ${testName} completed successfully`);
+        }
+
+        if (typeof window !== "undefined") {
+            if (typeof callbackToRunBetweenTests === 'function') {
+                await callbackToRunBetweenTests(partHistory, isLastTest);
+            }
+        } else {
+            // run each test and export the results to a folder ./tests/results/<testFunction name>/
+            const exportName = testFunction.test.name;
+            const exportPath = `./tests/results/${exportName}/`;
+            // create the directory if it does not exist
+            if (!fs.existsSync(exportPath)) {
+                fs.mkdirSync(exportPath, { recursive: true });
+            }
+
+            // Collect SOLID nodes from the scene
+            const solids = (partHistory.scene?.children || []).filter(o => o && o.type === 'SOLID' && typeof o.toSTL === 'function');
+
+            // Export solids (triggered by either flag for convenience)
+            if (testFunction.exportSolids || testFunction.printArtifacts) {
+                solids.forEach((solid, idx) => {
+                    const rawName = solid.name && String(solid.name).trim().length ? String(solid.name) : `solid_${idx}`;
+                    const safeName = sanitizeFileName(rawName);
+                    let stl = "";
+                    try {
+                        stl = solid.toSTL(safeName, 6);
+                    } catch (e) {
+                        console.warn(`[runTests] toSTL failed for solid ${rawName}:`, e?.message || e);
+                        return;
+                    }
+                    const outPath = path.join(exportPath, `${safeName}.stl`);
+                    writeFile(outPath, stl);
+                });
+            }
+
+            // Export faces per solid
+            if (testFunction.exportFaces) {
+                solids.forEach((solid, sidx) => {
+                    const rawName = solid.name && String(solid.name).trim().length ? String(solid.name) : `solid_${sidx}`;
+                    const safeSolid = sanitizeFileName(rawName);
+                    let faces = [];
+                    try {
+                        faces = typeof solid.getFaces === 'function' ? solid.getFaces(false) : [];
+                    } catch {
+                        faces = [];
+                    }
+                    faces.forEach(({ faceName, triangles }, fIdx) => {
+                        if (!triangles || triangles.length === 0) return;
+                        const rawFace = faceName || `face_${fIdx}`;
+                        const safeFace = sanitizeFileName(rawFace);
+                        const stl = trianglesToAsciiSTL(`${safeSolid}_${safeFace}`, triangles);
+                        const outPath = path.join(exportPath, `${safeSolid}_${safeFace}.stl`);
+                        writeFile(outPath, stl);
+                    });
+                });
+            }
+
+            // Export 3MF with embedded feature history
+            await export3mfArtifact({
+                partHistory,
+                exportName,
+                exportPath,
+                solids,
+            });
+
+        }
+    }
+
+    if (IS_NODE_RUNTIME) logTestEvent('Test run finished');
+}
+
+
+
+
+
+
+
+
+
+
+export async function runSingleTest(testFunction, partHistory = new PartHistory()) {
+    let error = null;
+    try {
+        await testFunction.test(partHistory);
+        await partHistory.runHistory();
+        // Optional per-test post-run hook for validations/metrics
+        if (typeof testFunction.afterRun === 'function') {
+            try { await testFunction.afterRun(partHistory); } catch (e) { console.warn('afterRun failed:', e?.message || e); }
+        }
+    } catch (e) {
+        error = e;
+        if (testFunction.allowErrors) {
+            const name = (testFunction.test && testFunction.test.name) ? testFunction.test.name : 'unnamed_test';
+            const exportPath = `./tests/results/${name}/`;
+            try { if (!fs.existsSync(exportPath)) fs.mkdirSync(exportPath, { recursive: true }); } catch {}
+            const msg = `${e?.message || e}\n\n${e?.stack || ''}`;
+            try { writeFile(path.join(exportPath, 'error.txt'), msg); } catch {}
+            console.error(`Error in test ${name}:`, e);
+        } else {
+            // rethrow to fail fast for normal tests
+            throw e;
+        }
+    }
+    // sleep for 1 second to allow any async operations to complete
+    await new Promise(resolve => setTimeout(resolve, 1000));
+
+    return error;
+}
+
+
+// function to write a file. If the path dose not exist it should make the folders needed.  
+function writeFile(filePath, content) {
+    // imediatly return if running in the browser
+    if (typeof window !== "undefined") {
+        //console.warn(`writeFile is not supported in the browser.`);
+        return;
+    }
+
+    try {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, content, 'utf8');
+    } catch (error) {
+        console.log(`Error writing file ${filePath}:`, error);
+    }
+}
+
+function writeBinaryFile(filePath, content) {
+    if (typeof window !== "undefined") {
+        return;
+    }
+    try {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, content);
+    } catch (error) {
+        console.log(`Error writing file ${filePath}:`, error);
+    }
+}
+
+function appendToFile(filePath, content) {
+    if (!IS_NODE_RUNTIME) return;
+    try {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.appendFileSync(filePath, content, 'utf8');
+    } catch (error) {
+        console.log(`Error appending file ${filePath}:`, error);
+    }
+}
+
+function resetTestLog() {
+    if (!IS_NODE_RUNTIME) return;
+    writeFile(TEST_LOG_PATH, '');
+}
+
+function logTestEvent(message) {
+    if (!IS_NODE_RUNTIME) return;
+    const timestamp = new Date().toISOString();
+    appendToFile(TEST_LOG_PATH, `[${timestamp}] ${message}\n`);
+}
+
+function stringifyError(err) {
+    if (!err) return 'Unknown error';
+    if (typeof err === 'string') return err;
+    const message = err?.message || err?.toString?.() || 'Unknown error';
+    return err?.stack ? `${message}\n${err.stack}` : message;
+}
+
+// ---------------- Local helpers for artifact export (Node only) ----------------
+
+function sanitizeFileName(name) {
+    return String(name)
+        .replace(/[^a-zA-Z0-9._-]+/g, '_')      // collapse invalid chars
+        .replace(/^_+|_+$/g, '')                 // trim leading/trailing underscores
+        .substring(0, 100) || 'artifact';        // cap length
+}
+
+function trianglesToAsciiSTL(name, tris) {
+    const fmt = (n) => Number.isFinite(n) ? (Math.abs(n) < 1e-18 ? '0' : n.toFixed(6)) : '0';
+    const out = [];
+    out.push(`solid ${name}`);
+    for (let i = 0; i < tris.length; i++) {
+        const t = tris[i];
+        const p0 = t.p1, p1 = t.p2, p2 = t.p3;
+        const ux = p1[0] - p0[0], uy = p1[1] - p0[1], uz = p1[2] - p0[2];
+        const vx = p2[0] - p0[0], vy = p2[1] - p0[1], vz = p2[2] - p0[2];
+        let nx = uy * vz - uz * vy;
+        let ny = uz * vx - ux * vz;
+        let nz = ux * vy - uy * vx;
+        const len = Math.hypot(nx, ny, nz) || 1;
+        nx /= len; ny /= len; nz /= len;
+        out.push(`  facet normal ${fmt(nx)} ${fmt(ny)} ${fmt(nz)}`);
+        out.push(`    outer loop`);
+        out.push(`      vertex ${fmt(p0[0])} ${fmt(p0[1])} ${fmt(p0[2])}`);
+        out.push(`      vertex ${fmt(p1[0])} ${fmt(p1[1])} ${fmt(p1[2])}`);
+        out.push(`      vertex ${fmt(p2[0])} ${fmt(p2[1])} ${fmt(p2[2])}`);
+        out.push(`    endloop`);
+        out.push(`  endfacet`);
+    }
+    out.push(`endsolid ${name}`);
+    return out.join('\n');
+}
+
+async function export3mfArtifact({ partHistory, exportName, exportPath, solids }) {
+    let historyJson = null;
+    try {
+        const json = await partHistory?.toJSON?.();
+        if (json) historyJson = (typeof json === 'string') ? json : JSON.stringify(json);
+    } catch (e) {
+        console.warn(`[runTests] Failed to serialize feature history for ${exportName}:`, e?.message || e);
+    }
+
+    const additionalFiles = historyJson ? { 'Metadata/featureHistory.json': historyJson } : undefined;
+    const modelMetadata = historyJson ? { featureHistoryPath: '/Metadata/featureHistory.json' } : undefined;
+    const metadataManager = partHistory?.metadataManager || null;
+
+    const solidsForExport = [];
+    (solids || []).forEach((s, idx) => {
+        try {
+            const mesh = s?.getMesh?.();
+            const canExport = !!(mesh && mesh.vertProperties && mesh.triVerts);
+            if (mesh && typeof mesh.delete === 'function') {
+                try { mesh.delete(); } catch { }
+            }
+            if (canExport) {
+                solidsForExport.push(s);
+            } else {
+                const name = sanitizeFileName(s?.name || `solid_${idx}`);
+                console.warn(`[runTests] Skipping non-manifold solid for 3MF: ${name}`);
+            }
+        } catch {
+            const name = sanitizeFileName(s?.name || `solid_${idx}`);
+            console.warn(`[runTests] Skipping solid that failed to export for 3MF: ${name}`);
+        }
+    });
+
+    const safeName = sanitizeFileName(exportName || 'partHistory');
+    const outPath = path.join(exportPath, `${safeName}.3mf`);
+    try {
+        let data = null;
+        try {
+            data = await generate3MF(solidsForExport, {
+                unit: 'millimeter',
+                precision: 6,
+                scale: 1,
+                additionalFiles,
+                modelMetadata,
+                metadataManager,
+            });
+        } catch (e) {
+            data = await generate3MF([], {
+                unit: 'millimeter',
+                precision: 6,
+                scale: 1,
+                additionalFiles,
+                modelMetadata,
+                metadataManager,
+            });
+        }
+        if (data && data.length) {
+            writeBinaryFile(outPath, data);
+        } else {
+            console.warn(`[runTests] 3MF export returned empty payload for ${exportName}`);
+        }
+    } catch (e) {
+        console.warn(`[runTests] 3MF export failed for ${exportName}:`, e?.message || e);
+    }
+}