Why would I use this rather than the actual canvas API?

Because the actual canvas API is more limited in what it can do. Basically this was designed to be a lot like processing, without the special DSL; you write your applications using just javascript/coffeescript.

To be honest, right now, it's a pretty bare bones wrapper around the actual canvas API. Maybe there's more to come? What can it do that you can't currently do with one or two lines of normal JS?

Maybe there's more to come, but not much more. It's purposefully bare bones. When I was writing some canvas-based games, everything I looked into felt too heavyweight. Processing.js uses its own DSL. Akihabara was just overwhelming. This is designed to be something you can learn to use in 5 minutes. Hell, you could read the entire source in that time.

The base canvas API is even more bare bones though. All you essentially have access to is pixel manipulation, paths and rectangles. This builds on top of it to provide most of what you would see in processing.js.

Actually this is canvas.coffee. I would be much more interested if this was actual Javascript.

Yeah I was a little surprised a .js version wasn't included as well. If might be a good idea to reference how people can compile coffeescript for people who want to use this and don't know what coffeescript is.

Yes, I sort of regret calling it canvas.js but it's a bit late now. I will add information on how to compile coffeescript.

Are there any examples to look at?

Thanks. Wordman is fantastic.

Has anyone come across a canvas library similar to raphael.js or protoviz? (both svg)

Raphael.js and protoviz exist to lower the barrier of entry of SVG to canvas level [0]. The only advantage they have over canvas is interactivity. Certain libraries like impactjs [1] are aiming to fix that.

[0] Just about the entirety of canvas can be contained in a page: http://www.nihilogic.dk/labs/canvas_sheet/HTML5_Canvas_Cheat...

[1] http://impactjs.org/ - used in http://www.phoboslab.org/biolab/

test