mcp-3d-printer-server 1.2.25 → 1.2.27

package/dist/safety/printer-state.js

@@ -1,22 +1,11 @@
-import { normalizeMaterial, normalizeModel } from "./limits.js";
-let sequence = 0;
-/**
- * Publish one MQTT command with a string sequence id and no ACK wait.
- * Unpatched bambu-node 3.22.21 command classes send numeric sequence ids;
- * bambu-printer-mcp patches them to strings for H2-series firmware. This
- * server does not install that patch, so safety-relevant commands are
- * published here with the patched wire shape: {category:{sequence_id,command,...}}.
- */
-export function publishBambuCommand(printer, category, command, extra = {}) {
-    sequence = (sequence + 1) % 1000000000;
-    return printer.publish({ [category]: { sequence_id: String(sequence), command, ...extra } });
-}
+import { HIDDEN_HMS } from "./hidden-hms.js";
+import { isDualNozzleModel, normalizeMaterial, normalizeModel } from "./limits.js";
 const MAX_REPORT_AGE_MS = 15000;
 const MODEL_IDS = {
     O1C: "H2C", O1C2: "H2C", O1D: "H2D", O1E: "H2D Pro", O1S: "H2S", N6: "X2D",
     N2S: "A1", A1M: "A1 Mini", C11: "P1P", C12: "P1S", C13: "X1E", "BL-P001": "X1C", "BL-P002": "X1",
 };
-const SERIAL_MODELS = {
+export const SERIAL_MODELS = {
     "093": "H2S", "094": "H2D", "31B": "H2C", "239": "H2D Pro", "20P": "X2D",
     "00M": "X1C", "00W": "X1", "03W": "X1E", "01S": "P1P", "01P": "P1S", "22E": "P2S", "039": "A1", "030": "A1 Mini",
 };
@@ -115,17 +104,40 @@ export function readFreshPrinterStatus(printer, serial, timeoutMs = 5000) {
         printer.on("rawMessage", onRaw);
         printer.on("client:disconnect", onDisconnect);
         printer.on("client:error", onError);
-        // Publish only; an ACK wait would add a dependency that H2 firmware lacks.
+        // invoke() publishes only; executeCommand() would add an ACK dependency that H2 firmware lacks.
+        // String sequence ids without bambu-printer-mcp's bambu-node patch (H2-series firmware needs them).
         void Promise.all([publishBambuCommand(printer, "pushing", "pushall"), publishBambuCommand(printer, "info", "get_version")])
             .then(() => { requestsPublished = true; maybeResolve(); }, fail);
     });
 }
-function finiteNumber(value) {
+export function finiteNumber(value) {
     if (typeof value !== "number" && (typeof value !== "string" || !value.trim()))
         return undefined;
     const number = Number(value);
     return Number.isFinite(number) ? number : undefined;
 }
+/**
+ * X2D retains FAILED after a canceled job even with no active print error.
+ * Bambu Studio classifies FAILED as a finished job; its v02.08.02.61
+ * hms_en_20P table (926a7192574bcb9b3a732e1ec59a46d79cb45466)
+ * calls 0300400C "The task was canceled."
+ * Only this observed terminal condition qualifies, never an arbitrary failure.
+ * Callers still validate HMS, identity, hardware and material configuration,
+ * and print dispatch rechecks the identity of the observed job.
+ */
+export function isCancelledX2DJob(raw, model) {
+    return normalizeModel(model) === "x2d" && raw.gcode_state === "FAILED" &&
+        finiteNumber(raw.print_error) === 0 && finiteNumber(raw.fail_reason) === 0x0300400c &&
+        [raw.gcode_file, raw.subtask_name].some(value => typeof value === "string" && value.trim().length > 0);
+}
+/** Bambu Studio 2.8.2.61 marks FAILED as finished. Limit P1S recovery to
+ * a named prior job explicitly reporting idle, no print error and no HMS.
+ * Dispatch rechecks the observed job identity. */
+export function isFinishedP1SJob(raw, model) {
+    return normalizeModel(model) === "p1s" && raw.gcode_state === "FAILED" && raw.print_type === "idle" &&
+        finiteNumber(raw.print_error) === 0 && Array.isArray(raw.hms) && raw.hms.length === 0 &&
+        [raw.gcode_file, raw.subtask_name].some(value => typeof value === "string" && value.trim().length > 0);
+}
 const token = (value) => typeof value === "string" ? value.trim().toLowerCase().replace(/[\s_-]/g, "") : "";
 function nozzleTypeAndFlow(value) {
     const text = String(value ?? "");
@@ -159,7 +171,7 @@ export function unchippedNozzles(raw) {
         const index = finiteNumber(entry?.id);
         const stat = finiteNumber(entry?.stat);
         return index !== undefined && Number.isInteger(index) && index >= 0 && index < 16 &&
-            stat !== undefined && Number.isInteger(stat) && stat >= 0 && unreliableWithoutChip(entry, stat) ? [index] : [];
+            stat !== undefined && Number.isInteger(stat) && unreliableWithoutChip(entry, stat) ? [index] : [];
     });
 }
 const loggedUnchippedNozzles = new Set();
@@ -234,28 +246,107 @@ function reportedNozzles(raw) {
     }
     return output;
 }
-function validateErrors(raw, requireIdle) {
+const hiddenHmsSets = new Map(Object.entries(HIDDEN_HMS).map(([prefix, codes]) => [prefix, new Set(codes)]));
+export function hmsCode(entry) {
+    const code = finiteNumber(entry?.code);
+    const attr = finiteNumber(entry?.attr);
+    const valid = (value) => value !== undefined && Number.isInteger(value) && value >= 0 && value <= 0xffffffff;
+    if (!valid(code) || !valid(attr))
+        return undefined;
+    // BambuStudio DevHMS.cpp: code >> 16; DevHMS.h: 1=fatal,2=serious,3=common,4=info.
+    return { attr, code, severity: Math.floor(code / 65536), hex: (attr.toString(16).padStart(8, "0") + code.toString(16).padStart(8, "0")).toUpperCase() };
+}
+const hmsLabel = (hex) => `HMS ${hex.slice(0, 4)}-${hex.slice(4, 8)}-${hex.slice(8, 12)}-${hex.slice(12)}`;
+const hmsKey = (entry) => `hms:${entry.attr}:${entry.code}`;
+/** The one key format for a reported entry, shared by the gate and clear_hms_errors. */
+export function reportedHmsKey(entry) {
+    const parsed = hmsCode(entry);
+    return parsed ? hmsKey(parsed) : `hms:${entry?.attr}:${entry?.code}`;
+}
+/** Bambu's display form of a cleared-code key such as "hms:83887616:131184"; other keys unchanged. */
+export function describeHmsKey(key) {
+    const match = /^hms:(\d+):(\d+)$/.exec(key);
+    const entry = match ? hmsCode({ attr: Number(match[1]), code: Number(match[2]) }) : undefined;
+    return entry ? hmsLabel(entry.hex) : key;
+}
+/**
+ * A serious or common entry that Bambu lists for this serial prefix with empty
+ * text: Bambu Studio, Bambu Handy and the printer screen never show it, and
+ * the printer keeps printing with it (an X2D raises 0500-0600-0002-0070 at
+ * every boot). Bambu Studio selects the table by serial prefix, so this does
+ * too, but only when that prefix belongs to the verified model: a sparse report
+ * without a serial must not let a misconfigured serial pick another model's
+ * table. Fatal, invalid-level and unlisted entries never qualify.
+ */
+export function isHiddenNotice(serial, model, entry) {
+    if (entry.severity !== 2 && entry.severity !== 3)
+        return false;
+    const prefix = serial.trim().toUpperCase().slice(0, 3);
+    const normalized = normalizeModel(model);
+    if (!normalized || normalizeModel(SERIAL_MODELS[prefix] ?? "") !== normalized)
+        return false;
+    return hiddenHmsSets.get(prefix)?.has(entry.hex) === true;
+}
+function hiddenHmsEntries(raw, serial, model) {
+    if (!object(raw))
+        return [];
+    const identity = observedIdentity(raw, serial);
+    if (!identity.observedSerial || identity.model !== normalizeModel(model))
+        return [];
+    const entries = Array.isArray(raw.hms) ? raw.hms : [];
+    const seen = new Set();
+    return entries.map(hmsCode).filter((entry) => !!entry && isHiddenNotice(identity.observedSerial, model, entry) && !seen.has(entry.hex) && !!seen.add(entry.hex));
+}
+/** Labels of reported entries that pass only because Bambu hides them for this printer. */
+export function hiddenHmsNotices(raw, serial, model) {
+    return hiddenHmsEntries(raw, serial, model).map(entry => hmsLabel(entry.hex));
+}
+/** Cleared-code keys of reported hidden entries; clearing never removes them, so they are not re-acknowledged. */
+export function hiddenHmsKeys(raw, serial, model) {
+    return hiddenHmsEntries(raw, serial, model).map(hmsKey);
+}
+const loggedHiddenNotices = new Set();
+/** Name each hidden entry a check passed once per printer on stderr, so headless runs still record it. */
+function logHiddenNotices(raw, serial, model) {
+    for (const entry of hiddenHmsEntries(raw, serial, model)) {
+        const key = `${serial}:${entry.hex}`;
+        if (loggedHiddenNotices.has(key))
+            continue;
+        loggedHiddenNotices.add(key);
+        console.error(`Printer ${serial} reports ${hmsLabel(entry.hex)}, which Bambu lists for it without text and never shows as a fault; it does not block operations.`);
+    }
+}
+/**
+ * 0300_8013, "Printing was paused by the user" / "paused due to the pause command added to the
+ * printing file": the printer's report of a deliberate pause (a Pause, or a pause_at_layers stop),
+ * which Resume clears. A paused P1S reports it as print_error, so it is not an error for resuming
+ * a paused job. requireIdle is false only for Resume here; starting a job still needs no error.
+ * Ported from bambu-printer-mcp src/safety/printer-state.ts.
+ */
+export const PAUSE_NOTICE = 0x03008013;
+export function isPauseNotice(raw, requireIdle) {
+    const state = typeof raw?.gcode_state === "string" ? raw.gcode_state.toUpperCase() : "";
+    return !requireIdle && state === "PAUSE" && finiteNumber(raw?.print_error) === PAUSE_NOTICE;
+}
+function validateErrors(raw, requireIdle, serial, model) {
     const state = typeof raw.gcode_state === "string" ? raw.gcode_state.toUpperCase() : "UNKNOWN";
-    if (requireIdle && !["IDLE", "FINISH"].includes(state))
+    const terminal = isCancelledX2DJob(raw, model) || isFinishedP1SJob(raw, model);
+    if (requireIdle && !["IDLE", "FINISH"].includes(state) && !terminal)
         throw new Error(`Printer state ${state} is not safely idle.`);
-    if (!requireIdle && !["IDLE", "FINISH", "RUNNING", "PAUSE"].includes(state))
+    if (!requireIdle && !["IDLE", "FINISH", "RUNNING", "PAUSE"].includes(state) && !terminal)
         throw new Error(`Printer state ${state} is unknown or failed.`);
-    if (finiteNumber(raw.print_error) !== 0)
+    if (finiteNumber(raw.print_error) !== 0 && !isPauseNotice(raw, requireIdle))
         throw new Error("Printer reports a print error or did not report its error state.");
     if (!Array.isArray(raw.hms))
         throw new Error("Printer HMS error state is missing or malformed.");
-    for (const entry of raw.hms) {
-        const code = finiteNumber(entry?.code);
-        const attr = finiteNumber(entry?.attr);
-        // BambuStudio DevHMS.cpp: code >> 16; DevHMS.h: 1=fatal,2=serious,3=common,4=info.
+    for (const reported of raw.hms) {
+        const entry = hmsCode(reported);
         // Unknown severities fail closed; attr identifies the module and is not a severity bitmask.
-        if (code === undefined || attr === undefined || !Number.isInteger(code) || !Number.isInteger(attr) || code < 0 || code > 0xffffffff || attr < 0 || attr > 0xffffffff || Math.floor(code / 65536) !== 4) {
-            const hex = (value) => value.toString(16).toUpperCase().padStart(8, "0");
-            const label = code !== undefined && attr !== undefined && Number.isInteger(code) && Number.isInteger(attr) && code >= 0 && attr >= 0
-                ? ` (HMS ${hex(attr).slice(0, 4)}-${hex(attr).slice(4)}-${hex(code).slice(0, 4)}-${hex(code).slice(4)})` : "";
-            throw new Error(`Printer reports actionable or unknown HMS errors${label}; inspect and resolve them on the printer before proceeding.`);
-        }
+        if (entry && (entry.severity === 4 || isHiddenNotice(serial, model, entry)))
+            continue;
+        throw new Error(`Printer reports actionable or unknown HMS errors${entry ? ` (${hmsLabel(entry.hex)})` : ""}; inspect and resolve them before proceeding.`);
     }
+    logHiddenNotices(raw, serial, model);
 }
 function trayRange(value, label) {
     if (value === undefined || value === null || value === "" || value === "0" || value === 0)
@@ -265,15 +356,24 @@ function trayRange(value, label) {
         throw new Error(`Reported filament ${label} temperature is malformed.`);
     return number;
 }
-function externalTray(raw) {
+/** Dual-nozzle printers report one virtual external slot per nozzle, numbered as Bambu
+ * Studio does (VIRTUAL_TRAY_MAIN_ID 255 = right/main nozzle, VIRTUAL_TRAY_DEPUTY_ID 254 =
+ * left/deputy nozzle), so the requested tray selects its slot. Single-nozzle printers keep
+ * requiring exactly one slot 254 report, then the legacy vt_tray field. */
+function externalTray(raw, trayIndex, model) {
     const slots = raw.vir_slot;
+    const dualNozzle = isDualNozzleModel(model);
     if (Array.isArray(slots)) {
-        const selected = slots.filter((slot) => Number(slot?.id) === 254);
-        if (slots.length === 1 && selected.length === 1)
+        const selected = slots.filter((slot) => Number(slot?.id) === trayIndex);
+        if (selected.length === 1 && (dualNozzle || slots.length === 1))
             return selected[0];
+        if (dualNozzle && selected.length === 0 && slots.length > 0)
+            throw new Error(`External spool ${trayIndex} is not in the fresh per-nozzle report; cannot verify the selected material.`);
         if (slots.length > 0)
             throw new Error("External spool report is ambiguous for this nozzle; cannot verify the selected material.");
     }
+    if (dualNozzle)
+        throw new Error(`Dual-nozzle external spool ${trayIndex} requires a fresh per-nozzle vir_slot report; legacy vt_tray cannot verify the selected nozzle.`);
     return object(raw.vt_tray) ? raw.vt_tray : undefined;
 }
 function mappedTray(raw, index) {
@@ -315,7 +415,7 @@ export function validatePrinterState(status, requirements) {
     const model = normalizeModel(requirements.model);
     if (!model || !identity.model || model !== identity.model)
         throw new Error(`Printer model identity mismatch: requested ${requirements.model}, observed ${identity.model ?? "unknown"}.`);
-    validateErrors(raw, requirements.requireIdle !== false);
+    validateErrors(raw, requirements.requireIdle !== false, identity.observedSerial ?? "", model);
     if (requirements.requireLoadedFilament && (raw.ams?.tray_now !== undefined || Array.isArray(raw.ams?.ams))) {
         const current = finiteNumber(raw.ams?.tray_now);
         if (current === 255)
@@ -328,7 +428,7 @@ export function validatePrinterState(status, requirements) {
         }
     }
     const nozzles = requirements.nozzleDiameters.length ? reportedNozzles(raw) : [];
-    if (requirements.nozzleDiameters.length && ["h2d", "h2dpro", "h2c", "x2d"].includes(model) &&
+    if (requirements.nozzleDiameters.length && isDualNozzleModel(model) &&
         !Array.isArray(raw.device?.nozzle?.info) && !Array.isArray(raw.nozzle_diameter)) {
         throw new Error("A scalar legacy nozzle report is ambiguous for this multi-nozzle printer; fresh per-nozzle configuration is required.");
     }
@@ -357,16 +457,33 @@ export function validatePrinterState(status, requirements) {
     if (requirements.verifyMaterials !== false && (requirements.materials !== undefined || requirements.nozzleDiameters.length)) {
         const materials = requirements.materials ?? [];
         const positions = requirements.usedFilamentPositions ?? materials.map((_, index) => index);
+        // 255 is the right/main nozzle external spool only on dual-nozzle printers.
+        const dualNozzle = isDualNozzleModel(model);
+        const maxTray = dualNozzle ? 255 : 254;
         if (!positions.length)
             throw new Error("A declared material is required for each used filament or external spool.");
         for (const position of positions) {
             const material = normalizeMaterial(materials[position]);
             if (!Number.isInteger(position) || position < 0 || !material)
                 throw new Error(`A known declared material is required for filament position ${position}.`);
-            const trayIndex = requirements.useAMS ? requirements.amsMapping?.[position] : 254;
-            if (trayIndex === undefined || !Number.isInteger(trayIndex) || trayIndex < 0 || trayIndex > 254)
+            const physicalNozzle = requirements.filamentNozzleIndices?.[position];
+            const externalForNozzle = physicalNozzle === 0 ? 255 : physicalNozzle === 1 ? 254 : undefined;
+            const trayIndex = requirements.useAMS || requirements.amsMapping !== undefined
+                ? requirements.amsMapping?.[position] : dualNozzle ? externalForNozzle : 254;
+            if (!requirements.useAMS && dualNozzle && requirements.amsMapping === undefined && externalForNozzle === undefined) {
+                throw new Error(`External spool for filament position ${position} is ambiguous; re-slice with complete filament_map and physical_extruder_map nozzle bindings or provide a verified sliced plate.`);
+            }
+            if (trayIndex === undefined || !Number.isInteger(trayIndex) || trayIndex < 0 || trayIndex > maxTray)
                 throw new Error(`Complete AMS mapping is required for filament position ${position}.`);
-            const tray = trayIndex === 254 ? externalTray(raw) : mappedTray(raw, trayIndex);
+            if (!requirements.useAMS && trayIndex < 254)
+                throw new Error("External-spool printing requires an external spool mapping; AMS trays require use_ams:true.");
+            if (dualNozzle && trayIndex >= 254) {
+                if (externalForNozzle === undefined)
+                    throw new Error(`External spool ${trayIndex} needs a verified physical nozzle binding for filament position ${position}; re-slice with complete filament_map and physical_extruder_map metadata.`);
+                if (trayIndex !== externalForNozzle)
+                    throw new Error(`External spool ${trayIndex} does not feed physical nozzle ${physicalNozzle} for filament position ${position}; use spool ${externalForNozzle}.`);
+            }
+            const tray = trayIndex >= 254 ? externalTray(raw, trayIndex, model) : mappedTray(raw, trayIndex);
             const reportedType = typeof tray?.tray_type === "string" ? tray.tray_type.trim() : "";
             if (reportedType && normalizeMaterial(reportedType) !== material)
                 throw new Error(`Reported material ${reportedType} in slot ${trayIndex} contradicts declared ${materials[position]}.`);
@@ -389,7 +506,7 @@ export function manualHeatingRequirements(status, model, nozzleDiameter, materia
     const raw = status?.raw;
     if (!object(raw))
         throw new Error("A fresh printer report is required for manual nozzle heating.");
-    if (["h2d", "h2dpro", "h2c", "x2d"].includes(normalized) || reportedNozzles(raw).some(nozzle => nozzle.index !== 0)) {
+    if (isDualNozzleModel(normalized) || reportedNozzles(raw).some(nozzle => nozzle.index !== 0)) {
         throw new Error("Manual heating cannot verify the active nozzle and loaded material on this multi-nozzle printer. Use a checked sliced print instead.");
     }
     const requirements = {
@@ -410,3 +527,33 @@ export function manualHeatingRequirements(status, model, nozzleDiameter, materia
     }
     return requirements;
 }
+const EXTERNAL_STORAGE_STATES = ["none", "normal", "abnormal", "readonly"];
+/**
+ * The SD card or USB stick state, read as Bambu Studio does: the `sdcard`
+ * flag, then `home_flag` bits 8-9, then on firmware that reports cfg/fun/aux/stat
+ * the `aux` bits 12-13, each later source overriding the earlier one
+ * (DevStorage.cpp, DeviceManager.cpp parse_home_flag and parse_new_info).
+ */
+export function externalStorageState(raw) {
+    if (!object(raw))
+        return "none";
+    let state = raw.sdcard === true ? "normal" : "none";
+    if (Number.isInteger(raw.home_flag))
+        state = EXTERNAL_STORAGE_STATES[(raw.home_flag >> 8) & 3];
+    if (["cfg", "fun", "aux", "stat"].every(key => key in raw) && typeof raw.aux === "string" && /^[0-9a-f]+$/i.test(raw.aux)) {
+        state = EXTERNAL_STORAGE_STATES[Number((BigInt(`0x${raw.aux}`) >> 12n) & 3n)];
+    }
+    return state;
+}
+let sequence = 0;
+/**
+ * Publish one MQTT command with a string sequence id and no ACK wait.
+ * Unpatched bambu-node 3.22.21 command classes send numeric sequence ids;
+ * bambu-printer-mcp patches them to strings for H2-series firmware. This
+ * server does not install that patch, so safety-relevant commands are
+ * published here with the patched wire shape: {category:{sequence_id,command,...}}.
+ */
+export function publishBambuCommand(printer, category, command, extra = {}) {
+    sequence = (sequence + 1) % 1000000000;
+    return printer.publish({ [category]: { sequence_id: String(sequence), command, ...extra } });
+}

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

@@ -35,6 +35,8 @@ export interface BambuSliceOptions {
     minSave?: boolean;
     skipModifiedGcodes?: boolean;
     slicePlate?: number;
+    pauseAtLayers?: number[];
+    customGcodesFile?: string;
     /** Process keys written over the resolved process preset (layer_height, wall_loops, sparse_infill_density). */
     processOverrides?: Record<string, string>;
 }

package/dist/slicer/bambu-cli.js

@@ -489,6 +489,9 @@ const PROFILE_METADATA_KEYS = new Set([
  */
 export function planBambuCliInput(slicerType, is3mf, options) {
     const input = { slicerType, is3mf, meshTransformed: false };
+    if (!is3mf && options.repetitions !== undefined && options.cloneObjects) {
+        throw new Error("Use either repetitions or clone_objects for an STL, not both.");
+    }
     if (slicerType === "bambustudio")
         return input;
     const tilts = !!options.rotateX || !!options.rotateY;
@@ -499,9 +502,6 @@ export function planBambuCliInput(slicerType, is3mf, options) {
         }
         return input;
     }
-    if (options.repetitions !== undefined && options.cloneObjects) {
-        throw new Error("Use either repetitions or clone_objects for an STL with OrcaSlicer, not both.");
-    }
     return { ...input, meshTransformed: options.scale !== undefined || tilts };
 }
 /**
@@ -581,8 +581,8 @@ export function buildBambuCliArgs(bundle, outputDir, exportName, options, input)
     if (options.arrange !== undefined)
         args.push("--arrange", options.arrange ? "1" : "0");
     if (options.repetitions !== undefined) {
-        // OrcaSlicer rejects --repetitions for one STL; it copies the loaded model with --clone-objects.
-        if (input.slicerType !== "bambustudio" && !input.is3mf)
+        // Both Bambu Studio and OrcaSlicer copy standalone STL objects with --clone-objects.
+        if (!input.is3mf)
             args.push("--clone-objects", String(options.repetitions));
         else
             args.push("--repetitions", String(options.repetitions));
@@ -607,6 +607,8 @@ export function buildBambuCliArgs(bundle, outputDir, exportName, options, input)
     }
     if (options.loadFilamentIds)
         args.push("--load-filament-ids", options.loadFilamentIds);
+    if (options.customGcodesFile)
+        args.push("--load-custom-gcodes", path.resolve(options.customGcodesFile));
     return args;
 }
 /**

package/dist/slicer/layer-pauses.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pause-at-layer for Bambu-compatible slicer CLIs ("Add pause" in Bambu Studio
+ * and OrcaSlicer). The slicer writes the machine's own machine_pause_gcode
+ * (M400 U1 on Bambu printers) before the chosen layer, so the printer pauses
+ * by itself there and waits for Resume; no remote command is involved.
+ *
+ * The CLI takes these as --load-custom-gcodes <json> (CustomGCode::Info). It
+ * does not apply the pauses a project 3MF already carries in
+ * Metadata/custom_gcode_per_print_z.xml, so those are read here and passed the
+ * same way. A pause's print_z must be the exact top of its layer: a height
+ * between layers lands on the layer below.
+ */
+/** CustomGCode::Type, in the order bbs_3mf.cpp writes it as an integer. */
+declare const CUSTOM_GCODE_TYPES: readonly ["ColorChange", "PausePrint", "ToolChange", "Template", "Custom", "Unknown"];
+export type CustomGcodeType = (typeof CUSTOM_GCODE_TYPES)[number];
+export interface CustomGcodeItem {
+    type: CustomGcodeType;
+    print_z: number;
+    color: string;
+    extruder: number;
+    extra: string;
+}
+export interface CustomGcodeInfo {
+    mode: string;
+    gcodes: CustomGcodeItem[];
+}
+/** 1-based layer numbers, as Bambu Studio's and OrcaSlicer's preview slider count them. */
+export declare function parsePauseLayers(value: unknown): number[] | undefined;
+/**
+ * The custom G-codes (pauses, colour changes, ...) a project 3MF stores for
+ * one plate (1-based), as Bambu Studio and OrcaSlicer save them.
+ */
+export declare function readProjectCustomGcodes(threeMfPath: string, plate?: number): Promise<CustomGcodeInfo | undefined>;
+/** The plate's G-code text inside a sliced 3MF. */
+export declare function readPlateGcode(threeMfPath: string, plate?: number): Promise<string | undefined>;
+/** Each layer's top Z in order, from the slicer's "; Z_HEIGHT:" markers. */
+export declare function layerTops(gcode: string): number[];
+/**
+ * The 1-based layers whose block holds a pause: the slicer's "; PAUSE_PRINTING"
+ * marker or the machine's pause G-code on its own line.
+ */
+export declare function pausedLayers(gcode: string, pauseGcode?: string): number[];
+/** The machine_pause_gcode a sliced file was made with (its config block), else Bambu's M400 U1. */
+export declare function machinePauseGcode(gcode: string): string;
+/** Project custom G-codes plus a pause before each requested layer, at that layer's exact top. */
+export declare function customGcodesWithPauses(tops: number[], layers: number[], project?: CustomGcodeInfo): CustomGcodeInfo;
+export {};

package/dist/slicer/layer-pauses.js

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import JSZip from "jszip";
+/**
+ * Pause-at-layer for Bambu-compatible slicer CLIs ("Add pause" in Bambu Studio
+ * and OrcaSlicer). The slicer writes the machine's own machine_pause_gcode
+ * (M400 U1 on Bambu printers) before the chosen layer, so the printer pauses
+ * by itself there and waits for Resume; no remote command is involved.
+ *
+ * The CLI takes these as --load-custom-gcodes <json> (CustomGCode::Info). It
+ * does not apply the pauses a project 3MF already carries in
+ * Metadata/custom_gcode_per_print_z.xml, so those are read here and passed the
+ * same way. A pause's print_z must be the exact top of its layer: a height
+ * between layers lands on the layer below.
+ */
+/** CustomGCode::Type, in the order bbs_3mf.cpp writes it as an integer. */
+const CUSTOM_GCODE_TYPES = ["ColorChange", "PausePrint", "ToolChange", "Template", "Custom", "Unknown"];
+/** 1-based layer numbers, as Bambu Studio's and OrcaSlicer's preview slider count them. */
+export function parsePauseLayers(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const raw = Array.isArray(value) ? value : String(value).split(/[\s,;]+/).filter(Boolean);
+    const layers = raw.map(entry => Number(entry));
+    for (const layer of layers) {
+        if (!Number.isInteger(layer) || layer < 2) {
+            throw new Error(`pause_at_layers takes whole layer numbers of 2 or more (the printer cannot pause before layer 1), not ${JSON.stringify(value)}.`);
+        }
+    }
+    const unique = [...new Set(layers)].sort((a, b) => a - b);
+    return unique.length ? unique : undefined;
+}
+function xmlAttr(tag, name) {
+    const match = new RegExp(`\\b${name}="([^"]*)"`).exec(tag);
+    return match ? match[1].replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&") : undefined;
+}
+/**
+ * The custom G-codes (pauses, colour changes, ...) a project 3MF stores for
+ * one plate (1-based), as Bambu Studio and OrcaSlicer save them.
+ */
+export async function readProjectCustomGcodes(threeMfPath, plate = 1) {
+    let zip;
+    try {
+        zip = await JSZip.loadAsync(await fs.promises.readFile(threeMfPath));
+    }
+    catch {
+        return undefined;
+    }
+    const file = zip.file(/^Metadata\/custom_gcode_per_print_z\.xml$/i)[0];
+    if (!file)
+        return undefined;
+    const xml = await file.async("string");
+    for (const block of xml.match(/<plate>[\s\S]*?<\/plate>/g) ?? []) {
+        const info = /<plate_info\b[^>]*>/.exec(block)?.[0];
+        if (Number(info ? xmlAttr(info, "id") : NaN) !== plate)
+            continue;
+        const gcodes = [];
+        for (const tag of block.match(/<layer\b[^>]*>/g) ?? []) {
+            const type = CUSTOM_GCODE_TYPES[Number(xmlAttr(tag, "type"))] ?? "Unknown";
+            const printZ = Number(xmlAttr(tag, "top_z"));
+            if (!Number.isFinite(printZ))
+                continue;
+            gcodes.push({
+                type,
+                print_z: printZ,
+                color: xmlAttr(tag, "color") ?? "",
+                extruder: Number(xmlAttr(tag, "extruder") ?? 1) || 1,
+                // Template and Custom keep their G-code text in "extra" (CustomGCode.hpp).
+                extra: xmlAttr(tag, "extra") ?? "",
+            });
+        }
+        const modeTag = /<mode\b[^>]*>/.exec(block)?.[0];
+        return { mode: (modeTag && xmlAttr(modeTag, "value")) || "SingleExtruder", gcodes };
+    }
+    return undefined;
+}
+/** The plate's G-code text inside a sliced 3MF. */
+export async function readPlateGcode(threeMfPath, plate = 1) {
+    const zip = await JSZip.loadAsync(await fs.promises.readFile(threeMfPath));
+    const exact = zip.file(`Metadata/plate_${plate}.gcode`);
+    const file = exact ?? zip.file(/^Metadata\/plate_\d+\.gcode$/)[0];
+    return file ? file.async("string") : undefined;
+}
+/** Each layer's top Z in order, from the slicer's "; Z_HEIGHT:" markers. */
+export function layerTops(gcode) {
+    const tops = [];
+    for (const match of gcode.matchAll(/^; Z_HEIGHT: ([0-9.]+)\s*$/gm))
+        tops.push(Number(match[1]));
+    return tops;
+}
+/**
+ * The 1-based layers whose block holds a pause: the slicer's "; PAUSE_PRINTING"
+ * marker or the machine's pause G-code on its own line.
+ */
+export function pausedLayers(gcode, pauseGcode = "M400 U1") {
+    const lines = gcode.split(/\r?\n/);
+    const paused = new Set();
+    let layer = 0;
+    const pauseLine = pauseGcode.trim();
+    for (const line of lines) {
+        if (line.startsWith("; Z_HEIGHT:")) {
+            layer += 1;
+            continue;
+        }
+        if (layer === 0)
+            continue;
+        const trimmed = line.trim();
+        if (trimmed === "; PAUSE_PRINTING" || (pauseLine && trimmed === pauseLine))
+            paused.add(layer);
+    }
+    return [...paused].sort((a, b) => a - b);
+}
+/** The machine_pause_gcode a sliced file was made with (its config block), else Bambu's M400 U1. */
+export function machinePauseGcode(gcode) {
+    const match = /^; machine_pause_gcode = (.*)$/m.exec(gcode);
+    const value = match?.[1]?.split("\\n")[0]?.trim();
+    return value || "M400 U1";
+}
+/** Project custom G-codes plus a pause before each requested layer, at that layer's exact top. */
+export function customGcodesWithPauses(tops, layers, project) {
+    const total = tops.length;
+    const beyond = layers.filter(layer => layer > total);
+    if (beyond.length) {
+        throw new Error(`This print has ${total} layers, so it cannot pause before layer ${beyond.join(", ")}.`);
+    }
+    const pauses = layers.map(layer => ({ type: "PausePrint", print_z: tops[layer - 1], color: "", extruder: 1, extra: "" }));
+    const kept = (project?.gcodes ?? []).filter(item => !(item.type === "PausePrint" && pauses.some(p => Math.abs(p.print_z - item.print_z) < 1e-4)));
+    return {
+        mode: project?.mode || "SingleExtruder",
+        gcodes: [...kept, ...pauses].sort((a, b) => a.print_z - b.print_z),
+    };
+}

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

@@ -165,6 +165,7 @@ export declare class STLManipulator extends EventEmitter {
      * 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>;
+    private sliceSTLOnce;
     /**
      * Enhanced version of confirmTemperatures with better error handling
      * @param gcodePath Path to the G-code file

package/dist/stl/stl-manipulator.js

@@ -12,6 +12,7 @@ import { flattenOrcaFilament } from '../slicer/filament-profiles.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';
+import { customGcodesWithPauses, layerTops, machinePauseGcode, pausedLayers, readPlateGcode, readProjectCustomGcodes } from '../slicer/layer-pauses.js';
 /** Orca/Bambu Studio process keys; profile JSON values are strings. */
 export function orcaProcessOverrides(overrides) {
     const keys = {};
@@ -848,6 +849,45 @@ export class STLManipulator extends EventEmitter {
      * slicer's error_string and plate warnings.
      */
     async sliceSTLWithResult(stlFilePath, slicerType, slicerPath, slicerProfile, progressCallback, printerPreset, filamentProfile, bambuOptions, processOverrides) {
+        const once = (options) => 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 = [];
+            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 });
+        }
+    }
+    async sliceSTLOnce(stlFilePath, slicerType, slicerPath, slicerProfile, progressCallback, printerPreset, filamentProfile, bambuOptions, processOverrides) {
         const operationId = this.generateOperationId();
         this.activeOperations.set(operationId, true);
         const bambuCli = STLManipulator.usesBambuCliPreparation(slicerType, printerPreset);