Current active document and JSX extension

• How do I find the active document in InDesign, the one the user is currently working on? It seems that app.activeDocument, if it exists, is the correct reference?

Yes but beware this may fail if no documents are open. So you may prefer app.properties.activeDocument that can at least avoid code execution error.

• When the user switches from one to another document, I need to update my extension’s panel. Is there a call-back that I could register?

Have a look at CInterface.addEventListener in the sdk.

csInterface.addEventListener ( "documentAfterActivate", function(evt) {

       //a document has been activated. You should take care of if in to you jsx handler

    } );

• Is it possible to store “private” or extension-specific data with the document, so that my extension can update state depending on the active document? Or is that data better stored in local storage using some document-specific identifier?

Documents have ids so you could store info in the local storage However you may prefer the jsx insertLabel method:

app.activeDocument.insertLabel ( "key", "value" );