mcp-3d-printer-server 1.2.24 → 1.2.26

package/src/stl/stl-manipulator.ts

@@ -13,6 +13,7 @@ import {
   BambuCliProfilePreparer,
   assertSlicedProjectOutput,
   bambuCliFailureReason,
+  readCliResult,
   buildBambuCliArgs,
   planBambuCliInput,
   type BambuCliSlicerType,
@@ -20,9 +21,13 @@ import {
 } from '../slicer/bambu-cli.js';
 import { runSlicerProcess } from '../slicer/run-slicer.js';
 import { SlicerError, asPreparationError } from '../slicer/slicer-error.js';
+import { customGcodesWithPauses, layerTops, machinePauseGcode, pausedLayers, readPlateGcode, readProjectCustomGcodes } from '../slicer/layer-pauses.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 +1102,70 @@ 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 once = (options?: BambuSliceOptions) => this.sliceSTLOnce(stlFilePath, slicerType, slicerPath,
+      slicerProfile, progressCallback, printerPreset, filamentProfile, options, processOverrides);
+    const layers = bambuOptions?.pauseAtLayers?.length ? bambuOptions.pauseAtLayers : undefined;
+    const cli = STLManipulator.usesBambuCliPreparation(slicerType, printerPreset);
+    const plate = bambuOptions?.slicePlate && bambuOptions.slicePlate > 0 ? bambuOptions.slicePlate : 1;
+    const project = cli && /\.3mf$/i.test(stlFilePath) ? await readProjectCustomGcodes(stlFilePath, plate) : undefined;
+    if (!layers && !project?.gcodes.length) return once(bambuOptions);
+    if (layers && !cli) throw new Error(`Pausing at a layer needs the Bambu Studio or OrcaSlicer CLI, not ${slicerType}.`);
+    const customGcodesFile = path.join(this.tempDir, `custom-gcodes-${crypto.randomUUID()}.json`);
+    try {
+      let tops: number[] = [];
+      if (layers) {
+        if (progressCallback) progressCallback(10, `Finding layer heights for the pause before layer ${layers.join(", ")}`);
+        const plain = await once({ ...bambuOptions, pauseAtLayers: undefined, customGcodesFile: undefined });
+        const gcode = await readPlateGcode(plain.path, plate);
+        if (!gcode) throw new Error('The slicer wrote no plate G-code, so the pause layers cannot be placed.');
+        tops = layerTops(gcode);
+      }
+      const info = layers ? customGcodesWithPauses(tops, layers, project) : project!;
+      await fs.promises.writeFile(customGcodesFile, JSON.stringify(info));
+      const result = await once({ ...bambuOptions, customGcodesFile });
+      if (layers) {
+        const gcode = await readPlateGcode(result.path, plate);
+        const placed = gcode ? pausedLayers(gcode, machinePauseGcode(gcode)) : [];
+        const missing = layers.filter(layer => !placed.includes(layer));
+        if (!gcode || missing.length || layerTops(gcode).length !== tops.length) {
+          throw new Error(`The slicer did not place the pause before layer ${(missing.length ? missing : layers).join(", ")}. Nothing was sent to the printer.`);
+        }
+      }
+      return result;
+    } finally { await fs.promises.rm(customGcodesFile, { force: true }); }
+  }
+
+  private async sliceSTLOnce(
+    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 +1325,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 +1375,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 +1387,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 +1601,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 +1635,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 +1749,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 +1761,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;
+}

package/src/studio-print-options.ts

@@ -0,0 +1,201 @@
+/**
+ * The print options Bambu Studio's Send dialog sends, resolved the way it
+ * resolves them, so every print route sends what Bambu's own Print button
+ * would. Source: Bambu Studio v02.08.02.61 (commit 926a7192574b), the version
+ * the hidden-HMS and stage tables are pinned to:
+ *
+ * - SelectMachine.cpp:3344-3356 `set_print_config(bed_type,
+ *   bed_leveling == "on", flow_cali == "on", false, timelapse, true,
+ *   ext_change_assist, bed_leveling.getValueInt(), flow_cali.getValueInt(),
+ *   nozzle_offset_cali.getValueInt(), pa_value_switch ? 0 : 1)`. Vibration
+ *   calibration is always false and layer inspection always true; the
+ *   parameter order is PrintJob.hpp:98-116.
+ * - SelectMachine.cpp:7318-7329 `getValueInt`: off 0, on 1, auto 2.
+ * - SelectMachine.cpp:1117-1123 `update_select_layout`: update_option_opts
+ *   (which choices each option offers on this printer) runs before
+ *   load_option_vals.
+ * - SelectMachine.cpp:2993-3027 `load_option_vals`: the value saved in
+ *   BambuStudio.conf under the printer type, if the option offers it; else
+ *   "auto" if offered; else "on". Dual-nozzle printers then set nozzle offset
+ *   calibration to "auto" for a two-nozzle job and, without a filament
+ *   switcher, "off" for a one-nozzle job.
+ * - SelectMachine.cpp:2586-2615 `update_option_opts`: bed leveling offers
+ *   auto/on/off when the printer's support_bed_leveling is 2 and on/off when it
+ *   is 1; with 0 it is hidden and keeps the auto/on/off it was built with
+ *   (SelectMachine.cpp:676-691), as does flow calibration when the printer has
+ *   no PA calibration. DeviceManager.cpp:1100/4441 give P-series printers
+ *   (series_p1p: P1P, P1S) no PA calibration, so their flow calibration is
+ *   hidden and resolves to "auto". Nozzle offset calibration always offers auto.
+ * - SelectMachine.cpp:705-707: the PA value switch starts on and is not saved,
+ *   so extruder_cali_manual_mode is 0.
+ *
+ * Approximations, outside the P1P/P1S: flow calibration on other printers is
+ * shown when the printer's push status reports PA calibration (assumed here),
+ * and offers auto when support_auto_flow_calibration is true and the mapped
+ * filaments allow it (can_support_pa_auto_cali, assumed true). A filament
+ * switcher on a dual-nozzle printer is assumed absent.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type StudioOptionValue = "off" | "on" | "auto";
+type Offers = readonly StudioOptionValue[];
+const AUTO_ON_OFF: Offers = ["auto", "on", "off"];
+const ON_OFF: Offers = ["on", "off"];
+
+/**
+ * Studio's printer types (resources/printers/<type>.json at the pinned commit:
+ * model_id/printer_type, printer_series, support_bed_leveling,
+ * support_auto_flow_calibration), keyed by this server's model names.
+ */
+const STUDIO_PRINTERS: Record<string, { types: string[]; pSeries: boolean; bedLeveling: 0 | 1 | 2; autoFlow: boolean; dualNozzle: boolean }> = {
+  p1p: { types: ["C11"], pSeries: true, bedLeveling: 1, autoFlow: false, dualNozzle: false },
+  p1s: { types: ["C12"], pSeries: true, bedLeveling: 1, autoFlow: false, dualNozzle: false },
+  x1c: { types: ["3DPrinter-X1-Carbon"], pSeries: false, bedLeveling: 1, autoFlow: false, dualNozzle: false },
+  x1: { types: ["3DPrinter-X1"], pSeries: false, bedLeveling: 1, autoFlow: false, dualNozzle: false },
+  x1e: { types: ["C13"], pSeries: false, bedLeveling: 1, autoFlow: false, dualNozzle: false },
+  a1mini: { types: ["N1"], pSeries: false, bedLeveling: 1, autoFlow: false, dualNozzle: false },
+  a1: { types: ["N2S"], pSeries: false, bedLeveling: 1, autoFlow: false, dualNozzle: false },
+  p2s: { types: ["N7"], pSeries: false, bedLeveling: 2, autoFlow: true, dualNozzle: false },
+  x2d: { types: ["N6"], pSeries: false, bedLeveling: 2, autoFlow: true, dualNozzle: true },
+  h2s: { types: ["O1S"], pSeries: false, bedLeveling: 2, autoFlow: true, dualNozzle: false },
+  h2d: { types: ["O1D"], pSeries: false, bedLeveling: 2, autoFlow: true, dualNozzle: true },
+  h2dpro: { types: ["O1E"], pSeries: false, bedLeveling: 2, autoFlow: true, dualNozzle: true },
+  h2c: { types: ["O1C", "O1C2"], pSeries: false, bedLeveling: 2, autoFlow: true, dualNozzle: true },
+};
+
+export type StudioOptionSource = "caller" | "studio-config" | "studio-default";
+
+/** Explicit caller choices; each one wins over Studio's resolution. */
+export type CallerPrintOptions = {
+  bedLeveling?: boolean;
+  flowCalibration?: boolean;
+  vibrationCalibration?: boolean;
+  layerInspect?: boolean;
+  /** 0 off, 1 on, 2 auto, as Studio's getValueInt. */
+  autoBedLeveling?: number;
+  autoFlowCali?: number;
+  autoOffsetCali?: number;
+  extruderCaliManualMode?: number;
+};
+
+export type StudioPrintOptions = {
+  printerType?: string;
+  values: { bed_leveling: StudioOptionValue; flow_cali: StudioOptionValue; nozzle_offset_cali: StudioOptionValue };
+  sources: { bed_leveling: StudioOptionSource; flow_cali: StudioOptionSource; nozzle_offset_cali: StudioOptionSource };
+  task_bed_leveling: boolean;
+  task_flow_cali: boolean;
+  task_vibration_cali: boolean;
+  task_layer_inspect: boolean;
+  auto_bed_leveling: number;
+  auto_flow_cali: number;
+  auto_offset_cali: number;
+  extruder_cali_manual_mode: number;
+};
+
+/** Where Studio keeps BambuStudio.conf; BAMBU_STUDIO_CONFIG overrides it (empty: none). */
+export function studioConfigPath(): string | undefined {
+  const override = process.env.BAMBU_STUDIO_CONFIG;
+  if (override !== undefined) return override.trim() || undefined;
+  if (process.platform === "darwin") return path.join(os.homedir(), "Library", "Application Support", "BambuStudio", "BambuStudio.conf");
+  if (process.platform === "win32") return process.env.APPDATA ? path.join(process.env.APPDATA, "BambuStudio", "BambuStudio.conf") : undefined;
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "BambuStudio", "BambuStudio.conf");
+}
+
+/**
+ * The Send dialog options Studio saved for a printer type, and nothing else:
+ * BambuStudio.conf also holds access codes, so only that one section is kept,
+ * and a parse failure is reported without any of the file's text.
+ */
+export function readStudioSavedOptions(printerTypes: string[], configPath: string | undefined): Record<string, string> | undefined {
+  if (!configPath) return undefined;
+  let text: string;
+  try {
+    const stat = fs.statSync(configPath);
+    if (!stat.isFile() || stat.size > 16 * 1024 * 1024) return undefined;
+    text = fs.readFileSync(configPath, "utf8");
+  } catch { return undefined; }
+  let config: unknown;
+  // Studio appends "# MD5 checksum <hex>" after the JSON.
+  try { config = JSON.parse(text.split("\n").filter(line => !line.trimStart().startsWith("#")).join("\n")); }
+  catch { return undefined; }
+  if (!config || typeof config !== "object") return undefined;
+  for (const type of printerTypes) {
+    const section = (config as Record<string, unknown>)[type];
+    if (!section || typeof section !== "object" || Array.isArray(section)) continue;
+    const saved: Record<string, string> = {};
+    for (const key of ["bed_leveling", "flow_cali", "nozzle_offset_cali", "timelapse"]) {
+      const value = (section as Record<string, unknown>)[key];
+      if (typeof value === "string") saved[key] = value;
+    }
+    return saved;
+  }
+  return undefined;
+}
+
+function fromInt(value: number, label: string): StudioOptionValue {
+  if (value === 0) return "off";
+  if (value === 1) return "on";
+  if (value === 2) return "auto";
+  throw new Error(`${label} must be 0 (off), 1 (on) or 2 (auto).`);
+}
+
+const toInt = (value: StudioOptionValue) => value === "off" ? 0 : value === "on" ? 1 : 2;
+
+/** load_option_vals for one option: saved if offered, else auto if offered, else on. */
+function loaded(saved: string | undefined, offers: Offers): { value: StudioOptionValue; source: StudioOptionSource } {
+  if (saved !== undefined && (offers as readonly string[]).includes(saved)) return { value: saved as StudioOptionValue, source: "studio-config" };
+  return { value: offers.includes("auto") ? "auto" : "on", source: "studio-default" };
+}
+
+/**
+ * What Studio's Send dialog would send for this model, with the caller's
+ * explicit choices taking precedence. usedNozzles is the number of nozzles the
+ * job uses, for dual-nozzle printers.
+ */
+export function resolveStudioPrintOptions(model: string, caller: CallerPrintOptions = {}, options: { usedNozzles?: number; configPath?: string } = {}): StudioPrintOptions {
+  const printer = STUDIO_PRINTERS[model];
+  const saved = printer ? readStudioSavedOptions(printer.types, "configPath" in options ? options.configPath : studioConfigPath()) ?? {} : {};
+  const printerType = printer?.types[0];
+
+  const bedOffers = !printer || printer.bedLeveling !== 1 ? AUTO_ON_OFF : ON_OFF;
+  const flowOffers = !printer || printer.pSeries || printer.autoFlow ? AUTO_ON_OFF : ON_OFF;
+  const bed = loaded(saved.bed_leveling, bedOffers);
+  const flow = loaded(saved.flow_cali, flowOffers);
+  let offset = loaded(saved.nozzle_offset_cali, AUTO_ON_OFF);
+  if (printer?.dualNozzle && options.usedNozzles !== undefined) {
+    if (options.usedNozzles >= 2) offset = { value: "auto", source: "studio-default" };
+    else if (options.usedNozzles === 1) offset = { value: "off", source: "studio-default" };
+  }
+
+  const choose = (current: { value: StudioOptionValue; source: StudioOptionSource }, auto: number | undefined, flag: boolean | undefined, label: string) =>
+    auto !== undefined ? { value: fromInt(auto, label), source: "caller" as const }
+      : flag !== undefined ? { value: flag ? "on" as const : "off" as const, source: "caller" as const }
+        : current;
+  const bedLeveling = choose(bed, caller.autoBedLeveling, caller.bedLeveling, "auto_bed_leveling");
+  const flowCali = choose(flow, caller.autoFlowCali, caller.flowCalibration, "auto_flow_cali");
+  const nozzleOffset = choose(offset, caller.autoOffsetCali, undefined, "auto_offset_cali");
+  const manualMode = caller.extruderCaliManualMode ?? 0;
+  if (!Number.isInteger(manualMode) || manualMode < -1 || manualMode > 1) throw new Error("extruder_cali_manual_mode must be -1, 0 or 1.");
+
+  return {
+    ...(printerType ? { printerType } : {}),
+    values: { bed_leveling: bedLeveling.value, flow_cali: flowCali.value, nozzle_offset_cali: nozzleOffset.value },
+    sources: { bed_leveling: bedLeveling.source, flow_cali: flowCali.source, nozzle_offset_cali: nozzleOffset.source },
+    task_bed_leveling: bedLeveling.value === "on",
+    task_flow_cali: flowCali.value === "on",
+    task_vibration_cali: caller.vibrationCalibration ?? false,
+    task_layer_inspect: caller.layerInspect ?? true,
+    auto_bed_leveling: toInt(bedLeveling.value),
+    auto_flow_cali: toInt(flowCali.value),
+    auto_offset_cali: toInt(nozzleOffset.value),
+    extruder_cali_manual_mode: manualMode,
+  };
+}
+
+/** The number of nozzles a job's used filaments print from, when the inspection knows. */
+export function usedNozzleCount(inspection: { usedFilamentPositions: number[]; filamentNozzleIndices?: Array<number | undefined> }): number | undefined {
+  const nozzles = inspection.usedFilamentPositions.map(position => inspection.filamentNozzleIndices?.[position]).filter((value): value is number => Number.isInteger(value));
+  return nozzles.length === inspection.usedFilamentPositions.length && nozzles.length ? new Set(nozzles).size : undefined;
+}