API wishes

[michael]

The more I think about it, the less I think we should have an apply-like interface. Also the current API is misleading..

Annotations Manipulation API

as surface.apply(["insert", {type: "em"}], I'd rather respect a text insert.. than an annotation insert...

Maybe an explicit annotations interface is better..

surface.annotate({id: "annotation:1", type: "em", pos: [0,5]};

Or for comments:

surface.annotate({id: "annotation:2", type: "comment", pos: [0,10], properties: {"content": "Hi, I'm a comment"}});

No UI logic should be within Surface.. prompt() ing for a links url etc. should be handled outside.

In order to make passing annotations to the constructor work.. we can use that interface internally..

function(options) {
  var that = this;
  _.each(options.annotations, function(annotation) {
    that.annotate(annotation);
  });
}

Text Manipulation

surface.setText("initialized with new text");

This might brake the annotations. So we might want to allow only a full update of the surface, passing in the text content and all annotations.

surface.update({content: "foo", annotations: []});

Actually all init functionality could go into update.. and we just call it from the constructor.

Delta Updates

We might want to consider supporting delta updates but this would involve pulling in third party libs.. like Tim's Operation.js. We wanna wait with that I think.. and make surface small.. and dumb... and don't try to guess use-cases.