mcp-3d-printer-server 1.2.24 → 1.2.25

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.2.25] – 2026-11-02
+
+### Fixed
+
+- `lay_flat` rests a model on a face that is its real bottom. Before, it turned the face-normal group with the largest area to face down and moved the lowest point to Z=0, without checking that those faces were the lowest. The stove gap filler from Scan to Make (six T strips) printed upside down: its cap undersides' 23,838 mm² face down but sit 12 mm above the fin tips, so it stood on its fins.
+  - A pose qualifies only when some face, turned down, lies on the rotated model's lowest plane, within 0.5% of its height and at most 0.2 mm. The candidate poses are the 64 largest face groups and the model's six axes, so a domed part can flip exactly.
+  - Among qualifying poses, `lay_flat` picks the one with the least part and support volume per mm² of bed contact. Support is the overhang more than 45° from vertical, times its height above the bed. Ties go to the larger contact, then to the face that already points down.
+  - When no pose qualifies, the model is unchanged. The text result is still the STL path, and the new `structuredContent` `{path, laid_flat, message}` says why.
+  - The gap filler now comes out cap-down, fin tips 14.4 mm up. This is checked from the output vertices only. The same rule in bambu-printer-mcp was also checked by slicing with Bambu Studio 02.08.02.61 for a P1S, which gave no warning; that slice was not repeated here.
+- `slice_stl` returns Bambu Studio's own checks on the Bambu-compatible CLI route, and OrcaSlicer's where it writes the same `result.json`. When the CLI writes `result.json` (Bambu Studio 02.08.02.61 writes it on macOS on success too), `structuredContent.slicer_result` carries it parsed and unchanged: `error_string`, `return_code` and each `sliced_plates[].warning_message`. Before, the run's output directory was deleted with `result.json` in it, and warnings such as "It seems object … has floating cantilever. Please re-orient the object or enable support generation." were lost.
+  - The text result stays the sliced file's path.
+  - A failed slice is an error result whose text starts with Studio's `error_string` (unless it reports success), then each plate's `warning_message`, then the exit code, slicer output and suggestion, with no `Error: ` prefix. Its `structuredContent` carries `slicer_result` beside the existing `slicer` details.
+  - A `result.json` reporting a nonzero `return_code` fails the slice even when the CLI exits 0.
+  - The G-code slicers (PrusaSlicer, Cura, Slic3r, generic OrcaSlicer without a Bambu preset) write no `result.json` and return `structuredContent` `{path}` only.
+  - Tested with real `result.json` files from Bambu Studio 02.08.02.61 slicing the Scan to Make stove gap filler for a P1S on macOS, replayed by a fake CLI. The optional installed-Studio test also checks `slicer_result` on macOS; CI skips it. OrcaSlicer's `result.json` follows the same libslic3r format but was not run here.
+
 ## [1.2.24] – 2026-11-02
 
 ### Fixed

package/dist/index.js

@@ -692,7 +692,7 @@ class ThreeDPrinterMCPServer {
             slicerProfile = slicerProfile.split("|", 1)[0];
         }
         const slicerPath = this.resolveExecutableSelectorArg(args.slicer_path, toolName, "slicer_path") ?? defaultSlicerPathFor(slicerType);
-        return this.stlManipulator.sliceSTL(String(args.stl_path), slicerType, slicerPath, slicerProfile, undefined, // progressCallback
+        return this.stlManipulator.sliceSTLWithResult(String(args.stl_path), slicerType, slicerPath, slicerProfile, undefined, // progressCallback
         printerPreset, filamentProfile, options, processOverrides);
     }
     setupErrorHandling() {
@@ -1723,7 +1723,7 @@ class ThreeDPrinterMCPServer {
                     },
                     {
                         name: "lay_flat",
-                        description: "Attempt to rotate the model so its largest flat face lies on the XY plane (Z=0).",
+                        description: "Rotate the model so a face rests on the bed (Z=0), choosing the orientation with the least part and support volume per mm² of bed contact. A face counts only if nothing hangs below it. Returns the new STL path; structuredContent.laid_flat is false, with the input path, when no orientation qualifies.",
                         inputSchema: {
                             type: "object",
                             properties: {
@@ -1968,14 +1968,16 @@ class ThreeDPrinterMCPServer {
                         }
                         result = await this.stlManipulator.extendBase(String(args.stl_path), Number(args.extension_inches));
                         break;
-                    case "slice_stl":
-                        result = await this.runSliceTool("slice_stl", args);
-                        break;
+                    case "slice_stl": {
+                        const sliced = await this.runSliceTool("slice_stl", args);
+                        // The text stays the sliced file's path; slicer_result is the slicer's own result.json, verbatim.
+                        return { content: [{ type: "text", text: sliced.path }], structuredContent: sliced };
+                    }
                     case "slice_with_template":
                         if (!args?.template_name || !String(args.template_name).trim()) {
                             throw new Error("Missing required parameter: template_name");
                         }
-                        result = await this.runSliceTool("slice_with_template", args);
+                        result = (await this.runSliceTool("slice_with_template", args)).path;
                         break;
                     case "list_templates":
                         result = listTemplateRegistry(typeof args?.template_dir === "string" ? args.template_dir : undefined);
@@ -2384,12 +2386,14 @@ class ThreeDPrinterMCPServer {
                         }
                         result = await this.stlManipulator.centerModel(String(args.stl_path));
                         break;
-                    case "lay_flat":
+                    case "lay_flat": {
                         if (!args?.stl_path) {
                             throw new Error("Missing required parameter: stl_path");
                         }
-                        result = await this.stlManipulator.layFlat(String(args.stl_path));
-                        break;
+                        const layFlatResult = await this.stlManipulator.layFlatWithResult(String(args.stl_path));
+                        // The text stays the STL path clients read; structuredContent says whether it was laid flat.
+                        return { content: [{ type: "text", text: layFlatResult.path }], structuredContent: layFlatResult };
+                    }
                     case "fusion_mcp_status":
                         return structured(await this.fusion.status(args ?? {}, extra.signal));
                     case "fusion_mcp_call":
@@ -2429,7 +2433,8 @@ class ThreeDPrinterMCPServer {
                     content: [
                         {
                             type: "text",
-                            text: `Error: ${errorMessage}\nSuggestion: ${structuredError.suggestion}`
+                            // A slicer failure leads with the slicer's own words.
+                            text: `${error instanceof SlicerError && error.slicerText ? "" : "Error: "}${errorMessage}\nSuggestion: ${structuredError.suggestion}`
                         }
                     ],
                     // Clients validate structuredContent against a declared outputSchema even on errors.
@@ -2523,6 +2528,7 @@ class ThreeDPrinterMCPServer {
                 message,
                 tool,
                 slicer: { phase: error.phase, ...error.details },
+                ...(error.slicerResult ? { slicer_result: error.slicerResult } : {}),
             };
         }
         if (SLICING_TOOLS.has(tool)) {

package/dist/slicer/bambu-cli.d.ts

@@ -118,9 +118,11 @@ export interface BambuCliInput {
  */
 export declare function planBambuCliInput(slicerType: BambuCliSlicerType, is3mf: boolean, options: BambuSliceOptions): BambuCliInput;
 /**
- * The CLI's own reason for a failed run: result.json in the run's fresh output
- * directory (written on Linux for handled errors), else the exit-code table.
+ * The result.json in the run's fresh output directory, parsed verbatim. Bambu
+ * Studio 02.08.02.61 writes it on macOS for successes and failures alike.
  */
+export declare function readCliResult(outputDir: string): Record<string, unknown> | undefined;
+/** The CLI's own reason for a failed run: its result.json, else the exit-code table. */
 export declare function bambuCliFailureReason(exitCode: number | null, outputDir: string): string | undefined;
 /** CLI flags for the prepared bundle and caller options (input path appended by the caller). */
 export declare function buildBambuCliArgs(bundle: BambuSettingsBundle, outputDir: string, exportName: string, options: BambuSliceOptions, input: BambuCliInput): string[];

package/dist/slicer/bambu-cli.js

@@ -530,18 +530,23 @@ const BAMBU_CLI_ERRORS = {
     [-102]: "G-code in an unprintable area",
 };
 /**
- * The CLI's own reason for a failed run: result.json in the run's fresh output
- * directory (written on Linux for handled errors), else the exit-code table.
+ * The result.json in the run's fresh output directory, parsed verbatim. Bambu
+ * Studio 02.08.02.61 writes it on macOS for successes and failures alike.
  */
-export function bambuCliFailureReason(exitCode, outputDir) {
+export function readCliResult(outputDir) {
     try {
         const result = JSON.parse(fs.readFileSync(path.join(outputDir, "result.json"), "utf8"));
-        if (typeof result?.error_string === "string" && result.error_string.trim()) {
-            return `${result.error_string.trim()}${result.return_code !== undefined ? ` [${result.return_code}]` : ""}`;
-        }
+        return result && typeof result === "object" && !Array.isArray(result) ? result : undefined;
     }
     catch {
-        // result.json is written only on Linux and only for handled errors.
+        return undefined;
+    }
+}
+/** The CLI's own reason for a failed run: its result.json, else the exit-code table. */
+export function bambuCliFailureReason(exitCode, outputDir) {
+    const result = readCliResult(outputDir);
+    if (typeof result?.error_string === "string" && result.error_string.trim()) {
+        return `${result.error_string.trim()}${result.return_code !== undefined ? ` [${result.return_code}]` : ""}`;
     }
     if (exitCode === null)
         return undefined;

package/dist/slicer/slicer-error.d.ts

@@ -15,11 +15,21 @@ export interface SlicerFailureDetails {
     stderrTail?: string;
 }
 export declare function slicerSuggestion(phase: SlicerFailurePhase, slicerType?: string): string;
+/** Bambu Studio's or OrcaSlicer's own result.json, parsed verbatim. */
+export type SlicerResult = Record<string, unknown>;
+/**
+ * The slicer's own words: its error_string when it reports a failing
+ * return_code (not "Success."), then each plate's warning_message.
+ */
+export declare function slicerResultText(result: SlicerResult): string;
 export declare class SlicerError extends Error {
+    readonly slicerResult?: SlicerResult | undefined;
     readonly phase: SlicerFailurePhase;
     readonly suggestion: string;
     readonly details: SlicerFailureDetails;
-    constructor(phase: SlicerFailurePhase, message: string, details?: SlicerFailureDetails);
+    /** The slicer's own words from `slicerResult`; the message starts with them. */
+    readonly slicerText: string;
+    constructor(phase: SlicerFailurePhase, message: string, details?: SlicerFailureDetails, slicerResult?: SlicerResult | undefined);
 }
 /** Keep the last lines of slicer output; the actionable line is usually at the end. */
 export declare function tailText(text: string, maxLines?: number, maxChars?: number): string;

package/dist/slicer/slicer-error.js

@@ -25,12 +25,26 @@ export function slicerSuggestion(phase, slicerType) {
                 "uploaded or printed.";
     }
 }
+/**
+ * The slicer's own words: its error_string when it reports a failing
+ * return_code (not "Success."), then each plate's warning_message.
+ */
+export function slicerResultText(result) {
+    const plates = Array.isArray(result.sliced_plates) ? result.sliced_plates : [];
+    return [
+        result.return_code === 0 ? undefined : result.error_string,
+        ...plates.map((plate) => plate && typeof plate === "object" ? plate.warning_message : undefined),
+    ].filter((text) => typeof text === "string" && text.trim() !== "").map((text) => text.trim()).join("\n");
+}
 export class SlicerError extends Error {
-    constructor(phase, message, details = {}) {
-        super(message);
+    constructor(phase, message, details = {}, slicerResult) {
+        const slicerText = slicerResult ? slicerResultText(slicerResult) : "";
+        super(slicerText ? `${slicerText}\n${message}` : message);
+        this.slicerResult = slicerResult;
         this.name = "SlicerError";
         this.phase = phase;
         this.details = details;
+        this.slicerText = slicerText;
         this.suggestion = slicerSuggestion(phase, details.slicerType);
     }
 }

package/dist/stl/stl-manipulator.d.ts

@@ -2,6 +2,11 @@ import * as THREE from 'three';
 import { EventEmitter } from 'events';
 import { type BambuSliceOptions } from '../slicer/bambu-cli.js';
 export type { BambuSliceOptions } from '../slicer/bambu-cli.js';
+/** A sliced file, with the slicer's own result.json when it wrote one. */
+export type SliceOutput = {
+    path: string;
+    slicer_result?: Record<string, unknown>;
+};
 /** Print-sheet slicing overrides (PRD §8.4), applied on top of the selected profile. */
 export interface ProcessOverrides {
     /** mm */
@@ -154,6 +159,12 @@ export declare class STLManipulator extends EventEmitter {
      * @returns Path to the generated G-code or sliced 3MF file
      */
     sliceSTL(stlFilePath: string, slicerType: SlicerType, slicerPath: string, slicerProfile?: string, progressCallback?: ProgressCallback, printerPreset?: string, filamentProfile?: string, bambuOptions?: BambuSliceOptions, processOverrides?: ProcessOverrides): Promise<string>;
+    /**
+     * sliceSTL with the Bambu-compatible CLI's own result.json, parsed verbatim.
+     * A failure's SlicerError carries it too, and its message starts with the
+     * slicer's error_string and plate warnings.
+     */
+    sliceSTLWithResult(stlFilePath: string, slicerType: SlicerType, slicerPath: string, slicerProfile?: string, progressCallback?: ProgressCallback, printerPreset?: string, filamentProfile?: string, bambuOptions?: BambuSliceOptions, processOverrides?: ProcessOverrides): Promise<SliceOutput>;
     /**
      * Enhanced version of confirmTemperatures with better error handling
      * @param gcodePath Path to the G-code file
@@ -193,7 +204,21 @@ export declare class STLManipulator extends EventEmitter {
      */
     centerModel(stlFilePath: string, progressCallback?: ProgressCallback): Promise<string>;
     /**
-     * Rotate the model so its largest flat face lies on the XY plane (Z=0).
+     * Rotate the model so a face rests on the bed, in the pose with the least
+     * part and support material per mm² of bed contact, then move it down to
+     * Z=0. Returns the new file's path, or the input path when no pose qualifies.
      */
     layFlat(stlFilePath: string, progressCallback?: ProgressCallback): Promise<string>;
+    /**
+     * layFlat with its outcome. A pose qualifies only when some face, turned to
+     * face down, lies on the rotated mesh's lowest plane; `laid_flat` is false
+     * and the model is unchanged when none does.
+     */
+    layFlatWithResult(stlFilePath: string, progressCallback?: ProgressCallback): Promise<LayFlatResult>;
 }
+export type LayFlatResult = {
+    /** The laid-flat STL, or the unchanged input when `laid_flat` is false. */
+    path: string;
+    laid_flat: boolean;
+    message: string;
+};

package/dist/stl/stl-manipulator.js

@@ -9,7 +9,7 @@ import { EventEmitter } from 'events';
 import * as crypto from 'crypto';
 import { detectProfilesRoot } from '../slicer/profile-flatten.js';
 import { flattenOrcaFilament } from '../slicer/filament-profiles.js';
-import { BambuCliProfilePreparer, assertSlicedProjectOutput, bambuCliFailureReason, buildBambuCliArgs, planBambuCliInput, } from '../slicer/bambu-cli.js';
+import { BambuCliProfilePreparer, assertSlicedProjectOutput, bambuCliFailureReason, readCliResult, buildBambuCliArgs, planBambuCliInput, } from '../slicer/bambu-cli.js';
 import { runSlicerProcess } from '../slicer/run-slicer.js';
 import { SlicerError, asPreparationError } from '../slicer/slicer-error.js';
 /** Orca/Bambu Studio process keys; profile JSON values are strings. */
@@ -840,6 +840,14 @@ export class STLManipulator extends EventEmitter {
      * @returns Path to the generated G-code or sliced 3MF file
      */
     async sliceSTL(stlFilePath, slicerType, slicerPath, slicerProfile, progressCallback, printerPreset, filamentProfile, bambuOptions, processOverrides) {
+        return (await this.sliceSTLWithResult(stlFilePath, slicerType, slicerPath, slicerProfile, progressCallback, printerPreset, filamentProfile, bambuOptions, processOverrides)).path;
+    }
+    /**
+     * sliceSTL with the Bambu-compatible CLI's own result.json, parsed verbatim.
+     * A failure's SlicerError carries it too, and its message starts with the
+     * slicer's error_string and plate warnings.
+     */
+    async sliceSTLWithResult(stlFilePath, slicerType, slicerPath, slicerProfile, progressCallback, printerPreset, filamentProfile, bambuOptions, processOverrides) {
         const operationId = this.generateOperationId();
         this.activeOperations.set(operationId, true);
         const bambuCli = STLManipulator.usesBambuCliPreparation(slicerType, printerPreset);
@@ -979,14 +987,31 @@ export class STLManipulator extends EventEmitter {
                 progressCallback(20, `Executing slicer: ${slicerPath} ${args.join(' ')}`);
             console.error(`Executing: ${slicerPath} ${args.join(' ')}`);
             const cliOutputDir = bambuOutputDir;
-            await runSlicerProcess({
-                command: slicerPath,
-                args,
-                timeoutMs: this.resolveSlicerTimeoutMs(),
-                slicerType,
-                isCancelled: () => !this.activeOperations.get(operationId),
-                failureReason: cliOutputDir ? (exitCode) => bambuCliFailureReason(exitCode, cliOutputDir) : undefined,
-            });
+            try {
+                await runSlicerProcess({
+                    command: slicerPath,
+                    args,
+                    timeoutMs: this.resolveSlicerTimeoutMs(),
+                    slicerType,
+                    isCancelled: () => !this.activeOperations.get(operationId),
+                    failureReason: cliOutputDir ? (exitCode) => bambuCliFailureReason(exitCode, cliOutputDir) : undefined,
+                });
+            }
+            catch (error) {
+                // Keep the CLI's own result.json before the output directory is removed.
+                const failedResult = cliOutputDir ? readCliResult(cliOutputDir) : undefined;
+                if (failedResult && error instanceof SlicerError)
+                    throw new SlicerError(error.phase, error.message, error.details, failedResult);
+                throw error;
+            }
+            const slicerResult = cliOutputDir ? readCliResult(cliOutputDir) : undefined;
+            if (cliOutputDir && !slicerResult) {
+                // Older or Linux CLIs may write result.json only for handled errors.
+                console.error(`${slicerType} wrote no result.json for this slice, so its own checks are not available.`);
+            }
+            if (typeof slicerResult?.return_code === "number" && slicerResult.return_code !== 0) {
+                throw new SlicerError('execution', `Slicer exited with code 0, but its result.json reports return_code ${slicerResult.return_code}.`, { slicerType, slicerPath, exitCode: 0 }, slicerResult);
+            }
             if (!this.activeOperations.get(operationId)) {
                 throw new SlicerError('execution', 'Slicing operation cancelled after process finished', { slicerType, slicerPath });
             }
@@ -1013,7 +1038,7 @@ export class STLManipulator extends EventEmitter {
             catch (error) {
                 if (error instanceof SlicerError)
                     throw error;
-                throw new SlicerError('output', error instanceof Error ? error.message : String(error), { slicerType, slicerPath });
+                throw new SlicerError('output', error instanceof Error ? error.message : String(error), { slicerType, slicerPath }, slicerResult);
             }
             if (progressCallback)
                 progressCallback(100, "Slicing completed successfully");
@@ -1023,7 +1048,7 @@ export class STLManipulator extends EventEmitter {
                 success: true,
                 output: outputFilePath
             });
-            return outputFilePath;
+            return slicerResult ? { path: outputFilePath, slicer_result: slicerResult } : { path: outputFilePath };
         }
         catch (error) {
             console.error(`Slicing failed for ${stlFilePath}:`, error instanceof Error ? error.message : error);
@@ -1202,9 +1227,19 @@ export class STLManipulator extends EventEmitter {
         }
     }
     /**
-     * Rotate the model so its largest flat face lies on the XY plane (Z=0).
+     * Rotate the model so a face rests on the bed, in the pose with the least
+     * part and support material per mm² of bed contact, then move it down to
+     * Z=0. Returns the new file's path, or the input path when no pose qualifies.
      */
     async layFlat(stlFilePath, progressCallback) {
+        return (await this.layFlatWithResult(stlFilePath, progressCallback)).path;
+    }
+    /**
+     * layFlat with its outcome. A pose qualifies only when some face, turned to
+     * face down, lies on the rotated mesh's lowest plane; `laid_flat` is false
+     * and the model is unchanged when none does.
+     */
+    async layFlatWithResult(stlFilePath, progressCallback) {
         const operationId = this.generateOperationId();
         this.activeOperations.set(operationId, true);
         try {
@@ -1218,91 +1253,96 @@ export class STLManipulator extends EventEmitter {
             const positionAttribute = geometry.getAttribute('position');
             if (!positionAttribute)
                 throw new Error("Geometry has no position attribute.");
-            const faces = [];
+            const faceCount = Math.floor(positionAttribute.count / 3);
+            if (faceCount === 0)
+                throw new Error("No faces found in geometry.");
+            const mesh = {
+                positions: new Float64Array(faceCount * 9),
+                normals: new Float64Array(faceCount * 3),
+                areas: new Float64Array(faceCount),
+                volume: 0,
+            };
+            const center = new THREE.Vector3();
+            boundingBox.getCenter(center);
             const vA = new THREE.Vector3();
             const vB = new THREE.Vector3();
             const vC = new THREE.Vector3();
-            const faceNormal = new THREE.Vector3();
             const cb = new THREE.Vector3(), ab = new THREE.Vector3();
-            // Iterate through faces (triangles)
-            for (let i = 0; i < positionAttribute.count; i += 3) {
-                vA.fromBufferAttribute(positionAttribute, i);
-                vB.fromBufferAttribute(positionAttribute, i + 1);
-                vC.fromBufferAttribute(positionAttribute, i + 2);
-                // Calculate face normal
+            const fromA = new THREE.Vector3(), fromB = new THREE.Vector3(), fromC = new THREE.Vector3();
+            for (let face = 0; face < faceCount; face++) {
+                vA.fromBufferAttribute(positionAttribute, face * 3);
+                vB.fromBufferAttribute(positionAttribute, face * 3 + 1);
+                vC.fromBufferAttribute(positionAttribute, face * 3 + 2);
+                vA.toArray(mesh.positions, face * 9);
+                vB.toArray(mesh.positions, face * 9 + 3);
+                vC.toArray(mesh.positions, face * 9 + 6);
+                // Signed tetrahedron volumes about the center sum to the enclosed volume.
+                fromA.subVectors(vA, center);
+                fromB.subVectors(vB, center);
+                fromC.subVectors(vC, center);
+                mesh.volume += fromA.dot(fromB.cross(fromC)) / 6;
+                // The cross product's direction is the outward normal; half its length is the area.
                 cb.subVectors(vC, vB);
                 ab.subVectors(vA, vB);
                 cb.cross(ab);
-                faceNormal.copy(cb).normalize();
-                // Calculate face area (using cross product magnitude / 2)
-                const area = cb.length() / 2;
-                faces.push({
-                    normal: faceNormal.clone(),
-                    area: area,
-                    vertices: [vA.clone(), vB.clone(), vC.clone()] // Store vertices if needed for center calculation
-                });
+                mesh.areas[face] = cb.length() / 2;
+                cb.normalize().toArray(mesh.normals, face * 3);
             }
-            if (faces.length === 0)
-                throw new Error("No faces found in geometry.");
+            mesh.volume = Math.abs(mesh.volume);
             if (!this.activeOperations.get(operationId))
                 throw new Error("Operation cancelled");
             if (progressCallback)
                 progressCallback(65, "Grouping faces by normal...");
             // Group faces by similar normal vectors (tolerance for floating point errors)
-            const normalGroups = new Map();
+            const normalGroups = [];
             const tolerance = 1e-5;
-            for (const face of faces) {
-                let foundGroup = false;
-                for (const [key, group] of normalGroups.entries()) {
-                    if (face.normal.distanceToSquared(group.representativeNormal) < tolerance) {
-                        group.totalArea += face.area;
-                        // Optional: Average the normal? For now, just use the first one.
-                        foundGroup = true;
-                        break;
-                    }
-                }
-                if (!foundGroup) {
-                    const key = `${face.normal.x.toFixed(5)},${face.normal.y.toFixed(5)},${face.normal.z.toFixed(5)}`;
-                    if (!normalGroups.has(key)) { // Ensure unique key even if floats slightly differ after toFixed
-                        normalGroups.set(key, { totalArea: face.area, representativeNormal: face.normal });
-                    }
-                }
+            const faceNormal = new THREE.Vector3();
+            for (let face = 0; face < faceCount; face++) {
+                if (!(mesh.areas[face] > 0))
+                    continue;
+                faceNormal.fromArray(mesh.normals, face * 3);
+                const group = normalGroups.find(candidate => faceNormal.distanceToSquared(candidate.representativeNormal) < tolerance);
+                if (group)
+                    group.totalArea += mesh.areas[face];
+                else
+                    normalGroups.push({ totalArea: mesh.areas[face], representativeNormal: faceNormal.clone() });
             }
-            if (normalGroups.size === 0)
-                throw new Error("Could not group faces by normal.");
             if (!this.activeOperations.get(operationId))
                 throw new Error("Operation cancelled");
             if (progressCallback)
-                progressCallback(75, "Finding largest flat surface...");
-            // Include already-horizontal faces: excluding Z-aligned normals can
-            // stand a flat model on its edge, including on a repeated layFlat call.
-            let largestArea = 0;
-            let targetNormal = null;
-            const downVector = new THREE.Vector3(0, 0, -1); // Target normal (pointing down)
-            // Faces are grouped by direction, so a part whose flat faces are all
-            // horizontal has equal up- and down-facing areas. On a tie, keep the
-            // face that already points down so a seated part is not flipped.
-            for (const group of normalGroups.values()) {
-                const tied = targetNormal !== null && Math.abs(group.totalArea - largestArea) <= largestArea * 1e-6;
-                if (tied ? group.representativeNormal.z < targetNormal.z : group.totalArea > largestArea) {
-                    largestArea = group.totalArea;
-                    targetNormal = group.representativeNormal;
-                }
+                progressCallback(75, "Finding the pose that rests on the bed...");
+            // Candidate directions to turn down: the largest face groups, plus the
+            // model's own axes so a part with a domed side can be flipped exactly.
+            const candidates = normalGroups
+                .sort((a, b) => b.totalArea - a.totalArea)
+                .slice(0, LAY_FLAT_MAX_GROUP_CANDIDATES)
+                .map(group => group.representativeNormal);
+            for (const axis of [[0, 0, -1], [0, 0, 1], [1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0]]) {
+                const normal = new THREE.Vector3(axis[0], axis[1], axis[2]);
+                if (!candidates.some(candidate => candidate.distanceToSquared(normal) < tolerance))
+                    candidates.push(normal);
             }
-            if (!targetNormal) {
-                // Only a mesh without any face area reaches this.
-                console.warn("Could not find a suitable large flat face to lay down. No changes made.");
-                this.emit('operationComplete', { operationId, type: 'layFlat', success: true, output: stlFilePath, message: "No suitable flat face found." });
-                return stlFilePath;
+            let best = null;
+            for (const normal of candidates) {
+                const pose = evaluateLayFlatPose(mesh, normal);
+                if (pose && (!best || isBetterLayFlatPose(pose, best)))
+                    best = pose;
+            }
+            if (!best) {
+                const message = "No face lies on the model's lowest plane in any candidate orientation, so the model is unchanged.";
+                console.error(`lay_flat: ${message}`);
+                this.emit('operationComplete', { operationId, type: 'layFlat', success: true, output: stlFilePath, message });
+                return { path: stlFilePath, laid_flat: false, message };
             }
             if (progressCallback)
                 progressCallback(80, "Calculating rotation...");
-            // Calculate the rotation needed to align targetNormal with downVector
-            const quaternion = new THREE.Quaternion().setFromUnitVectors(targetNormal, downVector);
-            const rotationMatrix = new THREE.Matrix4().makeRotationFromQuaternion(quaternion);
+            // Turn the chosen normal to face straight down. Turning +Z down rotates
+            // half a turn about X, which keeps the model's X layout.
+            const downVector = new THREE.Vector3(0, 0, -1);
+            const rotationMatrix = best.normal.dot(downVector) < -1 + 1e-9
+                ? new THREE.Matrix4().makeRotationX(Math.PI)
+                : new THREE.Matrix4().makeRotationFromQuaternion(new THREE.Quaternion().setFromUnitVectors(best.normal, downVector));
             // Rotate around the model's center
-            const center = new THREE.Vector3();
-            boundingBox.getCenter(center);
             const toOriginMatrix = new THREE.Matrix4().makeTranslation(-center.x, -center.y, -center.z);
             const fromOriginMatrix = new THREE.Matrix4().makeTranslation(center.x, center.y, center.z);
             // Apply rotation
@@ -1320,8 +1360,9 @@ export class STLManipulator extends EventEmitter {
             const outputFileName = path.basename(stlFilePath, '.stl') + '_flat.stl';
             const outputFilePath = this.operationOutputPath(operationId, outputFileName);
             await this.saveSTL(geometry, outputFilePath, progressCallback); // 90-100% progress
-            this.emit('operationComplete', { operationId, type: 'layFlat', success: true, output: outputFilePath });
-            return outputFilePath;
+            const message = `Rests on ${best.contactArea.toFixed(1)} mm² of bed contact; overhangs more than 45° from vertical need about ${best.supportVolume.toFixed(0)} mm³ of support.`;
+            this.emit('operationComplete', { operationId, type: 'layFlat', success: true, output: outputFilePath, message });
+            return { path: outputFilePath, laid_flat: true, message };
         }
         catch (error) {
             this.emit('operationError', { operationId, type: 'layFlat', error: error instanceof Error ? error.message : String(error) });
@@ -1332,3 +1373,62 @@ export class STLManipulator extends EventEmitter {
         }
     }
 }
+const LAY_FLAT_MAX_GROUP_CANDIDATES = 64;
+/** Faces tilted more than 45° from vertical overhang and need support. */
+const LAY_FLAT_OVERHANG_COS = Math.SQRT1_2 + 1e-6;
+/**
+ * Score turning `normal` to face the bed. The bed is the mesh's lowest plane in
+ * that pose, its support plane. Faces lying on it, within 0.5% of the model's
+ * height there (at most 0.2 mm), are bed contact. Overhanging faces above it
+ * need support up from the bed: their projected area times their height.
+ * Returns null when no face lies on the bed: turning that normal down would
+ * rest the model on an edge or a point, not a face.
+ */
+function evaluateLayFlatPose(mesh, normal) {
+    const { positions, normals, areas } = mesh;
+    const nx = normal.x, ny = normal.y, nz = normal.z;
+    // Distance along the normal grows toward the bed: the bed is at its maximum.
+    let bed = -Infinity, top = Infinity;
+    for (let index = 0; index < positions.length; index += 3) {
+        const along = positions[index] * nx + positions[index + 1] * ny + positions[index + 2] * nz;
+        if (along > bed)
+            bed = along;
+        if (along < top)
+            top = along;
+    }
+    const tolerance = Math.min(0.2, Math.max(0.005 * (bed - top), 1e-4));
+    let contactArea = 0;
+    let supportVolume = 0;
+    for (let face = 0; face < areas.length; face++) {
+        const facing = normals[face * 3] * nx + normals[face * 3 + 1] * ny + normals[face * 3 + 2] * nz;
+        if (!(facing > 0))
+            continue;
+        const base = face * 9;
+        let heightSum = 0, heightMax = 0;
+        for (let corner = base; corner < base + 9; corner += 3) {
+            const height = bed - (positions[corner] * nx + positions[corner + 1] * ny + positions[corner + 2] * nz);
+            heightSum += height;
+            if (height > heightMax)
+                heightMax = height;
+        }
+        if (heightMax <= tolerance)
+            contactArea += areas[face];
+        else if (facing > LAY_FLAT_OVERHANG_COS)
+            supportVolume += areas[face] * facing * (heightSum / 3);
+    }
+    if (!(contactArea > 0))
+        return null;
+    return { normal, contactArea, supportVolume, stackHeight: (mesh.volume + supportVolume) / contactArea };
+}
+/**
+ * Prefer the pose with the lowest stack height, then the larger contact. On a
+ * tie, keep the face that already points down so a seated part is not flipped.
+ */
+function isBetterLayFlatPose(pose, best) {
+    const same = (a, b) => Math.abs(a - b) <= 1e-9 + 1e-6 * Math.max(Math.abs(a), Math.abs(b));
+    if (!same(pose.stackHeight, best.stackHeight))
+        return pose.stackHeight < best.stackHeight;
+    if (!same(pose.contactArea, best.contactArea))
+        return pose.contactArea > best.contactArea;
+    return pose.normal.z < best.normal.z;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mcp-3d-printer-server",
     "mcpName": "io.github.DMontgomery40/mcp-3d-printer-server",
-    "version": "1.2.24",
+    "version": "1.2.25",
     "description": "MCP server for connecting Claude with 3D printer management systems",
     "main": "dist/index.js",
     "repository": "https://github.com/DMontgomery40/mcp-3D-printer-server",

package/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/DMontgomery40/mcp-3D-printer-server",
     "source": "github"
   },
-  "version": "1.2.24",
+  "version": "1.2.25",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "mcp-3d-printer-server",
-      "version": "1.2.24",
+      "version": "1.2.25",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/src/index.ts

@@ -32,7 +32,7 @@ import { createServer as createHttpServer, type IncomingMessage, type Server as
 import { randomUUID } from "node:crypto";
 import * as THREE from 'three';
 import { PrinterFactory } from "./printers/printer-factory.js";
-import { STLManipulator, type BambuSliceOptions, type ProcessOverrides } from "./stl/stl-manipulator.js";
+import { STLManipulator, type BambuSliceOptions, type ProcessOverrides, type SliceOutput } from "./stl/stl-manipulator.js";
 import { CounterpartService, type PrinterTarget } from "./counterpart/service.js";
 import {
   CAMERA_SNAPSHOT_OUTPUT_SCHEMA,
@@ -626,6 +626,8 @@ type StructuredToolError = {
   message: string;
   tool: string;
   slicer?: Record<string, unknown>;
+  /** The slicer's own result.json, verbatim. */
+  slicer_result?: Record<string, unknown>;
 };
 
 const SLICING_TOOLS = new Set(["slice_stl", "slice_with_template", "list_templates", "save_template", "get_slice_settings"]);
@@ -784,7 +786,7 @@ class ThreeDPrinterMCPServer {
   }
 
   /** Shared slice_stl / slice_with_template implementation. */
-  private async runSliceTool(toolName: string, args: Record<string, unknown> | undefined): Promise<string> {
+  private async runSliceTool(toolName: string, args: Record<string, unknown> | undefined): Promise<SliceOutput> {
     if (!args?.stl_path) {
       throw new Error("Missing required parameter: stl_path");
     }
@@ -847,7 +849,7 @@ class ThreeDPrinterMCPServer {
     const slicerPath =
       this.resolveExecutableSelectorArg(args.slicer_path, toolName, "slicer_path") ?? defaultSlicerPathFor(slicerType);
 
-    return this.stlManipulator.sliceSTL(
+    return this.stlManipulator.sliceSTLWithResult(
       String(args.stl_path),
       slicerType,
       slicerPath,
@@ -1919,7 +1921,7 @@ class ThreeDPrinterMCPServer {
           },
           {
             name: "lay_flat",
-            description: "Attempt to rotate the model so its largest flat face lies on the XY plane (Z=0).",
+            description: "Rotate the model so a face rests on the bed (Z=0), choosing the orientation with the least part and support volume per mm² of bed contact. A face counts only if nothing hangs below it. Returns the new STL path; structuredContent.laid_flat is false, with the input path, when no orientation qualifies.",
             inputSchema: {
               type: "object",
               properties: {
@@ -2197,15 +2199,17 @@ class ThreeDPrinterMCPServer {
             );
             break;
             
-          case "slice_stl":
-            result = await this.runSliceTool("slice_stl", args as Record<string, unknown> | undefined);
-            break;
+          case "slice_stl": {
+            const sliced = await this.runSliceTool("slice_stl", args as Record<string, unknown> | undefined);
+            // The text stays the sliced file's path; slicer_result is the slicer's own result.json, verbatim.
+            return { content: [{ type: "text", text: sliced.path }], structuredContent: sliced };
+          }
 
           case "slice_with_template":
             if (!args?.template_name || !String(args.template_name).trim()) {
               throw new Error("Missing required parameter: template_name");
             }
-            result = await this.runSliceTool("slice_with_template", args as Record<string, unknown> | undefined);
+            result = (await this.runSliceTool("slice_with_template", args as Record<string, unknown> | undefined)).path;
             break;
 
           case "list_templates":
@@ -2795,12 +2799,14 @@ class ThreeDPrinterMCPServer {
             result = await this.stlManipulator.centerModel(String(args.stl_path));
             break;
 
-          case "lay_flat":
+          case "lay_flat": {
             if (!args?.stl_path) {
                 throw new Error("Missing required parameter: stl_path");
             }
-            result = await this.stlManipulator.layFlat(String(args.stl_path));
-            break;
+            const layFlatResult = await this.stlManipulator.layFlatWithResult(String(args.stl_path));
+            // The text stays the STL path clients read; structuredContent says whether it was laid flat.
+            return { content: [{ type: "text", text: layFlatResult.path }], structuredContent: layFlatResult };
+          }
 
           case "fusion_mcp_status":
             return structured(await this.fusion.status(args ?? {}, extra.signal));
@@ -2861,7 +2867,8 @@ class ThreeDPrinterMCPServer {
           content: [
             {
               type: "text",
-              text: `Error: ${errorMessage}\nSuggestion: ${structuredError.suggestion}`
+              // A slicer failure leads with the slicer's own words.
+              text: `${error instanceof SlicerError && error.slicerText ? "" : "Error: "}${errorMessage}\nSuggestion: ${structuredError.suggestion}`
             }
           ],
           // Clients validate structuredContent against a declared outputSchema even on errors.
@@ -3035,6 +3042,7 @@ class ThreeDPrinterMCPServer {
         message,
         tool,
         slicer: { phase: error.phase, ...error.details },
+        ...(error.slicerResult ? { slicer_result: error.slicerResult } : {}),
       };
     }
     if (SLICING_TOOLS.has(tool)) {

package/src/slicer/bambu-cli.ts

@@ -641,17 +641,23 @@ const BAMBU_CLI_ERRORS: Record<number, string> = {
 };
 
 /**
- * The CLI's own reason for a failed run: result.json in the run's fresh output
- * directory (written on Linux for handled errors), else the exit-code table.
+ * The result.json in the run's fresh output directory, parsed verbatim. Bambu
+ * Studio 02.08.02.61 writes it on macOS for successes and failures alike.
  */
-export function bambuCliFailureReason(exitCode: number | null, outputDir: string): string | undefined {
+export function readCliResult(outputDir: string): Record<string, unknown> | undefined {
   try {
-    const result = JSON.parse(fs.readFileSync(path.join(outputDir, "result.json"), "utf8"));
-    if (typeof result?.error_string === "string" && result.error_string.trim()) {
-      return `${result.error_string.trim()}${result.return_code !== undefined ? ` [${result.return_code}]` : ""}`;
-    }
+    const result: unknown = JSON.parse(fs.readFileSync(path.join(outputDir, "result.json"), "utf8"));
+    return result && typeof result === "object" && !Array.isArray(result) ? result as Record<string, unknown> : undefined;
   } catch {
-    // result.json is written only on Linux and only for handled errors.
+    return undefined;
+  }
+}
+
+/** The CLI's own reason for a failed run: its result.json, else the exit-code table. */
+export function bambuCliFailureReason(exitCode: number | null, outputDir: string): string | undefined {
+  const result = readCliResult(outputDir);
+  if (typeof result?.error_string === "string" && result.error_string.trim()) {
+    return `${result.error_string.trim()}${result.return_code !== undefined ? ` [${result.return_code}]` : ""}`;
   }
   if (exitCode === null) return undefined;
   const code = Object.keys(BAMBU_CLI_ERRORS).map(Number).find((value) => value === exitCode || (value & 0xff) === exitCode);

package/src/slicer/slicer-error.ts

@@ -41,16 +41,35 @@ export function slicerSuggestion(phase: SlicerFailurePhase, slicerType?: string)
   }
 }
 
+/** Bambu Studio's or OrcaSlicer's own result.json, parsed verbatim. */
+export type SlicerResult = Record<string, unknown>;
+
+/**
+ * The slicer's own words: its error_string when it reports a failing
+ * return_code (not "Success."), then each plate's warning_message.
+ */
+export function slicerResultText(result: SlicerResult): string {
+  const plates = Array.isArray(result.sliced_plates) ? result.sliced_plates : [];
+  return [
+    result.return_code === 0 ? undefined : result.error_string,
+    ...plates.map((plate) => plate && typeof plate === "object" ? (plate as Record<string, unknown>).warning_message : undefined),
+  ].filter((text): text is string => typeof text === "string" && text.trim() !== "").map((text) => text.trim()).join("\n");
+}
+
 export class SlicerError extends Error {
   readonly phase: SlicerFailurePhase;
   readonly suggestion: string;
   readonly details: SlicerFailureDetails;
+  /** The slicer's own words from `slicerResult`; the message starts with them. */
+  readonly slicerText: string;
 
-  constructor(phase: SlicerFailurePhase, message: string, details: SlicerFailureDetails = {}) {
-    super(message);
+  constructor(phase: SlicerFailurePhase, message: string, details: SlicerFailureDetails = {}, readonly slicerResult?: SlicerResult) {
+    const slicerText = slicerResult ? slicerResultText(slicerResult) : "";
+    super(slicerText ? `${slicerText}\n${message}` : message);
     this.name = "SlicerError";
     this.phase = phase;
     this.details = details;
+    this.slicerText = slicerText;
     this.suggestion = slicerSuggestion(phase, details.slicerType);
   }
 }

package/src/stl/stl-manipulator.ts

@@ -13,6 +13,7 @@ import {
   BambuCliProfilePreparer,
   assertSlicedProjectOutput,
   bambuCliFailureReason,
+  readCliResult,
   buildBambuCliArgs,
   planBambuCliInput,
   type BambuCliSlicerType,
@@ -23,6 +24,9 @@ import { SlicerError, asPreparationError } from '../slicer/slicer-error.js';
 
 export type { BambuSliceOptions } from '../slicer/bambu-cli.js';
 
+/** A sliced file, with the slicer's own result.json when it wrote one. */
+export type SliceOutput = { path: string; slicer_result?: Record<string, unknown> };
+
 /** Print-sheet slicing overrides (PRD §8.4), applied on top of the selected profile. */
 export interface ProcessOverrides {
   /** mm */
@@ -1097,6 +1101,26 @@ export class STLManipulator extends EventEmitter {
     bambuOptions?: BambuSliceOptions,
     processOverrides?: ProcessOverrides
   ): Promise<string> {
+    return (await this.sliceSTLWithResult(stlFilePath, slicerType, slicerPath, slicerProfile, progressCallback,
+      printerPreset, filamentProfile, bambuOptions, processOverrides)).path;
+  }
+
+  /**
+   * sliceSTL with the Bambu-compatible CLI's own result.json, parsed verbatim.
+   * A failure's SlicerError carries it too, and its message starts with the
+   * slicer's error_string and plate warnings.
+   */
+  async sliceSTLWithResult(
+    stlFilePath: string,
+    slicerType: SlicerType,
+    slicerPath: string,
+    slicerProfile?: string,
+    progressCallback?: ProgressCallback,
+    printerPreset?: string,
+    filamentProfile?: string,
+    bambuOptions?: BambuSliceOptions,
+    processOverrides?: ProcessOverrides
+  ): Promise<SliceOutput> {
     const operationId = this.generateOperationId();
     this.activeOperations.set(operationId, true);
     const bambuCli = STLManipulator.usesBambuCliPreparation(slicerType, printerPreset);
@@ -1256,14 +1280,30 @@ export class STLManipulator extends EventEmitter {
       console.error(`Executing: ${slicerPath} ${args.join(' ')}`);
 
       const cliOutputDir = bambuOutputDir;
-      await runSlicerProcess({
-        command: slicerPath,
-        args,
-        timeoutMs: this.resolveSlicerTimeoutMs(),
-        slicerType,
-        isCancelled: () => !this.activeOperations.get(operationId),
-        failureReason: cliOutputDir ? (exitCode) => bambuCliFailureReason(exitCode, cliOutputDir) : undefined,
-      });
+      try {
+        await runSlicerProcess({
+          command: slicerPath,
+          args,
+          timeoutMs: this.resolveSlicerTimeoutMs(),
+          slicerType,
+          isCancelled: () => !this.activeOperations.get(operationId),
+          failureReason: cliOutputDir ? (exitCode) => bambuCliFailureReason(exitCode, cliOutputDir) : undefined,
+        });
+      } catch (error) {
+        // Keep the CLI's own result.json before the output directory is removed.
+        const failedResult = cliOutputDir ? readCliResult(cliOutputDir) : undefined;
+        if (failedResult && error instanceof SlicerError) throw new SlicerError(error.phase, error.message, error.details, failedResult);
+        throw error;
+      }
+      const slicerResult = cliOutputDir ? readCliResult(cliOutputDir) : undefined;
+      if (cliOutputDir && !slicerResult) {
+        // Older or Linux CLIs may write result.json only for handled errors.
+        console.error(`${slicerType} wrote no result.json for this slice, so its own checks are not available.`);
+      }
+      if (typeof slicerResult?.return_code === "number" && slicerResult.return_code !== 0) {
+        throw new SlicerError('execution', `Slicer exited with code 0, but its result.json reports return_code ${slicerResult.return_code}.`,
+          { slicerType, slicerPath, exitCode: 0 }, slicerResult);
+      }
 
       if (!this.activeOperations.get(operationId)) {
         throw new SlicerError('execution', 'Slicing operation cancelled after process finished', { slicerType, slicerPath });
@@ -1290,7 +1330,7 @@ export class STLManipulator extends EventEmitter {
         }
       } catch (error) {
         if (error instanceof SlicerError) throw error;
-        throw new SlicerError('output', error instanceof Error ? error.message : String(error), { slicerType, slicerPath });
+        throw new SlicerError('output', error instanceof Error ? error.message : String(error), { slicerType, slicerPath }, slicerResult);
       }
 
       if (progressCallback) progressCallback(100, "Slicing completed successfully");
@@ -1302,7 +1342,7 @@ export class STLManipulator extends EventEmitter {
         output: outputFilePath
       });
 
-      return outputFilePath;
+      return slicerResult ? { path: outputFilePath, slicer_result: slicerResult } : { path: outputFilePath };
     } catch (error) {
       console.error(`Slicing failed for ${stlFilePath}:`, error instanceof Error ? error.message : error);
       this.emit('operationError', {
@@ -1516,12 +1556,26 @@ export class STLManipulator extends EventEmitter {
   }
 
   /**
-   * Rotate the model so its largest flat face lies on the XY plane (Z=0).
+   * Rotate the model so a face rests on the bed, in the pose with the least
+   * part and support material per mm² of bed contact, then move it down to
+   * Z=0. Returns the new file's path, or the input path when no pose qualifies.
    */
   async layFlat(
     stlFilePath: string,
     progressCallback?: ProgressCallback
   ): Promise<string> {
+    return (await this.layFlatWithResult(stlFilePath, progressCallback)).path;
+  }
+
+  /**
+   * layFlat with its outcome. A pose qualifies only when some face, turned to
+   * face down, lies on the rotated mesh's lowest plane; `laid_flat` is false
+   * and the model is unchanged when none does.
+   */
+  async layFlatWithResult(
+    stlFilePath: string,
+    progressCallback?: ProgressCallback
+  ): Promise<LayFlatResult> {
     const operationId = this.generateOperationId();
     this.activeOperations.set(operationId, true);
 
@@ -1536,100 +1590,98 @@ export class STLManipulator extends EventEmitter {
       const positionAttribute = geometry.getAttribute('position');
       if (!positionAttribute) throw new Error("Geometry has no position attribute.");
 
-      const faces: { normal: THREE.Vector3; area: number; vertices: THREE.Vector3[] }[] = [];
+      const faceCount = Math.floor(positionAttribute.count / 3);
+      if (faceCount === 0) throw new Error("No faces found in geometry.");
+      const mesh: LayFlatMesh = {
+        positions: new Float64Array(faceCount * 9),
+        normals: new Float64Array(faceCount * 3),
+        areas: new Float64Array(faceCount),
+        volume: 0,
+      };
+      const center = new THREE.Vector3();
+      boundingBox.getCenter(center);
       const vA = new THREE.Vector3();
       const vB = new THREE.Vector3();
       const vC = new THREE.Vector3();
-      const faceNormal = new THREE.Vector3();
       const cb = new THREE.Vector3(), ab = new THREE.Vector3();
-
-      // Iterate through faces (triangles)
-      for (let i = 0; i < positionAttribute.count; i += 3) {
-          vA.fromBufferAttribute(positionAttribute, i);
-          vB.fromBufferAttribute(positionAttribute, i + 1);
-          vC.fromBufferAttribute(positionAttribute, i + 2);
-
-          // Calculate face normal
+      const fromA = new THREE.Vector3(), fromB = new THREE.Vector3(), fromC = new THREE.Vector3();
+
+      for (let face = 0; face < faceCount; face++) {
+          vA.fromBufferAttribute(positionAttribute, face * 3);
+          vB.fromBufferAttribute(positionAttribute, face * 3 + 1);
+          vC.fromBufferAttribute(positionAttribute, face * 3 + 2);
+          vA.toArray(mesh.positions, face * 9);
+          vB.toArray(mesh.positions, face * 9 + 3);
+          vC.toArray(mesh.positions, face * 9 + 6);
+          // Signed tetrahedron volumes about the center sum to the enclosed volume.
+          fromA.subVectors(vA, center);
+          fromB.subVectors(vB, center);
+          fromC.subVectors(vC, center);
+          mesh.volume += fromA.dot(fromB.cross(fromC)) / 6;
+
+          // The cross product's direction is the outward normal; half its length is the area.
           cb.subVectors(vC, vB);
           ab.subVectors(vA, vB);
           cb.cross(ab);
-          faceNormal.copy(cb).normalize();
-
-          // Calculate face area (using cross product magnitude / 2)
-          const area = cb.length() / 2;
-          
-          faces.push({
-              normal: faceNormal.clone(),
-              area: area,
-              vertices: [vA.clone(), vB.clone(), vC.clone()] // Store vertices if needed for center calculation
-          });
+          mesh.areas[face] = cb.length() / 2;
+          cb.normalize().toArray(mesh.normals, face * 3);
       }
 
-      if (faces.length === 0) throw new Error("No faces found in geometry.");
+      mesh.volume = Math.abs(mesh.volume);
 
       if (!this.activeOperations.get(operationId)) throw new Error("Operation cancelled");
       if (progressCallback) progressCallback(65, "Grouping faces by normal...");
 
       // Group faces by similar normal vectors (tolerance for floating point errors)
-      const normalGroups: Map<string, { totalArea: number; representativeNormal: THREE.Vector3 }> = new Map();
-      const tolerance = 1e-5; 
-
-      for (const face of faces) {
-          let foundGroup = false;
-          for (const [key, group] of normalGroups.entries()) {
-              if (face.normal.distanceToSquared(group.representativeNormal) < tolerance) {
-                  group.totalArea += face.area;
-                  // Optional: Average the normal? For now, just use the first one.
-                  foundGroup = true;
-                  break;
-              }
-          }
-          if (!foundGroup) {
-              const key = `${face.normal.x.toFixed(5)},${face.normal.y.toFixed(5)},${face.normal.z.toFixed(5)}`;
-              if (!normalGroups.has(key)) { // Ensure unique key even if floats slightly differ after toFixed
-                   normalGroups.set(key, { totalArea: face.area, representativeNormal: face.normal });
-              }
-          }
+      const normalGroups: { totalArea: number; representativeNormal: THREE.Vector3 }[] = [];
+      const tolerance = 1e-5;
+      const faceNormal = new THREE.Vector3();
+
+      for (let face = 0; face < faceCount; face++) {
+          if (!(mesh.areas[face] > 0)) continue;
+          faceNormal.fromArray(mesh.normals, face * 3);
+          const group = normalGroups.find(candidate => faceNormal.distanceToSquared(candidate.representativeNormal) < tolerance);
+          if (group) group.totalArea += mesh.areas[face];
+          else normalGroups.push({ totalArea: mesh.areas[face], representativeNormal: faceNormal.clone() });
       }
-      
-      if (normalGroups.size === 0) throw new Error("Could not group faces by normal.");
 
       if (!this.activeOperations.get(operationId)) throw new Error("Operation cancelled");
-      if (progressCallback) progressCallback(75, "Finding largest flat surface...");
-
-      // Include already-horizontal faces: excluding Z-aligned normals can
-      // stand a flat model on its edge, including on a repeated layFlat call.
-      let largestArea = 0;
-      let targetNormal: THREE.Vector3 | null = null;
-      const downVector = new THREE.Vector3(0, 0, -1); // Target normal (pointing down)
-
-      // Faces are grouped by direction, so a part whose flat faces are all
-      // horizontal has equal up- and down-facing areas. On a tie, keep the
-      // face that already points down so a seated part is not flipped.
-      for (const group of normalGroups.values()) {
-          const tied = targetNormal !== null && Math.abs(group.totalArea - largestArea) <= largestArea * 1e-6;
-          if (tied ? group.representativeNormal.z < targetNormal!.z : group.totalArea > largestArea) {
-              largestArea = group.totalArea;
-              targetNormal = group.representativeNormal;
-          }
+      if (progressCallback) progressCallback(75, "Finding the pose that rests on the bed...");
+
+      // Candidate directions to turn down: the largest face groups, plus the
+      // model's own axes so a part with a domed side can be flipped exactly.
+      const candidates = normalGroups
+        .sort((a, b) => b.totalArea - a.totalArea)
+        .slice(0, LAY_FLAT_MAX_GROUP_CANDIDATES)
+        .map(group => group.representativeNormal);
+      for (const axis of [[0, 0, -1], [0, 0, 1], [1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0]]) {
+          const normal = new THREE.Vector3(axis[0], axis[1], axis[2]);
+          if (!candidates.some(candidate => candidate.distanceToSquared(normal) < tolerance)) candidates.push(normal);
       }
 
-      if (!targetNormal) {
-          // Only a mesh without any face area reaches this.
-          console.warn("Could not find a suitable large flat face to lay down. No changes made.");
-          this.emit('operationComplete', { operationId, type: 'layFlat', success: true, output: stlFilePath, message: "No suitable flat face found." });
-          return stlFilePath;
+      let best: LayFlatPose | null = null;
+      for (const normal of candidates) {
+          const pose = evaluateLayFlatPose(mesh, normal);
+          if (pose && (!best || isBetterLayFlatPose(pose, best))) best = pose;
       }
-      
+
+      if (!best) {
+          const message = "No face lies on the model's lowest plane in any candidate orientation, so the model is unchanged.";
+          console.error(`lay_flat: ${message}`);
+          this.emit('operationComplete', { operationId, type: 'layFlat', success: true, output: stlFilePath, message });
+          return { path: stlFilePath, laid_flat: false, message };
+      }
+
       if (progressCallback) progressCallback(80, "Calculating rotation...");
-      
-      // Calculate the rotation needed to align targetNormal with downVector
-      const quaternion = new THREE.Quaternion().setFromUnitVectors(targetNormal, downVector);
-      const rotationMatrix = new THREE.Matrix4().makeRotationFromQuaternion(quaternion);
+
+      // Turn the chosen normal to face straight down. Turning +Z down rotates
+      // half a turn about X, which keeps the model's X layout.
+      const downVector = new THREE.Vector3(0, 0, -1);
+      const rotationMatrix = best.normal.dot(downVector) < -1 + 1e-9
+        ? new THREE.Matrix4().makeRotationX(Math.PI)
+        : new THREE.Matrix4().makeRotationFromQuaternion(new THREE.Quaternion().setFromUnitVectors(best.normal, downVector));
 
       // Rotate around the model's center
-      const center = new THREE.Vector3();
-      boundingBox.getCenter(center);
       const toOriginMatrix = new THREE.Matrix4().makeTranslation(-center.x, -center.y, -center.z);
       const fromOriginMatrix = new THREE.Matrix4().makeTranslation(center.x, center.y, center.z);
 
@@ -1652,8 +1704,9 @@ export class STLManipulator extends EventEmitter {
 
       await this.saveSTL(geometry, outputFilePath, progressCallback); // 90-100% progress
 
-      this.emit('operationComplete', { operationId, type: 'layFlat', success: true, output: outputFilePath });
-      return outputFilePath;
+      const message = `Rests on ${best.contactArea.toFixed(1)} mm² of bed contact; overhangs more than 45° from vertical need about ${best.supportVolume.toFixed(0)} mm³ of support.`;
+      this.emit('operationComplete', { operationId, type: 'layFlat', success: true, output: outputFilePath, message });
+      return { path: outputFilePath, laid_flat: true, message };
 
     } catch (error) {
       this.emit('operationError', { operationId, type: 'layFlat', error: error instanceof Error ? error.message : String(error) });
@@ -1663,3 +1716,75 @@ export class STLManipulator extends EventEmitter {
     }
   }
 }
+
+export type LayFlatResult = {
+  /** The laid-flat STL, or the unchanged input when `laid_flat` is false. */
+  path: string;
+  laid_flat: boolean;
+  message: string;
+};
+
+/** Face corners (9 per face), outward unit normals (3 per face), areas, and the enclosed volume. */
+type LayFlatMesh = { positions: Float64Array; normals: Float64Array; areas: Float64Array; volume: number };
+
+/**
+ * A direction to turn down, with the bed contact and support it gives.
+ * `stackHeight` is the part and support volume over the contact area: the mean
+ * height of material standing on each mm² of bed. Standing a long part on its
+ * end, or resting a part on a fin under a wide cap, makes it tall.
+ */
+type LayFlatPose = { normal: THREE.Vector3; contactArea: number; supportVolume: number; stackHeight: number };
+
+const LAY_FLAT_MAX_GROUP_CANDIDATES = 64;
+/** Faces tilted more than 45° from vertical overhang and need support. */
+const LAY_FLAT_OVERHANG_COS = Math.SQRT1_2 + 1e-6;
+
+/**
+ * Score turning `normal` to face the bed. The bed is the mesh's lowest plane in
+ * that pose, its support plane. Faces lying on it, within 0.5% of the model's
+ * height there (at most 0.2 mm), are bed contact. Overhanging faces above it
+ * need support up from the bed: their projected area times their height.
+ * Returns null when no face lies on the bed: turning that normal down would
+ * rest the model on an edge or a point, not a face.
+ */
+function evaluateLayFlatPose(mesh: LayFlatMesh, normal: THREE.Vector3): LayFlatPose | null {
+  const { positions, normals, areas } = mesh;
+  const nx = normal.x, ny = normal.y, nz = normal.z;
+  // Distance along the normal grows toward the bed: the bed is at its maximum.
+  let bed = -Infinity, top = Infinity;
+  for (let index = 0; index < positions.length; index += 3) {
+    const along = positions[index] * nx + positions[index + 1] * ny + positions[index + 2] * nz;
+    if (along > bed) bed = along;
+    if (along < top) top = along;
+  }
+  const tolerance = Math.min(0.2, Math.max(0.005 * (bed - top), 1e-4));
+
+  let contactArea = 0;
+  let supportVolume = 0;
+  for (let face = 0; face < areas.length; face++) {
+    const facing = normals[face * 3] * nx + normals[face * 3 + 1] * ny + normals[face * 3 + 2] * nz;
+    if (!(facing > 0)) continue;
+    const base = face * 9;
+    let heightSum = 0, heightMax = 0;
+    for (let corner = base; corner < base + 9; corner += 3) {
+      const height = bed - (positions[corner] * nx + positions[corner + 1] * ny + positions[corner + 2] * nz);
+      heightSum += height;
+      if (height > heightMax) heightMax = height;
+    }
+    if (heightMax <= tolerance) contactArea += areas[face];
+    else if (facing > LAY_FLAT_OVERHANG_COS) supportVolume += areas[face] * facing * (heightSum / 3);
+  }
+  if (!(contactArea > 0)) return null;
+  return { normal, contactArea, supportVolume, stackHeight: (mesh.volume + supportVolume) / contactArea };
+}
+
+/**
+ * Prefer the pose with the lowest stack height, then the larger contact. On a
+ * tie, keep the face that already points down so a seated part is not flipped.
+ */
+function isBetterLayFlatPose(pose: LayFlatPose, best: LayFlatPose): boolean {
+  const same = (a: number, b: number) => Math.abs(a - b) <= 1e-9 + 1e-6 * Math.max(Math.abs(a), Math.abs(b));
+  if (!same(pose.stackHeight, best.stackHeight)) return pose.stackHeight < best.stackHeight;
+  if (!same(pose.contactArea, best.contactArea)) return pose.contactArea > best.contactArea;
+  return pose.normal.z < best.normal.z;
+}