Specs: define how importing element registrations works, move built-in elements to a separate modul…

sky/specs/modules.md

 Sky Module System
 =================
 
 This document describes the Sky module system.
 
 Overview
 --------
 
 The Sky module system is based on the ``import`` element. In its
 most basic form, you import a module as follows:
@@ skipping 13 matching lines @@
 module waits until its list of outstanding dependencies is empty
 before marking itself complete.
 
 The ``as`` attribute on the ``import`` element binds a name to the
 imported module:
 
 ```html
 <import src="path/to/chocolate.sky" as="chocolate" />
 ```
 
+Each module implicitly imports the [Built-In Elements
+Module](builtins.md).
+
+When a module imports another, and the ``import`` element has no
+``as`` attribute, then any elements registered in that module whose
+tag names do not begin with an underscore must be registered on the
+importing module. (If multiple elements are registered with the same
+name, that name gets marked as dead for that module and all the
+registrations for that name are discarded.)
+
+TODO(ianh): decide if elements imported with "as" should be imported
+but with the "as" name prefixed, as in ``<foo.button>``
+
 
 Module API
 ----------
 
 Each module consists of one or more libraries. The first library in a
-module is the *element tree library*, which imports the dart:sky
-module and then consists of the following code for a Sky module:
+module is the *element tree library*, which consists of the following
+code for a Sky module:
 
 ```dart
+import 'dart:sky';
 final Module module = new Module();
 ```
 
 ...and the following code for a Sky application:
 
 ```dart
+import 'dart:sky';
 final Module module = new Application();
 ```
 
 The ``<script>`` elements found in the module's element tree create
 the subsequent libraries. Each one first imports the ``dart:mirror``
 library, then the ``dart:sky`` module, then the first library
 described above, then all the modules referenced by ``<import>``
 element up to that ``<script>`` element and all the libraries defined
 by ``<script>`` elements up to that point, interleaved so as to
 maintain the same relative order as those elements were first seen by
@@ skipping 65 matching lines @@
 }
 
 class Application extends AbstractModule {
   Application({String url, Root elements, this.gestureManager}) :
     super(url: url, elements: elements); // O(1)
   external String get title; // O(1)
   external void set title(String newValue); // O(1)
   final GestureManager gestureManager;
 }
 ```