Specs: define registerElement() a little differently, so that the code

sky/specs/apis.md

 APIs
 ====
 
 The Sky core API
 ----------------
 
 ```javascript
 module 'sky:core' {
 
   // EVENTS
@@ skipping 241 matching lines @@
     constructor (Dictionary attributes); // shorthand
     constructor (); // shorthand
     constructor attribute String tagName; // O(1) // "error"
     constructor attribute Boolean shadow; // O(1) // false
   }
 
 
 
   // MODULES
 
+  callback InternalElementConstructor void (Module module);
   dictionary ElementRegistration {
     String tagName;
     Boolean shadow = false;
-    Object prototype = Element;
+    InternalElementConstructor? constructor = null;
   }
 
   interface ElementConstructor {
     constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
     constructor (ChildArguments... nodes); // shorthand
     constructor (Dictionary attributes); // shorthand
     constructor (); // shorthand
 
     constructor attribute String tagName;
     constructor attribute Boolean shadow;
   }
 
   abstract class AbstractModule : EventTarget {
     readonly attribute Document document; // O(1) // the Documentof the module or application
     Promise<any> import(String url); // O(Yikes) // returns the module's exports
 
     readonly attribute String url;
 
     ElementConstructor registerElement(ElementRegistration options); // O(1)
     // if you call registerElement() with an object that was created by
     // registerElement(), it just returns the object after registering it,
     // rather than creating a new constructor
     // otherwise, it proceeds as follows:
-    //  0. let prototype be the prototype passed in (defaulting to Element)
-    //  1. let constructor be prototype.constructor
-    //  2. create a new Function that:
-    //      0. throws if not called as a constructor
-    //      1. initialises the shadow tree is shadow on the options is true
-    //      2. calls constructor, if it's not null, with the module as the argument
-    //  3. let that new Function's prototype be the aforementioned prototype
-    //  4. let that new Function have tagName and shadow properties set to
-    //     the values passed in
-    //  5. register the new element
+    //  1. let constructor be the constructor passed in, if any
+    //  2. let prototype be the constructor's prototype; if there is no
+    //     constructor, let prototype be Element
+    //  3. create a new Function that:
+    //      1. throws if not called as a constructor
+    //      2. creates an actual Element object
+    //      3. initialises the shadow tree if shadow on the options is true
+    //      4. calls constructor, if it's not null, with the module as the argument
+    //  4. let that new Function's prototype be the aforementioned prototype
+    //  5. let that new Function have tagName and shadow properties set to
+    //     the values passed in on options
+    //  6. register the new element
 
     ScriptElement? currentScript; // O(1) // returns the <script> element currently being executed if any, and if it's in this module; else null
   }
 
   class Module : AbstractModule {
     constructor (Application application, Document document, String url); // O(1)
     readonly attribute Application application; // O(1)
 
     attribute any exports; // O(1) // defaults to the module's document
   }
 
   class Application : AbstractModule {
     constructor (Document document, String url); // O(1)
     attribute String title; // O(1)
   }
 
   // see script.md for a description of the global object, though note that
   // the sky core module doesn't use it or affect it in any way.
 
 }
 ```
 
-TODO(ianh): is it ok that you can do
-module.application.registerElement()? we need application so that a
-module can implement <title> and get to application.title...
-
 TODO(ianh): event loop
 
 TODO(ianh): define the DOM APIs listed above, including firing the
 change callbacks
 
 TODO(ianh): schedule microtask, schedule task, requestAnimationFrame,
 custom element callbacks...
 
 
 
@@ skipping 13 matching lines @@
 Sky IDL works more or less the same as Web IDL but the syntax is a bit
 different.
 
 ```javascript
 module 'sky:modulename' {
 
   // this is a comment
 
   typedef NewType OldType; // useful when OldType is a commonly-used union
 
+  callback CallbackName ReturnType (ArgumentType argumentName);
+
   class ClassName {
     // a class corresponds to a JavaScript prototype
     // corresponds to a WebIDL 'interface'
   }
 
   abstract class Superclass {
     // an abstract class can't have a constructor
     // in every other respect it is the same as a regular class
   }
 
@@ skipping 119 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.