Hack yet another place where we need to use _codeMirror.replaceRange()...

src/document/DocumentManager.js

@@ -814,6 +814,14 @@ define(function (require, exports, module) {
      * given new text; if text == "", then the entire range is effectively deleted. If 'end' is omitted,
      * then the new text is inserted at that point and all existing text is preserved. Line endings will
      * be rewritten to match the document's current line-ending style.
+     * 
+     * IMPORTANT NOTE: Because of #1688, do not use this in cases where you might be
+     * operating on a linked document (like the main document for an inline editor) 
+     * during an outer CodeMirror operation (like a key event that's handled by the
+     * editor itself). A common case of this is code hints in inline editors. In
+     * such cases, use `editor._codeMirror.replaceRange()` instead. This should be
+     * fixed when we migrate to use CodeMirror's native document-linking functionality.
+     *
      * @param {!string} text  Text to insert or replace the range with
      * @param {!{line:number, ch:number}} start  Start of range, inclusive (if 'to' specified) or insertion point (if not)
      * @param {?{line:number, ch:number}} end  End of range, exclusive; optional

src/extensions/default/JavaScriptCodeHints/main.js

@@ -411,7 +411,11 @@ define(function (require, exports, module) {
             }
         }
         // Replace the current token with the completion
-        session.editor.document.replaceRange(completion, start, end);
+        // HACK (tracking adobe/brackets#1688): We talk to the private CodeMirror instance
+        // directly to replace the range instead of using the Document, as we should. The
+        // reason is due to a flaw in our current document synchronization architecture when
+        // inline editors are open.
+        session.editor._codeMirror.replaceRange(completion, start, end);
 
         // Return false to indicate that another hinting session is not needed
         return false;