bambu-printer-mcp 1.1.28 → 1.1.30

package/dist/printers/bambu.js

@@ -7,7 +7,8 @@ import os from "node:os";
 import { Readable } from "node:stream";
 import { readSafe3mfArchive } from "../safety/archive.js";
 import { inspectPrintFile } from "../safety/print-file.js";
-import { normalizeModel, validateTemperature } from "../safety/limits.js";
+import { isDualNozzleModel, normalizeModel, validateTemperature } from "../safety/limits.js";
+import { bridgeAmsMapping2Entry, bridgeAmsMappingValue, externalTrayForNozzle, describeAmsTrayRange } from "../ams-mapping.js";
 import { describeHmsKey, hiddenHmsKeys, hiddenHmsNotices, reportedHmsKey, validatePrinterState, manualHeatingRequirements } from "../safety/printer-state.js";
 import { withPrinterOperation, withPrintSnapshot, uniquePrintName, normalizedRemotePath, cancelPendingPrinterOperations } from "../safety/artifact.js";
 import { Client as FTPClient } from "basic-ftp";
@@ -355,6 +356,12 @@ class BambuClientStore {
             throw error;
         }
     }
+    forgetPrinter(printer) {
+        for (const [key, cached] of this.printers) {
+            if (cached === printer)
+                this.clearPrinterState(key);
+        }
+    }
     async disconnectAll() {
         const disconnectPromises = [];
         for (const printer of this.printers.values()) {
@@ -620,12 +627,17 @@ export class BambuImplementation {
         // `plate_N.json.filament_ids` -- and expand to a full project-level
         // array here. `amsMapping` is the raw escape hatch (takes precedence
         // when both are supplied).
+        // Dual-nozzle printers address two external spools: 254 feeds the left/deputy
+        // nozzle and 255 the right/main nozzle (Bambu Studio VIRTUAL_TRAY_DEPUTY_ID /
+        // VIRTUAL_TRAY_MAIN_ID). Single-nozzle printers keep 254 as the only external tray.
+        const dualNozzle = isDualNozzleModel(model);
+        const externalTrays = dualNozzle ? [254, 255] : [254];
         const validateTrayValue = (v, label) => {
             if (!Number.isInteger(v) ||
                 v < -1 ||
                 (v > 15 && v < 128) ||
-                v > 254) {
-                throw new Error(`${label} values must be integers in [-1, 15] (absolute tray) or 128-254 (HT/external); got ${v}`);
+                v > (dualNozzle ? 255 : 254)) {
+                throw new Error(`${label} values must be integers in ${describeAmsTrayRange({ dualNozzle })}; got ${v}`);
             }
         };
         let baseMapping;
@@ -655,7 +667,7 @@ export class BambuImplementation {
             const projectLen = Math.max(projectMetadata.projectFilamentCount, ...positions.map((p) => p + 1), 1);
             baseMapping = Array(projectLen).fill(-1);
             positions.forEach((pos, i) => {
-                baseMapping[pos] = options.useAMS === false ? 254 : i;
+                baseMapping[pos] = options.useAMS === false ? externalTrayForNozzle(inspection.filamentNozzleIndices?.[pos], dualNozzle) : i;
             });
         }
         let amsMapping;
@@ -663,15 +675,7 @@ export class BambuImplementation {
         if (usesH2ProjectFile) {
             const projLen = Math.max(projectMetadata.projectFilamentCount, baseMapping.length, 1);
             amsMapping = Array.from({ length: projLen }, (_, i) => i < baseMapping.length ? baseMapping[i] : -1);
-            amsMapping2 = amsMapping.map((v) => {
-                if (v < 0 || v === 255)
-                    return { ams_id: 255, slot_id: 255 };
-                if (v === 254)
-                    return { ams_id: 254, slot_id: 254 };
-                if (v >= 128)
-                    return { ams_id: 128, slot_id: v - 128 };
-                return { ams_id: Math.floor(v / 4), slot_id: v % 4 };
-            });
+            amsMapping2 = amsMapping.map((v) => bridgeAmsMapping2Entry(v, dualNozzle));
         }
         else {
             amsMapping = Array.from({ length: Math.max(5, baseMapping.length, projectMetadata.projectFilamentCount) }, (_, i) => i < baseMapping.length ? baseMapping[i] : -1);
@@ -681,8 +685,8 @@ export class BambuImplementation {
             if (baseMapping[position] === undefined || baseMapping[position] < 0) {
                 throw new Error(`Missing physical filament mapping for project filament ${position}.`);
             }
-            if (options.useAMS === false && baseMapping[position] !== 254) {
-                throw new Error("External-spool printing requires external spool mapping (254).");
+            if (options.useAMS === false && !externalTrays.includes(baseMapping[position])) {
+                throw new Error(`External-spool printing requires external spool mapping (${externalTrays.join(" or ")}).`);
             }
         }
         const legacyContainer = options.filePath.toLowerCase().endsWith(".gcode.3mf") && !usesH2ProjectFile && !isA1;
@@ -768,7 +772,7 @@ export class BambuImplementation {
                     project_id: submissionId,
                     subtask_id: submissionId,
                     task_id: submissionId,
-                    ams_mapping: amsMapping,
+                    ams_mapping: amsMapping.map(value => bridgeAmsMappingValue(value, dualNozzle)),
                     ams_mapping2: amsMapping2,
                 },
             };
@@ -838,17 +842,48 @@ export class BambuImplementation {
             throw new Error(`Failed to cancel print: ${error.message}`);
         }
     }
+    async invokeEmergencyCommand(printer, command, signal) {
+        if (!signal)
+            return invokeWithoutAck(printer, command);
+        let onAbort;
+        try {
+            await new Promise((resolve, reject) => {
+                onAbort = () => {
+                    // Force-close the actual transport: a raced publish may be queued
+                    // inside MQTT.js and otherwise dispatch after a later reconnect.
+                    this.printerStore.forgetPrinter(printer);
+                    void printer.disconnect(true).catch(() => {
+                        console.error("Failed to close an expired emergency MQTT client.");
+                    });
+                    reject(signal.reason);
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+                if (signal.aborted)
+                    onAbort();
+                else
+                    command.invoke(printer).then(resolve, reject);
+            });
+        }
+        finally {
+            signal.removeEventListener("abort", onAbort);
+        }
+        await sleep(COMMAND_SETTLE_MS);
+    }
     /** Raw MQTT stop for routes that already ran the shared cancellation steps. */
-    async sendStopOverMqtt(host, serial, token) {
+    async sendStopOverMqtt(host, serial, token, signal) {
+        signal?.throwIfAborted();
         const printer = await this.getPrinter(host, serial, token);
-        await invokeWithoutAck(printer, new UpdateStateCommand({ state: "stop" }));
+        signal?.throwIfAborted();
+        await this.invokeEmergencyCommand(printer, new UpdateStateCommand({ state: "stop" }), signal);
         return { status: "success", message: "Cancel command sent over MQTT." };
     }
     /** Raw MQTT heater-off; switching off needs no material or model declaration. */
-    async sendHeaterOffOverMqtt(host, serial, token, heater) {
+    async sendHeaterOffOverMqtt(host, serial, token, heater, signal) {
+        signal?.throwIfAborted();
         const printer = await this.getPrinter(host, serial, token);
+        signal?.throwIfAborted();
         const gcode = `${heater === "bed" ? "M140" : "M104"} S0`;
-        await invokeWithoutAck(printer, new GCodeLineCommand({ gcodes: [gcode] }));
+        await this.invokeEmergencyCommand(printer, new GCodeLineCommand({ gcodes: [gcode] }), signal);
         return { status: "success", message: `Heater-off sent over MQTT for ${heater}.`, command: gcode };
     }
     async pauseJob(host, serial, token, dispatch) {

package/dist/safety/limits.d.ts

@@ -21,6 +21,12 @@ export declare const MACHINE_LIMITS: Readonly<Record<string, {
     chamber: number;
     volume: readonly number[];
 }>>;
+/** Printers with two physical nozzles. Bambu Studio numbers the right/main nozzle 0
+ * (MAIN_EXTRUDER_ID) and the left/deputy nozzle 1 (DEPUTY_EXTRUDER_ID), and reports one
+ * virtual external-spool slot per nozzle: 255 (VIRTUAL_TRAY_MAIN_ID) and 254
+ * (VIRTUAL_TRAY_DEPUTY_ID). The single-nozzle H2S is deliberately absent. */
+export declare const DUAL_NOZZLE_MODELS: ReadonlySet<string>;
+export declare function isDualNozzleModel(model: unknown): boolean;
 export declare function normalizeModel(value: unknown): string | undefined;
 export declare function normalizeMaterial(value: unknown): string | undefined;
 export declare function validateTemperature(component: 'nozzle' | 'bed' | 'chamber', value: unknown, model: string, materials?: string[]): number;

package/dist/safety/limits.js

@@ -30,6 +30,15 @@ export const MACHINE_LIMITS = {
     h2s: { nozzle: 350, bed: 120, chamber: 65, volume: [340, 320, 340] },
     x2d: { nozzle: 300, bed: 120, chamber: 65, volume: [256, 256, 260] },
 };
+/** Printers with two physical nozzles. Bambu Studio numbers the right/main nozzle 0
+ * (MAIN_EXTRUDER_ID) and the left/deputy nozzle 1 (DEPUTY_EXTRUDER_ID), and reports one
+ * virtual external-spool slot per nozzle: 255 (VIRTUAL_TRAY_MAIN_ID) and 254
+ * (VIRTUAL_TRAY_DEPUTY_ID). The single-nozzle H2S is deliberately absent. */
+export const DUAL_NOZZLE_MODELS = new Set(['h2d', 'h2dpro', 'h2c', 'x2d']);
+export function isDualNozzleModel(model) {
+    const normalized = normalizeModel(model);
+    return normalized !== undefined && DUAL_NOZZLE_MODELS.has(normalized);
+}
 export function normalizeModel(value) {
     if (typeof value !== 'string')
         return undefined;

package/dist/safety/print-file.d.ts

@@ -12,6 +12,8 @@ export interface PrintFileInspection {
     selectsAms: boolean;
     nozzleTypes?: string[];
     nozzleFlows?: string[];
+    /** Physical nozzle index for each declared filament, composed from the selected plate headers. */
+    filamentNozzleIndices?: number[];
 }
 /** Inspect the exact selected plate. This does not simulate firmware or arbitrary motion:
  * only declared object bounds are checked, never purge/homing/wipe travel coordinates.

package/dist/safety/print-file.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { readBoundedPrintFile, loadSafe3mfArchive } from './archive.js';
-import { MACHINE_LIMITS, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
+import { MACHINE_LIMITS, isDualNozzleModel, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
 const NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
 const fail = (message) => { throw new Error(`Print safety: ${message}`); };
 function list(value) {
@@ -168,6 +168,7 @@ export async function inspectPrintFile(filePath, options) {
     const model = normalizeModel(options.model);
     if (!model)
         return fail(`unknown or missing printer model '${options.model}'`);
+    const dualNozzle = isDualNozzleModel(model);
     const plateIndex = options.plateIndex ?? 0;
     if (!Number.isInteger(plateIndex) || plateIndex < 0)
         return fail('selected plate index must be a nonnegative integer');
@@ -308,6 +309,24 @@ export async function inspectPrintFile(filePath, options) {
         const values = list(value);
         return values.length && values.every(v => !!normalizeMaterial(v)) ? values.map(v => normalizeMaterial(v)) : undefined;
     }, 'filament material');
+    // GCode.cpp uses 1-based filament_map logical extruders and then indexes
+    // physical_extruder_map to select the physical nozzle. Only this selected
+    // plate's headers establish that binding; unsliced project defaults do not.
+    const headerMap = (key, count, low, high) => {
+        const values = metadataValues(headers, [key]);
+        if (!values.length)
+            return undefined;
+        return consistent(values, value => {
+            const entries = list(value);
+            return entries.length === count && entries.every(v => NUMBER.test(v) && Number.isInteger(Number(v)) && Number(v) >= low && Number(v) <= high)
+                ? entries.map(Number) : undefined;
+        }, key.replace(/_/g, ' '));
+    };
+    const physicalExtruderMap = headerMap('physical_extruder_map', nozzleDiameters.length, 0, dualNozzle ? Math.min(nozzleDiameters.length, 2) - 1 : nozzleDiameters.length - 1);
+    if (physicalExtruderMap && new Set(physicalExtruderMap).size !== physicalExtruderMap.length)
+        fail('physical extruder map must be a complete permutation');
+    const filamentMap = headerMap('filament_map', materials.length, 1, nozzleDiameters.length);
+    const filamentNozzleIndices = filamentMap && physicalExtruderMap ? filamentMap.map(logical => physicalExtruderMap[logical - 1]) : undefined;
     const bedValues = metadataValues([...metadata, plate], ['curr_bed_type', 'bed_type']);
     const bedType = bedValues.length ? consistent(bedValues, normalizeBed, 'bed type') : undefined;
     if (options.bedType && (!bedType || normalizeBed(options.bedType) !== bedType))
@@ -370,7 +389,11 @@ export async function inspectPrintFile(filePath, options) {
             let line = stripComments(lines[index]);
             if (!line || line === '%')
                 continue;
-            // The official H2C template emits this literal separator without a semicolon.
+            // Accept only the exact vendor banners in their documented model/scope.
+            // X2D emits its filament-change banner throughout a print; H2C's record
+            // separator stays inside its explicitly bounded startup block.
+            if (line === '======== X2D filament_change gcode ==========' && model === 'x2d')
+                continue;
             if (line === '========== record data ==========' && h2cStartup(index))
                 continue;
             line = line.replace(/^N\d+\s*/i, '').replace(/\*\d+\s*$/, '');
@@ -477,9 +500,16 @@ export async function inspectPrintFile(filePath, options) {
                     continue;
                 }
                 const vendorWait = code === 'M109' && ['a1', 'a1mini'].includes(model);
+                // Bambu Studio addresses a physical nozzle on dual-nozzle machines with N<index>
+                // (X2D `M104 T1 S25 N0` multi-extruder pre-cooling and wipe-tower reheats).
+                // N selects a nozzle, never a target, so it is accepted only on those models,
+                // only for nozzle heaters, and only within the declared nozzle count.
+                const nozzleIndex = ['M104', 'M109'].includes(code) && dualNozzle;
                 for (const key of args.keys())
-                    if (!'SRTA'.includes(key) && !(key === 'H' && vendorWait))
+                    if (!'SRTA'.includes(key) && !(key === 'H' && vendorWait) && !(key === 'N' && nozzleIndex))
                         fail(`unsupported ${code} temperature parameter ${key}`);
+                if (args.has('N') && (!Number.isInteger(args.get('N')) || args.get('N') < 0 || args.get('N') >= Math.min(nozzleDiameters.length, 2)))
+                    fail(`unsupported ${code} nozzle index N`);
                 if (args.has('H') && (!Number.isFinite(args.get('H')) || args.get('H') < 0 || args.get('H') > 300))
                     fail(`unsupported ${code} wait parameter H`);
                 if (!args.has('S') && !args.has('R'))
@@ -489,13 +519,13 @@ export async function inspectPrintFile(filePath, options) {
                 // Without a verified per-filament nozzle map, apply all possible materials.
                 if (args.has('T') && (!Number.isInteger(args.get('T')) || args.get('T') < 0 || args.get('T') >= nozzleDiameters.length))
                     fail('physical heater target has no declared nozzle');
-                const position = args.has('T') ? undefined : active;
+                const position = args.has('T') || args.has('N') ? undefined : active;
                 const commonFlush = code === 'M109' && args.size === 1 && args.get('S') === 290 && model === 'x1e' && !depositionStarted && !commonFlushUsed && boundedX1ePurge(lines, index);
                 if (commonFlush)
                     commonFlushUsed = true;
                 for (const key of ['S', 'R'])
                     if (args.has(key))
-                        heat(component, args.get(key), position, args.has('T') || args.has('A'), commonFlush);
+                        heat(component, args.get(key), position, args.has('T') || args.has('N') || args.has('A'), commonFlush);
             }
             else if (code === 'M620' || code === 'M621') {
                 const args = parameters(argumentsText, model === 'x2d' ? 'MAB' : model === 'h2c' ? 'MAN' : 'MA');
@@ -656,5 +686,5 @@ export async function inspectPrintFile(filePath, options) {
         return fail('selected G-code contains no printable commands');
     if (!used.size)
         materials.forEach((_, index) => used.add(index));
-    return { model, nozzleDiameters, materials, usedFilamentPositions: [...used].sort((a, b) => a - b), plateInternalPath, sha256, maxNozzleTemperature, maxBedTemperature, maxChamberTemperature, bedType, selectsAms, nozzleTypes, nozzleFlows };
+    return { model, nozzleDiameters, materials, usedFilamentPositions: [...used].sort((a, b) => a - b), plateInternalPath, sha256, maxNozzleTemperature, maxBedTemperature, maxChamberTemperature, bedType, selectsAms, nozzleTypes, nozzleFlows, filamentNozzleIndices };
 }

package/dist/safety/printer-state.d.ts

@@ -7,6 +7,8 @@ export interface PrinterStateRequirements {
     nozzleDiameters: number[];
     materials?: string[];
     usedFilamentPositions?: number[];
+    /** Verified physical nozzle index for each project filament, composed from the inspected plate mappings. */
+    filamentNozzleIndices?: number[];
     amsMapping?: number[];
     useAMS?: boolean;
     requireIdle?: boolean;

package/dist/safety/printer-state.js

@@ -1,6 +1,6 @@
 import { HIDDEN_HMS } from "./hidden-hms.js";
 import { GetVersionCommand, PushAllCommand } from "bambu-node";
-import { normalizeMaterial, normalizeModel } from "./limits.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",
@@ -282,15 +282,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) {
@@ -345,7 +354,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.");
     }
@@ -374,16 +383,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]}.`);
@@ -404,7 +430,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 = {

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

@@ -0,0 +1,12 @@
+import type { BambuSliceOptions } from '../stl/stl-manipulator.js';
+export declare function validateRemoteSliceOptions(options?: BambuSliceOptions): number;
+/** Upload only locally prepared profiles, then inspect the exact downloaded 3MF. */
+export declare function sliceWithOrcaApi(input: {
+    inputPath: string;
+    machinePath: string;
+    processPath: string;
+    filamentPaths: string[];
+    outputPath: string;
+    options?: BambuSliceOptions;
+    isCancelled: () => boolean;
+}): Promise<string>;

package/dist/slicer/remote-slicer.js

@@ -0,0 +1,240 @@
+/** AFKFelix/orca-slicer-api contract at a9a28f0a7b0c6f51b9be158509e9e9677532b868. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { inspectPrintFile } from '../safety/print-file.js';
+import { normalizeMaterial, normalizeModel } from '../safety/limits.js';
+const MAX_BYTES = 100000000;
+const SUPPORTED_OPTIONS = new Set([
+    'arrange', 'orient', 'loadFilaments', 'filamentColours', 'bedType',
+    'nozzleType', 'nozzleVolumeType', 'slicePlate',
+]);
+function configuration() {
+    let url;
+    try {
+        url = new URL(process.env.SLICER_API_URL ?? '');
+    }
+    catch {
+        throw new Error('Remote slicing requires a valid trusted SLICER_API_URL.');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new Error('SLICER_API_URL must use HTTP(S) without embedded credentials, query or fragment.');
+    }
+    const mode = process.env.SLICER_API_MODE || 'sync';
+    if (!['sync', 'async'].includes(mode))
+        throw new Error('SLICER_API_MODE must be sync or async.');
+    const timeout = Number(process.env.SLICER_API_TIMEOUT_MS ?? 600000);
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > 3600000) {
+        throw new Error('SLICER_API_TIMEOUT_MS must be an integer from 1 to 3600000.');
+    }
+    const headers = {};
+    const token = process.env.SLICER_API_TOKEN;
+    if (token) {
+        const header = process.env.SLICER_API_TOKEN_HEADER || 'Authorization';
+        if (!/^[a-zA-Z0-9!#$%&'*+.^_`|~-]+$/.test(header) ||
+            ['host', 'content-type', 'content-length', 'connection', 'transfer-encoding'].includes(header.toLowerCase()) ||
+            /[^\x20-\x7e]/.test(token)) {
+            throw new Error('Invalid remote slicing authentication configuration.');
+        }
+        headers[header] = header.toLowerCase() === 'authorization' ? `Bearer ${token}` : token;
+    }
+    return { base: url.href.replace(/\/+$/, ''), headers, mode, timeout };
+}
+export function validateRemoteSliceOptions(options = {}) {
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined && !SUPPORTED_OPTIONS.has(key)) {
+            throw new Error(`Remote slicing option ${key} is unsupported by orca-slicer-api; use a local backend for this workflow.`);
+        }
+    }
+    // Upstream evaluates multipart values by truthiness, so the string "false"
+    // becomes true. Never silently turn an explicit false into an enabled flag.
+    if (options.arrange === false || options.orient === false) {
+        throw new Error('Remote arrange=false and orient=false are unsupported by the upstream multipart API.');
+    }
+    const plate = options.slicePlate ?? 1;
+    if (!Number.isInteger(plate) || plate < 1)
+        throw new Error('Remote slicing requires one positive plate number; slicing all plates is unsupported.');
+    return plate;
+}
+/** The remote API forwards this display name to Orca's --curr-bed-type. */
+function remoteBedType(value) {
+    const names = {
+        textured_plate: 'Textured PEI Plate', textured_pei_plate: 'Textured PEI Plate',
+        cool_plate: 'Cool Plate', engineering_plate: 'Engineering Plate',
+        hot_plate: 'High Temp Plate', high_temp_plate: 'High Temp Plate',
+    };
+    const key = typeof value === 'string' ? value.trim().toLowerCase().replace(/[\s-]+/g, '_') : '';
+    if (typeof names[key] !== 'string')
+        throw new Error('Unsupported remote bed type; use textured_plate, cool_plate, engineering_plate, or hot_plate.');
+    return names[key];
+}
+async function readResponse(response, limit) {
+    const size = Number(response.headers.get('content-length'));
+    if (size > limit) {
+        await response.body?.cancel();
+        throw new Error('Remote slicing response exceeds the size limit.');
+    }
+    if (!response.body)
+        throw new Error('Remote slicing returned an empty response.');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > limit)
+                throw new Error('Remote slicing response exceeds the size limit.');
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel();
+    }
+    return Buffer.concat(chunks);
+}
+async function readJob(response) {
+    try {
+        const job = JSON.parse((await readResponse(response, 65536)).toString('utf8'));
+        if (job && typeof job === 'object' && !Array.isArray(job))
+            return job;
+    }
+    catch { /* Do not echo an untrusted response, which may contain credentials. */ }
+    throw new Error('Remote slicing returned invalid job metadata.');
+}
+/** Upload only locally prepared profiles, then inspect the exact downloaded 3MF. */
+export async function sliceWithOrcaApi(input) {
+    const options = input.options ?? {};
+    const plate = validateRemoteSliceOptions(options);
+    if (input.filamentPaths.length !== 1 || (options.filamentColours && options.filamentColours.length !== 1)) {
+        throw new Error('orca-slicer-api supports exactly one filament slot; multi-slot projects require a local slicer.');
+    }
+    const config = configuration();
+    const machine = JSON.parse(await fs.readFile(input.machinePath, 'utf8'));
+    const filament = JSON.parse(await fs.readFile(input.filamentPaths[0], 'utf8'));
+    const processProfile = JSON.parse(await fs.readFile(input.processPath, 'utf8'));
+    const bedType = remoteBedType(options.bedType ?? processProfile.curr_bed_type ?? 'textured_plate');
+    const model = normalizeModel(machine.printer_model);
+    const nozzles = Array.isArray(machine.nozzle_diameter) ? machine.nozzle_diameter.map(Number) : [];
+    const materialValues = Array.isArray(filament.filament_type) ? filament.filament_type : [];
+    const materials = materialValues.map(normalizeMaterial);
+    if (!model || !nozzles.length || nozzles.some((n) => ![0.2, 0.4, 0.6, 0.8].includes(n)) ||
+        materials.length !== 1 || !materials[0]) {
+        throw new Error('Remote slicing requires explicit model, nozzle and single-material metadata in the prepared profiles.');
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    const deadline = setTimeout(() => { timedOut = true; controller.abort(); }, config.timeout);
+    const cancelCheck = setInterval(() => { if (input.isCancelled())
+        controller.abort(); }, 100);
+    let requestId;
+    let terminalJob = false;
+    let wroteOutput = false;
+    const request = async (route, init = {}) => {
+        if (input.isCancelled())
+            controller.abort();
+        // Do not pass multipart data to fetch after cancellation: undici may start
+        // its body producer before checking the signal and close it mid-enqueue.
+        controller.signal.throwIfAborted();
+        let response;
+        try {
+            response = await fetch(config.base + route, { ...init, headers: config.headers, signal: controller.signal, redirect: 'manual' });
+        }
+        catch {
+            throw new Error('Remote slicing HTTP request failed; check the trusted service configuration.');
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error(`Remote slicing HTTP ${response.status}.`);
+        }
+        return response;
+    };
+    try {
+        const ext = path.extname(input.inputPath).toLowerCase();
+        if (!['.stl', '.3mf'].includes(ext))
+            throw new Error('Remote slicing supports only STL or 3MF input.');
+        const bytes = await fs.readFile(input.inputPath);
+        if (bytes.length > MAX_BYTES)
+            throw new Error('Remote slicing input exceeds the 100 MB upstream limit.');
+        const form = new FormData();
+        form.set('file', new Blob([new Uint8Array(bytes)], { type: ext === '.3mf' ? 'model/3mf' : 'model/stl' }), `model${ext}`);
+        for (const [field, filePath, type] of [
+            ['printerProfile', input.machinePath, 'machine'],
+            ['presetProfile', input.processPath, 'process'],
+            ['filamentProfile', input.filamentPaths[0], 'filament'],
+        ]) {
+            const profile = JSON.parse(await fs.readFile(filePath, 'utf8'));
+            // The remote validator requires these metadata fields even for standalone
+            // user profiles. They do not change the resolved machine/process settings.
+            const data = { ...profile, type, from: profile.from || 'User' };
+            form.set(field, new Blob([JSON.stringify(data)], { type: 'application/json' }), `${field}.json`);
+        }
+        form.set('exportType', '3mf');
+        form.set('plate', String(plate));
+        form.set('bedType', bedType);
+        form.set('resolveProfileInheritance', 'false');
+        if (options.arrange === true)
+            form.set('arrange', 'true');
+        if (options.orient === true)
+            form.set('orient', 'true');
+        let response = await request(config.mode === 'async' ? '/slice-async' : '/slice', { method: 'POST', body: form });
+        if (config.mode === 'async') {
+            const submitted = await readJob(response);
+            if (typeof submitted.requestId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(submitted.requestId)) {
+                throw new Error('Remote slicing returned an invalid request ID.');
+            }
+            requestId = submitted.requestId;
+            for (;;) {
+                // Construct the documented same-service paths. Returned URLs cannot
+                // redirect authenticated requests to an arbitrary origin or route.
+                const job = await readJob(await request(`/slice-async/${requestId}`));
+                if (job.status === 'completed' || job.status === 'failed') {
+                    terminalJob = true;
+                    if (job.status === 'failed')
+                        throw new Error('Remote slicing job failed; inspect the service logs.');
+                    break;
+                }
+                if (job.status !== 'pending' && job.status !== 'processing')
+                    throw new Error('Remote slicing returned an unknown job state.');
+                await delay(500, undefined, { signal: controller.signal });
+            }
+            response = await request(`/slice-async/${requestId}/result`);
+        }
+        const result = await readResponse(response, MAX_BYTES);
+        await fs.writeFile(input.outputPath, result, { flag: 'wx', mode: 0o600 });
+        wroteOutput = true;
+        const inspection = await inspectPrintFile(input.outputPath, {
+            model, nozzleDiameters: nozzles, plateIndex: plate - 1, bedType,
+        });
+        if (JSON.stringify(inspection.materials) !== JSON.stringify(materials)) {
+            throw new Error('Remote sliced file materials contradict the prepared filament profile.');
+        }
+        if (input.isCancelled())
+            throw new Error('Remote slicing cancelled.');
+        return input.outputPath;
+    }
+    catch (error) {
+        if (wroteOutput)
+            await fs.rm(input.outputPath, { force: true });
+        if (controller.signal.aborted) {
+            throw new Error(`Remote slicing ${timedOut ? 'timed out' : 'cancelled'}; the remote job may continue. No retry was sent.`);
+        }
+        throw error;
+    }
+    finally {
+        // DELETE only removes finished jobs; upstream has no active-job cancellation.
+        // Cleanup never retries submission or masks a valid result / original error.
+        if (requestId && terminalJob && !controller.signal.aborted) {
+            try {
+                await (await request(`/slice-async/${requestId}`, { method: 'DELETE' })).body?.cancel();
+            }
+            catch {
+                console.error('Remote slicing finished-job cleanup failed; service retention applies.');
+            }
+        }
+        clearTimeout(deadline);
+        clearInterval(cancelCheck);
+    }
+}

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

@@ -22,7 +22,7 @@ export type TransformationParams = {
     relative?: boolean;
     selectionBounds?: THREE.Box3;
 };
-export declare const SLICER_TYPES: readonly ["bambustudio", "orcaslicer", "orcaslicer-bambulab", "prusaslicer", "cura", "slic3r"];
+export declare const SLICER_TYPES: readonly ["bambustudio", "orcaslicer", "orcaslicer-bambulab", "orca-slicer-api", "prusaslicer", "cura", "slic3r"];
 export type SlicerType = typeof SLICER_TYPES[number];
 export declare function normalizeSlicerType(rawSlicerType: string): SlicerType;
 export declare function isBambuCompatibleSlicer(slicerType: SlicerType): boolean;