Status of wrappers in XPConnect.
Purpose of this document
Developers in the know understand that wrappers play a large role in XPConnect, and that we have a lot of them. Less informed developers understand that wrappers exist and are somehow important, but they don't know when they should use what wrappers, or if they should be seeing a wrapper. This document will serve as a high level overview to wrappers.
Types of Wrappers
window.focus(), you're calling into XPCWrappedNative code. They are implicitly created by XPConnect and you should not have to worry about how that happens. There are several types of wrapped natives, but I won't cover those here.
new XPCNativeWrapper(wrappedNative). "Expando" properties, not defined in idl, but created by the wrapped object are not visible through this wrapper.
This wrapper was created to address some problems with XPCNativeWrapper. In particular, some extensions want to be able to safely access non-natively-implemented content defined objects (and to access the underlying under an XPCNativeWrapper without its strong behavior guarantees). XPCSJOW act as a buffer between the chrome code. Note: Because any type of object can be wrapped here, there is no predefined behavior. The only guarantee here is that untrusted code will run in an untrusted context. In particular, the underlying object might act entirely differently from what is expected. Safe JSObject wrappers are implicitly created in some circumstances. All properties are visible through this wrapper.
The cross origin wrapper, or XOW, was recently implemented in order to broker access between web sites. This wrapper is implicitly created by XPConnect. All access checks happen in XOW code. If a XOW wrapper happens to wrap an object that is from the same origin as the running code, it acts like the Safe JSObject wrapper and it is possible to do anything to the XOW that you would do with any JS object. If the underlying object is not accessible, then it acts like an XPCNativeWrapper, meaning that it allows access to all APIs and behaviors provided by idl, overriding whatever the other site might have done.
What Wrappers Should I Use
Alright, you've skimmed the above and now you want to write some code! What wrappers should you use?
Chrome Code (extensions, etc)
As mentioned above, XPCWrappedNative and XPCWrappedJS wrappers are created implicitly, you should never have to worry about them. Likewise, if you are writing an extension or chrome code that never touches content code, you don't have to worry about wrappers.
However, most extensions do touch content in some way. If you do touch content (via its window, for example) you should always get an XPCNativeWrapper. If you don't, then you have found a bug. See the documentation on XPCNativeWrapper for more information about its use.
If you need more access to an object or need to access a content defined object that is implemented in JS or otherwise not available through an idl interface, then you should be using XPCSafeJSObjectWrappers. At the moment, you can either get one through
XPCNativeWrapper.wrappedJSObject or by explictly writing
new XPCSafeJSObjectWrapper(object). Note, however, that I'm looking into implicitly creating these wrappers in all relevant cases and removing the visible constructor.
Content Code (a webpage)
As has always been the case, content code should not have to worry about wrappers or wrapping. Especially with the advent of XOWs, if you write code that conforms to the security restrictions imposed by the browser, you should not have to worry about wrappers. This does not mean that you can ignore security, think of XOWs like a safety belt, they will try to protect you, but you can still get in an accident.