hypothesis/h — pull request #965 by csillag (2013-11-30 02:44:27+00:00)
Title: Automatic document change tracking, and on-the-fly reanchoring

When working on integrating ujvari's image work, we have been frustrated by the undesirable interplay between the various components at play; more specifically, dom-text-mapper being unable to cope with independent changes in the DOM. (See #945)

During our earlier testing, we did not really see how serious this problem is, but after some playing around, I had to admin that in some situations, it can be kind of vulnerable.

That made me angry, so I have implemented ubiquitous change tracking, and on-the-fly re-anchoring on the top of it.

In a nutshell, here is what it does:
* dom-text-mapper new uses the [mutation-summary library](https://code.google.com/p/mutation-summary/) to track mutations happening in the DOM.
* Change notifications are no longer necessary; all changes are captured, and acted upon automatically.
* When somebody calls one of dom-text-mapper's methods, which rely on the mapping data, before returning, the mapping database is always automatically refreshed, observing the changes happened since last check.
* Even when dom-text-mapper is not accessed, we react to mutations by updating our data.
* dom-text-mapper is now also able to selectively ignore changes in a configured set of elements, and also ignore their contents when scanning. (This was necessary because we have the heatmap, the toolbar, etc. embedded in the host document.)
* dom-text-mapper can also detect corpus changes in the document. (Ie. when the changes cause the serialized text version to change, too), and in these cases, it no longer freaks out, but does a full re-scan, and publishes a notification.
* Annotator's DomTextMapper plugin can now react to these corpus change notifications, and in these cases, we
re-calculate all our anchors, to adapt to the changed document content.
* I have enabled support for this in H. (With configuration matching our inserted element into the dom, etc.)

In practice, this looks like this:

* Go to http://observer1.dokku.hypothes.is/
* I suggest enabling always-on mode, for the best effect
* Open the sidebar
* Switch the annotation card to detail mode
* Open up the dev console
* Run `$("p")[0].childNodes[1].firstChild.nodeValue` to get a piece of the document. (The same as the quote visible on the annotation card in the sidebar.)
* Now overwrite this with something else, like this: `$("p")[0].childNodes[1].firstChild.nodeValue = "about our cool project"`
* Observe the effect: the change in the document's text is detected, and the annotation is anchored again, resulting in the quote now showing the visual diff. All happening automatically, without having to reload or anything.

Reacting to the changes, annotations can disappear, reappear, or move around.

The best way to test this would probably be some web-based editor, where H works. Any suggestions?

One way you _can not_ test this is by using Chrome's built-in HTML editor, editing the source of the page in the BG, because it works by "cheating", and changes the DOM without telling anybody about the mutation. (Normal web pages can not do this.)

* * *

This is a biggish piece of work (~600 lines of source code changes or so), so I expect some errors here and there.

This PR is not meant to be merged; this is here only for feedback and code review.

Enjoy.