A ShadowTree is an extra thing that is attached to a DOM element. The ShadowTree is the stack of ShadowRoot elements; it has a list of ShadowRoots, a HTMLContentSelector. Issue 1: HTMLContentSelector has a doubly linked list of RefPtr references to nodes--this needs to be fixed. Each ShadowRoot is a document fragment because it is behaviorally similar to a document fragment. When you operate on it in DOM, you aren’t able to copy it. If you try to appendChild(shadowRoot), appendChild will steal its children but not disconnect the ShadowRoot from his host, etc. apply-author-sheets: This controls whether stylesheets from the document apply to elements in the shadow. When you look at the element and see how it operates on the shadow tree, it passes pretty much all of the style recalc things to it if you look at attach, and the shadow tree passes that on to the ShadowRoots in the stack. Terminology--oldest and youngest ShadowRoots. Younger shadow roots are ones that were created later; they are towards the top of the stack. User-agent shadows are always the oldest, bottom-of-the-stack shadows. There are two special nodes, HTMLContentElement and HTMLShadowElement, which are subtypes of InsertionPoint. These are special in Shadow DOM--see the spec--a thing that doesn't render but stuff goes into it. The InsertionPoint has a list of nodes that are distributed to the insertion point. The InsertionPoint takes the children of the host and, using the a CSS selector, lays claim to light children of a node to populate this list. (??? The CSS selector for is actually a member of InsertionPoint. This is to simulate user-agent shadows for all elements. ???) HTMLShadowElement is an InsertionPoint that is a reference to an older tree in the stack. There are pointers from the ShadowRoot to the HTMLShadowElement that includes it. We need these back pointers to walk nodes in the flattened tree -- we never explicitly construct the flattened tree, just leave enough breadcrumbs in the tree to construct it implicitly. There's a thing called NodeRenderingContext which knows how to find the renderer that is the renderer of the node that is effectively the parent of a node in a flattened tree. For example, and are "erased" by the flattened tree, so if your nextSibling in the DOM is a , NodeRenderingContext knows to recurse into what nodes it has selected. Since flattened tree construction is implicit, this is effected in how the renderers are wired up. Hence NodeRenderingContext::parentNodeForRenderingAndStyle. Issues: NodeRenderingContext is a beast with phases, etc. etc. We like having all of this indirection logic in one class, just the class needs to be simplified. Issues: Distribution should be separated from attachment. With Shadow DOM suddenly you have an added level of complexity on node attachment and detachment, computing styles, etc. Q? How do we calculate the insertion point for a node? In InsertionPoint::attach, ShadowTree starts with the youngest ShadowRoot and distributes light children into its insertion points and the next oldest ShadowRoot into its insertion point (if any.) If the next oldest ShadowRoot was distributed into this ShadowRoot, assignment iterates and and does assignment (and attach) in the next oldest ShadowRoot on the stack. HTMLContentSelector has the logic to populate itself with light children if they match a CSS selector. First it collects all of the host children to distribute later. Then each is traversed and candidates are drawn from the set. HTMLContentSelector has a "phase" which is to prevent reentrancy. If a ShadowTree subtree is reattached, you don’t want to tickle the distribution in reattach. tree->selector().isSelecting(). HTMLContentSelector is basically the table mapping insertion point to the nodes distributed to it. Bug: Rename ShadowTree to ShadowRootStack. Bug: Switch from HTMLContentSelector phase to a flag as the reentrancy guard. (TODO: UML diagram) Bug: Remove the HTMLContent* (eg SelectionList, etc.) naming convention, because HTMLX is for HTML element X, and we already have HTMLContentElement. So let’s call it Content*. Bug: Rename HTMLContentSelection to something. "Selection" is bad because it is like click-and-drag selection. Bug: Can HTMLContentSelection be just a list of nodes in the insertion point, and get rid of HTMLContentSelection? We need the table to find the rendering parent of the distributed node. Could consider a design where a ShadowRoot has a bit whether it has been included with or not, but not a pointer to the specific element itself, and have each ShadowRoot point to its first docorder . ComposedShadowTreeWalker -- this class gives you a facility to walk the DOM as it is viewed as a result of the composition of this tree, kind of as the user sitting in front of the browser sees it: firstChild, lastChild, nextSibling, next (in tree order) etc. If you want to access the tree "as it all looks as it is composed", use ComposedTreeWalker. This is useful for event dispatch and things like that. For example FocusController uses this because it needs to walk the composed tree. TreeScope -- Document is a tree scope, but you can have subtrees that are in separate tree scopes. It is a tree overlaid on the document tree. Shadow DOM subtrees are in their own TreeScope and it is used to control how style (CSSStyleSelector ... treeScope->applyAuthorSheets()) is applied in Shadow DOM. Replaced Elements and Shadow DOM -------------------------------- Suppose you have an element or a