What is #targetengine?

This discussion was brought up in a Slack channel I monitor. One long-time developer said the following (cleaned up a bit for clarity):

As far as I know //@targetengine only works on InDesign (probably including InCopy) and Illustrator.

On InDesign it works properly and on Illustrator it does not. Nevertheless other apps as far as I know all have the ability to use targetengines with C++ and that’s what CEP does with each CEP [extension?] having its own isolated engine.

There are at least 3 types of engine.

1. main engines, in InDesign it’s a temp engine that forgets everything after completing a scripts execution.

2. Public Private engines like session that remember and are active after script execution and good for event listeners. These and main can be identified using $.engineName and found on ESTK / vsCode

3. Private Private $.engineName will show "" can only be created with C++ that what most of the apps use and CEP uses except for InDesign where CEP uses Public Private engines which can be chosen.

He thinks there's also a 4th type he's forgetten.

#targetengine is specific to the Adobe scripting in InDesign, PhotoShop, Illustrator etc. - it is not a general Javascript feature.

It specifies how to handle all the global 'stuff' - not only variables but also function declarations and any other change to the global status.

If you use the default 'main' engine all the globals disappear as soon as the script completes. If you use the 'session' engine all the globals are preserved as long as the host application keeps running. This means that if you run the script:

#targetengine "session"

var test = "test";

and later run the script:

#targetengine "session"

alert(test);

you get a message box showing test instead than giving an error

Besides the two standard 'main' and 'session' engines you can create your own ones, with arbitrary names - so if you run the script

#targetengine "mine"

var test = "another test";

and then run

#targetengine "mine"

alert(test);

you get a message box showing another test, but if you run again

#targetengine "session"

alert(test);

you still get test: there are two different 'test' global variables, one in the 'session' engine and one in the (newly created) 'mine' one.