Specs: Simplify the platform by only having one shadow tree per element.

sky/specs/apis.md

 APIs
 ====
 
 The Sky core API
 ----------------
 
 ```javascript
 module 'sky:core' {
 
   // EVENTS
@@ skipping 80 matching lines @@
     readonly attribute String tagName; // O(1)
 
     Boolean hasAttribute(String name); // O(N) in arguments
     String getAttribute(String name); // O(N) in arguments
     void setAttribute(String name, String value); // O(N) in arguments
     void removeAttribute(String name); // O(N) in arguments
     
     // Returns a new Array and new Attr instances every time.
     Array<Attr> getAttributes(); // O(N) in arguments
 
-    readonly attribute ShadowRoot? shadowRoot; // O(1) // returns the youngest shadow root
-    void addShadowRoot(ShadowRoot root); // O(N) in descendants of argument
+    readonly attribute ShadowRoot? shadowRoot; // O(1) // returns the shadow root
     Array<ContentElement> getDestinationInsertionPoints(); // O(N) in number of insertion points the node is in
 
     virtual void attributeChangeCallback(String name, String? oldValue, String? newValue); // noop
-    virtual void shadowRootChangeCallback(ShadowRoot root); // noop
     // TODO(ianh): does a node ever need to know when it's been redistributed?
   }
   Element createElement(String tagName, Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
   Element createElement(String tagName, Dictionary attributes); // shorthand
   Element createElement(String tagName, ChildArguments... nodes); // shorthand
   Element createElement(String tagName); // shorthand
 
-  Object registerElement(String tagName, Object interfaceObject); // O(N) in number of outstanding elements with that tag name to be upgraded
+  dictionary ElementRegistration {
+    String tagName;
+    Boolean shadow;
+    Object prototype;
+  }
+  Object registerElement(ElementRegistration options); // O(N) in number of outstanding elements with that tag name to be upgraded
 
   interface Text : Node {
     constructor (String value); // O(1)
     attribute String value; // O(1)
 
     void replaceWith(String node); // O(1) // special case override of Node.replaceWith()
 
     virtual void valueChangeCallback(String? oldValue, String? newValue); // noop
   }
 
   interface DocumentFragment : ParentNode {
     constructor (ChildArguments... nodes); // O(N) in number of arguments plus all their descendants
   }
 
   abstract interface TreeScope : ParentNode {
     readonly attribute Document? ownerDocument; // O(1)
     readonly attribute TreeScope? parentScope; // O(1)
 
     Element? findId(String id); // O(1)
   }
 
   interface ShadowRoot : TreeScope {
-    constructor (ChildArguments... nodes); // O(N) in number of arguments plus all their descendants
-    readonly attribute Element? host; // O(1)
-    readonly attribute ShadowRoot? olderShadowRoot; // O(1)
-    void removeShadowRoot(); // O(N) in descendants
+    constructor (Element host); // O(1) // note that there is no way in the API to use a newly created ShadowRoot
+    readonly attribute Element host; // O(1)
   }
 
   interface Document : TreeScope {
     constructor (ChildArguments... nodes); // O(N) in number of arguments plus all their descendants
   }
   
   interface SelectorQuery {
     constructor (String selector); // O(F()) where F() is the complexity of the selector
 
     Boolean matches(Element element); // O(F())
     Element? find(ParentNode root); // O(N*F()) where N is the number of descendants
     Array<Element> findAll(ParentNode root); // O(N*F()) where N is the number of descendants
   }
 
   // Built-in Elements
   interface ImportElement : Element { }
   interface TemplateElement : Element {
     readonly attribute DocumentFragment content; // O(1)
   }
   interface ScriptElement : Element { }
   interface StyleElement : Element { }
   interface ContentElement : Element {
     Array<Node> getDistributedNodes(); // O(N) in distributed nodes
   }
-  interface ShadowElement : Element {
-    Array<Node> getDistributedNodes(); // O(N) in distributed nodes
-  }
   interface ImgElement : Element { }
   interface IframeElement : Element { }
   interface TElement : Element { }
   interface AElement : Element { }
   interface TitleElement : Element { }
 
 
 
   // MODULES
   abstract interface AbstractModule : EventTarget {
@@ skipping 82 matching lines @@
     // private APIs - see below
     private void method();
 
     // arguments and overloading are done as follows
     // note that the argument names are only for documentation purposes
     ReturnType method(ArgumentType argumentName1, ArgumentType argumentName2);
     // the last argument's type can have "..." appended to it to indicate a varargs-like situation
     ReturnType method(ArgumentType argumentName1, ArgumentType... allSubsequentArguments);
   }
 
+  dictionary Options {
+    String foo;
+    Integer bar;
+  }
+
   // the module can have properties and methods also
   attribute String Foo;
   void method();
 
 }
 ```
 
 ### Private APIs ###
 
 Private APIs are only accessible via Symbol objects, which are then
@@ skipping 22 matching lines @@
 ### Types ###
 
 The following types are available:
 
 * ``Integer`` - WebIDL ``long long``
 * ``Float`` - WebIDL ``double``
 * ``String`` - WebIDL ``USVString``
 * ``Boolean`` - WebIDL ``boolean``
 # ``Object`` - WebIDL ``object``
 * ``InterfaceName`` - an instance of the interface InterfaceName
+* ``DictionaryName`` - an instance of the dictionary DictionaryName
 * ``Promise<Type>`` - WebIDL ``Promise<T>``
 * ``Array<Type>`` - WebIDL ``sequence<T>``
 * ``Dictionary`` - unordered set of name-value String-String pairs with no duplicate names
 * ``Type?`` - union of Type and the singleton type with value "null" (WebIDL nullable)
 * ``(Type1 or Type2)`` - union of Type1 and Type2 (WebIDL union)
 * ``any`` - union of all types (WebIDL ``any``)
 
 Methods that return nothing (undefined, in JS) use the keyword "void"
 instead of a type.
 
@@ skipping 23 matching lines @@
   the core mojo fabric JS API   sky:mojo:fabric:core
   the asyncWait/cancelWait mojo fabric JS API (interface to IPC thread)  sky:mojo:fabric:ipc
   the mojom for the shell, proxying through C++ so that the shell pipe isn't exposed  sky:mojo:shell
   the sky API  sky:core
   the sky debug symbols for private APIs  sky:debug
 ```
 
 TODO(ianh): determine if we want to separate the "this" from the
 Document, especially for Modules, so that exposing a module's element
 doesn't expose the module's exports attribute.