Debug Render Tree (for Ember Inspector)

[chancancode]

Introduce debug render tree

1. Before loading Ember, set ENV._DEBUG_RENDER_TREE = true;

   This controls whether to perform extra bookkeeping needed to make the captureRenderTree API work.

   This has to be set before the ember JavaScript code is evaluated.

   This is usually done by setting one of these...

   window.EmberENV = { _DEBUG_RENDER_TREE: true };
   

   window.ENV = { _DEBUG_RENDER_TREE: true };
   

   ...before the "vendor" <script> tag in index.html.

   Setting the flag after Ember is already loaded will not work correctly. It may appear to work somewhat, but fundamentally broken.

   This is not intended to be set directly. Ember Inspector will enable the flag on behalf of the user as needed.

   This flag is always on in development mode.

   The flag is off by default in production mode, due to the cost associated with the the bookkeeping work.

   The expected flow is that Ember Inspector will ask the user to refresh the page after enabling the feature. It could also offer a feature where the user add some domains to the "always on" list. In either case, Ember Inspector will inject the code on the page to set the flag if needed.

2. With the flag on, Ember._captureRenderTree() is available.

   It takes the application instance as an argument and returns an array of CapturedRenderNode:

   interface CapturedRenderNode {
     type: 'outlet' | 'engine' | 'route-template' | 'component';
     name: string;
     args: {
       positional: unknown[];
       named: Dict<unknown>;
     };
     instance: unknown;
     bounds: Option<{
       parentElement: Simple.Element;
       firstNode: Simple.Node;
       lastNode: Simple.Node;
     }>;
     children: CapturedRenderNode[];
   }

[RobbieTheWagner]

@chancancode is it better to use window.EmberENV or window.ENV?

[chancancode]

@rwwagner90 it is used like this: https://github.com/emberjs/ember.js/blob/master/packages/@ember/-internals/environment/lib/env.ts#L206

Do you have a way to inject the script just before the vendor script tag? If so, you should probably try to detect if the app has already tried to set either of those and then go with it.

If you have to inject at the very beginning of the page.. maybe you want to set window.ENV = window.EmberENV = {}? That way if the app tries to add more things to either, it would still work, as long as they check first and not override it with a new object.

[rwjblue]

We should only use window.EmberENV (usage of window.ENV is discouraged, and only exists as a form of legacy support). I’ll do a separate PR to add a deprecation if we find and use window.ENV.

[rwjblue]

Do we have stripping for this in Ember's own packages?