document the insulation magic that happens with Object.create, Map, etc.

jaredly · jaredly · commit 41f5760aba57 · 2015-08-10T15:52:50.000-07:00
diff --git a/shells/chrome/Readme.md b/shells/chrome/Readme.md
@@ -11,5 +11,36 @@ To hack on the plugin:
 
 Generally, changes to the UI will auto-propagate if you have `webpack --watch`
 on (close devtools and re-open them). If you change the background script or
-injector, you'll have to reload the extension from the extensions page.
+injector, you might have to reload the extension from the extensions page.
+
+## Insulating the environment
+
+React Devtools has part of the code (the backend + agent) running in the same
+javascript context as the inspected page, which makes the code vulnerable to
+environmental inconsistencies. For example, the backend uses the es6 `Map`
+class and normally expects it to be available in the global scope. If a user
+script has overridden this, the backend breaks.
+
+To prevent this, the content script [`src/GlobalHook.js`](src/GlobalHook.js),
+which runs before any user js, saves the native values we depend on to the
+`__REACT_DEVTOOLS_GLOBAL_HOOK__` global. These are:
+
+- Set
+- Map
+- WeakMap
+- Object.create
+
+Then in `webpack.backend.js`, these saved values are substituted for the
+globally referenced name (e.g. `Map` gets replaced with
+`window.__REACT_DEVTOOLS_GLOBAL_HOOK__.nativeMap`).
+
+## Fixing document.create
+
+React Native sets `document.createElement` to `null` in order to convince js
+libs that they are not running in a browser environment while `debug in
+chrome` is enabled.
+
+To deal with this, [`src/inject.js`](src/inject.js) calls
+`document.constructor.prototype.createElement` when it needs to create a
+`<script>` tag.
 
diff --git a/test/example/sink.html b/test/example/sink.html
@@ -7,6 +7,8 @@
     <body>
         <script src="build/sink.js"></script>
         <script>
+            // Test to make sure the backend doesn't depend on Object.create
+            // or ES6 globals
             Object.create = null;
             Map = null;
             Set = null;
