The improvement is to add stencils, exactly in the same way an application like Visio has them. It's not a rocket science idea, but clearly a big improvement in usability for both developers and users. We'll supply a central repository of a good number of stencils, which will be freely available under a creative commons style license. You'll be able to load one, or a set, and work with it as you would any under shape.
There are some details to be worked out, the registry system, a naming convention, etc. But, we've got the first version working in Java, so we're looking at a first release in the Java code base September-October 2010. We didn't want to invent our own description XML for stencils, and the Visio format is far too complex for our purposes, so we've gone with the shape format available on the excellent Dia diagramming tool. This is an SVG sub-set, wrapped by a few additional attributes needed. The format is clearly well thought out, enables the vast majority of required stencils to be drawn, yet keeps the format simple and fast to implement.
Dia also specifies a mechanism to define a set of stencils, we'll be using this, or something very similar. We'll also be re-using our embedded PNG concept we recently introduced to the Java code ( which is a posting on its own, and probably deserves a post after this one, since it needs a proper explanation ). The short story is that a set will comprise a set description XML and some number of PNG files only. The Dia format describing the XML of the shape will be embedded in the PNG itself.
As mentioned, the change to the API should be minimal (if anything). We intend to add the stencil as a new shape and change the other vertex shapes to call the correct stencil ( but leave the old shape classes and methods, only deprecated in Java ).
The additional ideas this project has brought up are: 1) Implement the edge end markers as stencils and 2) Implement a vertex perimeter description to position ports correctly. We're researching a mechanism to infer the perimeter from the SVG of the shape, but this is very much at the research stage.