Khan/live-editor — pull request #212 by kevinb7 (2014-12-15 22:25:23+00:00)
Title: add debugger to live-editor

The debugger uses ES6 generators and only works on browsers that support generators. Right now that limits its use to Chrome 39+ and Firefox 26+.

The debugger feature uses a couple of libraries that I created:
- https://github.com/kevinb7/stepper – does most of the heavy lifting include transforming the code into generators, stepping through the code, reporting line numbers, setting up recurring method calls, e.g. "draw", and setting callbacks for "mouseClicked", etc. Supports local variable list and stack traces. These features aren't available in live-editor yet, but you can see them in action in the [stepper live demo](http://kevinb7.github.io/stepper/demo/index.html)
- https://github.com/kevinb7/iframe-overlay – forwards events to the canvas in the iframe. It's required so that events occur in the correct place when you hit a breakpoint in something like "mouseClicked" and then you move your mouse out of the iframe. Updates timestamps so that events after delivered with the proper delays between them even after hitting a breakpoint.

Sub-libraries I created:
- https://github.com/kevinb7/eventsim – simulates events without additional dependencies. Used by iframe-overlay.
- https://github.com/kevinb7/poster – make communicating with iframes, windows, and web workers easier by providing an EventEmitter-like interface. Used by iframe-overlay and the stepper demo.
- https://github.com/kevinb7/scheduler – simulates an event loop for "re-entrant" tasks. If the program that the debugger is debugging contains special methods like "draw" and "mouseClicked" we'd like to queue them in the order that they appear, but we should only start stepping through once we've finished stepping through the current method. Used by stepper.
- https://github.com/kevinb7/object-browser – UI control to browse hierarchical structures, looks similar to the object browser in Chrome Dev Tools
- https://github.com/kevinb7/gehry – deconstruct (and reconstruct) hierarchical structures that can be serialized for transport using postMessage (or poster). Preserves cyclical references so that structures like a doubly-linked list can be inspected. Used in the stepper demo.
- https://github.com/kevinb7/basic-ds – provides basic stack and doubly-linked list implementations. The biggest difference from most list implementations is that you can access the nodes as well as the values. The list is used by the scheduler as a queue and the stack is used by the stepper to store the call stack.
- https://github.com/kevinb7/tsbuild – simplifies building commonjs modules with declaration files and standalone .js files for the browser. Used by most of the projects for building.

Why TypeScript:
TypeScript provides access some useful ES6 features (simplified class syntax, default parameters, rest parameters, and fat arrow closures) and compiles down to idiomatic ES5. It also provides static type checking which eliminates a certain class of bugs. Lastly, it can provide more accurate code completion and more reliable refactoring. Note: there is no TypeScript being used in the live-editor codebase itself.

Testing:
All of the projects list above have automated test suites using travis-ci (except for tsbuild... those will be coming shortly) and are currently passing. Some tests required using a real browser. I was able to automate this using a project called [testee.js](http://daffl.github.io/testee.js/) and using xvfb and Firefox on travis-ci.

I've also added another test runner to live-editor which runs all of the tests from test/output/pjs but with the debugger enabled. This means that all tests programs are run through the transformations that the debugger uses and then the debugger automatically steps through each line in the program. There was only one test case that needed to be disabled (there's a comment in the spec file explaining why).

Operation:
To use the debugger you'll need to use a supported browser add ?debugger=true to the end of the URL. Once these two conditions are met you'll see a checkbox in the bottom left of the screen that says "debug" the same as in the hackweek demo. I made it a bit more obvious when you're in debug mode by change the background of the editor to be light yellow, hiding the text cursor, changing the mouse cursor from the i-beam to the default cursor. Also, when editing, breakpoints are a light blue with black text to indicate that they're disabled.

TODO:
There's one bug I just noticed where breakpoints in the editor aren't updated when a user adds/deletes lines. This shouldn't take too long to fix, but I'd like to start this review because it's rather large and I'm sure there's other things that I've missed as well. I hope that with more eyes on this feature we can spot them.