I've done it the hard way for now, by navigating the API as rawly as it gets to display the documents. Doing it this way for a bit will inform what kind of macros or other context helpers we need to make the view as clean as possible.
Played around a bit with macros and their capabilities, I think creating a java context helper class is the better way. The velocity template should make it easy to create very custom html. With macros, we could "hide" the complex method calls, but eg. creating a shortcut for a loop AND customize the html inside this loop will not be possible easily.
And, correct me if I'm wrong, your "shortcut setters" like "#set($iterator=$response.values.response.iterator())" have to be declared in every template file, cause template libraries cannot share variables, and macros only produce Strings and no other return types.
So I suggest a small java wrapper object that still uses the doclist for performance considerations and only provides handy convenience methods like
getResultIterator() -> iterator of ids, used in #foreachs
so a custom result view looks like this:
#foreach($docid in $helper.getResultIterator())
This object can be passed to the velocity context and may be accessible to all custom templates, without changing the data's nature (doclist to momory objects or the like). I'll have a test version of thos approch ready this evening.