What are the limitations of Opal?

I'm very keen to try Opal in a new Rails project, but the risk of course is that I won't discover what it can't do until I've spent hundreds of hours doing everything else, and run into a brick wall that I can't possibly get through.

What are its limitations?

For example (and of course answers should not be limited to these topics if there are other limitations worth mentioning) I would assume that you can't just use any old Ruby library in your Opal code (but I'd love to find out that I'm wrong about that!).

I would also guess there might be difficulties in using any arbitrary JavaScript library, or that there are cases where you need to write JavaScript to interface with those.

And of course there could be all sorts of issues that I haven't even begun to imagine. It looks like an amazing project, but I want to know what gotchas I might encounter unexpectedly if I were to just dive in head-first.

From a Ruby standpoint:

• Strings are immutable b/c are bridged to JS Strings
• All Numeric (Integer/Float/etc.) are bridged to the JS Number class
• Symbols and Strings are the same, they're both bridged to JS Strings
• no access to some stuff from the browser (File,Thread,System,Process,etc)
• require is more tricky since there's no filesystem in the browser and as of 0.6.x they're gathered at the top of the file (AssetPipeline style). Things should improve from 0.7.x on (unreleased), (as a sidenote, similar issues are found in RubyMotion).
• you still need to learn the DOM, and possibly the CSSOM

From a JS standpoint:

• Math stuff is like in Ruby (i.e. method calls) that means it's slower (like in Ruby) compared to native JS operators; that means you won't probably use opal to write a HTML5 3D game engine
• no access to properties from outside the class, as in Ruby if you want to access instance variables you need to use methods
• some particularly convoluted (or if you want, idiomatic) JS libraries are harder to use with just Native or bridged classes (class MyClass < `MyJsClass`; end) and need full blown wrappers (opal-jquery is an example, and that happens all the time in Ruby too, where you seldom use FFI mapped apis directly and always wrap C libraries).

That said you usually can get a lot of stuff done with just using Native or opal-jquery. I personally have found myself moving classes from the backend to the frontend more than once. Testability and code readability surely improves (as long as you write good Ruby) and you can reuse your OOD skills.

I surely may be missing something, anyone is welcomed to chime in. And it will eventually turn into a blog post on http://opalrb.com/blog.

tl;dr

Don't forget you are in a browser. Don't underestimate the power of Ruby.