How to access app.activeDocument from a palette button?

With a lot of trial and error and ploughing through vague, unclear articles and non-existent docs, I figured it out.

• It seems like palettes don't actually know what app they're in. They just sit there.
• To get anything from your app, you need to throw javascript at it using the seemingly completely undocumented BridgeTalk, giving BridgeTalk a callback function if you need anything to happen in the palette once it's finished

This actually isn't half as difficult as it looks when you're wading through the mountains of noise on the topic. Basically, anything you want to write like this:

function someFunction() {
   // get data from the application and write it in the palette
   palette.info.text = app.activeDocument.selection.length;
}
palette.button.onclick = someFunction;

...you have to write like this...

function someFunction() {
  // get data from the application
  return app.activeDocument.selection.length;
}
 
palette.button.onclick = function(){
 
 // make a BridgeTalk object to throw the script
  var bt = new BridgeTalk(); 
  bt.target = "illustrator"; 
 
 // a string containing javascript code to execute in Illustrator
  bt.body = someFunction.toString()+'someFunction();'; 
 
 // a function that recieves whatever the body JS above returns
  bt.onResult = function(result){ 
      palette.info.text = result;
 };
 
  bt.send();
}

This sort of structure should work for essentially anything - the only tricky case I can think of is if you need Illustrator to read some data that is in your palette - since the code you throw can't access any variables in the rest of your script - in which case you can do something like this:

bt.body = 'var = '+someVariable.toString()+'; '+someFunction.toString()+'someFunction();';

Or if you need to parameters to someFunction:

bt.body = someFunction.toString()+'someFunction('+someVariable.toString()+');';

I made a mistake in the code above - it should be     palette.info.text = result.body;

Not      palette.info.text = result;

So annoying I can't edit it...