This article needs a technical review. How you can help.
This document is a high-level overview of XPConnect wrapper objects (for the more technical description see XPConnect security membranes). For practical advice on dealing with wrappers, see Safely accessing content DOM from chrome.
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.
Basic XPConnect objects
XPCWrappedNative
These objects are created when any natively implemented XPCOM object (that is, any object implemented in C++) needs to be reflected into JavaScript. This includes all DOM objects (including Window) and chrome elements that are reflected into JavaScript.
This wrapper is responsible for mapping calls from JavaScript into C++. This means that when you say window.focus(), you're calling into XPCWrappedNative code.
If you call 'toString()' and get "[xpconnect wrapped nsIFoo]" then the reference is to a XPCWrappedNative object with interface nsIFoo.
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.
XPCWrappedJS
These objects are the exact opposite of XPCWrappedNative. They exist to reflect an object from JavaScript into C++. This means that whenever you pass your JavaScript object into a C++ function, we create one of these wrappers. For example, if you've implemented some component with an interface nsIFoo and you pass your JavaScript object into a C++ function taking an nsIFoo, an XPCWrappedJS is created around your object. C++ calls are routed through XPCWrappedJS code into your JavaScript implementation.
These wrappers are created by XPConnect, so you should not have to worry about how to construct them or whether to construct them.
Double wrapping. There is one case where an XPCWrappedNative wraps another wrapper object. This case is where a JS object was passed in via some IDL-declared interface, creating an XPCWrappedJS, and is now being returned to JavaScript via some other interface. In order to preserve API compatibility, an XPCWrappedNative is created around the XPCWrappedJS.
Security wrappers exposed to chrome
To learn about security wrappers, see the article on script security in Gecko.
Note that a previous version of the current page recommended using __exposedProps__ to expose objects from chrome to content. This is now deprecated and we are in the process of removing support for it. If you need to make objects or functions defined in chrome code accessible to content, use Components.utils.cloneInto or Components.utils.exportFunction.