[devtools] Add DOMSnapshot domain for dom+layout+style snapshots.

third_party/WebKit/Source/core/inspector/browser_protocol.json

 {
     "version": { "major": "1", "minor": "2" },
     "domains": [{
         "domain": "Inspector",
         "experimental": true,
         "types": [],
         "commands": [
             {
                 "name": "enable",
                 "description": "Enables inspector domain notifications."
@@ skipping 3030 matching lines @@
             {
                 "id": "InlineTextBox",
                 "type": "object",
                 "properties": [
                     { "name": "boundingBox", "$ref": "DOM.Rect", "description": "The absolute position bounding box." },
                     { "name": "startCharacterIndex", "type": "integer", "description": "The starting index in characters, for this post layout textbox substring." },
                     { "name": "numCharacters", "type": "integer", "description": "The number of characters in this post layout textbox substring." }
                 ],
                 "description": "Details of post layout rendered text positions. The exact layout should not be regarded as stable and may change between versions.",
                 "experimental": true
-            },
-            {
-                "id": "LayoutTreeNode",
-                "type": "object",
-                "properties": [
-                    { "name": "nodeId", "$ref": "DOM.NodeId", "description": "The id of the related DOM node matching one from DOM.GetDocument." },
-                    { "name": "boundingBox", "$ref": "DOM.Rect", "description": "The absolute position bounding box." },
-                    { "name": "layoutText", "type": "string", "optional": true, "description": "Contents of the LayoutText if any" },
-                    { "name": "inlineTextNodes", "type": "array", "optional": true, "items": { "$ref": "InlineTextBox" }, "description": "The post layout inline text nodes, if any." },
-                    { "name": "styleIndex", "type": "integer", "optional": true, "description": "Index into the computedStyles array returned by getLayoutTreeAndStyles." }
-                ],
-                "description": "Details of an element in the DOM tree with a LayoutObject.",
-                "experimental": true
-            },
-            {
-                "id": "ComputedStyle",
-                "type": "object",
-                "properties": [
-                    { "name": "properties", "type": "array", "items": { "$ref": "CSSComputedStyleProperty" } }
-                ],
-                "description": "A subset of the full ComputedStyle as defined by the request whitelist.",
-                "experimental": true
             }
         ],
         "commands": [
             {
                 "name": "enable",
                 "description": "Enables the CSS agent for the given page. Clients should not assume that the CSS agent has been enabled until the result of this command is received."
             },
             {
                 "name": "disable",
                 "description": "Disables the CSS agent for the given page."
@@ skipping 175 matching lines @@
                 "name": "getBackgroundColors",
                 "parameters": [
                     { "name": "nodeId", "$ref": "DOM.NodeId", "description": "Id of the node to get background colors for." }
                 ],
                 "returns": [
                     { "name": "backgroundColors", "type": "array", "items": { "type": "string" }, "description": "The range of background colors behind this element, if it contains any visible text. If no visible text is present, this will be undefined. In the case of a flat background color, this will consist of simply that color. In the case of a gradient, this will consist of each of the color stops. For anything more complicated, this will be an empty array. Images will be ignored (as if the image had failed to load).", "optional": true }
                 ],
                 "experimental": true
             },
             {
-                "name": "getLayoutTreeAndStyles",
-                "parameters": [
-                    { "name": "computedStyleWhitelist", "type": "array", "items": { "type": "string" }, "description": "Whitelist of computed styles to return." }
-                ],
-                "returns": [
-                    { "name": "layoutTreeNodes", "type": "array", "items": { "$ref": "LayoutTreeNode" } },
-                    { "name": "computedStyles", "type": "array", "items": { "$ref": "ComputedStyle" } }
-                ],
-                "description": "For the main document and any content documents, return the LayoutTreeNodes and a whitelisted subset of the computed style. It only returns pushed nodes, on way to pull all nodes is to call DOM.getDocument with a depth of -1.",
-                "experimental": true
-            },
-            {
                 "name": "startRuleUsageTracking",
                 "description": "Enables the selector recording.",
                 "experimental": true
             },
             {
                 "name": "takeCoverageDelta",
                 "description": "Obtain list of rules that became used since last call to this method (or since start of coverage instrumentation)",
                 "returns": [
                     { "name": "coverage", "type": "array", "items": { "$ref": "RuleUsage" } }
                 ],
@@ skipping 34 matching lines @@
             {
                 "name": "styleSheetRemoved",
                 "parameters": [
                     { "name": "styleSheetId", "$ref": "StyleSheetId", "description": "Identifier of the removed stylesheet." }
                 ],
                 "description": "Fired whenever an active document stylesheet is removed."
             }
         ]
     },
     {
+        "domain": "DOMSnapshot",
+        "experimental": true,
+        "description": "This domain facilitates obtaining document snapshots with DOM, layout, and style information.",
+        "dependencies": ["CSS", "DOM", "Page"],
+        "types": [
+            {
+                "id": "DOMNode",
+                "type": "object",
+                "properties": [
+                    { "name": "nodeType", "type": "integer", "description": "<code>Node</code>'s nodeType." },
+                    { "name": "nodeName", "type": "string", "description": "<code>Node</code>'s nodeName." },
+                    { "name": "nodeValue", "type": "string", "description": "<code>Node</code>'s nodeValue." },
+                    { "name": "childNodeIndexes", "type": "array", "items": { "type": "integer" }, "optional": true, "description": "The indexes of the node's child nodes in the <code>domNodes</code> array returned by <code>getSnapshot</code>, if any." },

[pfeldman, 2017/06/06 22:54:29]

It is tempting to use backendNodeId here - it is stable Node id that is
associated with the node. Either use those in place of indexes or at least
include them for nodes. That would be your interop path into the DOM/CSS world.

[Eric Seckler, 2017/06/07 10:23:37]

Added as a field. We'd prefer to continue referencing nodes by their indexes
here though.

+                    { "name": "attributes", "type": "array", "items": { "$ref": "Attribute" }, "optional": true, "description": "Attributes of the <code>Element</code> node in the form of flat array <code>[name1, value1, name2, value2]</code>." },
+                    { "name": "documentURL", "type": "string", "optional": true, "description": "Document URL that <code>Document</code> or <code>FrameOwner</code> node points to." },

[pfeldman, 2017/06/06 22:54:29]

Everything rare that is not essential to any node and has named string value:
extract into array of auxProperties of type "Attribute" or better yet have it
renamed into "NameValue" and reuse for attributes and computed styles.

That would be baseURL, publicId, systemId.

[Eric Seckler, 2017/06/07 10:23:37]

Chatted to Alex about this, too. We'd like to keep the supported auxProperties
explicit + documented in the protocol. I moved everything that only exists for
particular node types into an additional AuxiliaryProperties type to clean this
up a little.

An alternative might be a list of key->string items, where key is of an enum
type (which we can use to document what keys are supported). Not sure if that
would make any practical difference though.

+                    { "name": "baseURL", "type": "string", "optional": true, "description": "Base URL that <code>Document</code> or <code>FrameOwner</code> node uses for URL completion." },
+                    { "name": "publicId", "type": "string", "optional": true, "description": "<code>DocumentType</code> node's publicId." },
+                    { "name": "systemId", "type": "string", "optional": true, "description": "<code>DocumentType</code> node's systemId." },
+                    { "name": "frameId", "$ref": "Page.FrameId", "optional": true, "description": "Frame ID for frame owner elements." },
+                    { "name": "contentDocumentIndex", "type": "integer", "optional": true, "description": "The index of a frame owner element's content document in the <code>domNodes</code> array returned by <code>getSnapshot</code>, if any." },
+                    { "name": "pseudoType", "$ref": "DOM.PseudoType", "optional": true, "description": "Type of a pseudo element node." },
+                    { "name": "pseudoElementIndexes", "type": "array", "items": { "type": "integer" }, "optional": true, "description": "Indexes of pseudo elements associated with this node in the <code>domNodes</code> array returned by <code>getSnapshot</code>, if any." },
+                    { "name": "importedDocumentIndex", "type": "integer", "optional": true, "description": "Index of the imported document's node of a link element in the <code>domNodes</code> array returned by <code>getSnapshot</code>, if any." },
+                    { "name": "templateContentIndex", "type": "integer", "optional": true, "description": "Index of the content node of a template element in the <code>domNodes</code> array returned by <code>getSnapshot</code>." },
+                    { "name": "isSVG", "type": "boolean", "optional": true, "description": "Whether the node is SVG." },

[pfeldman, 2017/06/06 22:54:29]

Let's save at least on this one:)

[Eric Seckler, 2017/06/07 10:23:37]

Got rid of it for now. If we need it later, we can add it back.

+                    { "name": "layoutNodeIndex", "type": "integer", "optional": true, "description": "The index of the node's related layout tree node in the <code>layoutTreeNodes</code> array returned by <code>getSnapshot</code>, if any." }
+                ],
+                "description": "A Node in the DOM tree."
+            },
+            {
+                "id": "LayoutTreeNode",
+                "type": "object",
+                "properties": [
+                    { "name": "domNodeIndex", "type": "integer", "description": "The index of the related DOM node in the <code>domNodes</code> array returned by <code>getSnapshot</code>." },
+                    { "name": "boundingBox", "$ref": "DOM.Rect", "description": "The absolute position bounding box." },
+                    { "name": "layoutText", "type": "string", "optional": true, "description": "Contents of the LayoutText, if any." },
+                    { "name": "inlineTextNodes", "type": "array", "optional": true, "items": { "$ref": "CSS.InlineTextBox" }, "description": "The post-layout inline text nodes, if any." },
+                    { "name": "styleIndex", "type": "integer", "optional": true, "description": "Index into the <code>computedStyles</code> array returned by <code>getSnapshot</code>." }
+                ],
+                "description": "Details of an element in the DOM tree with a LayoutObject."
+            },
+            {
+                "id": "ComputedStyle",
+                "type": "object",
+                "properties": [
+                    { "name": "properties", "type": "array", "items": { "$ref": "CSS.CSSComputedStyleProperty" } }

[pfeldman, 2017/06/06 22:54:29]

Rename and reuse your "Attribute" to make your domain almost self-contained?

[Eric Seckler, 2017/06/07 10:23:37]

Done.

+                ],
+                "description": "A subset of the full ComputedStyle as defined by the request whitelist."
+            },
+            {
+                "id": "Attribute",
+                "type": "object",
+                "properties": [
+                    { "name": "name", "type": "string", "description": "Node attribute name." },
+                    { "name": "value", "type": "string", "description": "Node attribute value." }
+                ],
+                "description": "A node attribute."
+            }
+        ],
+        "commands": [
+            {
+                "name": "getSnapshot",
+                "parameters": [
+                    { "name": "computedStyleWhitelist", "type": "array", "items": { "type": "string" }, "description": "Whitelist of computed styles to return." },
+                    { "name": "depth", "type": "integer", "optional": true, "description": "The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree or provide an integer larger than 0." },

[pfeldman, 2017/06/06 22:54:29]

Drop depth and pierce, always imply -1, true?

[Eric Seckler, 2017/06/07 10:23:37]

Done.

+                    { "name": "pierce", "type": "boolean", "optional": true, "description": "Whether or not iframes, template contents, and imported documents should be traversed when returning the subtree (default is false)." }
+                ],
+                "returns": [
+                    { "name": "domNodes", "type": "array", "items": { "$ref": "DOMNode" }, "description": "The nodes in the DOM tree. The DOMNode at index 0 corresponds to the root document." },
+                    { "name": "layoutTreeNodes", "type": "array", "items": { "$ref": "LayoutTreeNode" }, "description": "The nodes in the layout tree." },
+                    { "name": "computedStyles", "type": "array", "items": { "$ref": "ComputedStyle" }, "description": "Whitelisted ComputedStyle properties for each node in the layout tree." }
+                ],
+                "description": "Returns a document snapshot, including the DOM tree of the root node up to the given depth in a flattened array, as well as layout and white-listed computed style information for the nodes. Shadow DOM in the returned DOM tree is flattened."
+            }
+        ]
+    },
+    {
         "domain": "IO",
         "description": "Input/Output operations for streams produced by DevTools.",
         "experimental": true,
         "types": [
             {
                 "id": "StreamHandle",
                 "type": "string"
             }
         ],
         "commands": [
@@ skipping 1390 matching lines @@
                 "parameters": [
                     { "name": "windowId", "$ref": "WindowID", "description": "Browser window id." }
                 ],
                 "returns": [
                     { "name": "bounds", "$ref": "Bounds", "description": "Bounds information of the window. When window state is 'minimized', the restored window position and size are returned." }
                 ]
             }
         ]
     }]
 }